====== 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 theBorland compilers.  If you don't have these, you need to get them, theyhave 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 filesthat are written to the /td directory, and it also reads the 00XX.gen filesthat 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, thenuse 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, whichproduces 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 thatlooks 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 typein your choice.  When you have all the options as you want them, use Ctrl-Enterto activate the "Prepare - Run Info" process.  Use the Escape key to exit fromthe 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 recordsoutput by the Tierra program (the break.X files). input file = break.1     This is the name of the file containing the birth and death recordsoutput by the Tierra program.  In long runs, a series of these files may beproduced, with the names break.1, break.2, break.3, ..., break.X.  ThePrepare - Run Info program will read each of them in turn, if you specifythe name of the first one. update frequency   = 100     The "Prepare - Run Info" will preview the entire record of births anddeaths in order to rank all the size and genotype classes by their relativeabundances.  If the "update frequency" option is non-zero, there will be tworankings.  One ranking will be for the entire run.  Another ranking will occurrepeatedly throughout the run, at the frequency indicated by this option(measured in millions of instructions, the default is to rank the classesevery 100 million instruction).  I suggest you leave the update frequencyat 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 usethe 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 eachoutput 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-alonerun_info tool.  It takes the same input parameters, but by not being bundledwith the rest of the Beagle tools, it has a lot more memory to spare.  Justtype run_info to the DOS prompt.====== BARS ================================================================     The Bars option will display a running frequency distribution of upto 55 size or genotype classes simultaneously, in the form of a moving bargraph.     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 typein your choice.  When you have all the options as you want them, use Ctrl-Enterto 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 displayto pause.  Hitting any key while the display is paused will cause the displayto resume.  Hitting the Escape key while the display is running will cause thedisplay to stop, hitting the Escape key a second time will terminate thedisplay and return to the option window.  If the "g" key is hit while thedisplay is running, or when it has terminated but is still displayed, theimage on the screen will be saved to a .gif file.  When the display iscomplete, the machine will beep; hitting the Escape key will return to theoption window.     An explanation of the Bars options follows: directory  = c:\tierra\td     This is the path to the file containing the birth and death recordsoutput by the Tierra program (the break.X files). input file = break.1     This is the name of the file containing the birth and death recordsoutput by the Tierra program.  In long runs, a series of these files may beproduced, with the names break.1, break.2, break.3, ..., break.X.  TheBars program will read each of them in turn, if you specify the name of thefirst 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 classof 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 uniquegenotypes (Y) or only distinct size classes (N). update display     = Y     The "Prepare - Run Info" option ranked all the size and genotype classesby their relative abundances, through the whole run, and for every periodindicated 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 mostabundant 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 notselected (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 asummary of the information contained in the relevant run_info file.  Thecontents and format of the display will depend on the other options chosenin 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 ispossible to display up to 55 bars.  You may specify any number of bars youchoose, up to the limit of your display.  On a VGA, if you choose up to 24bars, they will be wide and have large labels.  If you choose from 25 to 55bars, they will be narrow and have small labels.====== TRACE ===============================================================     This option will produce a phase diagram, illustrating the relativeabundances 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 typein your choice.  When you have all the options as you want them, use Ctrl-Enterto activate the Trace display.  Use the Escape key to exit from the Traceoption.     While the display is running, hitting the "p" key will cause the displayto pause.  Hitting any key while the display is paused will cause the displayto resume.  Hitting the Escape key while the display is running will cause thedisplay to stop, hitting the Escape key a second time will terminate thedisplay and return to the option window.  If the "g" key is hit while thedisplay is running, or when it has terminated but is still displayed, theimage on the screen will be saved to a .gif file.  When the display iscomplete, the machine will beep; hitting the Escape key will return to theoption window.     An explanation of the Trace options follows: directory  = c:\tierra\td     This is the path to the file containing the birth and death recordsoutput by the Tierra program (the break.X files). input file = break.1     This is the name of the file containing the birth and death recordsoutput by the Tierra program.  In long runs, a series of these files may beproduced, with the names break.1, break.2, break.3, ..., break.X.  TheTrace program will read each of them in turn, if you specify the name of thefirst 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 shrinkfactor 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 wascropping the vertical dimension (when making a video tape). separate genotypes = Y     This options allows you to decide if the axes will represent uniquegenotypes (Y) or only distinct size classes (N).====== DIVERSITY ===========================================================     This option provides a graphical display of the output from theDIVERSE.EXE program (see the diverse.doc file).  The DIVERSE.EXE programgenerates files containing indices of diversity and turnover throughout arun.  The Diversity option displays these indices.  You must run theDIVERSE.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 typein your choice.  When you have all the options as you want them, use Ctrl-Enterto activate the Diversity display.  Use the Escape key to exit from theDiversity option.     While the display is running, hitting the "p" key will cause the displayto pause.  Hitting any key while the display is paused will cause the displayto resume.  Hitting the Escape key while the display is running will cause thedisplay to stop, hitting the Escape key a second time will terminate thedisplay and return to the option window.  If the "g" key is hit while thedisplay is running, or when it has terminated but is still displayed, theimage on the screen will be saved to a .gif file.  When the display iscomplete, the machine will beep; hitting the Escape key will return to theoption window.     An explanation of the Diversity options follows: directory  = c:\tierra\td     This is the path to the file containing the diversity indices, outputby 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 indicesoutput by the Diverse program, you wish to display in your graphical x,ydisplay.  When you move to these lines in the window, a menu of options willpop 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, amore 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.