|PyPI package| |Documentation| |Test results| |Test coverage| |Code
analysis| |License| |status| |Analytics|
*DE-Sim*: a Python-based object-oriented discrete-event simulator for modeling complex systems
==============================================================================================
*DE-Sim* is an open-source, Python-based object-oriented discrete-event
simulation (DES) tool that makes it easy to use large, heterogeneous
datasets and high-level data science tools such as
`NumPy <https://numpy.org/>`__,
`Scipy <https://scipy.org/scipylib/index.html>`__,
`pandas <https://pandas.pydata.org/>`__, and
`SQLAlchemy <https://www.sqlalchemy.org/>`__ to build and simulate
complex computational models. Similar to
`Simula <http://www.simula67.info/>`__, *DE-Sim* models are implemented
by defining logical process objects which read the values of a set of
variables and schedule events to modify their values at discrete
instants in time.
To help users build and simulate complex, data-driven models, *DE-Sim*
provides the following features:
- **High-level, object-oriented modeling:** *DE-Sim* makes it easy for
users to use object-oriented Python programming to build models. This
makes it easy to use large, heterogeneous datasets and high-level
data science packages such as NumPy, pandas, SciPy, and SQLAlchemy to
build complex models.
- **Stop conditions:** DE-Sim makes it easy to terminate simulations
when specific criteria are reached. Researchers can specify stop
conditions as functions that return true when a simulation should
conclude.
- **Results checkpointing:** DE-Sim makes it easy to record the results
of simulations by using a configurable checkpointing module.
- **Reproducible simulations:** To help researchers debug simulations,
repeated executions of the same simulation with the same
configuration and same random number generator seed produce the same
results.
- **Space-time visualizations:** DE-Sim generates space-time
visualizations of simulation trajectories. These diagrams can help
researchers understand and debug simulations.
Projects that use *DE-Sim*
--------------------------
*DE-Sim* has been used to develop
`WC-Sim <https://github.com/KarrLab/wc_sim>`__, a multi-algorithmic
simulator for `whole-cell models <https://www.wholecell.org>`__.
Examples
--------
- `Minimal simulation <de_sim/examples/minimal_simulation.py>`__: a
minimal example of a simulation
- `Random walk <de_sim/examples/random_walk.py>`__: a random
one-dimensional walk which increments or decrements a variable with
equal probability at each event
- `Parallel hold (PHOLD) <de_sim/examples/phold.py>`__: model developed
by Richard Fujimoto for benchmarking parallel DES simulators
- `Epidemic <https://github.com/KarrLab/de_sim/blob/master/de_sim/examples/sirs.py>`__:
an SIR model of an epidemic of an infectious disease
Tutorial
--------
Please see
`sandbox.karrlab.org <https://sandbox.karrlab.org/tree/de_sim>`__ for
interactive tutorials on creating and executing models with *DE-Sim*.
Template for models and simulations
-----------------------------------
```de_sim/examples/minimal_simulation.py`` <de_sim/examples/minimal_simulation.py>`__
contains a template for implementing and simulating a model with
*DE-Sim*.
Installation
------------
1. Install dependencies
- Python >= 3.7
- pip >= 19
2. Install this package using one of these methods
- Install the latest release from PyPI ``pip install de_sim``
- Install a Docker image with the latest release from DockerHub
``docker pull karrlab/de_sim``
- Install the latest version from GitHub
``pip install git+https://github.com/KarrLab/de_sim.git#egg=de_sim``
API documentation
-----------------
Please see the `API
documentation <https://docs.karrlab.org/de_sim/source/de_sim.html>`__.
Performance
-----------
Please see the `*DE-Sim* article <joss_paper/paper.md>`__ for
information about the performance of *DE-Sim*.
Strengths and weaknesses compared to other DES tools
----------------------------------------------------
Please see the `*DE-Sim* article <joss_paper/paper.md>`__ for a
comparison of *DE-Sim* with other DES tools.
License
-------
The package is released under the `MIT license <LICENSE>`__.
Citing *DE-Sim*
---------------
Please use the following reference to cite *DE-Sim*:
Arthur P. Goldberg & Jonathan Karr. (2020). `DE-Sim: an object-oriented,
discrete-event simulation tool for data-intensive modeling of complex
systems in Python. Journal of Open Source Software, 5(55),
2685. <https://doi.org/10.21105/joss.02685>`__
Contributing to *DE-Sim*
------------------------
We enthusiastically welcome contributions to *DE-Sim*! Please see the
`guide to contributing <CONTRIBUTING.md>`__ and the `developer's code of
conduct <CODE_OF_CONDUCT.md>`__.
Development team
----------------
This package was developed by the `Karr Lab <https://www.karrlab.org>`__
at the Icahn School of Medicine at Mount Sinai in New York, USA by the
following individuals:
- `Arthur
Goldberg <https://www.mountsinai.org/profiles/arthur-p-goldberg>`__
- `Jonathan Karr <https://www.karrlab.org>`__
Acknowledgements
----------------
This work was supported by National Science Foundation award 1649014,
National Institutes of Health award R35GM119771, and the Icahn Institute
for Data Science and Genomic Technology.
Questions and comments
----------------------
Please submit questions and issues to
`GitHub <https://github.com/KarrLab/de_sim/issues>`__ or contact the
`Karr Lab <mailto:info@karrlab.org>`__.
.. |PyPI package| image:: https://img.shields.io/pypi/v/de_sim.svg
:target: https://pypi.python.org/pypi/de_sim
.. |Documentation| image:: https://readthedocs.org/projects/de-sim/badge/?version=latest
:target: https://docs.karrlab.org/de_sim
.. |Test results| image:: https://circleci.com/gh/KarrLab/de_sim.svg?style=shield
:target: https://circleci.com/gh/KarrLab/de_sim
.. |Test coverage| image:: https://coveralls.io/repos/github/KarrLab/de_sim/badge.svg
:target: https://coveralls.io/github/KarrLab/de_sim
.. |Code analysis| image:: https://api.codeclimate.com/v1/badges/2fa3ece22f571fd36b12/maintainability
:target: https://codeclimate.com/github/KarrLab/de_sim
.. |License| image:: https://img.shields.io/github/license/KarrLab/de_sim.svg
:target: LICENSE
.. |status| image:: https://joss.theoj.org/papers/e3ca43be9717d153672c48239939e993/status.svg
:target: https://joss.theoj.org/papers/e3ca43be9717d153672c48239939e993
.. |Analytics| image:: https://ga-beacon.appspot.com/UA-86759801-1/de_sim/README.md?pixel