Info file: brew.info,    -*-Text-*-
produced by `texinfo-format-buffer'
from file `brew.texi'
using `texinfmt.el' version 2.38 of 3 July 1998.





File: brew.info, Node: Top, Next: License, Prev: (dir), Up: (dir)

Brew `The Evolutionary Programmers Playground'  Version 0.2
***********************************************************

Brew is an environment for `Evolutionary Programming'.
It's an experiment raising an `Artificial Code Evolution'.

I wrote brew out of curiosity and for fun, enjoy....
Brew is homebrew by  Robert Epprecht <epprecht@solnet.ch>.


This brew version runs best on *Linux text console*.
Please *do* use that, if you can.

Running brew outside Linux text console is not really supported,
though brew might run on it, if you're lucky.


* Menu:

* License::                     The GNU General Public License
* Goals::                       What it's all about
* Introduction::                Overview and getting started.
* Users manual::                Brew user manual.
* Programmers manual::          partly written....

 -- The Detailed Node Listing ---

Introduction

* Evolutionary programming::    What do I mean by 'evolutionary programming'?
* Biological analogy::          Is this artificial life?
* Feature overview::            A quick overview over some brew features.
* Getting started::             Where to get Forth and how to start brew.
* Run evolution::               Brew the gene soup...
* Why Forth?::                  Why do I use Forth?

What do I mean by 'evolutionary programming'?

* Simple hypothetical example::  How it could be used.
* Changing code::               How the code get's changed.

Changing code

* Variable diversification::    Optimising numeric values.
* Code mutation::               Building new code to try it out.

Biological analogy.

* Artificial life::             Does brew evolve a form of virtual life?
* Biological terms::            Some biological terms used in brew context.

Getting started

* Gforth::                      GNU Forth by Anton Ertl, Bernd Paysan e.a.
* pfe::                         Portable Forth Environment. Guido Draheim.
* bigForth::                    Forth system written by Bernd Paysan.
* iForth::                      Commercial, fast Forth by Marcel Hendrix.

Why FORTH

* Note to Forth programmers::   

Brew user manual

* Some brew basics::            Some basics you should understand.
* Using menus::                 Basics of the brew user interface.
* Context documentation::       Reading context documentation.

Brews main display:

* Brew main screen::            Brew can have some very different looks.
* Display menu::                Configuring display.
* Color menu::                  Coding information into colors.
* Menus menu::                  Browse all globally accessible brew menus.

Individuals, nuclei and spots:

* Individuals menu::            Selecting predefined individuals.
* Nuc menu::                    Editing nucs.
* Edit spot menu::              Editing a single spot.
* Menu global variables::       Global variables visible to the genomes.

Controlling population:

* Food menu::                   Food supply controls population.
* Population control::          Mean automatic stress producer.

Diversification and mutation:

* Diversification menu::        Changing variable values.
* Mutation menu::               Configuring mutation.
* Gene pools menu::             Selecting a gene pool.
* Actual pool menu::            Probabilities of currently used genes.
* Stack type symbols::          Brews rudimentary stack type checking.
* Gene primitives::             Building blocks for genomes.
* Gene edit menu::              Editing genomes by hand.

Displaying statistics about cells and spots:

* Scanning nucs::               Display nuc statistics.
* Scanning spots::              Display spot statistics.

Advanced operation:

* Configurable actions::        Do something on nuc or spot subsets.
* Menu current genomes::        Examining all genomes of all living cells.
* Menu select nucs::            Set a multi purpose `selected' flag.

World wide settings and creation of new worlds:

* World menu::                  World wide settings and interfaces.
* World list menu::             Multiple worlds to choose from.
* Big Bang menu::               Creating new multidimensional worlds.
* System menu::                 Brews system wide settings.

Logging and writing the generated program code to files:

* Log files menu::              Detailed switching what to log.
* Code file menu::              Write produced program code to a file.

Recording evolutionary sessions:

* Record and Playback::         Recording evolutionary sessions.

Compile time configuration:

* Compile time options::        Start a customised brew.

Miscellaneous:

* Menu function keys::          Configuring function keys.
* Menu Demos::                  Some demos.
* Experiments::                 Advanced users demos.

Some brew basics

* Genes::                       What they can do and what they can't.
* Diversification/Mutation::    Two classes of changes.
* Trial phase::                 Trying out new code first.
* Classes of variables::        Cell variables and world variables.
* Run modes::                   Brew can run in different modes.
* Display modes::               Brew can show you different informations.

Classes of variables

* Variable names::              Variable naming scheme.

Display modes

* Example world mode display::  Petri shell look.
* Example step display::        Real time statistics.

Using menus

* Menu example::                How a menu might look.
* Moving and selecting::        How to select menu items.
* Key bindings::                Key bindings and how to find them out.
* Colours in menus::            
* Numeric input::               Hidden capabilities when entering numbers.
* Float input::                 Everyday float syntax on input.
* Scale input::                 Input of fractions.
* Selecting functions::         Selecting functions from a list.
* Scrolling menus::             When menus do not fit on a screen.
* Using Forth in menus::        Using the whole power of Forth in menus.

Menu example

* Example key bindings::        What you see by pressing `k'.
* Configuring F5::              Example configuring F5.

Brew main screen

* World map interaction::       Things you can do in world mode.       
* Cloning nucs to a spot::      How you can clone nucs.
* Step display interaction::    Interaction in statistical (step) display.

Display menu

* Time::                        Brews concept of time.
* Configuring spot display::    Configuring display of world map.
* Step display menu::           Configuring display of statistics.
* Info line::                   Configuring last line.

Configuring spot display

* Show me functions::           

Step display menu

* ASCII graphs::                So called `continuous display'.
* ASCII bar graphics::          Displaying distribution of values.
* Text display::                Minimum, maximum and average as numbers.

The different kinds of statistical data representations can be combined
at the same time each one in his own screen area.

* Menu step display::           Configuring step display screen.
* Menu continuous display::     Continuous display sub menu.
* Step display presets::        Often used display configurations.

Color menu

* Conditional colouring::       User defined colour conditions.       

Population control

* Eat and consume::             Get paid by results, pay taxes, consume energy.
* Elitism::                     Only the best individuals will survive.
* Menu elite::                  Current score list of the individuals.

Diversification menu

* NUC diversification::         Diversification of NUC local variables.
* SPOT diversification::        Diversification of SPOT local variables.
* GLOBAL diversification::      Diversification of GLOBAL variables.

Mutation menu

* Probability lists::           Pools of functions with different probabilities
* Mutation types menu::         Different types and sub-types of mutation

Gene primitives

* Integer arithmetics genes::   Basic arithmetics.
* Stack juggling genes::        Arranging items on the Forth stack.
* Genes reading from memory::   Fetching a value from an address.
* Genes writing to memory::     Writing a value to an address.
* Dealing with overflow::       Genes respecting upper limits for values.
* Nuc and spot variables::      Genes for read/write and read/only variables.
* Global variables::            Read only access to some global variables.
* Insight genes::               Genes giving the cell access to its innards.

Floating point primitives:

* Float arithmetic genes::      Basic float maths.     
* More float arithmetics::      Fnegate, fabs, fmax, fmin, f2*, f2/, 1/f
* Logarithms and exponentials::  Logarithms, exponentials, roots.    
* Trigonometry::                Trigonometric functions gene primitives.
* Mixed maths::                 Mixed integer/float operators.
* Type casts::                  Casts between integer and floating point.
* Read float values::           Fetching floats from memory.
* Store float values::          Store floating point values to memory.
* Float stack manipulation::    Arranging items on the float stack.
* Nuc and spot floats::         Float variables local to a nuc or spot.

Conditional structures:

* Gene conditionals::           Conditionally executing gene code sequences.
* Floating point comparison::   Conditions based on floating point values.

Whole tested genomes can be used like new primitives:

* Genome pool::                 Successful genomes as new genes.

Do something on nuc or spot subsets.

* Simple nuc conditions::       Defining simple nuc subsets.
* Simple spot conditions::      Defining simple spot subsets.

Extended conditions requiring parameters and a comparison:
* Extended conditions::         Spot or nuc subsets based on comparisons.

Actions to be done on the defined subset:
* Generic nuc/spot actions::    Doing something on spot or nuc subsets.
* Nuc specific actions::        Doing something on nuc subsets.

* Defining maybe-do actions::   The menu interface to conditional actions.

Generic interface to act on a nuc subset:
* Menu nuc subsets::            Menu interface to act on nuc subsets.
* Menu spot subsets::           Menu interface to act on spot subsets.

Menu current genomes

* Colouring on equality::       Display cells with same amount of a quality.
* Colouring on difference::     Displaying `less', `equal', `more' type info.
* Menu this genome::            Examining all cells having the same genome.

Big Bang menu

* World size and visibility::   Current worlds geometry and visibility.
* Big Bang::                    Define and create a new world.

Brews record and playback feature.

* Recording from scratch::      How to record an evolutionary session.
* Record after playback::       How to continue recording on an existing file.
* Record benchmark::            Recording to be used as benchmark.
* Playback::                    Playing back a recorded session.

Programmers manual

* Files::                       File overview.

Brews files overview

* Directory tree::              Brews default directory structure.
* Program files::               Program source files.
* Genes files::                 Gene primitive files.                 
* Configuration files::         Initialisation and configuration.
* Output files::                The `brew/OUTPUT/' directory.
* Temporary files::             Files in `brew/OUTPUT/tmp/'.             
* Informative files::           Documentation and informations.
* Programming tool files::      System adaption and profiling.
* Benchmark files::             Benchmarks and benchmark results.
* Console and key setup::       Configuring console size and keys.
* Bugs and Debugging::          Debugging and known bugs.






File: brew.info, Node: License, Next: Goals, Prev: Top, Up: Top

GNU GENERAL PUBLIC LICENSE
**************************

                         Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

   The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.

   To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

   We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

   Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

   Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and
modification follow.

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  2. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.

       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:

       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,

       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,

       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

  5. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.

  7. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

  9. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.

 10. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.

                                NO WARRANTY

 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs
=============================================

   If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  NAME OF AUTHOR
     
     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License
     as published by the Free Software Foundation; either version 2
     of the License, or (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public License along
     with this program; if not, write to the Free Software Foundation, Inc.,
     59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

   Also add information on how to contact you by electronic and paper
mail.

   If the program is interactive, make it output a short notice like
this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
     type `show w'.  This is free software, and you are welcome
     to redistribute it under certain conditions; type `show c'
     for details.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.

   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright
     interest in the program `Gnomovision'
     (which makes passes at compilers) written
     by James Hacker.
     
     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Library General Public License instead of this License.




File: brew.info, Node: Goals, Next: Introduction, Prev: License, Up: Top

What it's all about
*******************

'brew' is an interactive environment for experiments with an
`artificial code evolution' using the Forth language.
*Note Evolutionary programming::.


The main intention is to supply a test environment to experiment with
this fascinating programming technique, try out different approaches
and to analyse the results.

Brew generates gene sequences of real Forth code and compiles
successful genes at run time. It gives you lots of possibilities to
watch the evolutionary process in real time, like scanning inner
variables and displaying results as bar graphics or let it's cells be
located in a grid and show that on screen. Brew can write the
generated code to files or generate detailed log files about many
aspects of its inner working.

Brews recording capability allows reproducing interactive sessions and
demonstrating them easily, or to run series of experiments with
changed parameters.

Brew comes with its own pseudo graphical user interface which gives
you access to just about every parameter and setting without learning
a new syntax. This can be done interactively at any time of an
evolutionary experiment and you can study the effects immediately.


Brew is extensible. Suggestions about missing features are welcome.
If you experiment with it, please let me know. I'm interested in
extending brew based on user feedback.


If you miss information about some topic in this manual mail me
please. I will add more nodes on request.




File: brew.info, Node: Introduction, Next: Users manual, Prev: Goals, Up: Top

Introduction
************

* Menu:

* Evolutionary programming::    What do I mean by 'evolutionary programming'?
* Biological analogy::          Is this artificial life?
* Feature overview::            A quick overview over some brew features.
* Getting started::             Where to get Forth and how to start brew.
* Run evolution::               Brew the gene soup...
* Why Forth?::                  Why do I use Forth?




File: brew.info, Node: Evolutionary programming, Next: Biological analogy, Prev: Introduction, Up: Introduction

What do I mean by 'evolutionary programming'?
=============================================

Years ago I had a crazy idea:
Shouldn't it be possible to write a program that would generate program
units by creating numerous more or less random code snippets and optimise
them by a evolutionary process a bit similar to the darvinistic view of
biological evolution?

I imagined that the main program would start a number of small program
items with random code and random variable values that were scored on
success of solving a given task. If the score reached a certain level
the program can reproduce and build another copy of itself. If the
limit isn't reached within a certain time the item gets taken out of
the play. So I imagined that successful code (and variable values)
would increase rapidly, while bad variants would disappear.

The trick is to make the copies of the program snippets differ a bit
from the original ones, changing code and variables, at least
sometimes. So new genetic variants and mutations arise.

When the number of tried code snippets increases too much, the
conditions are made harder automatically. The results must be better
now to be considered a success. Couldn't that give a evolution a bit
similar to the biological one?

I tried it out on a old slow Atari ST using Forth as language and was
positively surprised and fascinated by the results.


Later on I rewrote the whole thing on more decent hardware under
Linux. I learned through usenet discussions that the principle wasn't
at all my own invention. Others had tried similar things long before
me under names like `evolutionary programming', `genetic programming'
or even `artificial life' and others.

I prefer the term `evolutionary programming' and call the process a
`artificial code evolution'.

* Menu:

* Simple hypothetical example::  How it could be used.
* Changing code::               How the code get's changed.




File: brew.info, Node: Simple hypothetical example, Next: Changing code, Prev: Evolutionary programming, Up: Evolutionary programming

Simple hypothetical example.
----------------------------

Let's take a very simple example:
In an experiment you would change a single parameter and get a single
result. You would like brew to figure out how to compute the result
from the input parameter. It could be an electronic device, with one
input and one output.

So you'd give a certain input to the device and measure it's output.
You provide the input (as read only variable) to the program and
expect the code snippets to return their guess for the output in a
certain variable. The input would get changed with each step.

Now the code snippets would get scored on their guess what the output
could be. Eventually they might find out by accident to put the result
of a computation based on the input in the variable where you expect
the result. A kind of evolution might start giving better results
after some time.


Of course you'd have to supply the hardware and software interface to
the tested device if you'd actually want to do the experiment with
brew. When testing brew I do not actually do the experiment, but give
a random input parameter and supply the result formula to the scoring
process. So the evolutionary process would have to find out a
surviving strategy under this (unknown) scoring rule.




File: brew.info, Node: Changing code, Prev: Simple hypothetical example, Up: Evolutionary programming

Changing code
-------------

Let's assume the electronic device in our example is a very simple
one. It would give an output that would be the sum of an offset and
the input voltage multiplied by a gain:

           output

              ^  *
              | *
              |*
              * <- offset
             *|
  ----------*-+----------->  input
           *  |
          *   |
         *    |
        *     |


Maybe we would start the evolution with inputs very close to zero,
drifting away in a random way.

One of the random code snippets might copy the content of a inner
variable to the result variable. If the result happens to be somehow
close to the offset of the device this will give a better score.

Brew takes two different approaches to optimise the result:

* Menu:

* Variable diversification::    Optimising numeric values.
* Code mutation::               Building new code to try it out.




File: brew.info, Node: Variable diversification, Next: Code mutation, Prev: Changing code, Up: Changing code

Variable diversification
........................

Inner variables, local to the code snippets get changed in a random
way when the code reproduces. In our simple example the inherent
selection process will lead to the variable in question getting closer
and closer to the offset of the probed electronic device, as the cells
with this value would get the highest score.

In a biological analogy I would compare such diversification to an
individual having a bit longer legs or something. It's more like a
variation then a real mutation.




File: brew.info, Node: Code mutation, Prev: Variable diversification, Up: Changing code

Code mutation
.............

Meanwhile the tested input voltage of our experiment would have
drifted away from zero during our evolution. So the gain part of our
hypothetical device gets more and more influence on the result over
time.

In a certain rate brew does try out other random code to be executed
by mutating it. It might try out multiplying the input by the content
of another local variable and adding it to the offset. If this
happens, the gain variable and the offset variable would optimise
quickly by the mechanism described above.

In a biological analogy I would compare this to proper mutation, like
an individual having another number of legs or growing wings instead.

Brew does generate gene sequences of real Forth code.



While results do happen sometimes to be as ideal as described above,
this is not always the case. Probably there would be much more code
executed that might not have any influence on the result. As we will
see later, we can score on code length too, and mutation can cut out
random code parts to strip it down to the essential parts.

Quite often the process will not find usable solutions at all, or give
good, but very unexpected results ;-)




File: brew.info, Node: Biological analogy, Next: Feature overview, Prev: Evolutionary programming, Up: Introduction

Biological analogy.
===================

The concept of 'evolutionary programming' has many analogies to
biological evolution.

The mechanism how brew tries to find a solution to a given task is
very similar to the darvinistic approach on biological evolution. As
we need words to think about something I do use a pseudo-biological
vocabulary to describe what's happening. As simple as the basic
concept may appear, things get much more complex as you proceed.

* Menu:

* Artificial life::             Does brew evolve a form of virtual life?
* Biological terms::            Some biological terms used in brew context.




File: brew.info, Node: Artificial life, Next: Biological terms, Prev: Biological analogy, Up: Biological analogy

Artificial life
---------------

In this manual and in the source I do use terms like 'cell' 'genes'
'genome' 'reproduction' 'cell division' 'population' 'food' 'birth'
'living' and many others. I want to make clear that this is only an
analogy, helping my limited mind to understand and communicate how
things work.

I do not think in any way that brew is actually producing a kind of
virtual life, though it might look sometimes as if it would.


This being said I can mention the fact, that some people do use terms
like `Artificial Live' differently and might actually use it in the
context of brew.




File: brew.info, Node: Biological terms, Prev: Artificial life, Up: Biological analogy

Biological terms
----------------
Let me give you some biological terms and an explanation what they
mean in the context of brew:

   * `cell'. By `cell' I mean the entity of all code and data related
     to one of those code snippets tried out by brew. A cell is
     essentially a data structure with inner variables and pointers to
     the executed code. I call this data structure `nucleus'. A `cell'
     can have a location in a virtual world (*Note Run modes::).
     (*Note Note to Forth programmers::).

   * `nucleus'. Data structure of a `cell' as explained above.
     Sometimes I do call them `nucs'. Strictly speaking this is the
     part of the nucleus that all cells have. A `nucleus' can have
     extensions like other variables or such in addition to the `nuc'.

   * `gene'. Genes are Forth program code executed when the cell is
     activated. Gene code can be interpreted during an initial trial
     phase and get compiled if they are successful. Genes are
     generated by `mutating' the genes of the mother cell. I usually
     start evolutions with a gene that does nothing at all.

   * `genome'. The sequence of all `genes' of an individual cell.

   * `mutation'. The process of gene generation and modification.
     There are several distinct mutation types, some exchange
     individual genes of a certain kind, others add new gene sequences
     or cut random sequences out of the mother genome.

   * `population'. All the cells currently living in a virtual
     `world'.

   * `population control'. The mechanism that automatically regulates
     the number of living cells by making conditions harder or easier
     depending on the current number of individuals.

   * `world'. I hate programs that run for hours only to spit out a
     number as result after a long time. That's boring! So you can run
     brew in a mode where every cell has a location in a virtual world
     and you can watch what's happening while things evolve.




File: brew.info, Node: Feature overview, Next: Getting started, Prev: Biological analogy, Up: Introduction

Brew feature overview
=====================

Brew is a highly customisable and very interactive program to try out
`evolutionary programming'.

Brew has some special features. Let me just enumerate some:

   * Interactivity. Brew is highly interactive. It has it's own form
     of menus, which could be described as a form of active text. Just
     move cursor and press `<RETURN>' to select something on the
     screen. (This is brews equivalent of moving the mouse and
     clicking in a GUI type of user interface). The menu system tries
     to give you some hints of how it works, so I advise you to just
     try it out.

   * Configurability. Brew is highly configurable through a set of
     configuration files.

   * Compile time configuration. When you start brew, brew will be
     compiled before it starts. As the Forth compiler is incredibly
     fast you won't even recognise that. You can compile brew with
     many different options adapting it to the experiment you want to
     make. (*Note Compile time options::).

   * Record and Playback abilities. Just about anything you can do
     with brew can be recorded, saved and played back later on. This
     is not only the case for evolutionary sessions, but also for any
     configuration you made through the menus or through configuration
     files.

   * Context sensitive documentation interface. Pressing `?' will let
     you browse the documentation, starting with the node related to
     the menu context. `<F1>' should give the same result.

   * World mode and linear mode. Brew can run in the so called `world
     mode' and does this by default. In world mode each cell has a
     defined location in a virtual `world' and you can watch how
     things evolve like cells in a petri dish, when you have the
     display switched to display a world map. You can define multi
     dimensional worlds if you have too much RAM and CPU power....

     In world mode brew is a kind of `Evolutionary Cellular Automata'.
     I think there's much potential in this combination.

   * Display modes. Brew can show you many kind of informations while
     it's running. So you can watch bar graphic statistics on
     interesting variables in real time, or you can display
     statistical informations as text, let colour display information
     (in world mode) or switch display off to speed up things. Like
     everything in brew you can interactively switch the information
     given on the display while brew is running. Display modes get
     saved to recorded sessions like everything else.

   * Log files and Code files. Brew can write the generated Forth code
     to a file or log what it's doing. Both can be done with many
     switches what information to include in this files. You can do
     `tail -f' on these files and watch what's happening.

   * Benchmarks. Brew is eating a real lot of CPU power and using a
     lot of Forth features. You can use it to benchmark your Forth
     system and hardware. It comes with some predefined benchmarks and
     it's very easy to make new ones.

   * Programmability. If you're able to program in Forth you can
     extend brew, write new gene primitives or do whatever you like.
     You can even change gene sequences that brew has generated or
     write your own ones during an evolution, and contribute your own
     ideas to the evolution in process. (Record mode would record your
     code like any other user interaction of course.)

     If you don't know Forth consider learning a bit. It's not
     difficult, just forget what you have learned about other computer
     languages first. Forth is different.




File: brew.info, Node: Getting started, Next: Run evolution, Prev: Feature overview, Up: Introduction

Getting started
===============

Download brew:

Get a current brew version from `http://reppre51.home.solnet.ch/'


Installation:

To install brew just unpack the files, say:

* `tar -xvjf brew.tar.bz2' (if you have a xxx.tar.bz2 file).
   (older tar versions might need `-xvIf' instead of `-xvjf').

* `tar -xvzf brew.tgz' (if you have a xxx.tgz file)

then: `cd brew'

I would unpack brew in brew users home directory.
Please do read `README-SECURITY'.


Forth:

You need a Forth system to run brew.
Basically you start brew by changing to the brew directory and
typing the name of your Forth system followed by `brew.fs':

`cd brew'
`FORTH brew.fs'     where`FORTH' is the name of your Forth.

As brew needs a lot of dictionary space you have to start most Forth's
with additional options. See the different Forth systems below for
instructions.


Brew is developed and tested mainly on Gforth on Linux text console.
It's tested (less intensively) on some other Forth systems and seems to
run there.  Please mail me if you want to adapt it to other systems.


How to get a Forth system and how to start brew:

* Menu:

* Gforth::                      GNU Forth by Anton Ertl, Bernd Paysan e.a.
* pfe::                         Portable Forth Environment. Guido Draheim.
* bigForth::                    Forth system written by Bernd Paysan.
* iForth::                      Commercial, fast Forth by Marcel Hendrix.



Now you can try to start brew on a text console.
Brew will give you some usage hints, so just try it out.


You should be able to reach a context sensitive help from just about
any place inside brew, by pressing `<F1>' or `?'.


Most things in brew are text mode menus. Just move the cursor
somewhere and press `<RETURN>' to select something and explore some of
brews possibilities. So when in other types of user interfaces you
would move the mouse and click on something, you do this in brew by
moving the text cursor and press`<RETURN>'.

`k' will normally show you key bindings active in the context.


Quit brew with `QUIT brew' in system menu (*Note System menu::),
or by saying `goodbye' (which might be on `<F12>').
(*Note Menu function keys::). My personal shortcut to quit brew is
pressing a couple of `y'.

Brew will clean up temporary files and give you a list of produced
output files.


This brew version runs best on the Linux *text console*.
Running brew outside Linux text console is not really supported,
though you might eventually succeed to run it there. Whatever you
try, please do use a *fixed width* font, brews menu system depends
on that.

There is a simple console size setup helper `configure-console.fs'.
Try that if there are display problems.


If you have problems with keys like `<RETURN>'
`<CURSOR-ARROWS>' `<FUNCTION-KEYS>'
`<PageUp>' `<Home>' try to run
`make-ekey-map.fs'. Brew will suggest that anyway if it
gets unknown key codes.
(*Note Console and key setup::)




A good place to ask questions about Forth is comp.lang.forth on usenet.
You will find many active Forth experts there.




File: brew.info, Node: Gforth, Next: pfe, Prev: Getting started, Up: Getting started

Gforth
------

Gforth is a widely used Forth under the GPL. It is my main development
platform and available for many different processor architectures. The
goal of the Gforth Project is to develop a standard model for ANS
Forth. Gforth comes with documentation in info format.

Chances are good, that your Linux includes Gforth, but I would
recommend compiling it from source.

Get Gforth from:
`http://www.complang.tuwien.ac.at/forth/gforth/'
`http://www.jwdt.com/~paysan/gforth.html'

Join the Gforth mailing list, if you have questions about it.

To start brew change to the brew directory and say something like:
`gforth --dictionary-size 10M  brew.fs'
Of course you can adapt dictionary-size to your needs. About 2M is the
minimum to run brew, the more the better.  I use 120M and more ;-)




File: brew.info, Node: pfe, Next: bigForth, Prev: Gforth, Up: Getting started

Portable Forth Environment
--------------------------

`pfe' the `Portable Forth Environment' is a very nice Forth
implementation in C.  You can download it from:
`http://sourceforge.net/projects/pfe'

start brew with:
`cd brew/'
`pfe brew.fs'




File: brew.info, Node: bigForth, Next: iForth, Prev: pfe, Up: Getting started

bigForth
--------

bigForth is another GPL'd (at least for Linux) Forth system. It is
written by Bernd Paysan. Bigforth comes with interesting extensions
(like MINOS) which are not used by brew however.

Get it from `http://www.jwdt.com/~paysan/bigforth.html'
There is a mailing list too.

You have to increase mem-size and dictionary-size to use brew on bigForth.
For a big comfortable system you could say
`bigforth  --mem-size 106M --dictionary-size 80M brew.fs'
`bigforth  --mem-size 4M  --dictionary-size 2M'  would be about the minimum.

As you can see mem-size has to be bigger than the desired
dictionary-size. Bernd Paysan, the author of bigForth advised me to
take about 9/8 and add a few megabytes. Just try it out.




File: brew.info, Node: iForth, Prev: bigForth, Up: Getting started

iForth
------

A very fast commercial Forth written by Marcel Hendrix mainly for NT,
but running also under Linux.

