Detailed Description

Abstract Syntax Tree (AST) representation of a mathematical expression.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

Abstract Syntax Trees (ASTs) are a simple kind of data structure used in libSBML for storing mathematical expressions. The ASTNode_t is the cornerstone of libSBML's AST representation. An AST "node" represents the most basic, indivisible part of a mathematical formula and come in many types. For instance, there are node types to represent numbers (with subtypes to distinguish integer, real, and rational numbers), names (e.g., constants or variables), simple mathematical operators, logical or relational operators and functions. LibSBML ASTs provide a canonical, in-memory representation for all mathematical formulas regardless of their original format (which might be MathML or might be text strings).

: An AST node in libSBML is a recursive tree structure; each node has a type, a pointer to a value, and a list of children nodes. Each ASTNode_t node may have none, one, two, or more children depending on its type. There are node types to represent numbers (with subtypes to distinguish integer, real, and rational numbers), names (e.g., constants or variables), simple mathematical operators, logical or relational operators and functions. The following diagram illustrates an example of how the mathematical expression "1 + 2" is represented as an AST with one plus node having two integer children nodes for the numbers 1 and 2. The figure also shows the corresponding MathML representation:

Example AST representation of a mathematical expression.
Infix	AST	MathML
`1 + 2`		`<math xmlns="http://www.w3.org/1998/Math/MathML">` `<apply>` `<plus/>` `<cn type="integer"> 1 </cn>` `<cn type="integer"> 2 </cn>` `</apply>` `</math>`

The following are other noteworthy points about the AST representation in libSBML:

A numerical value represented in MathML as a real number with an exponent is preserved as such in the AST node representation, even if the number could be stored in a double data type. This is done so that when an SBML model is read in and then written out again, the amount of change introduced by libSBML to the SBML during the round-trip activity is minimized.

Rational numbers are represented in an AST node using separate numerator and denominator values. These can be retrieved using the methods ASTNode_t::getNumerator() and ASTNode_t::getDenominator().

The children of an ASTNode_t are other ASTNode_t objects. The list of children is empty for nodes that are leaf elements, such as numbers. For nodes that are actually roots of expression subtrees, the list of children points to the parsed objects that make up the rest of the expression.

For many applications, the details of ASTs are irrelevant because libSBML provides text-string based translation functions such as SBML_formulaToL3String() and SBML_parseL3Formula(). If you find the complexity of using the AST representation of expressions too high for your purposes, perhaps the string-based functions will be more suitable.

ASTNodeType_t

: Every ASTNode_t has an associated type code to indicate whether, for example, it holds a number or stands for an arithmetic operator. The type is recorded as a value drawn from the enumeration ASTNodeType_t. The list of possible types is quite long, because it covers all the mathematical functions that are permitted in SBML. The values are shown in the following table:

AST_CONSTANT_E	AST_FUNCTION_CSC	AST_LOGICAL_AND
AST_CONSTANT_FALSE	AST_FUNCTION_CSCH	AST_LOGICAL_IMPLIES²
AST_CONSTANT_PI	AST_FUNCTION_DELAY	AST_LOGICAL_NOT
AST_CONSTANT_TRUE	AST_FUNCTION_EXP	AST_LOGICAL_OR
AST_DIVIDE	AST_FUNCTION_FACTORIAL	AST_LOGICAL_XOR
AST_FUNCTION	AST_FUNCTION_FLOOR	AST_MINUS
AST_FUNCTION_ABS	AST_FUNCTION_LN	AST_NAME
AST_FUNCTION_ARCCOS	AST_FUNCTION_LOG	AST_NAME_AVOGADRO¹
AST_FUNCTION_ARCCOSH	AST_FUNCTION_MAX²	AST_NAME_TIME
AST_FUNCTION_ARCCOT	AST_FUNCTION_MIN²	AST_ORIGINATES_IN_PACKAGE²
AST_FUNCTION_ARCCOTH	AST_FUNCTION_PIECEWISE	AST_PLUS
AST_FUNCTION_ARCCSC	AST_FUNCTION_POWER	AST_POWER
AST_FUNCTION_ARCCSCH	AST_FUNCTION_QUOTIENT²	AST_RATIONAL
AST_FUNCTION_ARCSEC	AST_FUNCTION_RATE_OF²	AST_REAL
AST_FUNCTION_ARCSECH	AST_FUNCTION_REM²	AST_REAL_E
AST_FUNCTION_ARCSIN	AST_FUNCTION_ROOT	AST_RELATIONAL_EQ
AST_FUNCTION_ARCSINH	AST_FUNCTION_SEC	AST_RELATIONAL_GEQ
AST_FUNCTION_ARCTAN	AST_FUNCTION_SECH	AST_RELATIONAL_GT
AST_FUNCTION_ARCTANH	AST_FUNCTION_SIN	AST_RELATIONAL_LEQ
AST_FUNCTION_CEILING	AST_FUNCTION_SINH	AST_RELATIONAL_LT
AST_FUNCTION_COS	AST_FUNCTION_TAN	AST_RELATIONAL_NEQ
AST_FUNCTION_COSH	AST_FUNCTION_TANH	AST_TIMES
AST_FUNCTION_COT	AST_INTEGER	AST_UNKNOWN
AST_FUNCTION_COTH	AST_LAMBDA
¹ (Level 3 only)
² (Level 3 Version 2+ only)

The types have the following meanings:

If the node is basic mathematical operator (e.g., "+"), then the node's type will be AST_PLUS, AST_MINUS, AST_TIMES, AST_DIVIDE, or AST_POWER, as appropriate.

If the node is a predefined function or operator from SBML Level 1 (in the string-based formula syntax used in Level 1) or SBML Level 2 and 3 (in the subset of MathML used in SBML Levels 2 and 3), then the node's type will be either AST_FUNCTION_X, AST_LOGICAL_X, or AST_RELATIONAL_X, as appropriate. (Examples: AST_FUNCTION_LOG, AST_RELATIONAL_LEQ.)

If the node refers to a user-defined function, the node's type will be AST_FUNCTION (because it holds the name of the function).

If the node is a lambda expression, its type will be AST_LAMBDA.

If the node is a predefined constant ("ExponentialE", "Pi", "True" or "False"), then the node's type will be AST_CONSTANT_E, AST_CONSTANT_PI, AST_CONSTANT_TRUE, or AST_CONSTANT_FALSE.

(Levels 2 and 3 only) If the node is the special MathML csymbol time, the value of the node will be AST_NAME_TIME. (Note, however, that the MathML csymbol delay is translated into a node of type AST_FUNCTION_DELAY. The difference is due to the fact that time is a single variable, whereas delay is actually a function taking arguments.)

(Level 3 only) If the node is the special MathML csymbol avogadro, the value of the node will be AST_NAME_AVOGADRO.

(Level 3 Version 2+ only) If the node is the special MathML csymbol rateOf, the value of the node will be AST_FUNCTION_RATE_OF.

(Level 3 Version 2+ only) If the node is a MathML operator that originates in a package, it is included in the ASTNodeType_t list, but may not be legally used in an SBML document that does not include that package. This includes the node types from the 'Distributions' package (AST_DISTRIB_FUNCTION_NORMAL, AST_DISTRIB_FUNCTION_UNIFORM, etc.), and elements from MathML that were not included in core.

If the node contains a numerical value, its type will be AST_INTEGER, AST_REAL, AST_REAL_E, or AST_RATIONAL, as appropriate.

Converting between ASTs and text strings

The text-string form of mathematical formulas produced by SBML_formulaToString() and read by SBML_parseFormula() and SBML_parseL3Formula() are in a simple C-inspired infix notation. A formula in this text-string form can be handed to a program that understands SBML mathematical expressions, or used as part of a translation system. The libSBML distribution comes with an example program in the "examples" subdirectory called translateMath that implements an interactive command-line demonstration of translating infix formulas into MathML and vice-versa.

The formula strings may contain operators, function calls, symbols, and white space characters. The allowable white space characters are tab and space. The following are illustrative examples of formulas expressed in the syntax:

0.10 * k4^2

(vm * s1)/(km + s1)

The following table shows the precedence rules in this syntax. In the Class column, 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 precedence and associativity rules are taken from the C programming language, except for the symbol ^, which is used in C for a different purpose. (Exponentiation can be invoked using either ^ or the function power.)

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

A program parsing a formula in an SBML model should assume that names appearing in the formula are the identifiers of Species_t, Parameter_t, Compartment_t, FunctionDefinition_t, Reaction_t (in SBML Levels 2 and 3), or SpeciesReference_t (in SBML Level 3 only) objects defined in a model. When a function call is involved, the syntax consists of a function identifier, followed by optional white space, followed by an opening parenthesis, 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. There is an almost one-to-one mapping between the list of predefined functions available, and those defined in MathML. All of the MathML functions are recognized; this set is larger than the functions defined in SBML Level 1. In the subset of functions that overlap between MathML and SBML Level 1, there exist a few differences. The following table summarizes the differences between the predefined functions in SBML Level 1 and the MathML equivalents in SBML Levels 2 and 3:

Table comparing the names of certain functions in the SBML text-string formula syntax and MathML. The left column shows the names of functions recognized by SBML_parseFormula(); the right column shows their equivalent function names in MathML 2.0, used in SBML Levels 2 and 3.
Text string formula functions	MathML equivalents in SBML Levels 2 and 3
`acos`	`arccos`
`asin`	`arcsin`
`atan`	`arctan`
`ceil`	`ceiling`
`log`	`ln`
`log10(x)`	`log(x)` or `log(10, x)`
`pow(x, y)`	`power(x, y)`
`sqr(x)`	`power(x, 2)`
`sqrt(x)`	`root(x)` or `root(2, x)`

