Environment file

This is the setup file for the task/resource system in Avida.

Six main keywords are used in this file, RESOURCE, GRADIENT_RESOURCE, REACTION, CELL, MUTATION, and SET_ACTIVE. Their formats are:

  RESOURCE  resource_name[:options]  {resource_name ...}
  GRADIENT_RESOURCE  gradient_resource_name[:options]  {gradient_resource_name ...}
  REACTION  reaction_name  task  [process:...]  [requisite:...]
  CELL resource_name:cell_list[:flow]
  MUTATION name trigger scope type rate
  SET_ACTIVE type name new_status(default=true)

Resources

All entries on a resource line are names of individual resources. Resources can have a global quantity depletable by all organisms or can have quantities that vary from cell to cell. The resource name infinite is used to refer to an undepletable resource. There are two basic commands to set up a general resource: RESOURCE and CELL. In addition, GRADIENT_RESOURCE is a specific instance of RESOURCE which allows the user to specify a cellular distribution of quantities that change (aka move) over time in an Avida run.

RESOURCE Command

The syntax for the Resource command is:

RESOURCE resource_name[:options]  {resource_name ...}

Where resource_name is a unique name of the resource. This name may be used by the CELL command to further define the resource or in the REACTION to define which resource is consumed/created by a reaction.

Where options is a colon delimited list of factors that modify the resource. The following chart specifies these options.

 

Table 1: Resources Options

(blue variables used for all resources while red variables are only used for spatial resources)

Argument	Description	Default
inflow	The number of units of the resource that enter the population over the course of an update. For a global resource this inflow occurs evenly throughout the update, not all at once. For a spatial resource this inflow amount is added every update evenly to all grid cells in the rectangle described by the points (inflowx1,inflowy1) and (inflowx2,inflowy2).	0
outflow	The fraction of the resource that will flow out of the population each update. As with inflow, this happens continuously over the course of the update for a global resource. In the case of a spatial resource the fraction is withdrawn each update from each cell in the rectangle described by the points (outflowx1,outflowy1) and (outflowx2,outflowy2).	0.0
initial	The initial abundance of the resource in the population at the start of an experiment. For a spatial resource the initial amount is spread evenly to each cell in the world grid.	0
geometry	The layout of the resource in space. global -- the entire pool of a resource is available to all organisms grid -- organisms can only access resources in their grid cell. Resource can not flow past the edges of the world grid. (resource will use spatial parameters) torus -- organisms can only access resources in their grid cell. Resource can flow to the opposite edges of the world grid. (resource will use spatial parameters)	global
deme	Is this resource going to be used by a deme. (True or False)	false
energy	Is this an energy resource. The energy model must be used. (True or False)	false
inflowx1	Leftmost coordinate of the rectangle where resource will flow into world grid. If not specified but an inflow rate is specified, an x-coordinate will be determinstically assigned.	0
inflowx2	Rightmost coordinate of the rectangle where resource will flow into world grid. If not specified, inflowx1's value will be used.	0
inflowy1	Topmost coordinate of the rectangle where resource will flow into world grid. If not specified but an inflow rate is specified, a y-coordinate will be determinstically assigned.	0
inflowy2	Bottommost coordinate of the rectangle where resource will flow into world grid. If not specified, inflowy1's value will be used.	0
outflowx1	Leftmost coordinate of the rectangle where resource will flow out of world grid.	0
outflowx2	Rightmost coordinate of the rectangle where resource will flow out of world grid. If not specified, outflowx1's value will be used.	0
outflowy1	Topmost coordinate of the rectangle where resource will flow out of world grid.	0
outflowy2	Bottommost coordinate of the rectangle where resource will flow out of world grid. If not specified, outflowy1's value will be used.	0
xdiffuse	How fast material will diffuse right and left. This flow depends on the amount of resources in a given cell and amount in the cells to the right and left of it. (0.0 - 1.0)	1.0
xgravity	How fast material will move to the right or left. This movement depends only on the amount of resource in a given cell. (-1.0 - 1.0)	0
ydiffuse	How fast material will diffuse up and down. This flow depends on the amount of resources in a given cell and amount in the cells above and below it. (0.0 - 1.0)	1.0
ygravity	How fast material will move to the up or down. This movement depends only on the amount of resource in a given cell. (-1.0 - 1.0)	0

 

