Perform dimensional analysis on model


The DimensionalAnalysis property specifies whether to perform dimensional analysis on the model before simulation. It is a property of the CompileOptions object. CompileOptions holds the model's compile time options and is the object property of the configset object. When DimensionalAnalysis is set to true, the SimBiology® software checks whether the physical quantities of the units involved in reactions and rules, match and are applicable.

For example, consider a reaction a + b —> c. Using mass action kinetics, the reaction rate is defined as a*b*k, where k is the rate constant of the reaction. If you specify that initial amounts of a and b are 0.01M and 0.005M respectively, then units of k are 1/(M*second). If you specify k with another equivalent unit definition, for example, 1/[(moles/liter)*second], DimensionalAnalysis checks whether the physical quantities match. If the physical quantities do not match, you see an error and the model is not simulated.

Unit conversion requires dimensional analysis. If DimensionalAnalysis is off, and you turn UnitConversion on, then DimensionalAnalysis is turned on automatically. If UnitConversion is on and you turn off DimensionalAnalysis, then UnitConversion is turned off automatically.

If you have MATLAB® function calls in your model, dimensional analysis ignores any expressions containing function calls and generates a warning.

Valid physical quantities for reaction rates are amount/time, mass/time, or concentration/time.


Applies toObject: CompileOptions (in configset object)
Data typeboolean
Data values

true or false. Default value is true.


    Note:   SimBiology allows exponentiation of any dimensionless quantity to any dimensionless power. For example, you can write the following expression if both x and a are dimensionless: (x + 3)^(a + 0.5)

    Note:   SimBiology uses unit strings including empty units in association with DimensionalAnalysis and UnitConversion features.

    • When DimensionalAnalysis and UnitConversion are both false, unit strings are not used. However, SimBiology still performs a minimum level of dimensional analysis to decide whether a reaction rate is in dimensions of amount/time or concentration/time.

    • When DimensionalAnalysis is true and UnitConversion is false, units (if not empty) must have consistent dimensions so that SimBiology can perform dimensional analysis. However, the units are not converted.

    • When UnitConversion is set to true (which requires DimensionalAnalysis to be true), SimBiology performs a dimensional analysis and converts everything to consistent units. Hence, you must specify consistent units, and no unit strings can be empty. If you have a dimensionless parameter, you must still set its unit string to dimensionless.

    Tip   If you have a custom function and UnitConversion is on, follow the recommendation below.

    • Non-dimensionalize the parameters that are passed to the function if they are not already dimensionless.

      Suppose you have a custom function defined as y = f(t) where t is the time in hour and y is the concentration of a species in mole/liter. When you use this function in your model to define a repeated assignment rule for instance, define it as: s1 = f(time/t0)*s0, where time is the simulation time, t0 is a parameter defined as 1.0 hour, s0 is a parameter defined as 1.0 mole/liter, and s1 is the concentration of a species in mole/liter. Note that time and s1 do not have to be in the same units as t0 and s0, but they must be dimensionally consistent. For example, the time and s1 units can be set to minute and picomole/liter, respectively.


This example shows how to retrieve and set DimensionalAnalysis from the default true to false in the default configuration set in a model object.

  1. Import a model.

    modelObj = sbmlimport('oscillator')

    SimBiology Model - Oscillator 
       Model Components:
         Models:            0
         Parameters:        0
         Reactions:         42
         Rules:             0
         Species:           23
  2. Retrieve the configset object of the model object.

    configsetObj = getconfigset(modelObj)
     Configuration Settings - default (active)
         SolverType:           ode15s
         StopTime:             10.000000
         AbsoluteTolerance:    1.000000e-006
         RelativeTolerance:    1.000000e-003
         StatesToLog:          all
         UnitConversion:       true
         DimensionalAnalysis:  true
  3. Retrieve the CompileOptions object.

    optionsObj = get(configsetObj,'CompileOptions')
    Compile Settings:
         UnitConversion:       true
         DimensionalAnalysis:  true
  4. Assign a value of false to DimensionalAnalysis.

     set(optionsObj,'DimensionalAnalysis', false)
Was this topic helpful?