This section documents the following known problems, limitations, and possible pitfalls in using libSBML:
make uninstall
behavior
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.
char* SBML_formulaToString(const ASTNode* tree)
and ASTNode* SBML_parseFormula(const char* formula)
can be
used to convert mathematical formulas to/from a text-string format.
However, MathML (the XML encoding format used in SBML Levels 2
and 3 for mathematical formulas) does not have a defined standard
text-string representation. LibSBML arbitrarily uses the syntax defined by
SBML Level 1 (which used a text-string representation of formulas and
not MathML). For the most part, this syntax maps directly to MathML, but
there are differences in a few of the symbols used to represent
the common mathematical functions. In particular, in the text-string
syntax, log(x)
represents the natural logarithm, whereas in
MathML, the natural logarithm is <ln/>
. Application
writers are urged to consult the documentation for
SBML_formulaToString()
and SBML_parseFormula()
,
and to be careful when translating between text forms and MathML forms
(especially if their application provides a direct text-string input
facility to users).
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 if you are using
a system with libxml2 2.6.16, 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 in versions of the operating system up through 10.5.8.)
<notes>
and
<annotation>
elements).string
. 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.
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
.
(Thanks to Allyson Lister for reporting and solving the following.) For reasons that remain a mystery, attempting to use the libSBML Java interface from within an application installed as a war file in the stock version of Tomcat v.6 under the Ubuntu "Intrepid" release will result in exceptions such as the following:
java.lang.UnsatisfiedLinkError: org.sbml.libsbml.libsbmlJNI.new_SBMLReader()J
The cause appears to be unrelated to libSBML. Users are advised to
uninstall the stock tomcat6 package that comes from running the command
sudo apt-get install tomcat6
, and instead install the latest
version of Tomcat. The following detailed recipe comes from Allyson
Lister:
sudo apt-get remove
tomcat6
followed by sudo apt-get autoremove
to remove
the copy of Tomcat that came with the Ubuntu installation.
bin/catalina.sh
in an
editor and add the following line to the beginning of the file (after the
main comments section at the top of the file):
JAVA_OPTS="$JAVA_OPTS -Djava.library.path=/usr/local/lib"
SBMLDocument::setLevelAndVersion()
performs
conversion between versions and levels of SBML (to the extent possible
within technical and practical limits). However, conversion to/from SBML
Level 1 Version 1 is not supported.
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.