See Marcel Hendrix's home-page for more adequate information.
`http://home.iae.nl/users/mhx/'


Brew on iForth is experimental at the moment,
a step more experimental than brew is anyway ;-)

Marcel Hendrix had informed me that some newer brew versions gave
different results on iForth 2.0 than I'm getting on the systems I use
here. These problems have disappeared now. Benchmarks do run now and
give the same (evolutionary) results as on Gforth, pfe and bigFORTH,
and Brew runs very fast on iForth 2.0.

But I still do have problems with brews menu system on iForth 2.0 on
Linux. (I do not have NT to test on it).

We will try to fix that. So please check for a new brew version.




File: brew.info, Node: Run evolution, Next: Why Forth?, Prev: Getting started, Up: Introduction

Let it brew.
============

Press `<SPACE>' to start and stop the evolutionary process.
Watch it for a while, then just press some keys and see what happens....

Yes, please do me the favour and just give it a try before you
read on, I'll wait here for you....
Hope you'll find your way out somehow ;-)

Leave brew by pressing some `Q' or try `<F12>'.


You should be able to read the context sensitive documentation by
pressing `?' or (hopefully) `<F1>'.




File: brew.info, Node: Why Forth?, Prev: Run evolution, Up: Introduction

Why FORTH
=========

People ask me why I do use such a strange language as FORTH and not C,
C++ or Java. The reason is not because brew is such a crazy program
that I just *had* to use some obscure minority language to write it,
no, I have selected FORTH for a couple of reasons:

   * FORTH offers the programmer some unique possibilities. Some of
     them are very valuable to setup artificial evolution. Forth
     applications have full run time access to Forths compiling and
     interpreting capabilities. A Forth program can compile new
     functions at runtime. Compilation is very fast and there is no
     separate linking required. So brew can compile successful gene
     code at runtime and use it at full speed.

   * Compiled code uses up memory. As most of the tested code
     mutations are just garbage it's a big gain that a Forth
     application can also use the FORTH interpreter. Interpreting is
     very fast. Brew takes advantage of it by first trying out new
     code while keeping it in a string that gets interpreted. If the
     code does not get scored well enough (which will be much more
     often the case than not) the string just disappears without using
     up any resources.

   * Factorising program flow into small reusable simple items is a
     strength of Forth. I consider this to be an important plus in the
     context of code evolution. Artificial evolutions sometimes are
     surprisingly good at finding solutions of simple problems, but
     often do a lousy job in more complex situations. So reusable,
     simple code items could become valuable gene building blocks in
     an evolutionary process.

   * Forth is a stack oriented language and brews genes use the stack,
     of course. I have the impression that mutation based on a stack
     has a better chance of changing code structure in a useful way
     than without. Mutation is based on stack flow which somehow
     reflects (aspects of) the code structure.

   * I think FORTH is one of the most intelligent ways to deal with
     programmable devices such as computers.


* Menu:

* Note to Forth programmers::   




File: brew.info, Node: Note to Forth programmers, Prev: Why Forth?, Up: Why Forth?

Note to Forth programmers
-------------------------

A quick note to Forth programmers:

Please note that I do use some terms different than they are used
inside the Forth community, so that people coming from other computer
languages might understand what I mean:

   * `Cell'. By `cell' I mean those virtual beings brew produces.

   * `Code'. The term is used in the sense of `Forth program code'
     like programmers of other languages would understand it. I do not
     mean machine code. Brew only generates high level Forth code.

   * `Function'. Sometimes I talk of `functions' instead of `words'.

   * `Call'. Sometimes I `call' a function instead of `executing' a
     word.




File: brew.info, Node: Users manual, Next: Programmers manual, Prev: Introduction, Up: Top

Brew user manual
****************

* Menu:

* Some brew basics::            Some basics you should understand.
* Using menus::                 Basics of the brew user interface.
* Context documentation::       Reading context documentation.

Brews main display:

* Brew main screen::            Brew can have some very different looks.
* Display menu::                Configuring display.
* Color menu::                  Coding information into colors.
* Menus menu::                  Browse all globally accessible brew menus.

Individuals, nuclei and spots:

* Individuals menu::            Selecting predefined individuals.
* Nuc menu::                    Editing nucs.
* Edit spot menu::              Editing a single spot.
* Menu global variables::       Global variables visible to the genomes.

Controlling population:

* Food menu::                   Food supply controls population.
* Population control::          Mean automatic stress producer.

Diversification and mutation:

* Diversification menu::        Changing variable values.
* Mutation menu::               Configuring mutation.
* Gene pools menu::             Selecting a gene pool.
* Actual pool menu::            Probabilities of currently used genes.
* Stack type symbols::          Brews rudimentary stack type checking.
* Gene primitives::             Building blocks for genomes.
* Gene edit menu::              Editing genomes by hand.

Displaying statistics about cells and spots:

* Scanning nucs::               Display nuc statistics.
* Scanning spots::              Display spot statistics.

Advanced operation:

* Configurable actions::        Do something on nuc or spot subsets.
* Menu current genomes::        Examining all genomes of all living cells.
* Menu select nucs::            Set a multi purpose `selected' flag.

World wide settings and creation of new worlds:

* World menu::                  World wide settings and interfaces.
* World list menu::             Multiple worlds to choose from.
* Big Bang menu::               Creating new multidimensional worlds.
* System menu::                 Brews system wide settings.

Logging and writing the generated program code to files:

* Log files menu::              Detailed switching what to log.
* Code file menu::              Write produced program code to a file.

Recording evolutionary sessions:

* Record and Playback::         Recording evolutionary sessions.

Compile time configuration:

* Compile time options::        Start a customised brew.

Miscellaneous:

* Menu function keys::          Configuring function keys.
* Menu Demos::                  Some demos.
* Experiments::                 Advanced users demos.




File: brew.info, Node: Some brew basics, Next: Using menus, Prev: Users manual, Up: Users manual

Some brew basics
================

There are some basic things you should understand to work with brew:

* Menu:

* Genes::                       What they can do and what they can't.
* Diversification/Mutation::    Two classes of changes.
* Trial phase::                 Trying out new code first.
* Classes of variables::        Cell variables and world variables.
* Run modes::                   Brew can run in different modes.
* Display modes::               Brew can show you different informations.




File: brew.info, Node: Genes, Next: Diversification/Mutation, Prev: Some brew basics, Up: Some brew basics

Genes
-----

In analogy to biology the Forth words executed by a cell are called
`genes'.

Genes can get changed by the `mutation' process. It is essential to
understand that mutation will only build on predefined gene
primitives. So if the manual talks about random code mutations this is
a simplification. Genes can only do things that are possible to
program with the given set of `gene primitives'. Like everything in
brew the set of gene primitives and the probability of each primitive
to get used by the mutation process can be configured at run time (or
by configuration files) and saved. Of course you can change that
during an evolution.

The set of gene primitives delivered with brew does not allow to call
any system functions or extern programs. This is absolutely crucial
for security reasons! If you introduce a new gene primitive you *must*
take care that mutation cannot possibly build anything dangerous with
it. The cells don't care what they do, they just try everything they
can....

The possibilities given by the gene primitives are in fact quite
restricted. The genes can access a set of variables, some of them are
read only, some can be written. There are genes to read and (possibly)
write these variables, genes for mathematical operations, comparisons
and conditionals....

There are *no* gene primitives to do any kind of address arithmetics.
This is essential not only for security reasons, but also for the
stability of the program. If you program new gene primitives you must
be aware of that.




File: brew.info, Node: Diversification/Mutation, Next: Trial phase, Prev: Genes, Up: Some brew basics

Diversification/Mutation
------------------------

The trick of evolutionary programming is to let copies of a genome be
variants and not just clones of the mother genome, at least sometimes.

There are two distinct ways brew does variation of the mother cell:

Variable Diversification:

     Diversification does not change genes but changes variable values
     only. Small changes appear more often than big ones. The process
     of selection will hopefully optimise the variables value.

Code Mutation:

     Proper mutation does change the genes, that is the code executed
     by the cells. There are several types of mutation, some insert
     new gene sequences (built out of the available primitives or from
     genes that have been built earlier in the evolution), some
     replace a single gene by another one fitting in the given
     sequence, some cut pieces out of the gene sequence, some restart
     to build a completely new sequence from scratch. The probability
     of each mutation type can be configured like usual.


In a biological analogy I would compare diversification to a child
having legs that differ a bit in length from those of the mother,
while in the case of mutation it would have another number of legs or
grow wings instead.




File: brew.info, Node: Trial phase, Next: Classes of variables, Prev: Diversification/Mutation, Up: Some brew basics

Trial phase
-----------

Most of the gene sequences generated by mutation are absolutely
useless. It would be a waste of memory to compile them all.

So new genomes must go through a so called `trial phase' first.
If the genome survives a given number of generations it will be
compiled into the `gene pool', but only a small fraction of the
mutated genomes pass this test successfully.

Genes on trial never get mutated, but the variables can get
diversified as usual.

*Note Why Forth?::, for some technical details.




File: brew.info, Node: Classes of variables, Next: Run modes, Prev: Trial phase, Up: Some brew basics

Classes of variables
--------------------

The variables that the genes can see come in two distinct classes:
Hereditary variables inside the nuc and external world variables.
Nuc variables are local to the cell, world variables to the spot.

All of them come as integer and float variables, and have read-only
and read-write variants.

Another (orthogonal) distinction is between variables that get
diversified (or at least can be) and those that are not.

Inner variables of the nucleus (nuc variables):

     Each cell has a set of inner variables in the nucleus.

     Some of them (i.e. the cells ID) have no relation to the genes
     and can not be seen by the cell. They only have meaning for brew.

     Others can be read or read and written by the cells genes. As
     part of the nucleus these variables are hereditary, are copied
     from the mother cell to their children. Some of these variables
     can be diversified and will get optimised by selection of 'good'
     values.

Variables of the virtual environment (world variables):

     The other class of variables does not belong to the cell but to
     it's environment. They are *not* hereditary of course. They
     belong to the virtual spot the cell is living on. Some can be
     changed by the cells genes though, which might lead to a change
     in score for the cell or for it's children. Of course this is
     only the case if the scoring function depends on the variable in
     question, or if the cell passes useful information (like
     intermediate computed results) through these variables to itself
     or to the cells that will life later on the same spot. (These
     will very often be children of the present cell).

     Read only world variables get often used as inputs of the task
     the cells are expected to do.

The number of variables of each class and subclass is compile time
configurable, of course.


It helps understanding brew better if you know about the names of the
different classes of variables. Look them up here:

* Menu:

* Variable names::              Variable naming scheme.




File: brew.info, Node: Variable names, Prev: Classes of variables, Up: Classes of variables

Variable names
..............

All variables of a subclass have the same name witch a capital letter
to distinguish each individual variable. Think of the capital letter
as an index in an array. For nuc variables the letter follows the
name, while it precedes in the case of world variables. So `organ-A'
and `organ-B' are two nuc variables of the same kind, while
`A-quality' is a world variable.


Name:        class:   access:        diversified?   compile option        
                                                                          
integer-A    global   read/only      maybe          global-integer-variables# 
dfloat-A     global   read/only      maybe          global-dfloat-variable
                                                                          
organ-A      nuc      read/write     maybe          nuc-organs#           
parameter-A  nuc      read/only      maybe          nuc-parameters#       
invisible-A  nuc      hidden         maybe          nuc-invisibles#       
secret-A     nuc      hidden         no             nuc-secrets#          
                                                                          
A-quality    world    read/write     maybe          spot-qualities#       
A-property   world    read/only      maybe          spot-properties#      
A-secret     world    hidden         maybe          spot-secrets#         

All these different kinds of variables come either as integer or as
floating point variables. The latter do have a `-f-' in their name. So
`f-organ-A' would be the first read/write floating point nuc variable.

For special purposes there are hidden variables not visible to the
(default) gene primitives. You might want to use them for some
experiments that i.e. introduce new gene primitives using such
variables, without giving the mutation process the ability to access
them directly.


Please note:
The next brew version will *not* follow these naming rules any more.
Names will be more custom defined, related to the experiments setup.
Visibility and r/w status will be determined by gene availability only.




File: brew.info, Node: Run modes, Next: Display modes, Prev: Classes of variables, Up: Some brew basics

Run modes
---------

Brew can run in a number of different modes.

You must understand at least the first two:

   * `World mode' In world mode the `cells' have a defined location in
     a virtual world. If display mode let's you see the world you can
     watch the cells like cell cultures in a petri dish. After a short
     time you will be able to see when a new useful gene has evolved
     or somesuch. If a cell wants to divide it only can do so, if a
     neighbouring spot in the virtual world is free. Of course you can
     be in world mode but switch display mode to see let's say
     statistics. So you don't *have to* look at the virtual world
     while in world mode.

   * `Linear mode' In linear mode cells do *not* have a defined
     location as in world mode. The two modes are exclusive. If a cell
     wants to divide brew will give it a memory allocation if the
     number of living cells allows it to do so.

   * `Record mode'. Brew can record just about any interaction you can
     do with it and write it to a file. The file is a normal Forth
     file which can be edited if you want to. Recording can not only
     be used to record evolutionary sessions, but also any kind of
     configuration made through the menus. Many configurations (but
     not necessary all of them, if you get too fancy) made through
     configuration files will also be included in the record file.

   * `Playback mode'. Playing back a recorded file by interpreting
     it's contents. Record and playback modes are exclusive.

   * Other modes. There are a number of other modes not explained
     here. Look in the source for `run-mode-masks' to learn more
     about.

You can combine different modes if they are not exclusive. So you can
be in record mode *and* in linear mode at the same time, but you
cannot be in world mode and linear mode at the same time, and you
can't record and playback simultaneously. Brew will not let you switch
to impossible run mode combinations, so just try it out.


You switch run modes in the corresponding menus:
*Note System menu::, for switching between world and linear mode.
*Note Record and Playback::, for recording and playback.




File: brew.info, Node: Display modes, Prev: Run modes, Up: Some brew basics

Display modes
-------------

Brew can display very different informations in a number of ways:

You can look how the cell cultures move in the virtual world while in
world mode, or you can watch statistics as text summary or bar graphs
in real time in step display.

Just look at some examples:

* Menu:

* Example world mode display::  Petri shell look.
* Example step display::        Real time statistics.




File: brew.info, Node: Example world mode display, Next: Example step display, Prev: Display modes, Up: Display modes

Example world mode display
..........................


...................       ******** ........  .**     ...      *********  . ....
....................       *******. ...... ..****    .......*********   .......
...................        ******    ........****     .......********  ........
.................... .  .   ******   ......*****      .......*******...........
.........................  ******** .... ..**** *    .........  *** ...........
.........................  *******.  . . ********    ..........****............
 .. ..   ......... ....... ******** .  ..********     ......... .* ............
  .    . .  .... . ......   *******   ..*********       .........  ...... ...
        .  ... ...*.....   ********....  ******* *      ..........*.......
 *********       **.....  ********..... ********* *    ....   ..    ... .   **
***********     ***************** .....*********       ..... ....   .   *. ****
************** *****************  .....********* *   ....... .  ..    *********
******************************** ....  ********     .........  .       ********
****************************** * ...   ********     ........          *********
**************************** *     . ..********     .......         ***********
****************************      . ....*****  *   ....... .       ************
****************************    .......*******     ........      **************
************** **************    .....* ****** *    .......     ***************
  **  * ** ** *  ************   ..  ...****** *     ......      ************ **
  *       *      **************    ...  ******     . ....       *********** *
*               *  ************     .. ******      ..... .      **********
         ....         * *******     . ...****      .....        ********  *
step: 636           cells: 42680         burden: 442        living: 1232

Each character symbolises a `cell'.  You can select and edit them.
*Note World map interaction::.

The bottom line displays some infos as text.  You can configure
what infos will be displayed.  Select the bottom line to do so.
*Note Display menu::.




File: brew.info, Node: Example step display, Prev: Example world mode display, Up: Display modes

Example step display
....................

This display type gives you real time statistic informations using textual
representation and different kinds of quite primitive  ASCII graphs.
It might need some time to get used to.
As primitive and simple the display might appear, it is surprising how
much detail information about the evolutionary process you can grasp from it,
once you got used to it....

e
 e
  e  xx                     AAAAAAAAA     A A AAAAAAAAAAA       AAA     A
   eAAAAAAAAAAAAAAAAAAAAAAAA   xx xxxAAAAAxAxA    xxxxxx AAAAAAAx  AAAAAx
   x  eexxxxeeeeeeexxxeeeeexxxxeeeeeexxxxeeeeexxxxeeeeeexxxxeeeeexxxxeeee
xxx
AAAA
e ave energy  x var living  A ave organ-A
                                                        *
                                                        **
                                        *  *     **   ****
                                       **  **   ***   *****
                                       **  **   *************
                                       **  ***  *************
                                      ***********************....             .
-380        scanning: energy                      vertical range: 72      1433
                                                 *
                                                  *
                                                * ****
                                                ******
                                             ** *******
                         .      .   ......***************......    .    .  .
-395        scanning: organ-A      -<zooming>|      vertical range: 117    190
food                    min: 0            max: 1254         average: 259
step: 73            cells: 9479         living: 825         +burden: 41

*Note Brew main screen::, common main screen capabilities.
*Note Step display interaction::, to see what else you can do here.
*Note Display menu::, for configuring display.




File: brew.info, Node: Using menus, Next: Context documentation, Prev: Some brew basics, Up: Users manual

Using menus
===========

Brew has it's own form of user interface. It is a kind of active text.

Usually this text menus serve the purpose of giving informations about
current settings and give an interface to change them.

You can select things on the screen by moving the cursor on it and
pressing `RET'. If you select the menu title or press `?' you can read
the documentation about the menu.

