model.model_roadrunner¶

RoadRunner model.

RoadrunnerSBMLModel ¶

RoadrunnerSBMLModel(
    source,
    base_path=None,
    changes=None,
    sid=None,
    name=None,
    selections=None,
    ureg=None,
    settings=None,
    parameters=None,
)

Bases: AbstractModel

Roadrunner model wrapper.

Load the model into roadrunner, with changes, selections and settings.

The parameters are added to the model as constant parameters, see AbstractModel; they are not selected by default.

r_loaded `property` ¶

r_loaded

Get the roadrunner instance of the model.

Raises:

Type	Description
`ValueError`	if no model is loaded.

initialize ¶

initialize(assignments)

Initialize the model with values before its initialization.

PEtab v2 sets the values of the parameter table and of the first conditions on the model before it is initialized, so an initial assignment follows a changed parameter, and a target which is set replaces its own initial assignment. roadrunner reinitializes the model when an initial value is set with init(...), which costs a compilation of the model per value. The model is therefore initialized as it was loaded, the values are set as the current values, and the initial assignments which read a changed entity are evaluated again, in their order, from the assignment rule of their helper parameter, which roadrunner evaluates on the current values.

roadrunner queues the events which fire at the time 0 with every reset, a loaded model counts as one, and a simulation fires them once: a second reset without a simulation in between fires them twice (case 01757 of the SBML Test Suite). A model which was not simulated since its last reset is therefore not reset again, the values as loaded are set back instead (the values of an earlier initialization included), see _reset; simulated records a simulation.

A compartment keeps the concentration of the species whose initial value is a concentration, as at the initialization of SBML, and of a species which is set as a concentration, and the amount of every other species; a species of an assignment rule follows its rule.

Parameters:

Name	Type	Description	Default
`assignments`	`Sequence[Assignment]`	the pre-initialization assignments of a plan. A formula reads the parameters after the values are set.	required

reset ¶

reset()

Set the model to the state it was loaded in, bitwise, without a simulation.

