libSBML C# API
5.20.2
|
Accessing libSBML from software | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Asking questions, reporting issues | The continued improvement of libSBML is crucially dependent on your
feedback. Below are some means of discussing and sharing your
experiences.
Reporting bugs and other problemsPlease report problems and other issues using the issue tracker for libSBML on GitHub: https://github.com/sbmlteam/libsbml/issues. You can also report problems on the sbml-interoperability mailing list (see next section). This may have advantages, such as that other people may also have experienced the same issue and offer a workaround more quickly than the libSBML developers can respond. Finally, if you want to contact the libSBML developers directly, you can email them at libsbml-team@googlegroups.com. Mailing lists, web forums, and list archivesIf you use SBML (which seems likely, if you are using libSBML), we urge you to sign up for sbml-announce, the SBML announcements mailing list. It is a low-volume, broadcast-only list where new releases of SBML and other important events are announced. These announcements are not cross-posted to the other lists below, so it's important to subscribe to sbml-announce even if you subscribe to the other lists below. In addition, if you use libSBML, we highly recommend that you subscribe or monitor the mailing list sbml-interoperability. Subscribing to this list will enable you to keep in touch with the latest developments in libSBML as well as to ask questions and share your experiences with fellow users and developers of libSBML and other SBML software. The mailing list is vigilantly moderated by humans to prevent spam and off-topic postings. If you are interested in delving more deeply into libSBML, perhaps to make extensions and modifications, we recommend that you also subscribe or monitor the mailing list libsbml-development. Being a member of this list will enable you to keep in touch with the latest developments in libSBML as well as to ask questions and share your experiences with fellow developers and users of libSBML. Web-based interfaces for all lists are available at http://sbml.org/Forums/, for those who prefer to interact with the list via a web forum interface. This website is also where you will find the mailing list archives. (The lists and the forums are cross-posted, and the archives are identical to each other.) Notifications via RSS and TwitterIf you wish to get notifications of mailing list postings via RSS, an individual feed for each mailing list mentioned above is available at http://sbml.org/Forums/. If you wish to get general announcements about SBML and its use, you may want to follow sbmlnews on Twitter. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
▼How to extend libSBML to support SBML packages | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Step by step summary of the implementation of an extension | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Detailed explanation of each package extension class | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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:
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 SourceForge.net. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Building and installing libSBML |
This section explains how to build libSBML from the source distribution. Table of contents1. Procedures for Linux, Mac OS X, FreeBSD, Solaris and CygwinLibSBML supports two build systems: CMake, and GNU autoconf plus GNU make. CMake is preferred and is the only one supported for building SBML Level 3 package extensions; the use of GNU autoconf and GNU make is deprecated but is currently still used to build the documentation. In all cases below, you will need to download the libSBML source code archive from the download area on GitHub then unpack the archive somewhere on your computer. 1.1 Configuring using CMakeCMake is a cross-platform build configuration system that can be used to generate makefiles as well as project files for common development environments such as Visual Studio, Eclipse, Xcode and CodeBlocks. If you do not already have CMake installed on your system, please make sure to download and install a copy of CMake 3.10 or later from cmake.org on your computer system. Next, start up the CMake graphical user interface (GUI). This is a configuration tool that allows you to select options for configuring your libSBML build and then generate makefiles for running the actual build. The GUI will look something similar to the following screenshot: ![]() Screenshot of CMake when it first starts up. Shown here is the Mac OS X version of CMake; it will look similar but not identical on other operating systems. In the CMake GUI interface, first click on the Browse Source... button and navigate to the directory where you unpacked the libSBML source code archive on your file system. Next, check the value of the field Where to build the binaries. We use so-called “out-of-source builds” for libSBML, meaning that CMake will place compiled binary files in a separate build directory, not intermixed with the source files. If the field for the build directory in the CMake GUI is blank, or CMake filled it with a different value than what you prefer, click on the Browse Build... button to change the directory. After filling in the fields at the top of the interface, click on the Configure button. If this is the first time you have executed CMake's Configure command in the libSBML source directory, you may see a dialog such as the following, asking you whether it can create a subdirectory where it will compile libSBML. Click on the "Yes" button if the directory location is acceptable. ![]() Dialog presented by CMake before it creates the subdirectory that it will use to compile libSBML. ![]() Screenshot of the Configure screen under Mac OS X. Unless you have special requirements, select the default choices of "Unix Makefiles" and "Use default native compilers", then click the Done button. This will close the selection dialog, whereupon CMake will read the libSBML configuration files and populate the options area in the CMake GUI with various options for controlling how libSBML is built. These new options are displayed in red, as illustrated in the following screenshot. ![]() Screenshot of the CMake interface after the configuration step. In this panel, you can set values for various libSBML configuration/build options. To find out the meaning of a particular option, hover your mouse/pointer over the item for a few seconds until a tooltip appears—it will provide a short description of the option under the cursor. There are numerous options available; below, we point out just a few that are especially popular for customization:
Note that selecting options and configuring libSBML using the GUI actually involves a two-step process:
Once you are satisfied with the options selected and there are no more red items the dialog box, click on the Generate button. This will cause CMake to create configuration files for the compilation environment you selected in the beginning (e.g., Visual Studio under Windows, or regular Unix makefiles under Mac OS or Linux, and so on). The files will be placed in the "build" directory you indicated in the second line of the CMake GUI. Now please proceed to Section 1.3, Compiling and installing LibSBML. 1.2 Configuring using GNU MakeWarning: the use of GNU autoconf and GNU make is deprecated. It cannot be used to properly build the libSBML packages, and it has only been retained to build the libSBML documentation. Please use the CMake-based build system unless you are attempting to build the documentation. First, in a shell (terminal), 1.2.a Basic configuration for Linux, Mac OS X, Solaris, and Cygwin If you only want to build the C and C++ interfaces and install
libSBML into ./configure LibSBML requires a separate XML library for low-level XML tokenizing
and Unicode support. It will by default attempt to use the libxml2 XML library; if you
do not have libxml2 version 2.6.16 or later on your system, the
Instead of using libxml2, you can inform the ./configure --with-expat And for Xerces, use ./configure --with-xerces Compatibility warning: The default XML parser library used by libSBML is libxml2. If you chose to use another XML parser library instead, beware there is a known bug in Xerces 2.6.0 that cannot be worked around at this time and causes errors in software using it. Xerces versions 2.2 2.5, and 2.7.0 and above, are known to work properly, and all Expat versions above 1.95.8 are also known to work. If your copy of libxml2, Expat, or Xerces is installed in a
non-standard location on your computer system (e.g., a private home
directory),
./configure --with-libxml="DIR"
or
./configure --with-xerces="DIR"
or
./configure --with-expat="DIR"
where DIR is the
parent directory of where the ./configure --with-expat="/sw" By default, during the installation phase (i.e., when running
./configure --prefix="/my/favorite/path" Of course, you can combine the flags to 1.2.b Interfaces for C#, Java, JavaScript, MATLAB, Octave, Perl, Python, R and Ruby LibSBML's core is written in C and C++, but libSBML comes with APIs for
other languages as well. To enable the library extensions for C#, Java,
JavaScript, MATLAB, Octave, Perl, Python, R and/or Ruby, you need to supply additional
options to ./configure --with-matlab=/Applications/MATLAB_R2010a.app If you want to build multiple language bindings for libSBML, combine multiple flags together as in the following example: ./configure --with-java --with-python Some of the language interfaces provide additional configuration options
besides the basic ./configure --with-python --with-python-interpreter=/usr/bin/python2.6 Please run The libSBML distribution ships with certain interface files provided, so that you do not need to have the software necessary to recreate them. However, if you obtained the libSBML distribution from the project repository on GitHub, or you want to recreate the files deliberately, you may need to configure libSBML to use SWIG to regenerate the libSBML language interfaces. Please see the section below on using SWIG. Finally, note that these additional language bindings are implemented
via foreign function interfaces in the respective languages; in all cases,
the core C/C++ libSBML library still must be compiled and installed. The
language binding files are not standalone implementations. For
instance, the Java language API files consist of a file named
A warning about Java versions: we have been unable to successfully compile the libSBML Java interface using the GNU Compiler for Java (gcj), at least in the case of gcj version 4.4.3 under Ubuntu Linux version 10.10. We do not recommend using gcj with libSBML for this reason. 1.2.c Creating 32- and/or 64-bit binaries On some hardware and operating system combinations, it is possible to
compile 64-bit as well as 32-bit versions of programs. Normally, the most
sensible default will be chosen by the systems' compilers automatically,
but when you download third-party software or compile your own, sometimes
it becomes necessary to select specific versions. LibSBML is no exception.
To make it easier to build libSBML explicitly in a 32-bit or 64-bit
version, Whether you need to do this depends very much on your hardware, operating system, and the format of other libraries and programs on your system. Currently, the most common situation where this issue arises is on 64-bit systems where not all libraries (e.g., the XML parser libraries) are available in 64-bit format. Then, libSBML needs to be configured to be built as a 32-bit binary: ./configure --enable-m32 The two options 1.2.d Creating universal binaries on Mac OS X Apple Macintosh operating systems versions 10.4–10.6 provide the
option of building binaries that can run natively on either PowerPC or x86
(Intel) architectures, as well as in either 32-bit or 64-bit versions.
Compiling a library to be a so-called universal binary containing
multiple versions of the object code requires the use of special options at
compilation time. To configure libSBML to be built as a universal binary,
specify the optional argument
./configure --enable-universal-binary
By default, on Mac OS 10.5, the libSBML option above will construct a
universal binary containing 32-bit PowerPC and 32-bit Intel x86 binaries;
on Mac OS 10.6, this becomes 32-bit PowerPC, 32-bit x86, and
64-bit x86 binaries. If you want to build universal binaries with a different
combination of CPU architectures, then you can specify it as an optional
argument to the ./configure --enable-universal-binary="-arch i386 -arch ppc -arch x86_64 -arch ppc64" Beware that building with this option turn on results in the creation of larger libSBML binary files, because the files contain essentially two copies of the same code (one for each architecture). Finally, if both 1.2.e Configuring for SWIGImportant: libSBML is known to work with SWIG version 2.0.0 or later; earlier versions are known not to work. You must use version 2.0.0 or later. SWIG is the
Simplified Wrapper and Interface Generator and in libSBML it is used
to create the bindings for C#, Java, JavaScript, Python, and other
programming languages. To configure libSBML to use SWIG, use the
./configure --with-swig="DIR"
1.2.f Configuring support for compression LibSBML provides built-in support for reading and writing compressed
SBML files. This facility works transparently: if a given SBML filename
ends with one of the suffixes recognized for a compressed file (namely,
These features are enabled by default if the required libraries can be
found on your system. The libraries are the zlib library (for the gzip and
zip formats) and the bzip2 library (for the bzip2
format). If the libSBML configure program cannot find the libraries in the
locations where it searches by default, you can inform the configure
program where to look by adding the flag
To selectively disable specific library checks and format support, add
the option ./configure --enable-compression=no 1.2.g Configuring for generating documentation LibSBML comes with extensive documentation, and the document you are
currently reading is part of it. Because the documentation is large and
regenerating it requires the use of software tools that not all users may
have, the authors of libSBML supply a separate downloadable archive
containing only the documentation. The documentation archive file has a
name of the form The same documentation files should also be available online at http://sbml.org/Software/libSBML/, although this online copy normally corresponds to the last stable release of libSBML and may not be up-to-date with the latest development version of libSBML in the SVN repository on SourceForge. If you would like to generate the documentation yourself, you will need the following software tools in addition to a Unix-like environment (or Cygwin under Windows):
Once libSBML is configured as above, you can generate the documentation
files by running make java-manual # Note: use 'gmake java-manual' on FreeBSDto recreate just the Java documentation, or make cpp-manual # Note: use 'gmake cpp-manual' on FreeBSDto recreate just the C++ documentation, or make c-manual # Note: use 'gmake c-manual' on FreeBSDto recreate just the C documentation, or make python-manual # Note: use 'gmake python-manual' on FreeBSDto recreate just the Python documentation. 1.2.h Configuring for software unit testing libSBML provides built-in facilities for testing itself. To run the
unit tests, a second library is required, (Note: If you are using g++ version 3.3, you will need to avoid using Check version 0.9.5, and instead use version 0.9.2. The problem is an incompatibility between Check 0.9.5 and earlier versions of g++. It appears that the compatibility problems in Check 0.9.5 disappear with versions of g++ after 3.3.) To enable the unit testing facilities in libSBML, add the
./configure --with-check Following this, you must build libSBML and then you can run the tests: make # Note: use 'gmake' on FreeBSD make check # Note: use 'gmake check' on FreeBSD The make check step is optional and will build and run an extensive suite of unit tests to verify all facets of the library. These tests are meant primarily for developers of libSBML and running them is not required for the library to function properly. All tests should pass with no failures or errors. If for some reason this is not the case on your system, please submit a bug report using the mechanisms described in the section titled "Bug Reports, Mailing Lists, and Related Topics" elsewhere in this manual. 1.3 Compiling and installing libSBMLAfter the configuration step (and if you are using CMake, the generation of the makefiles), the final steps are to run the compilation process followed by a command to install libSBML on your system. 1.3.a Using CMake If you are using CMake, then in a terminal/shell window, first
cd SRC/build
Next, execute the following command to compile libSBML: make # Note: use 'gmake' on FreeBSD If all went well and libSBML compiled without errors, you can use the following command to install libSBML on your computer: sudo make install # Note: use 'sudo gmake install' on FreeBSD Once the libSBML files are installed as described above, you may need to perform additional steps so that software can find the libSBML library files at run time. Please see the instructions in the section on making libSBML accessible to your software, provided elsewhere in this documentation. 1.3.b Using GNU make Important: parallel GNU make builds of libSBML are not
supported at this time. Attempting to use the
If you are using GNU make and not using CMake, in a terminal/shell
window,
cd SRC
Next, execute the following commands to compile libSBML: make # Note: use 'gmake' on FreeBSD If all went well and libSBML compiled without errors, you can use the following command to install libSBML on your computer: sudo make install # Note: use 'sudo gmake install' on FreeBSD Once the libSBML files are installed as described in the sections above, you may need to perform additional steps so that software can find the libSBML library files at run time. Please see the separate section on making libSBML accessible to your software provided elsewhere in this documentation. 1.3.c Debugging build problemsIf something went wrong during the build step and the compilation of libSBML stopped with an error, it may be useful to get more information in order to debug the process.
If you need to contact the libSBML Team for help with debugging a failing
libSBML build, it will greatly help us to get a record of the debugging
output from a clean build. On Linux, Mac OS X and Cygwin, you can
use the convenient
Don't forget to type Once you type 1.4 Advanced configuration options Whether you use CMake or GNU make, there are some additional advanced
options that are uncommonly used, but still worth explaining. We list the
options below using their names as they appear in the CMake configuration
screen; the alternative
2. Procedures for WindowsThere are two ways to compile libSBML under Windows: using the native Windows compilation tools from Microsoft, and using the Cygwin environment. In this section, we focus on using the native Windows environment because this appears to be the more popular approach used by Windows-based users of libSBML. Cygwin users can follow essentially the same instructions as for other Unix environments given above. 2.1 Configuring using CMakeTo create configurations suitable for compiling libSBML using the native Windows build tools, we recommend using CMake to generate them. (If you do not already have CMake installed on your system, please begin by downloading a copy of CMake version 2.8.4 or later from cmake.org.) Once you have CMake installed, also download and unzip the libSBML source code archive from the download area on GitHub.net and save the archive somewhere on your file system, then unpack it. Before going further, an issue on Windows concerns the dependency libraries on which libSBML depends. CMake will try to find all the dependencies for the default options, which leads to problems if they do not exist. We recommend Windows users download the dependencies we have prepackaged at the following download location: Download and extract this file into the same folder where you unpacked
the libSBML source distribution. CMake will look for these dependencies in
a folder called Once you have the libSBML sources and the dependency libraries unpacked on your system, start up the CMake graphical user interface (GUI). It will look something like the following screenshot: ![]() Screenshot of CMake when it first starts up. Click on the Browse Source... button and navigate to the directory
where you unpacked the libSBML source code archive on your file system.
CMake should automatically fill in the next line, Where to build the
binaries, using a subdirectory named ![]() Screenshot of the Configure screen under Microsoft Windows 7. Choose the settings appropriate for the build environment you are using and click the Finish button. After you close the configuration screen, CMake will populate the options area with various options it reads from the libSBML configuration files. These new options are displayed in red, as illustrated in the following screenshot. ![]() Screenshot of the CMake interface after the configuration step. In this panel, you can set values for various libSBML configuration/build
options. For example, you can set the location into which the compiled
libSBML libraries will be installed by clicking on the line for
Select the options with which you wish to build libSBML. All the
options for configuring libSBML, including language bindings and SBML
Level 3 packages, are listed here and may be selected/deselected as
required. For instance, to include the Java language bindings, click the
check-box for Next, click on the Generate button. This will cause CMake to create project configuration files ("Solutions") for the compilation environment you selected in the beginning (e.g., Visual Studio 2010). 2.2 Compiling and installing using MSVCThe MSVC Solution will contain a number of projects files, depending on the configuration selected. The following screenshot illustrates what you should see when you use the Solution Explorer in MSVC, and some of the most important targets that you will find there: ![]() Screenshot of MSVC's Solution Explorer when viewing the MSVC Solution files generated using CMake.
Other projects generated by the libSBML CMake configuration system and listed in the MSVC Solution explorer are named to indicate the intended target. Some examples include the following:
A typical procedure for building libSBML using MSVC consistes of performing the following steps:
Once the libSBML files are installed as described in the sections above, you may need to perform additional steps so that software can find the libSBML library files at run time. Please see the instructions on Making libSBML accessible to your software provided on a separate page of this documentation. 3. Files installed by libSBML, and their locations If all went as it should, the libSBML object files should end up
compiled and installed on your system, in either the default location
(
If you have compiled additional language extensions with libSBML, these files will be installed as well, but their names and locations depend on the particular language extension. The following two tables summarize the possibilities. The first table lists the names of the files, while the second table below lists the pathnames where those files will be installed.
The next table gives the locations of the files listed in the table
above for Linux/Unix-based operating systems. The pathnames shown here are
relative to the prefix directory used in configuring libSBML (meaning the
value DIR given to the
4. What to do if problems ariseGiven the large number of variables that are involved in installing libSBML (e.g., operating systems versions, library versions, etc.), it is not impossible that issues arise when you try to get libSBML working. We offer the following tips for what to do if you encounter problems:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Known issues and pitfalls | This section documents the following known problems, limitations, and
possible pitfalls in using libSBML:
Potential for language bindings to link old versions of libSBML by accident At application run-time, the language bindings for C#, Java, JavaScript, Perl, PHP, Python and others must be able to dynamically link the core libSBML library file (i.e., Some versions of MATLAB include a conflicting version of libstdc++ Some versions of MATLAB produced for Linux include a version of the stdc++ library that conflicts with the version provided by the operating system. This copy of the library is installed in MATLAB's own directories. This may cause a conflict not in building libSBML, but running MATLAB code that use libSBML, such as The solution is to preload the system stdc++ library before invoking MATLAB. You can accomplish this by setting the Linux environment variable Once you know the path to the stdc++ library file, set the value of export LD_PRELOAD=/path/to/system/libstdc++for sh-based shells such as Bash, or setenv LD_PRELOAD /path/to/system/libstdc++for csh-based shells. Explicit freeing of memory when using static MSVC runtimesOn MS Windows, when using libSBML compiled against a static MSVC runtime library, it is not possible to use the standard char * formula = SBML_formulaToString(astNode); /* ... do some work with formula here ... */ free(formula); To cope with this issue, beginning with version 4.2, libSBML provides a special function for this situation: 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 #10312 The 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 type 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. Possible unexpected
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Working with math | This section describes libSBML's facilities for working with SBML representations of mathematical expressions | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Additional complete example programs | The libSBML distribution comes with the following selection of complete example programs in the top-level file directory named examples/csharp | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Mathematical Expressions and their Manipulation | This section describes libSBML's facilities for working with SBML representations of mathematical expressions | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Reading and writing SBML content from your software | This section summarizes how to read and write SBML content using the facilities provided by the libSBML C# API |