An example of a RESOURCE statement that begins a run with a fixed amount of the (global) resource in the environment, but has no inflow or outflows is:

  RESOURCE  glucose:initial=10000

If you wanted to make this into a chemostat with a 10000 equilibrium concentration for unused resources, you could put:

  RESOURCE  maltose:initial=10000:inflow=100:outflow=0.01

If you want a resource that exists spatially where the resource enters from the top and flows towards the bottom where it exits the system, you could use:

  RESOURCE lactose:geometry=grid:initial=100000:inflow=100:outflow=0.1:\
  inflowx1=0:inflowx2=100:inflowy1=0:inflowy2=0:outflowx1=0:outflowx2=100:\
  outflowy1=100:outflowy2=100:ygravity=0.5

Defining a resource with no parameters means that it will start at a zero quantity and have no inflow or outflow. This is sometimes desirable if you want that resource to only be present as a byproduct of a reaction. Remember, though, that you should still have an outflow rate if it's in a chemostat.

CELL Command

Using Cell can help increase the detail of a spatial resource. Any cell in a grid can be given their own initial amount of a resource, inflow amount and outflow rate. These values are in addition to any other values set for the spatial resource for the entire for the grid (diffusion and gravity for instance). The command has the format:

CELL resource_name:cell_list[:options]

Where resource_name is the name of the spatial resource that this cell command will modify. If this resource has not been defined yet, a new resource with this name will be created.

Where cell_list is comma delimited list of cells that will be set. We treat the grid like a one dimensional array where 0 is the upper left corner, world_x - 1 is the upper right corner, and (world_x * world_y) - 1 is the lower right corner. As well as single cell you can also enter a range of cells by using the format a..b.

Where options is a colon delimited list of factors that modify the resource. The following chart specifies these options.

 

Table 4: Cell Options

Argument	Description	Default
inflow	The number of units of the resource that enter a cell at the end of an update.	0
outflow	The fraction of the resource that will flow out a cell each update.	0.0
initial	The initial abundance of the resource in a cell at the start of an experiment.	0

 

An example of setting two cells in the glucose spatial resource:

CELL glucose:20,50:initial=100:inflow=10:outflow=0.1

An example of setting a 3 x 3 square of cells in the middle of a a maltose spatial resource (assuming a 10 x 10 world):

CELL maltose:33..35,43..45,53..55:initial=500:inflow=5:outflow=0.01

Reactions

Reactions are set to allow organisms to consume or produce resources when those organisms preform certain tasks. Reactions can be used to reward (or punish) organisms for performing tasks or to set up a "food web". They are described by the task that triggers them, the processes they perform (including resources used and the results of using them), and requisites on when they can occur.

REACTION Command

REACTION  reaction_name  task[:argument:...]  [process:...]  [requisite:...]

Where reaction_name is a unique name for a reaction.

Where task is the name of the task that must be be performed to trigger the reaction. A list of common tasks is listed in Table 3.

Where argument is a list of specific arguments needed by the particular task.

Where process is a colon delimited list of information about how resources are consumed/produced. Process settings are described in Table 4.

Where requisite is a colon delimited list describing when reactions can be triggered. Requisite settings are described in Table 5.

Each reaction must have a task that triggers it. Currently, eighty tasks have been implemented, as summarized in the following table (in approximate order of complexity):

 

Table 5: Available Tasks

