Nested Simulation Experiments

A couple of days ago, I posted a proposal for a Nested Simulation Experiment for SED-ML. There I proposed that instead of defining a new Simulation class for each experiment you’d like to run, it would be better for implementers and modelers alike to be able to compose simulation experiments out of primitives. That is instead of defining:

• a TimeCourse Simulation experiment like this:
  
  <timeCourse id="s1" name="time course definition" algorithm="KiSAO:0000019">
  <uniformRange start="0" end="100" numberOfPoints="10" />
  </timeCourse>
  
• and next like this:
  
  <timeCourse id="s1" name="time course definition" algorithm="KiSAO:0000019">
  <vectorRange>
  <value> 1 </value>
  <value> 4 </value>
  <value> 10 </value>
  <value> 23 </value>
  <value> 42 </value>
  </vectorRange>
  </timeCourse>

one could compose these same experiments with primitives. (Just as an aside, note that in the cases above a simulator supporting the simulation experiment would have to implement a different set of operations).

The Primitives

I would envision three primitives:

• OneStep: this calculates one further output step for the model from its current state. Note that this does NOT have to mean one integration step. The simulator is allowed to take as many steps as needed, all that has to be fulfilled with this simulation class, is that, at the end, the desired output time is reached.
• SteadyState: This brings the model from its current state to a steady state. This simulation class will also just provide one output row for attached data generators, the state of the model at steady state.
• SetValue: This is not a simulation class, but rather a convenience function, to change a model variable/parameter. In this way it is akin to ChangeMath / ChangeAttribute / ChangeXML we would have to discuss the actual syntax of it.

These primitives then are used in a nested simulation experiment to describe virtually any simulation experiment. Through the nested class construct. This construct allows to refer to:

• A task object, which defines the model and simulation experiment to be called repeatedly,
• A range object, which defines how often the simulation task above is to be called,
• A SetValue construct describing how model variables are to be changed. Note:that the SetValue construct will have to be able to refer to the ranges current value.

Additionally, flags would indicate, whether the model is supposed to be reset after each run or not.

Examples

So far the proposal, so how would this look in an example. Lets go through each one and make up some examples as we go along.

• OneStep: This is a simulation class, causing the model time variable to be adapted from the current time with a given step (that determines where the desired output point is):
  
  <listOfSimulations>
  <oneStep id="s1" algorithm="KiSAO:0000019" step="0.1"/>
  </listOfSimulations>
  
  when used in a task, this simulation task simulates the model from 0 to 0.1. The data generators are supposed to be calculated to yield the desired outputs for time point 0.1.
  
• SteadyState: This is another simulation class, so we would define it as such. Unfortunately KISAO does not currently describe any steady state solvers and instead mostly integrators. So suppose in the following that:
  
  KISAO:0000099 = steady state solver (it would probably somewhere below KISAO:0000018)
  
  <listOfSimulations>
  <steadyState id="s2" algorithm="KiSAO:0000099" />
  </listOfSimulations>
  
  when used in a task, this simulation task brings the model to steady state. Once finished the data generators are supposed to be calculated to yield the desired output points for the model variables at steady state.
  
• NestedSimulation: So how would this now look in a nested simulation experiment:
  

<listOfSimulations>
    <nestedSimulation id="s3" algorithm="KiSAO:0000019"
                         resetModel="false" originalTask="task1">
    <vectorRange>
         <value> 1 </value>
        <value> 4 </value>
        <value> 10 </value>
    </vectorRange>
    <setValue target="/sbml/model/listOfParameters/parameter[@id='w']">
     <listOfVariables>
         <variable id="current" name="current range value" target="#current" />
     <listOfVariables/>
     <math>
         <ci>current</ci>
     </math>
    </setValue>
   </nestedSimulation>
</listOfSimulations>

The nested simulation above, would carry out task1 3 times. Each time the value of a model parameter ‘w’ is varied by applying one of the three values.  If task1 specifies a steady state primitive, then this snippet produces the steady state values for w=1, w=4 and w=10.

Or we could have used a uniform range to sweep the parameter. Or a functional range, to vary the parameter in logScale for example.

If task1 would refer to a uniformTimeCourse Simulation then this would actually perform a simulation, where a parameter is changed in steps. After each time we would see how the model reacts to this discrete parameter change.

Note that you could even define a uniform time course simulation using this approach. Here task1 refers to a ‘oneStep’ simulation task. We would just vary the models time each time:

<listOfSimulations>
    <nestedSimulation id="s3" algorithm="KiSAO:0000019"
                         resetModel="false" originalTask="task1">
    <uniformRange start="0" end="100" numberOfPoints="10" />
    <setValue target="#time">
     <listOfVariables>
         <variable id="current" name="current range value" target="#current" />
     <listOfVariables/>
     <math>
         <ci>current</ci>
     </math>
    </setValue>
   </nestedSimulation>
</listOfSimulations>

You could even think about nesting the nestedSimulation experiments in order to for example perform 2D parameter scans or what have you.

Conclusions

Defining simulation experiments through these primitives will open up SED-ML and make it really useful. These primitives are easy to implement. In fact they are already implemented in available simulators. They are what is needed to implement the proposed Range construct anyway.

So let us not be shackled by having to each time define a new simulation class. The nested approach here will be what is needed to define most simulation experiments. By adding new primitives later on it can be easily extended.

I’m perfectly happy to open it up further. What one could envision would be multiple <setValue> elements to change multiple parameters. or even multiple ranges, though then each would have to have an id, to be used in the SetValue constructs. But I’m sure it could be sorted out.