libSBML C API  5.18.0
Reading and writing SBML content

Table of Contents

This section summarizes how to read and write SBML content using the facilities provided by libSBML.

This is only a basic orientation to these essential facilities of libSBML, and is far from exhaustive in its coverage. Readers are directed to the rest of this manual for more details about using libSBML's many features and facilities. Please use the navigation bar near the top of the page and the table of contents in the left-hand column for navigating to other parts of this manual.

Getting started: the 1-minute introduction

LibSBML provides the class SBMLDocument_t as a top-level container for storing SBML content and data associated with it (such as warnings and error messages). Here is a simple example to start this discussion:

#include <iostream>
#include <sbml/SBMLTypes.h>
using namespace std;
int
main (int argc, char* argv[])
{
SBMLDocument_t* document = readSBML(argv[1]);
unsigned int errors = document->getNumErrors();
cout << endl;
cout << " filename: " << argv[1] << endl;
cout << " error(s): " << errors << endl;
cout << endl;
if (errors > 0) document->printErrors(cerr);
return errors;
}

The code above illustrates probably the simplest possible use of libSBML: reading a model and printing any errors or warnings encountered. The code begins with the inclusion of a single SBML header file, SBMLTypes.h, which serves to include most of the other useful libSBML individual header files. Next, in the body of the main function, the line

SBMLDocument_t* document = readSBML(argv[1]);

reads in a file and returns a pointer to an SBMLDocument_t object. A subsequent call to the method getNumErrors() on that object returns the number of errors encountered (if any), and a call to printErrors() method prints the errors (if any) to the C++ standard error output stream.

Reading SBML

SBML may be read from a file or an in-memory character string into an SBMLDocument_t object. LibSBML defines two basic, convenient, global functions (not methods on a specific object class, but global functions in the classic C programming sense) for reading SBML:

The model may be in any SBML Level and Version combination. LibSBML implements an unified object model for SBML that encompasses all SBML Levels, so applications generally do not need to worry about differences in syntax between these definitions of SBML when reading and writing models. (However, applications still need to be concerned about the constructs used and how they are interpreted, since there are substantial differences between SBML Level 1, Level 2, and Level 3!)

The SBMLDocument_t container

As might be deduced from the examples so far, an SBMLDocument_t object in libSBML represents a whole SBML model and its associated data. SBMLDocument_t corresponds roughly to the class SBML (respectively, Sbml) defined in the specification for SBML Level 3 (respectively, Level 2), but it does not have a direct correspondence in SBML Level 1. (Nevertheless, it is created by libSBML no matter whether the model is Level 1, Level 2 or Level 3.)

SBMLDocument_t is derived from SBase_t, so that it contains the usual SBase_t attributes (in SBML Level 2 and 3) of "metaid" and "sboTerm", as well as the subelements "notes" and "annotation". It also contains the attributes "level" and "version" indicating the Level and Version of the SBML content that was read. SBase_t (and thus its subclasses such as SBMLDocument_t) provides methods for querying this information:

Of course, the whole point of reading an SBML file or data stream is to get at the SBML model it contains. The following method allows access to the Model_t object within an SBML document:

SBMLDocument_t also acts to log any problems encountered while reading the model from the file or data stream. Whether the problems are warnings or errors, they are reported through a single common interface involving the object class SBMLError_t. The example earlier on this page already showed some of the methods available for accessing errors and warnings; here is a slightly more complete list:

  • unsigned int getNumErrors() on an SBMLDocument_t object returns a count of the diagnostic messages logged while attempting to read an SBML model using either SBMLReader_t::readSBMLFromFile(const std::string& filename) or SBMLReader_t::readSBMLFromString(const std::string& xml).
  • const SBMLError_t* getError(unsigned int n) returns a specific error indexed by the integer n. (Callers should first use getNumErrors() to get the number of errors, so that they can know the range of valid index numbers.) The SBMLError_t object class provides methods for assessing the severity of the problem encountered and for finding out the line and column number of where the problem occurred in the SBML input.
  • void printErrors(std::ostream_t& stream = std::cerr) on an SBMLDocument_t object prints all of the diagnostics to the given output stream, defaulting to the standard error stream if no stream argument is given in the call.

Finally, another set of SBMLDocument_t methods worth mentioning in the context of reading SBML are those for running consistency-checking and validation rules on the SBML content. These methods assess whether the SBML is legal according to basic rules listed in the SBML Level 2 and Level 3 specification documents. Note that they are mostly structural checks, in the sense that they can indicate whether the SBML is properly constructed; they cannot tell if a model is nonsense. (But at least they can assess whether it's syntactically correct nonsense!).

  • unsigned int checkConsistency(), invoked on an SBMLDocument_t object, performs a set of structural and mathematical checks on the SBML content and reports the number of failed checks (errors) encountered. Callers may use getNumErrors() and getError(unsigned int n) interfaces to examine the individual errors.
  • unsigned int checkL1Compatibility() peforms a set of semantic consistency checks on the document to establish whether it can be converted to SBML Level 1, and returns the number of failures. If all the checks succeed, it returns 0.
  • unsigned int checkL2v1Compatibility() peforms a set of semantic consistency checks on the document to establish whether it can be converted to SBML Level 2 Version 1, and returns the number of failures. If all the checks succeed, it returns 0.
  • unsigned int checkL2v2Compatibility() peforms a set of semantic consistency checks on the document to establish whether it can be converted to SBML Level 2 Version 2, and returns the number of failures. If all the checks succeed, it returns 0.
  • unsigned int checkL2v3Compatibility() peforms a set of semantic consistency checks on the document to establish whether it can be converted to SBML Level 2 Version 3, and returns the number of failures. If all the checks succeed, it returns 0.
  • unsigned int checkL2v4Compatibility() peforms a set of semantic consistency checks on the document to establish whether it can be converted to SBML Level 2 Version 4, and returns the number of failures. If all the checks succeed, it returns 0.
  • unsigned int checkL3v1Compatibility() peforms a set of semantic consistency checks on the document to establish whether it can be converted to SBML Level 3 Version 1, and returns the number of failures. If all the checks succeed, it returns 0.

At the time of this release of libSBML, the most recent release of SBML is Level 3 Version 2 Core Release 1 (RC 2).

Writing SBML

Writing SBML is, in the end, a very simple matter in libSBML. The library provides the class SBMLWriter_t for this purpose, and SBMLWriter_t offers the following methods:

  • bool SBMLWriter_t::writeSBMLToFile(const SBMLDocument_t* d, const std::string& filename) writes the given SBML document to the named file and returns either true on success or false on failure. Reasons for failure can be, for example, that the named file could not be opened for writing.
  • char* SBMLWriter_t::writeSBMLToString(const SBMLDocument_t* d) writes the given SBML document to a character string and returns a pointer to it, or returns NULL if a failure occurred. The string is owned by the caller and should be freed (using the standard C function free()) after it is no longer needed.
  • bool SBMLWriter_t::writeSBML(const SBMLDocument_t* d, std::ostream_t& stream) writes the given SBML document to the given output stream and returns either true on success or false on failure.