mathml¶

MathML helpers for the math of a CellML component.

libsbml renders a formula as a complete MathML document, i.e., with an xml declaration and a math element. CellML takes the equations of a component as one math element, so the rendered fragments are stripped of the declaration and the element, combined, and wrapped in a math element which declares the cellml namespace for the units of numbers. The sbml:units attribute of libsbml becomes cellml:units.

CellML requires units on every number and only knows real and e-notation numbers: a number without units gets dimensionless, the units of a number with units become their CellML name (sbml2cellml.cellmlunits), integers and rationals become reals. CellML has no symbols either: the SBML time symbol becomes the variable of integration TIME_ID, avogadro its value. An n-ary operator with less than two arguments is replaced by its value. The negation of a product which starts with a negation is cancelled, libcellml generates code for it which does not compile (cancel_negations).

A formula is a libsbml AST, or text in the syntax of libsbml (k1 * S1), in which a name which is a symbol of the syntax (avogadro, pi, NaN, time) is that symbol and not an id of the model; the converter passes ASTs.

MathMLError ¶

Bases: ValueError

A formula cannot be rendered as MathML.

simplify_operators ¶

simplify_operators(node)

Replace n-ary operators with less than two arguments.

MathML allows plus, times, and, or and xor with one argument (the argument) and without any (the identity element), CellML requires two.

Parameters:

Name	Type	Description	Default
`node`	`ASTNode`	root of the libsbml AST of the formula, changed in place.	required

Returns:

Type	Description
`ASTNode`	The root, which is another node when the root itself was replaced.

normalize_math ¶

normalize_math(node, units=None, number_units=NUMBER_UNITS)

Make the numbers and symbols of a formula valid CellML, in place.

The time symbol becomes a reference to the variable of integration TIME_ID, avogadro a number with libsbml's value. Integers and rationals become reals, a finite number without units gets number_units, the units of a number with units their CellML name. A negative number becomes the negative of a number: the code libcellml generates for the negative of a negative number is --1.0, a decrement in C which does not compile. Infinity and NaN stay as they are, they are written as the infinity and notanumber constants, which have no units. The delay and rateOf symbols stay, CellML has no counterpart for them.

Parameters:

Name	Type	Description	Default
`node`	`ASTNode`	root of the libsbml AST of the formula.	required
`units`	`UnitsNames \| None`	CellML units of the SBML units of a number (`CellMLUnits.number_units`), the same name when `None`.	`None`
`number_units`	`str`	CellML units of a number without units.	`NUMBER_UNITS`

cancel_negations ¶

cancel_negations(node)

Cancel the negation of a product or quotient which starts with a negation.

libcellml 0.7.1 generates the code of a negated product without parentheses: -((-2) * a) becomes --2.0*a, a decrement in C, and the model does not compile in libopencor. -((-a) * b) is a * b and -((-a) / b) is a / b, exactly. A negative number is such a negation once normalize_math has run. Other negations are generated with parentheses and stay.

Parameters:

Name	Type	Description	Default
`node`	`ASTNode`	root of the libsbml AST of the formula, changed in place.	required

Returns:

Type	Description
`ASTNode`	The root, which is another node when the root itself was replaced.

process_mathml_for_cellml ¶

process_mathml_for_cellml(
    formula, units=None, number_units=NUMBER_UNITS
)

Render a formula as a MathML fragment for CellML.

Parameters:

Name	Type	Description	Default
`formula`	`Formula`	the AST of the formula, which is not changed, or the formula in the SBML level 3 infix syntax, e.g., `k1 * S1`.	required
`units`	`UnitsNames \| None`	CellML units of the SBML units of a number, see `normalize_math`.	`None`
`number_units`	`str`	CellML units of a number without units.	`NUMBER_UNITS`

Returns:

Type	Description
`str`	The MathML of the formula without xml declaration and `math` element,
`str`	with `cellml:units` on every finite number and the time and
`str`	avogadro symbols replaced (see `normalize_math`).

Raises:

Type	Description
`MathMLError`	if a formula given as text does not parse.

mathml_for_assignment ¶

mathml_for_assignment(
    vid, formula, units=None, number_units=NUMBER_UNITS
)

MathML of the assignment vid = formula.

Parameters:

Name	Type	Description	Default
`vid`	`str`	id of the assigned variable.	required
`formula`	`Formula`	right hand side, see `process_mathml_for_cellml`.	required
`units`	`UnitsNames \| None`	CellML units of the SBML units of a number, see `normalize_math`.	`None`
`number_units`	`str`	CellML units of a number without units, e.g. the units of `vid` when the formula is its value.	`NUMBER_UNITS`

Returns:

Type	Description
`str`	The `apply` element of the equation.

mathml_for_algebraic ¶

mathml_for_algebraic(formula, units=None)

MathML of the implicit equation 0 = formula.

Parameters:

Name	Type	Description	Default
`formula`	`Formula`	the expression which is zero, see `process_mathml_for_cellml`.	required
`units`	`UnitsNames \| None`	CellML units of the SBML units of a number, see `normalize_math`.	`None`

Returns:

Type	Description
`str`	The `apply` element of the equation.

mathml_for_diff ¶

mathml_for_diff(vid, formula, ivid='t', units=None)

MathML of the differential equation d vid / d ivid = formula.

Parameters:

Name	Type	Description	Default
`vid`	`str`	id of the state variable.	required
`formula`	`Formula`	right hand side, see `process_mathml_for_cellml`.	required
`ivid`	`str`	id of the variable of integration.	`'t'`
`units`	`UnitsNames \| None`	CellML units of the SBML units of a number, see `normalize_math`.	`None`

Returns:

Type	Description
`str`	The `apply` element of the equation.

cellml_math ¶

cellml_math(parts)

Combine equation fragments into the math element of a component.

Parameters:

Name	Type	Description	Default
`parts`	`list[str]`	`apply` elements, e.g., from `mathml_for_assignment`.	required

Returns:

Type	Description
`str`	The complete `math` element with the MathML and cellml namespaces.