Skip to content

simulation.definition

The definition of a simulation: what is simulated, with units.

A Simulation is the interval of a simulation, the changes applied to the model before it is initialized (preinit_changes), the changes at times (changes, a list of Change), an optional pre-equilibration (SteadyState) and the output. It is compiled against a model into a sbmlsim.simulator.plan.Plan, which is what the simulator runs. The semantics are the ones of PEtab v2:

  1. The preinit_changes are applied to the model before its initial assignments are evaluated, so an initial assignment which depends on a changed parameter follows it.
  2. The model is initialized at start.
  3. The values of the changes at a time are evaluated with the state at that time and then assigned at once. A change at start is applied after the initialization.

A value is a Quantity, a number in the unit of its target in the model, or a formula: a string of the math of PEtab over the symbols of the model, in the units of the model. S is the amount of a species and [S] its concentration, as in the selections of roadrunner.

A time is a number in the time_unit of the simulation, in the time unit of the model if the simulation has none, or a Quantity.

Change dataclass 

Change(times, values)

Changes of the model at one or several times.

A change at several times is the same change at each of them, e.g. the doses of a multiple dosing:

Change([0, 24, 48], {"PODOSE_hctz": Q(10, "mg")})

Attributes:

Name Type Description
times tuple[Time, ...]

the times, numbers in the time_unit of the simulation or quantities.
values dict[str, Value]

target -> value, see the module.

Create a change, see the class.

Raises:

Type Description
ValueError

if there are no values or no times.

to_dict 

to_dict()

Convert to a dictionary of JSON types.

from_dict classmethod 

from_dict(d)

Create a change from its dictionary, see to_dict.

SteadyState dataclass 

SteadyState(
    preinit_changes=dict(),
    absolute_tolerance=1e-08,
    relative_tolerance=1e-06,
    max_time=100000000.0,
)

A pre-equilibration before the start of a simulation.

The model is initialized once, with the preinit_changes of the simulation and of the steady state together, and integrated until the rates of change of every state are within the tolerances, |dx/dt| <= absolute_tolerance + relative_tolerance * |x|. The state at steady state is the state the simulation starts from at its start.

Attributes:

Name Type Description
preinit_changes dict[str, Value]

changes before the initialization, e.g. the conditions of a pre-equilibration of PEtab.
absolute_tolerance float

absolute tolerance of the rates of change.
relative_tolerance float

relative tolerance of the rates of change.
max_time float

the longest pre-equilibration in the time unit of the model; a simulation which does not reach the steady state by then fails.

to_dict 

to_dict()

Convert to a dictionary of JSON types.

from_dict classmethod 

from_dict(d)

Create a steady state from its dictionary, see to_dict.

Simulation 

Simulation(
    *,
    end,
    start=0.0,
    time_unit=None,
    preinit_changes=None,
    changes=None,
    presimulation=None,
    times=None,
    steps=None,
    time_shift=0.0,
)

A simulation, see the module.

Attributes:

Name Type Description
time_unit str | None

unit of the times given as numbers, the time unit of the model if None.
start Time

start of the simulation, negative times are allowed.
end Time

end of the simulation.
preinit_changes dict[str, Value]

changes before the initialization of the model.
changes list[Change]

changes at times in [start, end].
presimulation SteadyState | None

a pre-equilibration before start.
times tuple[Time, ...] | None

exact output times, None for the output of the integrator.
steps int | None

an equidistant output of steps + 1 points, excludes times.
time_shift Time

added to the time of the result. A correct start is the better way to place a simulation in time.

Create a simulation, see the module and the attributes.

Raises:

Type Description
ValueError

if start >= end, if both times and steps are given, if steps < 1, if a pre-initialization change is a formula, or if a target is a pre-initialization change of the simulation and of the presimulation.

targets 

targets()

Get every target the simulation sets, before and after initialization.

with_values 

with_values(values)

Get a copy of the simulation with other values of targets.

A value replaces the value of its target wherever the simulation sets it, i.e. in the pre-initialization changes, in those of the presimulation and in every change, and is added to the pre-initialization changes of a target which the simulation does not set. This defines the semantics which Plan.with_values applies to a compiled simulation, for the points of a scan and the parameters of a fit.

Parameters:

Name Type Description Default
values Mapping[str, float | Quantity]

target -> value.

 required

Returns:

Type Description
Simulation

The new simulation, this one is not changed.

with_preinit_defaults 

with_preinit_defaults(values)

Get a copy of the simulation with default pre-initialization changes.

A default applies unless the simulation sets its target before the initialization itself, in its own preinit_changes or in those of its presimulation; a Change of the target at a time does not replace it. This is how the changes of a model reach its simulations.

Parameters:

Name Type Description Default
values Mapping[str, float | Quantity]

target -> value.

 required

Returns:

Type Description
Simulation

The new simulation, this one is not changed.

to_dict 

to_dict()

Convert to a dictionary of JSON types.

from_dict classmethod 

from_dict(d)

Create a simulation from its dictionary, see to_dict.

to_json 

to_json(path: None = None) -> str

to_json(path: Path) -> None

to_json(path=None)

Convert the definition to JSON.

Parameters:

Name Type Description Default
path Path | None

file to write the JSON to, the JSON is returned without one.

 None

Returns:

Type Description
str | None

The JSON without a path, None with a path.

from_json staticmethod 

from_json(json_info)

Read a simulation from JSON, a path or the JSON itself.