libSBML C++ API  5.12.0
LibSBML features at a glance

LibSBML is an application programming interface (API) library for reading, writing and manipulating files and data streams containing content in SBML (Systems Biology Markup Language) format. 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. LibSBML also fully supports all accepted SBML Level 3 packages.

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. Here are just some of the features offered by libSBML:

  • Full SBML Support. All constructs in SBML Level 1, 2 and 3 Core are supported, as are the constructs defined in the officially ratified SBML Level 3 packages.
  • 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. LibSBML offers extensive validation against the SBML specifications; this helps verify the correctness of SBML models in a way that goes beyond simple schema-based validation. All XML warnings and errors are logged with line and column number information and may be retrieved and manipulated programmatically. LibSBML also does not force applications to read and write valid models: SBML validation is something that must be invoked explicitly, which allows callers to do such things as store incomplete models during editing.
  • 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.
  • Support for both MathML and text-string mathematical formulas. LibSBML offers facilities for manipulating mathematical expressions in both MathML form and a text-string format. It uses an Abstract Syntax Trees (AST) representation of mathematical formulas, supporting both in-memory operations and the ability to parse and write either text-string or MathML representations. It also supports extensibility by plug-ins for SBML Level 3 packages.
  • Facilities for converting and transforming SBML. LibSBML provides various facilities that include such important functionality as converting between SBML Levels and Versions (when possible). LibSBML can also transform within-SBML constructs, such as to expand all user-defined functions in-line, replace reactions with explicit differential equations, and many other transformations. This makes many general SBML models accessible to software systems that do not directly support certain SBML constructs, or can only read certain Level/Version combinations of SBML.
  • Other domain-specific facilities. LibSBML provides many other useful facilities relevant to developing models in SBML. 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.
  • Access to SBML annotations and notes as XML objects. LibSBML offers an API to facilitate the creation and addition of MIRIAM-compatible RDF annotations inside SBML <annotation> elements. Both these kinds of annotations and the related SBML <notes> element content can be read and manipulated as XML structures or text strings.
  • Support for SBO. LibSBML provides API methods for adding and working with Systems Biology Ontology (SBO) terms in SBML models. 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.
  • 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.
  • XML parser abstraction. 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.
  • Interfaces for C, C++, C#, Java, JavaScript, MATLAB, Octave, Perl, PHP, Python, R and Ruby (as mentioned above). The C and C++ interfaces are implemented natively; the C#, Java, JavaScript, Perl, PHP, Python, R 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.
  • Small memory footprint and fast runtime. The parser is event-based (SAX2) and loads SBML data into C++ structures that mirror the SBML specification.
  • Portability. LibSBML is written in ISO standard C++ and C and is highly portable. It currently runs on the Linux, Mac OS X, and Microsoft Windows operating systems, but it has been known to run under FreeBSD, Solaris and iOS with little or no modifications.
  • Support for both CMake and GNU autoconf and make. For core libSBML, both build systems are supported, allowing programmers greater flexibility in configuring and embedding libSBML in their software.
  • Extensive testing. LibSBML has several thousand unit tests containing a total of over tens of thousands of individual assertions. In addition to these tests, libSBML contains over 4400 hand-written SBML XML files containing different variations of both correctly and incorrectly written SBML and XML syntax.
  • Extensive documentation. Complete API documentation is available in the "docs" subdirectory, with individual API manuals for the different programming languages support by libSBML.

Users of libSBML often find its features convenient to use for more than simply supporting SBML. For example, many software packages provide users with the ability to express mathematical expressions for such things as reaction rate expressions, and these packages' interfaces often let users type in the formulas directly as text strings. LibSBML's API for mathematical formulas, with its support for text-string based input, thus saves application programmers the work of developing their own formula manipulation and translation facilities.

LibSBML 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 site on