The systems biology simulation core library

Abstract Summary Studying biological systems generally relies on computational modeling and simulation, e.g., model-driven discovery and hypothesis testing. Progress in standardization efforts led to the development of interrelated file formats to exchange and reuse models in systems biology, such as SBML, the Simulation Experiment Description Markup Language (SED-ML) or the Open Modeling EXchange format. Conducting simulation experiments based on these formats requires efficient and reusable implementations to make them accessible to the broader scientific community and to ensure the reproducibility of the results. The Systems Biology Simulation Core Library (SBSCL) provides interpreters and solvers for these standards as a versatile open-source API in JavaTM. The library simulates even complex bio-models and supports deterministic Ordinary Differential Equations; Stochastic Differential Equations; constraint-based analyses; recent SBML and SED-ML versions; exchange of results, and visualization of in silico experiments; open modeling exchange formats (COMBINE archives); hierarchically structured models; and compatibility with standard testing systems, including the Systems Biology Test Suite and published models from the BioModels and BiGG databases. Availability and implementation SBSCL is freely available at https://draeger-lab.github.io/SBSCL/ and via Maven Central. Supplementary information Supplementary data are available at Bioinformatics online.


Resources and availability
SBSCL is a freely available open-source library for analysis, simulation, and interpretation of systems biology models in various modelling frameworks.
The primary repository of SBSCL is available at /draeger-lab/SBSCL.
A demo repository is available at /draeger-lab/SBSCL-demo.

Installation via Maven
The repository of SBSCL is based on Maven . Using SBSCL is straightforward when adding it as a dependency to the Project Object Model (POM) file in a Java™ project, as listing 1 demonstrates. This declaration automatically loads also all transitive dependencies, i.e., all required third-party libraries.
The version number will increase when new releases of SBSCL become available and will be listed in the README.md file of the primary repository. A minimal example, demonstrating the use and how a simple POM file could be structured, is available within the demo repository that is ready to use and try out. The standalone application SBMLsimulator 6,8 provides a Graphical User Interface (GUI) for SBSCL and is freely available .
For illustration purposes, listing 2 below also shows a template for such a minimal pom.xml file. All that needs to be changed to make this minimal example work is filling in values for the placeholders [

Use-case examples
We will now discuss a few use-case examples to demonstrate using SBSCL as a solver engine within an application. Just like the example POM file above, the examples described in this section can also be found in the demo repository for SBSCL at /draeger-lab/SBSCL-demo in the form of fully functioning standalone programs. The online JavaDoc provides further information about the details and functioning of the classes below. Trying out the example programs below requires downloading models in Systems Biology Markup Language (SBML) format from one of the preeminent online databases, such as BioModels 27 or BiGG 24,30 . For more general advice in developing larger software projects, we refer to related publications 47 .

Fundamentals for working with SBML in Java
To reduce the examples to the main aspects relevant to working with SBSCL directly, we will first discuss a few general techniques so that the following source-code examples can build upon these. The JSBML library 10,34 efficiently parses SBML files and delivers an object of type SBMLDocument, as listing 3 on the following page demonstrates. In most following examples, we will assume that the main method is present and that it will just call the constructor of the example class by passing an SBMLDocument object to it as an argument. By this, we can assume the user needs to specify the path to the SBML file of interest as a command-line argument following the scheme outlined in listing 4 on the next page. The code below launches a demo application from the command line with the absolute or relative path to an SBML file as the only argument (args[0]).
All examples assume the given SBML file to include the necessary extension packages expected for the desired analysis. In practice, further case distinctions may be necessary to ensure that correct content is loaded. The SBML file will be parsed via JSBML 10,34 , and the resulting SBMLDocument will be passed to the constructor of the class for further processing. Any exception will stop the program and automatically print a stack trace, e.g., if the file cannot be found, parsed, or is invalid. Finally, we recommend to always initialise a logger for the class to handle output, e.g., warnings, user messages, or more fine-grained debug information. This method is valuable because the output can be forwarded to the console, a log file, or some GUI. In our examples, we use the logger shipped within the standard distribution. Other third-party packages may provide more advanced features. The subsequent examples assume a logger to be bound to the variable logger, as demonstrated in listing 5 on the following page. We here call the containing class MyClass for demonstration purposes. <modelVersion>4.0.0</modelVersion>   MultiTable solution = solver.solve(interpreter, interpreter.getInitialValues(), 0d, timeEnd); 5 / / P r i n t , p l o t , o r d i s p l a y t h e s o l u t i o n a s a t a b l e . . . 6 } It is also recommended to enable localisation support via the standard Java class MessageFormat, whose format method can be statically imported as listing 6 indicates. Once this is done, it can be directly called from anywhere within the Java class, just like any other method.

