amici.splines

Splines

This module provides helper functions for reading/writing splines with AMICI annotations from/to SBML files and for adding such splines to the AMICI C++ code.

Functions

spline_user_functions(splines, p_index)

Custom user functions to be used in ODEExporter for linking spline expressions to C++ code.

sympify_noeval(x)

Classes

AbstractSpline(sbml_id, nodes, ...[, ...])

Base class for spline functions which can be computed efficiently thanks to tailored C++ implementations in AMICI.

CubicHermiteSpline(sbml_id, nodes, ...[, ...])

UniformGrid(start, stop[, step, ...])

A grid of uniformly-spaced real points, computed with rational arithmetic.
class amici.splines.AbstractSpline(sbml_id, nodes, values_at_nodes, *, evaluate_at=None, bc=None, extrapolate=None, logarithmic_parametrization=False)[source]

Base class for spline functions which can be computed efficiently thanks to tailored C++ implementations in AMICI. Inside an SBML file, such splines are implemented with an assignment rule containing both a symbolic piecewise formula for the spline (allowing compatibility with any SBML-aware software) and annotations which encode the necessary information for AMICI to recreate the spline object (allowing for fast computations when the SBML file is used together with AMICI).

__init__(sbml_id, nodes, values_at_nodes, *, evaluate_at=None, bc=None, extrapolate=None, logarithmic_parametrization=False)[source]

Base constructor for AbstractSpline objects.

Parameters:

  • sbml_id (str | sympy.core.symbol.Symbol) – The SBML ID of the parameter associated to the spline as a string or a SymPy symbol.

  • nodes (collections.abc.Sequence) – The points at which the spline values are known. Currently, they must be numeric or only depend on constant parameters. These points should be strictly increasing. This argument will be sympified.

  • values_at_nodes (collections.abc.Sequence) – The spline values at each of the points in nodes. They must not depend on model species. This argument will be sympified.

  • evaluate_at (str | sympy.core.basic.Basic | None) – The point at which the spline is evaluated. It will be sympified. Defaults to model time.

  • bc (typing.Union[None, str, tuple[typing.Optional[str], typing.Optional[str]]]) –

    Tuple of applied boundary conditions, one for each side of the spline domain. If a single boundary condition is given it will be applied to both sides. Possible boundary conditions (allowed values depend on the AbstractSpline subclass):

    None or ‘no_bc’:

    Boundary conditions are not needed for this spline object;

    ’zeroderivative’:

    first derivative set to zero;

    ’natural’:

    second derivative set to zero;

    ’zeroderivative+natural’:

    first and second derivatives set to zero;

    ’periodic’:

    periodic bc.

  • extrapolate (typing.Union[None, str, tuple[typing.Optional[str], typing.Optional[str]]]) –

    Whether to extrapolate the spline outside the base interval defined by (nodes[0], nodes[-1]). It is a tuple of extrapolation methods, one for each side of the base interval. If it is not a tuple, then the same extrapolation will be applied on both sides. Extrapolation methods supported:

    None or ‘no_extrapolation’:

    no extrapolation should be performed. An exception will be raised in the C++ code if the spline is evaluated outside the base interval. In the fallback SBML symbolic expression ‘polynomial’ extrapolation will be used.

    ’polynomial’:

    the cubic polynomial used in the nearest spline segment will be used.

    ’constant’:

    constant extrapolation will be used. Requires ‘zeroderivative’ boundary condition. For splines which are continuous up to the second derivative, it requires the stricter ‘zeroderivative+natural’ boundary condition.

    ’linear’:

    linear extrapolation will be used. For splines which are continuous up to the second derivative, this requires the ‘natural’ boundary condition.

    ’periodic’:

    Periodic extrapolation. Requires ‘periodic’ boundary conditions.

  • logarithmic_parametrization (bool) – Whether interpolation should be done in log-scale.

add_to_sbml_model(model, *, auto_add=False, x_nominal=None, y_nominal=None, x_units=None, y_units=None, y_constant=None)[source]

Function to add the spline to an SBML model using an assignment rule with AMICI-specific annotations.

Parameters:

  • model (libsbml.Model) – A libsbml.Model to which the spline is to be added.

  • auto_add (bool | str) – Automatically add missing parameters to the SBML model (defaults to False). Only used for expressions consisting in a single symbol. If equal to ‘spline’, only the parameter representing the spline will be added.

  • x_nominal (collections.abc.Sequence[float] | None) – Nominal values used when auto-adding parameters for nodes.

  • y_nominal (collections.abc.Sequence[float] | float | None) – Nominal values used when auto-adding parameters for values_at_nodes.

  • x_units (str | None) – Units used when auto-adding parameters for nodes.

  • y_units (str | None) – Units used when auto-adding parameters for values_at_nodes.

  • y_constant (collections.abc.Sequence[bool] | bool | None) – Constant flags used when auto-adding parameters for values_at_nodes.