Most menus also have key bindings, which are more convenient once you
get used to them. (*Note Key bindings::). Press `k' for key bindings.

To leave a menu press `q'.
As menus do nest, this will usually bring you back to the prior menu.
(Pressing `q' repeatedly will always bring you back to brews main screen).

`?' gives context sensitive documentation.


Many brew menus have some built in 'intelligence'. Don't be surprised
if things appear or disappear depending on your selections. Brew tries
to present you only the information and selection possibilities
relevant to a given situation. Sometimes menus give hints or warnings,
or even reset your input (if you try to set something to an impossible
value).

* Menu:

* Menu example::                How a menu might look.
* Moving and selecting::        How to select menu items.
* Key bindings::                Key bindings and how to find them out.
* Colours in menus::            
* Numeric input::               Hidden capabilities when entering numbers.
* Float input::                 Everyday float syntax on input.
* Scale input::                 Input of fractions.
* Selecting functions::         Selecting functions from a list.
* Scrolling menus::             When menus do not fit on a screen.
* Using Forth in menus::        Using the whole power of Forth in menus.




File: brew.info, Node: Menu example, Next: Moving and selecting, Prev: Using menus, Up: Using menus

Menu example
------------

Select actions of the function keys:

F1   does: menus-menu                   shift-F1  does: noop
F2   does: toggle-display-&-go          shift-F2  does: noop
F3   does: spot-scan-menu               shift-F3  does: noop
F4   does: nuc-scan-menu                shift-F4  does: noop
F5   does: noop                         shift-F5  does: noop
F6   does: noop                         shift-F6  does: noop
F7   does: noop                         shift-F7  does: noop
F8   does: noop                         shift-F8  does: noop
F9   does: do-FORTH
F10  does: noop
F11  does: toggle-anything
F12  does: goodbye

Select with <TAB>, cursor arrows and <RETURN>, leave with 'q' (or empty spot)
(Often there are also key bindings to the first letter of a word.  Press 'k')


This menu let's you configure function keys.
You can see it when you press `K' in brews main screen.
It's given as an example how a brew menu might look and work.

The first line is the menu title.  It's coloured in brew.
Selecting it (or pressing `?') shows the documentation.

At the bottom you might see a few (coloured) lines giving you hints
about the current menu and it's usage. Selecting one of these lines
ports you to menu usage documentation.

You can select items (including title and bottom lines) either by
moving cursor and pressing `<RET>', or by using key bindings (*Note
Moving and selecting::).

The following nodes show you how it might look when you try to see key
bindings or actually configure the action of a function key.

* Menu:

* Example key bindings::        What you see by pressing `k'.
* Configuring F5::              Example configuring F5.



File: brew.info, Node: Example key bindings, Next: Configuring F5, Prev: Menu example, Up: Menu example

Example key bindings
....................

Active keybindings:             default: noop   EXIT MENU

!   do-FORTH
1   function-key-actions F1-xt  choose from list and store
2   function-key-actions F2-xt  choose from list and store
3   function-key-actions F3-xt  choose from list and store
4   function-key-actions F4-xt  choose from list and store
5   function-key-actions F5-xt  choose from list and store
6   function-key-actions F6-xt  choose from list and store
7   function-key-actions F7-xt  choose from list and store
8   function-key-actions F8-xt  choose from list and store
9   function-key-actions F9-xt  choose from list and store
?   context-help
`   toggle-highlite-active
k   show-key-bindings
q   quit-menu                   EXIT MENU                                 (all)

Brew tries to figure out what pressing a key would do in the current
menu and to tell you in a somehow understandable language. Hope you
can understand from the above that pressing `5' will let you configure
function key `<F5>', by letting you choose from a list of possible
actions. You can see common key bindings too (*Note Key bindings::).

The default action shown in the title is the action of all undefined
keys.




File: brew.info, Node: Configuring F5, Prev: Example key bindings, Up: Menu example

Configuring F5
..............

Select action for this function key

noop
show-key-bindings
|feed-world|
nuc-scan-menu
spot-scan-menu
menu-step-display
menu-nuc-subsets
menu-select-nucs
menu-current-genomes
food-menu
menu-population-control
diversification-menu
color-menu
mutation-menu
big-bang-menu
world-menu
actual-pool-menu
gene-pool-menu
individuals-menu
toggle-display-&-go

Select with <TAB>, cursor arrows and <RETURN>, leave with 'q' (or empty spot)
This menu is a scrolling one.  <PageUp>  <PageDown>  <home>  <end>  <arrows>


Please note what the last line tells you here:
You do not see all the possible selections.  The menu can scroll.
*Note Scrolling menus::.




File: brew.info, Node: Moving and selecting, Next: Key bindings, Prev: Menu example, Up: Using menus

Moving and selecting in menus
-----------------------------

To select a menu item move cursor on it and press `<RET>'.
Move cursor with cursor arrays or jump to next selectable field with
`<TAB>'.

To leave a menu press `q'.
Most menus can also be left by selecting an empty spot or pressing an
undefined key.


In many cases the use of key bindings is a much more convenient way to
work with brew. See next node.




File: brew.info, Node: Key bindings, Next: Colours in menus, Prev: Moving and selecting, Up: Using menus

Key bindings in menus
---------------------

Most brew menus have key bindings. Key bindings are very convenient if
you get used to them. You can look them up in the manual for the
different menus, or just try the first letter of a word. 'Dangerous'
functions normally do not have key bindings, so you might just try.

Pressing `k' calls a function that tries to guess what the Forth code
bound to a key might do. Brew tries to give you a understandable
description what will happen when you press certain keys, but
sometimes you might not be able to understand what it tries to tell
you ;-)

There are a few common keybindings active in most menus:

   * `q': leave menu
   * `?': context documentation
   * `k': show keybindings
   * `!': FORTH interpreter
   * ``': show (most) active menu fields


Other frequently used key bindings:

   * `<SPACE>': next logical action, like start and stop brewing.
     (Usually it's just leaving the menu).

   * `o': Not really a common key binding, but often used to switch
     between two possibilities, like displaying world map or
     statistical data while brewing. Think of 'tOggling' or 'Other'.




File: brew.info, Node: Colours in menus, Next: Numeric input, Prev: Key bindings, Up: Using menus

The meaning of colours in menus.
--------------------------------

Some menus use colours to attract your attention.

   * `Cyan' get's mostly used for important menu display switches.
     They switch between say displaying nuc or spot data or integer
     and floating point values. Very often you will find the `o' key
     binding here (or first letter).

   * `Green' wants to attract your attention to some information, to a
     hint or suggestion, or to an option you could want to choose.

   * `Red' is used for warnings and errors.

These colours are configurable, of course.




File: brew.info, Node: Numeric input, Next: Float input, Prev: Colours in menus, Up: Using menus

Numeric input in menus
----------------------

You selected some value and are given the possibility to give a new
one.

Why even talk about something so simple?
Well below the simple looking interface there is the whole power of the
Forth interpreter. So if you know some Forth you can use it here to
compute your input, get informations or whatever.  The old value is on
stack and the value on top of stack will get stored to the right address
when you will press `<RET>'.  The same applies for float values
(*Note Float input::). Of course you must use float operators on them.

Example:
Let's say you selected 'organ-A' in the nuc menu to change it's value.
You can say things like `2* organ-B @ +' if this seems to make sense in
the given context to set the new value.  As many Forth's offer a history
functionality you might be able to get this input back when needed again,
most likely by pressing the cursor-up-key.  This can be very convenient.

If you don't understand what I'm talking about here, just forget it.
Make your input the way you are used to.
Brew will understand you anyway ;-)




File: brew.info, Node: Float input, Next: Scale input, Prev: Numeric input, Up: Using menus

Everydays syntax for float input.
---------------------------------

As not everybody is used to Forth float syntax brew tries to convert
numeric strings to valid Forth float input where appropriate. So you
can input strings like `10', `2.5', `-3.14159265' and brew will try
it's best to guess what you actually meant to say....

Please note that this has it's limitations:

   * String replacement is only done on the last space separated
     substring of your input.

   * While brew does try to replace number strings it does not replace
     other words like operators and such. So you can't say `pi +' when
     you actually mean `pi f+'.

As on integer input you can use the whole power of the Forth text
interpreter on numeric float input (*Note Numeric input::).




File: brew.info, Node: Scale input, Next: Selecting functions, Prev: Float input, Up: Using menus

Scale input, numeric fraction input in menus.
---------------------------------------------

At some places brew asks you to input numeric fractions. As with
numeric input (*Note Numeric input::) the whole power of the Forth
command line hides behind the simple looking interface.

But brew does some more behind your back here. In certain cases it has
the impudence to change your input, thinking that it knows better what
you want then you did say it ;-)

I know that this is dangerous, but I like the results. Please tell me
if you don't! Anyway, if you start your input with any of the
characters `%' `!' `"' or `'' brew will not try to be clever.


Some examples:

Fraction before:  Input:            Result:           Comment:          
                                                                        
1/2               0                 0/1               setting to zero   
                                                                        
1/2               2*                2/2               multiply          
1/2               2 *               2/2               multiply          
1/2               2/                1/4               divide            
1/2               2 /               1/4               divide            
                                                                        
1/2               2 7               2/7               numeric normal    
1/2               3/7               3/7               numeric           
1/2               4 / 7             4/7               numeric           
                                                                        
1/2               % 2*              1/4               escaping          




File: brew.info, Node: Selecting functions, Next: Scrolling menus, Prev: Scale input, Up: Using menus

Selecting functions from a list
-------------------------------

In many places you can select actions from a list.
Examples are setting display function or genome of a cell,
or determining function of 'look-at'.

The menu entry might look similar to the following line:

<look-at> function:     show-genome-b

If you select the left half you will see a list of functions to choose from.
The menu title will give you a short description of what the selected item
will be used for. You can use the first letter of a item as key binding to
select the item (*Note Key bindings::), at least if only one item starts with
that letter. Otherwise the last displayed item starting with that letter will
be selected.

Selecting the right entry you will see the *definition* of the
selected item.

Sometimes there is an item `(none)' (sometimes `noop') in the list of
selectable items. If you select it it means no selection.

Depending on the number of items you might not see all of them on a screen.
*Note Scrolling menus::.


There's an advanced feature on key `'':

On rare occasions you might want to select a word which is not
included in the list. Press `'', and write Forth code returning the
execution token of the function you want (the xt must correspond to a
*named* word). Please do not use this feature unless you know exactly,
what you are doing. Note that here your input will *not* get recorded
directly, so take care of that yourself, if you want.

The word will further get added to the list to make it convenient, if
you want to re-select it later on.




File: brew.info, Node: Scrolling menus, Next: Using Forth in menus, Prev: Selecting functions, Up: Using menus

Scrolling menus, (menus not fitting on one screen).
---------------------------------------------------


Brew tries to make a menu fit on a screen, but sometimes this is just
not possible. Imagine selecting from a list of items like functions or
files, where you can not know how many lines there will be when the
user invokes the menu. Brew solves the dilemma by making the region of
the screen where the list get's displayed scrollable. So in a
scrollable menu there will always only a part of the screen do
scrolling (at least the title line will not).

If there is space to display a menu help line at screen bottom (and
brew takes precautions to make that line available whenever possible)
brew will tell you when a menu is a scrolling one and therefore not
displaying all available choices by displaying the following line
This menu is a scrolling one.  <PageUp>  <PageDown>  <home>  <end>  <arrows>

So you have the following special key bindings active to make the
scrolling area (and only this one) of the menu scroll:

   * `<PageUp>'. Scroll the size of the scroll area up, stop at top.

   * `<PageDown>'. Scroll the size of the scroll area down, stop at
     bottom.

   * `<home>'. Scroll to top.

   * `<end>'. Scroll to bottom.

   * `<arrows>'. If cursor keys reach upper or lower *screen* border,
     the *scrollable area* of the screen scrolls one line. This scroll
     method is not recommended.




File: brew.info, Node: Using Forth in menus, Prev: Scrolling menus, Up: Using menus

Using Forth in menus
--------------------

If you know Forth you might want to use it's power inside a menu.
The key `!' will give you the possibility to enter Forth words.

Your input will be interpreted when you press `<RET>' and brew
will wait until you press another key.

If you want to make more Forth input before returning to the menu,
press `<SPACE>'.

Please note that this is the exception of the rule that the effect of
any input that could possibly change something on brews state is
automatically reproduced by playing back the record file, as long as
recording was switched on while you did it. This version of brew does
not care at all about your Forth input regarding recording here.




File: brew.info, Node: Context documentation, Next: Brew main screen, Prev: Using menus, Up: Users manual

Reading context documentation from within brew
==============================================

Brew has an interface to port you to the relevant documentation node.
You reach it by pressing `?', by selecting a menu title, or in default
configuration by pressing `<F1>'.

Brew uses an extern reader to do this, so of course all key bindings
are different while reading documentation.

Brew can use either the `info' reader (preferred) or a text mode html
browser (like `lynx') to display the documentation. Make sure you have
installed it. For html you have to produce or to download the html
file separately.

*Note System menu::, to switch between these documentation types, or
to see the strings passed to the OS in case of problems. You will find
hints how to change the default by selecting `reader'.




File: brew.info, Node: Brew main screen, Next: Display menu, Prev: Context documentation, Up: Users manual

Brew main screen
================

Brews main screen is the place to do things like start or stop the
evolutionary process and watch things going. You decide what
informations you are currently interested in and watch them evolving
at real time. It can display different informations in very different
ways. *Note Display menu::, for configuring what to display.

`<SPACE>'
     Press `<SPACE>' and brew will start brewing and continue until
     you press i.e. `<SPACE>' again.

`s'
     Pressing `s' is similar, but will just make one step and stop
     then.

`o'
     Toggle between world display and step (statistics) display.

`k'
     See all the other key bindings. (*Note Key bindings::).

`K'
     See and edit function key bindings. (*Note Menu function keys::).

The effect in terms of cells being generated and tested, genes getting
mutated and optimised, will be the same (if you start from the very
same conditions), but will look very different depending on the
display mode brew is in.

Look at two examples how brew could look in spot and step display:

*Note Example world mode display::, petri shell look world map.
*Note Example step display::, real time statistics display.


*Note Display menu::, choose what you want to see while brewing.
Pressing `D' or selecting the info line (last line of the screen)
ports you to `Display menu' where you can configure display including
info line.


Depending on the display mode you have additional menu interfaces:

* Menu:

* World map interaction::       Things you can do in world mode.       
* Cloning nucs to a spot::      How you can clone nucs.
* Step display interaction::    Interaction in statistical (step) display.


From brews main screen you reach many important other menu screens
with capital letter key bindings. *Note Key bindings::.

Brews menu list is on keys `B' and `m'.
*Note Menus menu::.


...and then, `?' goes to context sensitive documentation, as usual...
(and `d' has some demos).




File: brew.info, Node: World map interaction, Next: Cloning nucs to a spot, Prev: Brew main screen, Up: Brew main screen

Menu interactions in world maps.
--------------------------------

Brew displays world maps when it's main screen is in world mode, but
also to show you special informations coded as colours. Foreground
colour show nuc informations, background colours visualise spot data.

*Note Example world mode display::, to see how it might look.


In a world map you can select individual cells or spots to examine and
edit them:

*Note Nuc menu::, if you press `<RETURN>' on a cell.
*Note Edit spot menu::, if you select an empty spot.


Special key bindings:

`l'
     Pressed when cursor is on a cell shows it's genome as Forth
     source. On a empty space it gives `Edit spot menu'.

`c'
     Press this key if you want brew to continue to use the current
     colour coding while brewing. *Note Conditional colouring::, to
     learn more about.

`*'
     You can select a rectangle region in brews main screen world map.
     Define the region by pressing `*' on desired corners then press
     `<RETURN>' to go to a subset menu over the selected rectangle.
     There you can do whatever you want with the cells living inside
     the selected rectangle (*Note Configurable actions::).


Of course you have all the additional capabilities of brews main
screen menu interface at your disposal if you see the world map in
brews main screen.

In other maps you might find other menu interfaces too, press `k' to
check for key bindings or `<TAB>' to locate additional selectable
items.




File: brew.info, Node: Cloning nucs to a spot, Next: Step display interaction, Prev: World map interaction, Up: Brew main screen

Setting nucs to spots
---------------------

When you have examined a nuc (*Note World map interaction::) or
selected an individual (*Note Individuals menu::) brew will display
`Clone nuc by selecting an empty spot' on the info line. (This stays
as long as brew thinks to know which nuc you are interested in).

While brew is in that mode you can set a clone of the nuc by moving to
an empty spot and pressing `<RETURN>'. Of course you can select the
clone and edit it, if you want. (In this case the edited version would
be cloned if you select another empty spot).

You can even change to another world (*Note World list menu::) and set
clones of the selected nucs there.




File: brew.info, Node: Step display interaction, Prev: Cloning nucs to a spot, Up: Brew main screen

Brews main screen in statistical (step) mode.
---------------------------------------------

*Note Example step display::, to see how it might look.

Selecting the status line of a display item let's you choose the
variable that gets displayed. You can only select variables of the
same type.

In a scan display you can switch between automatic zooming or a fixed
range display (*Note ASCII bar graphics::).

If you select a column in a scan display you get access to information
about nucs or spots inside the value range of the selected bar. Brew
puts you into a `menu nuc subsets' or a `menu spot subsets'
with conditions set for the value range and the variable in question.
From there you can look at the nucs, scan or even change them.
You can define a range of columns by pressing `*' on the range
borders inside a scan bar graphic. When the range is displayed press
`<RETURN>' to go to the corresponding subset menu.
*Note Menu nuc subsets::.

Press `D' to do other configurations or select the `info line'. *Note
Display menu::.




File: brew.info, Node: Display menu, Next: Color menu, Prev: Brew main screen, Up: Users manual

Display menu
============

If you press `D' in brews main screen you come to the Display menu.
Here you can configure what information brew should display while brewing.

Normally you will have either spot display or step (statistics) display on.
Toggle between the two by selecting `step OR spot' or by pressing `o',
as you would do in main screen.

Displaying information in real time is nice to watch but costs time,
of course. So brew can be told to display the information you are
interested in only all (say) 128 steps, which I call `snapshots', or
switch display off completely. Key `t' toggles between real time and
snapshots display, like it does in main screen. Brew distinguishes
between `step-snapshots' and `spot-snapshots' and offers you to choose
between possible frequencies for the snapshots. The selected number is
marked with `*' on both sides.

Display menu let's you configure (only) the type of display switched on.
So switch it on in order to see the options. (Even the `D' key binding
will port you directly to step display configuration if brew is showing
step statistics).

If you insist on it, brew lets you even switch on both at the same
time. It only makes sense on very rare occasions, and you will get a
headache from it anyway....

* Menu:

* Time::                        Brews concept of time.
* Configuring spot display::    Configuring display of world map.
* Step display menu::           Configuring display of statistics.
* Info line::                   Configuring last line.




File: brew.info, Node: Time, Next: Configuring spot display, Prev: Display menu, Up: Display menu

Time
----

While in real life we might have the impression of time moving
continuously in one direction and myriads of different things seem to
happen at the very same time, brew has a different concept of time.

   * Brews time does not flow continuously but moves in concrete small
     steps. The same is true for locations in brews virtual worlds.

   * Different things do not really happen at the same time. In order
     to run the world through one step in time all it's spots get
     called one after the other. If the spot is inhabited, the cell
     get's woken up and goes through one step in his life time. The
     order of going through the spots is configurable.

If brew is displaying a map of it's virtual world it renews it's
display char by char for each spot it is working on. This display mode
is called `Spot display'. Additional information about the cell can be
coded in the char displayed and it's color while information about the
spot can be given by background color. (As colouring is slow, it's off
by default).

If brew is displaying statistical information it runs the whole world
through one step, computes the information in question and displays
it. This display mode is called `Step display'. The informations can
be shown in different ways like simple ASCII graphs, ASCII bar graphs
or as text and numbers, possibly all at the same time in different
regions of the screen.




File: brew.info, Node: Configuring spot display, Next: Step display menu, Prev: Time, Up: Display menu

Configuring spot display
------------------------

If spot display is switched on display menu lets you configure some
spot display settings:

   * `<look-at> function'. Cells show up as chars in brews world map.
     There are a number of functions to determine the char actually
     displayed. *Note Show me functions::, to learn about available
     functions.

   * `Parameters for look-at functions'. Some `look-at functions'
     require additional parameters like what variable to code in what
     scale, or how big the tolerance is, for a value to be still shown
     as zero. These parameters (if any) can be set here on the same
     line as the `<look-at> function'.

   * `Value to ASCII divisor'. Some `look-at functions' transfer a
     numeric integer value to a char. This is the scale for the
     transformation. If the scale is 100 for example a cell will show
     up as `0' if the value in question is from 0 to 99, and as `1'
     for values between 100 and 199. This scaling does not take place
     in cases where the absolute numeric value is not of interest like
     ID's for individuals or genomes. Most of these functions use a
     special mapping from value to displayed chars.

   * `Visibility'. Brews virtual world can have from one to five (or
     more) dimensions of any size. So often only a part of the world
     will be displayed. You can configure visibility range for each
     dimension here. If you want to display a world of more than two
     dimensions you can choose to show only one layer or a range of
     layers one over the other. In the latter case it might be helpful
     to delay display of each individual layer to have a chance to
     understand the three dimensional structure. *Note World size and
     visibility::.

   * `Color'. Color is configured in it's own menu. You reach color
     menu by pressing `C' from brews main screen. *Note Color menu::.

* Menu:

* Show me functions::           




File: brew.info, Node: Show me functions, Prev: Configuring spot display, Up: Configuring spot display

How cells show up in spot display
.................................

In spot display each cell shows up as a char. This char gives some
information about the cell. The function what information gets coded
in the char can be set individually in the nuc (*Note Nuc menu::).

The simplest function always displays a fixed char, so this cell (and
it's offspring) would always show up as a 'X' or something. Other
functions determine the char based on the state of inner variables,
age, energy, generation, genome or such.

Usually you will want to set it to a special function called
`<look-at>' which can be switched to all the others at run time. So
you can switch all the cells that have `<look-at>' as their `show-me'
function to show their age or whatever you like at runtime. This can
be done using key bindings (*Note Key bindings::) from *Note Brew main
screen::, or from display menu *Note Configuring spot display::.

(BTW: If you select the function from spot display you get the
possibility to have a look at it's definition. (*Note Selecting
functions::).)


You can choose among the following functions:

   * `show-ascii' A fixed `char' (see below) is displayed.

   * `show-age' Age determines displayed char.

   * `show-energy' Coding energy level to char.

   * `show-generation' Generation to char.

   * `show-genome' Different genomes look different.

   * `show-genome-b' Same, but using another char subset.

   * `show-genome-generation' Genomes generation as char.

   * `show-code-length' Code length coded as char.

   * `show-integer-nuc-var' Value of a integer nuc var (Variable and
     scale get chosen in *Note Display menu::).

   * `show-integer-var-sign' Sign of a integer nuc var with a certain
     tolerance (Both chosen in *Note Display menu::).

   * `show-float-nuc-var' Value of a float nuc var (Variable and scale
     get chosen in *Note Display menu::).

   * `show-float-var-sign' Sign of a float nuc var with a certain
     tolerance (Both chosen in *Note Display menu::).

   * `show-A' Value of organ-A. Obsolete.

   * `show-sign-A' If organ-A is near zero display `o', else display
     `+' or `-' depending on sign. Obsolete.

   * `<look-at>' This is the most important function, as it can be
     switched to all the others at run time. Switch it in display menu
     (*Note Configuring spot display::) or using brew main screen key
     bindings (*Note Key bindings::).

   * `show-ABC' Show letter A,B or C, depending which of the three nuc
     organs has the biggest absolute value. Use minuscule if the sign
     is negative.

   * `show-ABC*.' Quite obscure function used in an old demo.

   * `show-ABC-X|' Quite obscure function used in an old demo.

   * `show-~|'.*' Quite obscure function used in an old demo.




File: brew.info, Node: Step display menu, Next: Info line, Prev: Configuring spot display, Up: Display menu

Step display menu
-----------------

Configuring step display is more complex than spot display, so it has
it's own menu page. You will reach this page from display menu, or if
step display (only) is on, from brew main screen by pressing `D'. Step
display is always done after running the whole world through one time
step. It displays some statistics in real time about the evolutionary
step that just happened while brewing.

* Menu:

* ASCII graphs::                So called `continuous display'.
* ASCII bar graphics::          Displaying distribution of values.
* Text display::                Minimum, maximum and average as numbers.

The different kinds of statistical data representations can be combined
at the same time each one in his own screen area.

* Menu step display::           Configuring step display screen.
* Menu continuous display::     Continuous display sub menu.
* Step display presets::        Often used display configurations.

As primitive as these display types are, it's surprising how much
information about the evolutionary process you can get if you watch
them at real time and if you know what to look for ;-)




File: brew.info, Node: ASCII graphs, Next: ASCII bar graphics, Prev: Step display menu, Up: Step display menu

ASCII graphs
............


      x
     x x       x       xx        xx        x
             xx x        x      x  x      x x       xx       xxx      xx
    x            x    x   x    x         x   x     x  x     x   x    x
        x   x     xxxx     xxxx     xxxxx     xxxxx    xx  x     x
   x     x x                                             xx       xxx
          x                                           $$$$$$$$$$$$$$$$$$
  x                                 $$$$$$$$$$$$$$$$$$
 x                 $$$$$$$$$$$$$$$$$
x    $$$$$$$$$$$$$$
$$$$$
$ var nuc-do-cost  x var living

This type of graph is drawn continuously from left to right, one column
a step.  I call this type `continuous display'.

The last line gives you the meaning of the used characters:
`$' means how energy much a cell looses for each life step.
`x' shows how many 'cells' where living last step.

You can see population control at work in this example:

Population increases rapidly at the beginning until population control
raises life costs. Then population size starts to oscillate (and would
probably stabilise more or less after a short time).


Automatic zooming when the range is too small is indicated by
colouring the char in question different than usual. Number and type
of displayed variables, zoom factor, chars, colors and ranges are all
configurable of course.

This type of statistical display can deal with a number of variables,
but also with minimal, maximal and average values of variable groups
in nucs or spots, or display the size of the current range of them.

You can track as many variables as you want in this graph at the same
time, but you can only have *one* continuous display screen region.




File: brew.info, Node: ASCII bar graphics, Next: Text display, Prev: ASCII graphs, Up: Step display menu

ASCII bar graphics
..................

This type of display shows distribution of variable or function values
in a simple ASCII bar graph. The following example shows distribution
of genome generations, that is for how many generations the genome has
survived since last mutation:

                                           *
                                           *
                 *                         *
                 *                         *
                 *                         *
                 *                        **
                 *                *       ***
                 *               **      *****
                 **              ***    *******
      *         ****            ****   *********
*.. ..*.......*******.       ...*****  **********..
0           scanning: genome-generation            vertical range: 86      267

The name of the variable scanned is shown together with vertical and
horizontal ranges in the last line.

Here `genome-generation' gets scanned, horizontal range goes from 0
(left) to 267 (right) and vertical range is from zero to 86. Ranges
get zoomed in automatically if values fall out of displayed range. The
user get's notified in the middle of the bottom line if horizontal or
vertical zooming happens. Automatic zooming can be switched off, see
below.

This type of display is used both when scanning variables from a menu
or as real time display while brewing, when step display is on. In the
latter case it is redrawn completely after each step, and you can
display as many bar graphs on the screen as you want, but of course
they will get too small if you define too many of them.


The menu interaction is very similar in both cases:

If you select a column in a scan display you get access to information
about nucs or spots inside the value range of the selected bar. (You
can define a range of columns by pressing `*' on the range borders
inside a scan bar graphic. When the range is displayed press
`<RETURN>' to go to the corresponding subset menu). Brew puts you into
a `Menu nuc subsets' or `Menu spot subsets' respectively with
conditions set for the value range and the variable in question. From
here you can look at the nucs or spots, scan or even change them.

*Note Menu nuc subsets::. While you have all the possibilities of the
subset menus please note that your settings of conditions or actions
are volatile and will disappear once you leave the menu (while they
are persistent if you enter a subset menu the ordinary way).

The bottom line of a scan display can be used to switch between
automatic zooming of the horizontal display range and fixed display
range. Automatic zooming is practical but can make you quite nervous
when you watch it in real time. Toggle between the two modes by
selecting the center region of the line, where brew shows you when
zooming happens. If brew displays a fixed range of a scan the border
slices gather all values that are below or above displayed range. Set
border values at left or right end. This implies automatically
switching to fixed range display. Select `<fixed>' in the middle of
the status line to switch back to zoom mode.

You can also select the variable in question from the status line.




File: brew.info, Node: Text display, Next: Menu step display, Prev: ASCII bar graphics, Up: Step display menu

Text display
............

Text display shows minimal, average and maximal values of nuc or spot
variables. Each variable is shown in one text line and updated in real
time after each time step. You don't see much details, but then it
uses only one line of screen area. So you can display at least some
information about a few variables without using up much display space.

In the following example you see two nuc variables `code-cost',
`energy' and one spot variable `food':

code-cost               min: 400          max: 3799         average: 994
energy                  min: 500          max: 1328         average: 724
food                    min: 0            max: 1468         average: 233

Number and type of displayed variables is run time configurable like
always.




File: brew.info, Node: Menu step display, Next: Menu continuous display, Prev: Text display, Up: Step display menu

Menu step display
.................

You can combine above display types each one taking his own screen area.
This node assumes you know about the different types.
(*Note ASCII graphs:: *Note ASCII bar graphics:: *Note Text display::)

You can have *one* continuous display (displaying several variables)
and as many scan displays (bar graphs) and text display lines as you
want. For technical reasons brew distinguishes between
`nuc-scan-display' or `nuc-scan-func-dspl' and `spot-scan-display' and
between `nuc-text-display' and `world-text-display'. Configuration is
the same though.

Continuous display configuration is more complex and has it's own sub
menu *Note Menu continuous display::.

Step display menu lets you configure how many items of what kind you
want to be displayed (continuous display counting as one) and how many
lines of the screen each item should occupy.

The easiest way to add or remove an item is to select `add new item'
or `remove last item'. You will be guided through the configuration.

An entry for a displayed item might look like this:

nuc-scan-display    scanning: energy            lines:  12  v-range: 205

* The first item indicates the type of statistical display:

Name:                   class:      type:                               
nuc-scan-display        nuc         value distribution bar graph        
nuc-scan-func-dspl      nuc         function value bar graph            
spot-scan-display       world       value distribution bar graph        
nuc-text-display        nuc         minimum, maximum, average as text   
world-text-display      world       minimum, maximum, average as text   
continuous-display      both        value graph                         

* The second item is the variable (or function) name

* `lines' configures how many screen lines this display item will take
up.

* `v-range' is the vertical range. No need to initialise it normally.
Brew will take care about.


With `o' or by selecting `More infos'/`Less infos' respectively you
can toggle step display menu between two modes showing more or less
infos. While in the first mode an item occupies one line in the menu
it occupies up to three lines if more (less frequently used) info
get's displayed:

nuc-scan-display    scanning: energy            lines:  12  v-range: 205

nuc-scan-display    scanning: energy            lines:  12  v-range: 205
                    zoom starts horiz: 1/5      vertic: 1/4
                    bg color: blue              fg: default-color


Statistical bar graph display does automatic zooming: If values fall
outside displayed range horizontal or vertical scale will be adapted
to let all values fall inside. If too little of a range is occupied
brew will zoom up. The horizontal and vertical zoom start values
indicate how much of a range must be used (*Note Scale input::). So if
you set horizontal zoom start value to 1/6 and the values would use
less than that amount of screen width brew zooms up to fill the
screen. Zooming is indicated in the bottom line like this: 500
scanning: energy -<zooming>| vertical range: 52 1366 The '-' and '|'
left and right the word '<zooming>' indicate horizontal and vertical
zooming. So in this example both took place.

* The third line defines background and foreground colors.


Configuring text display items is trivial, so it's not covered here.


Configuring continuous display is done in it's own sub menu.
*Note Menu continuous display::.


If you see a green text similar to this one: fill the screen (7 lines
unused). you can select it (or press `f') to adapt item sizes to use
the whole screen, or set the individual step display item sizes
manually.


`presets' *Note Step display presets::, for often used templates.




File: brew.info, Node: Menu continuous display, Next: Step display presets, Prev: Menu step display, Up: Step display menu

Menu continuous display
.......................

This menu configures so called `continuous display'.
This type of simple graph displays a coloured char for a certain value
after each time step.  Let's say it would display average energy of all
living nucs. Then it would draw a char (let's say 'e') after each step
which would be higher up on the screen when more cells are living.
Please have a look at the example before reading this node
(*Note ASCII graphs::).

The menu might look similar to this:

Setup continuous display:

nuc-average     energy          *  red          low: 98         high: 160
nuc-max         energy          +  red          low: 0          high: 7006
get-variable    living          x  white        low: 0          high: 1920
spot-range      A-quality       A  green        low: 0          high: 1000

add new entry

Zoom up scale: 2/1


Probably you can guess what this would do:
   * 'A red *' shows the average energy level of all living nucs.
   * 'A red +' shows the maximal energy level found in all living nucs.
   * 'A white x' indicates population.
   * 'A green A' shows the range (that is the absolute difference between
     maximal and minimal value) of spot value `A-quality' over all spots
     of the current world.

You can select the type of the displayed value from the following list:
name:             kind:             value:                              
(none)            --                no selection                        
get-variable      various           variable value (see below)          
nuc-min           nuc               minimum                             
nuc-max           nuc               maximum                             
nuc-range         nuc               range                               
nuc-average       nuc               average                             
spot-min          spot              minimum                             
spot-max          spot              maximum                             
spot-range        spot              range                               
spot-average      spot              average                             

Type `get-variable' displays the value of a single global variable,
while the others display functions like average or range of groups of
variables of all living cells (nucs) or of all spots.
The single variables that `get-variable' can treat are:
living       how many cells currently alive
newborn      how many cells created in this step
cloned       cloned cells since start of evolution
died         how many cells died this step
nuc-do-cost  energy cost of one life step
code-price   energy cost of one code length unit
selected     number of selected cells

Defining char and color is trivial.

`low' and `high' defines the display range. No need to initialise them
normally. Brew will take care about.

`Zoom up scale' sets the zooming scale applied when a value falls out
of range (*Note Scale input::). Note that continuous display can only
zoom up, but not in the other direction. It cannot know in advance how
much or how little the value in question will change during next
steps. So it just adapts scale such that the value does fall into
display range, without resetting it later on. Of course you can always
do that yourself by hand setting `low' and `high'.

Use `add new entry' to add a new entry.




File: brew.info, Node: Step display presets, Prev: Menu continuous display, Up: Step display menu

Step display presets
....................

Planed to give some often used display configurations.




File: brew.info, Node: Info line, Prev: Step display menu, Up: Display menu

Info line
---------

Regardless whether you have step or spot display on you can display
some values on the bottom line of brew main display. The bottom line
is divided in a number of `display-slots'. So if you have five slots
you can display up to five values.

Configurating info line is trivial:

1) Select number of slots first (you can change it later on).

2) Select the information you want for each slot from the following
list:

noop                 no selection, nothing displayed
.step                display step number
.cells               display how many cells created since start of time
.burden              how much energy is needed for one life step
.code-price          energy price for a code length unit
.living              number of currently alive individuals
.selected            number of selected individuals
.newborn             newly born cells this step
.died                died cells this step
.trial               number of cells with genomes currently on trial
.mutations           number of mutations this step
.compiled-genes      successful genes compiled since start of time
.mutation-max-items  maximal ever generated code length
.age-threshold       maximal possible age (not very useful normally).
.scoring             show scoring (no taxes) of best scored individual.
.score               show best score after paying taxes.
.hits                count individuals that get scoring 0
                     (assuming scoring 0 means problem solved, somehow).


`messages'
Sometimes brew uses the bottom line to give you messages it considers
important. These messages will override your settings for a number of
steps. They can be about memory shortage, population emergencies,
extremely long genes (which very likely are a consequence of unbalanced
gene pools) and such.




File: brew.info, Node: Color menu, Next: Menus menu, Prev: Display menu, Up: Users manual

Color menu
==========

Brews world display can give more information by using colors.
So the color of the char symbolising a cell could code it's age
while background color could show how much food is on this spot.
These things are configured in the color menu, which you reach
from brews main screen by pressing `C'.

Please note that spot display has to be on for this, for step display
you can only switch colors on and off here. Other step display color
settings are done where step display items are configured.

Nuc related data is always mapped to *foreground* colors, while spot
related information will influence *background* color. It's quite
logical, if you think about it for a moment.


Color menu starts with a row of color samples. If you select them, the
colors name gets displayed, which can help recognising them elsewhere.

Switching foreground and background colouring is done by selecting the
corresponding entries, or (more convenient) by pressing `f' or `b'
respectively. Please note that these key bindings are the same as in
brews main screen.

Pressing capital `F' or `B' lets you select the function to code
information to colors. As usual you can also have a look at the
definition of the functions to choose (*Note Selecting functions::).

Foreground colors can be set by the following nuc dependent functions:
black                       you won't see black on black ;-)
red                         just fixed colors
green
brown
blue
magenta
cyan
white
default-color               white as foreground, black as background
condition>fg-colour         conditional colouring
                            (*Note Conditional colouring::).
selected>fg-color           selected cells get coloured
age>color                   mapping age to color
generation>color            mapping generation to color
genome>color                genome determines color
genome-generation>color     generation of genome determines color
code>color                  color shows code length
scoring>color               color coded raw scoring results
score>color                 score respecting code length penalty
trial>color                 cells on trial phase are shown coloured
                            (*Note Trial phase::).