A simulation leaves the model with the values of its pre-initialization and its state at its end until the next initialization, see initialize; a reader of the model, e.g. the references of a design, resets it after it read what it needs, so that nothing which reads the model later sees them (#315). Every parameter, compartment and species amount which is not the variable of an assignment rule is the one of the model as loaded afterwards, see _reset; roadrunner resets the model once per simulation, see initialize.

loaded_value ¶

loaded_value(selection)

Get the value of a parameter, a compartment or a species of the model as loaded.

The current value of the model depends on the simulations before it, see reset, the value as loaded does not (#315).

Parameters:

Name	Type	Description	Default
`selection`	`str`	the id of a parameter, a compartment or a species (its amount), or `[S]`, the concentration of the species `S`.	required

Returns:

Type	Description
`float`	The value as loaded.

Raises:

Type	Description
`KeyError`	if the selection is none of these.

simulated ¶

simulated()

Record that the model was simulated since its last initialization.

The next initialize resets the model, see there, and the time the simulation reached is kept, see discard_pending_events.

discard_pending_events ¶

discard_pending_events(horizon)

Discard the events of the simulation before which are still pending.

roadrunner's reset keeps the queue of the events of a model: an event with a delay which the simulation before triggered and which had not fired when it ended fires in the next simulation at its time, if that simulation reaches it (#305), also after an initialization without a simulation in between, e.g. the references of a design. Such an event is after the time the last simulation reached, so only a simulation which integrates beyond it can see it; for a model with an event with a delay the model is then generated again, which empties the queue (it costs milliseconds for a small model and tenths of a second for a large one). Every point of a scan reaches the same end, so a scan regenerates no model, unless it integrates to a steady state.

roadrunner restores a vector of absolute tolerances after the regeneration species by species with setIndividualTolerance, which raises for a species of an assignment rule, and not a number: the tolerance is a number during the regeneration, and the selections and the absolute tolerances of sbmlsim are set again after it. The next initialization resets the new model, which queues its events at t0.

Parameters:

Name	Type	Description	Default
`horizon`	`float`	the time of roadrunner the next simulation integrates to, `inf` for an integration to a steady state.	required

from_abstract_model `staticmethod` ¶

from_abstract_model(
    abstract_model,
    selections=None,
    ureg=None,
    settings=None,
)

Create from AbstractModel.

load_roadrunner_model `classmethod` ¶

load_roadrunner_model(source)

Load model from given source.

:param source: path to SBML model or SBML string :param state_path: path to rr state :return: roadrunner instance

get_state_path `staticmethod` ¶

get_state_path(sbml_path)

Get path of the state file.

The state file is a binary file which allows fast model loading.

Q ¶

Q(value, unit=None)

Create a quantity in a unit of pint and of the unit ids of the model.

A unit id of the model is its expression, e.g. mg_per_min/kg is a milligram per minute and kilogram for a model whose unit definition mg_per_min is a milligram per minute, see UnitsInformation.quantity. sbmlsim.Q takes the units of pint only. A unit of pint, e.g. the units of a quantity, is taken as it is.

Parameters:

Name	Type	Description	Default
`value`	`Any`	the magnitude, a number or an array.	required
`unit`	`str \| PlainUnit \| None`	the unit, a string or a unit of pint, dimensionless without one.	`None`

Returns:

Type	Description
`Quantity`	The quantity.

Raises:

Type	Description
`UndefinedUnitError`	for a unit which is neither a unit of pint nor a unit id of the model.

parse_units ¶

parse_units(ureg)

Parse the units of the model from its SBML, see sbml.

A hierarchical model has the units of its flattened SBML, which include the ones of its submodels.

set_timecourse_selections `classmethod` ¶

set_timecourse_selections(r, selections=None, exclude=())

Set the selections of the simulations.

Without selections every entity of the model is selected, except a compartment without a size (NaN), e.g. a membrane whose area the model does not use, which has no value to record.

Parameters:

Name	Type	Description	Default
`r`	`RoadRunner`	the roadrunner instance.	required
`selections`	`list[str] \| None`	the selections, every entity of the model without.	`None`
`exclude`	`Collection[str]`	ids which are not selected by default, e.g. the parameters a problem added to the model.	`()`

Returns:

Type	Description
`list[str]`	The selections.

set_selections ¶

set_selections(selections)

Set the selections of the simulations of the model.

Parameters:

Name	Type	Description	Default
`selections`	`Sequence[str] \| None`	the selections, every entity of the model for `None`, see `set_timecourse_selections`; the parameters added to the model are not selected by default.	required

Raises:

Type	Description
`RuntimeError`	if roadrunner has no selection of a name.

has_selection ¶

has_selection(selection)

Check whether roadrunner has a selection of a name in the model.

Parameters:

Name	Type	Description	Default
`selection`	`str`	the name, e.g. `S`, `[S]`, a parameter or `time`.	required

Returns:

Type	Description
`bool`	Whether the loaded model can select it.

set_integrator_settings ¶

set_integrator_settings(**kwargs)

Set settings of the integrator.

Every setting of the integrator of roadrunner is passed on, for CVODE e.g. relative_tolerance, stiff, variable_step_size, initial_time_step, minimum_time_step, maximum_time_step and maximum_num_steps. absolute_tolerance, a float or an AbsoluteTolerance, is set as one tolerance per state, see sbmlsim.model.tolerances.

A setting the integrator has already is not set again, so that a simulator which applies its settings before every simulation costs nothing: the tolerances of the states are computed again only for another tolerance, another instance of roadrunner or a vector of CVODE which was set elsewhere. They are computed from the initial volumes of the compartments of the model as loaded, so a simulation does not depend on the pre-initialization of the one before it.

Parameters:

Name	Type	Description	Default
`**kwargs`	`float \| int \| bool \| AbsoluteTolerance`	the settings by their names in roadrunner.	`{}`

Returns:

Type	Description
`Integrator`	The integrator.

Raises:

Type	Description
`ValueError`	if the integrator has no setting of a name, or an override of the absolute tolerance is not a state.

sbml_ids ¶

sbml_ids()

Get the constant parameters and the species of the SBML roadrunner simulates.

They are read from the SBML of the instance of roadrunner (getSBML(), i.e. with the added parameters and the helpers of the initial assignments) once per instance and kept: serializing and parsing the SBML again on every call took 4.8 s of the 8.6 s of the initialization of the experiments of the acetaminophen model of pkdb_models (403 kB of SBML), which call sampling.parameters_of for 133 simulations (#332). An instance which replaces r is read again. sbmlsim never changes the structure of its instance (regenerateModel keeps the SBML); an edit of the instance itself, e.g. r.addParameter(...) or r.removeSpecies(...), is not tracked, and the ids stay those of the instance as first read until r is replaced.

Returns:

Type	Description
`SBMLIds`	The ids, in the order of the SBML.

state_ids ¶

state_ids()

Get the ids of the states which the integrator integrates.

The states of roadrunner's state vector, the targets of rate rules first, then the independent floating species, in the order of getRatesOfChange and of the tolerance vector of CVODE. They are counted by the rates of change, not by the tolerance vector, which is empty for another integrator than CVODE.

tolerances ¶

tolerances()

Get the absolute tolerance of every state.

Returns:

Type	Description
`DataFrame`	A row per state with `sid`, `kind`, `compartment`, `volume` (the
`DataFrame`	reference volume of a concentration species) and
`DataFrame`	`absolute_tolerance`.

parameter_df `staticmethod` ¶

parameter_df(r)

Create GlobalParameter DataFrame.

:return: pandas DataFrame

species_df `staticmethod` ¶

species_df(r)

Create FloatingSpecies DataFrame.

:return: pandas DataFrame

SBMLIds `dataclass` ¶

SBMLIds(constant_parameters, species)

The ids of the SBML of a model, see RoadrunnerSBMLModel.sbml_ids.

Attributes:

Name	Type	Description
`constant_parameters`	`tuple[str, ...]`	the parameters which are constant.
`species`	`tuple[str, ...]`	the species.

reset_all ¶

reset_all(r)

Reset a model to its initial values, as RoadRunner.resetAll.

roadrunner exposes the symbols of a model as attributes, so a model with a species or parameter named reset hides the method reset, which resetAll calls (case 00952 of the SBML Test Suite). The binding is called directly.

The reset queues the events which fire at the time 0 at the integration start time of the integrator and of the model, which every simulate sets to its start: after a simulation whose last integration started later, e.g. at the end of a simulation with events, the events at the time 0 fired at that time plus their delay, i.e. after the end of the next simulation (#305). Both are set to 0 first.

Parameters:

Name	Type	Description	Default
`r`	`RoadRunner`	the roadrunner instance.	required

load_roadrunner ¶

load_roadrunner(source)

Load an instance of roadrunner, its model always compiled (#313).

roadrunner 2.10 takes the compiled model of a new instance from its cache in the process when another instance of the same SBML is alive, and the data of such a model has no piecewise triggers (createModelData(..., 0) in LLVMModelGenerator::createModel): CVODE's root finding does not stop at the switch of a piecewise of the model, and the instance integrates a few 1e-9 apart from a compiled one. Which instance is alive differs between the first experiment of a run, the later ones, a serial run and the workers of a pool, so a model is compiled whenever it is loaded (LoadSBMLOptions.RECOMPILE), which also keeps it out of the cache. The compilation is paid once per loaded model, i.e. once per model of an ExperimentRunner and of a worker of a pool, and an instance no longer shares its code with another one: 1.2 s and 41 MB per instance for the acetaminophen model of pkdb_models (403 kB of SBML), against 0.044 s and 16 MB from the cache; 0.2 s for dapagliflozin.

The model is compiled with roadrunner's default JIT, MCJIT. LLJIT compiles the dulaglutide model of pkdb_models 6.9 times faster (1.5 s against 10.4 s), but roadrunner 2.10 crashes with it (a segmentation fault in the compiled code of a model) in runs which compile a model again while an earlier instance of it is alive: in 3 of 8 fits of the dulaglutide model at the optimization level NONE (the levels LESS, DEFAULT and AGGRESSIVE were fitted once each, without a crash, and not in a loop), and in 1 to 3 of 40 processes of a loop over its experiments at the levels NONE, LESS and AGGRESSIVE (DEFAULT was not run). MCJIT did not crash, in 0 of 6 fits and 0 of 20 processes of the loop (#331).

Parameters:

Name	Type	Description	Default
`source`	`str \| Path`	the path of an SBML file or the SBML itself.	required

Returns:

Type	Description
`RoadRunner`	The instance.

model.model_roadrunner¶

RoadrunnerSBMLModel ¶

r_loaded property ¶

initialize ¶

reset ¶

loaded_value ¶

simulated ¶

discard_pending_events ¶

from_abstract_model staticmethod ¶

load_roadrunner_model classmethod ¶

get_state_path staticmethod ¶

Q ¶

parse_units ¶

set_timecourse_selections classmethod ¶

set_selections ¶

has_selection ¶

set_integrator_settings ¶

sbml_ids ¶

state_ids ¶

tolerances ¶

parameter_df staticmethod ¶

species_df staticmethod ¶

SBMLIds dataclass ¶

reset_all ¶

load_roadrunner ¶

r_loaded `property` ¶

from_abstract_model `staticmethod` ¶

load_roadrunner_model `classmethod` ¶

get_state_path `staticmethod` ¶

set_timecourse_selections `classmethod` ¶

parameter_df `staticmethod` ¶

species_df `staticmethod` ¶

SBMLIds `dataclass` ¶