Task	Description
echo	This task is triggered when an organism inputs a single number and outputs it without modification.
add	This task is triggered when an organism inputs two numbers, sums them together, and outputs the result.
sub	This task is triggered when an organism inputs two numbers, subtracts one from the other, and outputs the result.
not	This task is triggered when an organism inputs a 32 bit number, toggles all of the bits, and outputs the result. This is typically done either by nanding (by use of the nand instruction) the sequence to itself, or negating it and subtracting one. The latter approach only works since numbers are stored in twos-complement notation.
nand	This task is triggered when two 32 bit numbers are input, the values are 'nanded' together in a bitwise fashion, and the result is output. Nand stands for "not and". The nand operation returns a zero if and only if both inputs are one; otherwise it returns a one.
and	This task is triggered when two 32 bit numbers are input, the values are 'anded' together in a bitwise fashion, and the result is output. The and operation returns a one if and only if both inputs are one; otherwise it returns a zero.
orn	This task is triggered when two 32 bit numbers are input, the values are 'orn' together in a bitwise fashion, and the result is output. The orn operation stands for or-not. It is returns true if for each bit pair one input is one or the other one is zero.
or	This task is triggered when two 32 bit numbers are input, the values are 'ored' together in a bitwise fashion, and the result is output. It returns a one if either the first input or the second input is a one, otherwise it returns a zero.
andn	This task is triggered when two 32 bit numbers are input, the values are 'andn-ed' together in a bitwise fashion, and the result is output. The andn operation stands for and-not. It only returns a one if for each bit pair one input is a one and the other input is not a one. Otherwise it returns a zero.
nor	This task is triggered when two 32 bit numbers are input, the values are 'nored' together in a bitwise fashion, and the result is output. The nor operation stands for not-or and returns a one only if both inputs are zero. Otherwise a zero is returned.
xor	This task is triggered when two 32 bit numbers are input, the values are 'xored' together in a bitwise fashion, and the result is output. The xor operation stands for "exclusive or" and returns a one if one, but not both, of the inputs is a one. Otherwise a zero is returned.
equ	This task is triggered when two 32 bit numbers are input, the values are equated together in a bitwise fashion, and the result is output. The equ operation stands for 'equals' and will return a one if both bits are identical, and a zero if they are different.
logic_3AA- logic_3CP	These tasks include all 68 possible unique 3-input logic operations, many of which don't have easy-to-understand human readable names.

 

When describing a reaction, the process portion determines consumption of resources, their byproducts, and the resulting bonuses. There are several arguments (separated by colons; example below) to detail the use of a resource. Default values are in brackets:

 

Table 6: Reaction Process Specifications

Argument	Description	Default
resource	The name of the resource consumed. By default, no resource is being consumed, and the 'max' limit is the amount absorbed.	infinite
value	Multiply the value set here by the amount of the resource consumed to obtain the bonus. (0.5 may be inefficient, while 5.0 is very efficient.) This allows different reactions to make use of the same resource at different efficiency levels.	1.0
type	Determines how to apply the bonus (i.e. the amount of the resource absorbed times the value of this process) to change the merit of the organism.    add: Directly add the bonus to the current merit.    mult: Multiply the current merit by the bonus (warning: if the bonus is ever less than one, this will be detrimental!)    pow: Multiply the current merit by 2bonus. this is effectively multiplicative, but positive bonuses are always beneficial, and negative bonuses are harmful.    enzyme: Add bonus * resource / (resource + ksubm) to the current merit. This is gives a Michaelis-Menten enzyme type reward where bonus is the Kcat and the Km is entered. Does not work with unlimited resources.    energy: Add the bonus energy to the organism's energy waiting to be applied buffer. Bonus energy can be applied on completion of a reaction, execution of the sleep/eat instruction, or when the organisms divides. See Energy Model documentation for more information.	add
max	The maximum amount of the resource consumed per occurrence.	1.0
min	The minimum amount of resource required. If less than this quantity is available, the reaction ceases to proceed.	0.0
frac	The maximum fraction of the available resource that can be consumed.	1.0
product	The name of the by-product resource. At the moment, only a single by-product can be produced at a time.	none
conversion	The conversion rate to by-product resource	1.0
inst	The instruction that gets executed when this reaction gets performed. If you do not want an organism to be able to have the instruction in their genome, you still must put it in the instruction set file, but set its weight to zero. The instruction is executed at no cost to the organism.	none
lethal	Whether the cell dies after performing the process	0
random	Whether any produced resource is placed randomly in the world instead of the focal cell.	0
depletable	Whether this resource is consumed by reactions.	1
phenplastbonus	Specify how to handle phenotypic plasticity at run-time. This option may significantly slow an Avida experiment. When requested in many of the settings below (*), task bonuses will be adjusted by the plasticity of each organism's genotype. Requisites will still be honored, making true task completion information ambiguous.    default: Do not attempt to use the genotype's task plasticity.    *nobonus: Do not give a bonus to non-static tasks.    *fracbonus: Scale the bonus by how static the task is.    *fullbonus: Always reward a task when it is detected.	default
ksubm	Km for an enzyme reaction.	0.0

 

