Next: , Previous: (dir), Up: (dir)

Brew ‘The Evolutionary Programmers Playground’ Version 0.2.1

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

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

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.

--- The Detailed Node Listing ---


What do I mean by 'evolutionary programming'?

Changing code

Biological analogy.

Getting started


Brew user manual

Brews main display:

Individuals, nuclei and spots:

Controlling population:

Diversification and mutation:

Displaying statistics about cells and spots:

Advanced operation:

World wide settings and creation of new worlds:

Logging and writing the generated program code to files:

Recording evolutionary sessions:

Compile time configuration:


Some brew basics

Classes of variables

Display modes

Using menus

Menu example

Brew main screen

Display menu

Configuring spot display

Step display menu

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

Color menu

Population control

Diversification menu

Mutation menu

Gene primitives

Floating point primitives:

Conditional structures:

Whole tested genomes can be used like new primitives:

Do something on nuc or spot subsets.

Extended conditions requiring parameters and a comparison:

Actions to be done on the defined subset:

Generic interface to act on a nuc subset:

Menu current genomes

Big Bang menu

Brews record and playback feature.

Programmers manual

Brews files overview

Next: , Previous: Top, Up: Top


                         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.


   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

   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.


  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

       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



                      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

   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.

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

   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

   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.

Next: , Previous: License, Up: Top

2 What it's all about

'brew' is an interactive environment for experiments with an ‘artificial code evolution’ using the Forth language.
See 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 its 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.

Next: , Previous: Goals, Up: Top

3 Introduction

Next: , Previous: Introduction, Up: Introduction

3.1 What do I mean by 'evolutionary programming'?

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

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

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

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

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

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

I prefer the term ‘evolutionary programming’ and call the process a ‘artificial code evolution’.

Next: , Previous: Evolutionary programming, Up: Evolutionary programming

3.1.1 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 its 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.

Previous: Simple hypothetical example, Up: Evolutionary programming

3.1.2 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:


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

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

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

Brew takes two different approaches to optimise the result:

Next: , Previous: Changing code, Up: Changing code Variable diversification

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

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

Previous: Variable diversification, Up: Changing code Code mutation

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

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

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

Brew does generate gene sequences of real Forth code.

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

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

Next: , Previous: Evolutionary programming, Up: Introduction

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

Next: , Previous: Biological analogy, Up: Biological analogy

3.2.1 Artificial life

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

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

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

Previous: Artificial life, Up: Biological analogy

3.2.2 Biological terms

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

Next: , Previous: Biological analogy, Up: Introduction

3.3 Brew feature overview

Brew is a highly customisable and very interactive program to try out ‘evolutionary programming’.

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

Next: , Previous: Feature overview, Up: Introduction

3.4 Getting started

Download brew:

Get a current brew version from


To install brew just unpack the files, say:

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

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

then: cd brew

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


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

cd brew
FORTH brew.fs where‘FORTH’ is the name of your Forth.

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

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

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

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

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

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

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

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

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

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

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

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

Next: , Previous: Getting started, Up: Getting started

3.4.1 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:

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

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

Next: , Previous: Gforth, Up: Getting started

3.4.2 Portable Forth Environment

pfe’ the ‘Portable Forth Environment’ is a very nice Forth implementation in C. You can download it from:

start brew with:
cd brew/ pfe brew.fs

Next: , Previous: pfe, Up: Getting started

3.4.3 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
There is a mailing list too.

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

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

Previous: bigForth, Up: Getting started

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

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.

Next: , Previous: Getting started, Up: Introduction

3.5 Let it brew.

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

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

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

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

Previous: Run evolution, Up: Introduction

3.6 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:

Previous: Why Forth?, Up: Why Forth?

3.6.1 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:

Next: , Previous: Introduction, Up: Top

4 Brew user manual

Brews main display:

Individuals, nuclei and spots:

Controlling population:

Diversification and mutation:

Displaying statistics about cells and spots:

Advanced operation:

World wide settings and creation of new worlds:

Logging and writing the generated program code to files:

Recording evolutionary sessions:

Compile time configuration:


Next: , Previous: Users manual, Up: Users manual

4.1 Some brew basics

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

Next: , Previous: Some brew basics, Up: Some brew basics

4.1.1 Genes

In analogy to biology the Forth words executed by a cell are called ‘genes’.

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

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

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

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

Next: , Previous: Genes, Up: Some brew basics

4.1.2 Diversification/Mutation

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

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

Variable Diversification:
Diversification does not change genes but changes variable values only. Small changes appear more often than big ones. The process of selection will hopefully optimise the variables value.
Code Mutation:
Proper mutation does change the genes, that is the code executed by the cells. There are several types of mutation, some insert new gene sequences (built out of the available primitives or from genes that have been built earlier in the evolution), some replace a single gene by another one fitting in the given sequence, some cut pieces out of the gene sequence, some restart to build a completely new sequence from scratch. The probability of each mutation type can be configured like usual.

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

Next: , Previous: Diversification/Mutation, Up: Some brew basics

4.1.3 Trial phase

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

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

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

See Why Forth?, for some technical details.

Next: , Previous: Trial phase, Up: Some brew basics

4.1.4 Classes of variables

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

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

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

Inner variables of the nucleus (nuc variables):
Each cell has a set of inner variables in the nucleus.

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

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

Variables of the virtual environment (world variables):
The other class of variables does not belong to the cell but to its 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 its children. Of course this is only the case if the scoring function depends on the variable in question, or if the cell passes useful information (like intermediate computed results) through these variables to itself or to the cells that will life later on the same spot. (These will very often be children of the present cell).

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

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

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

Previous: Classes of variables, Up: Classes of variables Variable names

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

Name: class: access: diversified? compile option

integer-A global read/only maybe global-integer-variables#
dfloat-A global read/only maybe global-dfloat-variables#

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

A-quality world read/write maybe spot-qualities#
A-property world read/only maybe spot-properties#
A-secret world hidden maybe spot-secrets#

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

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

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

Next: , Previous: Classes of variables, Up: Some brew basics

4.1.5 Run modes

Brew can run in a number of different modes.

You must understand at least the first two:

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

Previous: Run modes, Up: Some brew basics

