Handling timescale

[kwabenantim]

Summary

The generated code currently tries to adjust for timescale differences. It does this with the understanding that Chaste assumes time is in hours and SBML assumes time is in seconds by default.

For example, in the code generated for the Goldbeter 1991 SRN model we have:

void Goldbeter1991OdeSystem::EvaluateYDerivatives(...)
{
  // Define state variables and reactions
  ...

  // Account for the differences in timescales
  rDY[0] *= 3600.0;
  rDY[1] *= 3600.0;
  rDY[2] *= 3600.0;
}

Running a simulation for 100s requires settings similar to:

double start_time = 0.0;
double end_time = 100.0 / 3600.0;   // 100s
double dt = 1.0 / 3600.0 / 100.0;  // 0.01s

By contrast, the Goldbeter1991OdeSystem in Chaste trunk doesn't perform the additional timescale adjustments and simply assumes time is in hours.

Which approach is better? Is there another way that is better than both?

---

EDIT:

The TysonNovak2001OdeSystem in Chaste trunk also does the timescale adjustments

    // Multiply by 60 beacuase the Tyson and Novak 2001 paper has time in minutes, not hours
    rDY[0] = dx1*60.0;
    rDY[1] = dx2*60.0;
    rDY[2] = dx3*60.0;
    rDY[3] = dx4*60.0;
    rDY[4] = dx5*60.0;
    rDY[5] = dx6*60.0;

[mirams]

Hmmmm, does SBML contain units for time like CellML does? Such that we could search for variables likely to be time (time, t, ?) and if their base SI unit is seconds, we could do an appropriate conversion automatically to Chaste cell-based units (hours). Or failing that don't suppose there is actually metadata annotating time?

[kwabenantim]

Currently the code generation does something like ( in chaste_model.py#L134 ):

if (there is a unit like
"""
  <unitDefinition name="hours" id="time">
    <listOfUnits>
      <unit kind="second" multiplier="3600"/>
    </listOfUnits>
  </unitDefinition>
""")
then
{
  set the timescale appropriately
}

Also, from SBML Level 3 (the version released in 2010) there's also a model.timeUnit according to https://sbml.org/software/libsbml/5.18.0/docs/formatted/c-api/class_model__t.html

The "timeUnits" attribute
The "timeUnits" attribute on SBML Level 3's Model_t object is used to specify the unit in which time is measured in the model. This attribute on Model_t is the only way to specify a unit for time in a model.

That will probably be useful for models using Level 3, although it looks like a quite a number of recent models on BioModels still use Level 2.

[kwabenantim]

The code generation should probably do something like:

if (there is a unit like
"""
      <unitDefinition id="MWDERIVEDUNIT_nanomole__meter___3_hour" name="nanomole/(meter^3*hour)">
        <listOfUnits>
          <unit kind="metre" exponent="-3"/>
          <unit kind="mole" exponent="1"/>
          <unit kind="second" exponent="-1"/>
          <unit kind="dimensionless" multiplier="2.77777777777778e-13"/>
        </listOfUnits>
      </unitDefinition>
""")
then
{
  apply the multiplier to everything that uses the unit.
}

[kwabenantim]

Probably also a good idea to add a CLI option for setting the default model timescale.

[kwabenantim]

As discussed in #9, the timescale option could look like:

--timescale=TIMESCALE
   Possible options: ms | s | m | h