See also: SBML_parseL3Formula(); SBML_parseFormula()

Examples:: createExampleSBML.c, printMath.c, translateL3Math.c, and translateMath.c.

Public Member Functions
int	ASTNode_addChild (ASTNode_t node, ASTNode_t disownedChild)
	Adds a node as a child of another node. More...

int	ASTNode_addSemanticsAnnotation (ASTNode_t node, XMLNode_t disownedAnnotation)
	Adds a given XML node structure as a MathML semantic annotation of a given ASTNode_t structure. More...

int	ASTNode_canonicalize (ASTNode_t *node)
	Converts a given node to a canonical form and returns `1` if successful, `0` otherwise. More...

ASTNode_t *	ASTNode_create (void)
	Creates a new ASTNode_t structure and returns a pointer to it. More...

ASTNode_t *	ASTNode_createFromToken (Token_t *token)
	Creates a new ASTNode_t structure from the given Token_t data and returns a pointer to it. More...

ASTNode_t *	ASTNode_createWithType (ASTNodeType_t type)
	Creates a new ASTNode_t structure and sets its type. More...

ASTNode_t *	ASTNode_deepCopy (const ASTNode_t *node)
	Creates a recursive copy of a node and all its children. More...

void	ASTNode_fillListOfNodes (const ASTNode_t node, ASTNodePredicate predicate, List_t lst)
	Returns a list of nodes rooted at a given node and satisfying a given predicate. More...

void	ASTNode_free (ASTNode_t *node)
	Frees the given ASTNode_t structure, including any child nodes. More...

int	ASTNode_freeName (ASTNode_t *node)
	Frees the name field of a given node and sets it to null. More...

char	ASTNode_getCharacter (const ASTNode_t *node)
	Gets the value of a node as a single character. More...

ASTNode_t *	ASTNode_getChild (const ASTNode_t *node, unsigned int n)
	Gets a child of a node according to its index number. More...

char *	ASTNode_getClass (const ASTNode_t *node)
	Returns the MathML "class" attribute of a given node. More...

XMLAttributes_t *	ASTNode_getDefinitionURL (ASTNode_t *node)
	Returns the MathML "definitionURL" attribute value of the given node. More...

char *	ASTNode_getDefinitionURLString (ASTNode_t *node)
	Returns the MathML "definitionURL" attribute value of the given node as a string. More...

long	ASTNode_getDenominator (const ASTNode_t *node)
	Gets the numerator value of a node representing a rational number. More...

long	ASTNode_getExponent (const ASTNode_t *node)
	Get the exponent value of a node. More...

char *	ASTNode_getId (const ASTNode_t *node)
	Returns the MathML "id" attribute of a given node. More...

long	ASTNode_getInteger (const ASTNode_t *node)
	Gets the value of a node as an integer. More...

ASTNode_t *	ASTNode_getLeftChild (const ASTNode_t *node)
	Returns the left-most child of a given node. More...

List_t *	ASTNode_getListOfNodes (const ASTNode_t *node, ASTNodePredicate predicate)
	Returns a list of nodes rooted at a given node and satisfying a given predicate. More...

double	ASTNode_getMantissa (const ASTNode_t *node)
	Get the mantissa value of a node. More...

const char *	ASTNode_getName (const ASTNode_t *node)
	Gets the value of a node as a string. More...

unsigned int	ASTNode_getNumChildren (const ASTNode_t *node)
	Returns the number of children of a given node. More...

long	ASTNode_getNumerator (const ASTNode_t *node)
	Gets the numerator value of a node representing a rational number. More...

unsigned int	ASTNode_getNumSemanticsAnnotations (ASTNode_t *node)
	Returns the number of MathML semantic annotations inside the given node. More...

SBase_t *	ASTNode_getParentSBMLObject (ASTNode_t *node)
	Returns the parent SBML structure containing the given node. More...

int	ASTNode_getPrecedence (const ASTNode_t *node)
	Gets the precedence of a node in the infix math syntax of SBML Level 1. More...

double	ASTNode_getReal (const ASTNode_t *node)
	Get the real-numbered value of a node. More...

ASTNode_t *	ASTNode_getRightChild (const ASTNode_t *node)
	Returns the right-most child of a given node. More...

XMLNode_t *	ASTNode_getSemanticsAnnotation (ASTNode_t *node, unsigned int n)
	Returns the nth MathML semantic annotation attached to the given node. More...

char *	ASTNode_getStyle (const ASTNode_t *node)
	Returns the MathML "style" attribute of a given node. More...

ASTNodeType_t	ASTNode_getType (const ASTNode_t *node)
	Returns the type of the given node. More...

char *	ASTNode_getUnits (const ASTNode_t *node)
	Returns the SBML "units" attribute of a given node. More...

void *	ASTNode_getUserData (const ASTNode_t *node)
	Returns the user data associated with this node. More...

double	ASTNode_getValue (const ASTNode_t *node)
	Returns the numerical value of this ASTNode_t. More...

int	ASTNode_hasCorrectNumberArguments (ASTNode_t *node)
	Returns true if the given node has the correct number of children for its type. More...

int	ASTNode_hasTypeAndNumChildren (const ASTNode_t *node, ASTNodeType_t type, unsigned int numchildren)
	Returns true if the given node is of a specific type and has a specific number of children. More...

int	ASTNode_hasUnits (const ASTNode_t *node)
	Returns true if the given node or any of its children have the SBML "units" attribute set. More...

int	ASTNode_insertChild (ASTNode_t node, unsigned int n, ASTNode_t disownedChild)
	Insert a new child node at a given point in the list of children of a node. More...

int	ASTNode_isAvogadro (const ASTNode_t *node)
	Returns true if the given node represents the special symbol `avogadro`. More...

int	ASTNode_isBoolean (const ASTNode_t *node)
	Returns true if this node is some type of Boolean value or operator. More...

int	ASTNode_isConstant (const ASTNode_t *node)
	Returns true if the given node represents a MathML constant. More...

int	ASTNode_isConstantNumber (const ASTNode_t *node)
	Returns true if the given node represents a MathML constant. More...

int	ASTNode_isFunction (const ASTNode_t *node)
	Returns true if the given node represents a function. More...

int	ASTNode_isInfinity (const ASTNode_t *node)
	Returns true if the given node stands for infinity. More...

int	ASTNode_isInteger (const ASTNode_t *node)
	Returns true if the given node contains an integer value. More...

int	ASTNode_isLambda (const ASTNode_t *node)
	Returns true if the given node is a MathML lambda function. More...

int	ASTNode_isLog10 (const ASTNode_t *node)
	Returns true if the given node represents the log base-10 function. More...

int	ASTNode_isLogical (const ASTNode_t *node)
	Returns true if the given node is a logical operator. More...

int	ASTNode_isName (const ASTNode_t *node)
	Returns true if the given node is a named entity. More...

int	ASTNode_isNaN (const ASTNode_t *node)
	Returns true if the given node represents not-a-number. More...

int	ASTNode_isNegInfinity (const ASTNode_t *node)
	Returns true if the given node represents negative infinity. More...

int	ASTNode_isNumber (const ASTNode_t *node)
	Returns true if the given node contains a number. More...

int	ASTNode_isOperator (const ASTNode_t *node)
	Returns true if the given node is a mathematical operator. More...

int	ASTNode_isPiecewise (const ASTNode_t *node)
	Returns true if the given node represents the MathML `<piecewise>` operator. More...

int	ASTNode_isRational (const ASTNode_t *node)
	Returns true if the given node represents a rational number. More...

int	ASTNode_isReal (const ASTNode_t *node)
	Returns true if the given node represents a real number. More...

int	ASTNode_isRelational (const ASTNode_t *node)
	Returns true if the given node represents a MathML relational operator. More...

int	ASTNode_isSetClass (const ASTNode_t *node)
	Returns true if the given node's MathML "class" attribute is set. More...

int	ASTNode_isSetId (const ASTNode_t *node)
	Returns true if the given node's MathML "id" attribute is set. More...

int	ASTNode_isSetParentSBMLObject (ASTNode_t *node)
	Returns true if the given node's parent SBML object is set. More...

int	ASTNode_isSetStyle (const ASTNode_t *node)
	Returns true if the given node's MathML "style" attribute is set. More...

int	ASTNode_isSetUnits (const ASTNode_t *node)
	Returns true if this node's SBML "units" attribute is set. More...

int	ASTNode_isSetUserData (const ASTNode_t *node)
	Returns true if the given node's user data object is set. More...

int	ASTNode_isSqrt (const ASTNode_t *node)
	Returns true if the given node is the MathML square-root operator. More...

int	ASTNode_isUMinus (const ASTNode_t *node)
	Returns true if the given node represents a unary minus. More...

int	ASTNode_isUnknown (const ASTNode_t *node)
	Returns true if the type of the node is unknown. More...

int	ASTNode_isUPlus (const ASTNode_t *node)
	Returns true if the given node is a unary plus. More...

int	ASTNode_isWellFormedASTNode (ASTNode_t *node)
	Returns true if the given node is well-formed. More...

int	ASTNode_prependChild (ASTNode_t node, ASTNode_t disownedChild)
	Adds a node as a child of another node. More...

void	ASTNode_reduceToBinary (ASTNode_t *node)
	Reduces the given node to a binary true. More...

int	ASTNode_removeChild (ASTNode_t *node, unsigned int n)
	Removes the nth child of a given node. More...

