What is an experiment definition, and how to create your own expdef 

The most important feature of Framsticks is that you may define your own rules for the simulator. There are no predetermined laws, just a script – an experiment definition. This script is a set of instructions in some language, which is interpreted by Framsticks program and executed.

This script defines behavior of the Framsticks system in a few associated areas:

  • Creation of objects in the world. The script defines where, when and how much of what objects will be created. An object is an evolved organism, food particle, or any other element of the world designed by a researcher. Thus, depending on some specific script, food or obstacles might appear, move and disappear, their location might depend on where creatures are, etc.
  • Objects interactions. Object collision/contact is an event, which may cause some action defined by the script author. For example, contact may mean energy ingestion, pushing each other, destruction, or reproduction.
  • Evolution. A steady-state (one-at-a-time) selection model, where a single genotype is inserted into a gene pool at a time, can be used. But a standard (i.e. generational replacement) evolutionary algorithm approach is also possible (a new gene pool replaces the whole old gene pool). Another possibility is tournament competition for all pairs of genotypes. In general, the script can define many gene pools and many populations, and perform independent evolutions under different conditions.
  • Evaluation criteria are flexible, and do not have to be as simple as the performances supplied by the simulator (but they will have to be based somehow on performances). For example, fitness might depend on time or energy required to fulfill some task, or degree of success (distance from target etc.).

So one can use Framsticks for simulation of various ecosystems, with very diverse laws. This system is very versatile! The script is built from "procedures" assigned to system events. Currently there are the following events:

  • onExpDefLoad – occurs after experiment definition was loaded. This procedure should prepare the environment, create gene pools and populations.
  • onExpInit – occurs when user clicks the "Initialize experiment" button, or when Simulator.init() is called.
  • onExpSave – occurs on save experiment request.
  • onExpLoad – occurs on load experiment request. After this event, system state should resemble the state before onExpSave.
  • onStep – occurs in each simulation step.
  • onBorn – occurs when a new organism is created in the world
  • onKill – occurs when a creature is removed from the world
  • on[X]Collision – occurs when an object of group [X] has touched some other object.

Thus a researcher may define the behavior of the whole system by implementing appropriate actions within these events. A single script (experiment definition) may use parameters, so it usually allows to perform a whole bunch (class) of diversified experiments.

Illustrative example (standard experiment definition)

The file "standard.expdef" contains the full source for the script used to optimize creatures on a steady-state basis, with fitness defined as a weighted sum of their performances (see parameters description). This script is quite versatile and complex. Below its general idea is explained, with simplified actions assigned to system events:

  • create single gene pool "Genotypes"
  • create two populations "Creatures" and "Food"
  • empty all gene pools and populations
  • place the beginning genotype in "Genotypes"
  • if too little food: create new object in "Food"
  • if too few organisms: select a parent from "Genotypes"; mutate, crossover, or copy it. From the resulting genotype create an individual in "Creatures"
  • move new object into a randomly chosen place in the world
  • set starting energy according to object type
  • if "Creatures" object died, save its performance in "Genotypes" (possibly creating a new genotype). If there are too many genotypes in "Genotypes", remove one.
  • send energy portion from "Food" object to "Creature" object.

When you look at the standard.expdef file (in the "scripts" subdirectory), you will see it is written in a simple language. Thus, when creating your own script, computer science background is helpful. A documentation on script writing is available here. The existing scripts should serve as examples (see cliutils.ini file in command-line frams distribution for illustrative examples). Any file with the ".expdef" extension, which is present in the "scripts" directory, will automatically appear on the list of experiment definitions to choose from.