biosimulators / biosimulators_gillespy2 Goto Github PK

GillesPy2 biochemical network simulation program via BioSimulators-compliant command-line interface and Docker container

Home Page: https://docs.biosimulators.org/Biosimulators_GillesPy2

License: MIT License

Dockerfile 2.56% Python 94.44% CSS 3.00%

systems-biology computational-biology biochemical-networks stochastic-simulation-algorithm sbml sed-ml combine-archive gillespy2 stochss stochkit

biosimulators_gillespy2's Introduction

BioSimulators

More comprehensive and more predictive models have the potential to advance biology, bioengineering, and medicine. Building more predictive models will likely require the collaborative efforts of many investigators. This requires teams to be able to share and reuse model components and simulations. Despite extensive efforts to develop standards such as COMBINE/OMEX, SBML, and SED-ML, it remains difficult to reuse many models and simulations. One challenge to reusing models and simulations is the diverse array of incompatible modeling formats and simulation tools.

BioSimulators addresses this challenge by providing is a registry of simulation tools, many of which provide consistent interfaces. These standardized simulation tools make it easier to find and run simulations. These standardized simulation tools build upon BioSimulators' standard for command-line interfaces for simulation tools, standard structure for Docker images of simulation tools, and format for capturing the capabilities (e.g., supporting modeling frameworks, simulation algorithms, modeling formats) of a simulation tool.

The BioSimulators website provides a web application for browsing this registry. This website provides links to the individual simulators and their containers. Instructions for using the containers are available at https://docs.biosimulations.org/users/simulating-projects/. Information about how to containerize a simulation tool and submit it to the registry is also available at https://docs.biosimulations.org/users/creating-tools/.

runBioSimulations provides a simple web application for using the containerized simulation tools in the BioSimulators registry to execute simulations. This makes it easy to run a broad range of simulations without having to install any software. BioSimulations provides a platform for sharing modeling studies, modifying published studies, and executing published studies using runBioSimulations.

This repository serves several function:

This repository is a central place for users to contribute and discuss issues related to BioSimulators.
This repository is a central place for simulation software developers to submit simulation tools to the BioSimulators registry.
This repository contains code for automated verification of the capabilities of containerized simulation tools.
This repository contains a Pipenv configuration and a Dockerfile for a Docker image with a Python environment with most of the validated simulation tools and tests for this Docker image

The code for the BioSimulators web application, REST API, and database is in the Biosimulations repository. The code for verifying the capabilities and accuracy of containerized simulation tools is in the BioSimulators test suite repository. The code for the individual simulation tools is spread across numerous repositories, including several owned by the BioSimulators GitHub organization.

Getting started

Users

We recommend that users use the hosted versions of runBioSimulations at https://run.biosimulations.org to execute simulations.

Each validated simulation tool is available as Docker image. Most of the validated simulation tools are also available as Python APIs. See https://biosimulators.org for information about the interfaces available for each tool and where they can be obtained.

A Docker image with a Python environment with APIs for most of the validated simulation tools is available at https://github.com/orgs/biosimulators/packages/container/package/biosimulators. An iPython shell for this environment can be launched by installing Docker and running the commands below. Information about using the Python APIs in the image is available at https://docs.biosimulations.org/users/simulating-projects/.:

docker pull ghcr.io/biosimulators/biosimulators
docker run -it --rm ghcr.io/biosimulators/biosimulators

Interactive tutorials for the Python APIs for simulation tools and for BioSimulators' API are available from Binder here.

Simulation software developers

Information about how to containerize a simulation tool and information about how to submit simulation tools to the registry is available at https://docs.biosimulations.org/users/publishing-tools/. We encourage developers to containerize their tools. However, BioSimulators also acccepts simulation tools that don't support BioSimulators' standards.

Developers

We welcome contributions to BioSimulators! Please see the Guide to Contributing for information about how to get started.

Technical documentation

Please see the links below for additional technical documentation.

