You should look at the API documentation for ASTNode class.
def readMathMLFromString(xml):
"""
readMathMLFromString(char const * xml) -> ASTNode
Reads the MathML from the given XML string, constructs a corresponding
abstract syntax tree, and returns a pointer to the root of the tree.
Parameter 'xml' is a string containing a full MathML expression.
Returns the root of an AST corresponding to the given mathematical
expression, otherwise 'None' is returned if the given string is 'None'
or invalid.
"""
return _libsbml.readMathMLFromString(xml)
def readMathMLFromStringWithNamespaces(xml, xmlns):
"""
readMathMLFromStringWithNamespaces(char const * xml, XMLNamespaces xmlns) -> ASTNode
Reads the MathML from the given XML string, constructs a corresponding
abstract syntax tree, and returns a pointer to the root of the tree.
Parameter 'xml' is a string containing a full MathML expression.
Parameter 'xmlns' is an XMLNamespaces object containing namespaces
that are considered active during the read. (For example, an SBML
Level 3 package namespace.)
Returns the root of an AST corresponding to the given mathematical
expression, otherwise 'None' is returned if the given string is 'None'
or invalid.
"""
return _libsbml.readMathMLFromStringWithNamespaces(xml, xmlns)
def writeMathMLToString(node):
"""
writeMathMLToString(ASTNode node) -> char *
Writes the given AST node (and its children) to a string as MathML,
and returns the string.
Parameter 'node' is the root of an AST to write out to the stream.
Returns a string containing the written-out MathML representation of
the given AST.
Note: The string is owned by the caller and should be freed (with
free()) when no longer needed. 'None' is returned if the given
argument is 'None.'
"""
return _libsbml.writeMathMLToString(node)
def writeMathMLWithNamespaceToString(node, sbmlns):
"""
writeMathMLWithNamespaceToString(ASTNode node, SBMLNamespaces sbmlns) -> char *
Writes the given AST node (and its children) to a string as MathML,
and returns the string.
Parameter 'node' is the root of an AST to write out to the stream.
Parameter 'sbmlns' is the SBML namespace to be used
Returns a string containing the written-out MathML representation of
the given AST.
Note: The string is owned by the caller and should be freed (with
free()) when no longer needed. 'None' is returned if the given
argument is 'None.'
"""
return _libsbml.writeMathMLWithNamespaceToString(node, sbmlns)
def parseFormula(formula):
"""
parseFormula(char const * formula) -> ASTNode
Parses a text string as a mathematical formula and returns an AST
representation of it.
The text-string form of mathematical formulas produced by
formulaToString() and read by parseFormula() use a simple C-inspired
infix notation taken from SBML Level 1. A formula in this text-string
form therefore can be handed to a program that understands SBML Level
1 mathematical expressions, or used as part of a formula translation
system. The syntax is described in detail in the documentation for
ASTNode. The following are illustrative examples of formulas
expressed using this syntax:
0.10 * k4^2
(vm * s1)/(km + s1)
Note that this facility is provided as a convenience by libSBML---the
MathML standard does not actually define a 'string-form' equivalent to
MathML expression trees, so the choice of formula syntax is somewhat
arbitrary. The approach taken by libSBML is to use the syntax defined
by SBML Level 1 (which in fact used a text-string representation of
formulas and not MathML). This formula syntax is based mostly on C
programming syntax, and may contain operators, function calls,
symbols, and white space characters. The following table provides the
precedence rules for the different entities that may appear in formula
strings.
+--------------+---------------------+---------+------------+------------+
| Token | Operation | Class | Precedence | Associates |
+--------------+---------------------+---------+------------+------------+
| name | symbol reference | operand | 6 | n/a |
| (expression) | expression grouping | operand | 6 | n/a |
| f(...) | function call | prefix | 6 | left |
| - | negation | unary | 5 | right |
| ^ | power | binary | 4 | left |
| * | multiplication | binary | 3 | left |
| / | divison | binary | 3 | left |
| + | addition | binary | 2 | left |
| - | subtraction | binary | 2 | left |
| , | argument delimiter | binary | 1 | left |
+--------------+---------------------+---------+------------+------------+
In the table above, operand implies the construct is an operand,
prefix implies the operation is applied to the following arguments,
unary implies there is one argument, and binary implies there are two
arguments. The values in the Precedence column show how the order of
different types of operation are determined. For example, the
expression a * b + c is evaluated as (a * b) + c because the '*'
operator has higher precedence. The Associates column shows how the
order of similar precedence operations is determined for example, a -
b + c is evaluated as (a - b) + c because the '+' and '-' operators
are left-associative.
The function call syntax consists of a function name, followed by
optional white space, followed by an opening parenthesis token,
followed by a sequence of zero or more arguments separated by commas
(with each comma optionally preceded and/or followed by zero or more
white space characters, followed by a closing parenthesis token. The
function name must be chosen from one of the pre-defined functions in
SBML or a user-defined function in the model. The following table
lists the names of certain common mathematical functions this table
corresponds to Table 6 in the SBML Level 1 Version 2 specification:
+-------+------+-------------------------------------------------------------------+--------------------------------+--------------------+
| Name | Args | Formula or meaning | Argument Constraints | Result constraints |
+-------+------+-------------------------------------------------------------------+--------------------------------+--------------------+
| abs | x | absolute value of x | | |
| acos | x | arc cosine of x in radians | -1.0 <= x <= 1.0 | 0 <= acos(x) <= Pi |
| asin | x | arc sine of x in radians | -1.0 <= x <= 1.0 | 0 <= asin(x) <= Pi |
| atan | x | arc tangent of x in radians | | 0 <= atan(x) <= Pi |
| ceil | x | smallest number not less than x whose value is an exact integer | | |
| cos | x | cosine of x | | |
| exp | x | e^x, where e is the base of the natural logarithm | | |
| floor | x | largest number not greater than x whose value is an exact integer | | |
| log | x | natural logarithm of x | x > 0 | |
| log10 | x | base 10 logarithm of x | x > 0 | |
| pow | x, y | x^y | | |
| sqr | x | x^2 | | |
| sqrt | x | &radicx | x > 0 | sqrt(x) >= 0 |
| sin | x | sine of x | | |
| tan | x | tangent of x | x != n*Pi/2, for odd integer n | |
+-------+------+-------------------------------------------------------------------+--------------------------------+--------------------+
WARNING:
There are differences between the symbols used to represent the common
mathematical functions and the corresponding MathML token names. This
is a potential source of incompatibilities. Note in particular that in
this text-string syntax, log(x) represents the natural logarithm,
whereas in MathML, the natural logarithm is <ln/>. Application
writers are urged to be careful when translating between text forms
and MathML forms, especially if they provide a direct text-string
input facility to users of their software systems.
Parameter 'formula' is the text-string formula expression to be
parsed.
Returns the root node of the AST corresponding to the 'formula', or
'None' if an error occurred in parsing the formula
See also parseL3Formula(), formulaToString(), formulaToL3String(),
formulaToL3StringWithSettings(), parseL3FormulaWithSettings(),
parseL3FormulaWithModel(), L3ParserSettings.
Note: Callers using SBML Level 3 are encouraged to use the facilities
provided by libSBML's newer and more powerful Level 3-oriented formula
parser and formatter. The entry points to this second system are
parseL3Formula() and formulaToL3String(). The Level 1-oriented system
(i.e., what is provided by formulaToString() and parseFormula()) is
provided untouched for backwards compatibility.
Note: We urge developers to keep in mind that the text-string formula
syntax is specific to libSBML. Neither MathML nor SBML define a text-
string format for mathematical formulas. LibSBML's particular syntax
should not be considered to be a canonical or standard general-purpose
mathematical expression syntax. LibSBML provides methods for parsing
and transforming text-string math formulas back and forth from AST
structures for the convenience of calling applications, but it is
important to keep the system's limitations in mind.
"""
return _libsbml.parseFormula(formula)
def formulaToL3String(tree):
"""
formulaToL3String(ASTNode tree) -> char *
Converts an AST to a text string representation of a formula using an
extended syntax.
The text-string form of mathematical formulas read by the function
parseL3Formula() and written by the function formulaToL3String() uses
an expanded version of the syntax read and written by parseFormula()
and formulaToString(), respectively. The latter two libSBML functions
were originally developed to support conversion between SBML Levels 1
and 2, and were focused on the syntax of mathematical formulas used in
SBML Level 1. With time, and the use of MathML in SBML Levels 2 and
3, it became clear that supporting Level 2 and 3's expanded
mathematical syntax would be useful for software developers. To
maintain backwards compatibility for libSBML users, the original
formulaToString() and parseFormula() have been left untouched, and
instead, the new functionality is provided in the form of
parseL3Formula() and formulaToL3String().
The following lists the main differences in the formula syntax
supported by the Level 3 ('L3') versions of the formula parsers and
formatters, compared to what is supported by the Level 1-oriented
parseFormula() and formulaToString():
* Units may be asociated with bare numbers, using the following
syntax:
number unit
The number may be in any form (an integer, real, or rational number),
and the unit must conform to the syntax of an SBML identifier
(technically, the type defined as 'SId' in the SBML specifications).
The whitespace between number and unit is optional.
* The Boolean function symbols '&&' (and), '||' (or), '!' (not),
and '!=' (not equals) may be used.
* The modulo operation is allowed as the symbol '%' and will
produce a <piecewise> function in the corresponding MathML output by
default, or can produce the MathML function 'rem,' depending on the
L3ParserSettings object (see L3ParserSettings_setParseModuloL3v2() ).
* All inverse trigonometric functions may be defined in the infix
either using 'arc' as a prefix or simply 'a' in other words, both
'arccsc' and 'acsc' are interpreted as the operator arccosecant as
defined in MathML 2.0. (Many functions in the simpler SBML Level 1
oriented parser implemented by parseFormula() are defined this way as
well, but not all.)
* The following expression is parsed as a rational number instead
of as a numerical division:
(integer/integer)
Spaces are not allowed in this construct in other words, "(3 / 4)"
(with whitespace between the numbers and the operator) will be parsed
into the MathML <divide> construct rather than a rational number. You
can, however, assign units to a rational number as a whole here is an
example: "(3/4) ml". (In the case of division rather than a rational
number, units are not interpreted in this way.)
* Various parser and formatter behaviors may be altered through
the use of a L3ParserSettings object in conjunction with the functions
parseL3FormulaWithSettings() and formulaToL3StringWithSettings() The
settings available include the following:
* The function 'log' with a single argument ("log(x)") can be parsed
as log10(x), ln(x), or treated as an error, as desired.
* Unary minus signs can be collapsed or preserved that is, sequential
pairs of unary minuses (e.g., "- -3") can be removed from the input
entirely and single unary minuses can be incorporated into the number
node, or all minuses can be preserved in the AST node structure.
* Parsing of units embedded in the input string can be turned on and
off.
* The string 'avogadro' can be parsed as a MathML csymbol or as an
identifier.
* The string % can be parsed either as a piecewise function or as the
'rem' function: a % b will either become
piecewise(a - b*ceil(a/b), xor((a < 0), (b < 0)), a - b*floor(a/b))
or
rem(a, b).
The latter is simpler, but the 'rem' MathML is only allowed as of SBML
Level 3 Version 2.* A Model object may optionally be provided to the
parser using the variant function call parseL3FormulaWithModel() or
stored in a L3ParserSettings object passed to the variant function
parseL3FormulaWithSettings(). When a Model object is provided,
identifiers (values of type 'SId' ) from that model are used in
preference to pre-defined MathML definitions for both symbols and
functions. More precisely:
* In the case of symbols: the Model entities whose identifiers will
shadow identical symbols in the mathematical formula are: Species,
Compartment, Parameter, Reaction, and SpeciesReference. For instance,
if the parser is given a Model containing a Species with the
identifier "pi", and the formula to be parsed is "3*pi", the
MathML produced will contain the construct <ci> pi </ci> instead of
the construct <pi/>.
* In the case of user-defined functions: when a Model object is
provided, 'SId' values of user-defined functions present in the model
will be used preferentially over pre-defined MathML functions. For
example, if the passed-in Model contains a FunctionDefinition object
with the identifier "sin", that function will be used instead of the
predefined MathML function <sin/>.
* An SBMLNamespaces object may optionally be provided to identify
SBML Level 3 packages that extend the syntax understood by the formula
parser. When the namespaces are provided, the parser will interpret
possible additional syntax defined by the libSBML plug-ins
implementing the SBML Level 3 packages for example, it may understand
vector/array extensions introduced by the SBML Level 3 Arrays package.
These configuration settings cannot be changed directly using the
basic parser and formatter functions, but can be changed on a per-call
basis by using the alternative functions parseL3FormulaWithSettings()
and formulaToL3StringWithSettings().
Neither SBML nor the MathML standard define a 'string-form' equivalent
to MathML expressions. The approach taken by libSBML is to start with
the formula syntax defined by SBML Level 1 (which in fact used a
custom text-string representation of formulas, and not MathML), and
expand it to include the functionality described above. This formula
syntax is based mostly on C programming syntax, and may contain
operators, function calls, symbols, and white space characters. The
following table provides the precedence rules for the different
entities that may appear in formula strings.
+----------------------+--------------------------+---------+---------+--------+
| Token | Operation | Class | Preced. | Assoc. |
+----------------------+--------------------------+---------+---------+--------+
| name | symbol reference | operand | 8 | n/a |
| (expression) | expression grouping | operand | 8 | n/a |
| f(...) | function call | prefix | 8 | left |
| ^ | power | binary | 7 | left |
| -, ! | negation, Boolean 'not' | unary | 6 | right |
| *, /, % | multip., div., modulo | binary | 5 | left |
| +, - | addition and subtraction | binary | 4 | left |
| ==, <, >, <=, >=, != | Boolean comparisons | binary | 3 | left |
| &&, || | Boolean 'and' and 'or' | binary | 2 | left |
| , | argument delimiter | binary | 1 | left |
+----------------------+--------------------------+---------+---------+--------+
In the table above, operand implies the construct is an operand,
prefix implies the operation is applied to the following arguments,
unary implies there is one argument, and binary implies there are two
arguments. The values in the Precedence column show how the order of
different types of operation are determined. For example, the
expression a + b * c is evaluated as a + (b * c) because the '*'
operator has higher precedence. The Associates column shows how the
order of similar precedence operations is determined for example, a
&& b || c is evaluated as (a && b) || c because the '&&' and '||'
operators are left-associative and have the same precedence.
The function call syntax consists of a function name, followed by
optional white space, followed by an opening parenthesis token,
followed by a sequence of zero or more arguments separated by commas
(with each comma optionally preceded and/or followed by zero or more
white space characters), followed by a closing parenthesis token. The
function name must be chosen from one of the pre-defined functions in
SBML or a user-defined function in the model. The following table
lists the names of certain common mathematical functions this table
corresponds to Table 6 in the SBML Level 1 Version 2 specification
with additions based on the functions added in SBML Level 2 and Level
3:
+----------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------+--------------------+
| Name | Argument(s) | Formula or meaning | Argument Constraints | Result constraints |
+----------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------+--------------------+
| abs | x | Absolute value of x. | | |
| acos, arccos | x | Arccosine of x in radians. | -1.0 <= x <= 1.0 | 0 <= acos(x) <= Pi |
| acosh, arccosh | x | Hyperbolic arccosine of x in radians. | | |
| acot, arccot | x | Arccotangent of x in radians. | | |
| acoth, arccoth | x | Hyperbolic arccotangent of x in radians. | | |
| acsc, arccsc | x | Arccosecant of x in radians. | | |
| acsch, arccsch | x | Hyperbolic arccosecant of x in radians. | | |
| asec, arcsec | x | Arcsecant of x in radians. | | |
| asech, arcsech | x | Hyperbolic arcsecant of x in radians. | | |
| asin, arcsin | x | Arcsine of x in radians. | -1.0 <= x <= 1.0 | 0 <= asin(x) <= Pi |
| atan, arctan | x | Arctangent of x in radians. | | 0 <= atan(x) <= Pi |
| atanh, arctanh | x | Hyperbolic arctangent of x in radians. | | |
| ceil, ceiling | x | Smallest number not less than x whose value is an exact integer. | | |
| cos | x | Cosine of x | | |
| cosh | x | Hyperbolic cosine of x. | | |
| cot | x | Cotangent of x. | | |
| coth | x | Hyperbolic cotangent of x. | | |
| csc | x | Cosecant of x. | | |
| csch | x | Hyperbolic cosecant of x. | | |
| delay | x, y | The value of x at y time units in the past. | | |
| factorial | n | The factorial of n. Factorials are defined by n! = n*(n-1)* ... * 1. | n must be an integer. | |
| exp | x | e^x, where e is the base of the natural logarithm. | | |
| floor | x | The largest number not greater than x whose value is an exact integer. | | |
| ln | x | Natural logarithm of x. | x > 0 | |
| log | x | By default, the base 10 logarithm of x, but can be set to be the natural logarithm of x, or to be an illegal construct. | x > 0 | |
| log | x, y | The base x logarithm of y. | y > 0 | |
| log10 | x | Base 10 logarithm of x. | x > 0 | |
| piecewise | x1, y1, [x2, y2,] [...] [z] | A piecewise function: if (y1), x1. Otherwise, if (y2), x2, etc. Otherwise, z. | y1, y2, y3 [etc] must be Boolean | |
| pow, power | x, y | x^y. | | |
| root | b, x | The root base b of x. | | |
| sec | x | Secant of x. | | |
| sech | x | Hyperbolic secant of x. | | |
| sqr | x | x^2. | | |
| sqrt | x | &radicx. | x > 0 | sqrt(x) >= 0 |
| sin | x | Sine of x. | | |
| sinh | x | Hyperbolic sine of x. | | |
| tan | x | Tangent of x. | x != n*Pi/2, for odd integer n | |
| tanh | x | Hyperbolic tangent of x. | | |
| and | x, y, z... | Boolean and(x, y, z...): returns true if all of its arguments are true. Note that and is an n-ary function, taking 0 or more arguments, and that and() returns true. | All arguments must be Boolean | |
| not | x | Boolean not(x) | x must be Boolean | |
| or | x, y, z... | Boolean or(x, y, z...): returns true if at least one of its arguments is true. Note that or is an n-ary function, taking 0 or more arguments, and that or() returns false. | All arguments must be Boolean | |
| xor | x, y, z... | Boolean xor(x, y, z...): returns true if an odd number of its arguments is true. Note that xor is an n-ary function, taking 0 or more arguments, and that xor() returns false. | All arguments must be Boolean | |
| eq | x, y, z... | Boolean eq(x, y, z...): returns true if all arguments are equal. Note that eq is an n-ary function, but must take 2 or more arguments. | | |
| geq | x, y, z... | Boolean geq(x, y, z...): returns true if each argument is greater than or equal to the argument following it. Note that geq is an n-ary function, but must take 2 or more arguments. | | |
| gt | x, y, z... | Boolean gt(x, y, z...): returns true if each argument is greater than the argument following it. Note that gt is an n-ary function, but must take 2 or more arguments. | | |
| leq | x, y, z... | Boolean leq(x, y, z...): returns true if each argument is less than or equal to the argument following it. Note that leq is an n-ary function, but must take 2 or more arguments. | | |
| lt | x, y, z... | Boolean lt(x, y, z...): returns true if each argument is less than the argument following it. Note that lt is an n-ary function, but must take 2 or more arguments. | | |
| neq | x, y | Boolean x != y: returns true unless x and y are equal. | | |
| plus | x, y, z... | x + y + z + ...: The sum of the arguments of the function. Note that plus is an n-ary function taking 0 or more arguments, and that plus() returns 0. | | |
| times | x, y, z... | x * y * z * ...: The product of the arguments of the function. Note that times is an n-ary function taking 0 or more arguments, and that times() returns 1. | | |
| minus | x, y | x - y. | | |
| divide | x, y | x / y. | | |
+----------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------+--------------------+
Parsing of the various MathML functions and constants are all case-
insensitive by default: function names such as cos, Cos and COS are
all parsed as the MathML cosine operator, <cos>. However, when a
Model object is used in conjunction with either
parseL3FormulaWithModel() or parseL3FormulaWithSettings(), any
identifiers found in that model will be parsed in a case-sensitive
way. For example, if a model contains a Species having the identifier
Pi, the parser will parse "Pi" in the input as "<ci> Pi </ci>" but
will continue to parse the symbols "pi" and "PI" as "<pi>".
As mentioned above, the manner in which the 'L3' versions of the
formula parser and formatter interpret the function "log" can be
changed. To do so, callers should use the function
parseL3FormulaWithSettings() and pass it an appropriate
L3ParserSettings object. By default, unlike the SBML Level 1 parser
implemented by parseFormula(), the string "log" is interpreted as
the base 10 logarithm, and not as the natural logarithm. However, you
can change the interpretation to be base-10 log, natural log, or as an
error since the name 'log' by itself is ambiguous, you require that
the parser uses 'log10' or 'ln' instead, which are more clear. Please
refer to parseL3FormulaWithSettings().
In addition, the following symbols will be translated to their MathML
equivalents, if no symbol with the same 'SId' identifier string exists
in the Model object provided:
+-----------------+-------------------------------------------------+--------------------------------------------------------------------------------------------------------------+
| Name | Meaning | MathML |
+-----------------+-------------------------------------------------+--------------------------------------------------------------------------------------------------------------+
| true | Boolean value true | <true/> |
| false | Boolean value false | <false/> |
| pi | Mathematical constant pi | <pi/> |
| avogadro | Value of Avogadro's constant stipulated by SBML | <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/avogadro"> avogadro </csymbol/> |
| time | Simulation time as defined in SBML | <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/time"> time </csymbol/> |
| inf, infinity | Mathematical constant "infinity" | <infinity/> |
| nan, notanumber | Mathematical concept "not a number" | <notanumber/> |
+-----------------+-------------------------------------------------+--------------------------------------------------------------------------------------------------------------+
Again, as mentioned above, whether the string "avogadro" is parsed
as an AST node of type AST_NAME_AVOGADRO or AST_NAME is configurable
use the version of the parser function called
parseL3FormulaWithSettings(). This Avogadro-related functionality is
provided because SBML Level 2 models may not use AST_NAME_AVOGADRO AST
nodes.
Parameter 'tree' is the AST to be converted.
Returns the formula from the given AST as text string, with a syntax
oriented towards the capabilities defined in SBML Level 3. The caller
owns the returned string and is responsible for freeing it when it is
no longer needed. If 'tree' is a null pointer, then a null pointer is
returned.
See also formulaToL3StringWithSettings(), formulaToString(),
parseL3FormulaWithSettings(), parseL3FormulaWithModel(),
parseFormula(), L3ParserSettings, getDefaultL3ParserSettings(),
getLastParseL3Error().
"""
return _libsbml.formulaToL3String(tree)