amici.ode_export

C++ Export

This module provides all necessary functionality specify an ODE model and generate executable C++ simulation code. The user generally won’t have to directly call any function from this module as this will be done by amici.pysb_import.pysb2amici(), amici.sbml_import.SbmlImporter.sbml2amici() and amici.petab_import.import_model()

Classes

ConservationLaw(identifier, name, value)	A conservation law defines the absolute the total amount of a (weighted) sum of states
Constant(identifier, name, value)	A Constant is a fixed variable in the model with respect to which sensitivities cannot be computed, abbreviated by k
Expression(identifier, name, value)	An Expressions is a recurring elements in symbolic formulas.
LogLikelihood(identifier, name, value)	A LogLikelihood defines the distance between measurements and experiments for a particular observable.
ModelQuantity(identifier, name, value)	Base class for model components
ODEExporter(ode_model[, outdir, verbose, …])	The ODEExporter class generates AMICI C++ files for ODE model as defined in symbolic expressions.
ODEModel([verbose, simplify])	Defines an Ordinary Differential Equation as set of ModelQuantities.
Observable(identifier, name, value[, …])	An Observable links model simulations to experimental measurements, abbreviated by y
Parameter(identifier, name, value)	A Parameter is a free variable in the model with respect to which sensitivities may be computed, abbreviated by p
SigmaY(identifier, name, value)	A Standard Deviation SigmaY rescales the distance between simulations and measurements when computing residuals or objective functions, abbreviated by sigmay
State(identifier, name, init, dt)	A State variable defines an entity that evolves with time according to the provided time derivative, abbreviated by x
TemplateAmici(template)	Template format used in AMICI (see string.template for more details).

Functions Summary

apply_template(source_file, target_file, …)	Load source file, apply template substitution as provided in templateData and save as targetFile.
cast_to_sym(value, input_name)	Typecasts the value to sympy.Float if possible, and ensures the value is a symbolic expression.
csc_matrix(matrix, rownames, colnames[, …])	Generates the sparse symbolic identifiers, symbolic identifiers, sparse matrix, column pointers and row values for a symbolic variable
generate_flux_symbol(reaction_index)	Generate identifier symbol for a reaction flux.
generate_measurement_symbol(observable_id)	Generates the appropriate measurement symbol for the provided observable
get_function_extern_declaration(fun, name)	Constructs the extern function declaration for a given function
get_model_override_implementation(fun, name)	Constructs amici::Model::* override implementation for a given function
get_sunindex_extern_declaration(fun, name, …)	Constructs the function declaration for an index function of a given function
get_sunindex_override_implementation(fun, …)	Constructs the amici::Model:: function implementation for an index function of a given function
get_switch_statement(condition, cases[, …])	Generate code for switch statement
is_valid_identifier(x)	Check whether x is a valid identifier for conditions, parameters, observables.
remove_typedefs(signature)	Strips typedef info from a function signature
smart_is_zero_matrix(x)	A faster implementation of sympy’s is_zero_matrix
smart_jacobian(eq, sym_var)	Wrapper around symbolic jacobian with some additional checks that reduce computation time for large matrices
smart_multiply(x, y)	Wrapper around symbolic multiplication with some additional checks that reduce computation time for large matrices
smart_subs_dict(sym, subs[, field, reverse])	Subsitutes expressions completely flattening them out.
strip_pysb(symbol)	Strips pysb info from a pysb.Component object
symbol_with_assumptions(name)	Central function to create symbols with consistent, canonical assumptions
var_in_function_signature(name, varname)	Checks if the values for a symbolic variable is passed in the signature of a function

Functions

amici.ode_export.apply_template(source_file, target_file, template_data)

Load source file, apply template substitution as provided in templateData and save as targetFile.

Parameters

• source_file (str) – relative or absolute path to template file

• target_file (str) – relative or absolute path to output file

• template_data (typing.Dict[str, str]) – template keywords to substitute (key is template variable without TemplateAmici.delimiter)

Return type

None

amici.ode_export.cast_to_sym(value, input_name)

Typecasts the value to sympy.Float if possible, and ensures the value is a symbolic expression.

Parameters

• value (typing.Union[typing.SupportsFloat, sympy.core.expr.Expr, sympy.logic.boolalg.BooleanAtom]) – value to be cast

• input_name (str) – name of input variable

Return type

sympy.core.expr.Expr

Returns

typecast value

amici.ode_export.csc_matrix(matrix, rownames, colnames, identifier=0, pattern_only=False)

Generates the sparse symbolic identifiers, symbolic identifiers, sparse matrix, column pointers and row values for a symbolic variable

Parameters

• matrix (sympy.matrices.dense.MutableDenseMatrix) – dense matrix to be sparsified

• rownames (typing.List[sympy.core.symbol.Symbol]) – ids of the variable of which the derivative is computed (assuming matrix is the jacobian)

• colnames (typing.List[sympy.core.symbol.Symbol]) – ids of the variable with respect to which the derivative is computed (assuming matrix is the jacobian)

• identifier (typing.Optional[int]) – additional identifier that gets appended to symbol names to ensure their uniqueness in outer loops

• pattern_only (typing.Optional[bool]) – flag for computing sparsity pattern without whole matrix

Return type

typing.Tuple[typing.List[int], typing.List[int], sympy.matrices.dense.MutableDenseMatrix, typing.List[str], sympy.matrices.dense.MutableDenseMatrix]

Returns

symbol_col_ptrs, symbol_row_vals, sparse_list, symbol_list, sparse_matrix

