/** @page libsbml-math Mathematical Expressions and their Manipulation

This section describes libSBML's facilities for working with SBML
representations of mathematical expressions.

@section math-overview Basic concepts

LibSBML uses <a
href="http://en.wikipedia.org/wiki/Abstract_syntax_tree">Abstract Syntax
Trees</a> (ASTs) to provide a canonical, in-memory representation for all
mathematical formulas regardless of their original format (i.e., C-like
infix strings or MathML).  In libSBML, an AST is a collection of one or
more objects of class ASTNode.  An AST @em node in libSBML is a recursive
structure containing a pointer to the node's value (which might be, for
example, a number or a symbol) and a list of children nodes.  Each ASTNode
node may have none, one, two, or more child depending on its type.  The
following diagram illustrates an example of how the mathematical expression
"1 + 2" is represented as an AST with one @em plus node having two @em
integer children nodes for the numbers 1 and 2.  The figure also shows the
corresponding MathML representation:

@image html astnode-illustration.jpg "Example AST representation of a mathematical expression."
@image latex astnode-illustration.jpg "Example AST representation of a mathematical expression."

The following are noteworthy about the AST representation in libSBML:

@li 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 @c 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.
 
@li Rational numbers are represented in an AST node using separate
numerator and denominator values.  These can be retrieved using the methods
@link ASTNode::getNumerator() getNumerator() @endlink and @link
ASTNode::getDenominator() getDenominator() @endlink on an ASTNode object.

@li The children of an ASTNode are other ASTNode 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 the
applications can use the text-string based translation functions such as
SBML_formulaToString() and SBML_parseFormula().  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.

Finally, it is worth noting that the AST and MathML handling code in
libSBML remains written in C, not C++.  (All of libSBML was originally
written in C.)  Readers may occasionally wonder why some aspects are more
C-like and less object oriented, and that's one of the reasons.


@section math-convert Converting between ASTs and text strings

SBML Level 2 represents mathematical expressions using MathML, but most
applications do not use MathML directly.  Instead, applications generally
either interact with mathematics in text-string form, or else they use the
API for working with Abstract Syntax Trees (described below).  LibSBML
provides support for both approaches.  The libSBML formula parser has been
carefully engineered so that transformations from MathML to infix string
notation <em>and back</em> is possible with a minimum of disruption to the
structure of the mathematical expression.

The example below shows a simple program that, when run, takes a MathML
string compiled into the program, converts it to an AST, converts
<em>that</em> to an infix representation of the formula, compares it to the
expected form of that formula, and finally translates that formula back to
MathML and displays it.  The output displayed on the terminal should have
the same structure as the MathML it started with.  The program is a simple
example of using the various MathML and AST reading and writing methods,
and shows that libSBML preserves the ordering and structure of the
mathematical expressions.

<a class="anchor" name="example-program">
@verbatim
#include <iostream>
#include <sbml/SBMLTypes.h>

int
main (int argc, char *argv[])
{
  const char* expected = "1 + f(x)";

  const char* s = "<?xml version='1.0' encoding='UTF-8'?>"
    "<math xmlns='http://www.w3.org/1998/Math/MathML'>"
    "  <apply> <plus/> <cn> 1 </cn>"
    "                  <apply> <ci> f </ci> <ci> x </ci> </apply>"
    "  </apply>"
    "</math>";

  ASTNode* ast    = readMathMLFromString(s);
  char*    result = SBML_formulaToString(ast);

  if ( strcmp(result, expected) == 0 )
    cout << "Got expected result" << endl;
  else
    cout << "Mismatch after readMathMLFromString()" << endl;

  ASTNode* new_mathml = SBML_parseFormula(result);
  char*    new_s      = writeMathMLToString(new_mathml);

  cout << "Result of writing AST:" << endl << new_s << endl;
}
@endverbatim

The text-string form of mathematical formulas produced by
SBML_formulaToString() and read by SBML_parseFormula() are simple
C-inspired infix notation taken from SBML Level&nbsp;1.  It is summarized
in the next section below.  A formula in this text-string form therefore
can be handed to a program that understands SBML Level&nbsp;1 mathematical
expressions, or used as part of a translation system.  The libSBML
distribution comes with an example program in the @c "examples"
subdirectory called @c translateMath that implements an interactive
command-line demonstration of translating infix formulas into MathML and
vice-versa.  In summary, the functions available are the following:

@li <code>char * @link SBML_formulaToString(const ASTNode_t* tree)
SBML_formulaToString(const ASTNode* tree) @endlink</code> reads an
AST, converts it to a text string in SBML Level 1 formula syntax, and
returns it.  The caller owns the character string returned and should free
it after it is no longer needed.

@li <code>ASTNode * SBML_parseFormula(const char* formula)</code> reads a
text-string containing a mathematical expression in SBML Level 1 syntax and
returns an AST corresponding to the expression.


@section math-diffs The string formula syntax and differences with MathML

The text-string formula syntax is an infix notation essentially derived
from the syntax of the C programming language and was originally used in
SBML Level&nbsp;1.  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:

@verbatim
0.10 * k4^2
@endverbatim
@verbatim
(vm * s1)/(km + s1)
@endverbatim

The following table shows the precedence rules in this syntax.  In the
Class column, @em operand implies the construct is an operand, @em prefix
implies the operation is applied to the following arguments, @em unary
implies there is one argument, and @em 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
<em>a * b + c</em> is evaluated as <em>(a * b) + c</em> because the @c *
operator has higher precedence.  The Associates column shows how the order
of similar precedence operations is determined; for example, <em>a - b +
c</em> is evaluated as <em>(a - b) + c</em> because the @c + and @c -
operators are left-associative.  The precedence and associativity rules are
taken from the C programming language, except for the symbol @c ^, which is
used in C for a different purpose.  (Exponentiation can be invoked using
either @c ^ or the function @c power.)

@htmlinclude libsbml-math-precedence-table.html

A program parsing a formula in an SBML model should assume that names
appearing in the formula are the identifiers of Species, Parameter,
Compartment, FunctionDefinition, or Reaction 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 Level 2:

@htmlinclude libsbml-math-functions.html

@section math-ast Methods for working with libSBML's Abstract Syntax Trees

Every ASTNode in a libSBML abstract syntax tree has an associated type,
which is a value taken 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; their names hopefully evoke the construct that they
represent:

@htmlinclude libsbml-astnode-types.html

There are a number of methods for interrogating the type of an ASTNode and
for testing whether a node belongs to a general category of constructs.
The methods on ASTNode for this purpose are the following:

@li <code>ASTNodeType_t @link ASTNode::getType() getType() @endlink</code>
returns the type of this AST node.

@li <code>bool @link ASTNode::isConstant() isConstant() @endlink</code>
returns @c true if this AST node is a MathML constant (@c true, @c false,
@c pi, @c exponentiale), @c false otherwise.

@li <code>bool @link ASTNode::isBoolean() isBoolean() @endlink</code>
returns @c true if this AST node returns a boolean value (by being either a
logical operator, a relational operator, or the constant @c true or @c
false).

@li <code>bool @link ASTNode::isFunction() isFunction() @endlink</code>
returns @c true if this AST node is a function (i.e., a MathML defined
function such as @c exp or else a function defined by a FunctionDefinition
in the Model).

@li <code>bool @link ASTNode::isInfinity() isInfinity() @endlink</code>
returns @c true if this AST node is the special IEEE 754 value infinity.

@li <code>bool @link ASTNode::isInteger() isInteger() @endlink</code>
returns @c true if this AST node is holding an integer value.

@li <code>bool @link ASTNode::isNumber() isNumber() @endlink</code> returns
@c true if this AST node is holding any number.

@li <code>bool @link ASTNode::isLambda() isLambda() @endlink</code> returns
@c true if this AST node is a MathML @c lambda construct.

@li <code>bool @link ASTNode::isLog10() isLog10() @endlink</code> returns
@c true if this AST node represents the @c log10 function, specifically,
that its type is AST_FUNCTION_LOG and it has two children, the first of
which is an integer equal to 10.

@li <code>bool @link ASTNode::isLogical() isLogical() @endlink</code>
returns @c true if this AST node is a logical operator (@c and, @c or, @c
not, @c xor).

@li <code>bool @link ASTNode::isName() isName() @endlink</code> returns @c
true if this AST node is a user-defined name or (in SBML Level 2) one of
the two special @c csymbol constructs "delay" or "time".

@li <code>bool @link ASTNode::isNaN() isNaN() @endlink</code> returns @c
true if this AST node has the special IEEE 754 value "not a number" (NaN).

@li <code>bool @link ASTNode::isNegInfinity() isNegInfinity()
@endlink</code> returns @c true if this AST node has the special IEEE 754
value of negative infinity.

@li <code>bool @link ASTNode::isOperator() isOperator() @endlink</code>
returns @c true if this AST node is an operator (e.g., @c +, @c -, etc.)

@li <code>bool @link ASTNode::isPiecewise() isPiecewise() @endlink</code>
returns @c true if this AST node is the MathML @c piecewise function.

@li <code>bool @link ASTNode::isRational() isRational() @endlink</code>
returns @c true if this AST node is a rational number having a numerator
and a denominator.

@li <code>bool @link ASTNode::isReal() isReal() @endlink</code> returns @c
true if this AST node is a real number (specifically, AST_REAL_E or
AST_RATIONAL).

@li <code>bool @link ASTNode::isRelational() isRelational() @endlink</code>
returns @c true if this AST node is a relational operator.

@li <code>bool @link ASTNode::isSqrt() isSqrt() @endlink</code> returns @c
true if this AST node is the square-root operator

@li <code>bool @link ASTNode::isUMinus() isUMinus() @endlink</code> returns
@c true if this AST node is a unary minus.

@li <code>bool @link ASTNode::isUnknown() isUnknown() @endlink</code>
returns @c true if this AST node's type is unknown.


Programs manipulating AST node structures should check the type of a given
node before calling methods that return a value from the node.  The
following are the ASTNode object methods available for returning values
from nodes:

@li <code>long @link ASTNode::getInteger() getInteger() @endlink</code> 

@li <code>char @link ASTNode::getCharacter() getCharacter() @endlink</code> 

@li <code>const char* @link ASTNode::getName() getName() @endlink</code> 

@li <code>long @link ASTNode::getNumerator() getNumerator() @endlink</code> 

@li <code>long @link ASTNode::getDenominator() getDenominator()
@endlink</code>

@li <code>double @link ASTNode::getReal() getReal() @endlink</code> 

@li <code>double @link ASTNode::getMantissa() getMantissa() @endlink</code> 

@li <code>long @link ASTNode::getExponent() getExponent() @endlink</code> 


Of course, all of this would be of little use if libSBML didn't also
provide methods for @em setting the values of AST node objects!  And it
does.  The methods are the following:

@li <code>void @link ASTNode::setCharacter(char value) setCharacter(char
value) @endlink</code> sets the value of this ASTNode to the given
character <code>value</code>.  If character is one of @c +, @c -, @c *, @c
/ or @c ^, the node type will be to the appropriate operator type.  For all
other characters, the node type will be set to AST_UNKNOWN.

@li <code>void @link ASTNode::setName(const char *name) setName(const char
*name) @endlink</code> sets the value of this AST node to the given
<code>name</code>.  The node type will be set (to AST_NAME) <em>only
if</em> the AST node was previously an operator (<code>isOperator(node) !=
0</code>) or number (<code>isNumber(node) != 0</code>).  This allows names
to be set for AST_FUNCTIONs and the like.

@li <code>void @link ASTNode::setValue(int value) setValue(int value)
@endlink</code> sets the value of the node to the given integer
<code>value</code>.  Equivalent to the next method.

@li <code>void @link ASTNode::setValue(long value) setValue(long value)
@endlink</code> sets the value of the node to the given integer
<code>value</code>.  Equivalent to the previous method.  No, this is not a
G&ouml;delian self-referential loop.

@li <code>void @link ASTNode::setValue(long numerator, long denominator)
setValue(long numerator, long denominator) @endlink</code> sets the value
of this ASTNode to the given rational <code>value</code> in two parts: the
numerator and denominator.  The node type is set to AST_RATIONAL.

@li <code>void @link ASTNode::setValue(double value) setValue(double value)
@endlink</code> sets the value of this ASTNode to the given real (double)
<code>value</code> and sets the node type to AST_REAL.

@li <code>void @link ASTNode::setValue(double mantissa, long exponent)
setValue(double mantissa, long exponent) @endlink</code> sets the value of
this ASTNode to a real (double) using the two parts given: the mantissa and
the exponent.  The node type is set to AST_REAL_E.


Finally, ASTNode also defines some miscellaneous methods for manipulating
ASTs:

@li <code>ASTNode* @link ASTNode::ASTNode(ASTNodeType_t type)
ASTNode(ASTNodeType_t type) @endlink</code> creates a new ASTNode object
and returns a pointer to it.  The returned node will have the given
<code>type</code>, or a type of AST_UNKNOWN if no argument
<code>type</code> is explicitly given.

@li <code>unsigned int @link ASTNode::getNumChildren() getNumChildren()
@endlink</code> returns the number of children of this AST node or
<code>0</code> is this node has no children.

@li <code>void @link ASTNode::addChild(ASTNode* child) addChild(ASTNode*
child) @endlink</code> adds the given node as a child of this AST node.
Child nodes are added in left-to-right order.

@li <code>void @link ASTNode::prependChild(ASTNode* child)
prependChild(ASTNode* child) @endlink</code> adds the given node as a child
of this AST node.  This method adds child nodes in right-to-left order.

@li <code>ASTNode* @link ASTNode::getChild (unsigned int n) getChild
(unsigned int n) @endlink</code> returns the <code>n</code>th child of this
AST node or NULL if this node has no <code>n</code>th child [i.e., if
<code>n &gt; (node->getNumChildren() - 1)</code>, where <code>node</code>
is a pointer to a node].

@li <code>ASTNode* @link ASTNode::getLeftChild() getLeftChild()
@endlink</code> returns the left child of this AST node.  This is
equivalent to <code>getChild(0)</code>;

@li <code>ASTNode* @link ASTNode::getRightChild() getRightChild()
@endlink</code> returns the right child of this AST node or NULL if this
node has no right child.

@li <code>void @link ASTNode::swapChildren(ASTNode *that)
swapChildren(ASTNode *that) @endlink</code> swaps the children of this
ASTNode with the children of @c that ASTNode.

@li <code>void @link ASTNode::setType(ASTNodeType_t type)
setType(ASTNodeType_t type) @endlink</code> sets the type of this ASTNode
to the given ASTNodeType_t enumeration value.



@section math-reading Reading and Writing Mathematical Expressions into ASTs

As mentioned above, applications often can avoid working with raw MathML by
using either libSBML's text-string interface or the AST API.  However, when
needed, reading MathML content directly and creating ASTs is easily done in
libSBML using a method designed for this purpose:

@li <code>ASTNode* readMathMLFromString(const char* xml)</code> reads raw
MathML from a text string, constructs an AST from it, then returns the root
ASTNode of the resulting expression tree.

Similarly, writing out Abstract Syntax Tree structures is easily done using
the following method:

@li <code>char* writeMathMLToString(const ASTNode* node)</code> writes an
AST to a string.  The caller owns the character string returned and should free
it after it is no longer needed.


<p> The <a href="#example-program">example program</a> given above
demonstrate the use of these methods.


*/