4.1.6 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:

Next: , Previous: Display modes, Up: Display modes Example world mode display
...................       ******** ........  .**     ...      *********  . ....
....................       *******. ...... ..****    .......*********   .......
...................        ******    ........****     .......********  ........
.................... .  .   ******   ......*****      .......*******...........
.........................  ******** .... ..**** *    .........  *** ...........
.........................  *******.  . . ********    ..........****............
 .. ..   ......... ....... ******** .  ..********     ......... .* ............
  .    . .  .... . ......   *******   ..*********       .........  ...... ...
        .  ... ...*.....   ********....  ******* *      ..........*.......
 *********       **.....  ********..... ********* *    ....   ..    ... .   **
***********     ***************** .....*********       ..... ....   .   *. ****
************** *****************  .....********* *   ....... .  ..    *********
******************************** ....  ********     .........  .       ********
****************************** * ...   ********     ........          *********
**************************** *     . ..********     .......         ***********
****************************      . ....*****  *   ....... .       ************
****************************    .......*******     ........      **************
************** **************    .....* ****** *    .......     ***************
  **  * ** ** *  ************   ..  ...****** *     ......      ************ **
  *       *      **************    ...  ******     . ....       *********** *
*               *  ************     .. ******      ..... .      **********
         ....         * *******     . ...****      .....        ********  *
step: 636           cells: 42680         burden: 442        living: 1232

Each character symbolises a ‘cell’. You can select and edit them.
See 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.
See Display menu.

Previous: Example world mode display, Up: Display modes Example step display

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

  e  xx                     AAAAAAAAA     A A AAAAAAAAAAA       AAA     A
   x  eexxxxeeeeeeexxxeeeeexxxxeeeeeexxxxeeeeexxxxeeeeeexxxxeeeeexxxxeeee
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

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

Next: , Previous: Some brew basics, Up: Users manual

4.2 Using menus

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

These text menus give you informations about current settings and at the same time they do let you change them. Furthermore it's also the interface to the built in online help system (see Online help).

You SELECT things on the screen by moving the cursor to it and press <RET>. This will SWITCH options, lets you CHANGE VALUES or takes you to SUB-MENUS. If the cursor is on a menu item that expects a numeric or a string value, you can just enter a new value without the need to press RET first.

If you select the menu title or press ? you can read the documentation about the menu.

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

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

? gives context sensitive documentation.

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

BTW: As I use the same menu system for some music applications the menu system can also take input from MIDI. This is not active in brew though.

Next: , Previous: Using menus, Up: Using menus

4.2.1 Menu example

Select actions of the function keys:

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

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

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

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

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