nuc-all-real>color          color nucs with real floating point values only
nuc-has-unreal>color        color nucs with unreal floats (infinities, nan's)
nuc-inf?>color              color nucs with infinities of both signs
nuc-neg-inf?>color          color nucs with negative infinities
nuc+inf?>color              color nucs with positive infinities
nuc-nan?>color              color nucs with nan's

Background colors can be set by the following spot dependent
functions:
black                       don't choose black on black ;-)
red                         just fixed colors
green
brown
blue
magenta
cyan
white
default-color               black as background, white as foreground
condition>bg-colour         conditional colouring
                            (*Note Conditional colouring::).
selected>bg-color           EXCEPTION: selected NUC colors background
scoring-hit>bg-color        EXCEPTION: a NUC scoring zero colors background
fcp>color                   watch memory allocation of the OS
food>color                  show food color map
A-quality>color             and for all other spot qualities
A-property>color            same for all spot properties
A-secret>color              and for all spot secrets, if any
spot-all-real>color         colour spots without unreal float values
spot-has-unreal>color       colour spots having unreal float values
spot-inf?>color             colour spots with infinities of both signs
spot-neg-inf?>color         colour spots with negative infinities
spot+inf?>color             colour spots with positive infinities
spot-nan?>color             colour spots with NANs


In all cases where a value range should be mapped to colors we need a
scale to do the mapping. If the range of values is too big, the colors
will just wrap. So the same color does not necessarily mean a similar
value. You can set the different scales by hand, or select the menu
entries that try to set the scale such that either the whole color
range gets used, just the half range gets used, or only two colors.
The first case is good if the range is likely to stay equal or will
probably shrink. The other cases are for situations where the value
range is likely to grow some or grow much. Adapt color scales from
time to time (if you use them) not to get fooled by excessive color
wrapping.


Some useful key bindings in color menu:
   * `f' Toggle foreground color.
   * `b' Toggle background color.
   * `F' Set foreground color coding.
   * `B' Set background color coding.
   * `c' Calibrate background color scales to full color range.
   * `h' Calibrate background color scales to half color range.
   * `2' Calibrate background color scales to use 2 colours only.


*Note Scrolling menus::.


* Menu:

* Conditional colouring::       User defined colour conditions.       



File: brew.info, Node: Conditional colouring, Prev: Color menu, Up: Color menu

Conditional colouring
---------------------

Brew comes with pre-defined functions to code informations by colours.
Sometimes you might want to define your own conditions. From `Color
menu' select `condition>fg-colour' for nuc variables, respectively
`condition>bg-colour' for spot variables and then `EDIT' to go to
`Conditional colouring menu'.

*Note Extended conditions::, to learn how to set up colour conditions.

You can also set colour conditions from `world maps' by pressing `c'.
Brew sets up colouring like it is used in the current map if you do
so. (*Note World map interaction::).




File: brew.info, Node: Menus menu, Next: Individuals menu, Prev: Color menu, Up: Users manual

Brews super menu.
=================

Brews super menu is just a list of all globally accessible menus.
You get there by pressing `B' or `m' from the main screen.

It's an interface meant for browsing all the options or when you don't
know the key binding to go to a certain menu directly. I advice you
strongly to get used to the key bindings though, as they are much more
convenient. All menus have upper case key bindings in brews main
screen. There are a few lower case `shortcut' key bindings too, but
there is always an uppercase binding, anyway.

Note that there are menus which you can not access directly neither
from brews main screen nor from here. These menus deal with a
individual instance of a group of things like spots, nucs, genomes and
such. Brew can not know which instance you want to work on. You have
to select it first in another place. Please read *Note Using menus::.

   * `menu Individuals'. Select and edit predefined individuals to
     release in the world. *Note Individuals menu::.

   * `menu System'. Configure system wide options. *Note System
     menu::.

   * `menu World'. Configure world wide options. *Note World menu::.

   * `menu Worlds list'. Select a world and enter, configure world
     names and the like. *Note World list menu::.

   * `menu global Variables'. Simplest type of variables visible to
     genomes. *Note Menu global variables::.

   * `menu Mutation'. Configure mutation. *Note Mutation menu::.

   * `menu Diversification'. Configure nuc and spot variable
     diversifications. *Note Diversification menu::.

   * `menu Gene pools'. Select gene pool. *Note Gene pools menu::.

   * `menu Actual pool'. Configure actual gene pool. *Note Actual pool
     menu::.

   * `menu Current Genomes'. Examine different currently living
     genomes. *Note Menu current genomes::.

   * `menu Population control'. Configure population control. *Note
     Population control::.

   * `menu Food'. Configure food supply. *Note Food menu::.

   * `menu Elite'. Current score list of the individuals. *Note Menu
     elite::.

   * `menu Scan nucs'. Gather statistical informations about all nucs.
     *Note Scanning nucs::.

   * `menu Scan world'. Gather statistical informations about all
     spots. *Note Scanning spots::.

   * `menu Select nucs'. Select or de-select nuc subsets. *Note Menu
     select nucs::.

   * `menu Nuc Subsets'. Do something on all nucs meeting a certain
     condition. *Note Menu nuc subsets::.

   * `menu Spot Subsets'. Do something on all spots meeting a given
     condition. *Note Menu spot subsets::.

   * `menu Display'. Configure display of brews main screen. *Note
     Display menu::.

   * `menu Color'. Configure colors in brews main screen. *Note Color
     menu::.

   * `menu Step Display'. Configure brews main screens display when in
     step display. *Note Step display menu::.

   * `menu Continuous Display'. Configure step ASCII graph display
     called `continuous display'. *Note Menu continuous display::.

   * `menu Log files'. Configure writing log files. *Note Log files
     menu::.

   * `menu Code files'. Configure writing generated Forth code to a
     file. *Note Code file menu::.

   * `menu Record Playback'. Record your interactions with brew or
     replay your session. *Note Record and Playback::.

   * `menu Function Keys'. Configure function key bindings. *Note Menu
     function keys::.

   * `menu Demos'. Some demos. This brew version does not have much
     here, as things change too quickly during this development phase.
     You are welcome to send me your own experiments as demos. *Note
     Menu Demos::.

   * `menu Big Bang'. Create a new world. *Note Big Bang menu::.

   * `Manual'. Call the external manual reader on top node. *Note
     System menu::, for how to switch between using info reader or
     html browser.




File: brew.info, Node: Individuals menu, Next: Nuc menu, Prev: Menus menu, Up: Users manual

Individuals menu
================

You reach the individuals menu by pressing `I' from brews main screen.
This menu lets you select from a list of predefined individuals.

You can edit the selected individual as you wish and set it somewhere
in your brew universe. This menu has it's main function when you set
up a new evolution. You can add new individuals to a biotope later on
of course, if you decide to do so. (You might be surprised how
difficult it is to do so successfully, when the other cells are
already somehow optimised to the given conditions though).

Press `i' to select an individual from the list.
Press `e' to examine and edit it as you like.

If you return to the main screen now you can set clones of this
individual by pressing `<RET>' on a spot. Brew displays `Clone nuc by
selecting an empty spot' at the bottom line to let you know. You could
edit each clone again, of course. This possibility is lost as soon
brew gets confused which individual you might mean. Just select and
edit it again to continue then.

If you want to randomly sow a number of clones use the function
presented in the menu (`c'). There is a variant which diversifies
diversificable nuc variables of each sown clone (`d'), making them a
bit different, which is usually a good idea to start an evolution.
*Note Diversification menu::, to configure variable diversification.

Please note that brew does try but not *insist* to sow as many cells
as you tell it to. If a cell falls on a spot that is already occupied
it will be lost, like a seed falling on infertile ground.

Of course you can select a first individual, set or sow it, select
another one (or edit it differently) and set some more if you want to
start with more than one species. Don't forget to make them look
different so you can *see* what's happening with them.




File: brew.info, Node: Nuc menu, Next: Edit spot menu, Prev: Individuals menu, Up: Users manual

Nuc menu
========

This menu screen gives you detailed information about a individual cell
and let's you edit it. You reach this menu by selecting a nuc in brews
world map (world display) or from individuals menu. Editing a nuc changes
only this single cell of course.

Most of the menu items refer to variables local to the nuc. Brew let's
you edit all of them (with very few exceptions), even if it thinks
it's a bad idea. Changing some variables like the ID of the cell could
confuse brew. So brew warns you by ringing the bell when you try to do
so, but does not prevent you from doing it (except in some really
dangerous cases).

Going through the menu from top to bottom:

   * `wake-me'. This is the cells genome. It get's executed when the
     cell is woken up. Look at the definition of the code by selecting
     it's name (*Note Selecting functions::). This code get's mutated
     by the mutation process. Normally you will probably start a
     evolution with `noop'.

   * `<name>'. The genomes name or the information that this genome is
     on trial. Selecting it will let you examine or edit the genome.
     (*Note Gene edit menu::).

   * `.gene-info'. Gives you some information about the cells genome.

   * `select'. Selecting a cell just sets a certain flag in it's data.
     The flag is hereditary. You can use the flag to mark a cell to
     look at it's offspring. You can also mark groups of cells (from
     other menus) and do something with all selected cells, or just
     display them coloured. *Note Menu select nucs::, for more
     information.

   * `eat'. 'Eating' in brew mens getting energy. The eat function is
     the place where scoring takes place. It's a bit like animal
     training: Individuals that behave 'better' get more food. The
     cells can not see or change this function, only you can.

   * `score'. Raw scoring result without code taxes.

   * `reproduce'. Select the way the cell reproduces. Currently only
     `cell-division' is implemented, so you don't have much choice....

   * `show-me'. Select a function determining how the cell will show
     up in the world map. *Note Show me functions::, to see what is
     available.

   * `nuc id'. Each nuc has a unique identification number. It helps
     identifying it in log files. Normally it is not a good idea to
     change it.

   * `genome id'. Each genome has it's unique identification number.
     It helps identifying it in log files. Normally it is not a good
     idea to change it.

   * `code cost'. The longer the gene code, the higher the code cost.
     You can edit this value, but it will be recalculated by the
     mutation process as soon as the genome gets mutated next time.
     Your value has no longer any influence on the mutated genomes
     code cost then.

   * `nuc length'. Length of the nucs data structure. You cannot
     change this here.

   * `age'. The age of the cell in time steps. You can edit it if you
     want to cheat for some reason.

   * `age limit'. A nuc will die at the latest when he will get older
     than this maximal possible age.

   * `generation'. The cells generation since start of this evolution.

   * `genome gen'. Generation of this genome since last mutation.

   * `energy'. Amount of 'energy' the cell has available. A cell dies
     if it has no energy left and can reproduce if it's energy level
     surpasses `reproduction energy'. Energy is received through
     `eating' which will give more or less energy depending on how
     well the cell has solved it's task and on how much food there is.
     Each live step costs energy and gene code length does too. These
     values are used for `population control'. A mother cell passes
     it's energy on to the children, equally dividing it to give each
     one it's share.

   * `char'. If you set `show me' to `show-ascii' this char will be
     shown to symbolise the cell in spot display. Otherwise it has no
     influence at all.

   * `reproduction energy'. Energy level a cell must reach to be able
     to reproduce. Some other conditions (depending on `world mode' or
     `linear mode' respectively) must fit for successful reproduction.
     Energy is divided equally among the children. Nuc variables can
     get diversified and the genome can get mutated when a cell
     reproduces.

   * `Integer/Floating point Nuc variables'. The following screen area
     is dedicated to the nuc variables of all the different classes.
     Switch between INTEGER or FLOAT variable display (use `o', like
     usual). In the case of floats the menu further let's you choose
     between VISIBLE (to mutation) or HIDDEN variables (Please read
     *Note Variable names::).

     The number of nuc variables of each kind is configured at compile
     time. If there are more than fit on the screen the area where
     they are displayed will be scrolling (*Note Scrolling menus::).

   * `diversification'. Organs, parameters and invisibles can get
     diversified. There are two bitmasks to switch that on or off for
     each individual variable: a global one and a nuc individual one.
     A variable can only get diversified if both masks are on for it.
     Here you set the mask `my-diversifctn-mask' local to this nuc
     only. You will see the letter indices for each variable class.
     Lower case letters mean diversification is off, upper case means
     on. Brew lets you switch diversibility of the variables you have
     chosen above to be displayed. Please note that the mutation
     process automatically sets all the bits of this mask (but not of
     the global one) of which the variables in question get used by
     the genome. Mutation does not reset these bits, if the variables
     are not used any more. This is not a bug, it's part of the play.

   * `sow' and `sow diversified' work like from individuals menu
     (*Note Individuals menu::).

   * `remove cell' takes this cell out of the play.

   * `SPOT' let's you examine and edit the spot the nuc is on.




File: brew.info, Node: Edit spot menu, Next: Menu global variables, Prev: Nuc menu, Up: Users manual

Edit a single spot
==================

You will not want to examine or edit a single spot too frequently,
but here is a menu to do it anyway.

You reach this menu from brews main screen by pressing `l' on an empty
spot. (Pressing `<RET>' will have the same effect most of the time).
If the spot is occupied by a cell you can get here from the nuc menu
by selecting `Spot' therein.

You can see and edit either the different INTEGER or FLOAT spot
variables.

*Note Variable names::, for information about the different variable classes.
*Note Numeric input::, how to use Forth power in input.
*Note Float input::, let's you use everydays float syntax on input.
*Note Scrolling menus::, scrolling menus.




File: brew.info, Node: Menu global variables, Next: Food menu, Prev: Edit spot menu, Up: Users manual

Global variables
================

This menu let's you see and edit global integer or float variables.
You get here from brews main screen by pressing `V'.

These variables are the simplest type of environment variables.
Normally you will give the genome read only access to them,
if you use them at all.

You can see and edit either the different INTEGER or FLOAT global
variables. Key `o' toggles as usual.

To set them all to the same value, set the first one and select
`set them all to this value'.

To configure diversification of global variables use the link to
*Note Diversification menu::.

*Note Numeric input::, how to use Forth power in input.
*Note Float input::, to use everydays float syntax on input.
*Note Scrolling menus::, scrolling menus.




File: brew.info, Node: Food menu, Next: Population control, Prev: Menu global variables, Up: Users manual

Food menu
=========

The cells need `energy' to survive and to reproduce.
They get energy by `eating' `food'.

Population get's controlled by two means:
   * Limiting food supply.
   * Adapting `energy costs' for each life step and for code length.

This menu is for food supply configuration.
You get here by pressing `F' in brew main screen.


Food portions are given once a evolutionary time step.
There are different ways to distribute food:

   * `World food supply'. This food amount is equally divided and
     shared amongst all living cells. It is a good help to control
     population size. But if you depend too much on it population size
     will oscillate very much, which might be problematic.

   * `Individual food share'. Each living individual get's this much
     food extra. This works against stabilising population.

   * `Food share on spot'. Food is deposed on spots where it remains
     until a cell eats it up there. Food accumulation on empty spots
     leads to moving cell cultures. Apart from a more interesting look
     in world view this has a stabilising effect on population size
     and influences the development of evolution. Food deposits on
     empty spots postpone the effect of population control measures,
     which stabilises oscillations to some degree. The influence on
     the course of evolution is complex.

   * `Feed world manually'. Sometimes you want to give a extra food
     portion to all spots and all cells.

   * Food menu let's you access some other functions you are likely to
     use to choose useful input, like scanning all spots and all nucs
     or configuring costs. These are just duplicate interfaces to
     functions explained elsewhere.




File: brew.info, Node: Population control, Next: Diversification menu, Prev: Food menu, Up: Users manual

Population control
==================

Evolution only will lead to useful results if there is some sort of
life stress that controls which genomes will survive and which will
not.

This menu let's you configure population control. You get here by
pressing `P' in brews main screen.

This brew version has two different ways of doing it:

* Menu:

* Eat and consume::             Get paid by results, pay taxes, consume energy.
* Elitism::                     Only the best individuals will survive.
* Menu elite::                  Current score list of the individuals.



File: brew.info, Node: Eat and consume, Next: Elitism, Prev: Population control, Up: Population control

Brews pseudo biological mode
----------------------------

Brew stresses it's little 'beings' by two means:
   * Limiting food supply.
   * Adapting `energy costs' for each life step and for code length.

This menu is for configuration of automatic adaption of energy costs.
It's a mean automatic stress producer!

Separing costs for gene code length and life steps gives you a
convenient way of controlling length of generated code.

Population control menu also deals with population emergencies.


Let me explain some technical terms first:

   * `High water mark', `Low water mark'. If population crosses these
     limits brew will automatically increase or decrease life stress
     in order to stabilise population in between them.

   * `Stress additive step'. Stress amount added (or subtracted) to
     the current stress when population is out of bounds.

   * `Stress rate'. Rate the current stress is multiplied (or divided)
     by when population is out of bounds.

   * `Population flood'. Population has crossed a critical limit. Brew
     takes drastical measures to decrease it.

   * `S.O.S.'. Population has fallen below a critical limit. Brew
     takes a number of drastical measures to save the population from
     dying out.


Configurating possibilities:

   * `Live stress, additive step'. Amount of additive live stress
     change when population is out of bounds.

   * `Stress rate'. Multiplicative live stress change when population
     is out of bounds (*Note Scale input::).

   * `Code price, additive step'. Amount of additive stress adaption
     (dependent on code length) when population is out of bounds.

   * `Code price rate'. Multiplicative stress change (dependent on
     code length) when population is out of bounds (*Note Scale
     input::).

   * `High water mark'. Beyond this limit brew will increase stress to
     keep population down.

   * `Flood-mark'.
     Beyond this limit brew will take drastic measures to cut population down.
     Brew will issue a message to you if that happens.

   * `Flood stress rate'. Multiplicative stress rate applied in case
     of population flood emergency (*Note Scale input::).

   * `Flood energy rate'. In case of population flood emergency the
     energy level of each living cell will get multiplied by this rate
     (*Note Scale input::).

   * `Flood food rate'. In case of population flood emergency
     population control will multiply all food rations (world food
     supply, individual food share, share on spot) by this ratio.
     (*Note Food menu::, *Note Scale input::). This measure should
     have a lasting effect on population size.

   * `Flood kill rate'. As a measure to have a immediate effect brew
     can remove a certain ratio of all living cells on population
     flood emergencies. This does not remedy the problem of course.
     (*Note Scale input::).

   * `Low water mark'. Whenever population falls below this level brew
     will automatically decrease stress to let the population grow
     again.

   * `Low water mark is active after step'. If you start an
     evolutionary experiment you are very likely to start with very
     few individuals, very often only a single one. You would not want
     brew to think this to be a population deficiency or population
     emergency. So population upwards regulation is set on hold for a
     number of time steps in the beginning. This also tries to force
     you to set up your experiment with somehow useful defaults, such
     that it can survive the start of the evolution without the help
     of population control. You would hardly get useful results out of
     a setup that wouldn't be able to start on one's own. Setting an
     experiment up in such a way is admittedly not always trivial. You
     might have to try out a bit, but it's worth the effort.

   * `Additive release'. Up regulation of population is done more
     rigidly than down regulation trying to avoid population
     breakdowns. This is the *factor* applied to additive stress
     change (applied as stress release, of course). Additive stress
     release will apply whenever population is less then the low water
     mark.

   * `Multiplicative release'. This is the *factor* by which
     multiplicative population regulation is stronger when applied
     upwards than downwards. (See last entry).

   * `SOS mark'. If population falls below this mark brew gets very
     alarmed and will apply very drastic measures to prevent the
     population from dying out completely. Brew will issue a message
     to you if it happens. Try to set up your experiments in a way it
     does not happen.

   * `SOS release rate'. In case of population breakdown emergency
     brew will apply this multiplicative rate to release both live
     stress and stress depending on gene code size. The additive
     stress steps also get adapted to the new situation depending on
     this rate (*Note Scale input::).

   * `Reproduction energy'. To push reproduction (on population
     breakdown emergency) brew will add the energy amount needed for
     reproduction multiplied by this factor to each living cells
     energy supply. This is emergency help only, not really solving
     the problem.

   * `SOS sow'. To have an immediate effect as emergency help on
     population breakdowns brew can sow clones for each living cell.
     This value determines the number of clones that will be spread
     over the world for each living individual.

   * `Current energy cost of each life step'. Current result of the
     above regulation process. Of course you can edit it by hand, but
     population control will continue to change it on his own behalf.
     It will start with your value at least.

   * `Can this 'cost' become a source of help in emergency
     situations?' When this is switched on, the stress can become
     negative. This can help in emergency situations. It can produce
     strange results sometimes, like genomes growing enormously when
     rating negative on gene code length. This does not happen too
     often, though.

   * `Current energy cost of code usage'. Current result of the above
     regulation process regarding gene code length regulation.

   * `rating scale'. Fixed scale not touched by population control to
     configure the weight of gene code length on applied stress (*Note
     Scale input::). If this rate is zero, code length will have no
     influence at all on applied stress. You can even set it negative
     for a short time, to let genomes grow. Then you carefully reset
     it to a small positive value and let mutation cut out all the
     useless code fragments. This can help mutation sometimes to find
     new survival tricks ;-)

   * `Scoring rate'. This is a third possibility to regulate
     population and to influence the course of the evolutionary
     process. Newer eating functions do their scoring more or less
     strictly depending this rate. So you set it large to start with,
     giving mutation a chance to try out ineffective gene code,
     setting it harder, when mutation *has* produced helpful code. You
     have to regulate this by hand, as population control does not use
     it automatically (yet?). Please note that not all eating
     functions do use it at all. (*Note Scale input::).

   * `Food supply'. As food supply is the other tool to regulate
     population you will find a link here. *Note Food menu::.





File: brew.info, Node: Elitism, Next: Menu elite, Prev: Eat and consume, Up: Population control

Elitism: only the best will survive
-----------------------------------

This more traditional way of population control works much more simple
and much more drastic: The cells get scored after each life step. Only
a fixed number of the fittest of them are kept, the others removed.
Population is filled up with mutated variations of the elite. Cells
are potentially immortal if they manage to stay in the elite.

   * `Population size'. This mechanism of population control tries to
     keep population at a fixed size. Note, that the actual population
     will often be smaller, because not all cells might have found a
     free spot for their offspring.

   * `Kept elite'. Number of the fittest individuals kept in the
     population. They will get used as base for mutations to fill up
     population to the desired size.

   * `Code price scale'. Scale for the gene code length to go into the
     scoring function.




File: brew.info, Node: Menu elite, Prev: Elitism, Up: Population control

Score list of individuals
-------------------------

This menu displays the list of individuals sorted by their score.
You get here from brews main screen by pressing `E'.

This brew versions only has a very simple informational menu here.


The possibility to see (or edit) each individuals genome is the only
additional menu option given. Later brew versions will probably let
you do more...




File: brew.info, Node: Diversification menu, Next: Mutation menu, Prev: Population control, Up: Users manual

Diversification menu
====================

The trick of evolutionary programming is to let the 'children' of a
code snippet you want to optimise be variations rather then exact
copies of the original. This is not only true for gene code, which
would be changed through `mutation', but also for nuc intern
(hereditary) variables, which are varied by `diversification'.

Later on I have found the diversification mechanism useful not only to
optimise inner variable values, but also to set up *input* for some
experiments. So I extended the possibilities of diversification on
spot variables too.

Sometimes it's unnecessary complicated to have these input variables
as local variables (to the spot or nuc), so I introduced a set of
global variables, which can get diversified too, for convenience.

`Diversification menu' sets up the parameters for diversification.
You reach it by pressing `m' and then `d' from brews main screen.

The first line tells you if you are looking at NUC, SPOT or GLOBAL
variables diversification. `o' cycles through them, like usual in such
situations.

The mechanism work similar, but not equal:

   * Diversification of NUC variables is only done when a nuc
     reproduces, and only in a certain rate of cases.
     (`diversification rate'). The values are never touched again by
     diversification during the whole life time of the cell. The
     values at time of reproduction will be passed on to the children,
     possibly diversified again. So a child will probably start with
     similar values as the mother cell had.

   * Diversification of SPOT variables however takes place every time
     the spot get's 'called' during evolution. (Well you can restrict
     it to inhabited spots only, if you want). As it is usually used
     as input for the task of a evolutionary experiment the value will
     change with every new life step. A child will very likely find
     values very different from the ones at the spot the mother cell
     lived.

   * Diversification of GLOBAL variables is done once a time step,
     before cycling through all spots of the current world.

Let me explain two technical terms which play a role in all cases:

   * `Diversification range'. This is the maximal possible deviation.
     Diversification will take a random value between zero and this
     value (inclusive) and add or subtract it from the original value.

   * `Diversification closeness'. In fact the value is run more than
     once through the random function. So if you set this value two a
     (small) positive integer > 1 big deviations will get less
     frequent. A value of zero is legitimate (but rarely useful) and
     means, that deviation will always be full positive or negative
     range.

   * `relative'. Diversification of floating point values (not for
     integers) can be done relative by factor. The diversified value
     will be multiplied or divided by a value up to this factor.

   * Of course all the above is only true for variables where
     diversification is switched on at all.


* Menu:

* NUC diversification::         Diversification of NUC local variables.
* SPOT diversification::        Diversification of SPOT local variables.
* GLOBAL diversification::      Diversification of GLOBAL variables.


*Note Scrolling menus::.




File: brew.info, Node: NUC diversification, Next: SPOT diversification, Prev: Diversification menu, Up: Diversification menu

Diversification of NUC variables
--------------------------------

Here you configure diversification of NUC variables:
Beside normal diversification you can configure rare big deviations too.

Upper screen half is for integer nuc variables, lower for floats.
They work very much alike. Please note that not only the diversified values,
but also the parameters for diversification are integers or floats themselves.

   * `Rate'. If rate is set to 1/4 diversification will be done on
     every 4th reproduction, statistically speaking of course. (*Note
     Scale input::).

   * `Range'. Maximal possible deviation in each direction.

   * `Relative'. Maximal factor/divider (only for floats).
 
   * `Closeness'. The bigger this value, the less big deviations.

   * `Sporadic'. (Usually much smaller) rate of sporadic big
     deviations. (*Note Scale input::).

   * `(sporadic) Range'. Range of sporadic deviations. Usually much
     bigger than normal diversification range this allows rare *big*
     value changes. This can be helpful to find isolated islands in a
     value map.


The rest of the menu lets you set the bits for the global diversification
mask for each nuc diversificable variable.
*Note Variable names::, for info on these variables.

Only variables with global *and* individual switch on can get
diversified at all.




File: brew.info, Node: SPOT diversification, Next: GLOBAL diversification, Prev: NUC diversification, Up: Diversification menu

Diversification of SPOT variables
---------------------------------

The configuration of SPOT diversification is very similar to the one
for nucs. It has less options though.

Please refer to *Note NUC diversification::, for more infos.

Please don't forget that you must configure much smaller values here
for a similar effect due to the differences in the inner working of
spot and nuc diversification.

You can restrain spot diversification to inhabited spots. This might
be worth considering for speed reasons, spot diversification will be
done *very* often if you use it.




File: brew.info, Node: GLOBAL diversification, Prev: SPOT diversification, Up: Diversification menu

Diversification of GLOBAL variables.
------------------------------------

This feature is implemented as a convenience to allow an easy set up
of some simple experiments.

The configuration of GLOBAL diversification is very similar to the one
for nucs or spots.

Please refer to *Note NUC diversification::, for more infos.




File: brew.info, Node: Mutation menu, Next: Gene pools menu, Prev: Diversification menu, Up: Users manual

Mutation menu
=============

Here you configure options for the mutation process.
You reach it from brews main screen by pressing `M'.


   * `How often to mutate'. This rate determines in how many cases a
     cell reproduction will lead to mutation of the genome. (*Note
     Scale input::).

   * `Mutation TYPES'. There are different types and sub-types of
     mutation *Note Mutation types menu::. Here you can edit the
     relative probabilities of each type to occur. *Note Probability
     lists::.

   * `Stack turning point'. Genes are normal Forth words and do use
     the Forth stack of course. Mutation has to take care about stack
     balance (and does some primitive type checking too). This is used
     here to influence the possible complexity of the generated gene
     sequences. Mutation knows about the stack aim it has to reach
     regarding depth and stack types. When depth is more than 'stack
     turning point' items off the desired aim, mutation only uses
     genes that don't make it worth. Don't choose too big values or
     the generated gene code will be very different to understand and
     mutation might have difficulty to find to an end. Mutation
     normally terminates, when the stack aim is reached.

   * `Mutations threshold'. Most of the times the stack aim would
     already be reached without inserting any genes at all. So we have
     to insert something to let the process start. So 'stack turning
     point' and such is not respected before 'mutations threshold'
     gene items are inserted. Normally a very small number is best for
     that value.

   * `Size limit for genomes in items'. If the gene pool is not too
     much out of balance regarding stack types mutation should find to
     an end without building too long gene sequences, but you cannot
     be sure about. As evolutionary programming tries out literally
     hundreds of millions of mutations it could get stuck sooner or
     later in a endless mutation. If the gene pool is out of balance
     this will often be the case. So we have this upper size limit as
     a safety belt. If a mutation passes over limit, brew throws and
     restarts the mutation all over again. Brew issues a message about
     it, because it's not considered normal to happen.

   * `RING/quiet'. Switch ringing the bell in case of exceeding genome
     size limit (see above).

   * `Trial phase'. Length of the so called 'trial phase' in
     generations. Each newly mutated gene has to survive trial phase
     before it will get compiled and possibly be put into the gene
     pool. (*Note Trial phase::). Genes on trial will not be mutated
     further.

   * `Include produced genomes as genes'. If this is switched on
     generated genomes that survive trial phase get put in a genomes
     list. The relative probabilities get increased every time a cell
     with this genome is reproduced. The genomes can be used as genes
     or revitalised as genomes from now on.

   * `nuc bit masks'. Diversification uses bit masks in the nuc for
     which variables to diversify or not. Mutation changes these
     masks, setting a bit for each nuc user variable used by a genome.
     Old brew versions did (deliberately) not reset these masks, so a
     nuc variable continued to be diversified from the moment any
     ancestors nuc genome ever set it. The new genomes masks did get
     ORed with the nucs maps. Switching to `Set nuc bit masks
     absolutely' resets them after each mutation.

   * `Diversification of variables'. As mutation and diversification
     are similar processes there is a link to the diversification menu
     here. (*Note Diversification/Mutation::).


* Menu:

* Probability lists::           Pools of functions with different probabilities
* Mutation types menu::         Different types and sub-types of mutation




File: brew.info, Node: Probability lists, Next: Mutation types menu, Prev: Mutation menu, Up: Mutation menu

Probability lists
-----------------

At some places brew uses pools of functions with different relative
probabilities to be (randomly) selected. Examples are the different
types of mutations or gene pools. These `probability lists' can be
nested one into the other.

