ProtocolFiles

What is a protocol file?

Protocol files are XML (Extensible Markup Language) files found in the folder iDynoMiCS-2 > protocol (or eGUT > protocol). Protocol files are descriptions of biological systems that we wish to simulate, which can be read by iDyno. iDyno will then simulate the system, returning XML output files with information on the state of the system at each time step, which have the same hierarchical structure as a protocol file. In fact, you can use these output files as protocol files to “restart” a simulation that you have previously run. In this section we'll be using some XML jargon, like “elements” and “attributes”. In order to understand what I’m talking about, it might be useful to read up on XMLs online. Here is a quick guide to XMLs that should give you a brief grounding:

https://www.tutorialspoint.com/xml/xml_quick_guide.htm

<!-- A tag surrounded by < and > indicates the content of node starts here -->
<node >
<!-- An XML node may contain childnodes -->
    <childNode> </childNode>
    <!-- Every node must be closed with it's tag surrounded by </ and > -->
    <childNode />
    <!-- If a node has no child nodes, a node can be closed immediately by adding / before > -->
    <childNode attribute="value" next-attribute="other value" /> 
    <!-- A node may have one or multiple attributes -->
</node >
<!-- Really, don't forget to include your node's end tag -->

The structure of a protocol file

In order to understand the general structure, let’s take a simple introductory example found at: protocol / biofilm.xml

Simulation

The root element of the protocol file is called “document” and only contains one child element: “simulation”. “simulation” contains several important elements that contain all the information iDyno needs to begin running a simulation. The first child element of “simulation” is “timer”. This defines a simulation’s “timestep” size, and how many of these timesteps a simulation should make before it finishes. In the absence of units, all times in iDyno protocol files are in minutes. Thus, in this simulation, iDyno will simulate 50 timesteps of 1 minute each. To be clear, that’s 1 simulated minute, in the simulated iDyno “world”, not 1 minute of computing time!

<document>
	<simulation name="biofilm" outputfolder="../results" log="NORMAL"
		comment="this is a file for testing purposes only.">
		<timer stepSize="1.0" endOfSimulation="50.0" />
...

Species library

Next up is the species library, or “speciesLib”. This contains information about the characteristics and behaviours of the species that will be modelled in the simulation. Each child element is a “species” with a name and a set of aspects that define its behaviour in the simulation. Note, “species” in iDyno does not necessarily have to be equivalent to a “species” in the biological sense, although the two do often match up. One important thing to note here is the modularity of species descriptions. For example, species 1 contains two “speciesModule” elements, telling you that is a coccoid and a producer. As a result, any agent that is species 1 will inherit all the aspects described in the species “coccoid”. This enables you to build up the definitions of species in iDynoMiCS 2 by combining sets of traits, rather than doing everything from scratch for each one. Each aspect within a species describes a characteristic of the species. Aspects such as density and morphology should be fairly self-explanatory. Another important type of aspect is “reactions”. This contains a list of reactions that an agent can carry out. Each reaction contains an expression that determines the rate of reaction (often a Monod equation) and stoichiometric components, which determine how much of the various substrates and reactants are used up or produced.

<speciesLib>
    
    <species name="MySpecies">
        <speciesModule name="coccoid" />
        <aspect name="reactions" class="InstantiableList">
            <list class="RegularReaction" nodeLabel="reaction"
                  entryClass="RegularReaction" keyClass="String" keyLabel="name">
                <reaction name="testReact" comment="biomass specific growth rate">
                    <expression value="mass * mumax * (solute1 / (solute1 + k) )">
                        <constant name="k" value="0.001" />
                        <constant name="mumax" value="1.0" />
                    </expression>
                    <stoichiometric component="mass" coefficient="1.0" />
                    <stoichiometric component="solute1" coefficient="-1.0" />
                </reaction>
            </list>
        </aspect>
    </species>

    <species name="coccoid">
        <aspect name="density" class="Double" value="1" />
        <aspect name="#isLocated" class="Boolean" value="true" />
        <aspect name="surfaces"	class="AgentSurfaces"/>
        <aspect name="morphology" class="String" value="coccoid" />
        <aspect name="volume" class="SimpleVolumeState" />
        <aspect name="radius" class="CoccoidRadius" />
        <aspect name="divide" class="CoccoidDivision"	/>
        <aspect name="updateBody" class="UpdateBody" />
    </species>

</speciesLib>

Compartment

The next child element within “simulation” is “compartment”. The compartment is the “stage” for our simulation, the virtual world, where our microbes live and behave. Every simulation needs at least one compartment for anything to actually happen.

This compartment contains various important child elements. “shape” describes the dimensions of the compartment. Looking at the information in “shape” you should be able to deduce whether this compartment is two- or three-dimensional. The attribute “max” tells you the length of each dimension. Any length given in iDyno without a unit is in micrometres (μm). Note also, that any mass given without units is in picograms (pg). “compartment” also contains “solutes”, in this case just one solute – “solute 1”. This tells iDyno what solutes to place in the spatial grid of concentrations within the compartment. The attribute “concentration” tells us that the initial concentration of “solute 1” in each grid cell will be 0.2. Note, that this is only the initial state, and that this concentration will change as the simulation progresses. There’s also an empty “reactions” element which hints at the fact the environmental reactions can take place in iDyno without the need for agents to carry them out. These could represent things like the natural degradation of an unstable solute.

<compartment name="MyCompartment">
    <shape class="Rectangle">
        <dimension name="X" isCyclic="true" targetResolution="1.0" max="40.0"/>
        <dimension name="Y" isCyclic="false" targetResolution="1.0" max="40.0"/>
    </shape>
    <solutes>
        <solute name="solute1" concentration="0.2" defaultDiffusivity="1.0" />
    </solutes>
    <reactions>
    </reactions>
...

Agents

Now we come to the all-important agents. These agents represent the microbial cells, epithelial cells, mucus or EPS particles and other objects in iDyno. The element “agents” is the Agent Container, and its direct child elements are the actual agents. Again, agents have aspects just like species do, and each agent has a “species” aspect which refers back to the species we defined in the species library. An agent’s other aspects can actually override aspects of the same name in the species definition. Here we can see that the agents also contain a “spawn” element, which essentially creates copies of the agent and distributes them through an area defined by the “domain” attribute. Please note, this is a slightly outdated way of spawning large numbers of agents. We prefer and encourage using the newer “spawn” elements that you can see in more recent protocols, like the “benchmark_3” protocols, which utilise a “templateAgent”.

Process managers

Finally, let’s take a quick look at the last child element of the compartment, “processManagers”. This contains a set of process managers – classes that run regular recurring processes that we want to simulate. An example of a ProcessManager is AgentRelaxation, this class manages the mechanical interactions between agents and their environment. If you want to have a look at how a process manager works, their Java classes are all contained in the folder iDynoMiCS-2 > src > processManager > library.