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

Getting started: the 1-minute introduction

In LibSBML, the class libsbmlcs.SBMLDocument is used 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:

namespace LibSBMLCSExample
{
  using System;
  using System.IO;
  using libsbml;
  public class echoSBML
  {
    public static void Main ( string[] args )
    {
      if ( args.Length != 2 )
      {
        string myname = Path.GetFileName(Environment.GetCommandLineArgs()[0]);
        Console.WriteLine("Usage: {0} input-filename output-filename", myname);
        Environment.Exit(1);
      }
      string inputFile  = args[0];
      string outputFile = args[1];
      if ( ! File.Exists(inputFile) )
      {
        Console.WriteLine("[Error] {0} : No such file.", inputFile);
        Environment.Exit(1);        
      }
      SBMLReader   reader  = new SBMLReader();
      SBMLWriter   writer  = new SBMLWriter();
      SBMLDocument sbmlDoc = reader.readSBML(inputFile);
      if ( sbmlDoc.getNumErrors() > 0)
      {
        sbmlDoc.printErrors(); 
        Console.WriteLine("[Error] Cannot read {0}", inputFile);
        Environment.Exit(1);        
      }
      writer.writeSBML(sbmlDoc, outputFile);
      Console.WriteLine("[OK] Echoed {0} to {1}", inputFile, outputFile);
    }
  }
}

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 a C# import command to load the libSBML API into the running C# interpreter. Next, it instantiates an libsbmlcs.SBMLReader object and stores it in a variable called reader. Then, it uses this object to read an SBML model stored in a file, creating an libsbmlcs.SBMLDocument object in the process and storing it in the variable document. Finally, it calls on the libsbmlcs.SBMLDocument.getNumErrors() method to check if any errors were encountered.

Reading SBML

SBML may be read from a file or an in-memory character string into a libsbmlcs.SBMLDocument object. LibSBML defines two basic, convenient, global functions for reading SBML:

libsbmlcs.SBMLDocument libsbmlcs.libsbml.readSBMLFromFile(string filename). This function takes a file name, attempts to read an SBML document from the file, and returns a libsbmlcs.SBMLDocument object if successful.
libsbmlcs.SBMLDocument libsbmlcs.libsbml.readSBMLFromString(string xml). This function takes a string assumed to contain XML content, attempts to read an SBML document from the string, and returns a libsbmlcs.SBMLDocument object if successful.

The model may be either in SBML Level 1 or SBML Level 2 format. LibSBML implements an unified object model for SBML that encompasses both Level 1 and Level 2, 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 and Level 2!)

The libsbmlcs.SBMLDocument container

As might be deduced from the examples so far, an libsbmlcs.SBMLDocument object in libSBML represents a whole SBML model and its associated data. The libsbmlcs.SBMLDocument class 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. (But, it is created by libSBML no matter whether the model is Level 1 or Level 2.)

libsbmlcs.SBMLDocument is derived from libsbmlcs.SBase, so that it contains the usual libsbmlcs.SBase attributes (in SBML Level 2 Version 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 read. libsbmlcs.SBase (and thus its subclasses such as libsbmlcs.SBMLDocument) provides methods for querying this information:

int libsbmlcs.SBMLDocument.getLevel() returns the SBML Level of the model.
int libsbmlcs.SBMLDocument.getVersion() returns the SBML Version within the Level of the model.

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 object within an SBML document:

libsbmlcs.SBMLDocument.getModel() returns a libsbmlcs.Model object for the SBML model contained in the libsbmlcs.SBMLDocument.

libsbmlcs.SBMLDocument 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. 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:

int libsbmlcs.SBMLDocument.getNumErrors() returns a count of the diagnostic messages logged during while attempting to read an SBML model using either libsbmlcs.libsbml.readSBMLFromFile() or libsbmlcs.libsbml.readSBMLFromString().
libsbmlcs.SBMLError libsbmlcs.SBMLDocument.getError(long n) returns the error indexed by integer n in the error log. The libsbmlcs.SBMLError object class provides methods for displaying an error message, 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.
libsbmlcs.SBMLDocument.printErrors() prints to standard output all of the errors and diagnostics logged with the given libsbmlcs.SBMLDocument().
libsbmlcs.SBMLDocument.printErrors(OStream stream) is identical to the method above, but prints all of the diagnostics to the given output stream instead of the terminal.

Finally, another set of libsbmlcs.SBMLDocument 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!).

int libsbmlcs.SBMLDocument.checkConsistency() performs a set of structural and mathematical checks on the SBML content and reports the number of failed checks (errors) encountered. Use the libsbmlcs.SBMLDocument.getNumErrors() and libsbmlcs.SBMLDocument.getError(int n) interfaces to examine the individual errors.
int libsbmlcs.SBMLDocument.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.
int libsbmlcs.SBMLDocument.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.
int libsbmlcs.SBMLDocument.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.
int libsbmlcs.SBMLDocument.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.
int libsbmlcs.SBMLDocument.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.
int libsbmlcs.SBMLDocument.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.

This release of libSBML supports Levels/Versions of SBML up through Level 3 Version 2 Core Release 1 (RC 2).

Writing SBML

Writing SBML is, in the end, a very simple matter in libsbmlcs. The library provides the following methods for this purposes:

int libsbmlcs.libsbml.writeSBMLToFile(SBMLDocument d, string filename) writes the given SBML document to a file, and returns either 1 on success or 0 on failure. Reasons for failure can be, for example, that the named file could not be opened for writing.
string libsbmlcs.libsbml.writeSBMLToString(SBMLDocument d) returns the given SBML document as a character string, or returns an empty string if a failure occurred.