simulator.executor¶

The executor runs a plan on roadrunner.

The semantics are the ones of PEtab v2:

The model is initialized with the pre-initialization values, see RoadrunnerSBMLModel.initialize: the initial assignments follow a changed parameter, and nothing of an earlier simulation is left.
A presimulation integrates until the rates of change vanish.
The interval is split at the times of the events. At the start of a segment the events of its time are applied: every value is evaluated first, with the state at that time, then every target is set; a compartment keeps the concentration of the concentration species in it, see sbmlsim.simulator.changes.apply_changes.
After a change at a time after the start, the events whose triggers the change made true fire, which roadrunner does not see, see sbmlsim.simulator.changes.fire_events.
A segment is integrated with the output of the plan and ends in its state at its end, which the next change is applied to; for the steps of the integrator see _steps, which has an event of the model as two rows at the time of the event, the states before and after it, which the markers of the events tell, see sbmlsim.model.event_rows. A change after the start, the one at the end included, has two rows at its time in the output, the state before the change, which ends the segment before it, and the state after it, which starts the next one: the steps of the integrator at every change, an output of times at its times which are changes. A segment of a model with events stops just before its end, a unit in the last place of the larger magnitude of its start and end and at least four machine epsilons, see segment_stop and _simulate_times, so an event of the model at the time of a change fires after the change and an event at the end after the state before it. A segment too short for CVODE, a few units in the last place in absolute time, is not integrated: its state is the one at its start, and the triggers before the next change are evaluated at the time the model is at, its start, so an event of the time in it fires once, after it, see integrable. A delayed event which roadrunner keeps pending closer after the start of an integration than CVODE integrates holds the state at the start likewise, see _integrate.
An event of the model within the resolution of the time after the end is at the end, see _event_at_the_end: the steps of the integrator have it as two rows, the states before and after it, an output time at the end the state after it, as a time of a grid at an event, and it fires after a change at the end. The steady state after the end starts after it. An event within the resolution before the end is in the chain at the end, whose rows are the state after it, as at a change. An event whose trigger becomes true within the rounding of the state one unit in the last place before the end, e.g. X >= 1 of X' = 1 from 0 at the end 1, fires before it, and the end has the state after it.
A model which does not read the time (ModelSymbols.time_dependent) is integrated in local time: every segment starts at the time 0 of roadrunner and its output is shifted back, so the first step of CVODE after a change is never below the resolution of the time. A model which reads the time is integrated in absolute time.

The executor uses no pint, no deepcopy, no xarray and no pandas: it is what an evaluation of the objective of a fit runs.

SteadyStateError ¶

Bases: RuntimeError

A presimulation did not reach a steady state.

execute ¶

execute(plan, model, selections)

Run a plan on a loaded model.

The output has two rows at the time of a change after the start, the state before the change and the state after it, and the steps of the integrator have two at an event of the model at the end, see the module.

Parameters:

Name	Type	Description	Default
`plan`	`Plan`	the plan, compiled against the model.	required
`model`	`RoadrunnerSBMLModel`	the loaded model.	required
`selections`	`Sequence[str]`	the columns of the result, `time` is added as the first column if it is missing.	required

Returns:

Type	Description
`TimecourseResult`	The result, with the time shifted by `plan.time_shift`.

Raises:

Type	Description
`SteadyStateError`	if the presimulation does not reach a steady state.
`RuntimeError`	if roadrunner fails to integrate.

output_columns ¶

output_columns(selections)

Get the columns of the output of a plan, the time of the simulation first.

A model may have an entity named time as well, which a later column time is (case 01820); else a later column time is the time of the simulation again, see output_time. Every executor shares it.

Parameters:

Name	Type	Description	Default
`selections`	`Sequence[str]`	the selections of the output.	required

Returns:

Type	Description
`list[str]`	The columns, `time` added as the first one if it is not.

output_time ¶

output_time(values, columns, plan, symbols)

Give the columns of the time of an output the time of the simulation.

The first column is shifted by plan.time_shift. A later column time is a copy of it, the time of the row: an engine reads it in its own time, which is the local time of a segment or misses the shift, and the state after a change is no row of the engine. A later column time of a model with an entity named time is the value of that entity. Every executor shares it.