int	ASTNode_replaceAndDeleteChild (ASTNode_t node, unsigned int n, ASTNode_t disownedChild)
	Replaces and deletes the nth child of a given node. More...

void	ASTNode_replaceArgument (ASTNode_t node, const char bvar, ASTNode_t *arg)
	Replaces occurrences of a given name with a new ASTNode_t structure. More...

int	ASTNode_replaceChild (ASTNode_t node, unsigned int n, ASTNode_t disownedChild)
	Replaces the nth child of a given node. More...

int	ASTNode_returnsBoolean (const ASTNode_t *node)
	Returns true if the given node is something that returns a Boolean value. More...

int	ASTNode_returnsBooleanForModel (const ASTNode_t node, const Model_t model)
	Returns true if the given node is something that returns a Boolean value. More...

int	ASTNode_setCharacter (ASTNode_t *node, char value)
	Sets the value of a given node to a character. More...

int	ASTNode_setClass (ASTNode_t node, const char className)
	Sets the MathML "class" of the given node. More...

int	ASTNode_setDefinitionURL (ASTNode_t node, XMLAttributes_t defnURL)
	Sets the MathML "definitionURL" attribute of the given node. More...

int	ASTNode_setDefinitionURLString (ASTNode_t node, const char defnURL)
	Sets the MathML "definitionURL" attribute of the given node. More...

int	ASTNode_setId (ASTNode_t node, const char id)
	Sets the MathML "id" attribute of the given node. More...

int	ASTNode_setInteger (ASTNode_t *node, long value)
	Sets the given node to a integer and sets it type to AST_INTEGER. More...

int	ASTNode_setName (ASTNode_t node, const char name)
	Sets the node to represent a named entity. More...

int	ASTNode_setRational (ASTNode_t *node, long numerator, long denominator)
	Sets the value of a given node to a rational number and sets its type to AST_RATIONAL. More...

int	ASTNode_setReal (ASTNode_t *node, double value)
	Sets the value of a given node to a real (`double`) and sets its type to AST_REAL. More...

int	ASTNode_setRealWithExponent (ASTNode_t *node, double mantissa, long exponent)
	Sets the value of a given node to a real (`double`) in two parts, a mantissa and an exponent. More...

int	ASTNode_setStyle (ASTNode_t node, const char style)
	Sets the MathML "style" of the given node. More...

int	ASTNode_setType (ASTNode_t *node, ASTNodeType_t type)
	Explicitly sets the type of the given ASTNode_t structure. More...

int	ASTNode_setUnits (ASTNode_t node, const char units)
	Sets the units of the given node. More...

int	ASTNode_setUserData (ASTNode_t node, void userData)
	Sets the user data of the given node. More...

int	ASTNode_swapChildren (ASTNode_t node, ASTNode_t that)
	Swaps the children of two nodes. More...

int	ASTNode_unsetClass (ASTNode_t *node)
	Unsets the MathML "class" attribute of the given node. More...

int	ASTNode_unsetId (ASTNode_t *node)
	Unsets the MathML "id" attribute of the given node. More...

int	ASTNode_unsetStyle (ASTNode_t *node)
	Unsets the MathML "style" attribute of the given node. More...

int	ASTNode_unsetUnits (ASTNode_t *node)
	Unsets the units associated with the given node. More...

int	ASTNode_unsetUserData (ASTNode_t *node)
	Unsets the user data of the given node. More...

ASTNode_t *	readMathMLFromString (const char *xml)
	Reads the MathML from the given XML string, constructs a corresponding abstract syntax tree, and returns a pointer to the root of the tree. More...

ASTNode_t *	readMathMLFromStringWithNamespaces (const char xml, XMLNamespaces_t xmlns)
	Reads the MathML from the given XML string, constructs a corresponding abstract syntax tree, and returns a pointer to the root of the tree. More...

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...

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...

L3ParserSettings_t *	SBML_getDefaultL3ParserSettings ()

char *	SBML_getLastParseL3Error ()
	Returns the last error reported by the "L3" mathematical formula parser. More...

ASTNode_t *	SBML_parseFormula (const char *formula)

ASTNode_t *	SBML_parseL3Formula (const char *formula)
	Parses a text string as a mathematical formula and returns an AST representation of it. More...

ASTNode_t *	SBML_parseL3FormulaWithModel (const char formula, const Model_t model)
	Parses a text string as a mathematical formula using a Model_t to resolve symbols, and returns an AST representation of the result. More...

ASTNode_t *	SBML_parseL3FormulaWithSettings (const char formula, const L3ParserSettings_t settings)
	Parses a text string as a mathematical formula using specific parser settings and returns an AST representation of the result. More...

char *	writeMathMLToString (const ASTNode_t *node)
	Writes the given ASTNode_t (and its children) to a string as MathML, and returns the string. More...

char *	writeMathMLToString (const ASTNode *node)

char *	writeMathMLWithNamespaceToString (const ASTNode_t node, SBMLNamespaces_t sbmlns)
	Writes the given AST node (and its children) to a string as MathML, and returns the string. More...

Member Function Documentation

int ASTNode_addChild	(	ASTNode_t *	node,
		ASTNode_t *	disownedChild
	)

Adds a node as a child of another node.

Child nodes are added in order from "left-to-right".

Parameters

node	the node which will get the new child node
disownedChild	the ASTNode_t instance to add

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Warning: Explicitly adding, removing or replacing children of an ASTNode_t structure may change the structure of the mathematical formula it represents, and may even render the representation invalid. Callers need to be careful to use this method in the context of other operations to create complete and correct formulas. The method ASTNode_isWellFormedASTNode() may also be useful for checking the results of node modifications.

See also: ASTNode_prependChild(); ASTNode_replaceChild(); ASTNode_insertChild(); ASTNode_removeChild(); ASTNode_isWellFormedASTNode()

Examples:: createExampleSBML.c.

int ASTNode_addSemanticsAnnotation	(	ASTNode_t *	node,
		XMLNode_t *	disownedAnnotation
	)

Adds a given XML node structure as a MathML semantic annotation of a given ASTNode_t structure.

The <semantics> element is a MathML 2.0 construct that can be used to associate additional information with a MathML construct. The construct can be used to decorate a MathML expressions with a sequence of one or more <annotation> or <annotation-xml> elements. Each such element contains a pair of items; the first is a symbol that acts as an attribute or key, and the second is the value associated with the attribute or key. Please refer to the MathML 2.0 documentation, particularly the Section 5.2, Semantic Annotations for more information about these constructs.

Parameters

node	the node to modify
disownedAnnotation	the annotation to add

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

Note: Although SBML permits the semantic annotation construct in MathML expressions, the truth is that this construct has so far (at this time of this writing, which is early 2011) seen very little use in SBML software. The full implications of using semantic annotations are still poorly understood. If you wish to use this construct, we urge you to discuss possible uses and applications on the SBML discussion lists, particularly sbml-discuss@caltech.edu and/or sbml-interoperability@caltech.edu.

int ASTNode_canonicalize ( ASTNode_t * node )

Converts a given node to a canonical form and returns 1 if successful, 0 otherwise.

The rules determining the canonical form conversion are as follows:

If the node type is AST_NAME and the node name matches "ExponentialE", "Pi", "True" or "False" the node type is converted to the corresponding AST_CONSTANT_X type.
If the node type is an AST_FUNCTION and the node name matches an SBML (MathML) function name, logical operator name, or relational operator name, the node is converted to the corresponding AST_FUNCTION_X or AST_LOGICAL_X type.

SBML Level 1 function names are searched first; thus, for example, canonicalizing log will result in a node type of AST_FUNCTION_LN. (See the SBML Level 1 Version 2 Specification, Appendix C.)

Sometimes, canonicalization of a node results in a structural conversion of the node as a result of adding a child. For example, a node with the SBML Level 1 function name sqr and a single child node (the argument) will be transformed to a node of type AST_FUNCTION_POWER with two children. The first child will remain unchanged, but the second child will be an ASTNode_t of type AST_INTEGER and a value of 2. The function names that result in structural changes are: log10, sqr, and sqrt.

Parameters

node	the node to be converted.

Returns: 1 if successful, 0 otherwise.

ASTNode_t * ASTNode_create ( void )

Creates a new ASTNode_t structure and returns a pointer to it.

The returned node will have a type of AST_UNKNOWN. The caller should be set the node type to something else as soon as possible using ASTNode_setType().

Returns: a pointer to the fresh ASTNode_t structure.

See also: ASTNode_createWithType()

ASTNode_t * ASTNode_createFromToken ( Token_t * token )

Creates a new ASTNode_t structure from the given Token_t data and returns a pointer to it.

The returned ASTNode_t structure will contain the same data as the Token_t structure. The Token_t structure is used to store a token returned by FormulaTokenizer_nextToken(). It contains a union whose members can store different types of tokens, such as numbers and symbols.

Parameters

token the Token_t structure to use

Returns: a pointer to the new ASTNode_t structure.

ASTNode_t * ASTNode_createWithType ( ASTNodeType_t type )

Creates a new ASTNode_t structure and sets its type.

Parameters

type	the type of node to create

Returns: a pointer to the fresh ASTNode_t structure.

See also: ASTNode_create()

Examples:: createExampleSBML.c.

ASTNode_t * ASTNode_deepCopy ( const ASTNode_t * node )

Creates a recursive copy of a node and all its children.

Parameters

node	the ASTNode_t structure to copy.

Returns: a copy of this ASTNode_t structure and all its children. The caller owns the returned structure and is reponsible for deleting it.

void ASTNode_fillListOfNodes	(	const ASTNode_t *	node,
		ASTNodePredicate	predicate,
		List_t *	lst
	)