amici.ode_export.generate_flux_symbol(reaction_index)

Generate identifier symbol for a reaction flux. This function will always return the same unique python object for a given entity.

Parameters

reaction_index (int) – index of the reaction to which the flux corresponds

Return type

sympy.core.symbol.Symbol

Returns

identifier symbol

amici.ode_export.generate_measurement_symbol(observable_id)

Generates the appropriate measurement symbol for the provided observable

Parameters

observable_id (typing.Union[str, sympy.core.symbol.Symbol]) – symbol (or string representation) of the observable

Returns

symbol for the corresponding measurement

amici.ode_export.get_function_extern_declaration(fun, name)

Constructs the extern function declaration for a given function

Parameters

• fun (str) – function name

• name (str) – model name

Return type

str

Returns

c++ function definition string

amici.ode_export.get_model_override_implementation(fun, name)

Constructs amici::Model::* override implementation for a given function

Parameters

• fun (str) – function name

• name (str) – model name

Return type

str

Returns

c++ function implementation string

amici.ode_export.get_sunindex_extern_declaration(fun, name, indextype)

Constructs the function declaration for an index function of a given function

Parameters

• fun (str) – function name

• name (str) – model name

• indextype (str) – index function {‘colptrs’, ‘rowvals’}

Return type

str

Returns

c++ function declaration string

amici.ode_export.get_sunindex_override_implementation(fun, name, indextype)

Constructs the amici::Model:: function implementation for an index function of a given function

Parameters

• fun (str) – function name

• name (str) – model name

• indextype (str) – index function {‘colptrs’, ‘rowvals’}

Return type

str

Returns

c++ function implementation string

amici.ode_export.get_switch_statement(condition, cases, indentation_level=0, indentation_step=' ')

Generate code for switch statement

Parameters

• condition (str) – Condition for switch

• cases (typing.Dict[int, typing.List[str]]) – Cases as dict with expressions as keys and statement as list of strings

• indentation_level (typing.Optional[int]) – indentation level

• indentation_step (typing.Optional[str]) – indentation whitespace per level

Returns

Code for switch expression as list of strings

amici.ode_export.is_valid_identifier(x)

Check whether x is a valid identifier for conditions, parameters, observables… . Identifiers may only contain upper and lower case letters, digits and underscores, and must not start with a digit.

Parameters

x (str) – string to check

Return type

bool

Returns

True if valid, False otherwise

amici.ode_export.remove_typedefs(signature)

Strips typedef info from a function signature

Parameters

signature (str) – function signature

Return type

str

Returns

string that can be used to construct function calls with the same variable names and ordering as in the function signature

amici.ode_export.smart_is_zero_matrix(x)

A faster implementation of sympy’s is_zero_matrix

Avoids repeated indexer type checks and double iteration to distinguish False/None. Found to be about 100x faster for large matrices.

Parameters

x (typing.Union[sympy.matrices.dense.MutableDenseMatrix, sympy.matrices.sparse.MutableSparseMatrix]) – Matrix to check

Return type

bool

amici.ode_export.smart_jacobian(eq, sym_var)

Wrapper around symbolic jacobian with some additional checks that reduce computation time for large matrices

Parameters

• eq (sympy.matrices.dense.MutableDenseMatrix) – equation

• sym_var (sympy.matrices.dense.MutableDenseMatrix) – differentiation variable

Return type

sympy.matrices.dense.MutableDenseMatrix

Returns

jacobian of eq wrt sym_var

amici.ode_export.smart_multiply(x, y)

Wrapper around symbolic multiplication with some additional checks that reduce computation time for large matrices

Parameters

• x (typing.Union[sympy.matrices.dense.MutableDenseMatrix, sympy.matrices.sparse.MutableSparseMatrix]) – educt 1

• y (sympy.matrices.dense.MutableDenseMatrix) – educt 2

Return type

typing.Union[sympy.matrices.dense.MutableDenseMatrix, sympy.matrices.sparse.MutableSparseMatrix]

Returns

product

amici.ode_export.smart_subs_dict(sym, subs, field=None, reverse=True)

Subsitutes expressions completely flattening them out. Requires sorting of expressions with toposort.

Parameters

• sym (sympy.core.expr.Expr) – Symbolic expression in which expressions will be substituted

• subs (typing.Dict[sympy.core.symbol.Symbol, typing.Union[typing.Dict[str, sympy.core.expr.Expr], sympy.core.expr.Expr]]) – Substitutions

• field (typing.Optional[str]) – Field of substitution expressions in subs.values(), if applicable

• reverse (bool) – Whether ordering in subs should be reversed. Note that substitution requires the reverse order of what is required for evaluation.

Return type

sympy.core.expr.Expr

Returns

Substituted symbolic expression

amici.ode_export.strip_pysb(symbol)

Strips pysb info from a pysb.Component object

Parameters

symbol (sympy.core.basic.Basic) – symbolic expression

Return type

sympy.core.basic.Basic

Returns

stripped expression

amici.ode_export.symbol_with_assumptions(name)

Central function to create symbols with consistent, canonical assumptions

Parameters

name (str) – name of the symbol

Returns

symbol with canonical assumptions

amici.ode_export.var_in_function_signature(name, varname)

Checks if the values for a symbolic variable is passed in the signature of a function

Parameters

• name (str) – name of the function

• varname (str) – name of the symbolic variable

Return type

bool

Returns

boolean indicating whether the variable occurs in the function signature