beagle.doc

地球模拟器

====== BEAGLE DOCUMENTATION =================================================

How to use Beagle:

     Beagle runs only on DOS based computers with VGA or CGA graphics cards.
Beagle will search for the cga.bgi or egavga.bgi files that come with the
Borland compilers.  If you don't have these, you need to get them, they
have been placed in the directory with the executable and this file.
Beagle reads the files that are written to disk by the Tierra simulator,
and displays them graphically.  Beagle reads the break.1 ... break.X files
that are written to the /td directory, and it also reads the 00XX.gen files
that are written to the /gb directory.

====== BEAGLE ===============================================================

     Start Beagle by typing beagle to the DOS prompt:

C> beagle

     From the top level menu, use cursor keys to select an option, then
use the Enter key to activate that option.

====== PREPARE - RUN INFO ===================================================

     You must process the break.X files with the "Prepare - Run Info"
option from the Beagle menu, or the stand-alone run_info utility, which
produces output files called run_info and run_info.g which are used by Beagle:

   select the Prepare option
   then select the Run Info option

     Selecting the "Prepare - Run Info" option will produce a window that
looks like this:

+tierun------------------------------------+
| directory  = c:\tierra\td                |
| input file = break.1                     |
| update frequency   = 100                 |
+------------------------------------------+

     Within this window, use the cursor key to move to an option, then type
in your choice.  When you have all the options as you want them, use Ctrl-Enter
to activate the "Prepare - Run Info" process.  Use the Escape key to exit from
the window.

     An explanation of these "Prepare - Run Info" options follows:

 directory  = c:\tierra\td

     This is the path to the file containing the birth and death records
output by the Tierra program (the break.X files).

 input file = break.1

     This is the name of the file containing the birth and death records
output by the Tierra program.  In long runs, a series of these files may be
produced, with the names break.1, break.2, break.3, ..., break.X.  The
Prepare - Run Info program will read each of them in turn, if you specify
the name of the first one.

 update frequency   = 100

     The "Prepare - Run Info" will preview the entire record of births and
deaths in order to rank all the size and genotype classes by their relative
abundances.  If the "update frequency" option is non-zero, there will be two
rankings.  One ranking will be for the entire run.  Another ranking will occur
repeatedly throughout the run, at the frequency indicated by this option
(measured in millions of instructions, the default is to rank the classes
every 100 million instruction).  I suggest you leave the update frequency
at 100.

     Start the "Prepare - Run Info" option running by hitting Ctrl-Enter.
When the program finishes, go back to the main menu by hitting the Escape key.
When the "Prepare - Run Info" option is finished, you can go ahead and use
the Bar and Trace displays.  To use the Bar and Trace displays in the future,
you do not have to repeat the Prepare process (you Prepare once for each
output file).

     The "Prepare - Run Info" option uses a lot of memory.  On long runs,
it may run out of memory.  If this happens, you should use the stand-alone
run_info tool.  It takes the same input parameters, but by not being bundled
with the rest of the Beagle tools, it has a lot more memory to spare.  Just
type run_info to the DOS prompt.

====== BARS ================================================================

     The Bars option will display a running frequency distribution of up
to 55 size or genotype classes simultaneously, in the form of a moving bar
graph.

     Selecting the Bars option generates a window that looks like this:

+bars----------------------------+
| directory  = c:\tierra\td      |
| input file = break.1           |
| x-axis (pop,inst)  = inst      |
| separate genotypes = Y         |
| update display     = Y         |
| view run_info      = N         |
| num bars (24,55)   = 24        |  * this line appears only with VGA display
+--------------------------------+

     Within this window, use the cursor key to move to an option, then type
in your choice.  When you have all the options as you want them, use Ctrl-Enter
to activate the Bars display.  Use the Escape key to exit from the Bars option.

     While the display is running, hitting the "p" key will cause the display
to pause.  Hitting any key while the display is paused will cause the display
to resume.  Hitting the Escape key while the display is running will cause the
display to stop, hitting the Escape key a second time will terminate the
display and return to the option window.  If the "g" key is hit while the
display is running, or when it has terminated but is still displayed, the
image on the screen will be saved to a .gif file.  When the display is
complete, the machine will beep; hitting the Escape key will return to the
option window.

     An explanation of the Bars options follows:

 directory  = c:\tierra\td

     This is the path to the file containing the birth and death records
output by the Tierra program (the break.X files).

 input file = break.1

     This is the name of the file containing the birth and death records
output by the Tierra program.  In long runs, a series of these files may be
produced, with the names break.1, break.2, break.3, ..., break.X.  The
Bars program will read each of them in turn, if you specify the name of the
first one.

 x-axis (pop,inst)  = inst

     This item gives you two options for how the horizontal scale is defined.
"pop" means that the horizontal scale specifies the population of each class
of creature.  "inst" means that the horizontal scale specifies how much memory
(measured in instructions) is occupied by each class of creature.

 separate genotypes = Y

     This options allows you to decide if the bars will represent unique
genotypes (Y) or only distinct size classes (N).

 update display     = Y

     The "Prepare - Run Info" option ranked all the size and genotype classes
by their relative abundances, through the whole run, and for every period
indicated by the update frequency.  The Bar option will display up to 55 bars
(see the "num bars" option below).  The bars displayed will be only the most
abundant size or genotype classes.  If the "update display" option is selected
(Y), the list of bars will be updated at the frequency selected during the
"Prepare - Run Info" process.  If the "update display" option is not
selected (N), the list will not be updated throughout the run.

 view run_info      = N

     If the option is selected (Y), a window will appear that displays a