You can select items (including title and bottom lines) either by moving cursor and pressing <<RET>>, or by using key bindings (see 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.

Next: , Previous: Menu example, Up: Menu example Example key bindings
Active keybindings:             default: noop   EXIT MENU

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

Brew tries to figure out what pressing a key would do in the current menu and to tell you in a somehow understandable language. Hope you can understand from the above that pressing 5 will let you configure function key <<F5>>, by letting you choose from a list of possible actions. The default entry shows what all the other keys would do (nothing but leave the menu, in this case). You can see common key bindings too (see Key bindings).

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

Previous: Example key bindings, Up: Menu example Configuring F5
Select action for this function key


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

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

Next: , Previous: Menu example, Up: Using menus

4.2.2 Moving and selecting in menus

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

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

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

Next: , Previous: Moving and selecting, Up: Using menus

4.2.3 Key bindings in menus

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

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

There are a few common keybindings active in most menus:

Other frequently used key bindings:

Next: , Previous: Key bindings, Up: Using menus

4.2.4 The online help system.

The menu system has built in online help capabilities.

Not only that the menu text may give you informations on the meaning of the displayed settings, suggest things to do next or warn you from possible problems with the settings you required or display menu items to explicitly select help, but there is more under the hoods:

Next: , Previous: Online help, Up: Using menus

4.2.5 The meaning of colours in menus.

Some menus use colours to attract your attention.

These colours are configurable, of course.

Next: , Previous: Colours in menus, Up: Using menus

4.2.6 Numeric input in menus

You selected some value and are given the possibility to give a new one. In the current menu version you don't even have to press <<RET>>, just move the cursor on the menu item and enter the new value.

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

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

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

Next: , Previous: Numeric input, Up: Using menus

4.2.7 Everydays syntax for float input.

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

Please note that this has its limitations:

As on integer input you can use the whole power of the Forth text interpreter on numeric float input (see Numeric input), and you don't have to press <<RET>> before entering numeric values any more.

Next: , Previous: Float input, Up: Using menus

4.2.8 Scale input, numeric fraction input in menus.

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

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

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

Some examples:

Fraction before: Input: Result: Comment:

1/2 0 0/1 setting to zero

1/2 2* 2/2 multiply
1/2 2 * 2/2 multiply
1/2 2/ 1/4 divide
1/2 2 / 1/4 divide

1/2 2 7 2/7 numeric normal
1/2 3/7 3/7 numeric
1/2 4 / 7 4/7 numeric

1/2 % 2* 1/4 escaping

Next: , Previous: Scale input, Up: Using menus

4.2.9 Selecting functions from a list

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

The menu entry might look similar to the following line:

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

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

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

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

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

There's an advanced feature on key ':

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

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

Next: , Previous: Selecting functions, Up: Using menus

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

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

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

This menu is a scrolling one.  <PageUp>  <PageDown>  <home>  <end>  <arrows>

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

Previous: Scrolling menus, Up: Using menus

4.2.11 Using Forth in menus

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

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

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

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

Next: , Previous: Using menus, Up: Users manual

4.3 Reading context documentation from within brew

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

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

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

See System menu, to switch between these documentation types, or to see the strings passed to the OS in case of problems. You will find hints how to change the default by selecting ‘reader’.

Next: , Previous: Context documentation, Up: Users manual

4.4 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. See Display menu, for configuring what to display.

Press <<SPACE>> and brew will start brewing and continue until you press i.e. <<SPACE>> again.
Pressing s is similar, but will just make one step and stop then.
Toggle between world display and step (statistics) display.
See all the other key bindings. (see Key bindings).
See and edit function key bindings. (see Menu function keys).

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

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

See Example world mode display, petri shell look world map.
See Example step display, real time statistics display.

See Display menu, choose what you want to see while brewing.
Pressing D or selecting the info line (last line of the screen) ports you to ‘Display menu’ where you can configure display including info line.

Depending on the display mode you have additional menu interfaces:

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

Brews menu list is on keys B and m.
See Menus menu.

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

Next: , Previous: Brew main screen, Up: Brew main screen

4.4.1 Menu interactions in world maps.

Brew displays world maps when its 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.

See 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:

See Nuc menu, if you press <<RETURN>> on a cell.
See Edit spot menu, if you select an empty spot.

Special key bindings:

Pressed when cursor is on a cell shows its genome as Forth source. On a empty space it gives ‘Edit spot menu’.
Press this key if you want brew to continue to use the current colour coding while brewing. See Conditional colouring, to learn more about.
You can select a rectangle region in brews main screen world map. Define the region by pressing * on desired corners then press <<RETURN>> to go to a subset menu over the selected rectangle. There you can do whatever you want with the cells living inside the selected rectangle (see Configurable actions).

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

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

Next: , Previous: World map interaction, Up: Brew main screen

4.4.2 Setting nucs to spots

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

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

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

Previous: Cloning nucs to a spot, Up: Brew main screen

4.4.3 Brews main screen in statistical (step) mode.

See 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 (see ASCII bar graphics).

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

Press D to do other configurations or select the ‘info line’. See Display menu.

Next: , Previous: Brew main screen, Up: Users manual

4.5 Display menu

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

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

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

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

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

Next: , Previous: Display menu, Up: Display menu

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

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

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

Next: , Previous: Time, Up: Display menu

4.5.2 Configuring spot display

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

Previous: Configuring spot display, Up: Configuring spot display How cells show up in spot display

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

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

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

(BTW: If you select the function from spot display you get the possibility to have a look at its definition. (see Selecting functions).)

You can choose among the following functions:

Next: , Previous: Configuring spot display, Up: Display menu

4.5.3 Step display menu

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

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

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

Next: , Previous: Step display menu, Up: Step display menu ASCII graphs
     x x       x       xx        xx        x
             xx x        x      x  x      x x       xx       xxx      xx
    x            x    x   x    x         x   x     x  x     x   x    x
        x   x     xxxx     xxxx     xxxxx     xxxxx    xx  x     x
   x     x x                                             xx       xxx
          x                                           $$$$$$$$$$$$$$$$$$
  x                                 $$$$$$$$$$$$$$$$$$
 x                 $$$$$$$$$$$$$$$$$
x    $$$$$$$$$$$$$$
$ var nuc-do-cost  x var living

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

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

You can see population control at work in this example:

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

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

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

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

Next: , Previous: ASCII graphs, Up: Step display menu ASCII bar graphics

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

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

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

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

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

The menu interaction is very similar in both cases:

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

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

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

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

Next: , Previous: ASCII bar graphics, Up: Step display menu Text display

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

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

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

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

Next: , Previous: Text display, Up: Step display menu Menu step display

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

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

Continuous display configuration is more complex and has its own sub menu see Menu continuous display.

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

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

An entry for a displayed item might look like this:

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

• The first item indicates the type of statistical display:

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

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

• ‘lines’ configures how many screen lines this display item will take up.

• ‘v-range’ is the vertical range. No need to initialise it normally. Brew will take care about.

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

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

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

Statistical bar graph display does automatic zooming:
If values fall outside displayed range horizontal or vertical scale will be adapted to let all values fall inside. If too little of a range is occupied brew will zoom up. The horizontal and vertical zoom start values indicate how much of a range must be used (see Scale input). So if you set horizontal zoom start value to 1/6 and the values would use less than that amount of screen width brew zooms up to fill the screen. Zooming is indicated in the bottom line like this:

500        scanning: energy       -<zooming>|      vertical range: 52      1366

The '-' and '|' left and right the word '<zooming>' indicate horizontal and vertical zooming. So in this example both took place.

• The third line defines background and foreground colors.

Configuring text display items is trivial, so its not covered here.

Configuring continuous display is done in its own sub menu.
See Menu continuous display.

If you see a green text similar to this one:

fill the screen (7 lines unused).

you can select it (or press f) to adapt item sizes to use the whole screen, or set the individual step display item sizes manually.

presets’ See Step display presets, for often used templates.

Next: , Previous: Menu step display, Up: Step display menu Menu continuous display

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

The menu might look similar to this:

Setup continuous display:

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

add new entry

Zoom up scale: 2/1

Probably you can guess what this would do:

You can select the type of the displayed value from the following list:

name: kind: value:
(none) no selection
get-variable various variable value (see below)
nuc-min nuc minimum
nuc-max nuc maximum
nuc-range nuc range
nuc-average nuc average
spot-min spot minimum
spot-max spot maximum
spot-range spot range
spot-average spot average

Type ‘get-variable’ displays the value of a single global variable, while the others display functions like average or range of groups of variables of all living cells (nucs) or of all spots.
The single variables that ‘get-variable’ can treat are:

living       how many cells currently alive
newborn      how many cells created in this step
cloned       cloned cells since start of evolution
died         how many cells died this step
nuc-do-cost  energy cost of one life step
code-price   energy cost of one code length unit
selected     number of selected cells

Defining char and color is trivial.

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

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

Use ‘add new entry’ to add a new entry.

Previous: Menu continuous display, Up: Step display menu Step display presets

Planed to give some often used display configurations.

Previous: Step display menu, Up: Display menu

4.5.4 Info line

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

Configurating info line is trivial:

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

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

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

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.

Next: , Previous: Display menu, Up: Users manual

4.6 Color menu

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

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

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

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

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

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

Foreground colors can be set by the following nuc dependent functions:

black                       you won't see black on black ;-)
red                         just fixed colors
default-color               white as foreground, black as background
condition>fg-colour         conditional colouring
                            (see 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
                            (see Trial phase).
nuc-all-real>color          color nucs with real floating point values only
nuc-has-unreal>color        color nucs with unreal floats (infinities, nan's)
nuc-inf?>color              color nucs with infinities of both signs
nuc-neg-inf?>color          color nucs with negative infinities
nuc+inf?>color              color nucs with positive infinities
nuc-nan?>color              color nucs with nan's

Background colors can be set by the following spot dependent functions:

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

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

Some useful key bindings in color menu:

See Scrolling menus.

Previous: Color menu, Up: Color menu

4.6.1 Conditional colouring

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

See Extended conditions, to learn how to set up colour conditions.

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

Next: , Previous: Color menu, Up: Users manual

4.7 Brews super menu.

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

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

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

Next: , Previous: Menus menu, Up: Users manual

4.8 Individuals menu

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

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

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

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

If you want to randomly sow a number of clones use the function presented in the menu (c). There is a variant which diversifies diversificable nuc variables of each sown clone (d), making them a bit different, which is usually a good idea to start an evolution. See 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.

Next: , Previous: Individuals menu, Up: Users manual

4.9 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:

Next: , Previous: Nuc menu, Up: Users manual

4.10 Edit a single spot

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

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

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

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

Next: , Previous: Edit spot menu, Up: Users manual

4.11 Global variables

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

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

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

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

To configure diversification of global variables use the link to
See Diversification menu.

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

Next: , Previous: Menu global variables, Up: Users manual

4.12 Food menu

The cells need ‘energy’ to survive and to reproduce.
They get energy by ‘eating’ ‘food’.

Population get's controlled by two means:

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

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

Next: , Previous: Food menu, Up: Users manual

4.13 Population control

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

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

This brew version has two different ways of doing it:

Next: , Previous: Population control, Up: Population control

4.13.1 Brews pseudo biological mode

Brew stresses its little 'beings' by two means:

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:

Configurating possibilities:

Next: , Previous: Eat and consume, Up: Population control

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

Previous: Elitism, Up: Population control

4.13.3 Score list of individuals

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

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

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

Next: , Previous: Population control, Up: Users manual

4.14 Diversification menu

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

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

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

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

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

The mechanism work similar, but not equal:

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

See Scrolling menus.

Next: , Previous: Diversification menu, Up: Diversification menu

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

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

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

Next: , Previous: NUC diversification, Up: Diversification menu

4.14.2 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 See 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.

Previous: SPOT diversification, Up: Diversification menu

4.14.3 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 See NUC diversification, for more infos.

Next: , Previous: Diversification menu, Up: Users manual

4.15 Mutation menu

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

Next: , Previous: Mutation menu, Up: Mutation menu

4.15.1 Probability lists

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

Example (mutation types):

mutation-types  items: 6    Edit relative probabilities.

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

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

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

You change relative probabilities by selecting the entry.

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

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

Selecting the name of an item shows you its definition.

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

Previous: Probability lists, Up: Mutation menu

4.15.2 Mutation types menu

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

Next: , Previous: Mutation menu, Up: Users manual

4.16 Gene pools menu

This menu let's you choose the gene pool to be used for mutation.
You get here from brews main screen by pressing G.

Currently only ‘gene-primitives’ is selectable.

Next: , Previous: Gene pools menu, Up: Users manual

4.17 Actual pool menu

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

Currently this is always ‘gene-primitives’.

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

See Probability lists.
See Scrolling menus.

Next: , Previous: Actual pool menu, Up: Users manual

4.18 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:

Correct use of the Forth data stack plays an important part in fulfilling these requirements. I'd consider it a possible security risk if the cells could read and write to arbitrary addresses and it would be disastrous regarding stability. So the mutation process *must* know about the type of stack data, at least about addresses. The usual Forth compiler does not do any type checking, assuming that the programmer is clever enough to do it right. Brews mutation process only does some very rudimentary type checking, just enough to assure stable and secure code and leaves the decision if the result does something useful to the evolutionary selection process. Brew knows about very few different types and uses one byte char symbols called ‘stack symbols’ to indicate them:

Brew uses a notation for stack types that looks similar to the usual stack effect comments in Forth source code. Please note that there are subtle differences not only in the look (intentionally) but also in the meaning: While Forth stack comments try to convey some type information *and* individuality of the values, brews stack symbols only talk about (very few) basic types.

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

Note that the last example would execute and compile the *same* code, just a normal swap. Only mutation would name it differently for its purposes. This allows you to give other probabilities to the different variations (or forbid some completely, if you want to), which has proven to be a very valuable feature.

Note that brews stack symbols are always single letters without spaces in between, and there is one single - char to separate symbols before and after gene execution. This has technical reasons but is convenient, as the slightly different look should remind you of the slightly different meaning.

Next: , Previous: Stack type symbols, Up: Users manual

4.19 Gene primitives

Mutation can only build genomes based on the so called ‘gene primitives’.
The gene primitives are given together with their stack type symbols here.
See Stack type symbols, for an explanation.

Floating point primitives:

Conditional structures:

Whole tested genomes can be used like new primitives:

Next: , Previous: Gene primitives, Up: Gene primitives

4.19.1 Integer arithmetics gene primitives

Next: , Previous: Integer arithmetics genes, Up: Gene primitives

4.19.2 Gene primitives to arrange items on the Forth stack

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

Forth makes heavy use of the so called ‘data stack’.
Brew uses some (but not all) of the possibilities Forth gives the programmer to rearrange items on the stack.

There is a conceptional difference of how brew sees stack juggling and how Forth programmer usually do. Let's take a simple example:

Brews mutation has to know about stack effects of its genes to generate something stable, secure and sometimes maybe even useful. Mutation does not care about the actual stack values (the '1' '2' above) though, but only about the *type* of them. So if you have two integers as x1 and x2 like in the example above brews mutation sees swap ( n1 n2 -- n2 n1) as a noop regarding stack effect. If one of them is a address instead, brews mutation mechanism sees that swap as a completely different word, even if it will compile the normal Forth word swap in both cases.
See Stack type symbols.

To get somehow readable gene code I don't like addresses lying around too long on the stack, but want them resolved as soon as possible. That's the main reason why I keep many type variants of the above primitives deactivated by commenting them out in the source. You can always activate them (but you might run into troubles with it...). You don't loose much by leaving them switched off, as there is no address arithmetic mutation can always get a copy of an address (variable) by choosing its gene a second time.

Next: , Previous: Stack juggling genes, Up: Gene primitives

4.19.3 Genes reading a value from a memory address.

As explained elsewhere genes cannot access arbitrary addresses for security and stability reasons.
See Stack type symbols.
See Genes.

If there *is* an address on the stack you can be sure it is legitimate for the genome to read (and even write) its contents.

Next: , Previous: Genes reading from memory, Up: Gene primitives

4.19.4 Genes writing a value to a memory address

As explained elsewhere genes cannot access arbitrary addresses for security and stability reasons.
See Stack type symbols.
See 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.

Next: , Previous: Genes writing to memory, Up: Gene primitives

4.19.5 Genes limiting values to avoid overflow problems

Gene sequences doing things like adding the contents of an address to the same address will provoke integer overflow very quickly. The cells do not have any problems with overflow, they even seem to like it specially... Genomes find out all sort of tricks they can play with overfloating variables. But probably this is not what you want, and it is usually quite difficult to understand what's happening. So you might want to avoid overflow. I don't think there is a simple and clean possibility to do this. The trick used here is more like a quick dirty hack that does some good and does some harm. Just use or leave it as you want ;-)

The trick is to have some words equivalent to ! or +! that refuse to write too big values. There is a maximal value, that will not be exceeded. Up to half that value you get as much as you want, then the curve increases half as steep (so you still get some more if you ask for more) until it reaches the maximum, where it stays. This is done by the word some.

Next: , Previous: Dealing with overflow, Up: Gene primitives

4.19.6 Read/write and read/only nuc and spot variables.

These genes access different classes of variables.
See 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 its address on the stack, as usual in Forth, while the read/only variant gives its 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 its current *value* can be known to the cell. There are other classes of variables (like secrets) that have no genes to access them. So the genes have per se no possibility to access them in any way.

The number of variables of the different classes is configured by compile time options.

Next: , Previous: Nuc and spot variables, Up: Gene primitives

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

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

Next: , Previous: Global variables, Up: Gene primitives

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

Next: , Previous: Insight genes, Up: Gene primitives

4.19.9 Basic floating point maths

Next: , Previous: Float arithmetic genes, Up: Gene primitives

4.19.10 More floating point operator primitives

Next: , Previous: More float arithmetics, Up: Gene primitives

4.19.11 Logarithms, exponentials, roots

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

Next: , Previous: Logarithms and exponentials, Up: Gene primitives

4.19.12 Trigonometric functions gene primitives

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

Next: , Previous: Trigonometry, Up: Gene primitives

4.19.13 Mixed integer/float operators

Next: , Previous: Mixed maths, Up: Gene primitives

4.19.14 Casts between integer and floating point

Next: , Previous: Type casts, Up: Gene primitives

4.19.15 Fetching floats from memory

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

Next: , Previous: Read float values, Up: Gene primitives

4.19.16 Fetching floats from memory

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

Next: , Previous: Store float values, Up: Gene primitives

4.19.17 Arranging items on the float stack

Next: , Previous: Float stack manipulation, Up: Gene primitives

4.19.18 Float variables local to a nuc or spot

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

Next: , Previous: Nuc and spot floats, Up: Gene primitives

4.19.19 Conditionally executing gene sequences

Gene sequences can contain IF ELSE THEN structures like other Forth code conditionally executing alternatives depending on numerical comparisons and such. Please note that these structures take the form of [IF] [ELSE] [THEN] during trial phase, as code is interpreted (not yet compiled) then. Of course brew takes care about that.

Next: , Previous: Gene conditionals, Up: Gene primitives

4.19.20 Conditions based on floating point values

Previous: Floating point comparison, Up: Gene primitives

4.19.21 Genome pools

Brew can put successfully tested genes into a genome pool.
Switch that on or off in ‘Mutation menu’.
See Mutation menu.

Genome pools serve two distinct purposes:

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.
See Probability lists.

Next: , Previous: Gene primitives, Up: Users manual

4.20 Examining and editing genes and whole genomes.

You are presented a somehow formatted output of the genomes Forth code. If you select a sub-gene, you will be put (recursively) in the menu regarding the sub-gene, or presented gene information, if it is a gene primitive.

Selecting the genomes name, or pressing e will write the genome to a file and call and external editor (defined in compile-options.fs) on it. You can change this Forth file as you want to, save it and leave the editor. Brew will check your input and inform you if it finds a problem. Otherwise it will replace the nucs genome with your input and set the nuc on trial. (see 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 See Genes files, if you want to define new gene primitives. (You could define genes from the Forth input line, if you want to. see Using Forth in menus).

Next: , Previous: Gene edit menu, Up: Users manual

4.21 Scanning nucs

If you press n in brews main screen you get to a menu displaying information about (all living) nucs. For each nuc variable you will see a line displaying minimal, maximal and average value. (see Scrolling menus). At one given time either integer or floating point variables are displayed. Toggle between them with o as usual, or by selecting the entry in the title line. (BTW: If you select one kind of variables brew will assume that you are interested in this type. So the display of i.e. ‘Nuc menu’ will also switch to the same kind. see Nuc menu).

The same menu get's used to display statistical informations about nuc subsets. The title line indicates what variable type gets displayed and if all nucs or only a subset where scanned.

You see a bunch of lines similar to the following:

generation              min: 1417         max: 1483         average: 1455
genome-generation       min: 0            max: 1098         average: 347
code-cost               min: 100          max: 1699         average: 435
energy                  min: 403          max: 1105         average: 727

Selecting a ‘min’ ‘max’ or ‘average’ value will port you to a nuc subset screen of the nucs having the value in question.
See Menu nuc subsets.

Selecting a variable name shows you a more detailed view of the distribution of values of the variable as a simple ASCII bar graph:

                ***       *
                ***       *
                ****     **
                **** *   **
                ******* *****
                *************  *
       *      ***************  *   *
    ** **     ***************  **  *
   *******   ********************  *
 * ******* * ***********************  * ***
 ************************************ * ****        *
************************************* ************ **  *       *
*****************************************************.****.....*.. *...*.     .
-129        scanning: energy                       vertical range: 69      2260

Selecting a bar of this display type will port you to a ‘Menu nuc subsets’ with the value range in question, to do more analysis or so. See Menu nuc subsets.

See Menu step display, for a way to display this type of information in real time while brewing. You'll find some additional information there too.

If you display floating point variables you will see lines like:

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

There are four signs at the right border, either dots or ‘-r+?’, which represent negative infinity, real values, positive infinities and NANs. A dot means that no values of this type exist. The above line says, that f-organ-A of all scanned nucs did contain a real value, no infinities or NANs. Selecting the sign will display counts for each value type, a line for each scanned floating point variable:

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

f-organ-A           0              72             0              0

Selecting a title entry like ‘-infinity’ will port you to a nuc subset menu with nucs that have i.e. negative infinities in any one of their nuc float variables. As an exception ‘real’ chooses nucs that have *only* real float values.

Selecting a number, let's say the +infinity count for f-organ-C goes to the nuc subsets with f-organ-C being +infinity.
See Menu nuc subsets, See Menu spot subsets, for documentation.

Toggle back with o, or by selecting ‘Type counts’.

Next: , Previous: Scanning nucs, Up: Users manual

4.22 Scanning spots

If you press w from brews main screen you'll get to a menu displaying statistical data over all spots. The same menu get's used at different locations to display statistics about different spot subsets. (see Scrolling menus).

It works exactly as the corresponding menu for nuc statistics.
See Scanning nucs, for more information.

Next: , Previous: Scanning spots, Up: Users manual

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

Depending the situation you are prompted for nuc or spot related conditions and actions, or both:

Extended conditions requiring parameters and a comparison:

Actions to be done on the defined subset:

Generic interface to act on a nuc subset:

Please use these advanced functions with great care.

Brew assumes that you know what you are doing here and does not even try to prevent you from doing the most stupid possible things with this feature... So if you tell brew to multiply the action pointer (xt) of all nucs genome by say 7/9 it will do it obediently ;-)

Brew does its 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?

Next: , Previous: Configurable actions, Up: Configurable actions

4.23.1 Simple conditions defining a nuc subset.

These conditions do not require any parameters.

Next: , Previous: Simple nuc conditions, Up: Configurable actions

4.23.2 Simple conditions defining a spot subset.

These conditions do not require any parameters.

Next: , Previous: Simple spot conditions, Up: Configurable actions

4.23.3 Extended conditions comparing two values

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

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

Next: , Previous: Extended conditions, Up: Configurable actions

4.23.4 Generic nuc/spot actions

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

Next: , Previous: Generic nuc/spot actions, Up: Configurable actions

4.23.5 Nuc specific actions

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

Next: , Previous: Nuc specific actions, Up: Configurable actions

4.23.6 Defining maybe-do actions

I call this mechanism of conditionally executing user defined actions maybe-do. The menu interface to set it all up looks slightly different depending on the situation. In some cases half of the job is already invisibly done, like setting the condition or action part. A typical interface might look like this before you define anything:

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

Simple condition’ switches between simple and extended conditions.
The rest is trivial, you will find out how it works. After you have done your configuration it might look similar to this:

DO something on some spots: Please use carefully...
Extended condition:  2-variables  A-quality  B-quality  >
What to do:          scale-variable  food  with  3/2

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

Next: , Previous: Defining maybe-do actions, Up: Configurable actions

4.23.7 Menu interface to act on a nuc subset

This menu is the user interface to use the ‘maybe-do’ functions on nucs. See 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.

Previous: Menu nuc subsets, Up: Configurable actions

4.23.8 Menu interface to act on a spot subset

This menu is the user interface to use the ‘maybe-do’ functions on spots. See Configurable actions, for an explanation what it does and how to configure it.

It works on spots analogous to the ‘Menu nuc subsets’.

See Menu nuc subsets, for more information.

Next: , Previous: Configurable actions, Up: Users manual

4.24 Menu current genomes

Pressing U (or u as a shortcut) from brews main screen takes you to the ‘Menu current genomes’. This menu deals with the genomes of all currently living cells. (see Scrolling menus). The start of the menu screen might look similar to this:

Menu current genomes.                  Genomes of living cells: 79

genome-id:   genome:      count:       cost:        max generations:

0          * noop         948          100          36
2            g-2 t:61     158          287259       26
3            g-3          314          3199         34
4            g-4          10           500          18
7            g-7 t:2      13           500          18
14           g-14 t:3     11           400          15
16           g-16         13           5198         24
18           g-18 t:5     16           4397         17
19           g-19 t:1     9            1000         22
23           on trial     21           1400         16
[ ... ]

The title line tells you how many different genomes there are currently.

The column titles (with the exception of the one for the genome name) are selectable menu items. If you select them, the display order of the lines belonging to the single genomes is changed to be based on the quality in question. Selecting the item again will switch between ascending and descending sorting. You can also use the key bindings given below.

The column have the following meaning:

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

The ‘current’ line will be indicated by a ‘*’ before genome name, and go down one line after examining the genome.

Next: , Previous: Menu current genomes, Up: Menu current genomes

4.24.1 Colouring on equality

Brew uses this function to show you all cells which share one special quality. Brew displays a world map and colours the cells in question. Similar maps get used to display spot qualities.

If you don't like the colours change ‘color-selected-fg-xt’ and ‘color-miss-fg-xt’ for foreground colours (showing nucs), respectively ‘color-selected-bg-xt’ and ‘color-miss-bg-xt’ for background colours (showing spots) in my-brew-options.fs.

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

See World map interaction, to learn what else you can do here.

Next: , Previous: Colouring on equality, Up: Menu current genomes

4.24.2 Three coloured world maps

Sometimes brew shows you a three coloured world map to indicate which nucs or spots fall below, inside or above a certain range regarding some quality in question. Falling ‘inside’ a range can also mean equality with a single value. Foreground colours code nuc qualities, background shows the spot like always.

As an example the map could show you all nucs having code cost falling into a given range (which is about the same as having a certain code length) in one color, the shorter ones in another, and the longer ones in a third colour. I call this ‘Colouring on difference’.

The meanings of the (default) colours (on foreground) are:

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

See World map interaction, to learn what else you can do here.

Previous: Colouring on difference, Up: Menu current genomes

4.24.3 Menu this genome

You'll get here normally selecting a entry for a genome from menu ‘Menu current genomes’. (Which you reach by pressing U in brews main screen). You cannot come here from brews main screen or from the super menu, as brew can not know which genome you are interested in.

The menu title shows you the name of the compiled genome (if it is compiled already) and how many cells share this same genome.

Next: , Previous: Menu current genomes, Up: Users manual

4.25 Menu select nucs

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

Nucs can be ‘selected’, which just means that a special flag is set within them. As a part of the nuc this flag is hereditary and will not be reset by brew without that you ask for it. The flag has no meaning at all for brew, it is a tool for the user to use for whatever he likes.

The feature has similar uses as the ‘maybe-do’ functions (see Configurable actions), but there are some differences:

Menu features:

There are two interfaces to the ‘maybe-do’ feature, one for changing selections based on a condition, the other to do configurable actions on all selected nucs (see Configurable actions).

Next: , Previous: Menu select nucs, Up: Users manual

4.26 World menu

This menu gives informations and interfaces to some world wide settings of the current world. You come here from brew main screen by pressing W.

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

Following items are purely informative, you cannot change them:

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

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

Some interfaces to other world related functions:

The rest of the world menu let's you define a action to do on spots that meet a certain condition (‘maybe-do’ feature working on spots). You must configure the condition which spots will be treated and define the action to take. Then you can select ‘DO something on some spots’ to trigger the action. Like always in similar cases you can select amongst simple or more complex conditions and actions or define your own in Forth program source. On inhabited spots (only) you can access nuc variables too. (see Configurable actions).

Next: , Previous: World menu, Up: Users manual

4.27 List of worlds

You get to this menu by pressing O (like ‘Other worlds’) in brews main screen. It is a list of all existing brew worlds. Select a world from the list to enter it.

Brew let's you change world names, and shows you some geometry information for each world.

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.

Next: , Previous: World list menu, Up: Users manual

4.28 Big Bang menu

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

You get here by pressing B+B (capital ‘B’ twice) from brews main screen.

The upper half of the menu screen shows you the settings of the current world, the lower half let's you configure and create another one. After creating a new world the new one will be the current one.

The second half is the main part of the menu, here you define the geometrical structure of your new world and the visibility ranges of each dimension and finally create it. Select ‘Clone geometry’ for same geometric structure as the current world has.

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

Next: , Previous: Big Bang menu, Up: Big Bang menu

4.28.1 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 its dimension.

If you want to display a world of more than two dimensions you can choose to show only one layer or a range of layers one over the other. In the latter case it might be helpful to delay display of each individual layer to have a chance to understand the three dimensional structure while the display is building up. The layers can be transparent or opaque on spots where no cell lives, depending on the background being displayed or not on empty spots. Background will always have to be displayed on the first displayed plane, but can be switched off later. As this sounds all more complicated than it is, there are some examples further down.

For each dimension you have a line like this:

1 dimension  spots: 80  visible from: 0         to: 80

The entries have the following meaning:

If you have more than two dimensions you will see the following two entries:


Two dimensional world, screen sized on the Linux text console. Fast and everything is visible: (Might be too small for some types of experiments).

Current world           spots: 1920
1 dimension  spots: 80  visible from: 0         to: 80
2 dimension  spots: 24  visible from: 0         to: 24
Delay displaying layers:        0

Tree dimensional world, only middle layer visible:

Current world           spots: 19200
1 dimension  spots: 80  visible from: 0         to: 80
2 dimension  spots: 24  visible from: 0         to: 24
3 dimension  spots: 10  visible from: 4         to: 4 4
Delay displaying layers:        0

Tree dimensional world, all layers visible. Brew displays one layer after the other, all opaque, and pauses a bit after each layer:

Current world           spots: 19200
1 dimension  spots: 80  visible from: 0         to: 80
2 dimension  spots: 24  visible from: 0         to: 24
3 dimension  spots: 10  visible from: 0         to: 10 10
Delay displaying layers:        1000

Tree dimensional world, all layers visible. Brew displays one layer after the other, the first one opaque (to hide previous display), all the following transparent. Pauses a bit after each layer:

Current world           spots: 19200
1 dimension  spots: 80  visible from: 0         to: 80
2 dimension  spots: 24  visible from: 0         to: 24
3 dimension  spots: 10  visible from: 0         to: 10 0
Delay displaying layers:        2000

Previous: World size and visibility, Up: Big Bang menu

4.28.2 Make a Big Bang

Here you define the geometry of your new world.

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.

Next: , Previous: Big Bang menu, Up: Users manual

4.29 System menu

This is the menu for brews system wide settings.
You get there by pressing S in brews main screen.

The identity number displayed in the title line can be helpful to identify output files, as the number get's included in file names.

When brew is started with special options (i.e. ‘COUNTING-WORDS’ see Programming tool files) additional items might show up in system menu.

Next: , Previous: System menu, Up: Users manual

4.30 Log files menu

This menu allows you to switch very detailed what brew should write in its log files and what not. You come to this menu by pressing L in brews main screen.

Brew can write very detailed log files about what it does. Actually this elaborated logging facility is a by-product of my debugging activities ;-) Debugging evolutionary programming can be quite a task...

Log files can be an excellent help when you want to understand what actually happens during an evolutionary session. If you want to do fancy things like drawing phylogenetic trees of the generated genomes or such, log files will be a big help. You will probably need to write some perl scripts to be able to process that amount of data though.

Logging slows brew down a lot, of course.

Please realize that brews log files can grow really big; don't forget to switch logging back off and delete the log files after use, or your brand new gigantic hard drive will be full very soon...

I will not explain the format of log files here, as this would take too much room and time. Just put logging on for some time, if you are interested in it. I think you should be able to understand the result.

Most of the menu screen is covered by switches what to put in the log file:

See Scrolling menus.

Next: , Previous: Log files menu, Up: Users manual

4.31 Writing generated program code to a file.

Brew can write the produced Forth program code to a file, the so called ‘code file’. Code file have normal Forth syntax and should compile the defined genome when they are included. Beside the code brew can put some more information (i.e. stack type comments) in the file. This is the place to configure that.
You'll get here from brews main screen by pressing first m and then c.

On a Linux system you can watch mutation and selection at work in real time by switching to another console and say tail -f OUTPUT/FORTH/gene-code.fs.

The menu gives you the following options:

Switches what to put in the code file:
(The first three are compound switches).

Next: , Previous: Code file menu, Up: Users manual

4.32 Brews record and playback feature.

You get to the Record and Playback menu by pressing R from brews main screen.

Evolutionary programming can be mean: You set up a new experiment, make some preliminary tests with a few options and see exciting results within very short time. Then you try to find even better defaults, only to realize that the defaults you took have been very, very lucky, but unfortunately you have forgotten them. If only brew could remember them for you...

Or you have done a lot of configuring and want to do a series of experiments starting from that point, but you don't want to do all this configuring all over again and again...

For such situation brew has a feature to record and playback just about every user interaction possible in brew (It will even catch a lot of things you might have configured using configuration files).

If you want the thing to work it will be enough in most cases just to switch recording on. This must be done *before* you put any cells into the play. Brew will automatically record brews state in the moment you switched recording on, catch and record every change you do to this state and every command you pass to brew.

Brews record files are ordinary Forth source text files which can be edited by hand of course.

Use brews recording feature

Next: , Previous: Record and Playback, Up: Record and Playback

4.32.1 How to record an evolutionary session starting from scratch.

When you switch recording on in the ‘Record and Playback menu’ brew saves its 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 its 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.

The menu now looks like this:

Next: , Previous: Recording from scratch, Up: Record and Playback

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

Next: , Previous: Record after playback, Up: Record and Playback

4.32.3 Recording to be used as a benchmark

Brew has some special features to make it comparatively easy to create very complex benchmarks.

Brew now gives you a short information about what it has done, like:

I'm appending the following line to maybe-run-benchmark.fs
[DEFINED] my-new-bench [IF]   include benchmarks/my-new-bench.fs      [THEN]

I copy the file to the benchmark directory:

After that you can execute the benchmark from the command line if the Forth you use has an option to interpret a string on start up. It is enough to CREATE benchmark-name as in gforth -e "CREATE my-new-bench" brew.fs and brew will start the bench and terminate when it's finished. So startup time (including brews compilation) is *included* in the measured time. This is intentional.

Very likely you must edit the benchmark file by hand, i.e. you will probably like to switch display off during the bench. Note that brew has spread comments throughout the file that try to give you hints, where you might want to edit something.

If you want terminal and/or key reaction switched off during the benchmark you must edit early-compile-hook.fs by hand.

Previous: Record benchmark, Up: Record and Playback

4.32.4 Playback a recorded evolutionary programming session.

Select ‘Playback’ in the ‘Record and Playback menu’.

Choose a playback file.
(If you don't, the default record file name is probed).

That's it...

To interrupt playback just press a key. Brew will ask you if you want to continue (c) or quit (q).

Next: , Previous: Record and Playback, Up: Users manual

4.33 Compile time options


So you'd better read compile-options.fs...

Next: , Previous: Compile time options, Up: Users manual

4.34 Configuring function key bindings.

Here you configure function key bindings.
You reach this menu by pressing K in brews main screen.

Function keys are active in brews main screen and a few other places.
(Generally activating it could possibly confuse brew in some situations.

If function keys don't work on your system try toggling ‘use-ekey’. This might help.

The menu lets you associate each function key with an action.
Function key bindings are active in this menu, so you can try out the result. You can select amongst the following functions:

Next: , Previous: Menu function keys, Up: Users manual

4.35 Some demos

Here you can select a few demos.

As brew currently changes very much there are not too many of them at the time being...

There should be a ‘default’ demo, which explains default brew initialisation of the brew version you are running.

Previous: Menu Demos, Up: Users manual

4.36 Experiments.

Experiments are a more advanced kind of demos.

Currently there are only some simple test experiments, sorry.

While ordinary demos often lead you through an example evolution ‘experiments’ usually just initialise brew and let you run the evolution on your own. You should have some experience with brew to run an experiment.

Please read the source files in INPUTS/experiments/.../ for information what's going on in the different experiments.

In this brew version experiments are started by including an *initialisation* file from the experiments subdirectory in INPUTS/experiments/. The initialisation file will include source files for the experiment on its own.

See System menu, for how to include files.

Previous: Users manual, Up: Top

5 Programmers manual


Please read the brew source. There are a lot of comments meant to be helpful. Feel free to ask me questions.

Previous: Programmers manual, Up: Programmers manual

5.1 Brews files overview

Next: , Previous: Files, Up: Files

5.1.1 Brews default directory tree

Next: , Previous: Directory tree, Up: Files

5.1.2 Brew program source files

Next: , Previous: Program files, Up: Files

5.1.3 Files with gene primitives

The gene primitives (of the new genes/mutation version) get loaded from brew/INPUTS/genes/.

See Gene primitives, for more informations.

Next: , Previous: Genes files, Up: Files

5.1.4 Initialisation and configuration

Technically there is a big difference between compile time configuration and run time configuration.

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:

For special cases there is a hook early in the compilation process:

Next: , Previous: Configuration files, Up: Files

5.1.5 Brews output in brew/OUTPUT/

Next: , Previous: Output files, Up: Files

5.1.6 Brews temporary files in brew/OUTPUT/tmp/.

Brew creates some temporary files in its tmp/ directory which defaults to brew/OUTPUT/tmp/.

If you leave brew like intended (see Getting started) it will remove most of them, but there are some exceptions:

Next: , Previous: Temporary files, Up: Files

5.1.7 Documentation, versions, development, conventions...

Next: , Previous: Informative files, Up: Files

5.1.8 Files with tools for profiling, testing and system adaptions

Next: , Previous: Programming tool files, Up: Files

5.1.9 Benchmarks and Benchmark results

Next: , Previous: Benchmark files, Up: Files

5.1.10 Configuration of console size and special keys.

Previous: Console and key setup, Up: Files

5.1.11 Bugs and Debugging