libSBML C# API
libSBML 5.8.0 C# API
|
![]() | The following is a collection of guidelines for libSBML authors and other interested persons to follow when writing libSBML code and documenting it | |
![]() | This section presents a complete example program in C++ demonstrating how to create a complete SBML Level 2 model programmatically and then writing the result to a file | |
![]() |
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 Advantages of a dedicated library for SBMLWhy 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:
Manipulating mathematical formulasIn 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. | |
![]() |
Known issues and pitfalls This section documents the following known problems, limitations, and
possible pitfalls in using libSBML:
Name collisions in mathematical expressions
In the C-like, text-based, formula expression syntax supported by libSBML
and used in SBML Level 1, four constants are reserved words:
<math xmlns="http://www.w3.org/1998/Math/MathML"> <apply> <times/> <cn type="integer"> 2 </cn> <pi/> </apply> </math> This problem exists for all four of the constants mentioned above, but is most commonly encountered in the context of "pi". Currently, the only ways to avoid this problem are either to avoid using the strings "pi" and "Pi" in this context, or to avoid using the text-string expressions altogether and instead use ASTs. All libSBML methods that accept text-string mathematical formulas have variants that accept ASTs instead. Differences in XML parser behaviorThe different parsers supported by libSBML (Xerces, Expat, libxml2) behave slightly differently when reading files, and the differences are difficult for libSBML to hide. The following are the differences of which we are currently aware:
Cannot report a failure of validation rule #10312The SBML Level 3 Version 1 Core specification defines validation rule #10312 as being The value of a "name" attribute must always conform to the syntax of typestring . Unfortunately,
given the way that all three XML parser libraries (libxml2, Expat, and
Xerces) work, it is impossible for libSBML to ever report this error
directly. The kinds of SBML input that would lead to a failure of this
validation rule cause the XML parsers to report overly general errors of
the "XML content not well formed" variety, and libSBML cannot determine the
true root cause. As a result, libSBML cannot detect when rule #10312 is
breached.
Different error number (either 20413 or 20409) may be reported depending on Level of SBML in useIn SBML Level 3 Version 1 Core, validation rule #20413 (concerning whether the ListOfUnits container element can be empty) subsumes what was validation rule #20409 in the specifications for SBML Level 2 Versions 2–4. Rule #20409 does not exist in Level 3. The consequence of this difference in the specifications is that an application may receive different validation error numbers for the same situation depending on whether it is dealing with a Level 2 or a Level 3 model.Potential for language bindings to link old versions of libSBML by accidentAt application run-time, the language bindings for C#, Java, Python, Perl and others must be able to dynamically link the core libSBML library file (i.e.,libsbml.so , libsbml.dylib or
libsbml.dll , depending on your operating system). If a user's
environment includes an old version of this library file, and it is picked
up at run-time instead of the correct library version, linking may fail
with mysterious errors about undefined symbols. Users and developers are
cautioned to make sure that their installations have matched versions of
libSBML components and are free of older versions that may be picked up
inadvertently.
Possible unexpected
| |
![]() | ||
![]() | This section describes libSBML's facilities for working with SBML representations of mathematical expressions | |
![]() | ||
![]() | This section summarizes how to read and write SBML content using the facilities provided by libSBML | |
![]() | This section describes the summary of extension support classes which are used for implementing a package extension in libSBML-5 | |
![]() | This section describes the summary of how to implement a package extension for libSBML-5 |