Deterministic dynamic simulation
Listing 7 demonstrates how to run a deterministic simulation by interpreting an SBML file as an ODE system. We assume the constructor to be called from the main method with two values: an SBMLDocument and a number that gives the end time for the simulation. SBML assumes simulations to always start at time t = 0, but SBSCL provides a more general implementation that allows the solver to work with other initial time points. It is also possible to pass an array with monotonously increasing double values to the solver to enforce that exact time points are met within the simulation. This technique can be crucial for model calibration, e.g., to compare the simulation's output to experimentally obtained values at specific time points. Many solvers are directly available within SBSCL (see figure 1 on page 7). We here use the RosenbrockSolver solver because it provides step-size adaptation and fine-grained error estimation, making it most precise and robust against stiff ODEs 23 . However, other solvers may have a faster runtime.
The result is a table data structure, which SBSCL calls MultiTable. This table possesses a shared time column for multiple data blocks. Such data blocks allow the simulation results to be organised in separate spreadsheets for compartments, reactive species, fluxes, and variable parameters. It is possible to access these values separately, display them as tables, write them to files, e.g., in Comma-Separated Values (CSV) format, or plot them directly using some suitable plotting framework.
The solve method of the DESSolver interface, from which the class AbstractDESolver inherits, also allows passing a customised observer as an additional argument. Such an observer needs to implement the PropertyChangeListener interface from the java.beans package. It can be handy for listening to interim results or or tracking the progress of the simulation, e.g., to display a progress bar or to plot values as they roll in. More detailed descriptions of the algorithms in this example can be found in a separate publication 23 .
It may look surprising that the SBMLinterpreter is asked to deliver initial values for the system. Those might not be directly stored in the SBML model but might be a target for more complex calculations, e.g., by solving initial assignments or other more involved operations. Of course, it is possible to pass customised initial conditions to the solver as needed. The solver also provides several settings, for instance, to adjust the step size as needed.

Stochastic simulation
Listing 8 on the following page shows a minimal example for running a stochastic simulation. Since the stochastic simulation part of SBSCL originates from the Framework for Evaluation of Reaction Networks (FERN) library 13 that uses a custom internal network to represent the SBML model, the procedure for loading the model diverges slightly from the other examples in this section. In the background, however, it also uses JSBML 10,34 for parsing the file.
To get the simulation result displayed, we need to initialise an observer now and add it to the simulator, in this case, an enhanced Gillespie solver 16 . The observer also requires a double value for the interval (comparable to the step size in deterministic simulation), an integer duration value, and an array of the species to be observed. As a general reference, the class Start within the package fern provides a fully-featured set of the stochastic simulation capabilities of SBSCL. Example files are, for instance, located in /src/main/resources/examples/ within the project's repository. String[] species = NetworkTools.getSpeciesNames(sim.getNet(), 6 NumberTools.getNumbersTo(sim.getNet().getNumSpecies() -1)); 7 Observer observer = new AmountIntervalObserver(sim, 0.1d, 5, species); 8 sim.addObserver(observer);  logger.info(format("Objective value:\t{0}", solver.getObjectiveValue())); 5 logger.info(format("Fluxes:\t{0}", solver.getSolution())); logger.warning(format("Solver returned null for model {0}.", doc.getModel().getName())); 8 } 9 } method from the standard Java class MessageFormat. All that needs to be done to conduct an FBA, is instantiating an object of type FluxBalanceAnalysis by passing an SBMLDocument to it. The objective value and the flux distribution can then be obtained from this instance. It is also possible to change the actual solver, which is handled by the underlying SCPSolver . The BiGG 24,30 Models Database provides many example models suitable for flux balance analysis with listing 9.

Simulating a hierarchically structured model
Listing 10 provides a code snippet that demonstrates how to simulate a model that includes the SBML extension package for the Hierarchical Model Composition (comp) extension. In this example, the result is displayed in the form of a table in a simple GUI. The path to the SBML file is here given as an argument within the variable args[0]. In the background, the CompSimulator class uses the so-called "flattening" routine implemented in the JSBML library. Flattening means that the hierarchically structured model is converted to a non-hierarchical model in memory, i.e., with a "flat" hierarchy of only one level. Afterwards, a regular solver can be applied to it. This example includes an uncomplicated display of the simulation results in a table on a dialogue window for illustration purposes. The SBML Test Suite 22 comprises some comp models, such as semantic test № 1128 in 01128-sbml-l3v1.xml, to run the code in listing 10.

