de-sim 1.0.5
object-oriented, discrete-event simulation tool for data-intensive modeling of complex systems
License: MIT
Keywords: computational modeling,data-driven modeling,discrete-event simulation,DES,object-oriented programming,Python

|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