This page will look better in a graphical browser that supports web standards, but is accessible to any browser or internet device.

Served by Samwise.

Cardiac Physiome Society workshop: November 6-9, 2017 , Toronto

Obtaining dependent libraries and programs for JSim

Introduction: what is needed

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:

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 (September 2011) points to the 5.0.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 (which came on baggins) 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. 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 baggins; 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

So! Assuming you have all that, we're ready to compile. We're going to run cmake--if you're in a console window you'll want to run 'ccmake' (cmake for consoles); if you're actually at the computer in question, you can run 'cmake-gui' which is prettier and has a slightly better UI.

In any event, cd into the libsbml directory (libsbml-5.0.0/, *not* libsbml-5.0.0/src/), then create a new directory in which to build; I usually use the creative name 'build':

cd libsbml-5.0.0/; mkdir build; cd build
Then from that working directory, run ccmake or cmake-gui with the argument '..' for 'up one directory':
cmake-gui ..
(you're pointing at the root 'CMakeLists.txt' file)

Now hit the 'configure' button (cmake-gui) or 'c' (ccmake) and it'll churn a bit and make you a list of options. If you're on Windows, it'll ask which type of build system you want to use--I tend to use Visual Studio for my projects, but cygwin is also available, if you have that installed. For me, using ccmake on baggins, I see:

 CMAKE_BUILD_TYPE                *Release
 CMAKE_INSTALL_PREFIX            */usr/local
 CMAKE_OSX_ARCHITECTURES         *                                             
 CMAKE_OSX_DEPLOYMENT_TARGET     *                                             
 CMAKE_OSX_SYSROOT               */Developer/SDKs/MacOSX10.5.sdk
 ENABLE_LAYOUT                   *OFF
 ENABLE_UNIVERSAL                *OFF
 EXTRA_LIBS                      *                                             
 LIBBZ_INCLUDE_DIR               */usr/include
 LIBBZ_LIBRARY                   */usr/lib/libbz2.dylib
 LIBXML_INCLUDE_DIR              */usr/include/libxml2
 LIBXML_LIBRARY                  */usr/lib/libxml2.dylib
 LIBZ_INCLUDE_DIR                */usr/include
 LIBZ_LIBRARY                    */usr/lib/libz.dylib
 SWIG_EXECUTABLE                 */usr/bin/swig
 WITH_BZIP2                      *ON
 WITH_CHECK                      *OFF
 WITH_CPP_NAMESPACE              *OFF
 WITH_CSHARP                     *OFF
 WITH_DOXYGEN                    *OFF
 WITH_EXAMPLES                   *OFF
 WITH_EXPAT                      *OFF
 WITH_JAVA                       *OFF
 WITH_LIBXML                     *ON
 WITH_MATLAB                     *OFF
 WITH_OCTAVE                     *OFF
 WITH_PERL                       *OFF
 WITH_PYTHON                     *OFF
 WITH_RUBY                       *OFF
 WITH_SWIG                       *ON
 WITH_XERCES                     *OFF
 WITH_ZLIB                       *ON
with instructions on how to change these at the bottom. In the GUI, all the 'ON/OFF' options are check marks. We do indeed want to change some of the options here: from the top:

The first thing you probably should do is change the compiler from 'c++' to 'g++', since that's more likely to be what was used for other projects. So switch to the 'advanced view'--this is a button in the GUI, and the 't' button (for 'toggle') in ccmake. Find CMAKE_CXX_COMPILER and switch it to g++ (probably /usr/bin/g++) and hit 'compile' again. (When you change the compiler, all the other options get reset, so we have to do this first).

Next, if you're on a 64-bit system, you'll need to compile to a 32-bit architecture to be compatible with the rest of JSim. To do this, you'll again need to be in the 'advanced view'. Find 'CMAKE_CXX_FLAGS' and add '-m32', and find 'CMAKE_C_FLAGS' and add '-m32' there, too. (Note: if you compiled libexpat yourself, you'll need to do the same thing there. I edited the Makefile after running 'configure' and just added '-m32' to all the various CFLAGS and CXXFLAGS.) After changing these options, my ccmake screen here looks like:

 CMAKE_AR                         /usr/bin/ar                                  
 CMAKE_BUILD_TYPE                 Release                                      
 CMAKE_COLOR_MAKEFILE             ON                                           
 CMAKE_CXX_COMPILER               /usr/bin/g++                                 
 CMAKE_CXX_FLAGS                  -m32                                         
 CMAKE_CXX_FLAGS_DEBUG            -g                                           
 CMAKE_CXX_FLAGS_MINSIZEREL       -Os -DNDEBUG                                 
 CMAKE_CXX_FLAGS_RELEASE          -O3 -DNDEBUG                                 
 CMAKE_CXX_FLAGS_RELWITHDEBINFO   -O2 -g                                       
 CMAKE_C_COMPILER                 /usr/bin/gcc                                 
 CMAKE_C_FLAGS                    -m32                                         
 CMAKE_C_FLAGS_DEBUG              -g                                           
 CMAKE_C_FLAGS_MINSIZEREL         -Os -DNDEBUG                                 
 CMAKE_C_FLAGS_RELEASE            -O3 -DNDEBUG                                 
 CMAKE_C_FLAGS_RELWITHDEBINFO     -O2 -g                                       
