Creating A New Mode¶
Note: this guide is in progress and does not contain all helpful details.
Once you have familiarized yourself with Symbulation and its default mode, you might be interested in designing your own experiment, adding functionality to the codebase, and collecting data.
The existing modes include
default (Host and Symbiont),
efficient (Efficient Host and Efficient Symbiont),
lysis (Bacterium and Phage), and public goods game or
pgg (PGGHost and PGGSymbiont).
There are several steps to creating your own world, including following conventions for file structure, adding your own organisms, designing tests, adding a WorldSetup file, adding targets to the makefile, and more.
This guide will walk you through how to properly add all of these features.
First, you must decide if your new mode falls under one of two scenarios. In the first scenario, you wish to change the processes of an existing organism, but will not be adding any new traits. The second scenario includes the addition of new traits, or genome values, and will therefore also require functions that track the evolution of this new trait. Depending on the goals of your project and which scenario it falls under (1 or 2), you will need to add to the codebase in a varying manner. Most sections below pertain to both scenarios and should be completed no matter what. Sections that are specific to a particular scenario will be labeled accordingly.
Choose a one word descriptor for your new mode.
Then make a folder in
Inside of this folder will be a world setup source file (explained in more detail later), as well as any necessary header files.
Next, you will need to add new header files for your new organisms.
The host organism(s) must extend the
Host.h class in the
source/default_mode, and similarly, the symbiont organism(s) must extend the
Each new class must contain the following:
genome/instance variables (Scenario 2 only)
mutate (Scenario 2 only)
config settings to edit genome/instance variables (Scenario 2 only)
World Class: Scenario 2 Only¶
In the second scenario, since you have added new traits to the organisms, you will need to add code that can track the evolution of these traits.
Once the organisms have been made, they must be put in a world.
Create a world class that extends the
SymWorld.h class in the
Next, make sure to add data nodes and functions that set up a data tracking file by using your newly created data nodes.
Next, create the source file to set up your newly created world. Follow a similar pattern as the other mode setup files. The primary difference should be the organism types added to the world, which should now be your newly created host(s) and symbiont(s).
Next, add a file to
source/native with the name
This is the main source file that will allow the experiment to function.
In it, the world is created, set up according to the setup file, and is permitted to run for the specified number of updates.
Lastly, add the necessary targets to the Makefile for your new mode. Your new mode will need:
a compiling target, with the naming convention “
a debug taget, with the naming convention “debug-
” and “ -debug”
a testing target, with the naming convention “test-
a debug while testing target, with the naming convention “test-debug-
After you have created your new mode, you must design tests to ensure it is functioning as expected.
Add a folder to
source/test with the name
Inside of this folder, add testing source files corresponding to each organism.
Make sure to also add files that test the interactions between organisms, as well as the data nodes.
Also make sure to do the following:
Include the testing file paths in
Add catch tags
Once you have created your organisms and corresponding world, designed their tests, added a main source file, and added targets to the Makefile, you are ready to experiment!