Example (mutation types):
mutation-types  items: 6    Edit relative probabilities.

1000    top-level-insertion
1000    top-level-replacement
3000    snip-types                      * nested list *
2000    top-level-address-replacemnt
1000    top-level-token-replace
100     restart-from-scratch

The values given in the first column are relative probabilities to get
selected by the random selection mechanism. This means that when a
mutation type will be used the first two types will have the same
relative probability to be chosen, while `snip-types' will be three
times as frequent and so on.

Note that `snip-types' will recurse on the nested probability list
when taken, to determine the final winner. Nesting levels are not
limited.

You change relative probabilities by selecting the entry.

In the case of nested lists you select just like the other entries to
determine the relative probability that (any) one entry of the nested
list would be chosen. To descend one level and set the relative
probabilities *within* the nested pool, select `* nested list *'.

The absolute size of the probability values has no influence only the
relative size has meaning and only within the current nesting level.

Selecting the name of an item shows you it's definition.

Depending the number of items this menu is likely to be a scrolling
one (*Note Scrolling menus::).




File: brew.info, Node: Mutation types menu, Prev: Probability lists, Up: Mutation menu

Mutation types menu
-------------------

There are different mutation types (and sub-types).
Here you configure relative probabilities of each type to happen.

   * `top-level-insertion'. This mutation type inserts a new gene
     sequence at a random position of the original sequence. Brew
     chooses a random position, determines the number and type of
     stack values there and builds a gene sequence that ends having
     the same number and type of stack items but possibly different
     values. Finally it splices the three gene sequences together to a
     new genome. This is the main gene building type, that can start
     from a empty (noop) sequence.

   * `top-level-replacement'. This type of mutation replaces a random
     gene sequence within a genome by another (new) one. Brew picks a
     random gene sequence from the genome and adapts end points such,
     that the end points do not cross conditional levels or somesuch.
     It determines the number and types of stack items at both end
     points and builds a new sequence having the same stack effect
     regarding number and type of items, but possibly changed values.
     So an address might very well have been replaced by another
     address or an integer number by another one. Just the count and
     type of stack items remain unchanged. Finally it splices the
     three gene sequences together to the new genome. This type helps
     optimising gene sequences that have already proven some
     usefulness.

   * `snip-types'. This family of mutation types determine a gene
     sequence within the genome having no overall stack effect
     regarding stack item number and types. The sequence might change
     stack *values*, though. The sequence is just omitted in the
     resulting genome. Together with scoring on code length this helps
     cutting useless gene sequences out of long genomes. Snip types
     come as the following sub types (select `* nested list *' to
     adapt probabilities):

        - `top-level-random-snip'. Look for a random starting point.
          Determine all possible ending points and take a random one.

        - `top-level-short-snip'. Look for a random starting point.
          Take the shortest possible (non empty) sequence to snip
          away.

        - `top-level-long-snip'. Look for a random starting point.
          Determine all possible ending points and take the longest
          possible sequence to be left out.

        - `top-level-snip-IF-ELSE-branch'. Brew can construct
          conditional IF-THEN or IF-ELSE-THEN structures, so it must
          be able to deconstruct them. This snip type chooses a random
          IF-ELSE-THEN structure and eliminates one of the branches,
          leaving the other in the genome without a condition. IF
          branches without ELSE either get snipped away completely or
          get executed unconditionally, eliminating the condition.
          This mutation type just drops the flag and leaves the work
          to eliminate the flag producing gene sequence to other snip
          types. (Brew can not know if the flag producing code has any
          side effects).

   * `top-level-address-replacemnt'. Replace a gene that gives an
     address (most likely some kind of variable) by another one that
     does so. Start at a random point and search towards the end of
     the genome for a gene giving a address. Take the first one found
     restarting from genomes start if necessary. Take a random gene
     giving an address (most likely another variable) as replacement.
     Note that the gene might eventually be replaced by itself. This
     mutation type is a special variety of the next (more generic)
     case. It exists as a separate type due to the special importance
     of addresses (variables). The address replacement type helps
     finding useful variables.

   * `top-level-token-replace'. Take a random gene item, replace it by
     one having the same stack effect regarding stack types (but
     probably different actual stack values). Works very much like
     address replacement above, but accepts any stack effect, not only
     address givers. The type helps optimising genomes that already
     might have developed some usefulness.

   * `restart-from-scratch'. This type throws out the whole genome and
     restarts from scratch by doing top-level-insertion on a empty
     sequence. The type tries to help breaking out of evolutionary
     dead end streets or might sometimes bring in completely new
     approaches to solve the given task. You will typically set this
     type to a pretty low probability.

   * `rebirth'. The genome is replaced by an old one out of a list of
     successful genomes. This gives a distinct species another chance.
     Brew can automatically adapt relative probabilities of the
     genomes based on reproduction count, so successful ones get
     reincarnated more frequently. (*Note Genome pool::).




File: brew.info, Node: Gene pools menu, Next: Actual pool menu, Prev: Mutation menu, Up: Users manual

Gene pools menu
===============

This menu let's you choose the gene pool to be used for mutation.
You get here from brews main screen by pressing `G'.

Currently only `gene-primitives' is selectable.




File: brew.info, Node: Actual pool menu, Next: Stack type symbols, Prev: Gene pools menu, Up: Users manual

Actual pool menu
================

This menu let's you edit the gene pool used for mutation.
You get here from brews main screen by pressing `A'.

Currently this is always `gene-primitives'.

Change the relative probabilities of the genes to be used by mutation.

*Note Probability lists::.
*Note Scrolling menus::.




File: brew.info, Node: Stack type symbols, Next: Gene primitives, Prev: Actual pool menu, Up: Users manual

Stack type symbols
==================

This is slightly advanced info which might help you understand some
brew internals better. If it confuses you, please skip it.

Brews mutation mechanism generates random Forth program code. It is
*not* a requirement on the mutation process that the produced program
snippets would do something useful. It is the duty of the evolutionary
selection mechanism to take care of usefulness. But there are at least
two requirements on the generated gene code that mutation *must*
fulfil:

   * Security. If I run brew on my computer I want to be sure it
     cannot possibly generate any harmful program code under whatever
     circumstances.

   * Correctness and stability. I want brew to produce programs that
     are crash proof. It *would* be possible to let evolutionary
     selection take care of that, but I don't like the idea. Let's
     imagine a very long genome which had a hidden instability which
     would be very, very unlikely to show up. All the other parts of
     the genome could be optimised through hundreds of millions of
     incarnations until the hidden bug would byte the first time. The
     evolutionary selection mechanism would probably take the whole
     genome out of the play, loosing all the achievements already
     made.

Correct use of the Forth data stack plays an important part in
fulfilling these requirements. I'd consider it a possible security
risk if the cells could read and write to arbitrary addresses and it
would be disastrous regarding stability. So the mutation process
*must* know about the type of stack data, at least about addresses.
The usual Forth compiler does not do any type checking, assuming that
the programmer is clever enough to do it right. Brews mutation process
only does some very rudimentary type checking, just enough to assure
stable and secure code and leaves the decision if the result does
something useful to the evolutionary selection process. Brew knows
about very few different types and uses one byte char symbols called
`stack symbols' to indicate them:

   - `n'. Cell wide numeric value, not distinguishing between signed
     and unsigned. (The technical term `cell' is used in the Forth
     sense here, indicating a storage unit, frequently 32 bits).

   - `a'. Address that contains a numeric cell wide value as above.
     Addresses can be read and written, but never can be the result of
     address arithmetic operations. Addresses that are read only are
     never passed as stack parameters, but read out immediately by the
     corresponding gene primitive.

   - `r'. Floating point value on the floating point stack. 

   - `A'. Address of a double-precision IEEE floating point value.
     Brew always uses double-precision IEEE floating point format when
     storing float values in memory for compatibility reasons.

   - `C'. Flag being `true' or `false'.

Brew uses a notation for stack types that looks similar to the usual
stack effect comments in Forth source code. Please note that there are
subtle differences not only in the look (intentionally) but also in
the meaning: While Forth stack comments try to convey some type
information *and* individuality of the values, brews stack symbols
only talk about (very few) basic types.

So Forth would say  `swap ( x1 x2 -- x2 x1) '
While brew would    `swap ( nn-nn ) '
or (depending on the types of the stack items) would possibly see it as a 
different word like `swap(an) ( an-na) '. 

Note that the last example would execute and compile the *same* code,
just a normal `swap'. Only mutation would name it differently for it's
purposes. This allows you to give other probabilities to the different
variations (or forbid some completely, if you want to), which has
proven to be a very valuable feature.

Note that brews stack symbols are always single letters without spaces
in between, and there is one single `-' char to separate symbols
before and after gene execution. This has technical reasons but is
convenient, as the slightly different look should remind you of the
slightly different meaning.




File: brew.info, Node: Gene primitives, Next: Gene edit menu, Prev: Stack type symbols, Up: Users manual

Gene primitives
===============

Mutation can only build genomes based on the so called `gene primitives'.
The gene primitives are given together with their stack type symbols here.
*Note Stack type symbols::, for an explanation.


* Menu:

* Integer arithmetics genes::   Basic arithmetics.
* Stack juggling genes::        Arranging items on the Forth stack.
* Genes reading from memory::   Fetching a value from an address.
* Genes writing to memory::     Writing a value to an address.
* Dealing with overflow::       Genes respecting upper limits for values.
* Nuc and spot variables::      Genes for read/write and read/only variables.
* Global variables::            Read only access to some global variables.
* Insight genes::               Genes giving the cell access to its innards.

Floating point primitives:

* Float arithmetic genes::      Basic float maths.     
* More float arithmetics::      Fnegate, fabs, fmax, fmin, f2*, f2/, 1/f
* Logarithms and exponentials::  Logarithms, exponentials, roots.    
* Trigonometry::                Trigonometric functions gene primitives.
* Mixed maths::                 Mixed integer/float operators.
* Type casts::                  Casts between integer and floating point.
* Read float values::           Fetching floats from memory.
* Store float values::          Store floating point values to memory.
* Float stack manipulation::    Arranging items on the float stack.
* Nuc and spot floats::         Float variables local to a nuc or spot.

Conditional structures:

* Gene conditionals::           Conditionally executing gene code sequences.
* Floating point comparison::   Conditions based on floating point values.

Whole tested genomes can be used like new primitives:

* Genome pool::                 Successful genomes as new genes.




File: brew.info, Node: Integer arithmetics genes, Next: Stack juggling genes, Prev: Gene primitives, Up: Gene primitives

Integer arithmetics gene primitives
-----------------------------------

   - ` + ( nn-n )'. Addition.

   - ` - ( nn-n )'. Subtraction.

   - ` negate ( n-n )'. Negate.

   - ` * ( nn-n )'. Multiply.

   - ` ?/ ( nn-n )'. Divide if divisor is not zero, else return zero.




File: brew.info, Node: Stack juggling genes, Next: Genes reading from memory, Prev: Integer arithmetics genes, Up: Gene primitives

Gene primitives to arrange items on the Forth stack
---------------------------------------------------

This might look familiar to Forth programmers and very strange to other
readers.... ;-)
(Consider learning some Forth basics and return to here later on....)

Forth makes heavy use of the so called `data stack'.
Brew uses some (but not all) of the possibilities Forth gives the programmer
to rearrange items on the stack.

There is a conceptional difference of how brew sees stack juggling and
how Forth programmer usually do. Let's take a simple example:

   * `swap'. This Forth word swaps the two topmost stack items. So if
     you have '1' '2' on the stack before, you'd have '2' '1' after.

     A Forth programmer might write this as follows:

   * `swap ( x1 x2 -- x2 x1)'. This is a usual way of writing down the
     stack effect of the word `swap' that was described above in plain
     English. Forth sees everything inside the parenthesis as a
     comment, while it symbolises the stack effect for the Forth
     programmer.

Brews mutation has to know about stack effects of it's genes to generate
something stable, secure and sometimes maybe even useful. Mutation does
not care about the actual stack values (the '1' '2' above) though, but
only about the *type* of them. So if you have two integers as x1 and x2
like in the example above brews mutation sees `swap ( n1 n2 -- n2 n1)'
as a noop regarding stack effect. If one of them is a address instead,
brews mutation mechanism sees that `swap' as a completely different word,
even if it will compile the normal Forth word `swap' in both cases.
*Note Stack type symbols::.


   - `dup ( n-nn)'. Duplicate the topmost stack item (integer).

   - `dup(a) ( a-aa)'. Duplicate the topmost stack item (address).
     This primitive is commented out by default. Uncomment to
     activate.

   - `2dup ( nn-nnnn)'. Duplicate the topmost pair of stack items
           (two integers).
   - `2dup(na) ( na-nana)'. Deactivated type variant.
   - `2dup(aa) ( aa-aaaa)'. Deactivated type variant.
   - `2dup(an) ( an-anan)'. Deactivated type variant.

   - `drop ( n-)'. Forget topmost stack item (integer).
   - `drop(a-) ( a-)'. Forget topmost stack item (address).

   - `nip       ( nn-n)'. Forget second stack item.
   - `nip(aa-a) ( aa-a)'. Forget second stack item.
   - `nip(an-n) ( an-n)'. Forget second stack item.
   - `nip(na-a) ( na-a)'. Forget second stack item.

   - `tuck ( nn-nnn)'. Put a copy of the topmost stack item below the
     second one (both integers).
   - `tuck(aa-aaa) ( aa-aaa)'. Deactivated type variant.
   - `tuck(na-ana) ( na-ana)'. Deactivated type variant.
   - `tuck(an-nan) ( an-nan)'. Deactivated type variant.

   - `swap ( nn-nn)'. Swap topmost two stack items (both integers).
   - `swap(aa-aa) ( aa-aa)'. Deactivated type variant.

   - `over ( nn-nnn)'. Put a copy of the second stack item over the
     (former) topmost one (both integers).
   - `over(an-ana) ( an-ana)'. Put a copy of the second stack item
     (address) over the (former) topmost one (integer).
   - `over(na-nan) ( na-nan)'. Deactivated type variant.
   - `over(aa-aaa) ( aa-aaa)'. Deactivated type variant.


To get somehow readable gene code I don't like addresses lying around
too long on the stack, but want them resolved as soon as possible.
That's the main reason why I keep many type variants of the above
primitives deactivated by commenting them out in the source. You can
always activate them (but you might run into troubles with it...). You
don't loose much by leaving them switched off, as there is no address
arithmetic mutation can always get a copy of an address (variable) by
choosing it's gene a second time.




File: brew.info, Node: Genes reading from memory, Next: Genes writing to memory, Prev: Stack juggling genes, Up: Gene primitives

Genes reading a value from a memory address.
--------------------------------------------

As explained elsewhere genes cannot access arbitrary addresses for
security and stability reasons.
*Note Stack type symbols::.
*Note Genes::.

If there *is* an address on the stack you can be sure it is legitimate
for the genome to read (and even write) it's contents.

   - `@ ( a-n)'. Read contents of address `a'.

   - `take ( a-n)'. A variant from the above gene, which I consider to
     be interesting as a building block in problem solving. This gene
     literally takes the value away from the address, as it reads it's
     contents and clears the memory location then. (So it's actually
     reading *and* writing to the address, which is legitimate).




File: brew.info, Node: Genes writing to memory, Next: Dealing with overflow, Prev: Genes reading from memory, Up: Gene primitives

Genes writing a value to a memory address
-----------------------------------------

As explained elsewhere genes cannot access arbitrary addresses for
security and stability reasons.
*Note Stack type symbols::.
*Note Genes::.

If there *is* an address on the stack you can be sure it is legitimate
for the genome to (read and) write to this address.

   - `! ( na-)'. Store integer `n' at address `a'.

   - `-! ( na-)'. Subtract integer `n' from the value at address `a'
     and store the new value at the same address.

   - `swap! ( an-)'. Store integer `n' at address `a'. This is like
     `!' with the parameters the other way round.

   - `off ( a-)'. Clear memory contents at address `a'.




File: brew.info, Node: Dealing with overflow, Next: Nuc and spot variables, Prev: Genes writing to memory, Up: Gene primitives

Genes limiting values to avoid overflow problems
------------------------------------------------

Gene sequences doing things like adding the contents of an address to
the same address will provoke integer overflow very quickly. The cells
do not have any problems with overflow, they even seem to like it
specially.... Genomes find out all sort of tricks they can play with
overfloating variables. But probably this is not what you want, and it
is usually quite difficult to understand what's happening. So you
might want to avoid overflow. I don't think there is a simple and
clean possibility to do this. The trick used here is more like a quick
dirty hack that does some good and does some harm. Just use or leave
it as you want ;-)

The trick is to have some words equivalent to `!' or `+!' that refuse
to write too big values. There is a maximal value, that will not be
exceeded. Up to half that value you get as much as you want, then the
curve increases half as steep (so you still get some more if you ask
for more) until it reaches the maximum, where it stays. This is done
by the word `some'.


   - `!(some) ( na-)'. Store some fraction of `n' at address `a'.

   - `+!(some) ( na-)'. Read value at address `a', add some of the
     value `n' and store result as new value at address `a'.

   - `-!(some) ( na-)'. Like above, but *subtract* some.

   - `swap!(some) ( an-)'. Like `!(some)', but parameters swapped.

   - `take-some ( a-n)'. Takes some of the value away from address `a'
     preserving sign of the original value.




File: brew.info, Node: Nuc and spot variables, Next: Global variables, Prev: Dealing with overflow, Up: Gene primitives

Read/write and read/only nuc and spot variables.
------------------------------------------------

These genes access different classes of variables.
*Note Variable names::, for more info.

There are (hereditary) variables of the nuc and (environmental)
variables of the spot. Each kind has a read/write and a read/only
variant. In brew the read/write variant puts it's address on the
stack, as usual in Forth, while the read/only variant gives it's
value. Brew can write read/only variables of course, only the genes
can't. Note that the address of a read/only variable will never be put
on stack during gene execution. That means that only it's current
*value* can be known to the cell. There are other classes of variables
(like `secrets') that have no genes to access them. So the genes have
per se no possibility to access them in any way.

The number of variables of the different classes is configured by
compile time options.


   - `organ-A ( -a)', `organ-B ( -a)', `organ-C ( -a)', .... These are
     the read/write nuc intern variables. They pass their address on
     the stack granting read/write access. These variables are
     hereditary and diversificable.

   - `parameter-A ( -n)', `parameter-B ( -n)', `parameter-C ( -n)',
     .... Read only nuc intern variables passing their current value
     on stack. These variables are hereditary and diversificable. The
     genome cannot know their address and therefore cannot change
     their value in any way. (Technically speaking they are just
     ordinary nuc variables. There are just no genes that deliver
     their addresses).

   - `A-quality ( -a)', `B-quality ( -a)', `C-quality ( -a)', ....
     Read/write spot variables, passing their address on the stack.

   - `A-property ( -n)', `B-property ( -n)', `C-property ( -n)', ....
     Read/only spot variables passing their current value on the
     stack.




File: brew.info, Node: Global variables, Next: Insight genes, Prev: Nuc and spot variables, Up: Gene primitives

Genes giving the cells read access to global variables.
-------------------------------------------------------

For many experiments it is not necessary to have nuc or spot local
variables. These genes give read access to a group of global integer
or float variables.

   - `integer-A@ ( -n)', `integer-B@ ( -n)', `integer-C@ ( -n)', ....
   - `dfloat-A-f@ ( -r)', `dfloat-B-f@ ( -r)', ....

The number of these variables is configured by compile time options.




File: brew.info, Node: Insight genes, Next: Float arithmetic genes, Prev: Global variables, Up: Gene primitives

Genes giving the cells knowledge about themselves.
--------------------------------------------------

These genes are for experiments like biological simulations. They give
the genome read/only access to some data about themselves like energy
level or age. They cannot directly change these data, but they could
adapt their behaviour to them i.e. do different things in their youth
than when they are old. Like all read/only variable access genes all
these genes pass the value on stack, hiding the address where it's
stored from the genome.


   - `age ( -n)'. Gene giving the current age of the individual.

   - `age-threshold ( -n)'. Maximal possible age.

   - `energy ( -n)'. Gene giving the cells current energy level.

   - `reproduction-threshold ( -n)'. How much energy needed for
     reproduction.




File: brew.info, Node: Float arithmetic genes, Next: More float arithmetics, Prev: Insight genes, Up: Gene primitives

Basic floating point maths
--------------------------

   - ` f+ ( rr-r )'. Floating point addition.

   - ` f- ( rr-r )'. Floating point subtraction.

   - ` f* ( rr-r )'. Floating point multiplication.

   - ` f/ ( rr-r )'. Floating point division.




File: brew.info, Node: More float arithmetics, Next: Logarithms and exponentials, Prev: Float arithmetic genes, Up: Gene primitives

More floating point operator primitives
---------------------------------------

   - ` fnegate ( r-r )'. Floating point negation.

   - ` fabs ( rr-r )'. Floating point absolute value.

   - ` fmax ( rr-r )'. Floating point maximum.

   - ` fmin ( rr-r )'. Floating point minimum.

   - ` f2* ( r-r )'. Double floating point value.

   - ` f2/ ( r-r )'. Divide floating point value by two.

   - ` 1/f ( r-r )'. Floating point reciprocal.




File: brew.info, Node: Logarithms and exponentials, Next: Trigonometry, Prev: More float arithmetics, Up: Gene primitives

Logarithms, exponentials, roots
-------------------------------

Aliases of ANS Forth float functions. See ANS Forth documentation.

   - ` f** ( rr-r )'.

   - ` fsqrt ( r-r )'.

   - ` fexp ( r-r )'.

   - ` fexpm1 ( r-r )'.

   - ` fln ( r-r )'.

   - ` flnp1 ( r-r )'.

   - ` flog ( r-r )'.

   - ` falog ( r-r )'.




File: brew.info, Node: Trigonometry, Next: Mixed maths, Prev: Logarithms and exponentials, Up: Gene primitives

Trigonometric functions gene primitives
---------------------------------------

Aliases of ANS Forth float functions. See ANS Forth documentation.

   - ` fsin ( r-r )'.

   - ` fcos ( r-r )'.

   - ` fsincos ( r-rr )'.

   - ` ftan ( r-r )'.

   - ` fasin ( r-r )'.

   - ` facos ( r-r )'.

   - ` fatan ( r-r )'.

   - ` fatan2 ( rr-r )'.

   - ` fsinh ( r-r )'.

   - ` fcosh ( r-r )'.

   - ` ftanh ( r-r )'.

   - ` fasinh ( r-r )'.

   - ` facosh ( r-r )'.

   - ` fatanh ( r-r )'.

   - ` pi ( -r )'.




File: brew.info, Node: Mixed maths, Next: Type casts, Prev: Trigonometry, Up: Gene primitives

Mixed integer/float operators
-----------------------------

   - ` f+i ( rn-r )'. Add integer value to a float and give result as
     float.

   - ` f-i ( rn-r )'. Subtract integer value from a float and give
     result as float.

   - ` f*i ( rn-r )'. Multiply a float value by a integer and give
     result as float.

   - ` f/i ( rn-r )'. Divide a float value by a integer and give
     result as float.

   - ` i/i ( nn-r )'. Divide a integer value by another integer and
     give result as float.

   - ` i+f ( nr-r )'. Add float value to a integer and give result as
     float.

   - ` i-f ( nr-r )'. Subtract float value from a integer and give
     result as float.

   - ` i*f ( nr-r )'. Multiply an integer by a float value and give
     result as float.

   - ` i/f ( nr-r )'. Divide an integer by a float value and give
     result as float.

   - ` f/f ( rr-n )'. Divide a float by another float and give result
     as integer.

   - ` f*f ( rr-n )'. Multiply two floats and give result as integer.

   - ` i*f>i ( nr-n )'. Multiply an integer by a float and give result
     as integer.

   - ` i/f>i ( nr-n )'. Divide an integer by a float and give result
     as integer.




File: brew.info, Node: Type casts, Next: Read float values, Prev: Mixed maths, Up: Gene primitives

Casts between integer and floating point
----------------------------------------

   - ` f>s ( r-n )'. Transform a float to an integer.

   - ` s>f ( n-r )'. Transform an integer to a float.




File: brew.info, Node: Read float values, Next: Store float values, Prev: Type casts, Up: Gene primitives

Fetching floats from memory
---------------------------

Brew stores all floats as dfloats (double-precision IEEE
floating-point format) for compatibility reasons.

   - ` df ( A-r )'. Read double-precision IEEE floating-point value.

   - ` f-take ( A-r )'. Read double-precision IEEE floating-point
     value actually 'taking it away' from the address (storing zero
     there).




File: brew.info, Node: Store float values, Next: Float stack manipulation, Prev: Read float values, Up: Gene primitives

Fetching floats from memory
---------------------------

Brew stores all floats as dfloats (double-precision IEEE
floating-point format) for compatibility reasons.

   - ` df! ( rA- )'. Store float as double-precision IEEE
     floating-point value at address A.

   - ` df+! ( rA- )'. Add float to the float stored at address A and
     store the sum as double-precision IEEE floating-point value at A.

   - ` df-! ( rA- )'. Subtract a float from the float stored at
     address A and store result as double-precision IEEE
     floating-point value at A.




File: brew.info, Node: Float stack manipulation, Next: Nuc and spot floats, Prev: Store float values, Up: Gene primitives

Arranging items on the float stack
----------------------------------

   - ` fdup ( r-rr )'. Clone topmost float stack item.

   - ` fdrop ( r- )'. Forget topmost float stack item.

   - ` fswap ( rr-rr )'. Exchange the two topmost float stack items.

   - ` fover ( rr-rrr )'. Copy second float stack item to the top.

   - ` frot ( rrr-rrr )'. Rotate third float stack item to the top.

   - ` drop(float-pointer) ( A- )'. Forget address of float on top of
     data stack.




File: brew.info, Node: Nuc and spot floats, Next: Gene conditionals, Prev: Float stack manipulation, Up: Gene primitives

Float variables local to a nuc or spot
--------------------------------------

These variables are the floating point versions of nuc and spot
variables. *Note Nuc and spot variables::, for more informations. Brew
always uses double-precision IEEE floating point format when storing
float values in memory for compatibility reasons. Float variables have
an additional 'f' or 'df' in their name. Some examples:

   - ` f-organ-A ( -A )'. Gives address of first read/write nuc local
     floating point variable.

   - ` f-parameter-B-f ( -r )'. Gives value of second read only nuc
     local floating point variable.

   - ` A-f-quality ( -A )'. Gives address of first read/write spot
     local floating point variable.

   - ` C-f-property ( -r )'. Gives value of third read only spot local
     floating point variable.




File: brew.info, Node: Gene conditionals, Next: Floating point comparison, Prev: Nuc and spot floats, Up: Gene primitives

Conditionally executing gene sequences
--------------------------------------

Gene sequences can contain `IF ELSE THEN' structures like other Forth
code conditionally executing alternatives depending on numerical
comparisons and such. Please note that these structures take the form
of `[IF] [ELSE] [THEN]' during trial phase, as code is interpreted
(not yet compiled) then. Of course brew takes care about that.

   - `g-IF-ELSE-THEN ( C-)' is a pseudo gen, which is never executed,
     but triggers insertion of a `IF ELSE THEN' structure. Setting
     relative probability of this pseudo gene in a gene pool therefore
     influences frequency of `IF ELSE THEN' structures relative to
     other flag taking genes (like `AND' or `OR'). (*Note Probability
     lists::).

   - `IF ( C-)', `[IF] ( C-)'. Conditional branch.
   - `ELSE', `[ELSE]'. Starts alternative sequence.
   - `THEN', `[THEN]'. Ends conditional structure.

   - ` 0= ( n-C)'. True if n is zero.

   - ` 0< ( n-C)'. True if n is below zero.

   - ` 0> ( n-C)'. True if n is positive and not zero.

   - ` = ( nn-C)'. True if the two integers are equal.

   - ` > ( nn-C)'. True if the first integer is bigger.

   - ` < ( nn-C)'. True if the first integer is smaller.

   - ` within ( nnn-C)'. True if the first integer is at least as big
     as the second one, but smaller than the third (topmost) one.

   - ` AND ( CC-C)'. True if both flags are true.

   - ` OR ( CC-C)'. True if at least one flag is true.

   - ` XOR ( CC-C)'. True if exactly one flag is true.




