libSBML C++ API  5.10.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
LibSBML features at a glance

LibSBML is an application programming interface (API) library for reading, writing and manipulating files and data streams containing SBML content. Developers can embed the library in their applications, saving themselves the work of implementing their own parsing, manipulation and validation software. At the API level, the library provides the same interface to data structures independently of whether the model originated in SBML Level 1, 2 or 3. The library currently also offers the ability to translate many models between SBML Levels and Versions.

LibSBML is written in ISO standard C++ and C and is highly portable. It is currently supported on the Linux, Mac OS X, and Microsoft Windows operating systems, but it has been known to run under FreeBSD and Solaris with little or no modifications. The library provides language bindings for C, C++, C#, Java, Python, Perl, MATLAB, Octave, and Ruby. The package is distributed in both source-code form and as precompiled dynamic libraries for the Microsoft Windows, Linux and Apple Mac OS X operating systems; they are available from the sbml project on SourceForge.net.

Advantages of a dedicated library for SBML

Why not simply use a generic XML parsing library? After all, SBML is usually expressed in XML, and there exist plenty of XML parsers, so why not simply tell people to use one of them, rather than develop a specialized library? The answer is: while it is true that developers can use general-purpose XML libraries, there are many reasons why using a system such as libSBML is a vastly better choice.

One of the features of libSBML is its facilities for manipulating mathematical formulas supporting differences in representation between SBML Level 1 and higher Levels of SBML. LibSBML provides an API that allows working with formulas in both text-string and MathML form, and to interconvert mathematical expressions between these forms. The utility of this facility extends beyond converting between SBML Level 1 and other Levels. Many software packages provide users with the ability to express formulas for such things as reaction rate expressions, and these packages' interfaces often let users type in the formulas directly as text strings. LibSBML saves application programmers the work of developing formula manipulation and translation functionality. It makes it possible to translate those formula strings directly into Abstract Syntax Trees (ASTs), manipulate them using AST operations, and write them out in the MathML format of SBML Levels 2 and 3.

Another feature of libSBML is the validation it performs on SBML inputs at the time of parsing files and data streams. This helps verify the correctness of models in a way that goes beyond simple syntactic validation. Still another invaluable feature of libSBML is the domain-specific operations it provides beyond simple SBML-specific accessor facilities. Examples of such operations include obtaining a count of the number of boundary condition species, determining the modifier species of a reaction (assuming the reaction provides kinetics), and constructing the stoichiometric matrix for all reactions in a model.

Some of the other features of libSBML include the following:

  • Full SBML Support. All constructs in SBML Level 1, 2 and 3 Core are supported. For compatibility with some technically incorrect but popular Level 1 applications and models, the parser also recognizes and stores notes and annotations defined for the top-level <sbml> element (logging a warning).
  • Unified SBML Level 3, Level 2 and Level 1 object models. All objects have getSBMLDocument(), getModel(), getLevel(), and getVersion() methods, among other things.
  • Full XML and SBML Validation. All XML warnings and errors are logged with line and column number information and may be retrieved and manipulated programmatically.
  • Dimensional analysis and unit checking. LibSBML implements a thorough system for dimensional analysis and checking units of quantities in a model. The validation rules for units that are specified in SBML Level 2 Version 2 and Version 3, as well as the equivalent warnings defined in SBML Level 2 Version 4 and Level 3 Version 1, are fully implemented, including checking units in mathematical formulas.
  • Access to SBML annotations and notes as XML objects. Annotations and notes are read and manipulated as XML structures instead of text strings. Further, in order to facilitate the support of MIRIAM compatible annotations, there are new object classes ModelHistory and CVTerm. These classes facilitate the creation and addition of RDF annotations inside <annotation> elements by providing parsing and manipulation functions that treat the annotations in terms of XMLNode objects implemented by the new XML layer. Both ModelHistory and CVTerm follow the general libSBML format of providing getters and setters for each variable stored within the class.
  • Support for SBO. The Systems Biology Ontology (SBO) is a machine-readable ontology tailored for computational modeling in systems biology. Annotating a model with SBO terms adds semantic information that can permit better software interpretation of the model's mathematical structure and (potentially) the ability to translate a model between different mathematical frameworks. LibSBML provides API methods for adding and working with SBO terms in SBML models.
  • Support for compressed SBML files. If an SBML file name ends in .gz, .zip or .bz2, libSBML will automatically uncompress the file upon reading it. Similarly, if the file to be written has one of those extensions, libSBML will write it out in compressed form. (The compression library incorporated by libSBML is MiniZip 1.01e, written by Gilles Vollant and made freely available for all uses including commercial applications.)
  • Parser abstraction layer. LibSBML relies on third-party XML parser libraries, but thanks to its implementation of an abstraction layer, libSBML can use any of three different popular XML parser libraries: Expat, Apache Xerces-C++, and Libxml2. LibSBML provides identical functionality and checking of XML syntax is available no matter which one is used. SBML Documents are parsed and manipulated in the Unicode codepage for efficiency; however, strings are transcoded to the local code page for SBML structures.
  • Convenience methods. LibSBML provides many other useful methods, such as for obtaining a count of the number of boundary condition species, determining the modifier species of a reaction (assuming the reaction provides kinetics), and more.
  • Small memory footprint and fast runtime. The parser is event-based (SAX2) and loads SBML data into C++ structures that mirror the SBML specification.
  • Interfaces for C, C++, C#, Java, Python, Perl, MATLAB, Octave, and Ruby. The C and C++ interfaces are implemented natively; the C#, Java, Perl, Python, and Ruby interfaces are implemented using SWIG, the Simplified Wrapper Interface Generator; and the MATLAB and Octave interfaces are implemented through custom hand-written code.
  • Well tested: libSBML has over 4300 unit tests containing a total of over 17,000 individual assertions. In addition to these tests, libSBML contains over 4400 individually hand-written SBML XML files containing different variations of correct and incorrect SBML and XML syntax. The entire library was written using the test-first approach popularized by Kent Beck and eXtreme Programming, where it's one of the 12 principles.
  • Written in portable, pure ISO C and C++. The build system uses GNU tools (Autoconf, GNU Make) to build shared and static libraries.
  • Complete user manual. Documentation is available in the "docs" subdirectory in both pre-formatted and source form.

Manipulating mathematical formulas

In SBML Level 1, mathematical formulas are represented as text strings using a C-like syntax. This representation was chosen because of its simplicity, widespread familiarity and use in applications such as Gepasi and Jarnac, whose authors contributed to the initial design of SBML. In SBML Levels 2 and 3, there was a need to expand the mathematical vocabulary of Level 1 to include additional functions (both built-in and user-defined), mathematical constants, logical operators, relational operators and a special symbol to represent time. Rather than growing the simple C-like syntax into something more complicated and esoteric in order to support these features, and consequently having to manage two standards in two different formats (XML and text string formulas), SBML Levels 2 and 3 leverage an existing standard for expressing mathematical formulas, namely the content portion of MathML.

LibSBML provides an abstraction for working with mathematical expressions in both text-string and MathML form: Abstract Syntax Trees (ASTs). Abstract Syntax Trees are well-known in the computer science community; they are simple recursive data structures useful for representing the syntactic structure of sentences in certain kinds of languages (mathematical or otherwise). Much as libSBML allows programmers to manipulate SBML at the level of domain-specific objects, regardless of SBML Level or version, it also allows programmers to work with mathematical formula at the level of ASTs regardless of whether the original format was C-like infix or MathML. LibSBML goes one step further by allowing programmers to work exclusively with infix formula strings and instantly convert them to the appropriate MathML whenever needed.