Skip to content

simulator.executor_core

The executor of the engine core runs a plan on a model of the engine core.

A plan is one request of the contract simulation/1 (request_of) which one call of the engine simulates: the engine initializes the model with the values of the request, reaches the steady state of a presimulation, integrates in absolute time from the start in the segments between the changes, fires the events of the model and answers with the table of the selections, see sbmlsim.model.model_core and the documentation of sbmlsim-core. The executor therefore holds no loop over the segments and no semantics of its own, unlike the executors of COPASI and AMICI; the table becomes a TimecourseResult with output_columns and output_time of sbmlsim.simulator.executor, which every executor shares, so the column time, a later column time and a model with an entity named time are the ones of roadrunner.

The engine has the semantics of the executor of roadrunner, see sbmlsim.simulator.executor: the values before the initialization, which the initial assignments see, the pre-equilibration of a steady state from the time 0 whatever the start, the changes of PEtab v2 (the values of a change set at once, a compartment which keeps the concentrations of its species, the events a change triggers fired with it) and the output of the steps of the integrator or of the given times, with two rows at the time of a change after the start, the state before the change and the state after it.

A simulation which fails raises the error of its cause and not one of the bindings (_failed): a simulation the engine does not support is an UnsupportedModelError, which a run raises for the whole scan, a presimulation which reaches no steady state a SteadyStateError, and every other failure of the engine a RuntimeError with its message, so a point of a scan is flagged and an evaluation of a fit is infinite as with the other engines. A scan does not run its points through execute but hands the requests of a chunk to the engine as one batch, which answers with a PointError instead of raising (point_error, the same mapping of the errors), see sbmlsim.simulator.worker._run_chunk_core.

The known differences to the executor of roadrunner, the first five of which the engine documents:

  1. A change which sets a state exactly to the threshold of a strict comparison of a trigger fires its event right after the change, as the executors of COPASI and AMICI do; the CVODE of roadrunner ignores a root which is 0 at the start of a segment.
  2. A change may set the variable of an assignment rule which has no math: the engine ignores such a rule, as roadrunner does. A plan never carries such a change, since ModelSymbols.kind refuses the variable of an assignment rule as a target, so only a request built by hand reaches it.
  3. A change of an entity named time sets that entity, where the executor of roadrunner sets the clock of roadrunner.
  4. Events which accumulate end the simulation with an error of the integration (CV_TOO_MUCH_WORK), e.g. the bouncing ball at its accumulation point, which roadrunner falls through and goes on from: the executions of the events within the relative tolerance of the last root share the budget of maximum_num_steps steps towards one output time.
  5. The roots of a condition which chatters share that budget as well, so a model which roadrunner finishes after millions of steps may end with CV_TOO_MUCH_WORK here.
  6. A steady state after the end of a simulation, the output at the time inf of Plan.steady_state_output, is no part of the contract: the steady_state of a request is the pre-equilibration before the start alone, so such a plan cannot be expressed as one request and check_supported refuses it rather than leaving its last row out.
  7. A value of a request is a number, so a value which a plan sets by a formula is folded where the executor evaluates the formula without the model and refused otherwise (check_supported): a formula of the time at a change, whose time the plan carries, and a formula of a parameter before the initialization whose symbols are the values of the model as loaded or the numbers the same pre-initialization sets, see _preinit_value. The model of the engine is stateless, so the executor cannot set the values of a pre-initialization on it and read what a formula reads, as the executor of roadrunner does. Only a formula of a parameter is folded: the size of a compartment and the amount or the concentration of a species are set with the bookkeeping of the volumes and the amounts of the initialization, which the engine does otherwise, see the next difference; the day the engine holds the concentrations of a pre-initialization across the initialization, a formula of a compartment and of a species can be folded as well.
  8. The engine converts the concentration of a species a pre-initialization sets into an amount with the volume its compartment has at the moment of the assignment, where every other executor holds the concentration across the initialization and converts it with the size the compartment has when the model is initialized (PEtab v2, a compartment keeps the concentrations of the species in it). The two differ wherever the same pre-initialization changes that size, whether it sets the compartment itself or a symbol its size follows by an initial assignment: {"[A]": 5.0, "C": 3.0} of the probe model, whose C is 2 as loaded, is A = 15 in roadrunner and A = 10 in the engine, and on a model whose compartment is c = V*f the pre-initialization {"[A]": 5.0, "f": 3.0} is A = 30 against A = 10 (measured). The engine applies the values of a request one after the other, so the direct pair comes out right in the other order, {"C": 3.0, "[A]": 5.0}, which is a symptom of that one rule and no second difference. check_supported refuses a pre-initialization which sets the concentration of a species and changes the size of its compartment (_check_concentrations) rather than simulate a state neither engine would answer for, and the static bundle of the panels of a model, whose recipe the engine runs in the browser without a plan at all, shares that refusal (concentration_problem, the one place the rule lives, see sbmlsim.serve.export). Measured and not refused, since the engines agree on them: an amount of such a compartment, the amount of a substance species among them, a pre-initialization which changes the size of a compartment without setting a species in it, whose concentrations the engine carries across the initialization itself, and the values of a change, which the engine applies at once.
  9. The engine integrates with the absolute tolerance of every state of roadrunner (CoreSBMLModel.request_settings), so it needs no factor of one tolerance as COPASI and AMICI do, but its own build of CVODE chooses its own steps and its own evaluation of the model as loaded can differ from roadrunner's by a unit in the last place, e.g. the volume of a compartment of an assignment rule of many terms, which scales the tolerance of a concentration species in it (two of the 28 states of the HCTZ model): a result is not roadrunner's bitwise and the error of the engine is not bounded by roadrunner's. Measured as the largest error of a variable relative to its largest value, against roadrunner at the relative tolerance 1e-12 and the absolute 1e-16, on the scan of three doses of the HCTZ model of tests.simulator.test_simulator_engines: at the defaults of Simulator the error of the engine is 1.0003 of roadrunner's on that model and 0.98 and 1.03 of it on the two other packaged models which have an error at all (the error of roadrunner is exactly 0 on the demo and on the midazolam model, where the ratio is undefined and not a percentage), and at the relative tolerance 1e-8 and the absolute 1e-10 of the same scan it is 1.237 of it. ACCURACY_MARGIN of that module is therefore no bound of the agreement of the two integrators but a check of the class of the error: a core which does not receive the tolerance vector of roadrunner is wrong by orders of magnitude, while the step selection of two builds of CVODE moves the error by a few percent at equal tolerances.