File: brew.info, Node: Floating point comparison, Next: Genome pool, Prev: Gene conditionals, Up: Gene primitives

Conditions based on floating point values
-----------------------------------------

   - ` f< ( rr-C)'. 

   - ` f> ( rr-C)'. 

   - ` f0< ( r-C)'. 

   - ` f0= ( r-C)'. 




File: brew.info, Node: Genome pool, Prev: Floating point comparison, Up: Gene primitives

Genome pools
------------

Brew can put successfully tested genes into a genome pool.
Switch that on or off in `Mutation menu'.
*Note Mutation menu::.

Genome pools serve two distinct purposes:

   * `Genomes as gene building blocks'. Whole genomes that have proven
     to be useful can be reused like gene primitives to build new
     genes.

   * `Revitalisation of old genomes'. Sometimes useful genomes
     disappear by accident during an evolution. You can give them
     another chance by randomly re-introduce some of them again.
     (*Note Mutation types menu::).


Brew increases the relative probability of each genome every time
a cell with this genome get's reproduced. So successful genomes
will be used more often than less successful ones. This mechanism
is switched by the same switch as mentioned above.
*Note Probability lists::.




File: brew.info, Node: Gene edit menu, Next: Scanning nucs, Prev: Gene primitives, Up: Users manual

Examining and editing genes and whole genomes.
==============================================

You are presented a somehow formatted output of the genomes Forth
code. If you select a sub-gene, you will be put (recursively) in the
menu regarding the sub-gene, or presented gene information, if it is a
gene primitive.

Selecting the genomes name, or pressing `e' will write the genome to a
file and call and external editor (defined in `compile-options.fs') on
it. You can change this Forth file as you want to, save it and leave
the editor. Brew will check your input and inform you if it finds a
problem. Otherwise it will replace the nucs genome with your input and
set the nuc on trial. (*Note Trial phase::). All your used Forth words
must be defined already as genes. Brew will inform you, if you do use
a word that isn't. Have a look at some examples in *Note Genes
files::, if you want to define new gene primitives. (You could define
genes from the Forth input line, if you want to. *Note Using Forth in
menus::).




File: brew.info, Node: Scanning nucs, Next: Scanning spots, Prev: Gene edit menu, Up: Users manual

Scanning nucs
=============

If you press `n' in brews main screen you get to a menu displaying
information about (all living) nucs. For each nuc variable you will
see a line displaying minimal, maximal and average value. (*Note
Scrolling menus::). At one given time either integer or floating point
variables are displayed. Toggle between them with `o' as usual, or by
selecting the entry in the title line. (BTW: If you select one kind of
variables brew will assume that you are interested in this type. So
the display of i.e. `Nuc menu' will also switch to the same kind.
*Note Nuc menu::).

The same menu get's used to display statistical informations about nuc
subsets. The title line indicates what variable type gets displayed
and if all nucs or only a subset where scanned.


You see a bunch of lines similar to the following:

generation              min: 1417         max: 1483         average: 1455
genome-generation       min: 0            max: 1098         average: 347
code-cost               min: 100          max: 1699         average: 435
energy                  min: 403          max: 1105         average: 727


Selecting a `min' `max' or `average' value will port you to
a nuc subset screen of the nucs having the value in question.
*Note Menu nuc subsets::.

Selecting a variable name shows you a more detailed view of the
distribution of values of the variable as a simple ASCII bar graph:

                *
                *
                *
                *
                *
                **
                ***       *
                ***       *
                ****     **
                **** *   **
                ******* *****
                *************
                *************  *
       *      ***************  *   *
    ** **     ***************  **  *
   *******   ********************  *
 * ******* * ***********************  * ***
 ************************************ * ****        *
************************************* ************ **  *       *
*****************************************************.****.....*.. *...*.     .
-129        scanning: energy                       vertical range: 69      2260

Selecting a bar of this display type will port you to a `Menu nuc
subsets' with the value range in question, to do more analysis or so.
*Note Menu nuc subsets::.


*Note Menu step display::, for a way to display this type of
information in real time while brewing. You'll find some additional
information there too.


If you display floating point variables you will see lines like:

f-organ-A         min: 0          max: 3.1415926536  avr: .0436332313    .r..

There are four signs at the right border, either dots or `-r+?', which
represent negative infinity, real values, positive infinities and
NANs. A dot means that no values of this type exist. The above line
says, that *f-organ-A* of all scanned nucs did contain a real value,
no infinities or NANs. Selecting the sign will display counts for each
value type, a line for each scanned floating point variable:

Type counts:        -infinity:     real:          +infinity:     nan:

f-organ-A           0              72             0              0

Selecting a title entry like `-infinity' will port you to a nuc subset
menu with nucs that have i.e. negative infinities in any one of their
nuc float variables. As an exception `real' chooses nucs that have
*only* real float values.

Selecting a number, let's say the +infinity count for f-organ-C goes to
the nuc subsets with f-organ-C being +infinity.
*Note Menu nuc subsets::, *Note Menu spot subsets::, for documentation.

Toggle back with `o', or by selecting `Type counts'.




File: brew.info, Node: Scanning spots, Next: Configurable actions, Prev: Scanning nucs, Up: Users manual

Scanning spots
==============

If you press `w' from brews main screen you'll get to a menu
displaying statistical data over all spots. The same menu get's used
at different locations to display statistics about different spot
subsets. (*Note Scrolling menus::).

It works exactly as the corresponding menu for nuc statistics.
*Note Scanning nucs::, for more information.




File: brew.info, Node: Configurable actions, Next: Menu current genomes, Prev: Scanning spots, Up: Users manual

Do something on nuc or spot subsets.
====================================

In many situations you might want to do something with a certain class
of nucs or on certain spots only.

Maybe you are especially interested in all nucs having a certain
genome. So you'd like to replace their display function to something
special so you can watch what's happening with them. Or you'd like to
multiply one of the inner variables of all the cells having this
genome with a given scale, set a special condition on all the spots
inhabited by these cells, remove all other cells or whatever might
make sense in the given situation. Brew has functions to do such
things. You can do quite fancy things with these functions and of
course you can record and replay later on what you did just like about
everything in brew. (Just switch recording on before you do it).

As you will see soon, there are menu interfaces on a couple of places
to do such things. If you want to work on nucs having a special genome
as in the examples above, you'd best use the interface from the menu
that deals with (this) genome; if you want to work on cells on a spot
where spot variables reflect a special condition, approach from a menu
that deals with spots. But you can do much fancier things, if you want
to.

So we must configure at least two parts, (and often some more).

   * `Condition'. The condition is the part that defines on which nucs
     or spots (or combinations of both) the action has to be made.
     Sometimes the condition is already preset for you by brew. In the
     above examples you would go to the menu interface of all nucs
     with this genome which would set the condition to work on all the
     nucs having this genome, so you wouldn't have to bother about.
     Conditions might be simple (like: do it on all inhabited spots)
     or more complex needing more parameters (like: do it on all spots
     where a certain quality is smaller than 1765). For real complex
     cases the interface also allows you to enter Forth source to
     determine whether to do it here or not.

   * `Action'. On all spots and/or nucs (depending the situation)
     where `condition' is `TRUE' this action will be taken. Like with
     conditions there are simple actions (like: remove this nuc) and
     more complex ones that need additional parameters (like: multiply
     energy level of these nucs by 5/3). You can enter fancy actions
     as Forth source at run time. Whatever you'll do, if recording is
     on, it will be recorded of course.


Depending the situation you are prompted for nuc or spot related
conditions and actions, or both:
* Menu:

* Simple nuc conditions::       Defining simple nuc subsets.
* Simple spot conditions::      Defining simple spot subsets.

Extended conditions requiring parameters and a comparison:
* Extended conditions::         Spot or nuc subsets based on comparisons.

Actions to be done on the defined subset:
* Generic nuc/spot actions::    Doing something on spot or nuc subsets.
* Nuc specific actions::        Doing something on nuc subsets.

* Defining maybe-do actions::   The menu interface to conditional actions.

Generic interface to act on a nuc subset:
* Menu nuc subsets::            Menu interface to act on nuc subsets.
* Menu spot subsets::           Menu interface to act on spot subsets.


Please use these advanced functions with great care.

Brew assumes that you know what you are doing here and does not even
try to prevent you from doing the most stupid possible things with
this feature.... So if you tell brew to multiply the action pointer
(`xt') of all nucs genome by say 7/9 it will do it obediently ;-)

Brew does it's best in many places to prevent you from doing stupid
mistakes, but please don't rely on that. Here it does not do
*anything* like that. Did I make that clear?




File: brew.info, Node: Simple nuc conditions, Next: Simple spot conditions, Prev: Configurable actions, Up: Configurable actions

Simple conditions defining a nuc subset.
----------------------------------------

These conditions do not require any parameters.

   * `true'. Do with everybody.

   * `selected?'. Do with all selected nucs.

   * `on-trial?'. Do with all nucs in trial phase.

   * `fertile?'. Do with all nucs that would have enough energy to
     reproduce.

   * `will-die?'. Do with all nucs that will die this life step.




File: brew.info, Node: Simple spot conditions, Next: Extended conditions, Prev: Simple nuc conditions, Up: Configurable actions

Simple conditions defining a spot subset.
-----------------------------------------

These conditions do not require any parameters.

   * `everywhere'. Unconditionally do everywhere.

   * `inhabited?'. Do on all inhabited spots.

   * `empty?'. Do on all spots that are *not* inhabited.




File: brew.info, Node: Extended conditions, Next: Generic nuc/spot actions, Prev: Simple spot conditions, Up: Configurable actions

Extended conditions comparing two values
----------------------------------------

The condition is based on the comparison of two values.
These conditions do require additional parameters and the comparison:

   * `2-variables'. The flag is computed through comparison of the
     values of two spot or nuc variables, which you should select
     next. Of course you can also see variables hidden to the genes
     like `secrets'. You can act like a god in this virtual universe
     ;-)

   * `variable-number'. The flag is computed through comparison of a
     spot or nuc variable against a numeric value. You should select
     the variable and set the threshold value next.

   * `variable-within'. The value of a variable is chequed to be
     within two border values. The lower border is inclusive, the
     upper exclusive. So `0 3 WITHIN' is true for 0, 1 and 2, but not
     for 3. The flag is compared against `true', so use `=' for values
     that are within the range and `<>' for all values that are
     outside range as comparison (see below).

   * `function-number'. The return value of a function (like the score
     of a cell) is compared to a numeric value.

   * `function-within'. The return value of a function is tested if it
     is between two given numeric values.

   * `evaluate-expr'. Select this if you want to define your own
     condition as Forth source. Please take care to use nuc local
     variables exclusively in situations where the nuc is defined at
     all.... The source will be evaluated on all spots and/or nucs
     (depending the situation) and must return *two* stack items to be
     run through the following comparison.


     All the above functions have a floating point version like
     `df-variable-number'. The following words work on dfloat
     variables only to test value types:

   * `df-var-real?'. True if the value is real.

   * `df-var-inf?'. True for infinities of both signs.

   * `df-var-pos-inf?'. True for positive infinity.

   * `df-var-neg-inf?'. True for negative infinity.

   * `df-var-nan?'. True if it is not a number (NAN).


   * `Comparison'. The above functions give two values which are
     compared by one of the following comparisons:

        * `<'. Do it if first value is smaller.

        * `<='. Do it if first value is smaller or equal.

        * `>'. Do it if first value is bigger.

        * `>='. Do it if first value is bigger or equal.

        * `='. Do it if both values are equal.

        * `<>'. Do it if the values are different.


Please note, that of all the above there are distinct versions for
integer and floating point data. (Brew tries to select the right
version depending on the situation, but don't rely too much on that).




File: brew.info, Node: Generic nuc/spot actions, Next: Nuc specific actions, Prev: Extended conditions, Up: Configurable actions

Generic nuc/spot actions
------------------------


   * `set-variable'. Set a variable to a given value. You should
     select the variable and enter the value next.

   * `add-to-variable'. Add a value to a given variable. You should
     select the variable and enter the value next.

   * `sub-from-variable'. Subtract a value from a given variable. You
     should select the variable and enter the value next.

   * `scale-variable'. Multiply a given variable by a scale (like
     1/2). You should select the variable and enter the scale next.
     (*Note Scale input::).

   * `evaluate-do'. Select this item to define your own action as
     Forth source. Your input will be interpreted on all spots/nucs
     where the condition fits. The function is not allowed to access
     stack items it did not put there itself and must not leave
     something on the stack. Please take care to use nuc local
     variables exclusively in situations where the nuc is defined at
     all....


Please note, that of all the above there are distinct versions for
integer and floating point data. (Brew tries to select the right
version depending on the situation, but don't rely too much on that).




File: brew.info, Node: Nuc specific actions, Next: Defining maybe-do actions, Prev: Generic nuc/spot actions, Up: Configurable actions

Nuc specific actions
--------------------

In addition to the generic actions on nuc and/or spot variables you
can program the following nuc specific actions:

   * `select-nuc'. Select nuc.

   * `de-select-nuc'. De-select nuc.

   * `toggle-selection'. Toggle selection status of the nuc.

   * `remove-nuc'. Remove the nuc.




File: brew.info, Node: Defining maybe-do actions, Next: Menu nuc subsets, Prev: Nuc specific actions, Up: Configurable actions

Defining maybe-do actions
-------------------------

I call this mechanism of conditionally executing user defined actions
`maybe-do'. The menu interface to set it all up looks slightly
different depending on the situation. In some cases half of the job is
already invisibly done, like setting the condition or action part. A
typical interface might look like this before you define anything:

Setup condition and action first.
Simple condition:    false
What to do:          noop

`Simple condition' switches between simple and extended conditions.
The rest is trivial, you will find out how it works. After you have done
your configuration it might look similar to this:

DO something on some spots: Please use carefully...
Extended condition:  2-variables  A-quality  B-quality  >
What to do:          scale-variable  food  with  3/2

Selecting the first line of the example, will actually *do* it now.




File: brew.info, Node: Menu nuc subsets, Next: Menu spot subsets, Prev: Defining maybe-do actions, Up: Configurable actions

Menu interface to act on a nuc subset
-------------------------------------

This menu is the user interface to use the `maybe-do' functions on
nucs. *Note Configurable actions::, for an explanation what it does
and how to configure it.

After defining the condition you can display and analyse (scan) all
nucs that fulfils it. The title line of the menu gives the count of
nucs that meet the condition. If an action is defined, you can execute
it on each nuc of the subset.

   * `DO IT'. Do the user defined action on each nuc that fulfils the
     condition.

   * `Show subset'. Show a world map with the subset coloured.

   * `Show on range'. If it makes sense in the given context brew
     offers you a map to see if nucs fall below, within or above a
     given range.

   * `Scan this subset'. Give a summary about nuc variable values or
     more detailed ASCII bar graphs about value distribution on each
     variable. *Note Scanning nucs::, for a description. Called from
     this entry data is collected from nucs fulfilling the condition
     only.

   * `Scan nucs'. Same but with data from *all* nucs for comparisons.

   * `Scan world'. Scan over all spots. Not directly related, but
     useful sometimes. *Note Scanning spots::, for a description how
     it works.




File: brew.info, Node: Menu spot subsets, Prev: Menu nuc subsets, Up: Configurable actions

Menu interface to act on a spot subset
--------------------------------------

This menu is the user interface to use the `maybe-do' functions on
spots. *Note Configurable actions::, for an explanation what it does
and how to configure it.

It works on spots analogous to the `Menu nuc subsets'.

*Note Menu nuc subsets::, for more information.




File: brew.info, Node: Menu current genomes, Next: Menu select nucs, Prev: Configurable actions, Up: Users manual

Menu current genomes
====================

Pressing `U' (or `u' as a shortcut) from brews main screen
takes you to the `Menu current genomes'. This menu deals with the
genomes of all currently living cells. (*Note Scrolling menus::).
The start of the menu screen might look similar to this:

Menu current genomes.                  Genomes of living cells: 79

genome-id:   genome:      count:       cost:        max generations:

0          * noop         948          100          36
2            g-2 t:61     158          287259       26
3            g-3          314          3199         34
4            g-4          10           500          18
7            g-7 t:2      13           500          18
14           g-14 t:3     11           400          15
16           g-16         13           5198         24
18           g-18 t:5     16           4397         17
19           g-19 t:1     9            1000         22
23           on trial     21           1400         16
[ ... ]

The title line tells you how many different genomes there are
currently.

The column titles (with the exception of the one for the genome name)
are selectable menu items. If you select them, the display order of
the lines belonging to the single genomes is changed to be based on
the quality in question. Selecting the item again will switch between
ascending and descending sorting. You can also use the key bindings
given below.

The column have the following meaning:

   * `genome-id'. Identification number of the genome. As these
     numbers are given in ascending order it is also a relative
     indicator of the age of this genome.

           Selecting the column title or pressing `i' or `g' will set
     the genome-id to be the key for the order of genome display.
     Selecting it again will switch between ascending and descending
     order.

           Selecting this columns entry of a genome leads to the menu
     for this individual genome. *Note Menu this genome::.

   * `genome'. Name of the compiled genome, if any. As genomes on
     trial have no name yet `on trial' get's displayed instead (see
     genome #23 above). If the genome *has* been compiled, but there
     are still some individuals left in trial phase from before that
     their number gets displayed as `t: <number>' after the name (see
     genome #2 above). (You cannot order display based on genome
     names).

           Selecting this columns entry of a genome will display the
     genomes program code.

   * `count'. Number of living cells with this genome. Press `c' to
     switch to count based display order.

           Selecting this columns entry of a genome will display a
     world map with the cells having this genome coloured.

   * `cost'. Code cost of the genome. This is a function of gene code
     length, so it also tells you something about the relative length
     of the genomes. Press `o' for cOst based display ordering.

           Selecting this columns entry of a genome will display a
     three coloured world map. Cells having the same gene code cost as
     the genome in question are white, cells with shorter code red and
     those with longer code are displayed cyan. *Note Colouring on
     difference::.

   * `max generations'. Check all cells of the same genome for how
     many generations this genome has already survived since last
     mutating it. The *maximal* number of generations found is
     displayed here. Pressing `m' orders display based on this value.

           Selecting this columns entry of a genome will display a
     three coloured world map. Cells having the same genome generation
     cost as displayed in the genome entry in question are white,
     cells with less genome generations red and those with more genome
     generations are displayed cyan. *Note Colouring on difference::.


* Menu:

* Colouring on equality::       Display cells with same amount of a quality.
* Colouring on difference::     Displaying `less', `equal', `more' type info.
* Menu this genome::            Examining all cells having the same genome.


You can look at each listed genome one after the other by pressing one
of the following keys:

   * `<SPACE>' to go to corresponding `Menu this genome'.

   * `l' or `n' to see the genomes Forth code.

   * `.' to call `.gene-info' on the genome. In the case of genomes on
     trial it shows the evaluated Forth code instead.

The `current' line will be indicated by a `*' before genome name, and
go down one line after examining the genome.




File: brew.info, Node: Colouring on equality, Next: Colouring on difference, Prev: Menu current genomes, Up: Menu current genomes

Colouring on equality
---------------------

Brew uses this function to show you all cells which share one special
quality. Brew displays a world map and colours the cells in question.
Similar maps get used to display spot qualities.

If you don't like the colours change `color-selected-fg-xt' and
`color-miss-fg-xt' for foreground colours (showing nucs), respectively
`color-selected-bg-xt' and `color-miss-bg-xt' for background colours
(showing spots) in `my-brew-options.fs'.

As an example brew uses it to show you all cells sharing the same
genome.

*Note World map interaction::, to learn what else you can do here.




File: brew.info, Node: Colouring on difference, Next: Menu this genome, Prev: Colouring on equality, Up: Menu current genomes

Three coloured world maps
-------------------------

Sometimes brew shows you a three coloured world map to indicate which
nucs or spots fall below, inside or above a certain range regarding
some quality in question. Falling `inside' a range can also mean
equality with a single value. Foreground colours code nuc qualities,
background shows the spot like always.

As an example the map could show you all nucs having code cost falling
into a given range (which is about the same as having a certain code
length) in one color, the shorter ones in another, and the longer ones
in a third colour. I call this `Colouring on difference'.


The meanings of the (default) colours (on foreground) are:

   * `magenta'. Lower, less of the quality in question.

   * `white'. Inside range or equal amount of the quality in question.

   * `cyan'. Higher, more of the quality in question.

If you don't like the colours change `color-below-fg-xt',
`color-selected-fg-xt' and `color-above-fg-xt' for the foreground
colours (showing nucs), respectively `color-below-bg-xt',
`color-selected-bg-xt' and `color-above-bg-xt' for the background
colours (showing spots) in `my-brew-options.fs'.


*Note World map interaction::, to learn what else you can do here.




File: brew.info, Node: Menu this genome, Prev: Colouring on difference, Up: Menu current genomes

Menu this genome
----------------

You'll get here normally selecting a entry for a genome from menu
`Menu current genomes'. (Which you reach by pressing `U' in brews main
screen). You cannot come here from brews main screen or from the super
menu, as brew can not know which genome you are interested in.

The menu title shows you the name of the compiled genome (if it is
compiled already) and how many cells share this same genome.


   * `genome GID'. The entry informs you about the genome
     identification number, which is not editable (at least not from
     here). If you select the entry brew will show you the Forth
     program code of the genome.

   * `.gene-info'. This entry gives you more informations about the
     genome.

   * `show cells'. Show a world map with cells having this genome
     coloured. (*Note Colouring on equality::).

   * `show younger/older'. Show a three color world map on age of
     genome relative to this one. (*Note Colouring on difference::).

   * `Scan these nucs'. Get nuc scan information from the nucs sharing
     this genome. The interface works exactly as the generic one, but
     the information of summary and detailed value distribution graphs
     are automatically scanned from these cells only. (*Note Scanning
     nucs::).

   * `Scan all nucs'. Get nuc scan information from *all* nucs. This
     is convenient to compare to the scan results gained from the
     subset of cells with the genome currently examined.

   * `Select these nucs'. Set the `selected' flag in all the nucs
     having this genome. (i.e. when you want to have a easy way to see
     the offspring later on).

   * `clear selection'. Clear the `selected' flag in all the nucs
     having this genome.

   * `toggle selection'. Invert the `selected' flag in all the nucs
     having this genome.

   * `Do something on these nucs'. This is the `maybe-do' interface to
     do something on the subset of nucs sharing this genome. You can
     program actions executed with all these cells or even enter Forth
     source code to be applied on them at run time. Brew already did
     set the condition (to work on nucs with this genome only) for
     you. You just have to select the action. This is an advanced
     feature without safety net. Please use with care. *Note
     Configurable actions::, for more info.




File: brew.info, Node: Menu select nucs, Next: World menu, Prev: Menu current genomes, Up: Users manual

Menu select nucs
================

This menu deals with the selection status of nucs.
You get here from brews main screen by pressing `T'.
The title line tells you how many nucs are selected and how many aren't.


Nucs can be `selected', which just means that a special flag is set
within them. As a part of the nuc this flag is hereditary and will not
be reset by brew without that you ask for it. The flag has no meaning
at all for brew, it is a tool for the user to use for whatever he
likes.

The feature has similar uses as the `maybe-do' functions (*Note
Configurable actions::), but there are some differences:

   * `Persistence'. A nuc once selected stays selected if you do not
     de-select it somehow. This is not always the case with nucs
     fulfilling a certain condition at one moment. At a later moment
     the same nuc might very well fail to fulfil the condition.

   * `Combinations'. The possibility to add, remove and invert
     selections on various (sub) groups of nucs depending on different
     conditions one after another let's you build very complex subsets
     much more easy than you could with a single condition.

   * `Heredity'. The fact that selection status gets transmitted to
     the descendants opens the door to uses that would not be possible
     with the other similar features.