Return type:

None

property amici_annotation: str

An SBML annotation describing the spline.

property bc: tuple[None | str, None | str]

Boundary conditions applied to this spline.

check_if_valid(importer)[source]

Check if the spline described by this object can be correctly be implemented by AMICI. E.g., check whether the formulas for spline grid points, values, … contain species symbols.

Return type:

None

derivative(x, **kwargs)[source]

Evaluate the spline derivative at the point x.

Return type:

sympy.core.expr.Expr

evaluate(x)[source]

Evaluate the spline at the point x.

Return type:

sympy.core.basic.Basic

property evaluate_at: Basic

The symbolic argument at which the spline is evaluated.

property extrapolate: tuple[None | str, None | str]

Whether to extrapolate the spline outside the base interval.

property extrapolation_formulas: tuple[None | Basic, None | Basic]

Returns the extrapolation formulas on the left and right side of the interval (nodes[0], nodes[-1]). A value of None means that no extrapolation is required.

property formula: Piecewise

Compute a symbolic piecewise formula for the spline.

static from_annotation(sbml_id, annotation, *, locals_)[source]

Create a spline object from a SBML annotation.

This function extracts annotation and children from the XML annotation and gives them to the _fromAnnotation function for parsing. Subclass behaviour should be implemented by extending _fromAnnotation. However, the mapping between method strings and subclasses must be hard-coded into this function here (at the moment).

Return type:

amici.splines.AbstractSpline

static get_annotation(rule)[source]

Extract AMICI spline annotation from an SBML assignment rule (given as a libsbml.AssignmentRule object). Return None if any such annotation could not be found.

Return type:

xml.etree.ElementTree.Element | None

integrate(x0, x1)[source]

Integrate the spline between the points x0 and x1.

Return type:

sympy.core.basic.Basic

static is_spline(rule)[source]

Determine if an SBML assignment rule (given as a libsbml.AssignmentRule object) is an AMICI-annotated spline formula.

Return type:

bool

property logarithmic_parametrization: bool

Whether interpolation is done in log-scale.

property mathml_formula: Piecewise

Compute a symbolic piecewise formula for the spline for use inside a SBML assignment rule: SBML symbol naming will be used and operations not supported by SBML MathML will be avoided.

abstract property method: str

Spline method.

property nodes: ndarray

The points at which the spline values are known.

ode_model_symbol(importer)[source]

Returns the sympy object to be used by amici.de_export.ODEModel. This expression can be differentiated and easily mapped to the C++ code.

Return type:

sympy.core.function.Function

parameters(importer)[source]

Returns the SBML parameters used by this spline

Return type:

set[sympy.core.symbol.Symbol]

property period: Basic | None

Period of a periodic spline. None if the spline is not periodic.

plot(parameters=None, *, xlim=None, npoints=100, xlabel=None, ylabel='spline value', ax=None)[source]

Plots the spline, highlighting the nodes positions.

poly(i, *, x=None)[source]

Get the polynomial interpolant on the (nodes[i], nodes[i+1]) interval. The polynomial is written in Horner form with respect to the scaled variable poly_variable(x, i). If no variable x is provided, it will default to the one given at initialization time.

Return type:

sympy.core.basic.Basic

poly_variable(x, i)[source]

Given an evaluation point, return the value of the variable in which the polynomial on the i-th interval is expressed.

Return type:

sympy.core.basic.Basic

property sbml_formula: Piecewise

Compute a symbolic piecewise formula for the spline, using SBML symbol naming (the AMICI time symbol will be replaced with its SBML counterpart).

property sbml_id: Symbol

SBML ID of the spline parameter.

second_derivative(x)[source]

Evaluate the spline second derivative at the point x.

Return type:

sympy.core.basic.Basic

segment_formula(i, *, x=None)[source]

Return the formula for the actual value of the spline expression on the (nodes[i], nodes[i+1]) interval. Unless logarithmic parametrization is used, this is equal to the interpolating polynomial.

Return type:

sympy.core.basic.Basic

abstract property smoothness: int

Smoothness of this spline.

squared_L2_norm_of_curvature()[source]

Return the squared L2 norm of the spline’s curvature (commonly used as a regularizer). This is always computed in the spline native scale (i.e., in log-scale for positivity enforcing splines).

Return type:

sympy.core.basic.Basic

property values_at_nodes: ndarray

The spline values at each of the points in nodes.

y_scaled(i)[source]

Return the values which should be interpolated by a polynomial. Unless logarithmic parametrization is used, they are equal to the values given at initialization time.