If no process is given, a single associated process with all default settings is assumed. If multiple process statements are given, all are acted upon when the reaction is triggered. Assuming you were going to set all of the portions of process to be their default values, this portion of the reaction statement would appear as:

  process:resource=infinite:value=1:type=add:max=1:min=0:frac=1:product=none:conversion=1

This statement has many redundancies; for example, it would indicate that the associated reaction should use the infinite resource, making 'frac' and 'min' settings irrelevant. Likewise, since 'product' is set to none, the 'conversion' rate is never considered.

The requisite entry limits when this reaction can be triggered. The following requisites (in any combination) are possible:

 

Table 7: Reaction Requisite Specifications

Argument	Description	Default
reaction	This limits this reaction from being triggered until the other reaction specified here has been triggered first. With this, the user can force organisms to perform reactions in a specified order.	none
noreaction	This limits this reaction from being triggered if the reaction specified here has already been triggered. This allows the user to make mutually exclusive reactions, and force organisms to "choose" their own path.	none
min_count	This restriction requires that the task used to trigger this reaction must be performed a certain number of times before the trigger will actually occur. This (along with max_count) allows the user to provide different reactions depending on the number of times an organism has performed a task.	0
max_count	This restriction places a cap on the number of times a task can be done and still trigger this reaction. It allows the user to limit the number of times a reaction can be done, as well as (along with min_count) provide different reactions depending on the number of times an organism as performed a task.	INT_MAX
min_tot_count	This restriction requires that the total number of tasks performed by the organism must be at least this high before this reaction will trigger. This (along with max_tot_count) allows the user to provide different reactions depending on how many tasks an organism performs.	0
max_tot_count	This restriction places a cap on the number of tasks an organism can do and still trigger this reaction. It allows the user to limit the number of tasks that will be rewarded, as well as (along with min_tot_count) provide different reactions depending on the number of tasks an organism performs.	INT_MAX
reaction_min_count	This restriction requires that the reaction must be performed a certain number of times before any rewards are given. The restriction refers to the number of times the specific reaction has been triggered, regardless of how many times the referenced task has been performed. The reaction process specs max and min will restrict reactions and their counts, not tasks.	0
reaction_max_count	This restriction caps the number of times an organism can perform the reaction, effectively limiting the number of times a reaction will be rewarded. The restriction refers to the number of times the specific reaction has been triggered, regardless of how many times the referenced task has been performed. The reaction process specs max and min will restrict reactions and their counts, not tasks.	INT_MAX
divide_only	This command decides when a task will be checked, if the value is 0 the task will only be checked when an organism executes an IO. If the value is 1 the task will only be checked when the organism divides. If the value is 2 the task will be checked at both times.	0
parasite_only	This command only allows parasites to get credit for the reaction, not host organisms.	False

 

No restrictions are present by default. If there are multiple requisite entries, only *one* of them need be satisfied in order to trigger the reaction. Note though that a single requisite entry can have as many portions as needed.

Examples

We could simulate the pre-environment system (in which no resources were present and task performance was rewarded with a fixed bonus) with a file including only lines like:

  REACTION AND logic:2a process:type=mult:value=4.0   requisite:max_count=1
  REACTION EQU logic:2h process:type=mult:value=32.0  requisite:max_count=1

