libSBML C++ API
5.18.0
|
Parses an SBML formula string into an AST. More...
Functions | |
ASTNode_t * | SBML_parseFormula (const char *formula) |
Parses the given SBML formula and returns a representation of it as an Abstract Syntax Tree (AST). More... | |
Parses an SBML formula string into an AST.
ASTNode_t* SBML_parseFormula | ( | const char * | formula | ) |
Parses the given SBML formula and returns a representation of it as an Abstract Syntax Tree (AST).
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) ≤ π |
asin | x | arc sine of x in radians | -1.0 ≤ x ≤ 1.0 | 0 ≤ asin(x) ≤ π |
atan | x | arc tangent of x in radians | 0 ≤ atan(x) ≤ π | |
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 | x2 | ||
sqrt | x | √x | x > 0 | sqrt(x) ≥ 0 |
sin | x | sine of x | ||
tan | x | tangent of x | x ≠ n*π/2, for odd integer n |
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.formula | the text-string formula expression to be parsed |
formula
, or NULL
if an error occurred in parsing the formula