Systems Biology Simulation Core Library (SBSCL) 1.5 API

Simulation Core Library: Documentation

About Simulation Core Library

The Java™ API Simulation Core Library comprises a collection of integrators for differential equation systems combined with an interpreter for the Systems Biology Markup Language (SBML). It is the first simulation library that is based on JSBML. The user can read an SBML model and simulate it with one of the provided numerical integration routines. All SBML levels and versions are supported. The library can easily be integrated into customized software, such as parameter estimation tools.

When using the Simulation Core Library, please cite:
Roland Keller, Alexander Dörr, Akito Tabira, Akira Funahashi, Michael J. Ziller, Richard Adams, Nicolas Rodriguez, Nicolas Le Novère, Noriko Hiroi, Hannes Planatscher, Andreas Zell, and Andreas Dräger. The systems biology simulation core algorithm. BMC Systems Biology, 7:55, July 2013. [ DOI | link | pdf ]

How to integrate Simulation Core Library into your software?

You just have to add the provided jar-file simulation-core-library.jar to the class path of your Java project. Then you have access to all classes of the library. This library depends on the following third-party libraries:

• Commons-math-2.2.jar
• JUnit-4.8.jar
• JSBML

For SED-ML support, the following additional libraries are required:

• commons-io-1.4.jar
• jaxen-1.1.1.jar
• jdom-contrib.jar
• jdom.jar
• jlibsedml.jar
• jmathml.jar
• xom-1.2.1.jar

Please make sure to include the correct third-party libraries into your class path before working with this library.

The provided integration methods

The RosenbrockSolver is best suitable for integrating stiff differential equation systems and also has a precise timing of SBML events. It is taken and adapted from Kotcon et al. (2011)

Several further solvers have been taken from the Apache Commons Math Library and wrapped into our library:

• AdamsBashforthSolver
• AdamsMoultonSolver
• DormandPrince54Solver
• DormandPrince853Solver
• GraggBulirschStoerSolver
• HighamHall54Solver

The following solvers have been implemented additionally and are fast, but not suitable for all differential equation systems:

• EulerMethod
• RungeKutta_EventSolver

For a full list of available solvers, see org.simulator.math.odes.

Reading an SBML model and creating the respective differential equation system

A model can be read in by using the SBMLReader class from JSBML. With the model in memory the SBMLinterpreter can create the differential equation system that provides the basis for simulation:

      Model model = (new SBMLReader()).readSBML(sbmlfile).getModel();

      SBMLinterpreter interpreter = new SBMLinterpreter(model);
    

For more documentation about working with SBML models in simulations see org.simulator.sbml.

Simulation of a differential equation system

The created differential equation system can then be simulated with a chosen solver and given time points. The result is stored in a data structure called MultiTable.

      AbstractDESSolver solver = new RosenbrockSolver();

      double[] timePoints = {0.0, 0.1, 0.2, 0.3, 0.4, 0.5};

      MultiTable solution = solver.solve(interpreter, interpreter.getInitialValues(), timePoints);
    

Using SED-ML for simulation

The following example shows how to read in a File f (in SED-ML format) and how to run a simulation described in this file afterwards. The simulation results are stored in a MultiTable:

      SEDMLDocument doc = Libsedml.readDocument(f);

      SedML sedml = doc.getSBMLModel();

      Output wanted = sedml.getOutputs().get(0);

      SedMLSBMLSimulatorExecutor exe = new SedMLSBMLSimulatorExecutor(sedml, wanted);

      Map res = exe.runSimulations();

      MultiTable solution = exe.processSimulationResults(wanted, res);

    

For more information about how to use SED-ML to execute your simulation experiments, see org.simulator.sedml.

Simulation of the models in the SBML Test Suite

You can run the simulation of the models in the SBML Test Suite by using the command below. TestSuiteDirectory denotes the directory containing your copy of the (entire) SBML test suite. Here we assume that the actual test cases are located in the sub-folder cases/semantic/ within the TestSuiteDirectory on your computer. The simulation is conducted for the models with numbers from first to last (these numbers are the indices of the models in the test suite, without leading zeros).

      java -cp SimulationCoreLibrary_vX.Y_incl-libs.jar org.simulator.SBMLTestSuiteRunner TestSuiteDirectory/cases/semantic/ first last
    

Please note that, you have to replace _vX.Y_ within the library's name by the current release number, e.g., 1.2.

For example, if you like to simulate all test suite models ranging from 00259 to 00326, simply call the algorithm with first = 259 and last = 326.

Note that for the sake of a simple configuration, the simulation is started using default settings for the selection of the integration routine, step size etc.

The SBML Test Suite Database provides an up-to-date overview about the capabilities of various SBML-compliant solver implementations.

Simulation of the models from BioModels database

In a similar way, you can also download and simulate all models from BioModels database:

      java -cp SimulationCoreLibrary_vX.Y_incl-libs.jar org.simulator.TestBiomodels BioModelsDirectory/ first last
    

Again, you have to replace _vX.Y_ within the library's name by the current release number, e.g., 1.2. Please use the variables first and last without leading zeros as in the previous case. The variable BioModelsDirectory gives the path to your local copy of BioModels database.

As in the previous case, the simulation is conducted using default settings.

Listening to SBML constraint violation

In version 1.3 a new listener interface has been added to this library, which can be used to perform user-defined actions upon violation of a Constraint's math expression during a simulation. A simple implementation is already included in this package, which logs violation at the Level.WARNING using standard Java™ logging (see Logger). By default the SBMLinterpreter adds this SimpleConstraintListener to its internal list of ConstraintListeners.

You can remove this listener by calling the method SBMLinterpreter.removeConstraintListener(int), with the argument 0 for the first listener in the list, and add your own listener implementation with the help of method SBMLinterpreter.addConstraintListener(ConstraintListener).

The following example demonstrates how you can easily define your customized ConstraintListener:

      double timeEnd = 5d;

      SBMLDocument doc = SBMLReader.read(new File("path/to/file.xml"));

      SBMLinterpreter interpreter = new SBMLinterpreter(doc.getModel());

          interpreter.addConstraintListener(new ConstraintListener() {

               /* (non-Javadoc)

                    * @see org.simulator.sbml.ConstraintListener#processViolation(org.simulator.sbml.ConstraintEvent)

                    */

               public void processViolation(ConstraintEvent evt) {

                     System.err.println("Constraint violated at time " + evt.getTime() + ": " + evt.getSource().getMath().toFormula());

               }

          });

          solver.solve(interpreter, interpreter.getInitialValues(), 0d, timeEnd);
    

You can find more details about this topic in the description of package org.simulator.sbml.