class amici.splines.CubicHermiteSpline(sbml_id, nodes, values_at_nodes, derivatives_at_nodes=None, *, evaluate_at=None, bc='auto', extrapolate=None, logarithmic_parametrization=False)[source]
__init__(sbml_id, nodes, values_at_nodes, derivatives_at_nodes=None, *, evaluate_at=None, bc='auto', extrapolate=None, logarithmic_parametrization=False)[source]

Constructor for CubicHermiteSpline objects.

Parameters:

  • sbml_id (str | sympy.core.symbol.Symbol) – The SBML ID of the parameter associated to the spline as a string or a SymPy symbol.

  • x – The point at which the spline is evaluated. It will be sympified.

  • nodes (collections.abc.Sequence) – The points at which the spline values are known. Currently, they must be numeric or only depend on constant parameters. These points should be strictly increasing. This argument will be sympified.

  • values_at_nodes (collections.abc.Sequence) – The spline values at each of the points in nodes. They must not depend on model species. This argument will be sympified.

  • derivatives_at_nodes (collections.abc.Sequence) – The spline derivatives at each of the points in nodes. They must not depend on model species. This argument will be sympified. If not specified, it will be computed by finite differences.

  • evaluate_at (str | sympy.core.basic.Basic | None) – The point at which the spline is evaluated. It will be sympified. Defaults to model time.

  • bc (typing.Union[None, str, tuple[typing.Optional[str], typing.Optional[str]]]) – Applied boundary conditions (see AbstractSpline documentation). If ‘auto’ (the default), the boundary conditions will be automatically set depending on the extrapolation methods.

  • extrapolate (typing.Union[None, str, tuple[typing.Optional[str], typing.Optional[str]]]) – Extrapolation method (see AbstractSpline documentation).

  • logarithmic_parametrization (bool) – Whether interpolation should be done in log-scale.

add_to_sbml_model(model, *, auto_add=False, x_nominal=None, y_nominal=None, x_units=None, y_units=None, y_constant=None)

Function to add the spline to an SBML model using an assignment rule with AMICI-specific annotations.

Parameters:

  • model (libsbml.Model) – A libsbml.Model to which the spline is to be added.

  • auto_add (bool | str) – Automatically add missing parameters to the SBML model (defaults to False). Only used for expressions consisting in a single symbol. If equal to ‘spline’, only the parameter representing the spline will be added.

  • x_nominal (collections.abc.Sequence[float] | None) – Nominal values used when auto-adding parameters for nodes.

  • y_nominal (collections.abc.Sequence[float] | float | None) – Nominal values used when auto-adding parameters for values_at_nodes.

  • x_units (str | None) – Units used when auto-adding parameters for nodes.

  • y_units (str | None) – Units used when auto-adding parameters for values_at_nodes.

  • y_constant (collections.abc.Sequence[bool] | bool | None) – Constant flags used when auto-adding parameters for values_at_nodes.

Return type:

None

property amici_annotation: str

An SBML annotation describing the spline.

property bc: tuple[None | str, None | str]

Boundary conditions applied to this spline.

check_if_valid(importer)[source]

Check if the spline described by this object can be correctly be implemented by AMICI. E.g., check whether the formulas for spline grid points, values, … contain species symbols.

Return type:

None

d_scaled(i)[source]

Return the derivative of the polynomial interpolant at the i-th point. Unless logarithmic parametrization is used, it is equal to the derivative of the spline expression.

Return type:

sympy.core.expr.Expr

derivative(x, **kwargs)

Evaluate the spline derivative at the point x.

Return type:

sympy.core.expr.Expr

property derivatives_at_nodes: ndarray

The spline derivatives at each of the points in nodes.

property derivatives_by_fd: bool
evaluate(x)

Evaluate the spline at the point x.

Return type:

sympy.core.basic.Basic

property evaluate_at: Basic

The symbolic argument at which the spline is evaluated.

property extrapolate: tuple[None | str, None | str]

Whether to extrapolate the spline outside the base interval.

property extrapolation_formulas: tuple[None | Basic, None | Basic]

Returns the extrapolation formulas on the left and right side of the interval (nodes[0], nodes[-1]). A value of None means that no extrapolation is required.

property formula: Piecewise

Compute a symbolic piecewise formula for the spline.

static from_annotation(sbml_id, annotation, *, locals_)

Create a spline object from a SBML annotation.

This function extracts annotation and children from the XML annotation and gives them to the _fromAnnotation function for parsing. Subclass behaviour should be implemented by extending _fromAnnotation. However, the mapping between method strings and subclasses must be hard-coded into this function here (at the moment).

Return type:

amici.splines.AbstractSpline

static get_annotation(rule)

Extract AMICI spline annotation from an SBML assignment rule (given as a libsbml.AssignmentRule object). Return None if any such annotation could not be found.

Return type:

xml.etree.ElementTree.Element | None