summary of the information contained in the relevant run_info file.  The
contents and format of the display will depend on the other options chosen
in this window (try it and see).
     
 num bars (24,55)   = 24

     This option will only appear if you have a VGA display.  On a CGA display,
it is only possible to display up to 24 bars.  However, on a VGA, it is
possible to display up to 55 bars.  You may specify any number of bars you
choose, up to the limit of your display.  On a VGA, if you choose up to 24
bars, they will be wide and have large labels.  If you choose from 25 to 55
bars, they will be narrow and have small labels.

====== TRACE ===============================================================

     This option will produce a phase diagram, illustrating the relative
abundances of two size or genotype classes over time, as an x,y plot.

     Selecting the Trace option generates a window that looks like this:

+trace---------------------------+
| directory  = c:\tierra\td      |
| input file = break.1           |
| x size     = 80aaa             |
| y size     = 45aaa             |
| axis (pop,inst)    = pop       |
| shrink factor      = 1         |
| separate genotypes = Y         |
+--------------------------------+

     Within this window, use the cursor key to move to an option, then type
in your choice.  When you have all the options as you want them, use Ctrl-Enter
to activate the Trace display.  Use the Escape key to exit from the Trace
option.

     While the display is running, hitting the "p" key will cause the display
to pause.  Hitting any key while the display is paused will cause the display
to resume.  Hitting the Escape key while the display is running will cause the
display to stop, hitting the Escape key a second time will terminate the
display and return to the option window.  If the "g" key is hit while the
display is running, or when it has terminated but is still displayed, the
image on the screen will be saved to a .gif file.  When the display is
complete, the machine will beep; hitting the Escape key will return to the
option window.

     An explanation of the Trace options follows:

 directory  = c:\tierra\td

     This is the path to the file containing the birth and death records
output by the Tierra program (the break.X files).

 input file = break.1

     This is the name of the file containing the birth and death records
output by the Tierra program.  In long runs, a series of these files may be
produced, with the names break.1, break.2, break.3, ..., break.X.  The
Trace program will read each of them in turn, if you specify the name of the
first one.

 x size     = 80aaa

     The size or genotype class to be plotted on the x axis.

 y size     = 45aaa

     The size or genotype class to be plotted on the y axis.

 axis (pop,inst)    = pop

     This item gives you two options for how the horizontal axes are defined.
"pop" means that the axes specify the population of each class of creature.
"inst" means that the axes specify how much memory (measured in instructions)
is occupied by each class of creature.

 shrink factor      = 1

     The axes will normally fill the whole screen, but if you use a shrink
factor of less than 1, the y axis will shrink to fill only part of the screen.
This option was introduced to get the display to fit a device that was
cropping the vertical dimension (when making a video tape).

 separate genotypes = Y

     This options allows you to decide if the axes will represent unique
genotypes (Y) or only distinct size classes (N).

====== DIVERSITY ===========================================================

     This option provides a graphical display of the output from the
DIVERSE.EXE program (see the diverse.doc file).  The DIVERSE.EXE program
generates files containing indices of diversity and turnover throughout a
run.  The Diversity option displays these indices.  You must run the
DIVERSE.EXE program before you can use the Diversity option.

     Selecting the Diversity option generates a window that looks like this:

+diversity---------------------------+
| directory  = c:\tierra\td          |
| x var      = Time                  |
| y var      = GenoDiv               |
| data file  = divdat.1              |
| range file = divrange              |
| shrink factor = 1                  |
+------------------------------------+

     Within this window, use the cursor key to move to an option, then type
in your choice.  When you have all the options as you want them, use Ctrl-Enter
to activate the Diversity display.  Use the Escape key to exit from the
Diversity option.

     While the display is running, hitting the "p" key will cause the display
to pause.  Hitting any key while the display is paused will cause the display
to resume.  Hitting the Escape key while the display is running will cause the
display to stop, hitting the Escape key a second time will terminate the
display and return to the option window.  If the "g" key is hit while the
display is running, or when it has terminated but is still displayed, the
image on the screen will be saved to a .gif file.  When the display is
complete, the machine will beep; hitting the Escape key will return to the
option window.

     An explanation of the Diversity options follows:

 directory  = c:\tierra\td

     This is the path to the file containing the diversity indices, output
by the diverse.exe program (the divdat.X and divrange files).

 x var      = Time
 y var      = GenoDiv

     These options allow you to choose which two, of the eight indices
output by the Diverse program, you wish to display in your graphical x,y
display.  When you move to these lines in the window, a menu of options will
pop up:

               +---------+------------------------------+
               | Time    | elapsed time in instructions |
               | NumCell | number of cells              |
               | NumSize | number of sizes              |
               | SizeDiv | size diversity               |
               | AgeSize | average age of sizes         |
               | NumGeno | number of genotypes          |
               | GenoDiv | genotype diversity           |
               | AgeGeno | average age of genotypes     |
               +---------+------------------------------+

     To select a parameter, cursor to that line and hit Enter.  Below, a
more technical explanation of some of these parameters is provided:

            NumCell | number of cells: total number of adult cells living
                      in the soup.
            NumSize | number of sizes: total number of distinct size classes
                      of adult cells living in the soup.