libSBML C# API  5.20.2
Loading...
Searching...
No Matches
Working with math

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

Internally, libSBML uses Abstract Syntax Trees (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 MathML 2.0 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.

Basic concepts

Converting between ASTs and text strings

SBML Levels 2 and 3 represent mathematical expressions using using MathML 2.0 (more specifically, a subset of the content portion of MathML 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 and back 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 that 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.

The text-string form of mathematical formulas written by SBML_formulaToString() and SBML_formulaToL3String() , and read by SBML_parseFormula() and SBML_parseL3Formula() , 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.

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 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 3. We describe both below, beginning with the simpler but more limited system.

Simpler scheme based on SBML LevelĀ 1's syntax

The simpler, more limited translation system is read by SBML_parseFormula() and written by SBML_formulaToString() . It uses an infix notation essentially derived from the syntax of the C programming language and was originally used in SBML Level 1. We summarize the syntax here, but for more complete details, readers should consult the documentation for SBML_parseFormula() 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:

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

Token Operation Class Precedence Associates
namesymbol referenceoperand6n/a
(expression)expression groupingoperand6n/a
f(...)function callprefix6left
-negationunary5right
^powerbinary4left
*multiplicationbinary3left
/divisonbinary3left
+additionbinary2left
-subtractionbinary2left
,argument delimiterbinary1left
A table of the expression operators and their precedence in the text-string format for mathematical expressions used by SBML_parseFormula().

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 2) Reaction, or (in Level 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 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:

Text string formula functions MathML equivalents in SBML Levels 2 and 3
acosarccos
asinarcsin
atanarctan
ceilceiling
logln
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)
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.

Note that 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) always 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. The more advanced mathematical formula system, described below, offers the ability to control how log is interpreted as well as other parsing behaviors.

Advanced, SBML Level 3-oriented formula scheme

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.

Reading and Writing MathML directly

The example program given above demonstrate the use of these methods.