simulator.plan¶

A simulation compiled against a model: the plan the executor runs.

compile_simulation does everything which does not depend on the values a scan or a fit sets: it converts every time into the time unit of the model and every quantity into the unit of its target, resolves the kind of every target, merges the changes into one event per time, checks every formula and builds the output times. A Plan holds numbers, strings and the symbols of the model, no quantity and no libsbml object, so it is pickled for the workers of a fit and an evaluation never touches pint.

A formula stays a string in the plan; the executor compiles it once per process, see sbmlsim.simulator.formula.

TIME_RTOL `module-attribute` ¶

TIME_RTOL = 1e-09

Output times closer than TIME_RTOL times the time scale are one output time.

Assignment `dataclass` ¶

Assignment(target, kind, value=None, formula=None)

The value of one target, a number in the unit of the model or a formula.

Attributes:

Name	Type	Description
`target`	`str`	the target, `S`, `[S]` or the id of a parameter or compartment.
`kind`	`TargetKind`	the kind of the target.
`value`	`float \| None`	the value, `None` for a formula.
`formula`	`str \| None`	the formula, `None` for a value.

PlanEvent `dataclass` ¶

PlanEvent(time, assignments)

The assignments at one time.

Attributes:

Name	Type	Description
`time`	`float`	the time in the time unit of the model.
`assignments`	`tuple[Assignment, ...]`	the assignments, evaluated together and then applied.

OutputMode ¶

Bases: StrEnum

The output of a simulation.

SteadyStatePlan `dataclass` ¶

SteadyStatePlan(
    preinit,
    absolute_tolerance,
    relative_tolerance,
    max_time,
)

A pre-equilibration of a plan, see sbmlsim.simulation.SteadyState.

Attributes:

