<\input texinfo		@c -*-texinfo-*-
@c 	$Id: brew.texi,v 1.1.1.1 2009-06-09 18:28:50 anton Exp $

@c %**start of header
@setfilename brew.info
@settitle Brew manual
@setchapternewpage odd
@c %**end of header

@c enable top node in html output:
@c @ifinfo

@node Top, License, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top Brew @samp{The Evolutionary Programmers Playground}  Version 0.2

Brew is an environment for @samp{Evolutionary Programming}.@*
It's an experiment raising an @samp{Artificial Code Evolution}.

I wrote brew out of curiosity and for fun, enjoy@enddots{}@*
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@enddots{}

@detailmenu
 --- 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 @samp{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 @kbd{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 @samp{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 @samp{less}, @samp{equal}, @samp{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 @file{brew/OUTPUT/} directory.
* Temporary files::             Files in @file{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.

@end detailmenu
@end menu

@c @end ifinfo


@node License, Goals, Top, Top
@comment  node-name,  next,  previous,  up
@chapter GNU GENERAL PUBLIC LICENSE

@smallformat
                         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.
@end smallformat


@node Goals, Introduction, License, Top
@comment  node-name,  next,  previous,  up
@chapter What it's all about

'brew' is an interactive environment for experiments with an
@samp{artificial code evolution} using the Forth language.@*
@xref{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.


@node Introduction, Users manual, Goals, Top
@comment  node-name,  next,  previous,  up
@chapter 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?
@end menu


@node Evolutionary programming, Biological analogy, Introduction, Introduction
@comment  node-name,  next,  previous,  up
@section 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 @samp{evolutionary programming}, @samp{genetic programming} or
even @samp{artificial life} and others.

I prefer the term @samp{evolutionary programming} and call the process
a @samp{artificial code evolution}.

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


@node Simple hypothetical example, Changing code, Evolutionary programming, Evolutionary programming
@comment  node-name,  next,  previous,  up
@subsection 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.


@node Changing code,  , Simple hypothetical example, Evolutionary programming
@comment  node-name,  next,  previous,  up
@subsection 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:
@format

           output

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

@end format

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.
@end menu


@node Variable diversification, Code mutation, Changing code, Changing code
@comment  node-name,  next,  previous,  up
@subsubsection 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.


@node Code mutation,  , Variable diversification, Changing code
@comment  node-name,  next,  previous,  up
@subsubsection 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 ;-)


@node Biological analogy, Feature overview, Evolutionary programming, Introduction
@comment  node-name,  next,  previous,  up
@section 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.
@end menu


@node Artificial life, Biological terms, Biological analogy, Biological analogy
@comment  node-name,  next,  previous,  up
@subsection 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 @samp{Artificial Live} differently and might actually use it in the
context of brew.


@node Biological terms,  , Artificial life, Biological analogy
@comment  node-name,  next,  previous,  up
@subsection Biological terms
Let me give you some biological terms and an explanation what they mean in
the context of brew:

@itemize @bullet
@item @samp{cell}.
      By @samp{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 @samp{nucleus}. A @samp{cell} can have a
      location in a virtual world (@pxref{Run modes}).
      (@pxref{Note to Forth programmers}).

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

@item @samp{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 @samp{mutating} the genes of the mother cell.
      I usually start evolutions with a gene that does nothing at all.

@item @samp{genome}.
      The sequence of all @samp{genes} of an individual cell.

@item @samp{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.

@item @samp{population}.
      All the cells currently living in a virtual @samp{world}.

@item @samp{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.

@item @samp{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.
@end itemize


@node Feature overview, Getting started, Biological analogy, Introduction
@comment  node-name,  next,  previous,  up
@section Brew feature overview

Brew is a highly customisable and very interactive program to try out
@samp{evolutionary programming}.

Brew has some special features.  Let me just enumerate some:
@itemize @bullet

@item 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
@kbd{@key{<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.

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

@item 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. (@pxref{Compile time options}).

@item 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.

@item Context sensitive documentation interface.
Pressing @kbd{?} will let you browse the documentation, starting with the
node related to the menu context. @kbd{@key{<F1>}} should give the same result.

@item World mode and linear mode.
Brew can run in the so called @samp{world mode} and does this by default.
In world mode each cell has a defined location in a virtual @samp{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@enddots{}

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

@item 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.

@item 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 @code{tail -f} on these files and watch what's happening.

@item 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.

@item 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.
@end itemize


@node Getting started, Run evolution, Feature overview, Introduction
@comment  node-name,  next,  previous,  up
@section Getting started

Download brew:@*

Get a current brew version from @uref{http://reppre51.home.solnet.ch/}


Installation:

To install brew just unpack the files, say:

* @code{tar -xvjf brew.tar.bz2} (if you have a xxx.tar.bz2 file).@*
@ @ @ (older tar versions might need @samp{-xvIf} instead of @samp{-xvjf}).@*

* @code{tar -xvzf brew.tgz} (if you have a xxx.tgz file)@*

then:
@code{cd brew}

I would unpack brew in brew users home directory.@*
Please do read @file{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 @samp{brew.fs}:

@code{cd brew}@*
@code{FORTH brew.fs}@ @ @ @ @ where@samp{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.
@end menu



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 @kbd{@key{<F1>}} or @kbd{?}.


Most things in brew are text mode menus. Just move the cursor somewhere
and press @kbd{@key{<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@kbd{@key{<RETURN>}}.

@kbd{k} will normally show you key bindings active in the context.


Quit brew with @samp{QUIT brew} in system menu (@pxref{System menu}),
or by saying @samp{goodbye} (which might be on @kbd{@key{<F12>}}).
(@pxref{Menu function keys}). My personal shortcut to quit brew is
pressing a couple of @kbd{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 @file{configure-console.fs}. 
Try that if there are display problems.


If you have problems with keys like @kbd{@key{<RETURN>}}
@kbd{@key{<CURSOR-ARROWS>}} @kbd{@key{<FUNCTION-KEYS>}}
@kbd{@key{<PageUp>}} @kbd{@key{<Home>}} try to run
@file{make-ekey-map.fs}. Brew will suggest that anyway if it
gets unknown key codes.@*
(@pxref{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.


@node Gforth, pfe, Getting started, Getting started
@comment  node-name,  next,  previous,  up
@subsection 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:@*
@uref{http://www.complang.tuwien.ac.at/forth/gforth/}
@uref{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:@*
@code{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 ;-)


@node pfe, bigForth, Gforth, Getting started
@comment  node-name,  next,  previous,  up
@subsection Portable Forth Environment

@samp{pfe} the @samp{Portable Forth Environment} is a very nice Forth
implementation in C.  You can download it from:@*
@uref{http://sourceforge.net/projects/pfe}

start brew with:@*
@code{cd brew/}
@code{pfe brew.fs}


@node bigForth, iForth, pfe, Getting started
@comment  node-name,  next,  previous,  up
@subsection 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 @uref{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@*
@code{bigforth  --mem-size 106M --dictionary-size 80M brew.fs}@*
@code{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.


@node iForth,  , bigForth, Getting started
@comment  node-name,  next,  previous,  up
@subsection 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.@*
@uref{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.


@node Run evolution, Why Forth?, Getting started, Introduction
@comment  node-name,  next,  previous,  up
@section Let it brew.

Press @kbd{@key{<SPACE>}} to start and stop the evolutionary process.@*
Watch it for a while, then just press some keys and see what happens@enddots{}

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

Leave brew by pressing some @kbd{Q} or try @kbd{@key{<F12>}}.


You should be able to read the context sensitive documentation
by pressing @kbd{?} or (hopefully) @kbd{@key{<F1>}}.


@node Why Forth?,  , Run evolution, Introduction
@comment  node-name,  next,  previous,  up
@section 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:

@itemize @bullet
@item
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.

@item 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.

@item 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.

@item 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.

@item
I think FORTH is one of the most intelligent ways to deal with
programmable devices such as computers.
@end itemize


@menu
* Note to Forth programmers::   
@end menu


@node Note to Forth programmers,  , Why Forth?, Why Forth?
@comment  node-name,  next,  previous,  up
@subsection 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:

@itemize @bullet
@item @samp{Cell}.
      By @samp{cell} I mean those virtual beings brew produces.

@item @samp{Code}.
      The term is used in the sense of @samp{Forth program code} like
      programmers of other languages would understand it.
      I do not mean machine code.
      Brew only generates high level Forth code.

@item @samp{Function}.
      Sometimes I talk of @samp{functions} instead of @samp{words}.

@item @samp{Call}.
      Sometimes I @samp{call} a function instead of @samp{executing} a word.
@end itemize


@node Users manual, Programmers manual, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter 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 @samp{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.
@end menu


@node Some brew basics, Using menus, Users manual, Users manual
@comment  node-name,  next,  previous,  up
@section 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.
@end menu


@node Genes, Diversification/Mutation, Some brew basics, Some brew basics
@comment  node-name,  next,  previous,  up
@subsection Genes

In analogy to biology the Forth words executed by a cell are called
@samp{genes}.

Genes can get changed by the @samp{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
@samp{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@enddots{}

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@enddots{}

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.


@node Diversification/Mutation, Trial phase, Genes, Some brew basics
@comment  node-name,  next,  previous,  up
@subsection 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:

@table @asis
@item 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.

@item 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.
@end table

@*
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.


@node Trial phase, Classes of variables, Diversification/Mutation, Some brew basics
@comment  node-name,  next,  previous,  up
@subsection 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 @samp{trial phase} first.@*
If the genome survives a given number of generations it will be
compiled into the @samp{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.

@xref{Why Forth?}, for some technical details.


@node Classes of variables, Run modes, Trial phase, Some brew basics
@comment  node-name,  next,  previous,  up
@subsection 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.

@table @asis
@item 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.

@item 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.
@end table

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.
@end menu


@node Variable names,  , Classes of variables, Classes of variables
@comment  node-name,  next,  previous,  up
@subsubsection 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 @samp{organ-A} and @samp{organ-B} are two nuc variables of the same kind,
while @samp{A-quality} is a world variable.


@multitable @columnfractions .175 .125 .2 .2 .3
@item Name: @tab class: @tab access: @tab diversified? @tab compile option

@item integer-A
@tab global @tab read/only @tab maybe @tab global-integer-variables#
@item dfloat-A
@tab global @tab read/only @tab maybe @tab global-dfloat-variables#

@item organ-A
@tab nuc @tab read/write @tab maybe @tab nuc-organs#
@item parameter-A
@tab nuc @tab read/only @tab maybe @tab nuc-parameters#
@item invisible-A
@tab nuc @tab hidden @tab maybe @tab nuc-invisibles#
@item secret-A
@tab nuc @tab hidden @tab no  @tab nuc-secrets#

@item A-quality
@tab world @tab read/write @tab maybe @tab spot-qualities#
@item A-property
@tab world @tab read/only @tab maybe @tab spot-properties#
@item A-secret
@tab world @tab hidden @tab maybe @tab spot-secrets#
@end multitable

All these different kinds of variables come either as integer or as
floating point variables.  The latter do have a @samp{-f-} in their name.
So @samp{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.


@node Run modes, Display modes, Classes of variables, Some brew basics
@comment  node-name,  next,  previous,  up
@subsection Run modes

Brew can run in a number of different modes.

You must understand at least the first two:
@itemize @bullet

@item @samp{World mode}
In world mode the @samp{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.

@item @samp{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.

@item @samp{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.

@item @samp{Playback mode}. Playing back a recorded file by interpreting
it's contents.  Record and playback modes are exclusive.

@item Other modes.  There are a number of other modes not explained here.
Look in the source for @code{run-mode-masks} to learn more about.
@end itemize

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:@*
@xref{System menu}, for switching between world and linear mode.@*
@xref{Record and Playback}, for recording and playback.


@node Display modes,  , Run modes, Some brew basics
@comment  node-name,  next,  previous,  up
@subsection 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.
@end menu


@node Example world mode display, Example step display, Display modes, Display modes
@comment  node-name,  next,  previous,  up
@subsubsection Example world mode display

@format

...................       ******** ........  .**     ...      *********  . ....
....................       *******. ...... ..****    .......*********   .......
...................        ******    ........****     .......********  ........
.................... .  .   ******   ......*****      .......*******...........
.........................  ******** .... ..**** *    .........  *** ...........
.........................  *******.  . . ********    ..........****............
 .. ..   ......... ....... ******** .  ..********     ......... .* ............
  .    . .  .... . ......   *******   ..*********       .........  ...... ...
        .  ... ...*.....   ********....  ******* *      ..........*.......
 *********       **.....  ********..... ********* *    ....   ..    ... .   **
***********     ***************** .....*********       ..... ....   .   *. ****
************** *****************  .....********* *   ....... .  ..    *********
******************************** ....  ********     .........  .       ********
****************************** * ...   ********     ........          *********
**************************** *     . ..********     .......         ***********
****************************      . ....*****  *   ....... .       ************
****************************    .......*******     ........      **************
************** **************    .....* ****** *    .......     ***************
  **  * ** ** *  ************   ..  ...****** *     ......      ************ **
  *       *      **************    ...  ******     . ....       *********** *
*               *  ************     .. ******      ..... .      **********
         ....         * *******     . ...****      .....        ********  *
step: 636           cells: 42680         burden: 442        living: 1232
@end format

Each character symbolises a @samp{cell}.  You can select and edit them.@*
@xref{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.@*
@xref{Display menu}.


@node Example step display,  , Example world mode display, Display modes
@comment  node-name,  next,  previous,  up
@subsubsection 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@enddots{}

@format
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
@end format

@xref{Brew main screen}, common main screen capabilities.@*
@xref{Step display interaction}, to see what else you can do here.@*
@xref{Display menu}, for configuring display.@*


@node Using menus, Context documentation, Some brew basics, Users manual
@comment  node-name,  next,  previous,  up
@section 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 @kbd{@key{RET}}.  If you select the menu title or press @kbd{?} you
can read the documentation about the menu.

Most menus also have key bindings, which are more convenient once you get
used to them. (@pxref{Key bindings}).  Press @kbd{k} for key bindings.

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

@kbd{?} 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.
@end menu


@node Menu example, Moving and selecting, Using menus, Using menus
@comment  node-name,  next,  previous,  up
@subsection Menu example
@format

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')

@end format

This menu let's you configure function keys.@*
You can see it when you press @kbd{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 @kbd{?}) 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 @kbd{@key{<RET>}}, or by using key bindings
(@pxref{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 @kbd{k}.
* Configuring F5::              Example configuring F5.
@end menu

@node Example key bindings, Configuring F5, Menu example, Menu example
@comment  node-name,  next,  previous,  up
@subsubsection Example key bindings
@format

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)
@end format

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 @kbd{5} will let you configure function key
@kbd{@key{<F5>}}, by letting you choose from a list of possible actions.
You can see common key bindings too (@pxref{Key bindings}).

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


@node Configuring F5,  , Example key bindings, Menu example
@comment  node-name,  next,  previous,  up
@subsubsection Configuring F5

@format
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>

@end format

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


@node Moving and selecting, Key bindings, Menu example, Using menus
@comment  node-name,  next,  previous,  up
@subsection Moving and selecting in menus

To select a menu item move cursor on it and press @kbd{@key{<RET>}}.@*
Move cursor with cursor arrays or jump to next selectable field with
@kbd{@key{<TAB>}}.

To leave a menu press @kbd{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.


@node Key bindings, Colours in menus, Moving and selecting, Using menus
@comment  node-name,  next,  previous,  up
@subsection 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 @kbd{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:

@itemize @bullet
@item @kbd{q}: leave menu
@item @kbd{?}: context documentation
@item @kbd{k}: show keybindings
@item @kbd{!}: FORTH interpreter
@item @kbd{`}: show (most) active menu fields
@end itemize


Other frequently used key bindings:

@itemize @bullet
@item @kbd{@key{<SPACE>}}: next logical action, like start and stop brewing.
(Usually it's just leaving the menu).

@item @kbd{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'.
@end itemize


@node Colours in menus, Numeric input, Key bindings, Using menus
@comment  node-name,  next,  previous,  up
@subsection The meaning of colours in menus.

Some menus use colours to attract your attention.

@itemize @bullet
@item @samp{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 @kbd{o} key binding here (or first letter). 

@item @samp{Green} wants to attract your attention to some information,
      to a hint or suggestion, or to an option you could want to choose.

@item @samp{Red} is used for warnings and errors.
@end itemize

These colours are configurable, of course.


@node Numeric input, Float input, Colours in menus, Using menus
@comment  node-name,  next,  previous,  up
@subsection 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 @kbd{@key{<RET>}}.  The same applies for float values
(@pxref{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 @code{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 ;-)


@node Float input, Scale input, Numeric input, Using menus
@comment  node-name,  next,  previous,  up
@subsection 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 @samp{10}, @samp{2.5}, @samp{-3.14159265} and
brew will try it's best to guess what you actually meant to say@enddots{}

Please note that this has it's limitations:

@itemize @bullet
@item String replacement is only done on the last space separated substring
of your input.

@item While brew does try to replace number strings it does not replace
other words like operators and such. So you can't say @samp{pi +} when
you actually mean @samp{pi f+}.
@end itemize

As on integer input you can use the whole power of the Forth text interpreter
on numeric float input (@pxref{Numeric input}).


@node Scale input, Selecting functions, Float input, Using menus
@comment  node-name,  next,  previous,  up
@subsection Scale input, numeric fraction input in menus.

At some places brew asks you to input numeric fractions. As with numeric
input (@pxref{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
@samp{%} @samp{!} @samp{"} or @samp{'} brew will not try to be clever.

@*
Some examples:

@multitable @columnfractions .25 .25 .25 .25
@item Fraction before:   @tab Input:   @tab Result:    @tab Comment:

@item 1/2                @tab 0        @tab 0/1        @tab setting to zero

@item 1/2                @tab 2*       @tab 2/2        @tab multiply
@item 1/2                @tab 2 *      @tab 2/2        @tab multiply
@item 1/2                @tab 2/       @tab 1/4        @tab divide
@item 1/2                @tab 2 /      @tab 1/4        @tab divide

@item 1/2                @tab 2 7      @tab 2/7        @tab numeric normal
@item 1/2                @tab 3/7      @tab 3/7        @tab numeric
@item 1/2                @tab 4 / 7    @tab 4/7        @tab numeric

@item 1/2                @tab % 2*     @tab 1/4        @tab escaping
@end multitable


@node Selecting functions, Scrolling menus, Scale input, Using menus
@comment  node-name,  next,  previous,  up
@subsection 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:@*

@format
<look-at> function:     show-genome-b
@end format

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 (@pxref{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 @code{(none)} (sometimes @code{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.@*
@xref{Scrolling menus}.


There's an advanced feature on key @kbd{'}:@*

On rare occasions you might want to select a word which is not included in
the list.  Press @kbd{'}, 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.


@node Scrolling menus, Using Forth in menus, Selecting functions, Using menus
@comment  node-name,  next,  previous,  up
@subsection 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
@format
This menu is a scrolling one.  <PageUp>  <PageDown>  <home>  <end>  <arrows>
@end format

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

@item @kbd{@key{<PageUp>}}.
      Scroll the size of the scroll area up, stop at top.

@item @kbd{@key{<PageDown>}}.
      Scroll the size of the scroll area down, stop at bottom.

@item @kbd{@key{<home>}}.
      Scroll to top.

@item @kbd{@key{<end>}}.
      Scroll to bottom.

@item @kbd{@key{<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.
@end itemize


@node Using Forth in menus,  , Scrolling menus, Using menus
@comment  node-name,  next,  previous,  up
@subsection Using Forth in menus

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

Your input will be interpreted when you press @kbd{@key{<RET>}} and brew@*
will wait until you press another key.

If you want to make more Forth input before returning to the menu,@*
press @kbd{@key{<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.@*


@node Context documentation, Brew main screen, Using menus, Users manual
@comment  node-name,  next,  previous,  up
@section Reading context documentation from within brew

Brew has an interface to port you to the relevant documentation node.
You reach it by pressing @kbd{?}, by selecting a menu title, or in
default configuration by pressing@ @kbd{@key{<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 @samp{info} reader (preferred) or a text mode
html browser (like @samp{lynx}) to display the documentation.
Make sure you have installed it. For html you have to produce or to
download the html file separately. 

@xref{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 @samp{reader}.


@node Brew main screen, Display menu, Context documentation, Users manual
@comment  node-name,  next,  previous,  up
@section 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.
@xref{Display menu}, for configuring what to display.

@table @kbd
@item <SPACE>
Press @kbd{@key{<SPACE>}} and brew will start brewing and continue until
you press i.e. @kbd{@key{<SPACE>}} again.  

@item s
Pressing @kbd{s} is similar, but will just make one step and stop then.

@item o
Toggle between world display and step (statistics) display.

@item k
See all the other key bindings. (@pxref{Key bindings}).

@item K
See and edit function key bindings. (@pxref{Menu function keys}).
@end table

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:

@xref{Example world mode display}, petri shell look world map.@*
@xref{Example step display}, real time statistics display.


@xref{Display menu}, choose what you want to see while brewing.@*
Pressing @kbd{D} or selecting the info line (last line of the screen)
ports you to @samp{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.
@end menu


From brews main screen you reach many important other menu screens with
capital letter key bindings. @xref{Key bindings}.

Brews menu list is on keys @kbd{B} and @kbd{m}.@*
@xref{Menus menu}.


...and then, @kbd{?} goes to context sensitive documentation, as usual...@*
(and @kbd{d} has some demos).


@node World map interaction, Cloning nucs to a spot, Brew main screen, Brew main screen
@comment  node-name,  next,  previous,  up
@subsection 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.

@xref{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:

@xref{Nuc menu}, if you press @kbd{@key{<RETURN>}} on a cell.@*
@xref{Edit spot menu}, if you select an empty spot.


Special key bindings:

@table @kbd
@item l
Pressed when cursor is on a cell shows it's genome as Forth source.
On a empty space it gives @samp{Edit spot menu}.

@item c
Press this key if you want brew to continue to use the current colour
coding while brewing. @xref{Conditional colouring}, to learn more about.

@item *
You can select a rectangle region in brews main screen world map. Define
the region by pressing @kbd{*} on desired corners then press
@kbd{@key{<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 (@pxref{Configurable actions}).
@end table


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 @kbd{k} to check
for key bindings or @kbd{@key{<TAB>}} to locate additional selectable items.


@node Cloning nucs to a spot, Step display interaction, World map interaction, Brew main screen
@comment  node-name,  next,  previous,  up
@subsection Setting nucs to spots

When you have examined a nuc (@pxref{World map interaction})
or selected an individual (@pxref{Individuals menu}) brew will
display @samp{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 @kbd{@key{<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 (@pxref{World list menu}) and set
clones of the selected nucs there.


@node Step display interaction,  , Cloning nucs to a spot, Brew main screen
@comment  node-name,  next,  previous,  up
@subsection Brews main screen in statistical (step) mode.

@xref{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 (@pxref{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 @samp{menu nuc subsets} or a @samp{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 @kbd{*} on the range
borders inside a scan bar graphic. When the range is displayed press
@kbd{@key{<RETURN>}} to go to the corresponding subset menu.@*
@xref{Menu nuc subsets}.

Press @kbd{D} to do other configurations or select the @samp{info line}.
@xref{Display menu}.


@node Display menu, Color menu, Brew main screen, Users manual
@comment  node-name,  next,  previous,  up
@section Display menu

If you press @kbd{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 @samp{step OR spot} or by pressing @kbd{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 @samp{snapshots}, or switch
display off completely. Key @kbd{t} toggles between real time and snapshots
display, like it does in main screen.  Brew distinguishes between
@samp{step-snapshots} and @samp{spot-snapshots} and offers you to choose
between possible frequencies for the snapshots. The selected number is
marked with @samp{*} 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 @kbd{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@enddots{}

@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.
@end menu


@node Time, Configuring spot display, Display menu, Display menu
@comment  node-name,  next,  previous,  up
@subsection 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.

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

@item 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.
@end itemize

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 @samp{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 @samp{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.


@node Configuring spot display, Step display menu, Time, Display menu
@comment  node-name,  next,  previous,  up
@subsection Configuring spot display

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

@itemize @bullet
@item @samp{<look-at> function}. Cells show up as chars in brews world map.
There are a number of functions to determine the char actually displayed.
@xref{Show me functions}, to learn about available functions.

@item @samp{Parameters for look-at functions}.
      Some @samp{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 @samp{<look-at> function}.

@item @samp{Value to ASCII divisor}.
      Some @samp{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 @samp{0} if the value in question is from 0 to 99,
      and as @samp{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.

@item @samp{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.
@xref{World size and visibility}.

@item @samp{Color}. Color is configured in it's own menu.
You reach color menu by pressing @kbd{C} from brews main screen.
@xref{Color menu}.
@end itemize

@menu
* Show me functions::           
@end menu


@node Show me functions,  , Configuring spot display, Configuring spot display
@comment  node-name,  next,  previous,  up
@subsubsection 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 (@pxref{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 @samp{<look-at>}
which can be switched to all the others at run time.
So you can switch all the cells that have @samp{<look-at>} as their 
@samp{show-me} function to show their age or whatever you like at runtime.
This can be done using key bindings (@pxref{Key bindings}) from
@xref{Brew main screen}, or from display menu @xref{Configuring spot display}.

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


You can choose among the following functions:

@itemize @bullet
@item @samp{show-ascii} A fixed @samp{char} (see below) is displayed.

@item @samp{show-age} Age determines displayed char.

@item @samp{show-energy} Coding energy level to char.

@item @samp{show-generation} Generation to char.

@item @samp{show-genome} Different genomes look different.

@item @samp{show-genome-b} Same, but using another char subset.

@item @samp{show-genome-generation} Genomes generation as char.

@item @samp{show-code-length} Code length coded as char.

@item @samp{show-integer-nuc-var} Value of a integer nuc var (Variable and
      scale get chosen in @pxref{Display menu}).

@item @samp{show-integer-var-sign} Sign of a integer nuc var with a certain
      tolerance (Both chosen in @pxref{Display menu}).

@item @samp{show-float-nuc-var} Value of a float nuc var (Variable and
      scale get chosen in @pxref{Display menu}).

@item @samp{show-float-var-sign} Sign of a float nuc var with a certain
      tolerance (Both chosen in @pxref{Display menu}).

@item @samp{show-A} Value of organ-A. Obsolete.

@item @samp{show-sign-A} If organ-A is near zero display @kbd{o}, else
      display @kbd{+} or @kbd{-} depending on sign. Obsolete.

@item @samp{<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 (@pxref{Configuring spot display}) or using brew main screen
      key bindings (@pxref{Key bindings}).

@item @samp{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.

@item @samp{show-ABC*.} Quite obscure function used in an old demo.

@item @samp{show-ABC-X|} Quite obscure function used in an old demo.

@item @samp{show-~|'.*} Quite obscure function used in an old demo.
@end itemize


@node Step display menu, Info line, Configuring spot display, Display menu
@comment  node-name,  next,  previous,  up
@subsection 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 @kbd{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 @samp{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.
@end menu

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 ;-)


@node ASCII graphs, ASCII bar graphics, Step display menu, Step display menu
@comment  node-name,  next,  previous,  up
@subsubsection ASCII graphs

@format

      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
@end format

This type of graph is drawn continuously from left to right, one column
a step.  I call this type @samp{continuous display}.@*

The last line gives you the meaning of the used characters:@*
@kbd{$} means how energy much a cell looses for each life step.@*
@kbd{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.


@node ASCII bar graphics, Text display, ASCII graphs, Step display menu
@comment  node-name,  next,  previous,  up
@subsubsection 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:

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

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

Here @code{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 @kbd{*} on the range
borders inside a scan bar graphic. When the range is displayed press
@kbd{@key{<RETURN>}} to go to the corresponding subset menu). Brew
puts you into a @samp{Menu nuc subsets} or @samp{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.

@xref{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 @samp{<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.


@node Text display, Menu step display, ASCII bar graphics, Step display menu
@comment  node-name,  next,  previous,  up
@subsubsection 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{code-cost},
@code{energy} and one spot variable @code{food}:

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

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


@node Menu step display, Menu continuous display, Text display, Step display menu
@comment  node-name,  next,  previous,  up
@subsubsection 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.@*
(@pxref{ASCII graphs} @pxref{ASCII bar graphics} @pxref{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 @code{nuc-scan-display}
or @code{nuc-scan-func-dspl} and @code{spot-scan-display} and between
@code{nuc-text-display} and @code{world-text-display}. Configuration
is the same though.

Continuous display configuration is more complex and has it's own
sub menu @pxref{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 @samp{add new item}
or @samp{remove last item}. You will be guided through the configuration.

An entry for a displayed item might look like this:@*
@format

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

@bullet{} The first item indicates the type of statistical display:@*
@multitable @columnfractions .33 .17 .5

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

@bullet{} The second item is the variable (or function) name

@bullet{} @samp{lines} configures how many screen lines this display item will take up.

@bullet{} @samp{v-range} is the vertical range.
No need to initialise it normally. Brew will take care about.

@*
With @kbd{o} or by selecting @samp{More infos}/@samp{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:
@format

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

@end format

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 (@pxref{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:
@format
500        scanning: energy       -<zooming>|      vertical range: 52      1366
@end format
The '-' and '|' left and right the word '<zooming>' indicate horizontal and
vertical zooming.  So in this example both took place.

@bullet{} 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.@*
@xref{Menu continuous display}.

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

@*
@samp{presets} @xref{Step display presets}, for often used templates.


@node Menu continuous display, Step display presets, Menu step display, Step display menu
@comment  node-name,  next,  previous,  up
@subsubsection Menu continuous display

This menu configures so called @samp{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
(@pxref{ASCII graphs}).

The menu might look similar to this:

@format
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

@end format

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

You can select the type of the displayed value from the following list:@*
@multitable @columnfractions .25 .25 .5
@item  name:         @tab kind:     @tab value:
@item  (none)        @tab --        @tab no selection
@item  get-variable  @tab various   @tab variable value (see below)
@item  nuc-min       @tab nuc       @tab minimum
@item  nuc-max       @tab nuc       @tab maximum
@item  nuc-range     @tab nuc       @tab range
@item  nuc-average   @tab nuc       @tab average
@item  spot-min      @tab spot      @tab minimum
@item  spot-max      @tab spot      @tab maximum
@item  spot-range    @tab spot      @tab range
@item  spot-average  @tab spot      @tab average
@end multitable

Type @samp{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 @samp{get-variable} can treat are:@*
@format
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
@end format

Defining char and color is trivial.

@samp{low} and @samp{high} defines the display range. No need to initialise
them normally.  Brew will take care about.

@samp{Zoom up scale} sets the zooming scale applied when a value falls out
of range (@pxref{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 @samp{low}
and @samp{high}.

Use @samp{add new entry} to add a new entry.


@node Step display presets,  , Menu continuous display, Step display menu
@comment  node-name,  next,  previous,  up
@subsubsection Step display presets

Planed to give some often used display configurations.


@node Info line,  , Step display menu, Display menu
@comment  node-name,  next,  previous,  up
@subsection 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 @samp{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:

@format
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).
@end format

@*
@samp{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.


@node Color menu, Menus menu, Display menu, Users manual
@comment  node-name,  next,  previous,  up
@section 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 @kbd{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 @kbd{f} or @kbd{b}
respectively. Please note that these key bindings are the same as in
brews main screen.

Pressing capital @kbd{F} or @kbd{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 (@pxref{Selecting functions}).

Foreground colors can be set by the following nuc dependent functions:
@format
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
                            (@pxref{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
                            (@pxref{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
@end format

Background colors can be set by the following spot dependent functions:
@format
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
                            (@pxref{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
@end format

@*
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:@*
@itemize @bullet
@item @kbd{f} Toggle foreground color.@*
@item @kbd{b} Toggle background color.@*
@item @kbd{F} Set foreground color coding.@*
@item @kbd{B} Set background color coding.@*
@item @kbd{c} Calibrate background color scales to full color range.@*
@item @kbd{h} Calibrate background color scales to half color range.@*
@item @kbd{2} Calibrate background color scales to use 2 colours only.@*
@end itemize

@*
@xref{Scrolling menus}.


@menu
* Conditional colouring::       User defined colour conditions.       
@end menu

@node Conditional colouring,  , Color menu, Color menu
@comment  node-name,  next,  previous,  up
@subsection Conditional colouring

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

@xref{Extended conditions}, to learn how to set up colour conditions.

You can also set colour conditions from @samp{world maps} by pressing
@kbd{c}. Brew sets up colouring like it is used in the current map if
you do so. (@pxref{World map interaction}).


@node Menus menu, Individuals menu, Color menu, Users manual
@comment  node-name,  next,  previous,  up
@section Brews super menu.

Brews super menu is just a list of all globally accessible menus.@*
You get there by pressing @kbd{B} or @kbd{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 @samp{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 @xref{Using menus}.

@itemize @bullet
@item @samp{menu Individuals}.
      Select and edit predefined individuals to release in the world.
      @xref{Individuals menu}.

@item @samp{menu System}.
      Configure system wide options.
      @xref{System menu}.

@item @samp{menu World}.
      Configure world wide options.
      @xref{World menu}.

@item @samp{menu Worlds list}.
      Select a world and enter, configure world names and the like.
      @xref{World list menu}.

@item @samp{menu global Variables}.
      Simplest type of variables visible to genomes.
      @xref{Menu global variables}.

@item @samp{menu Mutation}.
      Configure mutation.
      @xref{Mutation menu}.

@item @samp{menu Diversification}.
      Configure nuc and spot variable diversifications.
      @xref{Diversification menu}.

@item @samp{menu Gene pools}.
      Select gene pool.
      @xref{Gene pools menu}.

@item @samp{menu Actual pool}.
      Configure actual gene pool.
      @xref{Actual pool menu}.

@item @samp{menu Current Genomes}.
      Examine different currently living genomes.
      @xref{Menu current genomes}.

@item @samp{menu Population control}.
      Configure population control.
      @xref{Population control}.

@item @samp{menu Food}.
      Configure food supply.
      @xref{Food menu}.

@item @samp{menu Elite}.
      Current score list of the individuals.
      @xref{Menu elite}.

@item @samp{menu Scan nucs}.
      Gather statistical informations about all nucs.
      @xref{Scanning nucs}.

@item @samp{menu Scan world}.
      Gather statistical informations about all spots.
      @xref{Scanning spots}.

@item @samp{menu Select nucs}.
      Select or de-select nuc subsets.
      @xref{Menu select nucs}.

@item @samp{menu Nuc Subsets}.
      Do something on all nucs meeting a certain condition.
      @xref{Menu nuc subsets}.

@item @samp{menu Spot Subsets}.
      Do something on all spots meeting a given condition.
      @xref{Menu spot subsets}.

@item @samp{menu Display}.
      Configure display of brews main screen.
      @xref{Display menu}.

@item @samp{menu Color}.
      Configure colors in brews main screen.
      @xref{Color menu}.

@item @samp{menu Step Display}.
      Configure brews main screens display when in step display.
      @xref{Step display menu}.

@item @samp{menu Continuous Display}.
      Configure step ASCII graph display called @samp{continuous display}.
      @xref{Menu continuous display}.

@item @samp{menu Log files}.
      Configure writing log files.
      @xref{Log files menu}.

@item @samp{menu Code files}.
      Configure writing generated Forth code to a file.
      @xref{Code file menu}.

@item @samp{menu Record Playback}.
      Record your interactions with brew or replay your session.
      @xref{Record and Playback}.

@item @samp{menu Function Keys}.
      Configure function key bindings.
      @xref{Menu function keys}.

@item @samp{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. @xref{Menu Demos}.

@item @samp{menu Big Bang}.
      Create a new world.
      @xref{Big Bang menu}.

@item @samp{Manual}.
      Call the external manual reader on top node.
      @xref{System menu}, for how to switch between using info reader
      or html browser.
@end itemize


@node Individuals menu, Nuc menu, Menus menu, Users manual
@comment  node-name,  next,  previous,  up
@section Individuals menu

You reach the individuals menu by pressing @kbd{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 @kbd{i} to select an individual from the list.@*
Press @kbd{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 @kbd{@key{<RET>}} on a spot. Brew displays @samp{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 (@kbd{c}). There is a variant which diversifies diversificable
nuc variables of each sown clone (@kbd{d}), making them a bit different,
which is usually a good idea to start an evolution.
@xref{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.


@node Nuc menu, Edit spot menu, Individuals menu, Users manual
@comment  node-name,  next,  previous,  up
@section 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:@*
@itemize @bullet

@item @samp{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
      (@pxref{Selecting functions}). This code get's mutated by the mutation
      process. Normally you will probably start a evolution with @samp{noop}.

@item @samp{<name>}. The genomes name or the information that this genome is on
       trial. Selecting it will let you examine or edit the genome.
       (@pxref{Gene edit menu}).

@item @samp{.gene-info}. Gives you some information about the cells genome.

@item @samp{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.
      @xref{Menu select nucs}, for more information.

@item @samp{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.

@item @samp{score}. Raw scoring result without code taxes.

@item @samp{reproduce}. Select the way the cell reproduces. Currently only
      @code{cell-division} is implemented, so you don't have much 
      choice@enddots{}

@item @samp{show-me}. Select a function determining how the cell will show up
      in the world map. @xref{Show me functions}, to see what is available.

@item @samp{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.

@item @samp{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.

@item @samp{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.

@item @samp{nuc length}. Length of the nucs data structure. You cannot
      change this here.

@item @samp{age}. The age of the cell in time steps. You can edit it
      if you want to cheat for some reason.

@item @samp{age limit}. A nuc will die at the latest when he will get
      older than this maximal possible age.

@item @samp{generation}. The cells generation since start of this evolution.

@item @samp{genome gen}. Generation of this genome since last mutation.

@item @samp{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 @samp{reproduction energy}. Energy is received through
      @samp{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 @samp{population control}. A mother cell passes it's energy on to the
      children, equally dividing it to give each one it's share.

@item @samp{char}. If you set @samp{show me} to @samp{show-ascii} this
      char will be shown to symbolise the cell in spot display.  Otherwise
      it has no influence at all.

@item @samp{reproduction energy}. Energy level a cell must reach to be
      able to reproduce. Some other conditions (depending on @samp{world mode}
      or @samp{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.

@item @samp{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 @kbd{o},
      like usual).
      In the case of floats the menu further let's you choose between VISIBLE
      (to mutation) or HIDDEN variables (Please read @pxref{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 (@pxref{Scrolling menus}).

@item @samp{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 @samp{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.

@item @samp{sow} and @samp{sow diversified} work like from individuals
      menu (@pxref{Individuals menu}).

@item @samp{remove cell} takes this cell out of the play.

@item @samp{SPOT} let's you examine and edit the spot the nuc is on.
@end itemize


@node Edit spot menu, Menu global variables, Nuc menu, Users manual
@comment  node-name,  next,  previous,  up
@section 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 @kbd{l} on an empty
spot. (Pressing @kbd{@key{<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 @samp{Spot} therein.

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

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


@node Menu global variables, Food menu, Edit spot menu, Users manual
@comment  node-name,  next,  previous,  up
@section Global variables

This menu let's you see and edit global integer or float variables.@*
You get here from brews main screen by pressing @kbd{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 @kbd{o} toggles as usual.

To set them all to the same value, set the first one and select@*
@samp{set them all to this value}.

To configure diversification of global variables use the link to@*
@xref{Diversification menu}.

@xref{Numeric input}, how to use Forth power in input.@*
@xref{Float input}, to use everydays float syntax on input.@*
@xref{Scrolling menus}, scrolling menus.


@node Food menu, Population control, Menu global variables, Users manual
@comment  node-name,  next,  previous,  up
@section Food menu

The cells need @samp{energy} to survive and to reproduce.@*
They get energy by @samp{eating} @samp{food}.

Population get's controlled by two means:@*
@itemize @bullet
@item Limiting food supply.@*
@item Adapting @samp{energy costs} for each life step and for code length.@*
@end itemize

This menu is for food supply configuration.@*
You get here by pressing @kbd{F} in brew main screen.

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

@item @samp{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.

@item @samp{Individual food share}. Each living individual get's this much
food extra. This works against stabilising population.

@item @samp{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.

@item @samp{Feed world manually}. Sometimes you want to give a extra
food portion to all spots and all cells.

@item 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.
@end itemize


@node Population control, Diversification menu, Food menu, Users manual
@comment  node-name,  next,  previous,  up
@section 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
@kbd{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.
@end menu

@node Eat and consume, Elitism, Population control, Population control
@comment  node-name,  next,  previous,  up
@subsection Brews pseudo biological mode

Brew stresses it's little 'beings' by two means:@*
@itemize @bullet
@item Limiting food supply.@*
@item Adapting @samp{energy costs} for each life step and for code length.@*
@end itemize

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:
@itemize @bullet

@item @samp{High water mark}, @samp{Low water mark}. If population crosses
these limits brew will automatically increase or decrease life stress
in order to stabilise population in between them.

@item @samp{Stress additive step}. Stress amount added (or subtracted)
to the current stress when population is out of bounds.

@item @samp{Stress rate}. Rate the current stress is multiplied (or
divided) by when population is out of bounds.

@item @samp{Population flood}. Population has crossed a critical limit.
Brew takes drastical measures to decrease it.

@item @samp{S.O.S.}. Population has fallen below a critical limit.
Brew takes a number of drastical measures to save the population from
dying out.
@end itemize

@*
Configurating possibilities:@*
@itemize @bullet

@item @samp{Live stress, additive step}.
Amount of additive live stress change when population is out of bounds.

@item @samp{Stress rate}.
Multiplicative live stress change when population is out of bounds
(@pxref{Scale input}).

@item @samp{Code price, additive step}.
Amount of additive stress adaption (dependent on code length) when
population is out of bounds.

@item @samp{Code price rate}.
Multiplicative stress change (dependent on code length) when population
is out of bounds (@pxref{Scale input}).

@item @samp{High water mark}.
Beyond this limit brew will increase stress to keep population down.

@item @samp{Flood-mark}.
Beyond this limit brew will take drastic measures to cut population down.@*
Brew will issue a message to you if that happens.

@item @samp{Flood stress rate}.
Multiplicative stress rate applied in case of population flood emergency
(@pxref{Scale input}).

@item @samp{Flood energy rate}.
In case of population flood emergency the energy level of each living cell
will get multiplied by this rate (@pxref{Scale input}).

@item @samp{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. (@pxref{Food menu}, @pxref{Scale input}). This measure should
have a lasting effect on population size.

@item @samp{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. (@pxref{Scale input}).

@item @samp{Low water mark}.
Whenever population falls below this level brew will automatically decrease
stress to let the population grow again.

@item @samp{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.

@item @samp{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.

@item @samp{Multiplicative release}.
This is the *factor* by which multiplicative population regulation is
stronger when applied upwards than downwards. (See last entry).

@item @samp{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.

@item @samp{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 (@pxref{Scale input}).

@item @samp{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.

@item @samp{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.

@item @samp{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.

@item @samp{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.

@item @samp{Current energy cost of code usage}.
Current result of the above regulation process regarding gene code length
regulation.

@item @samp{rating scale}.
Fixed scale not touched by population control to configure the weight of
gene code length on applied stress (@pxref{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
;-)

@item @samp{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. (@pxref{Scale input}).

@item @samp{Food supply}.
As food supply is the other tool to regulate population you will find a
link here. @xref{Food menu}.

@end itemize


@node Elitism, Menu elite, Eat and consume, Population control
@comment  node-name,  next,  previous,  up
@subsection 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.

@itemize @bullet
@item @samp{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.

@item @samp{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.

@item @samp{Code price scale}.
      Scale for the gene code length to go into the scoring function.
@end itemize


@node Menu elite,  , Elitism, Population control
@comment  node-name,  next,  previous,  up
@subsection Score list of individuals

This menu displays the list of individuals sorted by their score.@*
You get here from brews main screen by pressing @kbd{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...


@node Diversification menu, Mutation menu, Population control, Users manual
@comment  node-name,  next,  previous,  up
@section 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 @samp{mutation}, but also for nuc intern (hereditary)
variables, which are varied by @samp{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.

@samp{Diversification menu} sets up the parameters for diversification.@*
You reach it by pressing @kbd{m} and then @kbd{d} from brews main screen.

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

The mechanism work similar, but not equal:
@itemize @bullet

@item Diversification of NUC variables is only done when a nuc reproduces,
and only in a certain rate of cases. (@samp{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.

@item 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.

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

Let me explain two technical terms which play a role in all cases:@*
@itemize @bullet

@item @samp{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.

@item @samp{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.

@item @samp{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.

@item Of course all the above is only true for variables where diversification
is switched on at all.
@end itemize

@*
@menu
* NUC diversification::         Diversification of NUC local variables.
* SPOT diversification::        Diversification of SPOT local variables.
* GLOBAL diversification::      Diversification of GLOBAL variables.
@end menu

@*
@xref{Scrolling menus}.


@node NUC diversification, SPOT diversification, Diversification menu, Diversification menu
@comment  node-name,  next,  previous,  up
@subsection 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.
@itemize

@item @samp{Rate}. If rate is set to 1/4 diversification will be done
      on every 4th reproduction, statistically speaking of course.
      (@pxref{Scale input}).

@item @samp{Range}. Maximal possible deviation in each direction.

@item @samp{Relative}. Maximal factor/divider (only for floats).
 
@item @samp{Closeness}. The bigger this value, the less big deviations.

@item @samp{Sporadic}. (Usually much smaller) rate of sporadic big deviations.
      (@pxref{Scale input}).

@item @samp{(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.
@end itemize

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

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


@node SPOT diversification, GLOBAL diversification, NUC diversification, Diversification menu
@comment  node-name,  next,  previous,  up
@subsection 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 @xref{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.


@node GLOBAL diversification,  , SPOT diversification, Diversification menu
@comment  node-name,  next,  previous,  up
@subsection 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 @xref{NUC diversification}, for more infos.


@node Mutation menu, Gene pools menu, Diversification menu, Users manual
@comment  node-name,  next,  previous,  up
@section Mutation menu

Here you configure options for the mutation process.@*
You reach it from brews main screen by pressing @kbd{M}.

@itemize @bullet

@item @samp{How often to mutate}.
This rate determines in how many cases a cell reproduction will lead
to mutation of the genome. (@pxref{Scale input}).

@item @samp{Mutation TYPES}.
There are different types and sub-types of mutation @xref{Mutation types menu}.
Here you can edit the relative probabilities of each type to occur.
@xref{Probability lists}.

@item @samp{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.

@item @samp{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.

@item @samp{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.

@item @samp{RING/quiet}.
Switch ringing the bell in case of exceeding genome size limit (see above).

@item @samp{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. (@pxref{Trial phase}).
Genes on trial will not be mutated further.

@item @samp{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.

@item @samp{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 @samp{Set nuc bit masks absolutely} resets them after each mutation.

@item @samp{Diversification of variables}.
As mutation and diversification are similar processes there is a link to the
diversification menu here. (@pxref{Diversification/Mutation}).
@end itemize

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


@node Probability lists, Mutation types menu, Mutation menu, Mutation menu
@comment  node-name,  next,  previous,  up
@subsection 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 @samp{probability lists} can
be nested one into the other.

Example (mutation types):
@format
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
@end format

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 @samp{snip-types}
will be three times as frequent and so on.

Note that @samp{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 @samp{* 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
(@pxref{Scrolling menus}).


@node Mutation types menu,  , Probability lists, Mutation menu
@comment  node-name,  next,  previous,  up
@subsection Mutation types menu

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

@item @samp{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.

@item @samp{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.

@item @samp{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 @samp{* nested list *} to adapt probabilities):
@itemize @minus

@item @samp{top-level-random-snip}. Look for a random starting point.
Determine all possible ending points and take a random one.

@item @samp{top-level-short-snip}. Look for a random starting point.
Take the shortest possible (non empty) sequence to snip away.

@item @samp{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.

@item @samp{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).
@end itemize

@item @samp{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.

@item @samp{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.

@item @samp{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.

@item @samp{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.
(@pxref{Genome pool}).
@end itemize


@node Gene pools menu, Actual pool menu, Mutation menu, Users manual
@comment  node-name,  next,  previous,  up
@section 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 @kbd{G}.

Currently only @samp{gene-primitives} is selectable.


@node Actual pool menu, Stack type symbols, Gene pools menu, Users manual
@comment  node-name,  next,  previous,  up
@section Actual pool menu

This menu let's you edit the gene pool used for mutation.@*
You get here from brews main screen by pressing @kbd{A}.

Currently this is always @samp{gene-primitives}.

Change the relative probabilities of the genes to be used by mutation.

@xref{Probability lists}.@*
@xref{Scrolling menus}.


@node Stack type symbols, Gene primitives, Actual pool menu, Users manual
@comment  node-name,  next,  previous,  up
@section 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:
@itemize

@item Security. If I run brew on my computer I want to be sure it cannot
      possibly generate any harmful program code under whatever circumstances.

@item 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.
@end itemize

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 @samp{stack symbols} to indicate them:
@itemize @minus

@item @code{n}. Cell wide numeric value, not distinguishing between signed
      and unsigned. (The technical term @code{cell} is used in the Forth
      sense here, indicating a storage unit, frequently 32 bits).

@item @code{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.

@item @code{r}. Floating point value on the floating point stack. 

@item @code{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.

@item @code{C}. Flag being @code{true} or @code{false}.
@end itemize

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.

@format
So Forth would say  @code{swap ( x1 x2 -- x2 x1) }
While brew would    @code{swap ( nn-nn ) }
or (depending on the types of the stack items) would possibly see it as a @*
different word like @code{swap(an) ( an-na) }. @*
@end format

Note that the last example would execute and compile the *same* code,
just a normal @code{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 @kbd{-} 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.


@node Gene primitives, Gene edit menu, Stack type symbols, Users manual
@comment  node-name,  next,  previous,  up
@section Gene primitives

Mutation can only build genomes based on the so called @samp{gene primitives}.@*
The gene primitives are given together with their stack type symbols here.@*
@xref{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.
@end menu


@node Integer arithmetics genes, Stack juggling genes, Gene primitives, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Integer arithmetics gene primitives
@itemize @minus

@item @code{ + ( nn-n )}. Addition.

@item @code{ - ( nn-n )}. Subtraction.

@item @code{ negate ( n-n )}. Negate.

@item @code{ * ( nn-n )}. Multiply.

@item @code{ ?/ ( nn-n )}. Divide if divisor is not zero, else return zero.
@end itemize


@node Stack juggling genes, Genes reading from memory, Integer arithmetics genes, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Gene primitives to arrange items on the Forth stack

This might look familiar to Forth programmers and very strange to other
readers@enddots{} ;-)@*
(Consider learning some Forth basics and return to here later on@enddots{})

Forth makes heavy use of the so called @samp{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:
@itemize

@item @code{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:

@item @code{swap ( x1 x2 -- x2 x1)}. This is a usual way of writing down
      the stack effect of the word @code{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.
@end itemize

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 @code{swap ( n1 n2 -- n2 n1)}
as a noop regarding stack effect. If one of them is a address instead,
brews mutation mechanism sees that @code{swap} as a completely different word,
even if it will compile the normal Forth word @code{swap} in both cases.@*
@xref{Stack type symbols}.

@itemize @minus

@item @code{dup ( n-nn)}. Duplicate the topmost stack item (integer).

@item @code{dup(a) ( a-aa)}. Duplicate the topmost stack item (address).
      This primitive is commented out by default. Uncomment to activate.

@item @code{2dup ( nn-nnnn)}. Duplicate the topmost pair of stack items
      (two integers).@*
@item @code{2dup(na) ( na-nana)}. Deactivated type variant.@*
@item @code{2dup(aa) ( aa-aaaa)}. Deactivated type variant.@*
@item @code{2dup(an) ( an-anan)}. Deactivated type variant.

@item @code{drop ( n-)}. Forget topmost stack item (integer).@*
@item @code{drop(a-) ( a-)}. Forget topmost stack item (address).

@item @code{nip       ( nn-n)}. Forget second stack item.@*
@item @code{nip(aa-a) ( aa-a)}. Forget second stack item.@*
@item @code{nip(an-n) ( an-n)}. Forget second stack item.@*
@item @code{nip(na-a) ( na-a)}. Forget second stack item.

@item @code{tuck ( nn-nnn)}.
      Put a copy of the topmost stack item below the second one
      (both integers).
@item @code{tuck(aa-aaa) ( aa-aaa)}. Deactivated type variant.
@item @code{tuck(na-ana) ( na-ana)}. Deactivated type variant.
@item @code{tuck(an-nan) ( an-nan)}. Deactivated type variant.

@item @code{swap ( nn-nn)}. Swap topmost two stack items (both integers).
@item @code{swap(aa-aa) ( aa-aa)}. Deactivated type variant.

@item @code{over ( nn-nnn)}. Put a copy of the second stack item over
      the (former) topmost one (both integers).
@item @code{over(an-ana) ( an-ana)}. Put a copy of the second stack item
      (address) over the (former) topmost one (integer).
@item @code{over(na-nan) ( na-nan)}. Deactivated type variant.
@item @code{over(aa-aaa) ( aa-aaa)}. Deactivated type variant.
@end itemize

@*
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@dots{}). 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.


@node Genes reading from memory, Genes writing to memory, Stack juggling genes, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Genes reading a value from a memory address.

As explained elsewhere genes cannot access arbitrary addresses for
security and stability reasons.@*
@xref{Stack type symbols}.@*
@xref{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.
@itemize @minus

@item @code{@@ ( a-n)}. Read contents of address @code{a}.

@item @code{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).
@end itemize


@node Genes writing to memory, Dealing with overflow, Genes reading from memory, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Genes writing a value to a memory address

As explained elsewhere genes cannot access arbitrary addresses for
security and stability reasons.@*
@xref{Stack type symbols}.@*
@xref{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.
@itemize @minus

@item @code{! ( na-)}. Store integer @code{n} at address @code{a}.

@item @code{-! ( na-)}. Subtract integer @code{n} from the value at address
      @code{a} and store the new value at the same address.

@item @code{swap! ( an-)}. Store integer @code{n} at address @code{a}.@*
      This is like @code{!} with the parameters the other way round.

@item @code{off ( a-)}. Clear memory contents at address @code{a}.
@end itemize


@node Dealing with overflow, Nuc and spot variables, Genes writing to memory, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection 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@enddots{}
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 @code{!} or @code{+!} 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 @code{some}.

@itemize @minus

@item @code{!(some) ( na-)}.
      Store some fraction of @code{n} at address @code{a}.

@item @code{+!(some) ( na-)}.
      Read value at address @code{a}, add some of the value @code{n}
      and store result as new value at address @code{a}.

@item @code{-!(some) ( na-)}. Like above, but *subtract* some.

@item @code{swap!(some) ( an-)}. Like @code{!(some)}, but parameters swapped.

@item @code{take-some ( a-n)}. Takes some of the value away from address
      @code{a} preserving sign of the original value.
@end itemize


@node Nuc and spot variables, Global variables, Dealing with overflow, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Read/write and read/only nuc and spot variables.

These genes access different classes of variables.@*
@xref{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 @code{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.

@itemize @minus

@item @code{organ-A ( -a)}, @code{organ-B ( -a)}, @code{organ-C ( -a)},
      @enddots{}
      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.

@item @code{parameter-A@ ( -n)}, @code{parameter-B@ ( -n)},
      @code{parameter-C@ ( -n)}, @enddots{}
      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).

@item @code{A-quality ( -a)}, @code{B-quality ( -a)},
      @code{C-quality ( -a)}, @enddots{}
      Read/write spot variables, passing their address on the stack.

@item @code{A-property@ ( -n)}, @code{B-property@ ( -n)},
      @code{C-property@ ( -n)}, @enddots{}
      Read/only spot variables passing their current value on the stack.
@end itemize


@node Global variables, Insight genes, Nuc and spot variables, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection 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.

@itemize @minus
@item @code{integer-A@@ ( -n)}, @code{integer-B@@ ( -n)},
      @code{integer-C@@ ( -n)}, @enddots{}
@item @code{dfloat-A-f@@ ( -r)}, @code{dfloat-B-f@@ ( -r)}, @enddots{}
@end itemize

The number of these variables is configured by compile time options.


@node Insight genes, Float arithmetic genes, Global variables, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection 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.

@itemize @minus

@item @code{age@ ( -n)}.
      Gene giving the current age of the individual.

@item @code{age-threshold@ ( -n)}.
      Maximal possible age.

@item @code{energy@ ( -n)}.
      Gene giving the cells current energy level.

@item @code{reproduction-threshold@ ( -n)}.
      How much energy needed for reproduction.
@end itemize


@node Float arithmetic genes, More float arithmetics, Insight genes, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Basic floating point maths
@itemize @minus

@item @code{ f+ ( rr-r )}. Floating point addition.

@item @code{ f- ( rr-r )}. Floating point subtraction.

@item @code{ f* ( rr-r )}. Floating point multiplication.

@item @code{ f/ ( rr-r )}. Floating point division.
@end itemize


@node More float arithmetics, Logarithms and exponentials, Float arithmetic genes, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection More floating point operator primitives
@itemize @minus

@item @code{ fnegate ( r-r )}. Floating point negation.

@item @code{ fabs ( rr-r )}. Floating point absolute value.

@item @code{ fmax ( rr-r )}. Floating point maximum.

@item @code{ fmin ( rr-r )}. Floating point minimum.

@item @code{ f2* ( r-r )}. Double floating point value.

@item @code{ f2/ ( r-r )}. Divide floating point value by two.

@item @code{ 1/f ( r-r )}. Floating point reciprocal.
@end itemize


@node Logarithms and exponentials, Trigonometry, More float arithmetics, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Logarithms, exponentials, roots

Aliases of ANS Forth float functions.  See ANS Forth documentation.

@itemize @minus
@item @code{ f** ( rr-r )}.

@item @code{ fsqrt ( r-r )}.

@item @code{ fexp ( r-r )}.

@item @code{ fexpm1 ( r-r )}.

@item @code{ fln ( r-r )}.

@item @code{ flnp1 ( r-r )}.

@item @code{ flog ( r-r )}.

@item @code{ falog ( r-r )}.
@end itemize


@node Trigonometry, Mixed maths, Logarithms and exponentials, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Trigonometric functions gene primitives

Aliases of ANS Forth float functions.  See ANS Forth documentation.

@itemize @minus
@item @code{ fsin ( r-r )}.

@item @code{ fcos ( r-r )}.

@item @code{ fsincos ( r-rr )}.

@item @code{ ftan ( r-r )}.

@item @code{ fasin ( r-r )}.

@item @code{ facos ( r-r )}.

@item @code{ fatan ( r-r )}.

@item @code{ fatan2 ( rr-r )}.

@item @code{ fsinh ( r-r )}.

@item @code{ fcosh ( r-r )}.

@item @code{ ftanh ( r-r )}.

@item @code{ fasinh ( r-r )}.

@item @code{ facosh ( r-r )}.

@item @code{ fatanh ( r-r )}.

@item @code{ pi ( -r )}.
@end itemize


@node Mixed maths, Type casts, Trigonometry, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Mixed integer/float operators

@itemize @minus
@item @code{ f+i ( rn-r )}.
      Add integer value to a float and give result as float.

@item @code{ f-i ( rn-r )}.
      Subtract integer value from a float and give result as float.

@item @code{ f*i ( rn-r )}.
      Multiply a float value by a integer and give result as float.

@item @code{ f/i ( rn-r )}.
      Divide a float value by a integer and give result as float.

@item @code{ i/i ( nn-r )}.
      Divide a integer value by another integer and give result as float.

@item @code{ i+f ( nr-r )}.
      Add float value to a integer and give result as float.

@item @code{ i-f ( nr-r )}.
      Subtract float value from a integer and give result as float.

@item @code{ i*f ( nr-r )}.
      Multiply an integer by a float value and give result as float.

@item @code{ i/f ( nr-r )}.
      Divide an integer by a float value and give result as float.

@item @code{ f/f ( rr-n )}.
      Divide a float by another float and give result as integer.

@item @code{ f*f ( rr-n )}.
      Multiply two floats and give result as integer.

@item @code{ i*f>i ( nr-n )}.
      Multiply an integer by a float and give result as integer.

@item @code{ i/f>i ( nr-n )}.
      Divide an integer by a float and give result as integer.
@end itemize


@node Type casts, Read float values, Mixed maths, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Casts between integer and floating point

@itemize @minus
@item @code{ f>s ( r-n )}. Transform a float to an integer.

@item @code{ s>f ( n-r )}. Transform an integer to a float.
@end itemize


@node Read float values, Store float values, Type casts, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Fetching floats from memory

Brew stores all floats as dfloats (double-precision IEEE floating-point
format) for compatibility reasons.

@itemize @minus
@item @code{ df@ ( A-r )}. Read double-precision IEEE floating-point value.

@item @code{ f-take ( A-r )}. Read double-precision IEEE floating-point value
      actually 'taking it away' from the address (storing zero there).
@end itemize


@node Store float values, Float stack manipulation, Read float values, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Fetching floats from memory

Brew stores all floats as dfloats (double-precision IEEE floating-point
format) for compatibility reasons.

@itemize @minus
@item @code{ df! ( rA- )}. Store float as double-precision IEEE floating-point
      value at address A.

@item @code{ df+! ( rA- )}. Add float to the float stored at address A and
      store the sum as double-precision IEEE floating-point value at A.

@item @code{ df-! ( rA- )}. Subtract a float from the float stored at address A
      and store result as double-precision IEEE floating-point value at A.
@end itemize


@node Float stack manipulation, Nuc and spot floats, Store float values, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Arranging items on the float stack

@itemize @minus
@item @code{ fdup ( r-rr )}. Clone topmost float stack item.

@item @code{ fdrop ( r- )}. Forget topmost float stack item.

@item @code{ fswap ( rr-rr )}. Exchange the two topmost float stack items.

@item @code{ fover ( rr-rrr )}. Copy second float stack item to the top.

@item @code{ frot ( rrr-rrr )}. Rotate third float stack item to the top.

@item @code{ drop(float-pointer) ( A- )}. Forget address of float on top
      of data stack.
@end itemize


@node Nuc and spot floats, Gene conditionals, Float stack manipulation, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Float variables local to a nuc or spot

These variables are the floating point versions of nuc and spot variables.
@xref{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:

@itemize @minus
@item @code{ f-organ-A ( -A )}.  Gives address of first read/write nuc
      local floating point variable.

@item @code{ f-parameter-B-f@ ( -r )}.  Gives value of second read only nuc
      local floating point variable.

@item @code{ A-f-quality ( -A )}.  Gives address of first read/write spot
      local floating point variable.

@item @code{ C-f-property@ ( -r )}.  Gives value of third read only spot
      local floating point variable.
@end itemize


@node Gene conditionals, Floating point comparison, Nuc and spot floats, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Conditionally executing gene sequences

Gene sequences can contain @code{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 @code{[IF] [ELSE] [THEN]} during trial phase, as code is interpreted
(not yet compiled) then. Of course brew takes care about that.
@itemize @minus

@item @code{g-IF-ELSE-THEN ( C-)} is a pseudo gen, which is never
      executed, but triggers insertion of a @code{IF ELSE THEN} structure.
      Setting relative probability of this pseudo gene in a gene pool
      therefore influences frequency of @code{IF ELSE THEN} structures
      relative to other flag taking genes (like @code{AND} or @code{OR}).
      (@pxref{Probability lists}).

@item @code{IF ( C-)}, @code{[IF] ( C-)}. Conditional branch.
@item @code{ELSE}, @code{[ELSE]}. Starts alternative sequence.
@item @code{THEN}, @code{[THEN]}. Ends conditional structure.

@item @code{ 0= ( n-C)}. True if n is zero.

@item @code{ 0< ( n-C)}. True if n is below zero.

@item @code{ 0> ( n-C)}. True if n is positive and not zero.

@item @code{ = ( nn-C)}. True if the two integers are equal.

@item @code{ > ( nn-C)}. True if the first integer is bigger.

@item @code{ < ( nn-C)}. True if the first integer is smaller.

@item @code{ within ( nnn-C)}. True if the first integer is at least as big
      as the second one, but smaller than the third (topmost) one.

@item @code{ AND ( CC-C)}. True if both flags are true.

@item @code{ OR ( CC-C)}. True if at least one flag is true.

@item @code{ XOR ( CC-C)}. True if exactly one flag is true.
@end itemize


@node Floating point comparison, Genome pool, Gene conditionals, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Conditions based on floating point values
@itemize @minus

@item @code{ f< ( rr-C)}. 

@item @code{ f> ( rr-C)}. 

@item @code{ f0< ( r-C)}. 

@item @code{ f0= ( r-C)}. 
@end itemize


@node Genome pool,  , Floating point comparison, Gene primitives
@comment  node-name,  next,  previous,  up
@subsection Genome pools

Brew can put successfully tested genes into a genome pool.@*
Switch that on or off in @samp{Mutation menu}.@*
@xref{Mutation menu}.

Genome pools serve two distinct purposes:
@itemize @bullet

@item @samp{Genomes as gene building blocks}.  Whole genomes that
      have proven to be useful can be reused like gene primitives
      to build new genes.

@item @samp{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.
      (@pxref{Mutation types menu}).
@end itemize


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.@*
@xref{Probability lists}.


@node Gene edit menu, Scanning nucs, Gene primitives, Users manual
@comment  node-name,  next,  previous,  up
@section 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 @kbd{e} will write the genome to a
file and call and external editor (defined in @file{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.
(@pxref{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 @xref{Genes files}, if you want to define new gene
primitives. (You could define genes from the Forth input line, if you want to.
@pxref{Using Forth in menus}).


@node Scanning nucs, Scanning spots, Gene edit menu, Users manual
@comment  node-name,  next,  previous,  up
@section Scanning nucs

If you press @kbd{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.
(@pxref{Scrolling menus}).  At one given time either integer or floating
point variables are displayed.  Toggle between them with @kbd{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. @samp{Nuc menu} will also switch to the same kind.
@pxref{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:
@format

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
@end format

@*
Selecting a @samp{min} @samp{max} or @samp{average} value will port you to
a nuc subset screen of the nucs having the value in question.@*
@xref{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:
@format

                *
                *
                *
                *
                *
                **
                ***       *
                ***       *
                ****     **
                **** *   **
                ******* *****
                *************
                *************  *
       *      ***************  *   *
    ** **     ***************  **  *
   *******   ********************  *
 * ******* * ***********************  * ***
 ************************************ * ****        *
************************************* ************ **  *       *
*****************************************************.****.....*.. *...*.     .
-129        scanning: energy                       vertical range: 69      2260
@end format

Selecting a bar of this display type will port you to a @samp{Menu nuc subsets}
with the value range in question, to do more analysis or so.
@xref{Menu nuc subsets}.

@*
@xref{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:

@format
f-organ-A         min: 0          max: 3.1415926536  avr: .0436332313    .r..
@end format

There are four signs at the right border, either dots or @samp{-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
@strong{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:

@format
Type counts:        -infinity:     real:          +infinity:     nan:

f-organ-A           0              72             0              0
@end format

Selecting a title entry like @samp{-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 @samp{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.@*
@xref{Menu nuc subsets}, @xref{Menu spot subsets}, for documentation.

Toggle back with @kbd{o}, or by selecting @samp{Type counts}.


@node Scanning spots, Configurable actions, Scanning nucs, Users manual
@comment  node-name,  next,  previous,  up
@section Scanning spots

If you press @kbd{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.
(@pxref{Scrolling menus}).

It works exactly as the corresponding menu for nuc statistics.@*
@xref{Scanning nucs}, for more information.


@node Configurable actions, Menu current genomes, Scanning spots, Users manual
@comment  node-name,  next,  previous,  up
@section 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).
@itemize @bullet

@item @samp{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.

@item @samp{Action}. On all spots and/or nucs (depending the situation)
      where @samp{condition} is @code{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.
@end itemize

@*
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.
@end menu

@*
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@enddots{}  So if you tell brew to multiply the action pointer
(@code{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?


@node Simple nuc conditions, Simple spot conditions, Configurable actions, Configurable actions
@comment  node-name,  next,  previous,  up
@subsection Simple conditions defining a nuc subset.

These conditions do not require any parameters.
@itemize @bullet

@item @samp{true}. Do with everybody.

@item @samp{selected?}. Do with all selected nucs.

@item @samp{on-trial?}. Do with all nucs in trial phase.

@item @samp{fertile?}.
      Do with all nucs that would have enough energy to reproduce.

@item @samp{will-die?}. Do with all nucs that will die this life step.
@end itemize


@node Simple spot conditions, Extended conditions, Simple nuc conditions, Configurable actions
@comment  node-name,  next,  previous,  up
@subsection Simple conditions defining a spot subset.

These conditions do not require any parameters.
@itemize @bullet

@item @samp{everywhere}. Unconditionally do everywhere.

@item @samp{inhabited?}. Do on all inhabited spots.

@item @samp{empty?}. Do on all spots that are *not* inhabited.
@end itemize


@node Extended conditions, Generic nuc/spot actions, Simple spot conditions, Configurable actions
@comment  node-name,  next,  previous,  up
@subsection Extended conditions comparing two values

The condition is based on the comparison of two values.@*
These conditions do require additional parameters and the comparison:
@itemize @bullet

@item @samp{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
      @code{secrets}. You can act like a god in this virtual universe ;-)

@item @samp{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.

@item @samp{variable-within}. The value of a variable is chequed to
      be within two border values. The lower border is inclusive,
      the upper exclusive. So @samp{0 3 WITHIN} is true for 0, 1 and 2,
      but not for 3. The flag is compared against @samp{true}, so use
      @samp{=} for values that are within the range and @samp{<>} for
      all values that are outside range as comparison (see below).

@item @samp{function-number}. The return value of a function (like the
      score of a cell) is compared to a numeric value.

@item @samp{function-within}. The return value of a function is tested
      if it is between two given numeric values.

@item @samp{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@enddots{}  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
@samp{df-variable-number}. The following words work on dfloat variables
only to test value types:

@item @samp{df-var-real?}. True if the value is real.

@item @samp{df-var-inf?}. True for infinities of both signs.

@item @samp{df-var-pos-inf?}. True for positive infinity.

@item @samp{df-var-neg-inf?}. True for negative infinity.

@item @samp{df-var-nan?}. True if it is not a number (NAN).


@item @samp{Comparison}. The above functions give two values which are
      compared by one of the following comparisons:
@itemize @bullet

      @item @code{<}.  Do it if first value is smaller.

      @item @code{<=}. Do it if first value is smaller or equal.

      @item @code{>}.  Do it if first value is bigger.

      @item @code{>=}. Do it if first value is bigger or equal.

      @item @code{=}.  Do it if both values are equal.

      @item @code{<>}. Do it if the values are different.
@end itemize
@end itemize


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).


@node Generic nuc/spot actions, Nuc specific actions, Extended conditions, Configurable actions
@comment  node-name,  next,  previous,  up
@subsection Generic nuc/spot actions

@itemize @bullet

@item @samp{set-variable}. Set a variable to a given value.
      You should select the variable and enter the value next.

@item @samp{add-to-variable}. Add a value to a given variable.
      You should select the variable and enter the value next.

@item @samp{sub-from-variable}. Subtract a value from a given variable.
      You should select the variable and enter the value next.

@item @samp{scale-variable}. Multiply a given variable by a scale (like 1/2).
      You should select the variable and enter the scale next.
      (@pxref{Scale input}).

@item @samp{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@enddots{}
@end itemize


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).


@node Nuc specific actions, Defining maybe-do actions, Generic nuc/spot actions, Configurable actions
@comment  node-name,  next,  previous,  up
@subsection Nuc specific actions

In addition to the generic actions on nuc and/or spot variables
you can program the following nuc specific actions:
@itemize @bullet

@item @samp{select-nuc}. Select nuc.

@item @samp{de-select-nuc}. De-select nuc.

@item @samp{toggle-selection}. Toggle selection status of the nuc.

@item @samp{remove-nuc}. Remove the nuc.
@end itemize


@node Defining maybe-do actions, Menu nuc subsets, Nuc specific actions, Configurable actions
@comment  node-name,  next,  previous,  up
@subsection Defining maybe-do actions

I call this mechanism of conditionally executing user defined actions
@code{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:
@format

Setup condition and action first.
Simple condition:    false
What to do:          noop
@end format

@samp{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:
@format

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
@end format

Selecting the first line of the example, will actually *do* it now.


@node Menu nuc subsets, Menu spot subsets, Defining maybe-do actions, Configurable actions
@comment  node-name,  next,  previous,  up
@subsection Menu interface to act on a nuc subset

This menu is the user interface to use the @samp{maybe-do} functions
on nucs. @xref{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.
@itemize @bullet

@item @samp{DO IT}.
      Do the user defined action on each nuc that fulfils the condition.

@item @samp{Show subset}.
      Show a world map with the subset coloured.

@item @samp{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.

@item @samp{Scan this subset}.
      Give a summary about nuc variable values or more detailed ASCII bar
      graphs about value distribution on each variable. @xref{Scanning nucs},
      for a description. Called from this entry data is collected from nucs
      fulfilling the condition only.

@item @samp{Scan nucs}.
      Same but with data from *all* nucs for comparisons.

@item @samp{Scan world}.
      Scan over all spots. Not directly related, but useful sometimes.
      @xref{Scanning spots}, for a description how it works.
@end itemize


@node Menu spot subsets,  , Menu nuc subsets, Configurable actions
@comment  node-name,  next,  previous,  up
@subsection Menu interface to act on a spot subset

This menu is the user interface to use the @samp{maybe-do} functions
on spots. @xref{Configurable actions}, for an explanation what it does
and how to configure it.

It works on spots analogous to the @samp{Menu nuc subsets}.@*

@xref{Menu nuc subsets}, for more information.


@node Menu current genomes, Menu select nucs, Configurable actions, Users manual
@comment  node-name,  next,  previous,  up
@section Menu current genomes

Pressing @kbd{U} (or @kbd{u} as a shortcut) from brews main screen
takes you to the @samp{Menu current genomes}. This menu deals with the
genomes of all currently living cells. (@pxref{Scrolling menus}).
The start of the menu screen might look similar to this:@*
@format

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
[ @dots{} ]
@end format

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:
@itemize @bullet

@item @samp{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 @kbd{i} or @kbd{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. @xref{Menu this genome}.

@item @samp{genome}.
      Name of the compiled genome, if any. As genomes on trial have no name
      yet @code{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
      @code{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.

@item @samp{count}. Number of living cells with this genome.
      Press @kbd{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.

@item @samp{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 @kbd{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. @xref{Colouring on difference}.

@item @samp{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 @kbd{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. @xref{Colouring on difference}.

@end itemize

@menu
* Colouring on equality::       Display cells with same amount of a quality.
* Colouring on difference::     Displaying @samp{less}, @samp{equal}, @samp{more} type info.
* Menu this genome::            Examining all cells having the same genome.
@end menu


You can look at each listed genome one after the other by pressing one of 
the following keys:

@itemize @bullet
@item @kbd{@key{<SPACE>}} to go to corresponding @samp{Menu this genome}.

@item @kbd{l} or @kbd{n} to see the genomes Forth code.

@item @kbd{.} to call @samp{.gene-info} on the genome. In the case
      of genomes on trial it shows the evaluated Forth code instead.
@end itemize

The @samp{current} line will be indicated by a @samp{*} before genome name,
and go down one line after examining the genome.


@node Colouring on equality, Colouring on difference, Menu current genomes, Menu current genomes
@comment  node-name,  next,  previous,  up
@subsection 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 @samp{color-selected-fg-xt} and
@samp{color-miss-fg-xt} for foreground colours (showing nucs), respectively
@samp{color-selected-bg-xt} and @samp{color-miss-bg-xt} for background
colours (showing spots) in @file{my-brew-options.fs}.

As an example brew uses it to show you all cells sharing the same genome.

@xref{World map interaction}, to learn what else you can do here.


@node Colouring on difference, Menu this genome, Colouring on equality, Menu current genomes
@comment  node-name,  next,  previous,  up
@subsection 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 @samp{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 @samp{Colouring on difference}.

@*
The meanings of the (default) colours (on foreground) are:
@itemize @bullet

@item @samp{magenta}. Lower, less of the quality in question.

@item @samp{white}. Inside range or equal amount of the quality in question.

@item @samp{cyan}. Higher, more of the quality in question.
@end itemize

If you don't like the colours change @samp{color-below-fg-xt},
@samp{color-selected-fg-xt} and @samp{color-above-fg-xt} for the
foreground colours (showing nucs), respectively @samp{color-below-bg-xt},
@samp{color-selected-bg-xt} and @samp{color-above-bg-xt} for the
background colours (showing spots) in @file{my-brew-options.fs}.

@*
@xref{World map interaction}, to learn what else you can do here.


@node Menu this genome,  , Colouring on difference, Menu current genomes
@comment  node-name,  next,  previous,  up
@subsection Menu this genome

You'll get here normally selecting a entry for a genome from menu
@samp{Menu current genomes}. (Which you reach by pressing @kbd{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.

@itemize @bullet

@item @samp{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.

@item @samp{.gene-info}.
      This entry gives you more informations about the genome.

@item @samp{show cells}.
      Show a world map with cells having this genome coloured.
      (@pxref{Colouring on equality}).

@item @samp{show younger/older}.
      Show a three color world map on age of genome relative to this one.
      (@pxref{Colouring on difference}).

@item @samp{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. (@pxref{Scanning nucs}).

@item @samp{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.

@item @samp{Select these nucs}.
      Set the @samp{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).

@item @samp{clear selection}.
      Clear the @samp{selected} flag in all the nucs having this genome.

@item @samp{toggle selection}.
      Invert the @samp{selected} flag in all the nucs having this genome.

@item @samp{Do something on these nucs}.
      This is the @samp{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.
      @xref{Configurable actions}, for more info.
@end itemize


@node Menu select nucs, World menu, Menu current genomes, Users manual
@comment  node-name,  next,  previous,  up
@section Menu select nucs

This menu deals with the selection status of nucs.@*
You get here from brews main screen by pressing @kbd{T}.@*
The title line tells you how many nucs are selected and how many aren't.

@*
Nucs can be @samp{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 @samp{maybe-do} functions
(@pxref{Configurable actions}), but there are some differences:
@itemize @bullet

@item @samp{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.

@item @samp{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.

@item @samp{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.
@end itemize

@*
Menu features:
@itemize @bullet

@item @samp{show selected}.
      Show a world map where all selected cells are coloured.

@item @samp{colour}.
      Configure colour of selected cells in the map described above.
      The default is @samp{red}.

@item @samp{deselect all}.
      Clear all selections of all cells.

@item @samp{toggle selections}.
      Invert selections of all nucs.

@item @samp{scan SELECTED nucs}.
      Statistical informations about all selected nucs.
      (@pxref{Scanning nucs}).

@item @samp{scan ALL nucs}.
      Statistical informations about *all* nucs for comparisons.
@end itemize

@*
There are two interfaces to the @samp{maybe-do} feature, one for changing
selections based on a condition, the other to do configurable actions on
all selected nucs (@pxref{Configurable actions}).
@itemize @bullet

@item @samp{Change selections}.
      This interface gives you the possibility to @samp{select},
      @samp{de-select}, @samp{toggle (invert) selection} on all nucs
      fulfilling a freely configurable condition.
      Click @samp{DO IT} to actually change selections in the configured way.

@item @samp{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 @samp{DO on selected nucs} after configuring to trigger the action.
@end itemize


@node World menu, World list menu, Menu select nucs, Users manual
@comment  node-name,  next,  previous,  up
@section 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 @kbd{W}.

The menu title line tells you how many dimensions of what size this world has.


@itemize @bullet
@item @samp{Name}.
      The first line starts with the worlds name. Select and change to
      whatever you like.

@item @samp{3/5}.
      Would say that you are in world # 3 of 5.

@item @samp{SELECT}.
      Change to another world. @xref{World list menu}.

@item @samp{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).
@end itemize

Following items are purely informative, you cannot change them:

@itemize @bullet
@item @samp{spots}.
      Number of spots in this universe.

@item @samp{living}.
      How many cells life in this world at the moment.

@item @samp{on trial}.
      How many cells are currently on trial.
      Selecting this item will show a map of nucs on trial (if any).

@item @samp{selected}.
      Number of selected cells.
      Selecting this item will show a map of selected nucs (if any).

@item @samp{compiled}.
      Number of compiled genomes since start of this evolution.

@item @samp{max items}.
      Longest generated genome so far.

@item @samp{qualities}.
      Number of spot qualities (r/w variables local to the spot).
      (@pxref{Variable names}). This is configured at compile time.

@item @samp{properties}.
      Number of spot properties (r/o variables local to the spot).
      (@pxref{Variable names}). This is configured at compile time.

@item @samp{secrets}.
      Number of spot secrets (variables local to the spot,
      invisible to the genome).
      (@pxref{Variable names}). This is configured at compile time.
@end itemize

@*
The next few lines give information about dimensionality and size
of the current world and let you configure visibility ranges for
each dimension. @xref{World size and visibility}.

@*
The following three entries let you configure special actions that
might be needed for some sort of experiments:
@itemize @bullet

@item @samp{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.

@item @samp{nuc do before}.
      On inhabited spots this is called (after @samp{spot do}) just before
      waking up the nuc. The function defaults to noop.

@item @samp{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.

@item @samp{step do before}.
      Action done when starting a new step. Default is a noop.

@item @samp{step do after}.
      Action done after finishing a step. Default is a noop.
@end itemize

@*
Some interfaces to other world related functions:
@itemize @bullet

@item @samp{Scan world}.
      Interface to the world scan functions over all spots.
      (@pxref{Scanning spots}).

@item @samp{Scan nucs}.
      Interface to the nuc scan functions over all living cells.
      (@pxref{Scanning nucs}).

@item @samp{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. (@pxref{Individuals menu}).

@item @samp{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.
      (@pxref{Big Bang menu}).
@end itemize

@*
The rest of the world menu let's you define a action to do on spots that
meet a certain condition (@samp{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 @samp{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.
(@pxref{Configurable actions}).


@node World list menu, Big Bang menu, World menu, Users manual
@comment  node-name,  next,  previous,  up
@section List of worlds

You get to this menu by pressing @kbd{O} (like @samp{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.

@itemize @bullet
@item @samp{clone}.
      Clone this world including all it's cells and enter the cloned one.

@item @samp{remove}.
      Delete this world and remove all it's inhabitants.

@item @samp{save}.
      Save this world (without it's cells) to a huge text file.
@end itemize

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.


@node Big Bang menu, System menu, World list menu, Users manual
@comment  node-name,  next,  previous,  up
@section Big Bang menu

This menu let's you define and create another world.

You get here by pressing @kbd{B}+@kbd{B} (capital @samp{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 @samp{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.
@end menu

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. (@pxref{Individuals menu}). Also check
visibility ranges in the upper menu half, and configure them as you like.


@node World size and visibility, Big Bang, Big Bang menu, Big Bang menu
@comment  node-name,  next,  previous,  up
@subsection 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:
@format
1 dimension  spots: 80  visible from: 0         to: 80
@end format

The entries have the following meaning:
@itemize @bullet

@item @samp{n'th dimension}. Number of dimension.

@item @samp{spots}. Size of dimension range.
      If @samp{spots} is 80, coordinates would go from 0 to 79.

@item @samp{visible from}.
      Start of visibility range, lowest visible coordinate.

@item @samp{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.
@end itemize

If you have more than two dimensions you will see the following two entries:
@itemize @bullet

@item @samp{backgr.off}.
      Coordinate of third dimension after which background displaying is
      switched off. Up to this coordinate layers are opaque, after they
      become transparent.

@item @samp{Delay displaying layers}.
      Delay (theoretically in milliseconds) after displaying a (third
      dimensions) layer. A pause can help to understand the displayed
      three dimensional structure.
@end itemize

@*
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).

@format
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
@end format

@*
Tree dimensional world, only middle layer visible:

@format
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
@end format

@*
Tree dimensional world, all layers visible. Brew displays one layer after
the other, all opaque, and pauses a bit after each layer:

@format
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
@end format

@*
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:

@format
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
@end format


@node Big Bang,  , World size and visibility, Big Bang menu
@comment  node-name,  next,  previous,  up
@subsection Make a Big Bang

Here you define the geometry of your new world.
@itemize @bullet

@item @samp{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.

@item @samp{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.

@item @samp{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.
@end itemize

@*
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.


@node System menu, Log files menu, Big Bang menu, Users manual
@comment  node-name,  next,  previous,  up
@section System menu

This is the menu for brews system wide settings.@*
You get there by pressing @kbd{S} in brews main screen.

@itemize @bullet

@item @samp{Running in WORLD mode} or @samp{LINEAR mode}.
      Switches if the cells do have a virtual location or not.
      (@pxref{Run modes}).

@item @samp{Reset brew}.
      Reset brew by reading @file{brew-defaults.fs}, do a @samp{free-field}
      and reading @file{brew-init.fs} again.
      If you have included your personal initialisation files you might
      want to include them too.

@item @samp{Brew version}.
      Give detailed information about versions of different brew parts
      and about some compile time options. Please include this output in
      bug reports.

@item @samp{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.
      @xref{Selecting functions}, for a method to see the definitions
      of the used random generators.
@itemize @bullet

@item @samp{random-BRODIE}.
      Use the random generator given by Leo Brodie in his excellent Forth
      introduction book @cite{Starting FORTH}.
@itemize @bullet

@item @samp{Random seed}.
      Current value of the random seed.
@end itemize

@item @samp{random-generalised}.
      Use a more generic random generator.
@itemize @bullet

@item @samp{Random seed}.
      Current value of the random seed.

@item @samp{Random generator}.
      Value used internally for random number generation.
@end itemize
@end itemize

@item @samp{Can cells change qualities of the future?}.
      Genes can change spot qualities (@pxref{Variable names}).
      If this switch is ON the change survives a time step,
      otherwise it only takes effect in the present life step

@item @samp{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 @samp{world mode}.

@item @samp{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.

@item @samp{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.

@item @samp{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 @samp{world mode}.
@itemize @bullet

@item @samp{sequential calling spots forwards}.
      This is the normal setting, it's fastest (for technical reasons)
      and the only setting recommended for 3D views.

@item @samp{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.

@item @samp{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.

@item @samp{alternate direction, starting forwards}.
      This calls the spots sequentially, starting forwards. Quite slow.

@item @samp{alternate direction, starting backwards}.
      This calls the spots sequentially, starting backwards. Quite slow.
@end itemize

@item @samp{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
      @file{brew/OUTPUT/}.

@item @samp{Save world}.
      Save all world and spot data to a Forth text file.
      Writes a *huge* file.

@item @samp{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.

@item @samp{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. (@pxref{Experiments}).

@item @samp{World scan}.
      Statistics about all spot variables. (@pxref{Scanning spots}).

@item @samp{Nuc scan}.
      Statistics about all nuc variables. (@pxref{Scanning nucs}).

@item @samp{Function keys}.
      Configure function key bindings.

@item @samp{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).

@item @samp{Cursor wraps at borders} or @samp{Cursor stops at borders}.
      Switch between cursor wrapping or stopping, when moving over a
      screen border.

@item @samp{Fix screen size}.
      Include @file{configure-console.fs} to fix console size problems.

@item @samp{Fix cursor moving problems (beeping)}.
      If you have problems moving the cursor with the arrow keys you can try
      this function. Hope it helps.

@item @samp{Manual}.
      Call the external manual reader on top node. See the entry
      @samp{Documentation type} below, to switch between info and html.

@item @samp{Documentation type}.
      Select between using @samp{info} or a html browser as context
      sensitive documentation reader.

@item @samp{reader}.
      Displays information how the docu reader gets called. 
      Intended to track problems calling context documentation.

@item @samp{QUIT brew}.
      Quit brew cleaning up temporary files and informing you about
      produced output files, if any. 
@end itemize


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. @samp{COUNTING-WORDS}
@pxref{Programming tool files}) additional items might show up in
system menu.


@node Log files menu, Code file menu, System menu, Users manual
@comment  node-name,  next,  previous,  up
@section 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 @kbd{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@enddots{}

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@enddots{}

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:
@itemize @bullet

@item @samp{All}.
      This puts all the switches on. Don't do this ;-)

@item @samp{Most}.
      This puts nearly all the switches on. Don't do this ;-)

@item @samp{Nothing}.
      Switches logging back off.

@item @samp{Some}.
      Switches some basic information on.

@item @samp{spot}.
      Log when doing a new spot.

@item @samp{birth}.
      Log each birth of a cell.

@item @samp{death}.
      Log death of a cell.

@item @samp{organs}.
      Log value of organs (and other cell variables) before and after
      waking nucs.

@item @samp{meal}.
      Log how much food each cell got in each life step.

@item @samp{costs}.
      Log live and gene code costs.

@item @samp{trial}.
      Log nucs on trial.

@item @samp{movement}.
      Log movements of nucs.

@item @samp{emergency}.
      Log population emergencies.

@item @samp{pop-control}.
      Log working of population control.

@item @samp{step}.
      Log time steps.

@item @samp{spot-vars}.
      Log value of spot variables before and after waking nucs.

@item @samp{random}.
      Log state of random generator.

@item @samp{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.

@item @samp{mutation}.
      Log mutations.
      (You can't switch that off if a more detailed logging switch is on).

@item @samp{m-type}.
      Log type of mutations.
      (You can't switch that off if a more detailed logging switch is on).

@item @samp{m-some}.
      Log mutation working with some detail information.
      (You can't switch that off if a more detailed logging switch is on).

@item @samp{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).

@item @samp{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).

@item @samp{log-m-extra}.
      Log extensive about the detailed inner working of mutation.
      This option is not compiled in by default, only on request.


@item @samp{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.


@item @samp{Log file}.
      Log file name. Defaults to @file{brew/OUTPUT/log/brew.log}.

@item @samp{Writing code file}.
      Link to the code file menu: Write generated program code to a file.

@item @samp{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).
@end itemize

@*
@xref{Scrolling menus}.


@node Code file menu, Record and Playback, Log files menu, Users manual
@comment  node-name,  next,  previous,  up
@section Writing generated program code to a file.

Brew can write the produced Forth program code to a file, the so called
@samp{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 @kbd{m} and then
@kbd{c}.

On a Linux system you can watch mutation and selection at work in real time
by switching to another console and say
@code{tail -f OUTPUT/FORTH/gene-code.fs}.

@*
The menu gives you the following options:
@itemize @bullet

@item @samp{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.

@item @samp{Code file}.
      Name of the code file relative to @file{OUTPUT/FORTH/}.
      The default code file name is @file{OUTPUT/FORTH/gene-code.fs}.

@item @samp{file on trial SUCCESS}.
      If you switch that ON genomes will be written to the code file
      when they successfully survive the so called @samp{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.

@item @samp{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 @samp{normal} person would ever use brew
      anyway ;-)
@end itemize

@*
Switches what to put in the code file:@*
(The first three are compound switches).
@itemize @bullet

@item @samp{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.

@item @samp{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.

@item @samp{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. (@pxref{Stack type symbols}).

@item @samp{STRUCTURE only}.
      Include only structure building words like @samp{IF} @samp{ELSE}
      and @samp{THEN}. All other code is omitted. For quick inspection of
      the structure of genomes. You can't compile the resulting pseudo code,
      of course.


@item @samp{code}.
      Normally you'd want code to be in the code files, won't you?

@item @samp{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 (@pxref{Stack type symbols}).

@item @samp{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.

@item @samp{structures}.
      If you switch this on, but @samp{code} off, you will see structure
      building words, without code in between.

@item @samp{frames}.
      By @samp{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.

@item @samp{depth&cost}.
      Informations about minimal and maximal stack depth so far and about
      accumulated code costs go into the code file.

@item @samp{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 @samp{item-numbers}.
      Put a item number for each used gene primitive.
@end itemize


@node Record and Playback, Compile time options, Code file menu, Users manual
@comment  node-name,  next,  previous,  up
@section Brews record and playback feature.


You get to the Record and Playback menu by pressing @kbd{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@enddots{}

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@enddots{}

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
@itemize @minus
@item to make configuration files by configurating through the menu interface
      and saving the result as a record file.
@item to record evolutionary sessions to be able to replay them, try variations
      or such.
@item 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@enddots{}
@item to record a evolutionary session as a benchmark for your hardware or
      Forth system. There are some special tools to make benchmarks.
@item to make a demo which you'll send to me that I can see what people do
      with my program ;-)
@end itemize

@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.
@end menu


@node Recording from scratch, Record after playback, Record and Playback, Record and Playback
@comment  node-name,  next,  previous,  up
@subsection How to record an evolutionary session starting from scratch.

When you switch recording on in the @samp{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.
@itemize @bullet

@item @samp{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.

@item @samp{Please give record file name}.
      Brew reacts by asking you for a file name relative to
      @file{OUTPUT/rec-play/}
      and defaults to @file{OUTPUT/rec-play/brew-recorded.fs}.

@item @samp{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.
      (@pxref{Individuals menu}).

@item @samp{Now go back to the main screen and set the individual}.
      Brew guides you here, just do what it tells you to do ;-)

@item 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 @pxref{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.
@end itemize

The menu now looks like this:
@itemize @bullet

@item @samp{Record is ON}.
      Switch it off here when you'll have finished (but not before that).

@item @samp{Record file: brew-recorded.fs}.
      That's just informative now. You cannot change that during recording.

@item @samp{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.
@itemize @bullet

@item @samp{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.
@end itemize

@item @samp{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.

@item @samp{record comment}.
      Insert remarks as a comment into the record file. These notes will
      *not* be displayed during play back.
@itemize @bullet

@item @samp{Give a comment to be included in the record file}
      Enter your text here.
@end itemize

@item @samp{message input}.
      Edit a short message that will be displayed in the last line
      (@samp{info line}) during playback.
@itemize @bullet

@item @samp{Give a message to be displayed during playback}.
      The message must be shorter than one full line.

@item @samp{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.
@end itemize
@end itemize


@node Record after playback, Record benchmark, Recording from scratch, Record and Playback
@comment  node-name,  next,  previous,  up
@subsection 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.


@node Record benchmark, Playback, Record after playback, Record and Playback
@comment  node-name,  next,  previous,  up
@subsection Recording to be used as a benchmark


Brew has some special features to make it comparatively easy to create
very complex benchmarks.
@itemize @bullet

@item @samp{Record benchmark}.
      Select this if you want to record an evolutionary session as benchmark.

@item @samp{Please give record file name}.
      Same as for normal recording.

@item @samp{Now you should select an individual and set it to a spot}.
      Same as for normal recording.

@item @samp{Now go back to the main screen and set the individual}.
      Same as for normal recording.

@item Now you continue as usual, but you might spread some assert state
      entries at critical places to make sure the bench plays right.

@item @samp{Finish benchmark}.
      Do *not* switch recording off the normal way when you are done,
      but select this entry instead.
@itemize @bullet

@item @samp{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.

@item @samp{Shall I append code for benchmark start from command line?  y/n}.
      This would append code to @file{maybe-run-benchmark.fs} to recognise
      the new bench. See source for more information.

@item @samp{Give the benchmark name}.
      Please name your benchmark here.
@end itemize
@end itemize

@*
Brew now gives you a short information about what it has done, like:
@format

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
@end format

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
@code{CREATE benchmark-name} as in
@code{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.


@node Playback,  , Record benchmark, Record and Playback
@comment  node-name,  next,  previous,  up
@subsection Playback a recorded evolutionary programming session.


Select @samp{Playback} in the @samp{Record and Playback menu}.

Choose a playback file.@*
(If you don't, the default record file name is probed).

That's it@enddots{}


To interrupt playback just press a key. Brew will ask you if you want
to continue (@kbd{c}) or quit (@kbd{q}).


@node Compile time options, Menu function keys, Record and Playback, Users manual
@comment  node-name,  next,  previous,  up
@section Compile time options

THIS NODE DOES NOT EXIST YET ;-)@*

So you'd better read @file{compile-options.fs}@enddots{}


@node Menu function keys, Menu Demos, Compile time options, Users manual
@comment  node-name,  next,  previous,  up
@section Configuring function key bindings.

Here you configure function key bindings.@*
You reach this menu by pressing @kbd{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 @samp{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:
@itemize @bullet

@item @samp{noop}.
      Do nothing.

@item @samp{context-help}.
      Show the manual node corresponding to the context.

@item @samp{show-key-bindings}.
      Show active key bindings as pressing @kbd{k} would.
      @xref{Example key bindings}.

@item @samp{|feed-world|}.
      Feed the world an extra food portion.
      @xref{Food menu}.

@item @samp{nuc-scan-menu}.
      Gather statistical informations about all nucs.
      @xref{Scanning nucs}.

@item @samp{spot-scan-menu}.
      Gather statistical informations about all spots.
      @xref{Scanning spots}.

@item @samp{menu-step-display}.
      Configure brews main screens display when in step display.
      @xref{Step display menu}.

@item @samp{menu-nuc-subsets}.
      Do something on all nucs meeting a certain condition.
      @xref{Menu nuc subsets}.

@item @samp{menu-select-nucs}.
      Select or de-select nuc subsets.
      @xref{Menu select nucs}.

@item @samp{menu-current-genomes}.
      Examine different currently living genomes.
      @xref{Menu current genomes}.

@item @samp{food-menu}.
      Configure food supply.
      @xref{Food menu}.

@item @samp{menu-population-control}.
      Configure population control.
      @xref{Population control}.

@item @samp{diversification-menu}.
      Configure global and nuc/spot local variable diversifications.
      @xref{Diversification menu}.

@item @samp{color-menu}.
      Configure colors in brews main screen.
      @xref{Color menu}.

@item @samp{mutation-menu}.
      Configure mutation.
      @xref{Mutation menu}.

@item @samp{big-bang-menu}.
      Create a new world.
      @xref{Big Bang menu}.

@item @samp{world-list-menu}.
      Select world from worlds list.
      @xref{World list menu}.

@item @samp{world-menu}.
      Configure world wide options.
      @xref{World menu}.

@item @samp{actual-pool-menu}.
      Configure actual gene pool.
      @xref{Actual pool menu}.

@item @samp{gene-pool-menu}.
      Select gene pool.
      @xref{Gene pools menu}.

@item @samp{individuals-menu}.
      Select and edit predefined individuals to release in the world.
      @xref{Individuals menu}.

@item @samp{toggle-display-&-go}.
      Switch display type in brews main screen without stopping evolution.
      (Same as the @kbd{t} does).
      @xref{Display modes}.

@item @samp{do-FORTH}.
      Enter Forth program source and interpret it.
      @xref{Using Forth in menus}.

@item @samp{toggle-anything}.
      Toggle a flag variable called @code{anything}, which you can use
      as you like. @samp{anything} is not used by brew itself.

@item @samp{function-key-menu}.
      Go to this menu.

@item @samp{display-menu}.
      Configure display of brews main screen.
      @xref{Display menu}.

@item @samp{code-file-menu}.
      Configure writing generated code to a file.
      @xref{Code file menu}.

@item @samp{rec/play-menu}.
      Record your interactions with brew or replay your session.
      @xref{Record and Playback}.

@item @samp{log-menu}.
      Configure writing log files.
      @xref{Log files menu}.

@item @samp{system-menu}.
      Configure system wide options.
      @xref{System menu}.

@item @samp{menus-menu}.
      Go to brews super menu.
      @xref{Menus menu}.

@item @samp{|goodbye|}.
      Quit brew.
@end itemize


@node Menu Demos, Experiments, Menu function keys, Users manual
@comment  node-name,  next,  previous,  up
@section 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@enddots{}

There should be a @samp{default} demo, which explains default brew
initialisation of the brew version you are running.


@node Experiments,  , Menu Demos, Users manual
@comment  node-name,  next,  previous,  up
@section 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
@samp{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 @file{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
@file{INPUTS/experiments/}. The initialisation file will include
source files for the experiment on it's own.


@xref{System menu}, for how to include files.


@node Programmers manual,  , Users manual, Top
@comment  node-name,  next,  previous,  up
@chapter Programmers manual

sorry@dots{} 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.
@end menu


@node Files,  , Programmers manual, Programmers manual
@comment  node-name,  next,  previous,  up
@section 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 @file{brew/OUTPUT/} directory.
* Temporary files::             Files in @file{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.
@end menu


@node Directory tree, Program files, Files, Files
@comment  node-name,  next,  previous,  up
@subsection Brews default directory tree

@itemize @bullet
@item @file{brew/INPUTS/}
      Directory for input files (except configuration files). You can change
      it by defining @samp{input-dir} as compile option.

@itemize @bullet
@item @file{brew/INPUTS/genes/}
      Directory for genes (of the new gene/mutation version). Predefined
      relative to @file{INPUTS/}.

@item @file{brew/INPUTS/experiments/}
      Directory for experiments (@pxref{Experiments}), each one having
      it's own subdirectory, which are not listed here.

@item @file{brew/INPUTS/extensions/}
      Directory for optional extensions.

@itemize @bullet
@item @file{brew/INPUTS/extensions/debugging/}
      Directory for optional debugging extensions. See the README files
      in the directory.

@end itemize
@item @file{brew/INPUTS/individuals/}
      Directory for individuals.
@end itemize


@item @file{brew/OUTPUT/}
      Directory for all output files.
      You can change it by defining @samp{out-dir} as compile option.

@itemize @bullet
@item @file{brew/OUTPUT/FORTH/}
      Directory for Forth code text files created by brew.
      Predefined relative to @file{OUTPUTS/}.

@item @file{brew/OUTPUT/rec-play/}
      Brew puts it's recorded files (as Forth source text files) here.
      Predefined relative to @file{OUTPUTS/}.

@item @file{brew/OUTPUT/log/}
      Brews log file directory.
      Predefined relative to @file{OUTPUTS/}.

@item @file{brew/OUTPUT/tmp/}
      Temporary brew files.
      Predefined relative to @file{OUTPUTS/}.
      Brew also puts some special output files here telling you that it has
      done so.
@end itemize


@item @file{brew/texi/}
      Main documentation directory.
@end itemize


@node Program files, Genes files, Directory tree, Files
@comment  node-name,  next,  previous,  up
@subsection Brew program source files

@itemize
@item @file{brew.fs}
      Main program file.

@item @file{system-dependent.fs}
      Fork to load system dependent adaptions and definitions.

@itemize @bullet
      @item @file{gforth.fs}
            Adaptions to Gforth.

      @item @file{pfe.fs}
            Adaptions to pfe.

      @item @file{iForth.fs}
            Adaptions to iForth.

      @item @file{bigFORTH.fs}
            BigForth adaptions.
@end itemize

@item @file{common-words.fs}
      Words commonly found in many Forth systems.
      Define them if they are not defined in the used Forth system.

@item @file{basics.fs}
      Some basic definitions I use in my programs.

@item @file{advanced.fs}
      Some basic definitions which can't be defined in @file{basics.fs} yet.

@item @file{brew-basics.fs}
      Some basic brew words. Defining them early avoids some
      dependency problems.

@item @file{allocation-pointers.fs}
      Deals with allocated memory blocks that will possibly get resized.

@item @file{block-variables.fs}
      Attempt to get faster variables in memory blocks. Depreciated.

@item @file{blockVARIABLEs-brew.fs}
      Brew variables defined as @samp{block-variables}. Depreciated.

@item @file{dp-speed-align.fs}
      Trying influence of aligning dictionary pointer on speed.

@item @file{memory-speed-align.fs}
      Aligning chunks of memory for speed.

@item @file{random.fs}
      Random number generators.

@item @file{lists.fs}
      Linked lists, possibly having multiple data fields.

@item @file{listed-masks.fs}
      Masks to be written as text (i.e. as Forth source).

@item @file{string-lists.fs}
      Lists containing stringbuf handles for dynamic string storage.

@item @file{string-replace.fs}
      Building tables of fixed strings and using them to replace strings
      by other strings.

@item @file{association-lists.fs}
      Lists of keys and associated data.

@item @file{probability-lists.fs}
      Lists with relative probabilities to be selected randomly.

@item @file{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.

@item @file{stringbuf-0.4.fs}
      Memory buffers originally implemented to concatenate strings and the
      like. Used in brew for many different purposes.

@item @file{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.

@item @file{console-codes.fs}
      Cursor and color management for the Linux text console.

@item @file{screen-size.fs}
      Screen size constants (defaults).

@item @file{display.fs}
      High level brew display interface.

@item @file{keybuf.fs}
      Simple key buffering.

@item @file{user-IO.fs}
      Advanced keyboard I/O words.

@item @file{key-mapping.fs}
      Maps special key events to menu key codes.

@item @file{mouse.fs}
      Faked mouse interface on top of an old implementation for Atari.
      Waiting to be reactivated on Linux console.

@item @file{menu.fs}
      User interface as active text menus.

@item @file{fileselect.fs}
      Experimental simple file interface.

@item @file{maybe-do.fs}
      User interface to do quite arbitrary things on nucs or spots that
      meet a certain condition. Quite hairy code...

@item @file{worlds.fs}
      Virtual world. New version allowing multiple multi dimensional worlds
      of arbitrary size.

@item @file{world-loop.fs}
      Looping over all spots of the virtual world.

@item @file{world-spots-arrayed.fs}
      Spots implemented as arrays.

@item @file{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@enddots{} 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.

@item @file{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.

@item @file{genes-0.3.fs}
      Newer gene/mutation implementation.

@item @file{mutation-0.3.fs}
      Newer gene/mutation implementation.

@item @file{gene-edit.fs}
      User interface to examine genes and whole genomes and to edit them by
      hand.

@item @file{gene-alternatives.fs}
      Some genes like @samp{drop} or @samp{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
      @samp{drop} or @samp{swap} when he edits a genome by hand. So brew
      must be able to figure out what exactly was meant.
 
@item @file{gene-pool.fs}
      Gene pools with relative probabilities to be used by mutation.

@item @file{statistics.fs}
      ASCII bar graphs of statistical data.

@item @file{reporting.fs}
      Writing very detailed log files.

@item @file{manual.fs}
      Show manual node corresponding to the context. 

@item @file{dynamic-key-bindings.fs}
      Interpreting this file adds some key bindings in brews main screen
      if the words are defined.

@item @file{mixed-old-stuff.fs}
      Mixed relicts from very early brew development still used in some
      old demos, benchmarks and the like.

@item @file{INPUTS/individuals/old-brew-individuals.fs}
      Individuals left over from very old brew versions.

@item @file{old-demos.fs}
      Old style demos not guaranteed to work in this brew version any more.

@item @file{maybe-run-benchmark.fs}
      Fork to run benchmarks if a benchmark name is defined from command line.

@item @file{bcompat-11-12.fs}
      Downwards compatibility to run @samp{transit-11-bench-A} and
      @samp{transit-12-bench}.

@item @file{debuging.fs}
      Words to help debugging.

@item @file{faked-genes.fs}
      Faking some genes for interactive debugging.

@item @file{compile-switches.fs}
      Compile features, leave them out or compile them with a run time
      switch. New and not used yet.

@item @file{scan.fs}
      New scanning mechanism. Not used yet.
@end itemize


@node Genes files, Configuration files, Program files, Files
@comment  node-name,  next,  previous,  up
@subsection Files with gene primitives

The gene primitives (of the new genes/mutation version) get loaded
from @file{brew/INPUTS/genes/}.

@itemize
@item @file{basic-arithmetics.fs}
@item @file{basic-stack.fs}
@item @file{conditionals.fs}
@item @file{fetch.fs}
@item @file{insight.fs}
@item @file{nuc-parameters.fs}
@item @file{off.fs}
@item @file{organs.fs}
@item @file{qualities.fs}
@item @file{spot-properties.fs}
@item @file{global-integers.fs}
@item @file{global-dfloats.fs}
@item @file{store-normalised.fs}
@item @file{store.fs}
@item @file{float-basic-arithmetics.fs}
@item @file{float-more-arithmetics.fs}
@item @file{float-exp.fs}
@item @file{float-trigonometry.fs}
@item @file{mixed-maths.fs}
@item @file{transform.fs}
@item @file{dfloat-fetch.fs}
@item @file{dfloat-store.fs}
@item @file{float-stack.fs}
@item @file{float-organs.fs}
@item @file{float-parameters.fs}
@item @file{spot-df-qualities.fs}
@item @file{spot-df-properties.fs}
@item @file{float-comparison.fs}
@end itemize

@xref{Gene primitives}, for more informations.


@node Configuration files, Output files, Genes files, Files
@comment  node-name,  next,  previous,  up
@subsection Initialisation and configuration

Technically there is a big difference between compile time configuration
and run time configuration. 

@itemize @bullet
@item 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.

@item Run time options 
just give defaults to the program at startup that can be changed at any time.
@end itemize

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:

@itemize @bullet
@item @file{compile-options.fs}
      Brew default compile time options as delivered with this brew version.

@item @file{my-compile-options.fs}
      Configuration file to put personal compile time options overriding
      defaults.


@item @file{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.

@item @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.

@item @file{brew-options.fs}
      Configuration file to change some initialisations done by 
      @file{brew-defaults.fs} or @file{brew-init.fs}.

@item @file{my-brew-options.fs}
      Configuration file to put personal adaptions and preferences.
@end itemize


@node Output files, Temporary files, Configuration files, Files
@comment  node-name,  next,  previous,  up
@subsection Brews output in @file{brew/OUTPUT/}

@itemize @bullet
@item @file{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.

@item @file{brew/OUTPUT/log/brew.log}
      Default name for brews log file.

@item @file{brew/OUTPUT/rec-play/brew-recorded.fs}
      Default name for recorded sessions as Forth text file.
      Including this file replays the session.
@end itemize


@node Temporary files, Informative files, Output files, Files
@comment  node-name,  next,  previous,  up
@subsection Brews temporary files in @file{brew/OUTPUT/tmp/}.

Brew creates some temporary files in its @file{tmp/} directory
which defaults to @file{brew/OUTPUT/tmp/}.

If you leave brew like intended (@pxref{Getting started}) it will
remove most of them, but there are some exceptions:

@itemize @bullet
@item @file{brew-identity}.
      On startup brew will create a file @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.

@item @file{created-files_nnn} (where @samp{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.

@item @samp{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 @file{created-files_nnn} for later reference.

@item @file{tmp-files_nnn} (where @samp{nnn} is the identity number)
      contains a list of temporary files that will be removed on exit,
      as the file itself will be.
@end itemize


@node Informative files, Programming tool files, Temporary files, Files
@comment  node-name,  next,  previous,  up
@subsection Documentation, versions, development, conventions@enddots{}

@itemize @bullet
@item @file{texi/}
      Main documentation directory.

@itemize @bullet
@item @file{texi/brew.texi}
      Source of this documentation in texinfo format.

@item @file{texi/brew.info}
      This documentation in info format.

@item @file{texi/brew.html}
      This documentation in HTML.
      Produce this file by saying @code{makeinfo --html brew.texi}.

@item @file{texi/brew.dvi}
      File to print this manual.
      Produce this file by saying @code{texi2dvi brew.texi}.

@item @file{texi/HOWTO}
      Just some personal notes for the texinfo development cycle.

@item @file{brew/texi/TODO}
      Separate documentation TODO list.
@end itemize


@item @file{DEVELOPMENT}
      This file describes the development process.
      You get a better overview from this file than from @file{ChangeLog}.

@item @file{ChangeLog}
      Very detailed ChangeLog file.

@item @file{cvs-tags}
      Overview over CVS snapshots.

@item @file{VERSION-README}
      Some information about the current version and series.  Obsolete.

@item @file{README}
      Old README. Mostly replaced by this manual.

@item @file{README-SECURITY}
      Security aspects.  Please *do* read that.

@item @file{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.


@item @file{code-chapters.txt}
      Overview over organisation of @file{brew.fs}.

@item @file{brew/OUTPUT/FORTH/README-forth-directory}
      Directory information.

@item @file{brew/OUTPUT/log/README-log}
      Directory information.

@item @file{brew/OUTPUT/rec-play/README-rec-play}
      Directory information.

@item @file{brew/OUTPUT/tmp/README-tmp}
      Directory information.

@item @file{NAMING}
      Some conventions for naming Forth words in brew.

@item @file{TODO}
      Some TODO items.

@item @file{benchmark-results.txt}
      Some benchmark results.
@end itemize


@node Programming tool files, Benchmark files, Informative files, Files
@comment  node-name,  next,  previous,  up
@subsection Files with tools for profiling, testing and system adaptions

@itemize @bullet
@item @file{TAGS}
      Emacs TAGS file.

@item @file{make-ekey-map.fs}
      Help to make ekey mapping on a new system.

@item @file{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.

@item @file{tests/}
      Directory for some tests.

@item @file{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.
@end itemize


@node Benchmark files, Console and key setup, Programming tool files, Files
@comment  node-name,  next,  previous,  up
@subsection Benchmarks and Benchmark results

@itemize @bullet
@item @file{maybe-run-benchmark.fs}
      Fork to run benchmarks if a benchmark name is defined from command line.

@item @file{benchmark-results.txt}
      Some benchmark results.

@item @file{benchmarks/}
      Directory for benchmarks.

@item @file{bcompat-11-12.fs}
      Downwards compatibility to run @samp{transit-11-bench-A} and
      @samp{transit-12-bench}.
@end itemize


@node Console and key setup, Bugs and Debugging, Benchmark files, Files
@comment  node-name,  next,  previous,  up
@subsection Configuration of console size and special keys.

@itemize @bullet
@item @file{configure-console.fs}
      Console size configurator. Try it if you have screen size problems.

@item @file{make-ekey-map.fs}
      Key mapping for keys like @kbd{@key{<RETURN>}}
      @kbd{@key{<CURSOR-ARROWS>}} @kbd{@key{<FUNCTION-KEYS>}}
      @kbd{@key{<PageUp>}} @kbd{@key{<Home>}}.
      Try it if brew reacts strange on some keys.
@end itemize


@node Bugs and Debugging,  , Console and key setup, Files
@comment  node-name,  next,  previous,  up
@subsection Bugs and Debugging

@itemize @bullet
@item @file{BUGS}
      Known bugs. Please consult before reporting a bug.

@item @file{environmental.test.fs}
      Tests some known environmental dependencies early in the load sequence.
      @samp{Brew} depends on allocated memory to be dfaligned and on a
      separate floating point stack.

@item @file{debuging.fs}
      Words to help debugging.

@item @file{faked-genes.fs}
      Faking some genes for interactive debugging.

@item @file{INPUTS/extensions/debugging/}
      This directory has files to help debugging of certain brew/Forth
      combinations.
@end itemize

@bye

Tag table:

End tag table
