/** @page libsbml-math Working with math

@tableofcontents

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

Internally, libSBML uses <a target="_blank"
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
text strings or the XML-based <a target="_blank"
href="http://www.w3.org/TR/MathML2/">MathML&nbsp;2.0</a> format).  LibSBML
provides an extensive API for working with ASTs; it also provides facilities
for translating between ASTs and mathematical formulas writing in a
text-string notation, as well as translating between ASTs and MathML.


@section math-overview Basic concepts

@copydetails doc_what_is_astnode


@section math-convert Converting between ASTs and text strings

SBML Levels 2 and 3 represent mathematical expressions using using <a
href="http://www.w3.org/Math/">MathML&nbsp;2.0</a> (more specifically, a
subset of the <em>content</em> portion of MathML&nbsp;2.0), but most
applications using libSBML do not use MathML directly.  Instead, applications
generally interact with mathematics using either the API for Abstract Syntax
Trees (described below), or using libSBML's facilities for encoding and
decoding mathematical formulas to/from text strings.  The latter is simpler
to use directly, so we describe it first.

The libSBML formula parser has been carefully engineered so that
transformations from MathML to the libSBML infix text 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 libSBML's basic 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">
@if cpp
@code{.cpp}
#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_formulaToL3String(ast);

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

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

  std::cout << "Result of writing AST:" << std::endl << new_s << std::endl;
}
@endcode
@endif

@if conly
@code{.c}
NEED A C VERSION HERE ...
@endcode
@endif

@if python
@code{.py}
import libsbml

expected = "1 + f(x)"

xml = "<?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>"

ast    = libsbml.readMathMLFromString(xml)
result = libsbml.formulaToL3String(ast)

if (result == text):
    print "Got expected result"
else:
    print "Mismatch after readMathMLFromString()"

new_mathml = libsbml.parseL3Formula(result)
new_string = libsbml.writeMathMLToString(new_mathml)

print "Result of writing AST to string: "
print new_string
@endcode
@endif

The text-string form of mathematical formulas written by
@sbmlfunction{formulaToString, String formula} and 
@sbmlfunction{formulaToL3String, String formula}, and read by
@sbmlfunction{parseFormula, ASTNode tree} and
@sbmlfunction{parseL3Formula, ASTNode tree}, use a simple C-inspired 
infix notation.  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
mathematical expressions, or used as part of a translation system.


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

There are actually two text-based formula parsing/writing systems in libSBML:
one that uses a more limited syntax and was originally designed for
translation between SBML Level&nbsp;1 (which used a text-string format for
representing mathematics) and higher levels of SBML, and a more recent, more
powerful version that offers features to support SBML Level&nbsp;3.  We
describe both below, beginning with the simpler but more limited system.


@subsection math-original Simpler scheme based on SBML Level&nbsp;1's syntax

The simpler, more limited translation system is read by
@sbmlfunction{parseFormula, String formula} and written by
@sbmlfunction{formulaToString, ASTNode tree}.  It uses an infix notation
essentially derived from the syntax of the C programming language and was
originally used in SBML Level&nbsp;1.  We summarize the syntax here, but for
more complete details, readers should consult the documentation for
@sbmlfunction{parseFormula, String formula}.

Formula strings in this infix notation 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
<code>a + b * c</code> is evaluated as <code>a + (b * c)</code> because the
@c * operator has higher precedence.  The Associates column shows how the
order of similar precedence operations is determined; for example, 
<code>a - b + c</code> is evaluated as <code>(a - b) + c</code> 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 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, (in Level&nbsp;2) Reaction, or (in
Level&nbsp;3) SpeciesReference 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&nbsp;1.
In the subset of functions that overlap between MathML and SBML Level&nbsp;1,
there exist a few differences.  The following table summarizes the
differences between the predefined functions in SBML Level&nbsp;1 and the MathML
equivalents in SBML Levels&nbsp;2 and&nbsp;3:

@htmlinclude math-functions.html

Note that <strong>there are differences between the symbols used to represent
the common mathematical functions and the corresponding MathML token
names</strong>.  This is a potential source of incompatibilities.  Note in
particular that in this text-string syntax, <code>log(x)</code> always
represents the natural logarithm, whereas in MathML, the natural logarithm is
<code>&lt;ln/&gt;</code>.  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.  The
more advanced mathematical formula system, described below, offers the
ability to control how <code>log</code> is interpreted as well as other
parsing behaviors.


@subsection math-l3 Advanced, SBML Level 3-oriented formula scheme

@copydetails doc_summary_of_string_math_l3


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

While it is convenient to read and write mathematical expressions in the form
of text strings, advanced applications usually need more powerful ways of
creating, traversing, and modifying mathematical formulas.  For this reason,
libSBML provides a rich API for interacting with ASTs directly.  This section
summarizes these facilities; for more information, readers should consult the
documentation for the ASTNode class.

@copydetails doc_astnode_types

@copydetails doc_summary_of_astnode_methods

@section math-reading Reading and Writing MathML directly

@copydetails doc_summary_of_writing_mathml_directly

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


*/