Returns a list of nodes rooted at a given node and satisfying a given predicate.

This method is identical to ASTNode_getListOfNodes(), except that instead of creating a new List_t structure, it uses the one passed in as argument lst. This function performs a depth-first search of the tree rooted at the given ASTNode_t structure, and adds to lst the nodes for which the given function predicate(node) returns true (i.e., nonzero).

The predicate is passed in as a pointer to a function. The function definition must have the type ASTNodePredicate , which is defined as

int (*ASTNodePredicate) (const ASTNode_t *node);

where a return value of non-zero represents true and zero represents false.

Parameters

node	the node at which the search is to be started
predicate	the predicate to use
lst	the list to use

See also: ASTNode_getListOfNodes()

void ASTNode_free ( ASTNode_t * node )

Frees the given ASTNode_t structure, including any child nodes.

Parameters

node	the node to be freed.

Examples:: createExampleSBML.c, translateL3Math.c, and translateMath.c.

int ASTNode_freeName ( ASTNode_t * node )

Frees the name field of a given node and sets it to null.

This operation is only applicable to ASTNode_t structures corresponding to operators, numbers, or AST_UNKNOWN. This method will have no effect on other types of nodes.

Parameters

node	the node whose name field should be freed.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

char ASTNode_getCharacter ( const ASTNode_t * node )

Gets the value of a node as a single character.

This function should be called only when ASTNode_getType() returns AST_PLUS, AST_MINUS, AST_TIMES, AST_DIVIDE or AST_POWER for the given node.

Parameters

node	the node whose value is to be returned.

Returns: the value of node as a single character, or the value CHAR_MAX if is null.

ASTNode_t * ASTNode_getChild	(	const ASTNode_t *	node,
		unsigned int	n
	)

Gets a child of a node according to its index number.

Parameters

node	the node whose child should be obtained.
n	the index of the desired child node.

Returns: the nth child of this ASTNode_t or a null pointer if this node has no nth child (n > ASTNode_getNumChildre() - 1).

See also: ASTNode_getNumChildren(); ASTNode_getLeftChild(); ASTNode_getRightChild()

Examples:: printMath.c.

char * ASTNode_getClass ( const ASTNode_t * node )

Returns the MathML "class" attribute of a given node.

Parameters

node	the node whose class should be returned

Returns: the class identifier, or null if is a null pointer.

XMLAttributes_t * ASTNode_getDefinitionURL ( ASTNode_t * node )

Returns the MathML "definitionURL" attribute value of the given node.

Parameters

node	the node to query

Returns: the value of the "definitionURL" attribute in the form of a libSBML XMLAttributes_t structure, or a null pointer if node does not have a value for the attribute.

See also: ASTNode_getDefinitionURLString()

char * ASTNode_getDefinitionURLString ( ASTNode_t * node )

Returns the MathML "definitionURL" attribute value of the given node as a string.

Parameters

node	the node to query

Returns: the value of the "definitionURL" attribute in the form of a string, or a null pointer if node does not have a value for the attribute.

See also: ASTNode_getDefinitionURL()

long ASTNode_getDenominator ( const ASTNode_t * node )

Gets the numerator value of a node representing a rational number.

This function should be called only when ASTNode_getType() returns AST_RATIONAL for the given node.

Parameters

node	the node whose value is to be returned.

Returns: the value of the denominator of node, or the value LONG_MAX if is null.

See also: ASTNode_getNumerator()

long ASTNode_getExponent ( const ASTNode_t * node )

Get the exponent value of a node.

This function should be called only when ASTNode_getType() returns AST_REAL_E or AST_REAL for the given node.

Parameters

node	the node whose value is to be returned.

Returns: the value of the exponent field in the given node ASTNode_t structure, or NaN if is null.

char * ASTNode_getId ( const ASTNode_t * node )

Returns the MathML "id" attribute of a given node.

Parameters

node	the node whose identifier should be returned

Returns: the identifier of the node, or null if is a null pointer.

long ASTNode_getInteger ( const ASTNode_t * node )

Gets the value of a node as an integer.

This function should be called only when ASTNode_getType() returns AST_INTEGER for the given node.

Parameters

node	the node whose value is to be returned.

Returns: the value of the given ASTNode_t structure as a (long) integer, or the value LONG_MAX if is null.

ASTNode_t * ASTNode_getLeftChild ( const ASTNode_t * node )

Returns the left-most child of a given node.

This is equivalent to ASTNode_getChild(node, 0).

Parameters

node	the node whose child is to be returned.

Returns: the left child, or a null pointer if there are no children.

See also: ASTNode_getNumChildren(); ASTNode_getChild(); ASTNode_getRightChild()

Examples:: createExampleSBML.c, and printMath.c.

List_t * ASTNode_getListOfNodes	(	const ASTNode_t *	node,
		ASTNodePredicate	predicate
	)

Returns a list of nodes rooted at a given node and satisfying a given predicate.

This function performs a depth-first search of the tree rooted at the given ASTNode_t structure, and returns a List_t structure of nodes for which the given function predicate(node) returns true (i.e., non-zero).

The predicate is passed in as a pointer to a function. The function definition must have the type ASTNodePredicate, which is defined as

int (*ASTNodePredicate) (const ASTNode_t *node);

where a return value of nonzero represents true and zero represents false.

Parameters

node	the node at which the search is to be started
predicate	the predicate to use

Returns: the list of nodes for which the predicate returned true (i.e., nonzero). The List_t structure returned is owned by the caller and should be deleted after the caller is done using it. The ASTNode_t structures in the list, however, are not owned by the caller (as they still belong to the tree itself), and therefore should not be deleted.

See also: ASTNode_fillListOfNodes()

double ASTNode_getMantissa ( const ASTNode_t * node )

Get the mantissa value of a node.

This function should be called only when ASTNode_getType() returns AST_REAL_E or AST_REAL for the given node. If ASTNode_getType() returns AST_REAL for node, this method behaves identically to ASTNode_getReal().

Parameters

node	the node whose value is to be returned.

Returns: the value of the mantissa of node, or NaN if is null.

const char * ASTNode_getName ( const ASTNode_t * node )

Gets the value of a node as a string.

This function may be called on nodes that (1) are not operators, i.e., nodes for which ASTNode_isOperator() returns false (0), and (2) are not numbers, i.e., for which ASTNode_isNumber() also returns false (0).

Parameters

node	the node whose value is to be returned.

Returns: the value of node as a string, or a null pointer if is null.

Examples:: printMath.c.

unsigned int ASTNode_getNumChildren ( const ASTNode_t * node )

Returns the number of children of a given node.

Parameters

node	the ASTNode_t structure whose children are to be counted.

Returns: the number of children of node, or 0 is it has no children.

Examples:: printMath.c.

long ASTNode_getNumerator ( const ASTNode_t * node )

Gets the numerator value of a node representing a rational number.

This function should be called only when ASTNode_getType() returns AST_RATIONAL for the given node.

Parameters

node	the node whose value is to be returned.

Returns: the value of the numerator of node, or the value LONG_MAX if is null.

See also: ASTNode_getDenominator()

unsigned int ASTNode_getNumSemanticsAnnotations ( ASTNode_t * node )

Returns the number of MathML semantic annotations inside the given node.

The <semantics> element is a MathML 2.0 construct that can be used to associate additional information with a MathML construct. The construct can be used to decorate a MathML expressions with a sequence of one or more <annotation> or <annotation-xml> elements. Each such element contains a pair of items; the first is a symbol that acts as an attribute or key, and the second is the value associated with the attribute or key. Please refer to the MathML 2.0 documentation, particularly the Section 5.2, Semantic Annotations for more information about these constructs.

Parameters

node	the node to query

Returns: a count of the semantic annotations.

See also: ASTNode_addSemanticsAnnotation()

SBase_t * ASTNode_getParentSBMLObject ( ASTNode_t * node )

Returns the parent SBML structure containing the given node.

Parameters

node	the node to query

Returns: a pointer to the object structure containing the given node.

int ASTNode_getPrecedence ( const ASTNode_t * node )