Menu features:

   * `show selected'. Show a world map where all selected cells are
     coloured.

   * `colour'. Configure colour of selected cells in the map described
     above. The default is `red'.

   * `deselect all'. Clear all selections of all cells.

   * `toggle selections'. Invert selections of all nucs.

   * `scan SELECTED nucs'. Statistical informations about all selected
     nucs. (*Note Scanning nucs::).

   * `scan ALL nucs'. Statistical informations about *all* nucs for
     comparisons.


There are two interfaces to the `maybe-do' feature, one for changing
selections based on a condition, the other to do configurable actions
on all selected nucs (*Note Configurable actions::).

   * `Change selections'. This interface gives you the possibility to
     `select', `de-select', `toggle (invert) selection' on all nucs
     fulfilling a freely configurable condition. Click `DO IT' to
     actually change selections in the configured way.

   * `DO on selected nucs'. This interface let's you configure an
     action to be taken on all selected nucs. The condition part
     (being selected) is (invisibly) preset already. Click `DO on
     selected nucs' after configuring to trigger the action.




File: brew.info, Node: World menu, Next: World list menu, Prev: Menu select nucs, Up: Users manual

World menu
==========

This menu gives informations and interfaces to some world wide
settings of the current world. You come here from brew main screen by
pressing `W'.

The menu title line tells you how many dimensions of what size this
world has.


   * `Name'. The first line starts with the worlds name. Select and
     change to whatever you like.

   * `3/5'. Would say that you are in world # 3 of 5.

   * `SELECT'. Change to another world. *Note World list menu::.

   * `REMOVE'. Lets this whole world and all it's cells disappear. The
     compiled genomes will persist, of course (genomes on trial will
     disappear if they do not co-exist in another world, though).

Following items are purely informative, you cannot change them:

   * `spots'. Number of spots in this universe.

   * `living'. How many cells life in this world at the moment.

   * `on trial'. How many cells are currently on trial. Selecting this
     item will show a map of nucs on trial (if any).

   * `selected'. Number of selected cells. Selecting this item will
     show a map of selected nucs (if any).

   * `compiled'. Number of compiled genomes since start of this
     evolution.

   * `max items'. Longest generated genome so far.

   * `qualities'. Number of spot qualities (r/w variables local to the
     spot). (*Note Variable names::). This is configured at compile
     time.

   * `properties'. Number of spot properties (r/o variables local to
     the spot). (*Note Variable names::). This is configured at
     compile time.

   * `secrets'. Number of spot secrets (variables local to the spot,
     invisible to the genome). (*Note Variable names::). This is
     configured at compile time.


The next few lines give information about dimensionality and size of
the current world and let you configure visibility ranges for each
dimension. *Note World size and visibility::.


The following three entries let you configure special actions that
might be needed for some sort of experiments:

   * `spot do'. This function gets called on each spot (after
     diversifying spot variables) before waking up the nuc eventually
     living there. The default function is a noop.

   * `nuc do before'. On inhabited spots this is called (after `spot
     do') just before waking up the nuc. The function defaults to
     noop.

   * `nuc do after'. On inhabited spots this is called after the nuc
     has finished it's job. It is executed wherever a cell was woken
     up, even if the cell died or moved away in this life step. So if
     you write functions to put in here yourself check if the nuc is
     still here before you refer to nuc intern variables). Default is
     a noop.

   * `step do before'. Action done when starting a new step. Default
     is a noop.

   * `step do after'. Action done after finishing a step. Default is a
     noop.


Some interfaces to other world related functions:

   * `Scan world'. Interface to the world scan functions over all
     spots. (*Note Scanning spots::).

   * `Scan nucs'. Interface to the nuc scan functions over all living
     cells. (*Note Scanning nucs::).

   * `Delete all'. This clears the whole current world, initialises
     all world variables, sets all spot variables to zero and removes
     all nucs. After calling this function you have to set at least
     one individual to be able to do something useful. (*Note
     Individuals menu::).

   * `Big bang'. World menu only deals with the current world. There
     can be multiple worlds though, each one having her own structure
     and configuration settings. This leads to the menu to define and
     create another world. (*Note Big Bang menu::).


The rest of the world menu let's you define a action to do on spots
that meet a certain condition (`maybe-do' feature working on spots).
You must configure the condition which spots will be treated and
define the action to take. Then you can select `DO something on some
spots' to trigger the action. Like always in similar cases you can
select amongst simple or more complex conditions and actions or define
your own in Forth program source. On inhabited spots (only) you can
access nuc variables too. (*Note Configurable actions::).




File: brew.info, Node: World list menu, Next: Big Bang menu, Prev: World menu, Up: Users manual

List of worlds
==============

You get to this menu by pressing `O' (like `Other worlds') in brews
main screen. It is a list of all existing brew worlds. Select a world
from the list to enter it.

Brew let's you change world names, and shows you some geometry
information for each world.

   * `clone'. Clone this world including all it's cells and enter the
     cloned one.

   * `remove'. Delete this world and remove all it's inhabitants.

   * `save'. Save this world (without it's cells) to a huge text file.

If you want, you can also create new worlds from this menu.


BTW: As a shortcut in brews main screen you can switch to another
world by pressing the number key of the world you want to enter.




File: brew.info, Node: Big Bang menu, Next: System menu, Prev: World list menu, Up: Users manual

Big Bang menu
=============

This menu let's you define and create another world.

You get here by pressing `B'+`B' (capital `B' twice) from brews main
screen.

The upper half of the menu screen shows you the settings of the
current world, the lower half let's you configure and create another
one. After creating a new world the new one will be the current one.


The second half is the main part of the menu, here you define the
geometrical structure of your new world and the visibility ranges of
each dimension and finally create it. Select `Clone geometry' for same
geometric structure as the current world has.

* Menu:

* World size and visibility::   Current worlds geometry and visibility.
* Big Bang::                    Define and create a new world.

Note that you must configure the settings of the newly created world
to be able to do something with it. At least you must set some living
cells into it to start a new evolution. (*Note Individuals menu::).
Also check visibility ranges in the upper menu half, and configure
them as you like.




File: brew.info, Node: World size and visibility, Next: Big Bang, Prev: Big Bang menu, Up: Big Bang menu

World size and visibility
-------------------------

Brews virtual world can have from one to five (or more) dimensions of
any size. Often only a part of the world will be displayed. You can
configure visibility range for each dimension. Brew does no zooming in
world display, so visibility range in the first two dimensions cannot
exceed screen size (minus info line as last screen line), but of
course it can be like a visibility window in a bigger plane. Higher
dimensions are just projected into the plane taking into account
visibility range of all dimensions. So a cell of a four dimensional
world at coordinates (a,b,c,d) would be displayed at (a,b) provided
all coordinates fall into the visibility range of it's dimension.

If you want to display a world of more than two dimensions you can
choose to show only one layer or a range of layers one over the other.
In the latter case it might be helpful to delay display of each
individual layer to have a chance to understand the three dimensional
structure while the display is building up. The layers can be
transparent or opaque on spots where no cell lives, depending on the
background being displayed or not on empty spots. Background will
always have to be displayed on the first displayed plane, but can be
switched off later. As this sounds all more complicated than it is,
there are some examples further down.

For each dimension you have a line like this:
1 dimension  spots: 80  visible from: 0         to: 80

The entries have the following meaning:

   * `n'th dimension'. Number of dimension.

   * `spots'. Size of dimension range. If `spots' is 80, coordinates
     would go from 0 to 79.

   * `visible from'. Start of visibility range, lowest visible
     coordinate.

   * `visible to'. End of visibility range, highest visible
     coordinate. Note that in the above example visibility would not
     been switched off, because coordinate 80 does not exist and is
     never reached so. This saves some time on a screen where
     everything is visible anyway.

If you have more than two dimensions you will see the following two
entries:

   * `backgr.off'. Coordinate of third dimension after which
     background displaying is switched off. Up to this coordinate
     layers are opaque, after they become transparent.

   * `Delay displaying layers'. Delay (theoretically in milliseconds)
     after displaying a (third dimensions) layer. A pause can help to
     understand the displayed three dimensional structure.


Examples:

Two dimensional world, screen sized on the Linux text console. Fast
and everything is visible: (Might be too small for some types of
experiments).

Current world           spots: 1920
1 dimension  spots: 80  visible from: 0         to: 80
2 dimension  spots: 24  visible from: 0         to: 24
Delay displaying layers:        0


Tree dimensional world, only middle layer visible:

Current world           spots: 19200
1 dimension  spots: 80  visible from: 0         to: 80
2 dimension  spots: 24  visible from: 0         to: 24
3 dimension  spots: 10  visible from: 4         to: 4    backgr.off: 4
Delay displaying layers:        0


Tree dimensional world, all layers visible. Brew displays one layer
after the other, all opaque, and pauses a bit after each layer:

Current world           spots: 19200
1 dimension  spots: 80  visible from: 0         to: 80
2 dimension  spots: 24  visible from: 0         to: 24
3 dimension  spots: 10  visible from: 0         to: 10    backgr.off: 10
Delay displaying layers:        1000


Tree dimensional world, all layers visible. Brew displays one layer
after the other, the first one opaque (to hide previous display), all
the following transparent. Pauses a bit after each layer:

Current world           spots: 19200
1 dimension  spots: 80  visible from: 0         to: 80
2 dimension  spots: 24  visible from: 0         to: 24
3 dimension  spots: 10  visible from: 0         to: 10    backgr.off: 0
Delay displaying layers:        2000




File: brew.info, Node: Big Bang, Prev: World size and visibility, Up: Big Bang menu

Make a Big Bang
---------------

Here you define the geometry of your new world.

   * `Dimensions'. Dimensionality of the new world. While it is often
     advisable to select a two dimensional screen sized world for
     efficiency reasons you can define worlds from one to five (and
     more) dimensions. Choosing a exaggerated dimensionality will soon
     eat up a lot of memory and CPU power and slow down things too
     much though. You can have as many worlds as you like (provided
     you have enough memory) and each one can have a different
     dimensionality and size, but they all share the same spot
     structure (number and classes of spot variables) which is
     configured at compile time.

   * `dimension range'. Size of range for each dimension. The
     coordinates in this dimension will go from 0 to n-1. Brews world
     wraps at it's borders, if a cell moves in one direction and
     leaves the range in a dimensions range it will reenter the world
     from the opposite side.

   * `make a Big Bang'. After defining dimensionality and ranges for
     all dimensions this entry will appear. Choose it to actually
     create your new world. After the big bang the new world will be
     empty and all the spot variables will have a zero value. The new
     world will automatically become current. You can configure
     visibility ranges now.


In Linux text console (which is the main platform brew is developed
for) it is a good choice to make worlds two dimensional and 80 * 24
sized, to fit the screen.




File: brew.info, Node: System menu, Next: Log files menu, Prev: Big Bang menu, Up: Users manual

System menu
===========

This is the menu for brews system wide settings.
You get there by pressing `S' in brews main screen.


   * `Running in WORLD mode' or `LINEAR mode'. Switches if the cells
     do have a virtual location or not. (*Note Run modes::).

   * `Reset brew'. Reset brew by reading `brew-defaults.fs', do a
     `free-field' and reading `brew-init.fs' again. If you have
     included your personal initialisation files you might want to
     include them too.

   * `Brew version'. Give detailed information about versions of
     different brew parts and about some compile time options. Please
     include this output in bug reports.

   * `Random generator'. Switch random generator and initialise it.
     Sometimes the random generator and/or it's seed has an enormous
     influence on the results. Sometimes the same result turns up
     sooner or later quite independent of the used random generator.
     Brew gives you the possibility to try that out. *Note Selecting
     functions::, for a method to see the definitions of the used
     random generators.

        * `random-BRODIE'. Use the random generator given by Leo
          Brodie in his excellent Forth introduction book `Starting
          FORTH'.

             * `Random seed'. Current value of the random seed.

        * `random-generalised'. Use a more generic random generator.

             * `Random seed'. Current value of the random seed.

             * `Random generator'. Value used internally for random
               number generation.

   * `Can cells change qualities of the future?'. Genes can change
     spot qualities (*Note Variable names::). If this switch is ON the
     change survives a time step, otherwise it only takes effect in
     the present life step

   * `Cell division moves cell mother too?'. Normally the mother cell
     does not move when it divides, only the child is on a new
     location. This switch changes this behaviour. This option exists
     only in `world mode'.

   * `Cell division diversifies cell mother too?'. While the child's
     variables are always possibly diversified the mothers are not.
     This switches diversification of the mother cell.

   * `Cell division mutates cell mother too?'. Mutation normally can
     only happen on the child, but not on the mother cell of a cell
     division. This switch changes that.

   * `Order to call the spots'. To run brews world through a time step
     all the spots are called once, one after the other, at least
     normally. The order to call the spots can be configured here.
     This option exists only in `world mode'.

        * `sequential calling spots forwards'. This is the normal
          setting, it's fastest (for technical reasons) and the only
          setting recommended for 3D views.

        * `sequential calling spots backwards'. This is much slower
          then the other way round and there's no reason beside
          testing influence of this parameter to set it to this value.

        * `randomly calling as many spots as there are'. This is
          probably the slowest setting, but it can be interesting
          sometimes. Note that brew just calls the right number of
          random spots, not caring about if a spot get's called
          several times or if it's omitted.

        * `alternate direction, starting forwards'. This calls the
          spots sequentially, starting forwards. Quite slow.

        * `alternate direction, starting backwards'. This calls the
          spots sequentially, starting backwards. Quite slow.

   * `Save brew variables'. Save all brew variables which means saving
     most initialisations and configurations. Note that cells (edited,
     mutated or set to a spot) are *not* saved by this function. The
     variables are saved as Forth program source. You are prompted for
     a file name relative to `brew/OUTPUT/'.

   * `Save world'. Save all world and spot data to a Forth text file.
     Writes a *huge* file.

   * `Save all nucs'. Save all nucs data to a Forth text file, which
     can get huge, depending on the number of nucs and nuc variables.
     If you include this file later on the nucs will be reproduced and
     set to the same spots they where before, replacing other nucs on
     these spots. Genomes must be defined before, though. Use with
     care.

   * `Include file'. Select a file to be included. Brew does not check
     what you are doing here, it's completely at your own risk. In
     this brew version this also is used to include experiments, which
     might change in future versions. (*Note Experiments::).

   * `World scan'. Statistics about all spot variables. (*Note
     Scanning spots::).

   * `Nuc scan'. Statistics about all nuc variables. (*Note Scanning
     nucs::).

   * `Function keys'. Configure function key bindings.

   * `Use ekey for key input'. If your brew is compiled with ekey
     support you can switch this on and off here in case of input
     difficulties. (In case it only works when switched off, you
     should fix the problem or switch it off as a compile time
     option).

   * `Cursor wraps at borders' or `Cursor stops at borders'. Switch
     between cursor wrapping or stopping, when moving over a screen
     border.

   * `Fix screen size'. Include `configure-console.fs' to fix console
     size problems.

   * `Fix cursor moving problems (beeping)'. If you have problems
     moving the cursor with the arrow keys you can try this function.
     Hope it helps.

   * `Manual'. Call the external manual reader on top node. See the
     entry `Documentation type' below, to switch between info and
     html.

   * `Documentation type'. Select between using `info' or a html
     browser as context sensitive documentation reader.

   * `reader'. Displays information how the docu reader gets called.
     Intended to track problems calling context documentation.

   * `QUIT brew'. Quit brew cleaning up temporary files and informing
     you about produced output files, if any.


The identity number displayed in the title line can be helpful to
identify output files, as the number get's included in file names.


When brew is started with special options (i.e. `COUNTING-WORDS' *Note
Programming tool files::) additional items might show up in system
menu.




File: brew.info, Node: Log files menu, Next: Code file menu, Prev: System menu, Up: Users manual

Log files menu
==============

This menu allows you to switch very detailed what brew should write in
it's log files and what not. You come to this menu by pressing `L' in
brews main screen.


Brew can write very detailed log files about what it does. Actually
this elaborated logging facility is a by-product of my debugging
activities ;-) Debugging evolutionary programming can be quite a
task....

Log files can be an excellent help when you want to understand what
actually happens during an evolutionary session. If you want to do
fancy things like drawing phylogenetic trees of the generated genomes
or such, log files will be a big help. You will probably need to write
some perl scripts to be able to process that amount of data though.

Logging slows brew down a lot, of course.

Please realize that brews log files can grow really big; don't forget
to switch logging back off and delete the log files after use, or your
brand new gigantic hard drive will be full very soon....

I will not explain the format of log files here, as this would take
too much room and time. Just put logging on for some time, if you are
interested in it. I think you should be able to understand the result.


Most of the menu screen is covered by switches what to put in the log
file:

   * `All'. This puts all the switches on. Don't do this ;-)

   * `Most'. This puts nearly all the switches on. Don't do this ;-)

   * `Nothing'. Switches logging back off.

   * `Some'. Switches some basic information on.

   * `spot'. Log when doing a new spot.

   * `birth'. Log each birth of a cell.

   * `death'. Log death of a cell.

   * `organs'. Log value of organs (and other cell variables) before
     and after waking nucs.

   * `meal'. Log how much food each cell got in each life step.

   * `costs'. Log live and gene code costs.

   * `trial'. Log nucs on trial.

   * `movement'. Log movements of nucs.

   * `emergency'. Log population emergencies.

   * `pop-control'. Log working of population control.

   * `step'. Log time steps.

   * `spot-vars'. Log value of spot variables before and after waking
     nucs.

   * `random'. Log state of random generator.

   * `user'. Log user interactions (big brother is watching you).


     Please note that the following mutation logging switches depend
     on each other in ascending order. You cannot switch a lower order
     item off before clearing the higher order switches.

   * `mutation'. Log mutations. (You can't switch that off if a more
     detailed logging switch is on).

   * `m-type'. Log type of mutations. (You can't switch that off if a
     more detailed logging switch is on).

   * `m-some'. Log mutation working with some detail information. (You
     can't switch that off if a more detailed logging switch is on).

   * `m-more'. Log mutation working with a lot of detail informations.
     Can be configured away at compile time for speed reasons. (You
     can't switch that off if a more detailed logging switch is on).

   * `m-much'. Log a real lot of details about the inner working of
     mutations. Can be configured away at compile time for speed
     reasons. (You can't switch that off if a more detailed logging
     switch is on).

   * `log-m-extra'. Log extensive about the detailed inner working of
     mutation. This option is not compiled in by default, only on
     request.


   * `log-empty-spots'. Log spot variables and the like even for empty
     spots. This option is only interesting for debugging and writes
     an awful lot of information. Don't switch it on. This option is
     not compiled in by default, only on request.


   * `Log file'. Log file name. Defaults to
     `brew/OUTPUT/log/brew.log'.

   * `Writing code file'. Link to the code file menu: Write generated
     program code to a file.

   * `Log state'. Write current brew state to the log file in the same
     form as it would appear in a configuration or record file (that
     is as Forth code).


*Note Scrolling menus::.




File: brew.info, Node: Code file menu, Next: Record and Playback, Prev: Log files menu, Up: Users manual

Writing generated program code to a file.
=========================================

Brew can write the produced Forth program code to a file, the so called
`code file'. Code file have normal Forth syntax and should compile
the defined genome when they are included. Beside the code brew can put
some more information (i.e. stack type comments) in the file. This is
the place to configure that.
You'll get here from brews main screen by pressing first `m' and then
`c'.

On a Linux system you can watch mutation and selection at work in real
time by switching to another console and say `tail -f
OUTPUT/FORTH/gene-code.fs'.


The menu gives you the following options:

   * `Writing a human readable code file to the hd is off/ON'.
     Switches writing code files completely off. If switched off, the
     menu will not show any other options.

   * `Code file'. Name of the code file relative to `OUTPUT/FORTH/'.
     The default code file name is `OUTPUT/FORTH/gene-code.fs'.

   * `file on trial SUCCESS'. If you switch that ON genomes will be
     written to the code file when they successfully survive the so
     called `trial phase'. Normally this is the useful setting for
     this switch. The menu will show you some more options when you
     switch this one on.

   * `file ALL MUTATIONs'. Switching this ON will result in putting
     every generated genome in the code file at the time mutation
     creates them. Most of them will be useless or even absurd code.
     As there is more information available during the mutation
     process then after trial phase there are some more choices what
     to put in code files. I don't think these informations are too
     interesting to normal brew users though (But then I don't think a
     `normal' person would ever use brew anyway ;-)


Switches what to put in the code file:
(The first three are compound switches).

   * `ALL'. Switches all information that can be put into code files
     on. It's not that much as with log files, but it makes code files
     quite unreadable. It's more a debugging help.

   * `nothing'. Shortcut to switch everything off if you want to
     restart configuring the individual switches. If you don't want
     any code file at all use the very first option of the menu
     instead.

   * `CODE & stack'. Put Forth program code together with stack type
     symbol comments in the code file. This is usually the recommended
     setting, as you'd better collect other information from the log
     files. Brews stack type symbol comments are similar but not equal
     to the usual Forth stack comments. (*Note Stack type symbols::).

   * `STRUCTURE only'. Include only structure building words like `IF'
     `ELSE' and `THEN'. All other code is omitted. For quick
     inspection of the structure of genomes. You can't compile the
     resulting pseudo code, of course.


   * `code'. Normally you'd want code to be in the code files, won't
     you?

   * `stack'. Put stack type symbol comments, similar but not equal to
     the usual Forth stack comments into the code file. I think this
     makes the code a bit easier to read (*Note Stack type symbols::).

   * `mutation-type'. You might be curious what type of mutation
     generated the genome in question. This switch allows this
     information to be written to the code file.

   * `structures'. If you switch this on, but `code' off, you will see
     structure building words, without code in between.

   * `frames'. By `frame' I mean a gene code segment like a
     conditional clause, an inserted sequence or similar. Frames can
     be nested at will as long as a nested frame is always contained
     as a whole in the other one.

   * `depth&cost'. Informations about minimal and maximal stack depth
     so far and about accumulated code costs go into the code file.

   * `step,spot,id'. Put information about time (step), location
     (spot) and mother cell (id) where the mutation happened into the
     code file. This makes it especially easy when you want to
     associate with informations from log files.

   * `item-numbers'. Put a item number for each used gene primitive.




File: brew.info, Node: Record and Playback, Next: Compile time options, Prev: Code file menu, Up: Users manual

Brews record and playback feature.
==================================


You get to the Record and Playback menu by pressing `R' from brews
main screen.


Evolutionary programming can be mean: You set up a new experiment,
make some preliminary tests with a few options and see exciting
results within very short time. Then you try to find even better
defaults, only to realize that the defaults you took have been very,
very lucky, but unfortunately you have forgotten them. If only brew
could remember them for you....

Or you have done a lot of configuring and want to do a series of
experiments starting from that point, but you don't want to do all
this configuring all over again and again....

For such situation brew has a feature to record and playback just
about every user interaction possible in brew (It will even catch a
lot of things you might have configured using configuration files).

If you want the thing to work it will be enough in most cases just to
switch recording on. This must be done *before* you put any cells into
the play. Brew will automatically record brews state in the moment you
switched recording on, catch and record every change you do to this
state and every command you pass to brew.

Brews record files are ordinary Forth source text files which can be
edited by hand of course.

Use brews recording feature
   - to make configuration files by configurating through the menu
     interface and saving the result as a record file.
   - to record evolutionary sessions to be able to replay them, try
     variations or such.
   - just in case you select some very lucky starting conditions by
     accident. Recording does not cost much. As it only saves user
     interactions it has nothing to do during the actual evolutionary
     process and does not slow it down or so. So you can switch it on
     just in case....
   - to record a evolutionary session as a benchmark for your hardware
     or Forth system. There are some special tools to make benchmarks.
   - to make a demo which you'll send to me that I can see what people
     do with my program ;-)

* Menu:

* Recording from scratch::      How to record an evolutionary session.
* Record after playback::       How to continue recording on an existing file.
* Record benchmark::            Recording to be used as benchmark.
* Playback::                    Playing back a recorded session.




File: brew.info, Node: Recording from scratch, Next: Record after playback, Prev: Record and Playback, Up: Record and Playback

How to record an evolutionary session starting from scratch.
------------------------------------------------------------

When you switch recording on in the `Record and Playback menu' brew
saves it's current configuration to the record file, including all the
settings you changed trough the menu interface or configuration files.
It does *not* save the current state of the world and it's inhabitants
though. If you want to record an evolutionary session you must start
with an *empty* world. So brew clears the world when you switch
recording on and includes a command to do so in the record file. So if
you play back the file later it will start with an empty world too.
Note that in both cases all the contents of the current world (prior
to switching recording on) are lost.

   * `Record'. Switch recording on here to restarts a session from
     scratch. Brew removes all inhabitants of the current world and
     resets all world variables. It removes all other worlds
     completely.

   * `Please give record file name'. Brew reacts by asking you for a
     file name relative to `OUTPUT/rec-play/' and defaults to
     `OUTPUT/rec-play/brew-recorded.fs'.

   * `Now you should select an individual and set it to a spot'. Brew
     informs you now about the next necessary step and puts you in the
     individuals menu to select and eventually edit an individual.
     (*Note Individuals menu::).

   * `Now go back to the main screen and set the individual'. Brew
     guides you here, just do what it tells you to do ;-)

   * After that you continue just as you would have done without
     recording. You can use all the usual brew features and functions
     and everything (with very few exceptions *Note Using Forth in
     menus::) should be recorded automatically now as long as you do
     not switch recording off. Everything should be re-played exactly
     as it happened during recording if you choose the record file
     later on as a playback file.

The menu now looks like this:

   * `Record is ON'. Switch it off here when you'll have finished (but
     not before that).

   * `Record file: brew-recorded.fs'. That's just informative now. You
     cannot change that during recording.

   * `assert state (for benchmark creation)'. Put an entry about the
     current state of evolution including a check sum over all spots
     and one over all nucs which will be chequed at playback time.
     Brew will tell you if something went wrong during playback,
     silently proceed otherwise. For benchmarks and for debugging.

        * `You can give a comment'. The comment will be displayed
          together with the information if everything went ok or not
          at playback time. Use a *very short* description about what
          happened just before the state check.

   * `save state (normally only diffs get saved)'. This saves *all*
     brew variables, not only those that have changed. Use this to
     create initialisation files, but also if you intend to edit
     (especially cut) the recorded file later on by hand.

   * `record comment'. Insert remarks as a comment into the record
     file. These notes will *not* be displayed during play back.

        * `Give a comment to be included in the record file' Enter
          your text here.

   * `message input'. Edit a short message that will be displayed in
     the last line (`info line') during playback.

        * `Give a message to be displayed during playback'. The
          message must be shorter than one full line.

        * `For how many steps do you want the message to be
          displayed?'. Give an estimated number, you can always edit
          that in the record file by hand, if you don't like the
          result.




File: brew.info, Node: Record after playback, Next: Record benchmark, Prev: Recording from scratch, Up: Record and Playback

How to append to an existing recorded file.
-------------------------------------------

After playing back a recorded evolutionary session the record/playback
menu gives you the choice to continue recording, appending code to the
file. You must do this as the very first action after playback, after
the option will vanish from the menu. Brew must know the exact state
of everything when recording starts.

Please note, that the evolution may not use *anything* else (like
genomes, created other worlds or somesuch) than what was created
during the playback of the file in question. So you best restart brew,
play back the file and switch to recording, if you want to extend an
existing record file.




File: brew.info, Node: Record benchmark, Next: Playback, Prev: Record after playback, Up: Record and Playback

Recording to be used as a benchmark
-----------------------------------


Brew has some special features to make it comparatively easy to create
very complex benchmarks.

   * `Record benchmark'. Select this if you want to record an
     evolutionary session as benchmark.

   * `Please give record file name'. Same as for normal recording.

   * `Now you should select an individual and set it to a spot'. Same
     as for normal recording.

   * `Now go back to the main screen and set the individual'. Same as
     for normal recording.

   * Now you continue as usual, but you might spread some assert state
     entries at critical places to make sure the bench plays right.

   * `Finish benchmark'. Do *not* switch recording off the normal way
     when you are done, but select this entry instead.

        * `Saving code to assert current brew state to:
          brew-recorded.fs You can give a comment'. A final assert
          state entry is appended to the record file and you should
          give a very short comment that will be displayed together
          with the result of the state check.

        * `Shall I append code for benchmark start from command line?
          y/n'. This would append code to `maybe-run-benchmark.fs' to
          recognise the new bench. See source for more information.

        * `Give the benchmark name'. Please name your benchmark here.


Brew now gives you a short information about what it has done, like:

I'm appending the following line to maybe-run-benchmark.fs
[DEFINED] my-new-bench [IF]   include benchmarks/my-new-bench.fs      [THEN]

I copy the file to the benchmark directory:
benchmarks/my-new-bench.fs

After that you can execute the benchmark from the command line if the
Forth you use has an option to interpret a string on start up. It is
enough to `CREATE benchmark-name' as in `gforth -e "CREATE
my-new-bench" brew.fs' and brew will start the bench and terminate
when it's finished. So startup time (including brews compilation) is
*included* in the measured time. This is intentional.

Very likely you must edit the benchmark file by hand, i.e. you will
probably like to switch display off during the bench. Note that brew
has spread comments throughout the file that try to give you hints,
where you might want to edit something.




File: brew.info, Node: Playback, Prev: Record benchmark, Up: Record and Playback

Playback a recorded evolutionary programming session.
-----------------------------------------------------


Select `Playback' in the `Record and Playback menu'.

Choose a playback file.
(If you don't, the default record file name is probed).

That's it....


To interrupt playback just press a key. Brew will ask you if you want
to continue (`c') or quit (`q').




File: brew.info, Node: Compile time options, Next: Menu function keys, Prev: Record and Playback, Up: Users manual

Compile time options
====================

THIS NODE DOES NOT EXIST YET ;-)

So you'd better read `compile-options.fs'....




File: brew.info, Node: Menu function keys, Next: Menu Demos, Prev: Compile time options, Up: Users manual

Configuring function key bindings.
==================================

Here you configure function key bindings.
You reach this menu by pressing `K' in brews main screen.

Function keys are active in brews main screen and a few other places.
(Generally activating it could possibly confuse brew in some situations.

If function keys don't work on your system try toggling `use-ekey'.
This might help.

The menu lets you associate each function key with an action.
Function key bindings are active in this menu, so you can try out the result.
You can select amongst the following functions:

   * `noop'. Do nothing.

   * `context-help'. Show the manual node corresponding to the
     context.

   * `show-key-bindings'. Show active key bindings as pressing `k'
     would. *Note Example key bindings::.

   * `|feed-world|'. Feed the world an extra food portion. *Note Food
     menu::.

   * `nuc-scan-menu'. Gather statistical informations about all nucs.
     *Note Scanning nucs::.

   * `spot-scan-menu'. Gather statistical informations about all
     spots. *Note Scanning spots::.

   * `menu-step-display'. Configure brews main screens display when in
     step display. *Note Step display menu::.

   * `menu-nuc-subsets'. Do something on all nucs meeting a certain
     condition. *Note Menu nuc subsets::.

   * `menu-select-nucs'. Select or de-select nuc subsets. *Note Menu
     select nucs::.

   * `menu-current-genomes'. Examine different currently living
     genomes. *Note Menu current genomes::.

   * `food-menu'. Configure food supply. *Note Food menu::.

   * `menu-population-control'. Configure population control. *Note
     Population control::.

   * `diversification-menu'. Configure global and nuc/spot local
     variable diversifications. *Note Diversification menu::.

   * `color-menu'. Configure colors in brews main screen. *Note Color
     menu::.

   * `mutation-menu'. Configure mutation. *Note Mutation menu::.

   * `big-bang-menu'. Create a new world. *Note Big Bang menu::.

   * `world-list-menu'. Select world from worlds list. *Note World
     list menu::.

   * `world-menu'. Configure world wide options. *Note World menu::.

   * `actual-pool-menu'. Configure actual gene pool. *Note Actual pool
     menu::.

   * `gene-pool-menu'. Select gene pool. *Note Gene pools menu::.

   * `individuals-menu'. Select and edit predefined individuals to
     release in the world. *Note Individuals menu::.

   * `toggle-display-&-go'. Switch display type in brews main screen
     without stopping evolution. (Same as the `t' does). *Note Display
     modes::.

   * `do-FORTH'. Enter Forth program source and interpret it. *Note
     Using Forth in menus::.

   * `toggle-anything'. Toggle a flag variable called `anything',
     which you can use as you like. `anything' is not used by brew
     itself.

   * `function-key-menu'. Go to this menu.

   * `display-menu'. Configure display of brews main screen. *Note
     Display menu::.

   * `code-file-menu'. Configure writing generated code to a file.
     *Note Code file menu::.

   * `rec/play-menu'. Record your interactions with brew or replay
     your session. *Note Record and Playback::.

   * `log-menu'. Configure writing log files. *Note Log files menu::.

   * `system-menu'. Configure system wide options. *Note System
     menu::.

   * `menus-menu'. Go to brews super menu. *Note Menus menu::.

   * `|goodbye|'. Quit brew.




File: brew.info, Node: Menu Demos, Next: Experiments, Prev: Menu function keys, Up: Users manual

Some demos
==========

Here you can select a few demos.

As brew currently changes very much there are not too many of them at
the time being....

There should be a `default' demo, which explains default brew
initialisation of the brew version you are running.




File: brew.info, Node: Experiments, Prev: Menu Demos, Up: Users manual

Experiments.
============

Experiments are a more advanced kind of demos.

Currently there are only some simple test experiments, sorry.


While ordinary demos often lead you through an example evolution
`experiments' usually just initialise brew and let you run the
evolution on your own. You should have some experience with brew to
run an experiment.

Please read the source files in `INPUTS/experiments/.../' for
information what's going on in the different experiments.

In this brew version experiments are started by including an
*initialisation* file from the experiments subdirectory in
`INPUTS/experiments/'. The initialisation file will include source
files for the experiment on it's own.


*Note System menu::, for how to include files.




File: brew.info, Node: Programmers manual, Prev: Users manual, Up: Top

Programmers manual
******************

sorry... THIS CHAPTER DOES NOT REALLY EXIST YET ;-)

Please read the brew source. There are a lot of comments meant to be
helpful. Feel free to ask me questions.

* Menu:

* Files::                       File overview.




File: brew.info, Node: Files, Prev: Programmers manual, Up: Programmers manual

Brews files overview
====================

* Menu:

* Directory tree::              Brews default directory structure.
* Program files::               Program source files.
* Genes files::                 Gene primitive files.                 
* Configuration files::         Initialisation and configuration.
* Output files::                The `brew/OUTPUT/' directory.
* Temporary files::             Files in `brew/OUTPUT/tmp/'.             
* Informative files::           Documentation and informations.
* Programming tool files::      System adaption and profiling.
* Benchmark files::             Benchmarks and benchmark results.
* Console and key setup::       Configuring console size and keys.
* Bugs and Debugging::          Debugging and known bugs.




File: brew.info, Node: Directory tree, Next: Program files, Prev: Files, Up: Files

Brews default directory tree
----------------------------

   * `brew/INPUTS/' Directory for input files (except configuration
     files). You can change it by defining `input-dir' as compile
     option.

        * `brew/INPUTS/genes/' Directory for genes (of the new
          gene/mutation version). Predefined relative to `INPUTS/'.

        * `brew/INPUTS/experiments/' Directory for experiments (*Note
          Experiments::), each one having it's own subdirectory, which
          are not listed here.

        * `brew/INPUTS/extensions/' Directory for optional extensions.

             * `brew/INPUTS/extensions/debugging/' Directory for
               optional debugging extensions. See the README files in
               the directory.

        * `brew/INPUTS/individuals/' Directory for individuals.


   * `brew/OUTPUT/' Directory for all output files. You can change it
     by defining `out-dir' as compile option.

        * `brew/OUTPUT/FORTH/' Directory for Forth code text files
          created by brew. Predefined relative to `OUTPUTS/'.

        * `brew/OUTPUT/rec-play/' Brew puts it's recorded files (as
          Forth source text files) here. Predefined relative to
          `OUTPUTS/'.

        * `brew/OUTPUT/log/' Brews log file directory. Predefined
          relative to `OUTPUTS/'.

        * `brew/OUTPUT/tmp/' Temporary brew files. Predefined relative
          to `OUTPUTS/'. Brew also puts some special output files here
          telling you that it has done so.


   * `brew/texi/' Main documentation directory.




