model.model_copasi¶

The model of an SBML model in COPASI, see sbmlsim.model.model_sbml.

CopasiSBMLModel loads the SBML of a model into a data model of COPASI (python-copasi, the optional extra copasi), which it owns until it is released (close). Its values are read and written in the selections of roadrunner, S the amount of a species, [S] its concentration, the id of a parameter or a compartment, the id of a reaction its rate and time, with the numbers of the SBML: COPASI holds the amount of a species as a particle number, which the model converts with the factor of COPASI from a quantity to a number.

COPASI reads a model with its own units, without converting the numbers of the SBML (a species in other units than the model keeps its number, as in roadrunner). The model checks after the import that every plain initial number of the SBML is the one of COPASI and raises otherwise, e.g. for an amount whose particle number is not finite. It raises as well for an error of the import (of COPASI or of libsbml) and for the features COPASI loads and simulates otherwise than roadrunner, see _check_supported. COPASI multiplies the stoichiometries of a species by its conversion factor when it imports a model, so a model with conversion factors is compiled again after the import and a plan which changes a conversion factor is refused, see _compile_conversion_factors.

COPASI folds a constant entity into the constants of its model, a value written into it during a simulation is not seen. The SBML which COPASI loads therefore makes every entity which a change can set (the parameters, compartments and species which are not the variable of an assignment rule) non-constant and the target of one event which never fires (TARGETS_EVENT), which makes them part of the state of COPASI, where a change sets them (_set_current_values); an entity whose number in the SBML is not finite (NaN) is left out, COPASI integrates no state which is not finite, and a change of it raises.

LSODA in COPASI finds no crossing of a comparison whose root function is exactly 0 when it starts. In a model with events, the SBML which COPASI loads therefore has every comparison of a trigger and of a math COPASI integrates shifted by a parameter (SHIFT_PREFIX, SWITCH_PREFIX), which is 0 but before an integration from a state in which a comparison of a trigger is exactly at its threshold, see CopasiSBMLModel.shift_comparisons.