No RESOURCE statements need be included since only the infinite resource is used (by default, since we don't specify another resource's name) # To create an environment with two resources that are converted back and forth as tasks are performed, we might have:

  RESOURCE  yummyA:initial=1000
  RESOURCE  yummyB:initial=1000
  REACTION  AtoB  gobbleA  process:resource=yummyA:frac=0.001:product=yummyB
  REACTION  BtoA  gobbleB  process:resource=yummyB:frac=0.001:product=yummyA

A value of 1.0 per reaction is default. Obviously gobbleA and gobbleB would have to be tasks described within Avida.

A requisite against the other reaction being performed would prevent a single organism from garnering both rewards in equal measure.

As an example, to simulate a chemostat, we might have:

  RESOURCE glucose:inflow=100:outflow=0.01

This would create a resource called "glucose" that has a fixed inflow rate of 10000 units where 20% flows out every update. (Leaving a steady state of 50,000 units if no organism-consumption occurs).

Limitations to this system:

• Only a single resource can be required at a time, and only a single by-product can be produced.

The default setup is:

  REACTION  NOT  not   process:value=1.0:type=pow  requisite:max_count=1
  REACTION  NAND nand  process:value=1.0:type=pow  requisite:max_count=1
  REACTION  AND  and   process:value=2.0:type=pow  requisite:max_count=1
  REACTION  ORN  orn   process:value=2.0:type=pow  requisite:max_count=1
  REACTION  OR   or    process:value=3.0:type=pow  requisite:max_count=1
  REACTION  ANDN andn  process:value=3.0:type=pow  requisite:max_count=1
  REACTION  NOR  nor   process:value=4.0:type=pow  requisite:max_count=1
  REACTION  XOR  xor   process:value=4.0:type=pow  requisite:max_count=1
  REACTION  EQU  equ   process:value=5.0:type=pow  requisite:max_count=1

This creates an environment where the organisms get a bonus for performing any of nine tasks. Since none of the reactions are associated with a resource, the infinite resource is assumed, which is non-depeletable. The max_count of one means they can only get the bonus from each reaction a single time.

A similar setup that has 9 resources, one corresponding to each of the nine possible tasks listed above is:

  RESOURCE  resNOT:inflow=100:outflow=0.01   resNAND:inflow=100:outflow=0.01
  RESOURCE  resAND:inflow=100:outflow=0.01   resORN:inflow=100:outflow=0.01
  RESOURCE  resOR:inflow=100:outflow=0.01    resANDN:inflow=100:outflow=0.01
  RESOURCE  resNOR:inflow=100:outflow=0.01   resXOR:inflow=100:outflow=0.01
  RESOURCE  resEQU:inflow=100:outflow=0.01
REACTION  NOT  not   process:resource=resNOT:value=1.0:frac=0.0025
REACTION  NAND nand  process:resource=resNAND:value=1.0:frac=0.0025
REACTION  AND  and   process:resource=resAND:value=2.0:frac=0.0025
REACTION  ORN  orn   process:resource=resORN:value=2.0:frac=0.0025
REACTION  OR   or    process:resource=resOR:value=4.0:frac=0.0025
REACTION  ANDN andn  process:resource=resANDN:value=4.0:frac=0.0025
REACTION  NOR  nor   process:resource=resNOR:value=8.0:frac=0.0025
REACTION  XOR  xor   process:resource=resXOR:value=8.0:frac=0.0025
REACTION  EQU  equ   process:resource=resEQU:value=16.0:frac=0.0025

Other Commands

SET_ACTIVE Command

Allows user to activate or deactivate a reaction. If this command is not used all reactions are active.

  SET_ACTIVE type name new_status(default=true)

Where type is the type of command to activate/deactivate. Currently REACTION is the only choice.

Where name is the name of the item to activate/deactivate.

Where new_status sets if the item is active (0 or FALSE will deactivate).