sciml.hybridization¶

Where a network sits in a hybrid problem.

A Hybridization connects a Network to a model: what its inputs are, which entities of the model its outputs set, and in which of three places it runs.

pattern	inputs	outputs	executed by
`PRE_INITIALIZATION`	constants: formulas of parameters, arrays	parameters and initial values, set before the simulation	numpy, once per simulation
`RHS`	formulas of species, parameters and time, arrays	parameters of the rate equations	roadrunner, as assignment rules
`OBSERVABLE`	formulas of species, parameters and time, arrays	symbols of an observable	roadrunner, as assignment rules

A network before the simulation is evaluated by derived_changes, which a fit calls for every simulation with the values of its parameters. The networks of the other two patterns are compiled into the model by sbmlsim.sciml.compiler; derived_changes sets only their inputs which are arrays of a condition.

The condition of a simulation is the id of the simulation in its experiment.

NetworkPattern ¶

Bases: StrEnum

The place of a network in a hybrid problem.

is_compiled `property` ¶

is_compiled

Check whether a network of the pattern is compiled into the model.

NetworkInput `dataclass` ¶

NetworkInput(formula=None, formulas=None, arrays=None)

An input of a network or an element of one.

Exactly one of the attributes is given.

Attributes:

Name	Type	Description
`formula`	`str \| None`	an L3 formula of SBML which holds for every condition, e.g. `prey`, `alpha * prey` or `0.5`.
`formulas`	`Mapping[str, str] \| None`	id of the condition -> formula, for an input which differs between the conditions. `ALL_CONDITIONS` is the formula of the conditions which are not listed.
`arrays`	`Mapping[str, ArrayLike] \| None`	id of the condition -> values, `ALL_CONDITIONS` for the values of the conditions which are not listed. The arrays of an input have one shape.

is_conditional `property` ¶

is_conditional

Check whether the input differs between the conditions.

shape `property` ¶

shape

Get the shape of the arrays, None for an input of formulas.

all_formulas ¶

all_formulas()

Get the formulas of the input, empty for an input of arrays.

formula_of ¶

formula_of(condition)

Get the formula of a condition.

Parameters:

Name	Type	Description	Default
`condition`	`str`	id of the condition.	required

Returns:

Type	Description
`str \| None`	The formula, `None` for an input of arrays and for a condition
`str \| None`	without a formula.

array_of ¶

array_of(condition)

Get the array of a condition.

Parameters:

Name	Type	Description	Default
`condition`	`str`	id of the condition.	required

Returns:

Type	Description
`ndarray \| None`	The array, `None` for an input of formulas and for a condition
`ndarray \| None`	without an array.

Hybridization `dataclass` ¶

Hybridization(
    network,
    pattern,
    model,
    inputs,
    outputs,
    frozen=frozenset(),
    constants=dict(),
)

A network with its inputs, its outputs and its place in a problem.

The hybridization is validated when it is created, as far as it can be without the model: validate checks it against the model. Two hybridizations are equal when their attributes are; a hybridization is not hashable, its attributes are dictionaries.

Attributes:

Name	Type	Description
`network`	`Network`	the network.
`pattern`	`NetworkPattern`	where the network sits.
`model`	`str`	id of the model in the experiment.
`inputs`	`Mapping[str, NetworkInput]`	id of the input -> the input. The id is `<net>__input<k>` for an input which is given as an array and `<net>__input<k>__<index>` for an element of an input which is given element by element, see `sbmlsim.sciml.network.input_id`.
`outputs`	`Mapping[str, str]`	id of the element of an output -> target, see `sbmlsim.sciml.network.output_id`. The target is an entity of the model for `RHS`, an entity or the selection of its concentration (`[prey]`) for `PRE_INITIALIZATION`, and the symbol an observable uses for `OBSERVABLE`, which the compiler adds to the model. An output without a target is not used.
`frozen`	`Collection[str]`	ids of the elements of the arrays which are not estimated.
`constants`	`Mapping[str, float]`	id -> value of the symbols of the formulas which are neither entities of the model nor parameters of the fit.

error ¶

error(message)

Get an error which names the network.

Parameters:

Name	Type	Description	Default
`message`	`str`	what is wrong.	required

