This section documents 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: true, false, exponentiale and pi. Most of them will not easily lead to a name collision, but unfortunately, the character sequence pi is also sometimes used as a species identifier by biological modelers (e.g., to use "Pi" to represent a phosphate ion). If the string "pi" or "Pi" appears in a text string passed to a libSBML method that interprets formulas, it will be interpreted as the mathematical constant π (pi). For example, the expression 2 * Pi will yield

<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 behavior

The 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:

  1. Libxml2 version 2.6.16 on MacOS X, which is the default version of libxml installed on Macs in /usr/lib up through at least 10.5.1, fails to report uses of undefined namespaces in an XML document. This means that a construct such as n:attribute, where n is a namespace prefix that is not defined, will be silently ignored. As a result, libSBML cannot catch and report this error when libSBML has been configured with this version of libxml2. We know of no workaround at this time except to compile your own copy of libxml2 or use another parser library. (Incredibly enough, libxml 2.6.16 built from original sources on a Mac does report the error. The only explanation is that that Apple is shipping a modified version of libxml 2.6.16.)
  2. Expat and libxml2 tend to quit earlier than Xerces when they encounter an XML error in an input stream, whereas Xerces tends to process the input further and report an error as being on the element in which the XML error occurs. The result is that the first error reported by libSBML is sometimes different depending on which of the underlying XML parsers is being used. In our tests, this affects almost exclusively low-level XML syntax errors (such as start/end tag mismatches, unterminated strings) and not SBML errors per se, although a basic XML error can of course mask other, more substantive errors. The exceptional cases (the reason for the "almost" in the previous sentence) concern SBML Level 2 Version 3 validation rules 10309 (detection of metaid syntax), and rules 10802, 10803, 21004 and 21005 (detection of disallowed XML constructs inside <notes> and <annotation> elements).
  3. Xerces 2.5 and 2.7 (and probably other versions) under Windows apparently suffers from a bug in transcoding multibyte UTF-8 characters. The underlying reason for the problem is that the Xerces transcoding functions in the Xerces 2.7 file Win32TransService.cpp calls the Windows transcoding function WideCharToMultiByte with a first argument of CP_ACP (meaning the Windows ANSI code page) rather than CP_UTF8. Why this is the case is a mystery to us. The effect is that Xerces on Windows does not translate some non-text UTF-8 characters the same way as on other platforms.

Potential for language bindings to link old versions of libSBML by accident

At application run-time, the language bindings for 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 make uninstall behavior

The libSBML make uninstall command on Linux, MacOS, Cygwin, and Solaris only knows about the features most recently configured into libSBML. If you run configure, then make install, then run configure again with different options, and finally try make uninstall, the result will be to attempt removing the files implied by the most recent run of configure, not the files installed by the original make install.

Warnings during creation of documentation

If you run the commands to generate the libSBML documentation, there will be warnings printed for all except the C++ documentation. These warnings still exist as of version 3.1 of libSBML. Most of the warnings are known incompatibilities that are next to impossible to resolve between the different tools used to generate different versions of the API documentation. It is probably safe to ignore them. Hopefully the warnings will be eliminated in a future version of libSBML.