FormulaFormatter.h File Reference

Formats an AST formula tree as an SBML formula string. More...

Include dependency graph for FormulaFormatter.h:

This graph shows which files directly or indirectly include this file:

Functions
char *	SBML_formulaToString (const ASTNode_t *tree)
	Converts an AST to a string representation of a formula using a syntax basically derived from SBML Level 1. More...

Detailed Description

Formats an AST formula tree as an SBML formula string.

Author

Ben Bornstein

Function Documentation

SBML_formulaToString()

char* SBML_formulaToString

(

const ASTNode_t *

tree

)

Converts an AST to a string representation of a formula using a syntax basically derived from SBML Level 1.

The text-string form of mathematical formulas produced by SBML_formulaToString() and read by SBML_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.

A table of the expression operators and their precedence in the text-string format for mathematical expressions used by SBML_parseFormula().

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:

The names of mathematical functions defined in the SBML Level 1 Version 2 text-string formula syntax.

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

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.

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 SBML_parseL3Formula() and SBML_formulaToL3String(). The Level 1-oriented system (i.e., what is provided by SBML_formulaToString() and SBML_parseFormula()) is provided untouched for backwards compatibility.

Parameters

tree	the AST to be converted.

Returns

the formula from the given AST as an SBML Level 1 text-string mathematical formula. The caller owns the returned string and is responsible for freeing it when it is no longer needed.

See also

SBML_formulaToL3String()

SBML_formulaToL3StringWithSettings()

SBML_parseL3FormulaWithSettings()

SBML_parseL3FormulaWithModel()

SBML_parseFormula()

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.