Returns:

Type	Description
`NetworkHybridizationError`	The error, to be raised.

input_shapes ¶

input_shapes()

Get the shapes of the inputs of the forward pass, see input_shapes.

output_shapes ¶

output_shapes()

Get the shapes of the outputs of the network for its inputs.

fit_parameters ¶

fit_parameters(estimate, bounds=None)

Get the parameters of a fit of the network and freeze the rest.

The pattern decides whether the elements are entities of the model, see sbmlsim.sciml.parameters.network_fit_parameters, and every element which is not estimated is frozen.

Parameters:

Name	Type	Description	Default
`estimate`	`Mapping[str, bool]`	key of the entry -> whether the elements are estimated, for the network, a layer or an array.	required
`bounds`	`Mapping[str, tuple[float, float]] \| None`	key of the entry -> lower and upper bound, none by default.	`None`

Returns:

Type	Description
`list[FitParameter]`	The parameters of the fit and the hybridization with the other
`Hybridization`	elements frozen.

Raises:

Type	Description
`NetworkImportError`	if a key does not name the network, a layer or an array, or if an estimated element has no value.

summary ¶

summary()

Describe the network for the console and the report.

Returns:

Type	Description
`HookSummary`	The id of the network, its pattern, its layers with their types
`HookSummary`	in the order of the forward pass, the targets of its outputs and
`HookSummary`	one group per array of the layers the forward pass calls, with
`HookSummary`	the ids of all elements of the array.

conditions ¶

conditions()

Get the conditions for which an input has formulas or arrays.

Returns:

Type	Description
`dict[str, list[str]]`	id of an input -> the conditions its formulas or arrays name,
`dict[str, list[str]]`	without `ALL_CONDITIONS`; an input of one formula is not listed.

symbols ¶

symbols()

Get the ids whose values derived_changes reads.

Returns:

Type	Description
`frozenset[str]`	The symbols of the formulas of the inputs and the ids of the
`frozenset[str]`	elements which are not frozen, for a network before the
`frozenset[str]`	simulation. For a network which is compiled, which the model
`frozenset[str]`	evaluates, the ids of the frozen elements and of the outputs:
`frozenset[str]`	the model must have them, and `derived_changes` checks that the
`frozenset[str]`	model carries the values of the frozen elements.

targets ¶

targets()

Get the entities of the model derived_changes sets.

The targets are the keys of derived_changes as they are written: the id of an entity or the selection of the concentration of a species ([prey]), which sbmlsim.fit.derived compares by their entity (entity_of).

Returns:

Type	Description
`frozenset[str]`	The targets of the outputs for a network before the simulation,
`frozenset[str]`	and the ids of the elements of the inputs which are arrays of
`frozenset[str]`	conditions for a network which is compiled.

check_parameters ¶

check_parameters(targets)

Check the targets of the parameters of a fit against the network.

Parameters:

Name	Type	Description	Default
`targets`	`Collection[str]`	the entities the parameters of the fit write, without the prefix of a target which is not an entity of the model.	required

Raises:

Type	Description
`NetworkHybridizationError`	if a parameter writes an element which is frozen, an output or its target, or an element of an input.

input_values ¶

input_values(values, condition)

Get the inputs of the network for the values of a simulation.

Parameters:

Name	Type	Description	Default
`values`	`Mapping[str, float]`	id -> value of the parameters of the fit, of the changes of the simulation and of the entities of the model, in the units of the model. The constants of the hybridization are the values of the symbols which are not part of it.	required
`condition`	`str`	id of the condition of the simulation.	required

Returns:

Type	Description
`list[ndarray]`	The inputs, one array per input of the forward pass.

Raises:

Type	Description
`NetworkHybridizationError`	if an input has no formula or array for the condition, if a symbol of a formula has no value, or if the value of a formula is not defined or not a finite number.

derived_changes ¶

derived_changes(values, condition)

Get the changes of a simulation which follow from its values.

A network before the simulation is evaluated: its inputs are resolved with input_values, its arrays are the nominal values with the values of the elements which are not frozen, which the fit estimates, and its outputs are the changes of their targets. For a network which is compiled the changes are the elements of the inputs which are arrays of conditions, and the values of its frozen elements are compared with the network, which is how a model which was compiled from another network is found.

