This section documents known problems, limitations, and possible pitfalls in using libSBML.
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.
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:
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.)
<notes>
and
<annotation>
elements).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. 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.
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
.
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.