Gets the precedence of a node in the infix math syntax of 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_t. 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	x²
`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.

Parameters

node	the node whose precedence is to be calculated.

Returns: the precedence of node (as defined in the SBML Level 1 specification).

double ASTNode_getReal ( const ASTNode_t * node )

Get the real-numbered value of a node.

This function should be called only when ASTNode_isReal() returns non-zero for node. This function performs the necessary arithmetic if the node type is AST_REAL_E (mantissa * 10^exponent) or AST_RATIONAL (numerator / denominator).

Parameters

node	the node whose value is to be returned.

Returns: the value of node as a real (double), or NaN if is null.

ASTNode_t * ASTNode_getRightChild ( const ASTNode_t * node )

Returns the right-most child of a given node.

If ASTNode_getNumChildren(node) > 1, then this is equivalent to:

ASTNode_getChild(node, ASTNode_getNumChildren(node) - 1);

Parameters

node	the node whose child node is to be obtained.

Returns: the right child of node, or a null pointer if node has no right child.

See also: ASTNode_getNumChildren(); ASTNode_getLeftChild(); ASTNode_getChild()

Examples:: createExampleSBML.c.

XMLNode_t * ASTNode_getSemanticsAnnotation	(	ASTNode_t *	node,
		unsigned int	n
	)

Returns the nth MathML semantic annotation attached to the given node.

The <semantics> element is a MathML 2.0 construct that can be used to associate additional information with a MathML construct. The construct can be used to decorate a MathML expressions with a sequence of one or more <annotation> or <annotation-xml> elements. Each such element contains a pair of items; the first is a symbol that acts as an attribute or key, and the second is the value associated with the attribute or key. Please refer to the MathML 2.0 documentation, particularly the Section 5.2, Semantic Annotations for more information about these constructs.

Parameters

node	the node to query
n	the index of the semantic annotation to fetch

Returns: the nth semantic annotation on node , or a null pointer if the node has no nth annotation (which would mean that n > ASTNode_getNumSemanticsAnnotations(node) - 1).

See also: ASTNode_addSemanticsAnnotation()

char * ASTNode_getStyle ( const ASTNode_t * node )

Returns the MathML "style" attribute of a given node.

Parameters

node the node

Returns: a string representing the "style" value, or a null value if is a null pointer.

ASTNodeType_t ASTNode_getType ( const ASTNode_t * node )

Returns the type of the given node.

Parameters

node the node

Returns: the type of the given ASTNode_t structure.

char * ASTNode_getUnits ( const ASTNode_t * node )

Returns the SBML "units" attribute of a given node.

SBML Level 3 Version 1 introduced the ability to include an attribute sbml:units on MathML cn elements appearing in SBML mathematical formulas. The value of this attribute can be used to indicate the unit of measurement to be associated with the number in the content of the cn element. The value of this attribute must be the identifier of a unit of measurement defined by SBML or the enclosing Model. Here, the sbml portion is an XML namespace prefix that must be associated with the SBML namespace for SBML Level 3. The following example illustrates how this attribute can be used to define a number with value 10 and unit of measurement second:

<math xmlns="http://www.w3.org/1998/Math/MathML"
      xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core">
        <cn type="integer" sbml:units="second"> 10 </cn>
</math>

Parameters

node	the node whose units are to be returned.

Returns: the units, as a string, or a null value if is a null pointer.

Note: The sbml:units attribute for MathML expressions is only defined in SBML Level 3. It may not be used in Levels 1–2 of SBML.

See also: SBML_parseL3Formula()

void * ASTNode_getUserData ( const ASTNode_t * node )

Returns the user data associated with this node.

Parameters

node	the node to query

Returns: the user data of this node, or a null pointer if no user data has been set.

See also: ASTNode_setUserData()

double ASTNode_getValue ( const ASTNode_t * node )

Returns the numerical value of this ASTNode_t.

Parameters

node	the ASTNode_t whose value is to be returned.

Returns: the numerical value of this ASTNode_t, or NaN if this is not a type of node that has a numerical value.

Note: This function will return a numerical value (as a double) for any ASTNode_t that represents a number, a constant such as pi or avogadro or 1 for nodes of type AST_CONSTANT_TRUE and 0 for nodes of type AST_CONSTANT_FALSE. It does not evaluate the node in any way so, for example, it will not return the value of a named ASTNode_t or attempt to evaluate a function. This includes a node representing time i.e. nodes of type AST_NAME_TIME.

int ASTNode_hasCorrectNumberArguments ( ASTNode_t * node )

Returns true if the given node has the correct number of children for its type.

For example, an ASTNode_t structure with type AST_PLUS expects 2 child nodes.

Parameters

node	the node to query

Returns: 1 if node has the appropriate number of children for its type, 0 otherwise.

Note: This function performs a check on the top-level node only. Child nodes are not checked.

See also: ASTNode_isWellFormedASTNode()

int ASTNode_hasTypeAndNumChildren	(	const ASTNode_t *	node,
		ASTNodeType_t	type,
		unsigned int	numchildren
	)

Returns true if the given node is of a specific type and has a specific number of children.

This function is designed for use in cases such as when callers want to determine if the node is a unary not or unary minus, or a times node with no children, etc.

Parameters

node	the node to query
type	the type that the node should have
numchildren	the number of children that the node should have.

Returns: 1 if node is has the specified type and number of children, 0 otherwise.

int ASTNode_hasUnits ( const ASTNode_t * node )

Returns true if the given node or any of its children have the SBML "units" attribute set.

SBML Level 3 Version 1 introduced the ability to include an attribute sbml:units on MathML cn elements appearing in SBML mathematical formulas. The value of this attribute can be used to indicate the unit of measurement to be associated with the number in the content of the cn element. The value of this attribute must be the identifier of a unit of measurement defined by SBML or the enclosing Model. Here, the sbml portion is an XML namespace prefix that must be associated with the SBML namespace for SBML Level 3. The following example illustrates how this attribute can be used to define a number with value 10 and unit of measurement second:

<math xmlns="http://www.w3.org/1998/Math/MathML"
      xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core">
        <cn type="integer" sbml:units="second"> 10 </cn>
</math>

Parameters

node	the node to query

Returns: 1 if the attribute is set, 0 otherwise.

Note: The sbml:units attribute is only available in SBML Level 3. It may not be used in Levels 1–2 of SBML.

See also: ASTNode_isSetUnits()

int ASTNode_insertChild	(	ASTNode_t *	node,
		unsigned int	n,
		ASTNode_t *	disownedChild
	)

Insert a new child node at a given point in the list of children of a node.

Parameters

node	the ASTNode_t structure to modify.
n	unsigned int the index of the location where the `disownedChild` is to be added.
disownedChild	ASTNode_t structure to insert as the nth child.

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

Warning: Explicitly adding, removing or replacing children of an ASTNode_t structure may change the structure of the mathematical formula it represents, and may even render the representation invalid. Callers need to be careful to use this method in the context of other operations to create complete and correct formulas. The method ASTNode_isWellFormedASTNode() may also be useful for checking the results of node modifications.

See also: ASTNode_addChild(); ASTNode_prependChild(); ASTNode_replaceChild(); ASTNode_removeChild()

int ASTNode_isAvogadro ( const ASTNode_t * node )

Returns true if the given node represents the special symbol avogadro.

Parameters

node	the node to query

Returns: 1 if this stands for avogadro, 0 otherwise.

See also: SBML_parseL3Formula()

int ASTNode_isBoolean ( const ASTNode_t * node )

Returns true if this node is some type of Boolean value or operator.

Parameters

node	the node in question

Returns: 1 (true) if node is a Boolean (a logical operator, a relational operator, or the constants true or false), 0 otherwise.

int ASTNode_isConstant ( const ASTNode_t * node )

Returns true if the given node represents a MathML constant.

Examples of constants in this context are Pi, true, etc.

Parameters

node the node

Returns: 1 if node is a MathML constant, 0 otherwise.

int ASTNode_isConstantNumber ( const ASTNode_t * node )

Returns true if the given node represents a MathML constant.

Examples of constants in this context are Pi, true, etc.

Parameters

node the node

Returns: 1 if node is a MathML constant, 0 otherwise.

int ASTNode_isFunction ( const ASTNode_t * node )

Returns true if the given node represents a function.

Parameters

node the node

Returns: 1 if node is a function in SBML, whether predefined (in SBML Level 1), defined by MathML (SBML Levels 2–3) or user-defined.

int ASTNode_isInfinity ( const ASTNode_t * node )

Returns true if the given node stands for infinity.

Parameters

node	the node to query

Returns: 1 if node is the special IEEE 754 value for infinity, 0 otherwise.

int ASTNode_isInteger ( const ASTNode_t * node )

Returns true if the given node contains an integer value.

Parameters

node	the node to query

Returns: 1 if node is of type AST_INTEGER, 0 otherwise.

int ASTNode_isLambda ( const ASTNode_t * node )

Returns true if the given node is a MathML lambda function.

Parameters

node	the node to query

Returns: 1 if node is of type AST_LAMBDA, 0 otherwise.

int ASTNode_isLog10 ( const ASTNode_t * node )

Returns true if the given node represents the log base-10 function.

More precisely, this function tests if the given node's type is AST_FUNCTION_LOG with two children, the first of which is an AST_INTEGER equal to 10.

Returns: 1 if node represents a log10() function, 0 otherwise.

See also: SBML_parseL3Formula()

int ASTNode_isLogical ( const ASTNode_t * node )

Returns true if the given node is a logical operator.

Parameters

node	the node to query

Returns: 1 if node is a MathML logical operator (and, or, not, xor), 0otherwise.

int ASTNode_isName ( const ASTNode_t * node )

Returns true if the given node is a named entity.

More precisely, this returns a true value if node is a user-defined variable name or the special symbols time or avogadro.

Parameters

node	the node to query

Returns: 1 if node is a named variable, 0 otherwise.

int ASTNode_isNaN ( const ASTNode_t * node )

Returns true if the given node represents not-a-number.

Parameters

node	the node to query

Returns: 1 if node is the special IEEE 754 value NaN ("not a number"), 0 otherwise.

int ASTNode_isNegInfinity ( const ASTNode_t * node )

Returns true if the given node represents negative infinity.

Parameters

node	the node to query

Returns: 1 if node is the special IEEE 754 value negative infinity, 0 otherwise.

See also: ASTNode_isInfinity()

int ASTNode_isNumber ( const ASTNode_t * node )

Returns true if the given node contains a number.

This is functionally equivalent to:

ASTNode_isInteger(node) || ASTNode_isReal(node).

Parameters

node	the node to query

Returns: 1 if node is a number, 0 otherwise.

int ASTNode_isOperator ( const ASTNode_t * node )

Returns true if the given node is a mathematical operator.

The possible mathematical operators are +, -, *, / and ^ (power).

Parameters

node	the node to query

Returns: 1 if node is an operator, 0 otherwise.

int ASTNode_isPiecewise ( const ASTNode_t * node )

Returns true if the given node represents the MathML <piecewise> operator.

Parameters

node	the node to query

Returns: 1 if node is the MathML piecewise function, 0 otherwise.

int ASTNode_isRational ( const ASTNode_t * node )

Returns true if the given node represents a rational number.

Parameters

node	the node to query

Returns: 1 if node is of type AST_RATIONAL, 0 otherwise.

int ASTNode_isReal ( const ASTNode_t * node )

Returns true if the given node represents a real number.

More precisely, this node must be of one of the following types: AST_REAL, AST_REAL_E or AST_RATIONAL.

Parameters

node	the node to query

Returns: 1 if the value of node can represent a real number, 0 otherwise.

int ASTNode_isRelational ( const ASTNode_t * node )

Returns true if the given node represents a MathML relational operator.

Parameters

node	the node to query

Returns: 1 if node is a MathML relational operator, meaning ==, >=, >, <, and !=.

int ASTNode_isSetClass ( const ASTNode_t * node )

Returns true if the given node's MathML "class" attribute is set.

Parameters

node	the node to query

Returns: 1 if the attribute is set, 0 otherwise.

int ASTNode_isSetId ( const ASTNode_t * node )

Returns true if the given node's MathML "id" attribute is set.

Parameters

node	the node to query

Returns: 1 if it is set, 0 otherwise.

int ASTNode_isSetParentSBMLObject ( ASTNode_t * node )

Returns true if the given node's parent SBML object is set.

Parameters

node	the node to query

Returns: 1 if the parent SBML object is set, 0 otherwise.

int ASTNode_isSetStyle ( const ASTNode_t * node )

Returns true if the given node's MathML "style" attribute is set.

Parameters

node	the node to query

Returns: 1 if the attribute is set, 0 otherwise.

int ASTNode_isSetUnits ( const ASTNode_t * node )

Returns true if this node's SBML "units" attribute is set.

SBML Level 3 Version 1 introduced the ability to include an attribute sbml:units on MathML cn elements appearing in SBML mathematical formulas. The value of this attribute can be used to indicate the unit of measurement to be associated with the number in the content of the cn element. The value of this attribute must be the identifier of a unit of measurement defined by SBML or the enclosing Model. Here, the sbml portion is an XML namespace prefix that must be associated with the SBML namespace for SBML Level 3. The following example illustrates how this attribute can be used to define a number with value 10 and unit of measurement second:

<math xmlns="http://www.w3.org/1998/Math/MathML"
      xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core">
        <cn type="integer" sbml:units="second"> 10 </cn>
</math>

Parameters

node	the node to query

Returns: 1 if the attribute is set, 0 otherwise.

Note: The sbml:units attribute is only available in SBML Level 3. It may not be used in Levels 1–2 of SBML.

int ASTNode_isSetUserData ( const ASTNode_t * node )

Returns true if the given node's user data object is set.

Parameters

node	the node to query

Returns: 1 if the user data object is set, 0 otherwise.

See also: ASTNode_setUserData()

int ASTNode_isSqrt ( const ASTNode_t * node )

Returns true if the given node is the MathML square-root operator.

More precisely, the node type must be AST_FUNCTION_ROOT with two children, the first of which is an AST_INTEGER node having value equal to 2.

Parameters

node	the node to query

Returns: 1 if node represents a sqrt() function, 0 otherwise.

int ASTNode_isUMinus ( const ASTNode_t * node )

Returns true if the given node represents a unary minus.

A node is defined as a unary minus node if it is of type AST_MINUS and has exactly one child.

For numbers, unary minus nodes can be "collapsed" by negating the number. In fact, SBML_parseFormula() does this during its parsing process, and SBML_parseL3Formula() has a configuration option that allows this behavior to be turned on or off. However, unary minus nodes for symbols (AST_NAME) cannot be "collapsed", so this predicate function is still necessary.

Parameters

node	the node to query

Returns: 1 if node is a unary minus, 0 otherwise.

See also: SBML_parseL3Formula()

int ASTNode_isUnknown ( const ASTNode_t * node )

Returns true if the type of the node is unknown.

"Unknown" nodes have the type AST_UNKNOWN. Nodes with unknown types will not appear in an ASTNode_t tree returned by libSBML based upon valid SBML input; the only situation in which a node with type AST_UNKNOWN may appear is immediately after having create a new, untyped node using the ASTNode_t constructor. Callers creating nodes should endeavor to set the type to a valid node type as soon as possible after creating new nodes.

Parameters

node	the node to query

Returns: 1 if node is of type AST_UNKNOWN, 0 otherwise.

int ASTNode_isUPlus ( const ASTNode_t * node )

Returns true if the given node is a unary plus.

A node is defined as a unary minus node if it is of type AST_MINUS and has exactly one child.

Parameters

node	the node to query

Returns: 1 if node is a unary plus, 0 otherwise.

int ASTNode_isWellFormedASTNode ( ASTNode_t * node )

Returns true if the given node is well-formed.

Parameters

node	the node to query

Returns: 1 if node is well-formed, 0 otherwise.

Note: An ASTNode_t may be well-formed, with each node and its children having the appropriate number of children for the given type, but may still be invalid in the context of its use within an SBML model.

int ASTNode_prependChild	(	ASTNode_t *	node,
		ASTNode_t *	disownedChild
	)

Adds a node as a child of another node.

This method adds child nodes from right to left.

Parameters

node	the node that will receive the given child node.
disownedChild	the ASTNode_t instance to add.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Warning: Explicitly adding, removing or replacing children of an ASTNode_t structure may change the structure of the mathematical formula it represents, and may even render the representation invalid. Callers need to be careful to use this method in the context of other operations to create complete and correct formulas. The method ASTNode_isWellFormedASTNode() may also be useful for checking the results of node modifications.

See also: ASTNode_addChild(); ASTNode_replaceChild(); ASTNode_insertChild(); ASTNode_removeChild()

void ASTNode_reduceToBinary ( ASTNode_t * node )

Reduces the given node to a binary true.

Example: if node is and(x, y, z), then the formula of the reduced node is and(and(x, y), z). The operation replaces the formula stored in the current ASTNode_t structure.

Parameters

node	the node to modify

int ASTNode_removeChild	(	ASTNode_t *	node,
		unsigned int	n
	)

Removes the nth child of a given node.

Parameters

node	the node whose child element is to be removed.
n	unsigned int the index of the child to remove.

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

Warning: Explicitly adding, removing or replacing children of an ASTNode_t structure may change the structure of the mathematical formula it represents, and may even render the representation invalid. Callers need to be careful to use this method in the context of other operations to create complete and correct formulas. The method ASTNode_isWellFormedASTNode() may also be useful for checking the results of node modifications.

See also: ASTNode_addChild(); ASTNode_prependChild(); ASTNode_replaceChild(); ASTNode_insertChild()

int ASTNode_replaceAndDeleteChild	(	ASTNode_t *	node,
		unsigned int	n,
		ASTNode_t *	disownedChild
	)

Replaces and deletes the nth child of a given node.

Parameters

node	the ASTNode_t node to modify
n	unsigned int the index of the child to replace
disownedChild	ASTNode_t structure to replace the nth child

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

Warning: Explicitly adding, removing or replacing children of an ASTNode_t structure may change the structure of the mathematical formula it represents, and may even render the representation invalid. Callers need to be careful to use this method in the context of other operations to create complete and correct formulas. The method ASTNode_isWellFormedASTNode() may also be useful for checking the results of node modifications.

See also: ASTNode_addChild(); ASTNode_prependChild(); ASTNode_insertChild(); ASTNode_removeChild(); ASTNode_replaceChild()

void ASTNode_replaceArgument	(	ASTNode_t *	node,
		const char *	bvar,
		ASTNode_t *	arg
	)

Replaces occurrences of a given name with a new ASTNode_t structure.

For example, if the formula in node is x + y, then the <bvar> is x and arg is an ASTNode_t structure representing the real value 3. This function substitutes 3 for x within the node ASTNode_t structure.

Parameters

node	the node to modify
bvar	the MathML `<bvar>` to use
arg	the replacement node or structure

int ASTNode_replaceChild	(	ASTNode_t *	node,
		unsigned int	n,
		ASTNode_t *	disownedChild
	)

Replaces the nth child of a given node.

Parameters

node	the ASTNode_t node to modify
n	unsigned int the index of the child to replace
disownedChild	ASTNode_t structure to replace the nth child

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

Warning: Explicitly adding, removing or replacing children of an ASTNode_t structure may change the structure of the mathematical formula it represents, and may even render the representation invalid. Callers need to be careful to use this method in the context of other operations to create complete and correct formulas. The method ASTNode_isWellFormedASTNode() may also be useful for checking the results of node modifications.

See also: ASTNode_addChild(); ASTNode_prependChild(); ASTNode_insertChild(); ASTNode_removeChild(); ASTNode_replaceAndDeleteChild()

int ASTNode_returnsBoolean ( const ASTNode_t * node )

Returns true if the given node is something that returns a Boolean value.

This function looks at the whole ASTNode_t structure rather than just the top level of node. Thus, it will consider return values from MathML piecewise statements. In addition, if the ASTNode_t structure in node uses a function call, this function will examine the return value of the function. Note that this is only possible in cases the ASTNode_t structure can trace its parent Model_t structure; that is, the ASTNode_t structure must represent the <math> element of some SBML object that has already been added to an instance of an SBMLDocument_t structure.

Parameters

node	the node to query

Returns: 1 if node returns a boolean, 0 otherwise.

See also: ASTNode_isBoolean(); ASTNode_returnsBooleanForModel()

int ASTNode_returnsBooleanForModel	(	const ASTNode_t *	node,
		const Model_t *	model
	)

Returns true if the given node is something that returns a Boolean value.

This function looks at the whole ASTNode_t structure rather than just the top level of node. Thus, it will consider return values from MathML piecewise statements. In addition, if the ASTNode_t structure in node uses a function call, this function will examine the return value of the function using the definition of the function found in the given Model_t structure given by model (rather than the model that might be traced from node itself). This function is similar to ASTNode_returnsBoolean(), but is useful in situations where the ASTNode_t structure has not been hooked into a model yet.

Parameters

node	the node to query
model	the model to use as the basis for finding the definition of the function

Returns: 1 if node returns a boolean, 0 otherwise.

See also: ASTNode_isBoolean(); ASTNode_returnsBoolean()

int ASTNode_setCharacter	(	ASTNode_t *	node,
		char	value
	)

Sets the value of a given node to a character.

If character is one of +, -, *, / or ^, the node type will be set accordingly. For all other characters, the node type will be set to AST_UNKNOWN.

Parameters

node	the node to set
value	the character value for the node.

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_setClass	(	ASTNode_t *	node,
		const char *	className
	)

Sets the MathML "class" of the given node.

Parameters

node	the node to set
className	the new value for the "class" attribute

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_setDefinitionURL	(	ASTNode_t *	node,
		XMLAttributes_t *	defnURL
	)

Sets the MathML "definitionURL" attribute of the given node.

Parameters

node	the node to modify
defnURL	the value to which the attribute should be set

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_setDefinitionURLString	(	ASTNode_t *	node,
		const char *	defnURL
	)

Sets the MathML "definitionURL" attribute of the given node.

Parameters

node	the node to modify
defnURL	a string to which the attribute should be set

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_setId	(	ASTNode_t *	node,
		const char *	id
	)

Sets the MathML "id" attribute of the given node.

Parameters

node	the node to set
id	the identifier to use

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_setInteger	(	ASTNode_t *	node,
		long	value
	)

Sets the given node to a integer and sets it type to AST_INTEGER.

Parameters

node	the node to set
value	the value to set it to

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_setName	(	ASTNode_t *	node,
		const char *	name
	)

Sets the node to represent a named entity.

As a side-effect, this ASTNode_t object's type will be reset to AST_NAME if (and only if) the node was previously an operator (i.e., ASTNode_isOperator() returns true), number (i.e., ASTNode_isNumber() returns true), or unknown. This allows names to be set for AST_FUNCTION nodes and the like.

Parameters

node	the node to set
name	the name value for the node

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

Examples:: createExampleSBML.c.

int ASTNode_setRational	(	ASTNode_t *	node,
		long	numerator,
		long	denominator
	)

Sets the value of a given node to a rational number and sets its type to AST_RATIONAL.

Parameters

node	the node to set
numerator	the numerator value to use
denominator	the denominator value to use

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_setReal	(	ASTNode_t *	node,
		double	value
	)

Sets the value of a given node to a real (double) and sets its type to AST_REAL.

This is functionally equivalent to:

ASTNode_setRealWithExponent(node, value, 0);

Parameters

node	the node to set
value	the value to set the node to

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_setRealWithExponent	(	ASTNode_t *	node,
		double	mantissa,
		long	exponent
	)

Sets the value of a given node to a real (double) in two parts, a mantissa and an exponent.

As a side-effect, the node's type will be set to AST_REAL.

Parameters

node	the node to set
mantissa	the mantissa of this node's real-numbered value
exponent	the exponent of this node's real-numbered value

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_setStyle	(	ASTNode_t *	node,
		const char *	style
	)

Sets the MathML "style" of the given node.

Parameters

node	the node to set
style	the new value for the "style" attribute

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_setType	(	ASTNode_t *	node,
		ASTNodeType_t	type
	)

Explicitly sets the type of the given ASTNode_t structure.

Parameters

node	the node to set
type	the new type

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

Note: A side-effect of doing this is that any numerical values previously stored in this node are reset to zero.

int ASTNode_setUnits	(	ASTNode_t *	node,
		const char *	units
	)

Sets the units of the given node.

The units will be set only if the ASTNode_t object in node represents a MathML <cn> element, i.e., represents a number. Callers may use ASTNode_isNumber() to inquire whether the node is of that type.

SBML Level 3 Version 1 introduced the ability to include an attribute sbml:units on MathML cn elements appearing in SBML mathematical formulas. The value of this attribute can be used to indicate the unit of measurement to be associated with the number in the content of the cn element. The value of this attribute must be the identifier of a unit of measurement defined by SBML or the enclosing Model. Here, the sbml portion is an XML namespace prefix that must be associated with the SBML namespace for SBML Level 3. The following example illustrates how this attribute can be used to define a number with value 10 and unit of measurement second:

<math xmlns="http://www.w3.org/1998/Math/MathML"
      xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core">
        <cn type="integer" sbml:units="second"> 10 </cn>
</math>

Parameters

node	the node to modify
units	the units to set it to.

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

Note: The sbml:units attribute is only available in SBML Level 3. It may not be used in Levels 1–2 of SBML.

int ASTNode_setUserData	(	ASTNode_t *	node,
		void *	userData
	)

Sets the user data of the given node.

The user data can be used by the application developer to attach custom information to the node. In case of a deep copy, this attribute will passed as it is. The attribute will be never interpreted by this class.

Parameters

node	the node to modify
userData	the new user data

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

See also: ASTNode_getUserData()

int ASTNode_swapChildren	(	ASTNode_t *	node,
		ASTNode_t *	that
	)

Swaps the children of two nodes.

Parameters

node	the node to modify
that	the other node whose children should be used to replace those of `node`

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_unsetClass ( ASTNode_t * node )

Unsets the MathML "class" attribute of the given node.

Parameters

node	the node to modify

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_unsetId ( ASTNode_t * node )

Unsets the MathML "id" attribute of the given node.

Parameters

node	the node to modify

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_unsetStyle ( ASTNode_t * node )

Unsets the MathML "style" attribute of the given node.

Parameters

node	the node to modify

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_unsetUnits ( ASTNode_t * node )

Unsets the units associated with the given node.

Parameters

node	the node to modify

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

int ASTNode_unsetUserData ( ASTNode_t * node )

Unsets the user data of the given node.

The user data can be used by the application developer to attach custom information to the node. In case of a deep copy, this attribute will passed as it is. The attribute will be never interpreted by this class.

Parameters

node	the node to modify

Returns

integer value indicating success/failure of the function. The possible values returned by this function are:

See also: ASTNode_getUserData(); ASTNode_setUserData()

ASTNode_t * readMathMLFromString ( const char * xml )

Reads the MathML from the given XML string, constructs a corresponding abstract syntax tree, and returns a pointer to the root of the tree.

Parameters

xml	a string containing a full MathML expression

Returns: the root of an AST corresponding to the given mathematical expression, otherwise NULL is returned if the given string is NULL or invalid.

Examples:: createExampleSBML.c, translateL3Math.c, and translateMath.c.

ASTNode_t * readMathMLFromStringWithNamespaces	(	const char *	xml,
		XMLNamespaces_t *	xmlns
	)

Reads the MathML from the given XML string, constructs a corresponding abstract syntax tree, and returns a pointer to the root of the tree.

Parameters

xml	a string containing a full MathML expression
xmlns	an XMLNamespaces_t structure 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 NULL is returned if the given string is NULL or invalid.

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.

: The text-string form of mathematical formulas read by the function SBML_parseL3Formula() and written by the function SBML_formulaToL3String() uses an expanded version of the syntax read and written by SBML_parseFormula() and SBML_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 SBML_formulaToString() and SBML_parseFormula() have been left untouched, and instead, the new functionality is provided in the form of SBML_parseL3Formula() and SBML_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 SBML_parseFormula() and SBML_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_t 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 SBML_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_t object in conjunction with the functions SBML_parseL3FormulaWithSettings() and SBML_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_t object may optionally be provided to the parser using the variant function call SBML_parseL3FormulaWithModel() or stored in a L3ParserSettings_t object passed to the variant function SBML_parseL3FormulaWithSettings(). When a Model_t 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_t entities whose identifiers will shadow identical symbols in the mathematical formula are: Species_t, Compartment_t, Parameter_t, Reaction_t, and SpeciesReference_t. For instance, if the parser is given a Model_t containing a Species_t 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_t 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_t contains a FunctionDefinition_t object with the identifier "sin", that function will be used instead of the predefined MathML function <sin/>.
- An SBMLNamespaces_t 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 SBML_parseL3FormulaWithSettings() and SBML_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.

Expression operators and their precedence in the "Level 3" text-string format for mathematical expressions.
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:

Mathematical functions defined in the "Level 3" text-string formula syntax.
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	x².
`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.

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_t object is used in conjunction with either SBML_parseL3FormulaWithModel() or SBML_parseL3FormulaWithSettings(), any identifiers found in that model will be parsed in a case-sensitive way. For example, if a model contains a Species_t 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 SBML_parseL3FormulaWithSettings() and pass it an appropriate L3ParserSettings_t object. By default, unlike the SBML Level 1 parser implemented by SBML_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 SBML_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_t object provided:

