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:
- 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.
- 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.kindrefuses the variable of an assignment rule as a target, so only a request built by hand reaches it. - A change of an entity named
timesets that entity, where the executor of roadrunner sets the clock of roadrunner. - 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 ofmaximum_num_stepssteps towards one output time. - 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_WORKhere. - A steady state after the end of a simulation, the output at the time
infofPlan.steady_state_output, is no part of the contract: thesteady_stateof a request is the pre-equilibration before the start alone, so such a plan cannot be expressed as one request andcheck_supportedrefuses it rather than leaving its last row out. - 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. - 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, whoseCis 2 as loaded, isA = 15in roadrunner andA = 10in the engine, and on a model whose compartment isc = V*fthe pre-initialization{"[A]": 5.0, "f": 3.0}isA = 30againstA = 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_supportedrefuses 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, seesbmlsim.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. - 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 oftests.simulator.test_simulator_engines: at the defaults ofSimulatorthe 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_MARGINof 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
¶
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, |
required |
Returns:
| Type | Description |
|---|---|
TimecourseResult
|
The result, with the time shifted by |
Raises:
| Type | Description |
|---|---|
UnsupportedModelError
|
for a plan or a simulation the engine does not
support, see |
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 |
request_of
¶
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, |
required |
settings
|
dict[str, object] | None
|
the settings of the request, |
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
¶
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 |
concentration_problem
¶
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: |
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. |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
The problem of the first concentration whose volume the |
str | None
|
pre-initialization changes, |
str | None
|
engine simulates as every other executor does. |
point_error
¶
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 |
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. |