Skip to content

simulator.formula

Formulas of the math of PEtab over the selections of roadrunner.

A formula is a string of the math of PEtab whose symbols are selections of roadrunner: S is the amount of a species, [S] its concentration and time the time. The brackets are not math, so [S] is replaced by an identifier before the formula is parsed and mapped back afterwards; so is an identifier with a dot, the parameter of a PK observable, e.g. hctz.cmax.

A formula is compiled to a numpy function once and cached, a CompiledFormula is not pickled: a plan keeps the formula as a string.

The formulas of observables extend the math by four reductions over the time of one simulation, see reduce_formula and evaluate_reduced: max(x) and min(x) with a single argument (with two or more they are the elementwise functions of PEtab), mean(x), the time weighted mean, and at(x, t), the value at a time. A value is an array whose last axis is the time of a simulation, so a scan of many simulations reduces every simulation on its own. The formulas of data share reduce_formula and have only max and min, which reduce a labelled array along its dimension of the time or of the rows of a dataset by name, see sbmlsim.data.evaluate_function.

CompiledFormula dataclass 

CompiledFormula(formula, symbols, _function)

A formula compiled to a numpy function of its symbols.

Attributes:

Name Type Description
formula str

the formula as it was given.
symbols tuple[str, ...]

the selections the formula reads, sorted.

evaluate 

evaluate(values)

Evaluate the formula.

Parameters:

Name Type Description Default
values Sequence[float]

the values of the symbols, in the order of symbols.

 required

Returns:

Type Description
float

The value of the formula.

apply 

apply(values)

Evaluate the formula on values of any type numpy operates on.

Unlike evaluate, the result is not converted to a float, arrays and the quantities of pint keep their shape and their units.

Parameters:

Name Type Description Default
values Sequence[Any]

the values of the symbols, in the order of symbols.

 required

Returns:

Type Description
Any

The value of the formula.

evaluate_array 

evaluate_array(values, size)

Evaluate the formula on arrays of the values of its symbols.

Parameters:

Name Type Description Default
values Sequence[ndarray]

the values of the symbols, in the order of symbols, one array of size values per symbol.

 required
size int

the number of values, which a formula without symbols needs.

 required

Returns:

Type Description
ndarray

The size values of the formula.

Reduction dataclass 

Reduction(symbol, function, arguments)

A reduction over the time of a simulation, see reduce_formula.

Attributes:

Name Type Description
symbol str

the identifier which stands for its value in the formula.
function str

max, min, mean or at.
arguments tuple[str, ...]

the formulas of its arguments, which read the symbols of the reductions inside of them.

ReducedFormula dataclass 

ReducedFormula(formula, outer, reductions)

A formula whose reductions are replaced by symbols, see reduce_formula.

Attributes:

Name Type Description
formula str

the formula as it was given.
outer str

the formula with every reduction replaced by its symbol.
reductions tuple[Reduction, ...]

the reductions, an inner one before the one whose argument it is.

placeholders property 

placeholders

Get the symbols which stand for the reductions.

symbols property 

symbols

Get the identifiers the formula reads, also inside of the reductions.

outer_symbols property 

outer_symbols

Get the identifiers the formula reads outside of its reductions.

time_symbols property 

time_symbols

Get the identifiers the times of the at reductions read.

compile_formula cached 

compile_formula(formula)

Compile a formula, see the module.

Parameters:

Name Type Description Default
formula str

the formula.

 required

Returns:

Type Description
CompiledFormula

The compiled formula.

Raises:

Type Description
ValueError

if the formula is not valid math of PEtab.

reduce_formula cached 

reduce_formula(formula)

Find the reductions of a formula, see the module.

Parameters:

Name Type Description Default
formula str

the formula.

 required

Returns:

Type Description
ReducedFormula

The formula with its reductions.

Raises:

Type Description
ValueError

if the parentheses are not balanced, a reduction has not its number of arguments or a part of the formula is not valid math.

evaluate_reduced 

evaluate_reduced(
    formula, values, time=None, tolerance=0.0, changes=None
)

Evaluate a formula with reductions over the time of every simulation.

A value is a number, a numpy array or a quantity of pint. The last axis of an array is the time of a simulation and the axes before it are the simulations, e.g. (n_points, n_rows) padded with NaN in a worker or (*dims, time) of a scan. A number, or an array whose last axis has one element, is a value per simulation, which is constant in time. A reduction keeps its axis with one element, so its value broadcasts against the timecourses, and keeps the unit of its argument:

  • max(x), min(x): the largest and the smallest value, ignoring NaN;
  • mean(x): the trapezoidal integral divided by the time between the first and the last time point, the value itself for a single time point; the two time points of the states before and after a change at its time are an interval without time, which adds nothing;
  • at(x, t): the value at the time t, a number or a value per simulation, interpolated linearly; the value after a change or an event of the model at its time, toward the state before a change at a time before it (time points at most tolerance apart are a jump, see sbmlsim.result.timecourse.grid_weights) and NaN outside of the time points.

The times which are not finite, the padding (NaN) and the steady state after the end (inf), are no time points of a reduction.

Parameters:

Name Type Description Default
formula str

the formula.

 required
values Mapping[str, Any]

the values of its identifiers.

 required
time ndarray | None

the time points of the timecourses, of their shape; None where there are no times, e.g. for the units of a formula, which allows max and min of a timecourse.

 None
tolerance float | ndarray

the resolution of the time of every simulation, a number or an array of the shape of the simulations, e.g. (n_points,), see sbmlsim.simulator.plan.time_tolerance; at takes two time points at most this apart as a jump.

 0.0
changes Sequence[ndarray] | None

the times of the changes after the start of every simulation, in the order of the simulations flattened, see grid_weights; None for none.

 None

Returns:

Type Description
Any

The value of the formula.

Raises:

Type Description
ValueError

if the formula is not valid, reads an identifier without a value, reduces a timecourse with mean or at without time, or changes are not the ones of every simulation.