Parameters:

Name	Type	Description	Default
`values`	`ndarray`	the output, a column per entry of `columns`; changed in place.	required
`columns`	`Sequence[str]`	the columns, see `output_columns`.	required
`plan`	`Plan`	the plan.	required
`symbols`	`ModelSymbols`	the symbols of the model.	required

Returns:

Type	Description
`ndarray`	The output.

segment_stop ¶

segment_stop(start, end)

Get the time just before the end of a segment where its integration stops.

It is one unit in the last place of the times of the segment before its end, of the larger of the magnitudes of its start and its end in the time of roadrunner, which CVODE resolves: its rounding of the time is the machine epsilon times that magnitude. It is at least STOP, so the stop before an end at 0 is no subnormal number, at which CVODE fails, e.g. for a trigger of the time at 0, and roadrunner reports an event at the end with its rows when it integrates from the stop.

Parameters:

Name	Type	Description	Default
`start`	`float`	the start of the segment in the time of roadrunner.	required
`end`	`float`	its end in the time of roadrunner.	required

Returns:

Type	Description
`float`	The stop, a normal number before the end.

integrable ¶

integrable(start, stop)

Whether CVODE integrates from the start of a segment to its stop.

CVODE rejects an output time closer to the start than twice its rounding of the time, the machine epsilon times the larger magnitude (CV_TOO_CLOSE), and roadrunner a stop at the start: such a segment, of a few units in the last place in absolute time, e.g. between two changes a few units in the last place apart, is not integrated. Its state is the one at its start, which differs from the integrated one by the rate times its duration, and the events of the time in it fire after it, see _simulate. LSODA of COPASI has the same condition (TOUT too close to T), see sbmlsim.simulator.executor_copasi.

Parameters:

Name	Type	Description	Default
`start`	`float`	the start of the segment in the time of roadrunner.	required
`stop`	`float`	where its integration stops, see `segment_stop`.	required

Returns:

Type	Description
`bool`	Whether the segment is integrated, the condition of CVODE.

intermediate_time ¶

intermediate_time(previous, last, end)

Get a time between two output times from which the last one is exact.

An integrator integrates an output time from the one before it, to previous + (last - previous), which can round up by one unit in the last place: a last time before the end of a segment, its stop, can round to the end, where an event of the model at the time of a change fires before the change. From a time between them of the same sign within a factor of two of the last time the difference is exact, and so is the sum. Both executors share it, see _simulate_times and sbmlsim.simulator.executor_copasi.

Parameters:

Name	Type	Description	Default
`previous`	`float`	the output time before the last one.	required
`last`	`float`	the last output time.	required
`end`	`float`	the end of the segment, which the integration must not reach.	required

Returns:

Type	Description
`float \| None`	The time between, `None` if the last time is not before the end or
`float \| None`	the sum does not reach the end.

Raises:

Type	Description
`RuntimeError`	if no time between keeps the integration before the end.

steady_state ¶

steady_state(model, plan, start=0.0, exact=None)

Integrate a model until its rates of change vanish.

The model is integrated with the steps of the integrator over horizons which grow by a factor of ten, from start, until |dx/dt| <= absolute_tolerance + relative_tolerance * |x| for every state, events active. Every horizon ends in the state at its end, see _to_the_end; after an event which roadrunner kept pending and which fires after the end, the next horizon starts at the time of the model after it, so its trigger is not false again at the start of the next horizon and the event fires once. A horizon at whose end roadrunner fired an event before its time is integrated with exact output at its end, see _EventAtTheHorizon.

Parameters:

Name	Type	Description	Default
`model`	`RoadrunnerSBMLModel`	the model in the state the integration starts from, the markers of its events the last selections, see `execute`.	required
`plan`	`SteadyStatePlan`	the steady state.	required
`start`	`float`	the time the integration starts at.	`0.0`
`exact`	`set[int] \| None`	the horizons with exact output at their end, by their index.	`None`

Returns:

Type	Description
`float`	The time the steady state was reached at.

Raises:

Type	Description
`SteadyStateError`	if the steady state is not reached by `max_time`.
`_EventAtTheHorizon`	if roadrunner fired an event of the model before its time at the end of a horizon which is not in `exact`.