integrate(x0, x1)

Integrate the spline between the points x0 and x1.

Return type:

sympy.core.basic.Basic

static is_spline(rule)

Determine if an SBML assignment rule (given as a libsbml.AssignmentRule object) is an AMICI-annotated spline formula.

Return type:

bool

property logarithmic_parametrization: bool

Whether interpolation is done in log-scale.

property mathml_formula: Piecewise

Compute a symbolic piecewise formula for the spline for use inside a SBML assignment rule: SBML symbol naming will be used and operations not supported by SBML MathML will be avoided.

property method: str

Spline method (cubic Hermite spline)

property nodes: ndarray

The points at which the spline values are known.

ode_model_symbol(importer)

Returns the sympy object to be used by amici.de_export.ODEModel. This expression can be differentiated and easily mapped to the C++ code.

Return type:

sympy.core.function.Function

parameters(importer)

Returns the SBML parameters used by this spline

Return type:

set[sympy.core.symbol.Symbol]

property period: Basic | None

Period of a periodic spline. None if the spline is not periodic.

plot(parameters=None, *, xlim=None, npoints=100, xlabel=None, ylabel='spline value', ax=None)

Plots the spline, highlighting the nodes positions.

poly(i, *, x=None)

Get the polynomial interpolant on the (nodes[i], nodes[i+1]) interval. The polynomial is written in Horner form with respect to the scaled variable poly_variable(x, i). If no variable x is provided, it will default to the one given at initialization time.

Return type:

sympy.core.basic.Basic

poly_variable(x, i)

Given an evaluation point, return the value of the variable in which the polynomial on the i-th interval is expressed.

Return type:

sympy.core.basic.Basic

property sbml_formula: Piecewise

Compute a symbolic piecewise formula for the spline, using SBML symbol naming (the AMICI time symbol will be replaced with its SBML counterpart).

property sbml_id: Symbol

SBML ID of the spline parameter.

second_derivative(x)

Evaluate the spline second derivative at the point x.

Return type:

sympy.core.basic.Basic

segment_formula(i, *, x=None)

Return the formula for the actual value of the spline expression on the (nodes[i], nodes[i+1]) interval. Unless logarithmic parametrization is used, this is equal to the interpolating polynomial.

Return type:

sympy.core.basic.Basic

property smoothness: int

Smoothness of this spline (equal to 1 for cubic Hermite splines since they are continuous up to the first derivative).

squared_L2_norm_of_curvature()

Return the squared L2 norm of the spline’s curvature (commonly used as a regularizer). This is always computed in the spline native scale (i.e., in log-scale for positivity enforcing splines).

Return type:

sympy.core.basic.Basic

property values_at_nodes: ndarray

The spline values at each of the points in nodes.

y_scaled(i)

Return the values which should be interpolated by a polynomial. Unless logarithmic parametrization is used, they are equal to the values given at initialization time.

class amici.splines.UniformGrid(start, stop, step=None, *, number_of_nodes=None, always_include_stop=True)[source]

A grid of uniformly-spaced real points, computed with rational arithmetic.

Implements the collections.abc.Sequence interface and can be converted to a numpy.ndarray (conversion to float can be specified with dtype=float).

Variables:

  • start – first point.

  • stop – last point.

  • step – distance between consecutive points.

  • number_of_nodes – number of grid nodes.

__init__(start, stop, step=None, *, number_of_nodes=None, always_include_stop=True)[source]

Create a new UniformGrid.

Note: A UniformGrid with a single node cannot be created.

Parameters:

  • start (numbers.Real | sympy.core.basic.Basic) – First point in the grid

  • stop (numbers.Real | sympy.core.basic.Basic) – Last point in the grid (some caveats apply, see always_include_stop)

  • step (numbers.Real | sympy.core.basic.Basic | None) – Desired step size of the grid. Mutually exclusive with number_of_nodes.

  • number_of_nodes (numbers.Integral | None) – Number of grid nodes, i.e., the length of the grid. It must be greater than or equal to 2. Mutually exclusive with step.

  • always_include_stop (bool) – Controls the behaviour when step is not None. If True (default), the endpoint is the smallest start + k * step, with k integer, which is greater than or equal to stop. Otherwise, the endpoint is the largest start + k * step, with k integer, which is smaller than or equal to stop.

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

property number_of_nodes: Basic

Number of grid nodes.

property start: Basic

First point.

property step: Basic

Distance between consecutive points.

property stop: Basic

Last point.

amici.splines.spline_user_functions(splines, p_index)[source]

Custom user functions to be used in ODEExporter for linking spline expressions to C++ code.

Return type:

dict[str, list[tuple[typing.Callable[..., bool], typing.Callable[..., str]]]]

amici.splines.sympify_noeval(x)[source]