Framsticks

If you need help, read the hints (tooltips) which appear when you stop the mouse pointer over the name of a parameter in GUI. The documentation below is provided in addition to those hints and discusses only some issues.

---

Experiment

Experiment definition: choose experiment definition which controls behavior of the Framsticks system. It is a script file with the ".expdef" extension. All available experiment definitions are summarized here. Advanced users can create their own experiment definitions and thus exploit the full potential of the system. Press "Apply" each time you change the experiment definition.

Parameters of the standard experiment definition are available here (see also tips).

Two experiment definitions more:

• standard-log.expdef in scripts_sample subdirectory (provided as an example of logging all genetic operations).
• standard-tricks.expdef in scripts_sample subdirectory (provided as an example of complex fitness functions with customized performance measurements, and changing creature locations during their simulation).

Initialize experiment: perform initialization actions for the selected experiment definition (for example, create appropriate gene pools and populations, clear them, insert the initial genotype, reset counters, etc.). It is recommended to perform initialization before running an experiment.

Experiment: Gene pools: <gene pool name>

An experiment definition may group genotypes into "gene pools". Each of them has separate settings. Settings affect all genotypes belonging to a given group (gene pool).

Fitness formula: advanced users can enter a custom fitness formula here. For the "standard" experiment definition, the formula is automatically created when you change weights of fitness criteria, and it reflects those settings.

Scale fitness?: if turned on, fitness is modified linearly according to the scaling rules. Thus final fitness is computed, which is equal to:

• 1.0 for creatures with average fitness
• 0.0 for creatures with fitness less or equal to the value of (average fitness – Shift coefficient * standard deviation of fitness)
• Scaling coefficient for creatures with maximal fitness.

Experiment: Populations: <population name>

An experiment definition may group simulated objects into "populations". Each of them has separate settings. Settings affect all individuals/objects which are simulated and belong to a given group (population).

Energy calculation: calculate energy balance during simulation?

Death: remove simulated objects when their energy reaches 0 (creatures "die")?

Neural net simulation: after a creature is put into the world, activate its neural network

• Off – don't simulate neural networks at all
• Immediately
• After stabilization – start brain simulation when the creature stops (initial vibrations stop).

Performance sampling period: especially important for estimating distance and velocity. Low values cause vibrations/little movements to be counted as velocity. High values let only smooth, straight moves to be counted.

Performance calculation: after a creature is put into the world, calculate its performance

• Off – don't calculate at all
• Immediately
• After stabilization – start performance measurements when the creature stops (initial vibrations stop).

In the diagram above, all variables (x, y, z, dist, distance, lifespan, velocity, vertpos) ale scalar values.
dist, distance, lifespan, and velocity are non-negative.
average(z_i) is a weighted average, so if the last period is shorter, the influence of the last z_i on vertpos is proportionally lower.

NOTES. If you want to evolve quick creatures, calculating their speed including the result of falling down and turning over would be unfair. This is why "delay for stabilization" may be introduced. Otherwise, creatures could gain additional ("unfair") fitness bonus because of their initial position (creatures fall onto the ground and earn speed without using neurons).

Speed and movements are measured using center of gravity position.

Consider the following special (educational) situations. (1) When a creature waits for stabilization, other living and active creatures may push it and move it, so that it cannot stabilize. (2) When you set immediate simulation of neural network and after-stabilization performance calculation, a creature might start moving immediately and would never stabilize. Thus performance and energy wouldn't be calculated, and such a creature would live forever as long as it kept moving. (3) In water environment, stabilization may be difficult to achieve.

Muscle static work, Muscle dynamic work, Assimilation productivity: these settings influence energy balance. When non-zero values are used, creatures may spend more energy than Idle metabolism, and can gain energy by assimilation.

Files

Save backup: if you set this value to a number N>0, the simulator writes an EXPT (experiment state) file every N events. An "event" is triggered by an experiment definition. With the "standard" experiment definition, an event occurs after a creature dies and its genotype's performance is updated. Names for successive autosave files are generated automatically by adding numbers to the last filename you used when saving the EXPT file. For example, when you save an experiment state under the filename speed1.expt, and set this parameter to 250, you will get the files speed1_001.expt, speed1_002.expt, and so on. Each file (log) will be saved after evaluating 250 creatures.

Overwrite: if not set, the simulator will change filenames if needed so that it will not overwrite old files.

Show file comments: comments from loaded files will be displayed in the messages window.

Error handling

Choose level of details for messages in the Messages window. Decide when genotypes/creatures are checked against errors.

Fail on warnings: some genotypes cause problems when they construct creatures. They are valid syntactically, but warnings are generated while a creature is built from such a genotype. These warnings are called "build problems", and an example of this situation is when a genotype provides many identical muscles in the same place in the body. This is not allowed, and thus some muscles are disabled (which causes warnings).

