This section documents the following known problems, limitations, and possible pitfalls in using libSBML:

- Name collisions in mathematical expressions
- Differences in mathematical formula syntax
- Differences in XML parser behavior
- Cannot report a failure of validation rule #10312
- Different error number (either 20413 or 20409) may be reported depending on Level of SBML in use
- Potential for language bindings to link old versions of libSBML by accident
- Possible unexpected `make uninstall` behavior
- Explicit freeing of memory when using static MSVC runtimes
- Java exceptions when running in stock Tomcat 6 under Ubuntu "Intrepid"
- Conversion to/from SBML Level 1 Version 1 is not supported

## 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 mathematical formula syntax

The functions `char* SBML_formulaToString(const ASTNode* tree)` and `ASTNode* SBML_parseFormula(const char* formula)` (and their equivalents in the different language bindings supported by libSBML) 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).

## 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 MacOS 10.5.8, 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 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.)
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 Versions 3 and 4 validation rules 10309 (detection of metaid syntax), and rules 10802, 10803, 21004 and 21005 (detection of disallowed XML constructs inside `<notes>` and `<annotation>` elements).

## 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 `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.

## Different error number (either 20413 or 20409) may be reported depending on Level of SBML in use

In 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 accident

At 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 `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`.

## Explicit freeing of memory when using static MSVC runtimes

On MS Windows, when using libSBML compiled against a static MSVC runtime library, it is not possible to use the standard `free()` function call to free memory allocated and returned by libSBML. Without the ability to use `free()` to free the string returned by libSBML, the calling application will leak memory. An example of typical code where one would want to free the returned by libSBML is the following:

       char * formula = SBML_formulaToString(astNode);
       /* ... do some work with formula here ... */
       free(formula);

To cope with this issue, as of version 4.2, libSBML now provides a special function for this situation: `util_free()`.

## Java exceptions when running in stock Tomcat 6 under Ubuntu "Intrepid"

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

1. Run `sudo apt-get remove tomcat6` followed by `sudo apt-get autoremove` to remove the copy of Tomcat that came with the Ubuntu installation.
2. Download the latest version of Tomcat (6.0.18) from the Tomcat website, and unpack it into a location of your choosing.
3. Open `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"

4. Start Tomcat and load your war file. The application should now be able to access all the native libraries from libSBML.

## Conversion to/from SBML Level 1 Version 1 is not supported

The method `setLevelAndVersion()` on the class `SBMLDocument` 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.