Simulation tools, format converters, SED-ML/COMBINE validator, simulator test suite, and Python utilities: https://docs.biosimulations.org/users/biosimulators-packages/
REST API: https://api.biosimulators.org
Web site and database: https://docs.biosimulations.org

Known issues

Installation of individual simulation tools

Several simulation tools are not available from PyPI
- There is an open issue to publish LibSBMLSim to PyPI.
- The version of RBApy used by BioSimulators is a fork. This fork adds the ability to run simulation with GLPK and Gurobi, in addition to CPLEX. There is an open pull request to merge this fork. There is also an open issue to publish RBA to PyPI.
- BioNetGen, VCell and XPP cannot be installed from PyPI because they are not Python packages.
- Most simulation tools require dependencies which must be installed separately from pip. See each tool for its installation instructions.

BioSimulators consolidated Docker image

OpenCOR is not currently installed because OpenCOR is distributed as its own Python environment. A a result, OpenCOR is difficult to install into other environments, such as the consolidated BioSimulators environment. In addition, OpenCOR is also currently pinned to Python 3.7.
VCell is not currently installed because limited installation instructions are available. VCell also does not provide a compatible Python API.

Utilizing multiple simulation tools within a single Python environment

PySCeS and NEURON/NetPyNe cannot be imported into the same Python memory. This appears to be due to using different versions of SUNDIALS. Importing both causes segmentation faults. One workaround is to import the tools in separate forks that have separate memories.
CBMPy requires versions of SymPy that have microversion numbers. Currently, this is incompatible with the latest version of AMICI which requires SymPy >= 1.9, but no microversion of 1.9 is yet available.

License

This package is released under the MIT license.

Development team

This package was developed by the Karr Lab at the Icahn School of Medicine at Mount Sinai in New York and the Center for Cell Analysis and Modeling at UConn Health as part of the Center for Reproducible Biomodeling Modeling with assistance from the contributors listed here.

Funding

This package was developed with support from the National Institute for Bioimaging and Bioengineering (award P41EB023912).

Questions and comments

Please contact us at [email protected] with any questions or comments.

biosimulators_gillespy2's People

Contributors

Stargazers

Watchers

Forkers

briandrawert

biosimulators_gillespy2's Issues

Correct algorithm parameters in SED-ML for ex2 of model 28