Mathematical symbols defined in the "Level 3" text-string formula syntax.
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 SBML_parseL3FormulaWithSettings(). This Avogadro-related functionality is provided because SBML Level 2 models may not use AST_NAME_AVOGADRO AST nodes.

Parameters

tree	the AST to be converted.

Returns: the formula from the given AST as an SBML Level 3 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_parseL3FormulaWithSettings(); SBML_parseL3Formula(); SBML_parseL3FormulaWithModel(); SBML_getLastParseL3Error(); SBML_getDefaultL3ParserSettings()

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

Parameters

settings object, namely:

ParseUnits: If this is set to 'true' (the default), the function will write out the units of any numerical ASTNodes that have them, producing (for example) "3 mL", "(3/4) m", or "5.5e-10 M". If this is set to 'false', this function will only write out the number itself ("3", "(3/4)", and "5.5e-10", in the previous examples).

CollapseMinus: If this is set to 'false' (the default), the function will write out explicitly any doubly-nested unary minus ASTNodes, producing (for example) "--x" or even "-----3.1". If this is set to 'true', the function will collapse the nodes before producing the infix, producing "x" and "-3.1" in the previous examples.

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_t object is used, and whether Avogadro is a csymbol or not is immaterial to the produced infix.

Parameters

tree	the AST to be converted.
settings	the L3ParserSettings_t object used to modify behavior.