File: brew.info, Node: Program files, Next: Genes files, Prev: Directory tree, Up: Files

Brew program source files
-------------------------

   * `brew.fs' Main program file.

   * `system-dependent.fs' Fork to load system dependent adaptions and
     definitions.

        * `gforth.fs' Adaptions to Gforth.

        * `pfe.fs' Adaptions to pfe.

        * `iForth.fs' Adaptions to iForth.

        * `bigFORTH.fs' BigForth adaptions.

   * `common-words.fs' Words commonly found in many Forth systems.
     Define them if they are not defined in the used Forth system.

   * `basics.fs' Some basic definitions I use in my programs.

   * `advanced.fs' Some basic definitions which can't be defined in
     `basics.fs' yet.

   * `brew-basics.fs' Some basic brew words. Defining them early
     avoids some dependency problems.

   * `allocation-pointers.fs' Deals with allocated memory blocks that
     will possibly get resized.

   * `block-variables.fs' Attempt to get faster variables in memory
     blocks. Depreciated.

   * `blockVARIABLEs-brew.fs' Brew variables defined as
     `block-variables'. Depreciated.

   * `dp-speed-align.fs' Trying influence of aligning dictionary
     pointer on speed.

   * `memory-speed-align.fs' Aligning chunks of memory for speed.

   * `random.fs' Random number generators.

   * `lists.fs' Linked lists, possibly having multiple data fields.

   * `listed-masks.fs' Masks to be written as text (i.e. as Forth
     source).

   * `string-lists.fs' Lists containing stringbuf handles for dynamic
     string storage.

   * `string-replace.fs' Building tables of fixed strings and using
     them to replace strings by other strings.

   * `association-lists.fs' Lists of keys and associated data.

   * `probability-lists.fs' Lists with relative probabilities to be
     selected randomly.

   * `sorted-lists.fs' Build a sorted copy of a list possibly having
     multiple data fields. Sorting is done numerically on one of the
     data fields. Very simple minded insertion sort implementation.

   * `stringbuf-0.4.fs' Memory buffers originally implemented to
     concatenate strings and the like. Used in brew for many different
     purposes.

   * `simple-stringbuf.fs' Simple (fixed size) buffers for strings and
     the like. Maybe obsolete, as the new ordinary stringbuf version
     is much faster then the old one was.

   * `console-codes.fs' Cursor and color management for the Linux text
     console.

   * `screen-size.fs' Screen size constants (defaults).

   * `display.fs' High level brew display interface.

   * `keybuf.fs' Simple key buffering.

   * `user-IO.fs' Advanced keyboard I/O words.

   * `key-mapping.fs' Maps special key events to menu key codes.

   * `mouse.fs' Faked mouse interface on top of an old implementation
     for Atari. Waiting to be reactivated on Linux console.

   * `menu.fs' User interface as active text menus.

   * `fileselect.fs' Experimental simple file interface.

   * `maybe-do.fs' User interface to do quite arbitrary things on nucs
     or spots that meet a certain condition. Quite hairy code...

   * `worlds.fs' Virtual world. New version allowing multiple multi
     dimensional worlds of arbitrary size.

   * `world-loop.fs' Looping over all spots of the virtual world.

   * `world-spots-arrayed.fs' Spots implemented as arrays.

   * `world-spots-localized.fs' Alternative spot implementation with
     the intention to speed up things by localising spot data for
     cache consistency. On my system it's actually slower.... The
     current brew versions do not fully support this world
     implementation any more, but it might get reactivated, when it
     would give speed advantage on future processor designs.

   * `symbols-stack.fs' The mutation process selects it's genes doing
     simple type checking of the stack data that the genes work with.
     The types are mapped to one char stack type symbols. In old brew
     versions I used the data stack to play with these symbols. This
     implementation uses strings internally, but still looks like a
     stack.

   * `genes-0.3.fs' Newer gene/mutation implementation.

   * `mutation-0.3.fs' Newer gene/mutation implementation.

   * `gene-edit.fs' User interface to examine genes and whole genomes
     and to edit them by hand.

   * `gene-alternatives.fs' Some genes like `drop' or `swap' have type
     variants for data types like integer values and addresses. While
     mutation always will select the right variant, the user will
     probably just write `drop' or `swap' when he edits a genome by
     hand. So brew must be able to figure out what exactly was meant.
 
   * `gene-pool.fs' Gene pools with relative probabilities to be used
     by mutation.

   * `statistics.fs' ASCII bar graphs of statistical data.

   * `reporting.fs' Writing very detailed log files.

   * `manual.fs' Show manual node corresponding to the context.

   * `dynamic-key-bindings.fs' Interpreting this file adds some key
     bindings in brews main screen if the words are defined.

   * `mixed-old-stuff.fs' Mixed relicts from very early brew
     development still used in some old demos, benchmarks and the
     like.

   * `INPUTS/individuals/old-brew-individuals.fs' Individuals left
     over from very old brew versions.

   * `old-demos.fs' Old style demos not guaranteed to work in this
     brew version any more.

   * `maybe-run-benchmark.fs' Fork to run benchmarks if a benchmark
     name is defined from command line.

   * `bcompat-11-12.fs' Downwards compatibility to run
     `transit-11-bench-A' and `transit-12-bench'.

   * `debuging.fs' Words to help debugging.

   * `faked-genes.fs' Faking some genes for interactive debugging.

   * `compile-switches.fs' Compile features, leave them out or compile
     them with a run time switch. New and not used yet.

   * `scan.fs' New scanning mechanism. Not used yet.




File: brew.info, Node: Genes files, Next: Configuration files, Prev: Program files, Up: Files

Files with gene primitives
--------------------------

The gene primitives (of the new genes/mutation version) get loaded
from `brew/INPUTS/genes/'.

   * `basic-arithmetics.fs'
   * `basic-stack.fs'
   * `conditionals.fs'
   * `fetch.fs'
   * `insight.fs'
   * `nuc-parameters.fs'
   * `off.fs'
   * `organs.fs'
   * `qualities.fs'
   * `spot-properties.fs'
   * `global-integers.fs'
   * `global-dfloats.fs'
   * `store-normalised.fs'
   * `store.fs'
   * `float-basic-arithmetics.fs'
   * `float-more-arithmetics.fs'
   * `float-exp.fs'
   * `float-trigonometry.fs'
   * `mixed-maths.fs'
   * `transform.fs'
   * `dfloat-fetch.fs'
   * `dfloat-store.fs'
   * `float-stack.fs'
   * `float-organs.fs'
   * `float-parameters.fs'
   * `spot-df-qualities.fs'
   * `spot-df-properties.fs'
   * `float-comparison.fs'

*Note Gene primitives::, for more informations.




File: brew.info, Node: Configuration files, Next: Output files, Prev: Genes files, Up: Files

Initialisation and configuration
--------------------------------

Technically there is a big difference between compile time
configuration and run time configuration.

   * Compile time configurations influence the program being compiled.
     You can adapt brew to your needs compiling it at your liking for
     the experiment you want to make. You cannot change these options
     without quitting brew and restart it. If you miss some features
     described in this manual you probably haven't compiled them in.
     Just change compile options and they'll be there. Some features
     might slow down brew when compiled in, even if they are switched
     off at run time.

   * Run time options just give defaults to the program at startup
     that can be changed at any time.

Brew get's compiled each time at startup phase from source. The Forth
compiler is very fast, you probably won't even notice the time needed
for compilation on todays hardware and Forth systems. So the
difference between compile time options and run time options is not so
obvious at first glance.


Configuration files listed in their load sequence:

   * `compile-options.fs' Brew default compile time options as
     delivered with this brew version.

   * `my-compile-options.fs' Configuration file to put personal
     compile time options overriding defaults.


   * `brew-defaults.fs' Brew default initialisation after compilation.
     This file sets all the defaults but does not define individuals
     and does not set any into the current world. You can produce an
     alternative initialisation by configuring through the menus,
     saving it and copy the resulting file here or to a later
     configuration file.

   * `brew-init.fs' After the general defaults have been set, this
     file defines individuals and sets some into the current world.
     You can produce an alternative initialisation and copy the
     resulting file here or to a later configuration file.

   * `brew-options.fs' Configuration file to change some
     initialisations done by `brew-defaults.fs' or `brew-init.fs'.

   * `my-brew-options.fs' Configuration file to put personal adaptions
     and preferences.




File: brew.info, Node: Output files, Next: Temporary files, Prev: Configuration files, Up: Files

Brews output in `brew/OUTPUT/'
------------------------------

   * `brew/OUTPUT/FORTH/gene-code.fs' Default name for generated gene
     code as Forth text file. Including this file would compile the
     produced genes again.

   * `brew/OUTPUT/log/brew.log' Default name for brews log file.

   * `brew/OUTPUT/rec-play/brew-recorded.fs' Default name for recorded
     sessions as Forth text file. Including this file replays the
     session.




File: brew.info, Node: Temporary files, Next: Informative files, Prev: Output files, Up: Files

Brews temporary files in `brew/OUTPUT/tmp/'.
--------------------------------------------

Brew creates some temporary files in its `tmp/' directory which
defaults to `brew/OUTPUT/tmp/'.

If you leave brew like intended (*Note Getting started::) it will
remove most of them, but there are some exceptions:

   * `brew-identity'. On startup brew will create a file
     `brew//OUTPUT/tmp/brew-identity', if it does not exist already.
     It contains a integer number which is increased by one each time
     a new brew gets started. Brew uses it to define a unique identity
     for each running brew, and will append the number to many file
     names, making it possible to run multiple brew incarnations at
     the same time, without getting confused by the others temporary
     files.

   * `created-files_nnn' (where `nnn' is the identity number) contains
     a list of output files created during this brew session. The list
     will be displayed on exit and the files will not be removed
     automatically, nor will be the list. Do this by hand when you're
     done with it.

   * `Special output files'. Some special output files will default to
     brews temporary directory too, while others (more important ones)
     like record or code files have their own default directory. As
     mentioned above, brew will inform you about the location of
     produced files and leave this information in `created-files_nnn'
     for later reference.

   * `tmp-files_nnn' (where `nnn' is the identity number) contains a
     list of temporary files that will be removed on exit, as the file
     itself will be.




File: brew.info, Node: Informative files, Next: Programming tool files, Prev: Temporary files, Up: Files

Documentation, versions, development, conventions....
-----------------------------------------------------

   * `texi/' Main documentation directory.

        * `texi/brew.texi' Source of this documentation in texinfo
          format.

        * `texi/brew.info' This documentation in info format.

        * `texi/brew.html' This documentation in HTML. Produce this
          file by saying `makeinfo --html brew.texi'.

        * `texi/brew.dvi' File to print this manual. Produce this file
          by saying `texi2dvi brew.texi'.

        * `texi/HOWTO' Just some personal notes for the texinfo
          development cycle.

        * `brew/texi/TODO' Separate documentation TODO list.


   * `DEVELOPMENT' This file describes the development process. You
     get a better overview from this file than from `ChangeLog'.

   * `ChangeLog' Very detailed ChangeLog file.

   * `cvs-tags' Overview over CVS snapshots.

   * `VERSION-README' Some information about the current version and
     series. Obsolete.

   * `README' Old README. Mostly replaced by this manual.

   * `README-SECURITY' Security aspects. Please *do* read that.

   * `NEXT' Brew development has one difficulty: It tries to stay
     compatible between versions for some time, such that demos,
     benchmarks experiments and the like can be developed. From time
     to time compatibility must be broken. This file is a list of
     ideas, plans and TODO items for coming compatibility breaks.


   * `code-chapters.txt' Overview over organisation of `brew.fs'.

   * `brew/OUTPUT/FORTH/README-forth-directory' Directory information.

   * `brew/OUTPUT/log/README-log' Directory information.

   * `brew/OUTPUT/rec-play/README-rec-play' Directory information.

   * `brew/OUTPUT/tmp/README-tmp' Directory information.

   * `NAMING' Some conventions for naming Forth words in brew.

   * `TODO' Some TODO items.

   * `benchmark-results.txt' Some benchmark results.




File: brew.info, Node: Programming tool files, Next: Benchmark files, Prev: Informative files, Up: Files

Files with tools for profiling, testing and system adaptions
------------------------------------------------------------

   * `TAGS' Emacs TAGS file.

   * `make-ekey-map.fs' Help to make ekey mapping on a new system.

   * `profiling.fs' Helps optimising speed by counting how many times
     each word gets executed. Create COUNTING-WORDS before starting
     brew to trigger its use. Experimental.

   * `tests/' Directory for some tests.

   * `word-usage.fs' A profiling tool to count usage of most brew
     words. Only used for optimising speed. Create COUNTING-WORDS
     before starting brew to trigger its use. Experimental.




File: brew.info, Node: Benchmark files, Next: Console and key setup, Prev: Programming tool files, Up: Files

Benchmarks and Benchmark results
--------------------------------

   * `maybe-run-benchmark.fs' Fork to run benchmarks if a benchmark
     name is defined from command line.

   * `benchmark-results.txt' Some benchmark results.

   * `benchmarks/' Directory for benchmarks.

   * `bcompat-11-12.fs' Downwards compatibility to run
     `transit-11-bench-A' and `transit-12-bench'.




File: brew.info, Node: Console and key setup, Next: Bugs and Debugging, Prev: Benchmark files, Up: Files

Configuration of console size and special keys.
-----------------------------------------------

   * `configure-console.fs' Console size configurator. Try it if you
     have screen size problems.

   * `make-ekey-map.fs' Key mapping for keys like `<RETURN>'
     `<CURSOR-ARROWS>' `<FUNCTION-KEYS>' `<PageUp>' `<Home>'. Try it
     if brew reacts strange on some keys.




File: brew.info, Node: Bugs and Debugging, Prev: Console and key setup, Up: Files

Bugs and Debugging
------------------

   * `BUGS' Known bugs. Please consult before reporting a bug.

   * `environmental.test.fs' Tests some known environmental
     dependencies early in the load sequence. `Brew' depends on
     allocated memory to be dfaligned and on a separate floating point
     stack.

   * `debuging.fs' Words to help debugging.

   * `faked-genes.fs' Faking some genes for interactive debugging.

   * `INPUTS/extensions/debugging/' This directory has files to help
     debugging of certain brew/Forth combinations.


Tag table:
Node: Top150
Node: License12011
Node: Goals31190
Node: Introduction32759
Node: Evolutionary programming33268
Node: Simple hypothetical example35305
Node: Changing code36720
Node: Variable diversification37743
Node: Code mutation38396
Node: Biological analogy39680
Node: Artificial life40422
Node: Biological terms41145
Node: Feature overview43217
Node: Getting started46993
Node: Gforth50146
Node: pfe51033
Node: bigForth51361
Node: iForth52172
Node: Run evolution53043
Node: Why Forth?53600
Node: Note to Forth programmers55819
Node: Users manual56596
Node: Some brew basics59370
Node: Genes59979
Node: Diversification/Mutation61620
Node: Trial phase62996
Node: Classes of variables63638
Node: Variable names65846
Node: Run modes68037
Node: Display modes70338
Node: Example world mode display70829
Node: Example step display73073
Node: Using menus75123
Node: Menu example76969
Node: Example key bindings78743
Node: Configuring F580066
Node: Moving and selecting80832
Node: Key bindings81354
Node: Colours in menus82612
Node: Numeric input83303
Node: Float input84507
Node: Scale input85377
Node: Selecting functions87173
Node: Scrolling menus88843
Node: Using Forth in menus90379
Node: Context documentation91170
Node: Brew main screen92087
Node: World map interaction94176
Node: Cloning nucs to a spot95783
Node: Step display interaction96592
Node: Display menu97736
Node: Time99355
Node: Configuring spot display100870
Node: Show me functions102943
Node: Step display menu105824
Node: ASCII graphs107086
Node: ASCII bar graphics108907
Node: Text display112260
Node: Menu step display113152
Node: Menu continuous display117018
Node: Step display presets120502
Node: Info line120704
Node: Color menu122599
Node: Conditional colouring127740
Node: Menus menu128420
Node: Individuals menu132390
Node: Nuc menu134316
Node: Edit spot menu140460
Node: Menu global variables141269
Node: Food menu142137
Node: Population control143966
Node: Eat and consume144646
Node: Elitism152237
Node: Menu elite153266
Node: Diversification menu153739
Node: NUC diversification157164
Node: SPOT diversification158640
Node: GLOBAL diversification159351
Node: Mutation menu159782
Node: Probability lists163760
Node: Mutation types menu165511
Node: Gene pools menu170593
Node: Actual pool menu170902
Node: Stack type symbols171331
Node: Gene primitives175543
Node: Integer arithmetics genes177456
Node: Stack juggling genes177855
Node: Genes reading from memory181697
Node: Genes writing to memory182587
Node: Dealing with overflow183422
Node: Nuc and spot variables185098
Node: Global variables187111
Node: Insight genes187691
Node: Float arithmetic genes188620
Node: More float arithmetics188995
Node: Logarithms and exponentials189573
Node: Trigonometry190021
Node: Mixed maths190647
Node: Type casts191942
Node: Read float values192239
Node: Store float values192733
Node: Float stack manipulation193417
Node: Nuc and spot floats194022
Node: Gene conditionals194971
Node: Floating point comparison196640
Node: Genome pool196932
Node: Gene edit menu197878
Node: Scanning nucs199006
Node: Scanning spots202763
Node: Configurable actions203246
Node: Simple nuc conditions207206
Node: Simple spot conditions207753
Node: Extended conditions208176
Node: Generic nuc/spot actions211063
Node: Nuc specific actions212395
Node: Defining maybe-do actions212863
Node: Menu nuc subsets213902
Node: Menu spot subsets215320
Node: Menu current genomes215762
Node: Colouring on equality220418
Node: Colouring on difference221177
Node: Menu this genome222555
Node: Menu select nucs225016
Node: World menu227686
Node: World list menu232013
Node: Big Bang menu232824
Node: World size and visibility233982
Node: Big Bang238087
Node: System menu239719
Node: Log files menu246159
Node: Code file menu250267
Node: Record and Playback254547
Node: Recording from scratch257058
Node: Record after playback260941
Node: Record benchmark261772
Node: Playback264195
Node: Compile time options264646
Node: Menu function keys264890
Node: Menu Demos268438
Node: Experiments268802
Node: Programmers manual269629
Node: Files269964
Node: Directory tree270813
Node: Program files272456
Node: Genes files278376
Node: Configuration files279338
Node: Output files281630
Node: Temporary files282179
Node: Informative files283902
Node: Programming tool files285958
Node: Benchmark files286706
Node: Console and key setup287202
Node: Bugs and Debugging287684

End tag table