If you enable "Fail on warnings", such genotypes will not be simulated, only those that are entirely correct. Otherwise, genotypes with build problems (after they are fixed) will also be simulated.

World

Type: For 'Blocks' and 'Height field' you have to provide a "map" of heights. 'Height field' world has smooth slopes.

Size: Side length of the (square) world.

Map: description of world heights, it can be:

• randomly generated world: r (size1) (size2) (seed)
  size1,size2 are number of blocks in west-east and north-south direction. seed can be omitted, for different numbers you get different worlds.
• custom layout: m (size1) (size2)
  followed by world map (size1*size2 digits)
  5 means 'level zero' block height, 6-9 is a 'hill', 1-4 is a 'hole'
  example (a cross-shaped hill):

    m 3 3
    575
    777
    575
  

  additional characters "-" and "|" are slope surfaces between blocks ("-" is WE direction, "|" is NS direction). They are valid only between digits and only for 'Blocks' world type.
  more sophisticated example:

    m 5 5
    22-66
    222-6
    2|333
    -6-33
    4|498
  

• custom layout: M (size1) (size2)
  works just like 'm', but you can use floating point numbers instead of digits (so you can use 5.35, not just 5). Note that with 'M', the value of 0 means 'level zero' height, which is different from 'm' convention.

Water level: the main surface is at 0.0 height and you set the water level here.

Boundaries: what happens when a creature crosses the boundary of the world?

• None – the world is unlimited,
• Fence – creatures cannot go outside,
• Teleport – creatures are moved to the opposite side when trying to cross the border.

Genetics

Remember history...: the history of genetic operations (which genotype is mutated from which, which genotype was crossed over with which, etc.) is remembered so that you can draw a tree of evolution. Such history can consume large amounts of memory when it contains many (for example, tens of thousands) genotypes.

Genetics: Neurons to add

Checked neurons are those which may be introduced into genotypes during mutations.

Genetics: f0

Relative mutation probabilities for f0 genotype language.

Genetics: f1

Settings for f1 genotype language.

Excluded modifiers let you disable using some genotypic symbols during mutations: you can prevent some features from being present in the evolved genotypes. Excluding 'E' and 'e' is needed when energetic efficiency mode is disabled (so that the creatures will not change their starting energy). And, for example, if you don't want your creatures to use different sticks' weights to improve swimming ability in water, exclude 'W' and 'w'.

Proportional crossover: when turned off, random substrings of two parent genotypes are exchanged to form two offspring genotypes (in two-point crossing over). When turned on, cut points in the second parent will be selected proportionally (based on neural genes) to the cutpoints chosen randomly in the first parent. Thus, if both parents have the same number of neurons, then this will be preserved in their children. If, additionally, both parents have identical bodies and neural genes are aligned in both parent genotypes, then their children will also have identical bodies. This may be important if you perform crossover only within species (among similar genotypes – individuals).

Genetics: f1: Morphology contains detailed mutation probabilities concerning physical structure parts in genotypes. Genetics: f1: Neuron net contains detailed mutation probabilities concerning neuron net parts in genotypes.

Genetics: f4

Detailed mutation probabilities concerning f4 genotype language. When mutation occurs, it can be either Add node, Delete node, or Modify node. Values expressing probabilities can be adjusted here. Mutation types are shown below.

• Add node
  • Add division
  • Add neural connection
  • Add neural parameter
  • Add repetition
  • Add random symbol
• Delete node
• Modify node

The number of codes which are randomly mutated is also random, varying from 0% to 25% of the genotype genes.

Genetics: Conversions

Specific converters can be enabled and disabled here. They convert various formats of genotypes. Unless you are an experienced user, leave all of them enabled.

User scripts

These scripts are loaded automatically from the "scripts" subdirectory. Advanced users can create their own scripts.

Creature

Creature: Neurons

Random initialization: if set to zero, neuron states are equal to zero when each individual is created from its genotype and put into the simulator. If you enter a positive value, neural states are random, and thus NN control has to be more robust (and does not depend on specific initial state values).

Creature: Neurons: Enabled

These settings decide which neurons are simulated in creatures. If a neuron is not enabled, its state is initialized when a creature is "born", and then the state does not change.

Creature: Similarity

Determines how the dissimilarity of two genotypes is evaluated. This is important during crossing over, which can depend on the dissimilarity of the two parent genotypes (and can make crossing over of differing genotypes impossible). Similarity can also be involved in fitness reduction for speciation and creating niches. Enter weights for genotype/phenotype criteria concerning 'body' and 'brain'. Refer to scientific papers [1], [2], [3], [4] to get an idea of dissimilarity computation methods. Dissimilarity is also used for clustering of individuals using the UPGMA method.