This uses KISAO:0000029`. This algorithm only has on parameter 488 whose value is an integer. This needs to be changed.

Created modified version of model 297 test which GillesPy2 can test

GillesPy2 has problems with this example because it imprudently replaces ln with log in rate law expressions. See StochSS/GillesPy2#459. This can be turned into an example that GillesPy2 can simulate by making these replacements

Cln --> Clg
kdcln --> kdclg
kscln --> ksclg

Test Combine archive is invalid

The combine archive biomd0000000028.omex is not valid, and cannot be parsed by biosimulations_utils.

@jonrkarr Could I have some help with debugging this?

Algorithms/solvers to support and KiSAO ids

Solvers to initially support

KISAO terms exist for each of these algorithms and each of their parameters

gillespy2.solvers.numpy.ode_solver.ODESolver (integrator=lsoda): KISAO:0000088
- atol (float, default=1e-12): KISAO:0000211: absolute tolerance
- rtol (float, default=1e-6): KISAO:0000209: relative tolerance
- lband (int, default=None): KISAO:0000480: lower half bandwith
- uband (int, default=None): KISAO:0000479: upper half bandwith
- nsteps (int, default=500): KISAO:0000415: maximum number of steps
- first_step (float, default=0.0): KISAO:0000483: initial step size
- min_step (float, default=0.0): KISAO:0000485: minimum step size
- max_step (float, default=inf): KISAO:0000467: maximum step size
- max_order_ns (int, default=12) : KISAO:0000219: maximum non-stiff order (Adams order)
- max_order_s (int, default=5) : KISAO:0000220: maximum stiff order (BDF order)
gillespy2.solvers.cpp.ssa_c_solver.SSACSolver: KISAO:0000029: SSA
- seed (int, default=None): KISAO:0000488
gillespy2.solvers.numpy.tau_leaping_solver.TauLeapingSolver: KISAO:0000039: tau-leaping
- seed (int, default=None): KISAO:0000488
- tau_tol (float, default=0.03): KISAO:0000228: epsilon

Additional solvers to support

These require additional KiSAO terms. We should discuss with Anna Zhukova how they would prefer to represent vode/adams and vode/bdf within KiSAO. Same for hybrid-tau/RK45, hybrid-tau/RK23, etc.

I'm also not sure what the TauHybridSolver is. Unfortunately, GillesPy2 doesn't have much documentation or references. I think this might be slow-scale tau-leaping (10.1016/j.cma.2008.02.024). We need to ask Brian Drawert.

gillespy2.solvers.numpy.ode_solver.ODESolver (integrator=dopri5): KISAO:0000087
- atol (float, 1e-12): KISAO:0000211
- rtol (float, 1e-6): KISAO:0000209
- nsteps (int, 500): KISAO:0000415
- first_step (float, 0): KISAO:0000483
- max_step (float, inf): KISAO:0000467
- safety (float, 0.9) : Safety factor on new step selection
- ifactor (float, 10): Maximum factor to increase/decrease step size by in one step (description appears to be incorrect in SciPy)
- dfactor (float, 0.2): Minimum factor to increase/decrease step size by in one step
- beta (float, 0): Beta parameter for stabilised step size control
gillespy2.solvers.numpy.ode_solver.ODESolver (integrator=dop835): KISAO:0000436
- Same parameters as dopri5
gillespy2.solvers.numpy.ode_solver.ODESolver (integrator=vode)
- method (string, default=adams, range=['adams', 'bdf']): KISAO_0000475
- with_jacobian (bool, default=false):
- atol (float, default=1e-12): KISAO:0000211
- rtol (float, default=1e-6): KISAO:0000209
- lband (int, default=None): KISAO:0000480
- uband (int, default=None): KISAO:0000479
- order (int, default=12): KISAO:0000484
- nsteps (int, default=500): KISAO:0000415
- max_step (float, default=inf): KISAO:0000467
- min_step (float, default=0.0): KISAO:0000485
- first_step (float, default=0.0): KISAO:0000483
gillespy2.solvers.numpy.ode_solver.ODESolver (integrator=zvode)
- Same parameters as vode
gillespy2.solvers.numpy.tau_hybrid_solver.TauHybridSolver: maybe KISAO:0000028 , need to ask developers
- seed (int, default=None): KISAO:0000488
- tau_tol (float, default=0.03): KISAO:0000228
- integrator (string, default=lsoda, range=['RK45’, ‘RK23’, ‘Radau’, ‘BDF’, and ‘LSODA’]): KISAO_0000475

Solvers to potentially ignore

These solvers provide the same functionality as solvers above. We can ask Brian Drawert whether we should be using these, or the implementations above.

gillespy2.solvers.stochkit.stochkit_solvers.StochKitSolver (algorithm=ssa)
- seed: KISAO:0000488
gillespy2.solvers.stochkit.stochkit_solvers.StochKitSolver (algorithm=tau_leaping)
- seed: KISAO:0000488
- epsilon : KISAO:0000228
- threshold (minimum reactions  per  leap): KISAO:0000230
gillespy2.solvers.stochkit.stochkit_solvers.StochKitODESolver
Unclear whether this works and, if so, what the parameters are

Solvers to ignore

Identical to other solvers
- gillespy2.solvers.cpp.variable_ssa_c_solver.VariableSSACSolver
  From release notes: "This solver works identically to SSACSolver, but is optimized for multiple trajectories using variable input values for species and Parameters."
- gillespy2.solvers.numpy.ssa_solver.NumPySSASolver
  I assume this is equivalent to the C solver, but slower
Deprecated
- gillespy2.solvers.cython.cython_ssa_solver.CythonSSASolver
- gillespy2.solvers.numpy.basic_ode_solver.BasicODESolver
- gillespy2.solvers.numpy.basic_tau_hybrid_solver.BasicTauHybridSolver
- gillespy2.solvers.numpy.basic_tau_leaping_solver.BasicTauLeapingSolver

More documentation

https://gillespy2.github.io/GillesPy2/docs/build/html/classes/gillespy2.solvers.html
https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.ode.html
https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.solve_ivp.html

Are all of the results (predictions) for species?

@briandrawert To support SED-ML, we need to know the SBML XPATH of each recorded result. Are the results always predictions of species?

More specifically, do the keys of results_dict

_, results_dict = model.run(solver, ...)

map to these XPATHs?

/sbml:sbml/sbml:model/sbml:listOfSpecies/sbml:species[@id='{ key-of-results_dict }']

Create KISAO term for hybrid tau solver

This question is for the GillesPy2 developers

Providing BIOMD0000000028.omex as input gives error

using the file BIOMD0000000028.omex give the following error. The BIOMD0000000297.omex file is parsed correctly. The root level tag differs between the two. Biomod28 has the tag below, which may be causing the error with parsing the namespace.

<sedML xmlns="http://sed-ml.org/sed-ml/level1/version3"
  xmlns:addedPrefix="http://sed-ml.org/sed-ml/level1/version2" level="1" version="3">

File "gillespy2/lib/python3.8/site-packages/Biosimulations_utils/simulator/utils.py", line 74, in exec_simulations_in_archive
    task_executer(os.path.join(working_dir, model.file.name), model.format.sed_urn, simulation, working_dir, out_filename, 'csv')
  File "Biosimulators_GillesPy2/Biosimulators_gillespy2/core.py", line 260, in exec_simulation
    modify_xml_model_for_simulation(
  File "gillespy2/lib/python3.8/site-packages/Biosimulations_utils/simulation/sedml.py", line 1346, in modify_xml_model_for_simulation
    objs = et.xpath(obj_xpath, namespaces=namespaces)
  File "src/lxml/etree.pyx", line 2293, in lxml.etree._ElementTree.xpath
  File "src/lxml/xpath.pxi", line 325, in lxml.etree.XPathDocumentEvaluator.__init__
  File "src/lxml/xpath.pxi", line 259, in lxml.etree.XPathElementEvaluator.__init__
  File "src/lxml/xpath.pxi", line 131, in lxml.etree._XPathEvaluatorBase.__init__
  File "src/lxml/xpath.pxi", line 55, in lxml.etree._XPathContext.__init__
  File "src/lxml/extensions.pxi", line 81, in lxml.etree._BaseContext.__init__
TypeError: empty namespace prefix is not supported in XPath

@jonrkarr Do you know how to debug this? Is the sedml formatted incorrectly?

Are there conditions under which alternative solvers should be used?

This is a question for the GillesPy2 developers:

Models which have events aren't supported by SSACSolver. NumPySSASolver appears to support events.
Are there other such cases?

Isolate hanging behavior and submit bug to GillesPy2

Occasionally GillesPy2 simulations never terminate. I believe this originated around 1.5.11 - 1.6.2. Example runs:

Todo

Replicate bug with minimal example
Submit to GillesPy2

see if this cast should be handled by utils. The value is set as an expression

https://github.com/reproducible-biomedical-modeling/Biosimulations_GillesPy2/blob/99263c313ec125f2baacb206f8f2560adb5cc9ee/biosimulations_gillespy2/core.py#L67-L72

This issue was generated by todo based on a `TODO` comment in `99263c3`. It's been assigned to @bilalshaikh42 because they committed the code.

Licence

The licence is gpl-3.0-or-later.
See section 14

SEDML representation of KISAO terms is different from parameter map

The sedml specification states that the kisao term should be provided KISAO:0..x rather than the KISAO_0..x format in the kisao_algorithm_map in core.py.

@jonrkarr Confirming that we should change the format of the keys in the map? Will this change need to be reflected in the other simulators/elsewhere as well?