execute

execute(plan, model, selections)

Run a plan on a model of the engine core.

The contract of sbmlsim.simulator.executor.execute: 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, see the module.

Parameters:

Name Type Description Default
plan Plan

the plan, compiled against the model.

required
model CoreSBMLModel

the 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
UnsupportedModelError

for a plan or a simulation the engine does not support, see check_supported, which request_of calls.

SteadyStateError

if a presimulation does not reach a steady state.

RuntimeError

if the engine fails to simulate the request, with its message, e.g. an integration which fails, see _failed.

request_of

request_of(plan, model, selections, settings=None)

Get the request of the contract simulation/1 of a plan.

The request carries the whole simulation, since the engine holds no state of its own: the interval, the values before the initialization, the steady state before the start, the changes at their absolute times, the output and the settings of the integrator. It has no seed, so the engine orders simultaneous events of equal priority with the default of the contract; a plan has none.

A value of the request is a number, so every formula of the plan is folded here and a plan which one request cannot carry is refused (check_supported, which every request goes through): a request of the engine is always the one of a plan it simulates as roadrunner.

Parameters:

Name Type Description Default
plan Plan

the plan, compiled against the model.

required
model CoreSBMLModel

the model, which gives the settings of the integrator and the values a formula before the initialization reads.

required
selections Sequence[str]

the columns of the result, time is added as the first column if it is missing.

required
settings dict[str, object] | None

the settings of the request, model.request_settings() by default, which computes the absolute tolerance of every state once per call: a caller which builds the requests of the points of a scan computes them once and passes them here.

None

Returns:

Type Description
dict[str, Any]

The request, a dictionary of the fields of the contract.

Raises:

Type Description
UnsupportedModelError

