Bacterium
The Bacterium species is the most commonly-used type, and shown here is an example mark-up for a typical Bacterium.
The first part of the species mark-up lists the different particles composing this species; these particles form ‘compartments’ within the agent that signify the types of biomass that the agent contains. The possible particle types that may be used are taken from the particle mark-ups defined early in the protocol file, generally consisting of ‘biomass’, ‘inert’, and ‘capsule’. The initial mass of each particle may be given (in units of femtograms, 1 fg = 10-15 g), but if you set the value to zero the simulator will assign a reasonable random initial value for the mass. For Bacterium species, only one particle type is actually necessary to include, but it is common to include several types. In the example mark-up above, the Bacterium contains active biomass, inert biomass, and EPS compartments (the ‘biomass’, ‘inert’, and ‘capsule’ compartments, respectively); in this species, inert and capsule compartments exhibit special behaviour: inert biomass will accumulate in the agent, while a capsule will be excreted if it accumulates to take up too much of the agent’s mass. Note that the ‘capsule’ particle also requires you to specify its type via the class attribute; when the capsule has become too large and needs to be excreted, an agent of that class will be created (this means that it is necessary to have previously defined a species with that name; in the above example, the ‘MyAutotrophEPS’ species MUST be defined before ‘MyAutotroph’).
After the particle mark-ups, several different species parameters are defined; these few parameters are common to most types of agents. The color parameter defines the color used to draw agents of this species in POV-Ray images; possible color names include: red, blue, cyan, darkgray, lightgray, gray, green magenta, orange, pink, yellow, black, and white. The computationDomain parameter merely states which domain contains this particular species. The divRadius parameter defines how large an agent is allowed to grow before dividing into two agents. The deathRadius parameter defines how small an agent may become before being removed from the simulation. The babyMassFrac parameter defines what fraction of the parent agent’s biomass the newly created agent will inherit at division. The next two parameters define how neighbouring agents interact, as illustrated in the following diagram:
In this figure, two agents (defined by solid lines) overlap in their region of influence (dashed lines), and will thus shove one another apart. The shoveFactor parameter is a factor multiplying the agent radius that is used to determine the region of influence in neighbour shoving; in the image, the shoving radius r1Shov is computed from the agent radius r1Tot using this factor. The shoveLimit parameter sets the minimal distance between two agents, and is usually set to zero; if two agents are closer than this limit (overlap δ is positive), then shoving will occur.
The three additional parameters divRadiusCV, deathRadiusCV and babyMassFracCV can be used to define the degree of stochasticity affecting the division and death processes. By default the CV (coefficient of variation) of these parameters is set to 0.1 (see the LocatedParam class in the source code). Setting them to zero allows one to simulate an almost deterministic version of iDynoMiCS and can be useful to assess the effect of stochasticity in a particular system.
Following the location, size, shoving, and coefficient of variation parameters, one now defines any parameters particular to this class of species. For the class Bacterium shown above, the only additional parameter to specify is epsMax, which defines the maximum volume fraction of the agent that may be taken up by the EPS capsule before EPS excretion will occur. Other species types generally have other parameters that are defined here, as will be explained in the following sections.
The next item to define is the set of reactions in which this species is involved. These reactions are taken from the reaction mark-ups that were defined earlier, and once again you must take care that for each reaction the correct name is used in order to avoid a syntax error. For each reaction you may also set the status attribute to ‘active’ or ‘inactive’; some species types include mechanisms for switching reactions on or off during a simulation.
The final entry tags in the species mark-up create individuals of the defined species. From Version 1.2 of iDynoMiCS, the tags used in this section are dependent on the method of agent attachment specified in the SIMULATOR section of the protocol file (onetime or selfattach). For one-time attachment, cells are created on the solid structure, in a specified birth area. For self-attachment, the cells are introduced on the boundary layer and perform a 'run and tumble' motion, moving randomly through the domain
The number attribute specifies how many agents of this species are to be created, and the parameter birthday specifies the point of the simulation at which they will be introduced (with 0 hours meaning at the start of the simulation). The two coordinates parameters specify two opposing corners of the rectilinear region within which the agents will be randomly placed. In 2D simulations, this region is a rectangle and the z value is not read, while in 3D simulations the region is a rectangular prism.
Agents are 'injected' into the system between two time-points (in hours). This gives us two parameters, cellInjectionStartHour and cellInjectionEndHour. If injecting over the whole period, the end hour will be the same as the simulation time.
In the period between start and end, a number of cells are introduced onto the top of the boundary layer. These will then perform a run and tumble motion until they either (a) hit the surface, (b) hit the biofilm, or (c) return to the bulk. This run and tumble consists of a random angle being chosen, and the cell moving away at that angle for a specified distance (set by a cellRunSpeed parameter). After a certain number of seconds (set by parameter tumbleInt), the cell will change direction ('tumble'). Along the route, the agents checks whether it has come into contact with the biofilm surface or the substratum. If contact is detected (where contact is the cells radius + an adjustment parameter, stickinessAddition, that can capture additional receptors on an agent surface), these agents will attach. In (c), where an angle has been chosen such that the agent returns to the bulk, we assume the agent is back in the 'mix' and we try another run will a new agent. This continues until the number of cells that attach to the surface or biofilm matches a set rate per hour. This number is set in the parameters injectionOnAttachmentFrequency and injectionOffAttachmentFrequency - chosen dependent if you are within an injection period (between start and end hour) or outside that period.
The two frequencies (one for during cell injection and one for outside) capture the fact that, if outside an injection period, the rate of attachment could be significantly different. However if you don't need this, these can be set the same.
Note that cell attachment frequencies are measured in cells per hour. The simulator is able to adjust this if your time-step is less than one hour, so don't worry if you are using time-steps that are less than an hour.