Name	Type	Description
`preinit`	`tuple[Assignment, ...]`	the pre-initialization assignments of the steady state.
`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.

Plan `dataclass` ¶

Plan(
    start,
    end,
    preinit,
    events,
    steady_state,
    output,
    times,
    time_shift,
    symbols,
    steady_state_output=None,
    units=None,
)

A simulation compiled against a model, see the module.

Attributes:

Name	Type	Description
`start`	`float`	start of the simulation, in the time unit of the model.
`end`	`float`	end of the simulation.
`preinit`	`tuple[Assignment, ...]`	the assignments before the initialization, values only.
`events`	`tuple[PlanEvent, ...]`	the assignments at times in `[start, end]`, sorted by time.
`steady_state`	`SteadyStatePlan \| None`	the pre-equilibration, `None` without one.
`output`	`OutputMode`	the output of the simulation.
`times`	`tuple[float, ...]`	the output times of `OutputMode.TIMES`, empty otherwise.
`steady_state_output`	`SteadyStatePlan \| None`	the steady state after the end of the simulation, the output at the time `inf`, `None` without one.
`time_shift`	`float`	added to the time of the result.
`symbols`	`ModelSymbols`	the symbols of the model, which resolve a target `with_values` adds.

change_times `property` ¶

change_times

Get the times of the changes after the start, sorted.

A change at the start is the initial condition of the simulation and no change of its output; a change at the end is one.

output_change_times `property` ¶

output_change_times

Get the times of the changes after the start in the time of the output.

The change_times shifted by time_shift, the times of the states before and after a change in the result of the executor.

check_model ¶

check_model(symbols, uinfo)

Reject execution against different symbols or numerical units.

A manually constructed plan without a unit contract still checks its symbols. Plans returned by compilation always check both.

Parameters:

Name	Type	Description	Default
`symbols`	`ModelSymbols`	the symbols of the model which runs the plan.	required
`uinfo`	`UnitsInformation`	the units of the model which runs the plan.	required

Raises:

Type	Description
`ValueError`	if the plan was compiled for other symbols or units.

at_change ¶

at_change(times)

Get the change after the start which every time is at.

A time is at the time of a change if they differ by at most the resolution of the time (time_tolerance), so a time which differs from it by floating point noise, on either side, is at the change.

Parameters:

Name	Type	Description	Default
`times`	`Sequence[float] \| ndarray`	times in the time of the plan, i.e. without `time_shift`.	required

Returns:

Type	Description
`ndarray`	For every time the index of its change in `change_times`, `-1`
`ndarray`	for a time which is at no change.

with_values ¶

with_values(values, at=None)

Get the plan with other values of targets.

A value replaces the assignment of its target wherever the plan has one, i.e. before the initialization, in the steady state and at every time, and is added to the assignments before the initialization of a target which the plan does not set. This is the rule of Simulation.with_values on numbers in the units of the model, which is what a fit and a scan set.

With at the values are a change at that time instead: they join the event of that time, where they replace the assignment of a target the event already has, or are a new event. This is a dimension of a scan with at.

Parameters:

Name	Type	Description	Default
`values`	`Mapping[str, float]`	target -> value in the unit of the target in the model.	required
`at`	`float \| None`	the time of the change in the time unit of the model, `None` for the rule above.	`None`

Returns:

Type	Description
`Plan`	The new plan, this one is not changed.

Raises:

Type	Description
`ValueError`	if a target is not a target of the model, or `at` is outside of the simulation.

output_times ¶

output_times(changes=())

Get the times of the result of the plan.

An output time at a change after the start appears twice, the state before the change and the state after it.

Parameters:

Name	Type	Description	Default
`changes`	`Iterable[float]`	the times of further changes, e.g. of a dimension of a scan with `at`, in the time of the plan.	`()`

Returns:

Type	Description
`tuple[float, ...] \| None`	The output times shifted by `time_shift`, with `inf` last for the
`tuple[float, ...] \| None`	steady state after the end; `None` for the steps of the
`tuple[float, ...] \| None`	integrator, which differ between the values of a scan.

model_units ¶

model_units(uinfo)

Get the base unit and the scale of the unit of every entity of a model.

The contract keeps no registry, so a plan which carries it pickles.

Parameters:

Name	Type	Description	Default
`uinfo`	`UnitsInformation`	the units of the model.	required

Returns:

Type	Description
`UnitsContract`	The units of the model, see `UnitsContract`.

time_tolerance ¶

time_tolerance(start, end)

Get the resolution of the time of a simulation.

Two times which differ by less are one time: output times are merged (merge_times) and a time is at the time of a change (Plan.at_change).

Parameters:

Name	Type	Description	Default
`start`	`float`	The start of the simulation in the time of the plan.	required
`end`	`float`	The end of the simulation in the time of the plan.	required

Returns:

Type	Description
`float`	`TIME_RTOL * max(abs(start), abs(end), end - start)`.

merge_times ¶

merge_times(times, start, end)

Merge output times which differ by less than the resolution of the time.

Two times which differ by floating point noise (digitized data, a conversion of the time unit) are one output time. The tolerance is time_tolerance in the time of the plan, and a cluster of times whose consecutive distances are within it becomes its smallest time inside [start, end], else its smallest time. A time at inf stays a time of its own.

Parameters:

Name	Type	Description	Default
`times`	`Sequence[float] \| ndarray`	The output times in the time of the plan.	required
`start`	`float`	The start of the simulation in the time of the plan.	required
`end`	`float`	The end of the simulation in the time of the plan.	required

Returns:

Type	Description
`ndarray`	The merged, sorted output times and, for every given time, the index of
`ndarray`	its merged time.

compile_simulation ¶

compile_simulation(simulation, symbols, uinfo)

Compile a simulation against a model.

Parameters:

Name	Type	Description	Default
`simulation`	`Simulation`	the simulation.	required
`symbols`	`ModelSymbols`	the symbols of the model.	required
`uinfo`	`UnitsInformation`	the units of the model.	required

Returns:

Type	Description
`Plan`	The plan of the simulation, see the module.

Raises:

Type	Description
`ValueError`	if a time or a value cannot be converted, if a target is not a target of the model, if a change or an output time is outside of the interval of the simulation, or if two values of one target are set at one time.

target_values ¶

target_values(target, values, symbols, uinfo)

Get values of a target as numbers in the unit of the target in the model.

Parameters:

Name	Type	Description	Default
`target`	`str`	the target, `S`, `[S]` or the id of a parameter or a compartment.	required
`values`	`Any`	a quantity, or numbers in the unit of the target in the model.	required
`symbols`	`ModelSymbols`	the symbols of the model.	required
`uinfo`	`UnitsInformation`	the units of the model.	required

Returns:

Type	Description
`ndarray`	The values as floats.

Raises:

Type	Description
`ValueError`	if the target is not a target of the model, or a quantity cannot be converted into the unit of the target.

model_time ¶

model_time(simulation, time, symbols, uinfo)

Get a time of a simulation in the time unit of the model.

Parameters:

Name	Type	Description	Default
`simulation`	`Simulation`	the simulation, a number is in its `time_unit`.	required
`time`	`Time`	a number or a quantity.	required
`symbols`	`ModelSymbols`	the symbols of the model.	required
`uinfo`	`UnitsInformation`	the units of the model.	required

Returns:

Type	Description
`float`	The time in the time unit of the model.

Raises:

Type	Description
`ValueError`	if the time cannot be converted.

preinit_targets ¶

preinit_targets(plan)

Get the pre-initialization assignments of a plan and of its steady state.

simulator.plan¶

TIME_RTOL module-attribute ¶

Assignment dataclass ¶

PlanEvent dataclass ¶

OutputMode ¶

SteadyStatePlan dataclass ¶

Plan dataclass ¶

change_times property ¶

output_change_times property ¶

check_model ¶

at_change ¶

with_values ¶

output_times ¶

model_units ¶

time_tolerance ¶

merge_times ¶

compile_simulation ¶

target_values ¶

model_time ¶

preinit_targets ¶

TIME_RTOL `module-attribute` ¶

Assignment `dataclass` ¶

PlanEvent `dataclass` ¶

SteadyStatePlan `dataclass` ¶

Plan `dataclass` ¶

change_times `property` ¶

output_change_times `property` ¶