Parameters:

Name	Type	Description	Default
`values`	`Mapping[str, float]`	id -> value, see `input_values`. The values of the elements of the network which are not frozen are read from it by their id, the values of the frozen ones are ignored.	required
`condition`	`str`	id of the condition of the simulation.	required

Returns:

Type	Description
`dict[str, float]`	target -> value, in the unit of the target in the model.

Raises:

Type	Description
`NetworkHybridizationError`	if an input cannot be resolved, see `input_values`, if an element which is not frozen has no value, if an output is not a finite number, or if the values of the frozen elements of a network which is compiled are missing or differ from the network.

validate ¶

validate(sbml_path)

Check the hybridization against the model.

Parameters:

Name	Type	Description	Default
`sbml_path`	`Path`	the SBML model the network is a part of, without the network.	required

Raises:

Type	Description
`NetworkHybridizationError`	if the model cannot be read, if a target cannot be set by the network, see `_check_target`, if a constant is an entity of the model, if a formula uses a symbol which is an output of the network, or if an input of `PRE_INITIALIZATION` is not a constant of the simulation, i.e. depends on the time, a species, a reaction, a species reference, an entity which a rule sets or an event changes.

input_shapes ¶

input_shapes(network, inputs)

Get the shapes of the inputs of the forward pass of a network.

The shape of an input which is given as an array is the shape of its arrays. The shape of an input which is given element by element follows from the indices of its elements, which have to cover it.

Parameters:

Name	Type	Description	Default
`network`	`Network`	the network.	required
`inputs`	`Mapping[str, NetworkInput]`	id of the input -> the input, see `Hybridization`.	required

Returns:

Type	Description
`list[tuple[int, ...]]`	The shape of every input, in the order of the forward pass.

Raises:

Type	Description
`NetworkHybridizationError`	if an id is not the id of an input, if an input is given as an array and element by element, if an input of the forward pass is missing, or if the elements of an input do not cover a shape.

output_shapes ¶

output_shapes(network, shapes)

Get the shapes of the outputs of a network for inputs of given shapes.

Parameters:

Name	Type	Description	Default
`network`	`Network`	the network, with the values of its arrays.	required
`shapes`	`list[tuple[int, ...]]`	the shape of every input, in the order of the forward pass.	required

Returns:

Type	Description
`list[tuple[int, ...]]`	The shape of every output, in the order of the forward pass.

Raises:

Type	Description
`NetworkHybridizationError`	if the network cannot be evaluated on inputs of the shapes.
`NetworkImportError`	if an array of the network has no values.

entity_of ¶

entity_of(target)

Get the entity of the model a target names.

Parameters:

Name	Type	Description	Default
`target`	`str`	the entity or the selection of its concentration, e.g. `prey` or `[prey]`.	required

Returns:

Type	Description
`str`	The id of the entity, e.g. `prey`.

read_model ¶

read_model(sbml_path, network)

Read the model of an SBML file.

Parameters:

Name	Type	Description	Default
`sbml_path`	`Path`	the SBML file.	required
`network`	`str`	id of the network, for the message.	required

Returns:

Type	Description
`SBMLDocument`	The document and its model. The model is a part of the document and
`Model`	is valid as long as the document is referenced.

Raises:

Type	Description
`NetworkHybridizationError`	if the file does not exist or holds no model.

sciml.hybridization¶

NetworkPattern ¶

is_compiled property ¶

NetworkInput dataclass ¶

is_conditional property ¶

shape property ¶

all_formulas ¶

formula_of ¶

array_of ¶

Hybridization dataclass ¶

error ¶

input_shapes ¶

output_shapes ¶

fit_parameters ¶

summary ¶

conditions ¶

symbols ¶

targets ¶

check_parameters ¶

input_values ¶

derived_changes ¶

validate ¶

input_shapes ¶

output_shapes ¶

entity_of ¶

read_model ¶

is_compiled `property` ¶

NetworkInput `dataclass` ¶

is_conditional `property` ¶

shape `property` ¶

Hybridization `dataclass` ¶