A result of COPASI is reproducible within the integration and not bitwise across loads of a model: COPASI sums the fluxes of the reactions of a species into its rate in an order which depends on the addresses of its objects, i.e. on the memory the process allocated and freed before the load (a released model, whose data model is removed, or any memory of python), so the rate of a species of three or more reactions differs in its last bits and the integration amplifies it, on the HCTZ model with a dose to a few tens of times the tolerances of the integrator (copasi/basico#77). A loaded model is bitwise reproducible, also when another model is released.

CopasiSBMLModel ¶

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

Bases: SBMLModel

The model of an SBML model in COPASI, see the module.

Attributes:

Name	Type	Description
`entities`	`dict[str, Any]`	the parameters, compartments and species of COPASI by their SBML id.
`reactions`	`dict[str, Any]`	the reactions of COPASI by their SBML id.
`absolute_tolerance`	`AbsoluteTolerance`	the absolute tolerance set last, see `set_integrator_settings`.

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

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

Raises:

Type	Description
`ValueError`	for an error of COPASI when it imports the model, a model with algebraic rules, an initial number which COPASI reads otherwise, a selection COPASI has not, or an unknown setting.

dm `property` ¶

dm

Get the data model of COPASI of the model.

Raises:

Type	Description
`RuntimeError`	if the model was released, see `close`.

cmodel `property` ¶

cmodel

Get the model of COPASI.

mc `property` ¶

mc

Get the math container of COPASI, the values a simulation integrates.

values `property` ¶

values

Get the current values of the model in the selections of roadrunner.

close ¶

close()

Release the data model of COPASI, the model cannot be used afterwards.

A model which is garbage collected releases it as well.

from_abstract_model `staticmethod` ¶

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

Create from AbstractModel, see CopasiSBMLModel.

initialize ¶

initialize(assignments)

Initialize the model with values before its initialization.

The model is set to its initial state as loaded first (_restore), so an initialization does not depend on the one before it. The values are then set as the initial values of their targets and COPASI evaluates the initial assignments and the assignment rules which read them again; a target replaces its own initial assignment, whose initial expression is removed in COPASI while a target sets it. A formula reads the parameters as in roadrunner, the values which are set and otherwise the values as loaded, before the initial assignments are evaluated again (a parameter of an initial assignment has its value as loaded, also when an entity it depends on is set) and an assignment rule on that state, see _formula_values; the values of all formulas are evaluated before any of them is set (PEtab v2).

A compartment whose size changes keeps the concentration of the species whose initial value is a concentration and of a species which is set as a concentration, and the amount of every other species, as roadrunner does (RoadrunnerSBMLModel.initialize); a species of an assignment rule or of an initial assignment follows its math.

Parameters:

Name	Type	Description	Default
`assignments`	`Sequence[Assignment]`	the pre-initialization assignments of a plan. A formula reads parameters only, see `Plan.preinit`.	required

reset ¶

reset()

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

simulated ¶

simulated()

Record that the model was simulated since its last initialization.

Nothing is recorded: an initialization sets the initial state as loaded back whatever ran before it, see initialize.

loaded_value ¶

loaded_value(selection)

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

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.

value ¶

value(selection)

Get the current value of a selection.

Parameters:

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

Returns:

Type	Description
`float`	The value in the current state of the model.

Raises:

Type	Description
`RuntimeError`	if COPASI has no selection of the name, as roadrunner.

set_value ¶

set_value(selection, value)

Set the current value of a selection, between two integrations.

The value is set in the state of COPASI (_set_current_values), the amount of a species as its particle number, a concentration as the amount in the current size of its compartment, and the values which depend on it are updated.

Parameters:

Name	Type	Description	Default
`selection`	`str`	`S`, `[S]`, a parameter or a compartment.	required
`value`	`float`	the value.	required

Raises:

Type	Description
`RuntimeError`	if COPASI has no selection of the name, or it cannot be set: the time, a reaction or the variable of an assignment rule, as roadrunner.

pending_event_time ¶

pending_event_time()

Get the time of the next delayed event COPASI has scheduled.

Returns:

Type	Description
`float`	The time at which the next scheduled event executes, infinity
`float`	without one.

fire_pending_events ¶

fire_pending_events(time)

Execute the delayed events COPASI has scheduled at a time.

The model is set to the time and COPASI executes the events of its queue which are due, in the current state, and the events they trigger; the values which depend on the state are updated.

Parameters:

Name	Type	Description	Default
`time`	`float`	the time of the events, see `pending_event_time`.	required

Raises:

Type	Description
`RuntimeError`	if COPASI reports an error, with its message.

fire_queued_events ¶

fire_queued_events(time)

Execute the events COPASI queued at a time, e.g. at the initial values, and the events they trigger.

COPASI executes them at the start of an integration, the ones of a comparison for equality first (processQueue(false), then true, as CTrajectoryTask::processStep).

Parameters:

Name	Type	Description	Default
`time`	`float`	the time of the events, the current time.	required

Raises:

Type	Description
`RuntimeError`	if COPASI reports an error, with its message.

set_time ¶

set_time(time)

Set the current time of the model, between two integrations.

An integration of COPASI continues from the current time; the values which depend on the time are updated.

Parameters:

Name	Type	Description	Default
`time`	`float`	the time.	required

shift_comparisons ¶

shift_comparisons(resolution, written=False)

Shift the comparisons which are exactly at their threshold, before an integration.

LSODA in COPASI finds the root of a comparison where its root function changes its sign. A root function which is exactly 0 when LSODA starts to watch it is masked while it stays 0, and when one is 0 LSODA takes every root function at a little after the start (DRCHEK), so a comparison of a trigger at its threshold is not found when it turns later, e.g. X > 2 after a change which sets X = 2 and a rise of X right after the change or after a plateau, which roadrunner fires. COPASI handles such a root only when it applies the initial values, by the sign of its rate of change.

Every comparison of a trigger and of a math COPASI integrates is compiled shifted by a parameter, see _with_shifted_comparisons, which is 0 but before an integration from a state in which a comparison of a trigger is exactly at its threshold with its value as written, e.g. after a change which sets a value to it or the time to the time of a change. Then every comparison at its threshold is shifted, so that no root function of COPASI is 0 at the start and LSODA finds the crossings: a comparison keeps its value as written until the operands move by the shift in the direction which changes it, a comparison of a trigger which COPASI found turned at its threshold where LSODA saw it last (record_roots: at the end of the integration before or at the initial values, and the state of its root in COPASI is the turned value), e.g. time > 10 at the end of a horizon of a steady state at 10, keeps its turned value, so its event does not fire again. The size of a shift is _threshold_shift. Without such a comparison of a trigger every shift is 0, the model as written.

Parameters:

Name	Type	Description	Default
`resolution`	`float`	the resolution of the time of the simulation, see `sbmlsim.simulator.plan.time_tolerance`.	required
`written`	`bool`	whether every comparison of a trigger at its threshold has its value as written, after an event of the model which COPASI fired, whose processing of the states of the roots at a threshold the executor does not follow.	`False`

record_roots ¶

record_roots()

Record the roots of COPASI where LSODA saw them last, after an integration or at the initial values, see shift_comparisons.

landed ¶

landed()

Tell the comparisons of the triggers an integration left at their threshold or whose crossing COPASI missed.

An event of the model which COPASI fires in an integration may set a comparison of a trigger exactly to its threshold, e.g. G: X > 0 after E: X = 0, which LSODA does not find when it turns, see shift_comparisons: after the integration the comparison is at its threshold, or, if it turned, the state of its root in COPASI is not its value. COPASI processes a root it finds at once, so a state which differs from the sign of its root is a crossing it missed.

Returns:

Type	Description
`bool`	Whether a comparison of a trigger is exactly at its threshold, and
`list[int]`	the positions of the events among the events of the model whose
`tuple[bool, list[int]]`	crossing COPASI missed, in their order.

snapshot ¶

snapshot()

Get the current state of the model, of the shifts and of the roots as LSODA saw them last, see restore.

restore ¶

restore(snapshot)

Set the model back to a state of snapshot, the time and the shifts included.

The states of the triggers in COPASI are the ones of the integration after it; an integration sets them from the current values first.

rates ¶

rates(states)

Get the current rates of change of states.

Parameters:

Name	Type	Description	Default
`states`	`Sequence[str]`	the ids of species, whose rates are rates of their amounts, or of the targets of rate rules, see `state_ids`.	required

Returns:

Type	Description
`ndarray`	The rate of every state.

has_selection ¶

has_selection(selection)

Check whether COPASI 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_selections ¶

set_selections(selections)

Set the selections of the simulations of the model.

Parameters:

Name	Type	Description	Default
`selections`	`Sequence[str] \| None`	the selections, `default_selections` for `None`.	required

Raises:

Type	Description
`ValueError`	if COPASI has no selection of a name.

output_cns ¶

output_cns(selections)

Get the common names of COPASI of the values of selections.

The values of an output of COPASI (CDataHandler), the amount of a species as its particle number, see output_transform.

Parameters:

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

Returns:

Type	Description
`list[str]`	The common name of each selection.

Raises:

Type	Description
`ValueError`	if COPASI has no selection of a name.

output_transform ¶

output_transform(selections)

Get the conversion of the output of COPASI into the values of selections.

Parameters:

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

Returns:

Type	Description
`Callable[[Sequence[float] \| ndarray], ndarray]`	A function of the rows of an output (a row or an array of rows,
`Callable[[Sequence[float] \| ndarray], ndarray]`	the columns in the order of the selections), which turns the
`Callable[[Sequence[float] \| ndarray], ndarray]`	particle numbers into amounts.

set_integrator_settings ¶

set_integrator_settings(**settings)

Set settings of the integrator, LSODA of COPASI.

The settings have the names of roadrunner: relative_tolerance, absolute_tolerance, maximum_num_steps and maximum_time_step. COPASI has one absolute tolerance, the smallest tolerance of an AbsoluteTolerance (of the kinds and of the overrides, reported once when they differ) times COPASI_ATOL_FACTOR, so COPASI integrates at least as accurately as roadrunner at equal settings. A setting of roadrunner which COPASI has no equivalent of, e.g. variable_step_size, is ignored and reported once per model.

Parameters:

Name	Type	Description	Default
`**settings`	`IntegratorSetting`	the settings by their names in roadrunner.	`{}`

Raises:

Type	Description
`ValueError`	if neither COPASI nor roadrunner has a setting of a name, or a value is not valid.

integrator_state ¶

integrator_state()

Get the name of the integrator of the model and every one of its settings.

The settings have the names of roadrunner, the absolute tolerance is the AbsoluteTolerance of the model as it was set; the one absolute tolerance of LSODA is its smallest tolerance times COPASI_ATOL_FACTOR, see set_integrator_settings.

Returns:

Type	Description
`tuple[str, tuple[tuple[str, Any], ...]]`	The name of the integrator and its settings, sorted by name.

set_integrator_state ¶

set_integrator_state(state)

Set the settings of the integrator, see integrator_state.

Parameters:

Name	Type	Description	Default
`state`	`tuple[str, tuple[tuple[str, Any], ...]]`	the name of the integrator, `lsoda`, and its settings.	required

Raises:

Type	Description
`ValueError`	if the integrator is not the one of COPASI, or it has no setting of a name.

state_ids ¶

state_ids()

Get the ids of the states which the integrator integrates.

The species which reactions or a rate rule change, in the order of the SBML, then the other targets of rate rules, in the order of the SBML; read once, the states of a model do not change.

drain_messages ¶

drain_messages(label)

Take the messages of COPASI, raise for an error and log the others.

COPASI collects its messages in a queue of the process instead of printing them, so the messages of a call of COPASI are taken right after it. An error of COPASI and an error of libsbml, which COPASI passes on as a message of another type, raise; a message which is known not to change the numbers (BENIGN_MESSAGES) is logged at the level DEBUG, every other one as a warning.

Parameters:

Name	Type	Description	Default
`label`	`str`	the name of the model in a message.	required

Raises:

Type	Description
`ValueError`	with the text of the errors, if a message is an error.

model.model_copasi¶

CopasiSBMLModel ¶

dm property ¶

cmodel property ¶

mc property ¶

values property ¶

close ¶

from_abstract_model staticmethod ¶

initialize ¶

reset ¶

simulated ¶

loaded_value ¶

value ¶

set_value ¶

pending_event_time ¶

fire_pending_events ¶

fire_queued_events ¶

set_time ¶

shift_comparisons ¶

record_roots ¶

landed ¶

snapshot ¶

restore ¶

rates ¶

has_selection ¶

set_selections ¶

output_cns ¶

output_transform ¶

set_integrator_settings ¶

integrator_state ¶

set_integrator_state ¶

state_ids ¶

drain_messages ¶

dm `property` ¶

cmodel `property` ¶

mc `property` ¶

values `property` ¶

from_abstract_model `staticmethod` ¶