Returns: the formula from the given AST as an SBML Level 3 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_parseFormula(); SBML_parseL3Formula(); SBML_formulaToL3String()

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_t. 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	x²
`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.

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_formulaToString(); SBML_parseL3FormulaWithSettings(); SBML_parseL3Formula(); SBML_parseL3FormulaWithModel(); SBML_getLastParseL3Error(); SBML_getDefaultL3ParserSettings()

Examples:: printMath.c, translateL3Math.c, and translateMath.c.

L3ParserSettings_t * SBML_getDefaultL3ParserSettings ( )

char * SBML_getLastParseL3Error ( )

Returns the last error reported by the "L3" mathematical formula parser.

If the functions SBML_parseL3Formula(), SBML_parseL3FormulaWithSettings(), or SBML_parseL3FormulaWithModel() return NULL, an error is set internally. This function allows callers to retrieve information about the error.

Returns: a string describing the error that occurred. This will contain the input string the parser was trying to parse, the character it had parsed when it encountered the error, and a description of the error.

See also: SBML_parseL3Formula(); SBML_parseL3FormulaWithSettings(); SBML_parseL3FormulaWithModel(); SBML_getDefaultL3ParserSettings()

Examples:: translateL3Math.c.

ASTNode_t * SBML_parseFormula ( const char * formula )

Examples:: translateMath.c.

ASTNode_t * SBML_parseL3Formula ( const char * formula )

Parses a text string as a mathematical formula and returns an AST representation of it.

: The text-string form of mathematical formulas read by the function SBML_parseL3Formula() and written by the function SBML_formulaToL3String() uses an expanded version of the syntax read and written by SBML_parseFormula() and SBML_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 SBML_formulaToString() and SBML_parseFormula() have been left untouched, and instead, the new functionality is provided in the form of SBML_parseL3Formula() and SBML_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 SBML_parseFormula() and SBML_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_t 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 SBML_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_t object in conjunction with the functions SBML_parseL3FormulaWithSettings() and SBML_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_t object may optionally be provided to the parser using the variant function call SBML_parseL3FormulaWithModel() or stored in a L3ParserSettings_t object passed to the variant function SBML_parseL3FormulaWithSettings(). When a Model_t 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_t entities whose identifiers will shadow identical symbols in the mathematical formula are: Species_t, Compartment_t, Parameter_t, Reaction_t, and SpeciesReference_t. For instance, if the parser is given a Model_t containing a Species_t 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_t 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_t contains a FunctionDefinition_t object with the identifier "sin", that function will be used instead of the predefined MathML function <sin/>.
- An SBMLNamespaces_t 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 SBML_parseL3FormulaWithSettings() and SBML_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.

Expression operators and their precedence in the "Level 3" text-string format for mathematical expressions.
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:

Mathematical functions defined in the "Level 3" text-string formula syntax.
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	x².
`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.

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_t object is used in conjunction with either SBML_parseL3FormulaWithModel() or SBML_parseL3FormulaWithSettings(), any identifiers found in that model will be parsed in a case-sensitive way. For example, if a model contains a Species_t 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 SBML_parseL3FormulaWithSettings() and pass it an appropriate L3ParserSettings_t object. By default, unlike the SBML Level 1 parser implemented by SBML_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 SBML_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_t object provided:

