libSBML Perl API
libSBML 5.10.0 Perl API
|
Formats an L3 AST formula tree as an SBML formula string. More...
Functions | |
char * | SBML_formulaToL3String (const ASTNode_t *tree) |
Converts an AST to a string representation of a formula using a syntax derived from SBML Level 1, but extended to include elements from SBML Level 2 and SBML Level 3. More... | |
char * | SBML_formulaToL3StringWithSettings (const ASTNode_t *tree, const L3ParserSettings_t *settings) |
Converts an AST to a string representation of a formula using a syntax basically derived from SBML Level 1, with behavior modifiable with custom settings. More... | |
Formats an L3 AST formula tree as an SBML formula string.
char* SBML_formulaToL3String | ( | const ASTNode_t * | tree | ) |
Converts an AST to a string representation of a formula using a syntax derived from SBML Level 1, but extended to include elements from SBML Level 2 and SBML Level 3.
and
have been left untouched, and instead, the new functionality is provided in the form of
and.
The following are the differences in the formula syntax supported by the "L3" versions of the formula parsers and formatters, compared to what is supported by and:
SId
in the SBML specifications). The whitespace between number and unit is optional.&&
, ||
, !
, and !=
may be used.%
and will produce a piecewise function in the MathML.arc
as a prefix or simply a
; in other words, both arccsc
and acsc
are interpreted as the operator arccosecant defined in MathML. (Many functions in the SBML Level 1 infix-notation parser implemented by are defined this way as well, but not all.)(integer/integer)No spaces are allowed in this construct; in other words, "
(3 / 4)
" will be parsed into the MathML <divide>
construct rather than a rational number. The general number syntax allows you to assign units to a rational number, e.g., "(3/4) ml
". (If the string is a division, units are not interpreted in this way.)log
with a single argument ("log(x)
") can be parsed as log10(x)
, ln(x)
, or treated as an error, as desired. - -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. avogadro
can be parsed as a MathML csymbol or as an identifier. SId
) from that model are used in preference to pre-defined MathML definitions. More precisely, 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/>
. 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 with the identifier "sin
", that function will be used instead of the predefined MathML function <sin/>
. The parser function returns the root node of the AST corresponding to the formula given as the argument. If the formula contains a syntax error, the function will return NULL
instead. When NULL
is returned, an error is set; information about the error can be retrieved using Note that this facility and the SBML Level 1-based are provided as a convenience by libSBML—the MathML standard does not actually define a "string-form" equivalent to MathML expressions, so the choice of formula syntax is arbitrary. The approach taken by libSBML is to start with the syntax defined by SBML Level 1 (which in fact used a text-string representation of formulas, and not MathML), and expand it to include the above functionality. 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 | 8 | n/a |
( expression) | expression grouping | operand | 8 | n/a |
f( ...) | function call | prefix | 8 | left |
^ | power | binary | 7 | left |
-, ! | negation and boolean 'not' | unary | 6 | right |
*, /, % | multiplication, division, and modulo | binary | 5 | left |
+, - | addition and subtraction | binary | 4 | left |
==, <, >, <=, >=, != | boolean equality, inequality, and comparison | 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) ≤ π |
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) ≤ π |
atan , arctan |
x | Arctangent of x in radians. | 0 ≤ atan(x) ≤ π | |
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 | x2. | ||
sqrt |
x | √x. | x > 0 | sqrt(x) ≥ 0 |
sin |
x | Sine of x. | ||
sinh |
x | Hyperbolic sine of x. | ||
tan |
x | Tangent of x. | x ≠ n*π/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. |
Note that 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 and pass it an appropriate L3ParserSettings object. By default, unlike the SBML Level 1 parser implemented by, 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.
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 |
The boolean value true |
<true/> |
false |
The boolean value false |
<false/> |
pi |
The mathematical constant pi | <pi/> |
avogadro |
The numerical value of Avogadro's constant, as defined in the SBML specification | <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 or infinity |
The mathematical constant "infinity" | <infinity/> |
nan or notanumber |
The mathematical concept "not a number" | <notanumber/> |
Note that whether the string "avogadro
" is parsed as an AST node of type AST_NAME_AVOGADRO or AST_NAME is configurable; use the alternate version of this function, called. This functionality is provided because SBML Level 2 models may not use AST_NAME_AVOGADRO AST nodes.
tree | the AST to be converted. |
char* SBML_formulaToL3StringWithSettings | ( | const ASTNode_t * | tree, |
const L3ParserSettings_t * | settings | ||
) |
Converts an AST to a string representation of a formula using a syntax basically derived from SBML Level 1, with behavior modifiable with custom settings.
This function behaves identically to SBML_formulaToL3String(), but its behavior can be modified by two settings in the
settings | object, namely: |
All other settings will not affect the behavior of this function: the 'parseLog' setting is ignored, and "log10(x)", "ln(x)", and "log(x, y)" are always produced. Nothing in the Model object is used, and whether Avogadro is a csymbol or not is immaterial to the produced infix.
tree | the AST to be converted. |
settings | the L3ParserSettings object used to modify behavior. |