After you've done this, toggle back to the regular view.

Next, set CMAKE_INSTALL_PREFIX to where you want libsbml installed. I tend to use '../install', which will build it in [libsbml]/install/

If your installed version of SWIG is old, you'll need to change 'SWIG_EXECUTABLE' to the version you compiled. For me, this was /Users/lpsmith/swig/bin/swig

Since space is an issue, we're going to turn off the automatic reading of .zip and .bz files: turn off both WITH_BZIP2 and WITH_ZLIB.

If you're compiling on a mac and want universal binaries (which you probably do), set ENABLE_UNIVERSAL to ON.

To get the java bindings, turn on WITH_JAVA. (note: 'WITH_SWIG' is required if you want Java; it's on by default and you can and should leave it on.)

There are three options for using a particular xml library: WITH_LIBXML, WITH_EXPAT, and WITH_XERCES. Exactly one of these should be turned on, and the other two should be turned off. By default, WITH_LIBXML is on, but CellML also uses libxml in a way that's incompatible with libsbml's use of it, so if you want CellML translation, turn that off, and turn on either expat or xerces. For me, this was 'WITH_EXPAT'.

Now hit the Configure button (or 'c') again. This will pop up new options if you changed the xml parsing library, namely, the directory where it found it. For me when compiling on linux, it found expat installed, but I went ahead and changed it to a version I compiled myself:

 LIBEXPAT_INCLUDE_DIR             /user3/lpsmith/expat/include                 
 LIBEXPAT_LIBRARY                 /user3/lpsmith/expat/lib/libexpat.so         
It will also find SWIG_DIR and SWIG_VERSION based on the version of SWIG_EXECUTABLE you set.

f you're on a mac, you'll also want to change CMAKE_OSX_ARCHITECTURES. JSim doesn't handle 64-bit yet, and jbb is moving away from his ppc, so for now we only need the i386: delete the amd64 and ppc option and just leave 'i386'. This kind of defeats the purpose of the 'ENABLE_UNIVERSAL' option, but I'd use it anyway as it's more explicit--if you don't, you might end up with a 64-bit version.

Hit 'configure' again, and if there are no further issues, you will now be able to hit 'g'/the 'Generate' button. If no such option appears, try hitting 'configure' again and looking for unset variables you think sound important. My final version on a mac looked like:

 CMAKE_BUILD_TYPE                 Release                                                    
 CMAKE_INSTALL_PREFIX             ../install                                                 
 CMAKE_OSX_ARCHITECTURES          i386;
 CMAKE_OSX_DEPLOYMENT_TARGET                                                                 
 CMAKE_OSX_SYSROOT                /Developer/SDKs/MacOSX10.5.sdk                             
 ENABLE_LAYOUT                    OFF                                                        
 ENABLE_UNIVERSAL                 ON                                                         
 EXTRA_LIBS                                                                                  
 LIBBZ_INCLUDE_DIR                /usr/include                                               
 LIBBZ_LIBRARY                    /usr/lib/libbz2.dylib                                      
 LIBEXPAT_INCLUDE_DIR             /usr/include                                               
 LIBEXPAT_LIBRARY                 /usr/lib/libexpat.dylib                                    
 LIBXML_INCLUDE_DIR               /usr/include/libxml2                                       
 LIBXML_LIBRARY                   /usr/lib/libxml2.dylib                                     
 LIBZ_INCLUDE_DIR                 /usr/include                                               
 LIBZ_LIBRARY                     /usr/lib/libz.dylib                                        
 SWIG_DIR                         /Users/lpsmith/swig/share/swig/2.0.3                       
 SWIG_EXECUTABLE                  /users/lpsmith/swig/bin/swig                               
 SWIG_VERSION                     2.0.3                                                      
 WITH_BZIP2                       OFF                                                        
 WITH_CHECK                       OFF                                                        
 WITH_CPP_NAMESPACE               OFF                                                        
 WITH_CSHARP                      OFF                                                        
 WITH_DOXYGEN                     OFF                                                        
 WITH_EXAMPLES                    OFF                                                        
 WITH_EXPAT                       ON                                                         
 WITH_JAVA                        ON                                                         
 WITH_LIBXML                      OFF                                                        
 WITH_MATLAB                      OFF                                                        
 WITH_OCTAVE                      OFF                                                        
 WITH_PERL                        OFF                                                        
 WITH_PYTHON                      OFF                                                        
 WITH_RUBY                        OFF                                                        
 WITH_SWIG                        ON                                                         
 WITH_XERCES                      OFF                                                        
 WITH_ZLIB                        OFF                                                        
Note that it doesn't matter that LIBBZ_LIBRARY etc. are set: since 'WITH_BZIP2' is off, it won't use it. If you didn't have it on your system and it's set to something like NOTFOUND this is OK.

After you've generated output, you'll then have Makefiles in your build/ directory. If you configured it for Visual Studio, you can load it up there; otherwise, you'll probably want to type 'make' now. If you want to see what's going on, type:

   make VERBOSE=true
If you leave off the VERBOSE bit, it'll still work, just be more mysterious.

Finally, install!

   make install
and it'll put it in ../install or wherever you pointed it!

For Windows/visual studio, the above instructions can still be followed. The only thing to keep in mind is that once you are in VS, you'll need to change the project to 'Release' yourself, since by default it'll always come up 'Debug'. Hitting 'build' will build everything, and building the INSTALL target will install it.

The files we will actually need in JSim are three:

[install]/share/libsbml/bindings/java/libsbmlj.jar
[install]/share/libsbml/bindings/java/libsbmlj.dylib (or .so or .dll)
[install]/lib/libsbml.dylib (or .so or .dll)
Note that on a Mac, the 5.0.0 CMake build would create bindings/java/libsbmlj.dylib, but this was changed in svn (so presumably for all future versions of the library) to create bindings/java/libsbmlj.jnilib It is the exact same file, and it is fine if you rename one to the other.

The .jar file goes in [JSim]/third/server/

And the other two go in [jsimauxlib]/[system]/

You'll need to re-run jsbuild.j to get the new .jar file (I think) and after that, you're good to go!

MacOS application issues: For libsbml to work properly in the MacOS double-click application, the reference to libsbml*.dylib in libsbmlj.jnilib must be changed. This is accomplished via $JSIMSRC/build/jsset_libsbmlj. This does not affect command-line launch of JSim on MacOS, only double-click launch. jssetup_libsbmlj requires you environment be set properly for a JSim source build.

# first set you enviromnent for a JSim source build (JSIMSRC, etc)
# then issue the following command in the MacOS libsbml build directory

jssetup_libsbmlj libsbmlj.jnilib

# pay attention to any error messages 

Building sbtranslate (Antimony)

Instructions for building sbtranslate are available on Antimony's website: http://antimony.sourceforge.net/antimony-installation.html. You should already have everything you need from building libsbml, with the exception of the CellML SDK. I'm not going to try to tell you how to build CellML here, because that's too complicated. My advice is to try downloading the SDK for your platform, and if it works, great, and if not, turn off Antimony's ability to translate CellML (by turning off 'WITH_CELLML' in CMake). If I recall correctly, the current version of JSim doesn't even attempt to use sbtranslate to translate CellML anyway.

A few other things of note:

Once you build sbtranslate, you'll need to put that plus all its dependencies into [jsimauxlib]/[system]/. The dependencies are:

Mac users: You may have to update the following script (sbtranslate.sh):
#!/bin/sh

# wrapper for sbtranslate
#  needed since forked process from JSim does not autoset DYLD_LIBRARY_PATH

DIR=`echo $0 | sed s/sbtranslate.sh//`

cd $DIR

export DYLD_LIBRARY_PATH=$DIR

./sbtranslate $*
due to name changes, etc. This script is necessary when users start JSim using the point and click method (as opposed to command line start-up) so that when JSim calls sbtranslate it can find the dependent libraries (libsbml.dylib libantimony.dylib).

Building SBML to Matlab code generator (sbml2matlab)

sbml2matlab is a translator program that converts an SBML model into a MATLAB function and it is used by JSim to convert JSim MML models(converted to SBML) into Matlab code. See sbml2matlab web site for up-to-date, detailed, build instructions. The sbml2matlab executable is dependent on the libSBML library.

Dependencies:

First download source code from sbml2matlab web site. Next, generate platform specific build instructions for sbml2matlab by creating a build directory and cd into it:
cd dir_where_sbml2matlab_code_is; mkdir build; cd build
Now run cmake ('ccmake ..' or 'cmake-gui') and fill out necessary information to generate build scripts for the particular platform. Below is an example from the MacOS:
 CMAKE_BUILD_TYPE                                                              
 CMAKE_INSTALL_PREFIX             ../install                                   
 CMAKE_OSX_ARCHITECTURES          i386                                         
 CMAKE_OSX_DEPLOYMENT_TARGET                                                   
 CMAKE_OSX_SYSROOT                /Developer/SDKs/MacOSX10.6.sdk               
 LIBSBML_BIN                      /Users/bartj/SBML/libsbml-5.4.1/install/lib  
 LIBSBML_INCLUDE                  /Users/bartj/SBML/libsbml-5.4.1/install/include
 LIBSBML_LIB                      /Users/bartj/SBML/libsbml-5.4.1/install/lib  
Advanced page of cmake ('t' toggle between pages):
 CMAKE_AR                         /usr/bin/ar                                  
 CMAKE_BUILD_TYPE                                                              
 CMAKE_COLOR_MAKEFILE             ON                                           
 CMAKE_CXX_COMPILER               /usr/bin/c++                                 
 CMAKE_CXX_FLAGS                  -m32                                         
 CMAKE_CXX_FLAGS_DEBUG            -g                                           
 CMAKE_CXX_FLAGS_MINSIZEREL       -Os -DNDEBUG                                 
 CMAKE_CXX_FLAGS_RELEASE          -O3 -DNDEBUG                                 
 CMAKE_CXX_FLAGS_RELWITHDEBINFO   -O2 -g                                       
 CMAKE_C_COMPILER                 /usr/bin/gcc                                 
 CMAKE_C_FLAGS                    -m32                                         
 CMAKE_C_FLAGS_DEBUG              -g                                           
 CMAKE_C_FLAGS_MINSIZEREL         -Os -DNDEBUG                                 
 CMAKE_C_FLAGS_RELEASE            -O3 -DNDEBUG                                 
 CMAKE_C_FLAGS_RELWITHDEBINFO     -O2 -g                                       
 CMAKE_EXE_LINKER_FLAGS                                                        
 CMAKE_EXE_LINKER_FLAGS_DEBUG                                                  
 CMAKE_EXE_LINKER_FLAGS_MINSIZE                                                
 CMAKE_EXE_LINKER_FLAGS_RELEASE                                                
 CMAKE_EXE_LINKER_FLAGS_RELWITH                                                
 CMAKE_INSTALL_NAME_TOOL          /usr/bin/install_name_tool                   
 CMAKE_INSTALL_PREFIX             /usr/local                                   
 CMAKE_LINKER                     /usr/bin/ld                                  
 CMAKE_MAKE_PROGRAM               /usr/bin/make                                
 CMAKE_MODULE_LINKER_FLAGS                                                     
 CMAKE_MODULE_LINKER_FLAGS_DEBU                                                
 CMAKE_MODULE_LINKER_FLAGS_MINS                                                
 CMAKE_MODULE_LINKER_FLAGS_RELE                                                
 CMAKE_MODULE_LINKER_FLAGS_RELW                                                
 CMAKE_NM                         /usr/bin/nm                                  
 CMAKE_OBJCOPY                    CMAKE_OBJCOPY-NOTFOUND                       
 CMAKE_OBJDUMP                    CMAKE_OBJDUMP-NOTFOUND                       
 CMAKE_OSX_ARCHITECTURES                                                       
 CMAKE_OSX_DEPLOYMENT_TARGET                                                   
 CMAKE_OSX_SYSROOT                /Developer/SDKs/MacOSX10.6.sdk               
 CMAKE_RANLIB                     /usr/bin/ranlib                              
 CMAKE_SHARED_LINKER_FLAGS                                                     
 CMAKE_SHARED_LINKER_FLAGS_DEBU                                                
 CMAKE_SHARED_LINKER_FLAGS_MINS                                                

The important parts are: compiler flags (-m32) and the locations of libsbml and sbml header files. When happy with the information hit 'configure' again, and if there are no further issues, you will now be able to hit 'g', the 'Generate' button to generate build information targeting the particular OS. Exit cmake. Now that the build files have been created then either type 'make' in the build directory or open up the MS visual studio .sln file with Visual Studio Express and build all (If building for MS Windows). Two files are generated which need to be copied over to jsimauxlib: Mac users: You may have to update the following script (sbml2matlab.sh):
#!/bin/sh

# wrapper for sbtranslate
#  needed since forked process from JSim does not autoset DYLD_LIBRARY_PATH

DIR=`echo $0 | sed s/sbml2matlab.sh//`

cd $DIR

export DYLD_LIBRARY_PATH=$DIR

./sbml2matlab $*
due to name changes, etc. This script is necessary when users start JSim using the point and click method (as opposed to command line start-up) so that when JSim calls sbml2matlab it can find the dependent libraries (libsbml.dylib and libNOM.dylib).

That's it!

Comments or Questions?

[This page was last modified 04Jan17, 1:51 pm.]

Model development and archiving support at physiome.org provided by the following grants: NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.