Simulating SED-ML documents
The format SED-ML 45   logger.info(format("Outputs wanted: {0}", wanted.getId())); 17 IProcessedSedMLSimulationResults prRes = exe.processSimulationResults(wanted, res); 18 19 if (wanted.isPlot2d()) { The example in listing 11 shows how a SED-ML file can be loaded, interpreted, and executed using SBSCL's solvers. It makes extensive use of the execution framework from the jlibsedml library 1 . This framework performs boiler-plate code for operations such as post-processing of results and much more. This example is based on SED-ML Level 1 Version 2 3 elements, such as RepeatedTasks and FunctionalRange. The directory /src/test/resources/sedml/ within the SBSCL project contains example SED-ML files to test the code in listing 11.

Simulation of OMEX files
The Computational Modeling of Biological Networks (COMBINE) archive file format OMEX bundles many diverse files with a manifest file explaining the content 2 . This archive file format is most suitable for distributing many standardised files within one single compressed file. Consequently, an OMEX file may contain both a SED-ML file and an SBML file and possibly additional information, such as shared metadata 29 .
Listing 12 indicates how to load an OMEX file directly and to run it with SBSCL. For the sake of simplicity, we here assume that the given OMEX archive includes a SED-ML file, which does not always have to be the case. Consequently, further checks may be recommendable for ensuring the stability of end-user software. We also omit any demonstration for further processing of the individual simulation results but refer the reader to the examples above.
The file /src/test/resources/omex/12859 2014 369 MOESM1 ESM.omex within the SBSCL project repository can be used to test the code in listing 12.
2 Software design and implementation Figure 1 provides a simplified overview of the most central classes of SBSCL that are needed for the interpretation and simulation of systems biology models in different frameworks. Already the first release of SBSCL shipped the solvers for ODEs. For version 2, the SBML interpreter has been improved to support several new models from the SBML Test Suite 22 . Also, several problems were solved, including efficiency improvements and reduction of redundant source code.
Hierarchically structured models that rely on the comp extension package 37 for SBML are supported via the so-called flattening routine of the JSBML library 10,34 . The term "flattening" means that the model is first converted to a non-hierarchical, i.e., conventional, model in a pre-processing step, after which it can be directly solved using existing interpreters and solvers. By this, the support for models of this type strongly depends on the flattening algorithm within JSBML.
The FERN library 13 has been updated and incorporated into SBSCL to support stochastic simulation. It is now available as a separate repository ( /draeger-lab/FERN) for direct use. However, the maintenance continues within SBSCL, in which its classes have been adjusted for improved compatibility between the different frameworks. In doing so, the FERN package that initially depended on libSBML 5 was also migrated to JSBML.
New is also the package for constraint-based analysis, which currently contains the class FluxBalanceAnalysis and a linear solver based on the GNU Linear Programming Kit (GLPK). Additional Constraint-Based Reconstruction and Analysis (COBRA) methods are planned to be added in future releases and access to further linear solvers, which are included through the abstraction layer called SCPSolver .

Benchmark tests
We will now discuss the performance and accuracy of SBSCL based on the SBML Test Suite collection of edge-case models and published models from the online databases BioModels 27 and BiGG 24,30 and compare SBSCL to related software.  26 , as soon as Java™ parsers become available. In addition, since version 2.0, SBSCL comes with two new packages: for "stochastic simulation" using the FERN library 13 and for "flux balance constraints" based on the SCPSolver project.

Support of the SBML Test Suite
When SBSCL version 1.2 was released, it passed all tests from the ever-expanding test suite 23 . Meanwhile, the number of tests for the SBML core has increased, as figure 2 shows. In addition, test cases for specific extension packages have been created to cover more aspects of SBML. Figure 3 on the next page shows that release 2.1 of SBSCL supports and correctly solves the vast majority of the test cases from the current SBML Test Suite for SBML core, including deterministic and stochastic simulation tests and all tests for constraint-based simulation. As soon as the so-called "flattening" algorithm for converting hierarchically structured SBML models into monolithic models in the underlying JSBML library 10,34 is completed, SBSCL will immediately support more test cases for this SBML extension package called comp 37 .

News Documents Downloads Forums Facilities Community Events About
Google Site Search...

Register Log in
These test results were generated using Simulation Core Library 1.

2.
Results were submitted by RolandKeller on Thursday, March 28, 2013. Results were generated for the following SBML Level+Version: Highest.

Tests of SBML Core
The maps above shows the results of comparing each uploaded data file to the expected data for that test case. Each result is represented by a colored icon: green to indicate success, red to indicate test failure, yellow to indicate the application does not support some aspect(s) of that test, blue to indicate a result not included because the application does not support some aspect(s) of that test, gray to indicate a result is not included for unspecified reasons, and black to indicate a non-numeric problem with the result, such as missing data. You can hover your mouse over an icon to find out its test case number. To get more information about a specific case, click on the icon-the information will be presented in a new window.

8/23
Please contact use our issue tracking system for any questions or suggestions about this website.

News Documents Downloads Forums Facilities Community Events About
Google Site Search...

Register Log in
These test results were generated using Systems Biology Simulation Core Library (SBSCL) 2.

Tests of the Flux Balance Constraints Package Version 2
The maps above shows the results of comparing each uploaded data file to the expected data for that test case. Each result is represented by a colored icon: green to indicate success, red to indicate test failure, yellow to indicate the application does not support some aspect(s) of that test, blue to indicate a result not included because the application does not support some aspect(s) of that test, gray to indicate a result is not included for unspecified reasons, and black to indicate a non-numeric problem with the result, such as missing data. You can hover your mouse over an icon to find out its test case number. To get more information about a specific case, click on the icon-the information will be presented in a new window.

BioModel simulations
The BioModels Database 27 is one of the most commonly used online repositories for curated models in various formats from the community for COMBINE 11 . The BioModels Database facilitates collaboration and promotes the reuse, sharing, and repurposing of computational models in systems biology 9 .
To assess the usability and performance of SBSCL, we simulated the first 100 curated models from this online repository with SBSCL version 2.1, COmplex PAthway SImulator (COPASI) version 4.30.240 18 , and RoadRunner version 2.0.5 40 . All simulations were executed on the same machine using a single core 1 . Model load time and simulation time were timed separately, and the total time was calculated as the sum of load and simulate time. Model loading and simulation were performed in five independent runs for every simulator. All settings were identically selected for all simulators and all models as follows: • start = 0 • stop = 100 • steps = 100 • absolute tolerance = 1E-10 • relative tolerance = 1E-6.
for all models. SBSCL used the Rosenbrock solver with step-size adaptation. The comparison project provides the respective source code at /matthiaskoenig/sbscl-simulator-comparison.
Model load time is reported in figure 4 on the following page, simulation time in figure 5 on page 12, and total time in figure 6 on page 13. All 100 models could be executed successfully with SBSCL version 2.1, whereas COPASI version 4.30.240 and RoadRunner version 2.0.5 could execute 97 models successfully. However, due to the lacking support for delays in COPASI and RoadRunner, three models of circadian oscillations (BIOMD0000000024 35 , BIOMD0000000025 38 , BIOMD0000000034 39 ) could not be executed by the respective simulators.
All models loaded substantially faster with SBSCL (see figure 4 on the next page), mainly due to additional just-in-time compilation steps required in COPASI and RoadRunner. Simulations were overall the fastest with RoadRunner, followed by COPASI and RoadRunner figure 5 on page 12. Considering the combined load and simulation time for a single simulation (figure 6 on page 13), SBSCL has a much broader spread than the other simulators. Some models execute faster or slower than others compared to COPASI version 4.30.240 and RoadRunner version 2.0.5. COPASI and RoadRunner have clear advantages when executing many simulations after loading the model once. SBSCL could show similar performance for many models for a single simulation due to the faster model loading times.

BiGG Model simulations
BiGG 24,30 Models is a genome-scale metabolic network reconstructions database that integrates more than 100 published genome-scale metabolic networks 30 . For benchmarking our software suite for the FBA models, we simulated the entire suite of BiGG 24,30 Models using SBSCL version 2.1 and compared it with results obtained from COBRApy version 0.21.0 , a package for constraint-based modelling of metabolic networks based on the COBRA methods, which are widely used for genome-scale modelling of metabolic networks 12  All models loaded substantially faster with SBSCL (see figure 7 on page 14) than with COBRApy. Simulations were drastically faster with COBRApy than with SBSCL (see figure 8 on page 15). The combined load and simulation time for a single simulation (figure 9 on page 16) modelling is faster than COBRApy. COBRApy has a clear advantage when executing many simulations after loading the model once, whereas, for a single simulation, SBSCL has advantages due to the faster model loading times.

Comparison to other simulators with SBML support
The SBML software guide lists several tools that solve and simulate SBML models in various frameworks. We selected all those tools from this list, for which a report on supported SBML test cases is provided in the SBML Test Suite Database (on April 23 rd , 2021) and that are not superseded or replaced by a reimplementation (i.e., with a newer version of the same software). For example, libRoadRunner replaces the earlier software RoadRunner 40 . Table 1 on the following page presents an overview of all tools with their main features, which are subsequently described in more detail.

AMICI
The Advanced Multilanguage Interface for CVODES and IDAS (AMICI) supports differential equation models encoded in the formats PySB or SBML. It automatically compiles such models into executable formats for simulation. The supported output formats include Python modules, C++ libraries, or Matlab files in .mex format 14 . The compiled simulation files also facilitate forward sensitivity analysis, steady-state sensitivity analysis, and adjoint sensitivity analysis for likelihood-based output functions 19 .

BioUML
BioUML is an integrated environment for systems biology and collaborative analysis of biomedical data 25 . It comes with the support of SBML 33 , Systems Biology Graphical Notation (SBGN) 4,43 , the Biological Pathway Exchange (BioPAX) format 7 , PSI-MI, Open Biological and Biomedical Ontologies (OBO), and CellML 26 standards, along with providing different solvers for differential equations and methods for data analysis.

COPASI
COPASI is a standalone program designed for simulating and analysing biochemical networks and their dynamics 18 . This software application supports models in the SBML format (even with arbitrary discrete events). To simulate the behaviour of these models, COPASI provides implementations of ODEs solvers or Gillespie's stochastic simulation algorithm 17 .

FluxBalance
This teaching tool for FBA supports the fbc 31,32 for SBML Level 3 20,21 , including mapping flux distributions to SBML layouts 15 . Other simulation frameworks are not supported.

IBIOSIM
The computer-aided design (CAD) tool IBIOSIM aims to model, analyse, and design genetic circuits 46 . It primarily targets genetic circuits and analyses models representing metabolic networks, cell-signalling pathways, and other biological and chemical systems 28 . It supports importing all levels and versions of SBML and can export up to SBML Level 3 Version 1 21 .

LibRoadRunner
LibRoadRunner is a high-performance and portable simulation engine for systems and synthetic biology 19,40 . It comes up with the support of ODE solver, code for structural analysis, steady-state analyses, event handling, stochastic simulation with a significant C and C++ Application Programming Interface (API), and Python bindings.

LibSBMLSim
LibSBMLSim provides a C implementation of SBML core with support for Ordinary Differential Equations (ODEs), Differential Algebraic Equations (DAEs), and Delay Differential Equations (DDEs) and bindings to many languages (including Java™, C#, Python, and Ruby) 19,42 .

ModelBase
ModelBase is a free and expandable Python implementation for dynamic modelling, simulation, and analysis with SBML support 44 .

Morpheus
Morpheus is an environment for modelling, simulation, and studying multi-scale as well as multicellular systems 41 .

WinBEST-KIT
WinBEST-KIT is a simulator of biochemical reaction networks based on a GUI 36 .

Known limitations
The project's issue tracker at /draeger-lab/SBSCL/issues is available online to request new features or report any problems and limitations of SBSCL. Version 2.1 of SBSCL correctly solves the vast majority of the SBML Test Suite core test cases, as section 3.1 on page 8 indicates. A few test cases exist in which SBSCL currently fails to simulate correctly due to the following reasons: missing support for the delay property for the newly added rateOf function in SBML Level 3 Version 2 (see issue 46). some tests trigger events before the event condition is fulfilled (see issue 44).
In addition, some test cases have a stochastic nature which can fail sporadically. A compromise between runtime for the continuous integration and accuracy of the simulation results (depending on the number of runs used for averaging) had to be chosen.
Most failing test cases are related to the SBML extension package for the Hierarchical Model Composition (comp) package 37 for SBML Level 3. SBSCL uses the JSBML library 10,34 to flatten comp models and subsequently simulate the flattened models. Due to issues in JSBML with flattening the models, the comp package test cases fail to simulate. The issue is tracked via an issue in the JSBML repository at /sbmlteam/jsbml/issues/213. After resolving the flattening issue, the remaining comp tests will pass. Importantly, this is not a simulation issue with SBSCL, which supports all mathematical features in the comp model, but solely a problem of converting the hierarchical model to a non-hierarchical one.
All mentioned issues are tracked on the issue tracker and will be resolved in future versions of SBSCL.