Mathematical symbols defined in the "Level 3" text-string formula syntax.
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 SBML_parseL3FormulaWithSettings(). This Avogadro-related functionality is provided because SBML Level 2 models may not use AST_NAME_AVOGADRO AST nodes.

Parameters

formula the text-string formula expression to be parsed.

Returns: the root node of an AST representing the mathematical formula, or NULL if an error occurred while parsing the formula. When NULL is returned, an error is recorded internally; information about the error can be retrieved using SBML_getLastParseL3Error().

See also: SBML_parseL3FormulaWithSettings(); SBML_parseL3FormulaWithModel(); SBML_parseFormula(); SBML_formulaToL3StringWithSettings(); SBML_formulaToL3String(); SBML_formulaToString(); L3ParserSettings_t; SBML_getDefaultL3ParserSettings(); SBML_getLastParseL3Error()

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.

ASTNode_t * SBML_parseL3FormulaWithModel	(	const char *	formula,
		const Model_t *	model
	)

Parses a text string as a mathematical formula using a Model_t to resolve symbols, and returns an AST representation of the result.

This is identical to SBML_parseL3Formula(), except that this function uses the given model in the argument model to check against identifiers that appear in the formula. For more information about the parser, please see the definition of L3ParserSettings_t and the function SBML_parseL3Formula().

Parameters

formula	the mathematical formula expression to be parsed.
model	the Model_t object to use for checking identifiers.

Returns: the root node of an AST representing the mathematical formula, or NULL if an error occurred while parsing the formula. When NULL is returned, an error is recorded internally; information about the error can be retrieved using SBML_getLastParseL3Error().

See also: SBML_parseL3Formula(); SBML_parseL3FormulaWithSettings(); SBML_parseL3FormulaWithModel(); SBML_parseFormula(); SBML_getLastParseL3Error(); L3ParserSettings_t

ASTNode_t * SBML_parseL3FormulaWithSettings	(	const char *	formula,
		const L3ParserSettings_t *	settings
	)

Parses a text string as a mathematical formula using specific parser settings and returns an AST representation of the result.

This is identical to SBML_parseL3Formula(), except that this function uses the parser settings given in the argument settings. The settings override the default parsing behavior. The following parsing behaviors can be configured:

A Model_t object may optionally be provided to use identifiers (values of type SId) from the model in preference to pre-defined MathML symbols More precisely, the Model_t entities whose identifiers will shadow identical symbols in the mathematical formula are: Species_t, Compartment_t, Parameter_t, Reaction_t, and SpeciesReference_t. For instance, if the parser is given a Model_t containing a Species_t with the identifier "pi", and the formula to be parsed is "3*pi", the MathML produced by the parser will contain the construct <ci> pi </ci> instead of the construct <pi/>. Another example, if the passed-in Model_t contains a FunctionDefinition_t with the identifier "sin", that function will be used instead of the predefined MathML function <sin/>.
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 either collapsed or preserved; that is, the parser can either (1) remove sequential pairs of unary minuses (e.g., "- -3") from the input and incorporate single unary minuses into the number node, or (2) preserve all minuses in the AST node structure, turning them into ASTNode_t objects of type AST_MINUS.
The character sequence "number id" can be interpreted as a numerical value number followed by units of measurement indicated by id, or it can be treated as a syntax error. (In Level 3, MathML <cn> elements can have an attribute named units placed in the SBML namespace, which can be used to indicate the units to be associated with the number. The text-string infix formula parser allows units to be placed after raw numbers; they are interpreted as unit identifiers for units defined by the SBML specification or in the containing Model_t object.)
The symbol avogadro can be parsed either as a MathML csymbol or as a identifier. More specifically, "avogadro" can be treated as an ASTNode_t of type AST_NAME_AVOGADRO or of type AST_NAME.
Strings that match built-in functions and constants can either be parsed as a match regardless of capitalization, or may be required to be all-lower-case to be considered a match.
LibSBML plug-ins implementing support for SBML Level 3 packages may introduce extensions to the syntax understood by the parser. The precise nature of the extensions will be documented by the individual package plug-ins. An example of a possible extension is a notation for vectors and arrays, introduced by the SBML Level 3 Arrays package.

For more details about the parser, please see the definition of L3ParserSettings_t and SBML_parseL3FormulaWithSettings().

Parameters

formula	the mathematical formula expression to be parsed.
settings	the settings to be used for this parser invocation.

Returns: the root node of an AST representing the mathematical formula, or NULL if an error occurred while parsing the formula. When NULL is returned, an error is recorded internally; information about the error can be retrieved using SBML_getLastParseL3Error().

See also: SBML_parseL3Formula(); SBML_parseL3FormulaWithSettings(); SBML_parseL3FormulaWithModel(); SBML_parseFormula(); SBML_getLastParseL3Error(); L3ParserSettings_t

Examples:: translateL3Math.c.

char * writeMathMLToString ( const ASTNode_t * node )

Writes the given ASTNode_t (and its children) to a string as MathML, and returns the string.

Parameters

node	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. NULL is returned if the given argument is NULL.

char * writeMathMLToString ( const ASTNode * node )

Examples:: translateL3Math.c, and translateMath.c.

char * writeMathMLWithNamespaceToString	(	const ASTNode_t *	node,
		SBMLNamespaces_t *	sbmlns
	)

Writes the given AST node (and its children) to a string as MathML, and returns the string.

Parameters

node	the root of an AST to write out to the stream.
sbmlns	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. NULL is returned if the given argument is NULL.

Detailed Description

ASTNodeType_t

Converting between ASTs and text strings

Public Member Functions

Member Function Documentation