for a plan the engine does not simulate as roadrunner, see check_supported.

check_supported

check_supported(plan, model)

Refuse a plan the engine does not simulate as roadrunner.

request_of checks every plan, and Simulator.run the plan of the first point of every simulation and model before it runs a point, see sbmlsim.simulator.engines.check_plan, so a plan the engine refuses fails the whole scan whatever on_error says, which is what a plan one request cannot carry deserves: it fails every point of the scan alike.

The steady state after the end of a simulation is no field of the contract, a value of a request is a number, so a formula the executor cannot fold is refused, and the engine converts the concentration of a species with the volume its compartment has at the moment of the assignment, so a pre-initialization which sets a concentration and changes the size of its compartment is refused, see the module, _preinit_value and _check_concentrations.

Parameters:

Name Type Description Default
plan Plan

the plan, compiled against the model, with the values of a point.

required
model CoreSBMLModel

the model, which gives the values a formula before the initialization reads.

required

Raises:

Type Description
UnsupportedModelError

a NotImplementedError, for a plan with a steady state after the end of its simulation, for a formula the executor cannot fold into a number and for a pre-initialization of a concentration whose volume it changes.

concentration_problem

concentration_problem(targets, symbols, where)

Tell why the engine gets a pre-initialization of a concentration wrong.

The one place the rule of difference 8 of the module lives, so that the executor and the static bundle of the panels of a model, whose recipe the engine runs in the browser without a plan at all (sbmlsim.serve.export), refuse the same pre-initializations with the same words. It goes, with both of its callers, the day sbmlsim-core#7 is released: the engine then holds the concentration across the initialization itself and nothing is left to refuse. Two texts go with them, which grep sbmlsim-core#7 finds as well: the refusals of the engine core in docs/simulation.md and the clause of the engines in CLAUDE.md.

The engine converts the concentration of a species a pre-initialization sets into an amount with the volume its compartment has at the moment of the assignment, where every other executor holds the concentration across the initialization and converts it with the size the compartment has when the model is initialized (PEtab v2, a compartment keeps the concentrations of the species in it, RoadrunnerSBMLModel.initialize). The two differ wherever the same pre-initialization changes that size: {"[A]": 5.0, "C": 3.0} of the probe model, whose C is 2 as loaded, is A = 15 in roadrunner and A = 10 in the engine, and so is {"[A]": 5.0, "f": 3.0} of a model whose compartment is c = V*f, where no value of the pre-initialization is the compartment at all. The engine applies the values of a request one after the other, so the direct pair comes out right in the other order, which is a symptom of that one rule.

Every other pre-initialization of such a compartment is simulated, since the engines agree on them (measured, see the module): an amount, the amount of a substance species among them, which is set as it is whenever the volume settles, and a change of the size alone, whose concentrations the engine carries across the initialization itself.

Parameters:

Name Type Description Default
targets Iterable[str]

the targets of the pre-initialization, in the order a problem reports them: [S] for the concentration of a species and the id of the entity for every other value. A target the model has no species or compartment of is no problem of this rule.

required
symbols ModelSymbols

the symbols of the model, which give the compartment of a species and the symbols its size depends on.

required
where str

the model and whatever else names the pre-initialization, which the problem names after the species, e.g. of the model 'hctz' or of the panel 'patient_plasma' of the model 'hctz' in its variant 'default'.

required

Returns:

Type Description
str | None

The problem of the first concentration whose volume the

str | None

pre-initialization changes, None for a pre-initialization the

str | None

engine simulates as every other executor does.

point_error

point_error(point, model)

Get the error of a failed point of a batch as the error of an executor.

A batch of the engine answers with a PointError instead of raising, so that one point never ends the batch, see sbmlsim.simulator.worker._run_chunk_core: its kind is the error a single simulation would raise and its message is the message of that error, so a point of a batch and a point of its own fail alike, see _failed, which this shares the mapping with.

Parameters:

Name Type Description Default
point Any

the PointError of the bindings, with its kind, message and the flag of an integration which failed.

required
model CoreSBMLModel

the model which was simulated.

required

Returns:

Type Description
Exception

The error to raise or to record as the failure of the point.