JSim SBML support

Building SBML libraries and programs for JSim.

Introduction and requirements

JSim version 2.03 and above require the main libraries and java bindings from libSBML, the utility program sbtranslate from the Antimony package, and sbml2matlab program (JSim v2.07 and above) for full functionality. This document describes how to obtain what you need from those packages.

The core JSim program requires libsbml to perform its SBML/MML translations and Matlab code generation. This means that we need:

• libsbml, the core C++ library;
• libsbmlj, the SWIG-based wrapper Java-to-C++ library; and
• libsbmlj.jar, the java code that calls the SWIG library.

By default, libsbml distributions will statically link the libsbml library and the libsbmlj library (plus any dependent XML-reading libraries and compression libraries), so there is only a single library file that you need (libsbmlj), plus the jar file. If space is not an issue, it is highly recommended that this be used directly. However, if space is an issue, it is possible to compile the library yourself.

In addition, the Antimony program sbtranslate is used to perform the Antimony/MML translation, as well as (potentially) Antimony/MML/CellML translations. This is an external executable that also uses libsbml internally, as well as (potentially) the CellML API. Antimony binary distributions can also be used in any form, as long as 'sbtranslate' works. Again, if space is an issue, you may wish to ensure that sbtranslate uses the same version of libsbml that you use above. However, if the binary distribution of libsbml is being used, this will not use the libsbml library at all (as it is statically linked to libsbmlj instead), so it is not even necessary to ensure that the version of libsbml being used is the same! If space is indeed an issue, you'll need to compile from source, and at that point, you might as well compile libsbml at the same time.

Extracting from binaries:

Visit the libSBML home page, and follow the 'Download libSBML' link (which currently (April 2019) points to the 5.18.0 version). Assuming you are assembling binaries for distribution in the 'canonical' JSIMAUXLIB folders, you can get the two files you need (the libsbmlj library and the libsbmlj.jar file) from these distributions: follow the instructions for installation, and copy any of the libsbml.jar files (they should be functionally identical, if not actually identical) into $JSIMSRC/third/server/, and [libsbmlj.dll|libsbmlj.dylib|libsbmlj.so] into $JSIMAUXLIB/[win32|macos|linux]/. Next, visit the Antimony home page, and download any binary installers you find there (there will almost certainly be one for Windows, there may be one for MacOSX, and there probably will not be one for linux). Again, follow the instructions provided, and find the 'sbtranslate' executable. Copy this and all associated libraries into $JSIMAUXLIB. Assuming the version you download works with CellML, this will include several different libraries for that (including libxml2), plus the libsbml library, plus (on windows) two dll's needed to work with Visual Studio-compiled programs. Assuming you downloaded the binaries for libsbml, the libsbml library provided here may be the same or it may be different from the other; it won't matter, as libsbmlj is completely self-contained.

Building from source

Assuming either that space is an issue, or that the above binaries do not work or are not provided on your platform, you may need to build things from source. This should actually be fairly straightforward, as libSBML, Antimony, and even the CellML API now use CMake as their build system.

The first step, then, is to obtain CMake for all platforms on which you wish to build from source. If it is not already available on your system, you can get it from cmake.org. libSBML requires CMake version 2.8.0 or higher. Next, get the libsbml source from https://sourceforge.net/projects/sbml/files/libsbml/. As of this writing, the most recent was 5.0.0.

Unzip the file and cd into that directory. Now we need to change the java bindings from linking to the static version to linking to the dynamic version. Edit [libsbml]/src/bindings/java/CMakeLists.txt and search for '-static'. In 5.0.0, this line looked like: target_link_libraries(binding_java_lib ${LIBSBML_LIBRARY}-static ) Delete the '-static' bit, so it looks like: target_link_libraries(binding_java_lib ${LIBSBML_LIBRARY} ) The deal here is that the name of the static libsbml library is 'libsbml-static.a' and the name of the dynamic libsbml library is 'libsbml.so' (or whatever)--deleting '-static' will make it look for the dynamic one. This will save space, but will require that you always update both libsbml and sbtranslate at the same time in the future.

Next, we need a few programs and libraries: SWIG, and an XML parser--I went with 'expat'; other options are 'libxml' and 'xerces'. As of this writing, a bug in the CellML API makes using CellML and libsbml-with-libxml together impossible, so if a goal is to use sbtranslate's CellML translation capabilities, you should use expat or xerces. SWIG came pre-installed on most systems on which I tested, but version 1.3.31 had a bug in it that prevented compiling ('buffer overflow error'); the more recent 2.0.3 worked fine for me. I compiled it from source; the only warning here is that it will also need something called 'pcre', available from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. 'Configure' in the SWIG directory gave me easy-to-follow directions; I downloaded PCRE into the SWIG working directory, then ran, from that directory, Tools/pcre-build.sh and this configured and compiled pcre. Then I ran 'configure', 'make', and 'make install' from that same directory to get SWIG up and running, with

configure --prefix=/User/lpsmith/swig/

so it would compile into where I wanted it.

One word of caution here: If you want to be able to use a single libsbml.jar file, you will need the same version of SWIG everywhere you build (on Windows, linux, MacOS). Otherwise, the bindings can end up being different from one another. So I would recommend going with 2.0.3 (or whatever the latest is) on all three systems.

expat and libxml came preinstalled on MacOS; the only issue is that it's a dynamic library so you'd have to bundle it up with everything else. If you wanted to compile it static and link that into libsbml instead, you'd have one less file to deal with in distributing.

Building libsbml

MacOS application issues:

Building sbtranslate (Antimony)

Building SBML to Matlab code generator (sbml2matlab)