## pySODM
*Simulating and Optimising Dynamical Models in Python 3*
  [](https://hits.dwyl.com/twallema/pySODM)
### Quick installation
```
pip install pySODM
```
### Resources
Documentation: https://twallema.github.io/pySODM
Manuscript: https://www.sciencedirect.com/science/article/pii/S1877750323002089
pyPI: https://pypi.org/project/pySODM/
### Aim & Scope
A modeling and simulation workflow will typically constitute the following steps (see [Villaverde et. al](https://doi.org/10.1093/bib/bbab387)),
1. Build a system dynamical model to describe some real-world phenomenon. Assess structural identifiability.
2. Calibrate the model to a set of experimental data.
3. Extract knowledge from the calibrated parameter values (assess practical identifiability).
4. Use the model to make projections outside the calibrated range.
The aim of pySODM is to reduce the time it takes to step through this workflow. pySODM provides a *template* to construct, simulate and calibrate dynamical systems governed by differential equations. Models can have n-dimensional labeled states of different sizes and can be simulated deterministically and stochastically. Model parameters can be time-dependent by means of complex functions
with arbitrary inputs. The labeled n-dimensional model states can be aligned with n-dimensional
data to compute the posterior probability function, which can subsequently be optimised.
### Overview of features
| Workflow | Features |
|------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| Construct a dynamical model | Implement coupled systems of differential equations |
| | States can be n-dimensional and of different sizes, allowing users to build models with subprocesses |
| | Allows n-dimensional model states to be labelled with coordinates and dimensions by using `xarray.Dataset}` to store simulation output |
| | Easy indexing, manipulating, saving, and piping to third-party software of model output by formatting simulation output as `xarray.Dataset` |
| Simulating the model | Continuous and discrete deterministic simulation or discrete stochastic simulation (Jump processes, Gillespie's Stochastic Simulation Algorithm or Tau-Leaping) |
| | Vary model parameters during the simulation generically using a complex function |
| | Use *draw functions* to perform repeated simulations for sensitivity analysis. With multiprocessing support |
| Calibrate the model | Construct and maximize a posterior probability function |
| | Automatic alignment of data and model forecast over timesteps and coordinates |
| | Nelder-Mead Simplex and Particle Swarm Optimization for point estimation of model parameters |
| | Pipeline to and backend for `emcee.EnsembleSampler` to perform Bayesian inference of model parameters |
### Getting started
The [quistart tutorial](quickstart.md) will teach you the basics of building and simulating models with n-dimensional labeled states in pySODM. It will demonstrate how to vary model parameters over the course of a simulation and how to perform repeated simulations with sampling of model parameters.
The [workflow](worfklow.md) tutorial provides a step-by-step introduction to a modeling and simulation workflow by inferring the distributions of the model parameters of a simple compartmental disease model using a synthetic dataset.
The [enzyme kinetics](enzyme_kinetics.md) and [influenza 17-18](influenza_1718.md) case studies apply the modeling and simulation workflow to more advanced, real-world problems. In the enzyme kinetics case study, a 1D packed-bed reactor model is implemented in pySODM by reducing the two PDEs to a set of coupled ODEs by using the method-of-lines. In the Influenza 17-18 case study, a stochastic, age-structured model for influenza is developped and calibrated to the Influenza incidence data reported by the Belgian Federal Institute of Public Health. These case studies mainly serve to demonstrate pySODM's capabilities across scientific disciplines and highlight the arbitrarily complex nature of the models that can be built with pySODM. For an academic description of pySODM and on the Enzyme Kinetics and Influenza 17-18 case studies, checkout our [manuscript](https://arxiv.org/abs/2301.10664).
### Versions
- Version 0.2.0 (2023-01-19, PR #25)
> Introduction of `dimensions_per_state` in model declaration, allowing the user to define models where states can have different sizes.
- Version 0.2.1 (2023-01-27, PR #30)
> Fixed bugs encountered when incorporating pySODM into the SARS-CoV-2 Dynamic Transmission Models. More thorough checks on `bounds` in the log posterior probability function. Finished manuscript.
- Version 0.2.2 (2023-01-27, PR #31)
> Published to pyPI.
- Version 0.2.3 (2023-05-04, PR #46)
> Fixed minor bugs encountered when using pySODM for a dynamic input-output model of the Belgian economy. Published to pyPI.
- Version 0.2.4 (2023-12-04, PR #62)
> Validated the use of Python 3.11. Efficiency gains in simulation of jump processes. Ommitted dependency on Numba. All changes related to publishing our software manuscript in Journal of Computational Science. Improved nomenclature in model defenition.
- Version 0.1 (2022-12-23, PR #14)
> Application pySODM to three use cases. Documentation website. Unit tests for ODE, JumpProcess and calibration.
- Version 0.1.1 (2023-01-09, PR #20)
> Start of semantic versions: Major.Minor.Patch
- Version 0.1.2 (2023-01-11, PR #23)
> Calibration of 1-D model parameters generalized to n-dimensions.
> Added 'aggregation functions' to the `log_posterior_probability` class to perform custom aggregations of model output before matching with data.
> `xarray.DataArray`/`xarray.Dataset` can be used as datasets during calibration. Internally converted to `pd.DataFrame`.
- Version 0.0 (2022-11-14)
- First pySODM version. Obtained by splitting the generally applicable parts from the ad-hoc parts in UGentBiomath/COVID19-Model. Without documentation website.
- Pre-development (2020-05-01 - 2022-11-24)
- Code developped to model the spread of SARS-CoV-2 in Belgium (UGentBiomath/COVID19-Model).
Raw data
{
"_id": null,
"home_page": "https://github.com/twallema/pySODM",
"name": "pySODM",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "ODE PDE simulation calibration gillespie xarray emcee",
"author": "Tijs Alleman, KERMIT, Ghent University",
"author_email": "tijs.alleman@ugent.be",
"download_url": "",
"platform": null,
"description": "## pySODM\n*Simulating and Optimising Dynamical Models in Python 3*\n\n  [](https://hits.dwyl.com/twallema/pySODM)\n\n### Quick installation \n```\npip install pySODM\n```\n### Resources\n\nDocumentation: https://twallema.github.io/pySODM\n\nManuscript: https://www.sciencedirect.com/science/article/pii/S1877750323002089\n\npyPI: https://pypi.org/project/pySODM/ \n\n### Aim & Scope\n\nA modeling and simulation workflow will typically constitute the following steps (see [Villaverde et. al](https://doi.org/10.1093/bib/bbab387)),\n1. Build a system dynamical model to describe some real-world phenomenon. Assess structural identifiability.\n2. Calibrate the model to a set of experimental data.\n3. Extract knowledge from the calibrated parameter values (assess practical identifiability).\n4. Use the model to make projections outside the calibrated range.\n\nThe aim of pySODM is to reduce the time it takes to step through this workflow. pySODM provides a *template* to construct, simulate and calibrate dynamical systems governed by differential equations. Models can have n-dimensional labeled states of different sizes and can be simulated deterministically and stochastically. Model parameters can be time-dependent by means of complex functions\nwith arbitrary inputs. The labeled n-dimensional model states can be aligned with n-dimensional\ndata to compute the posterior probability function, which can subsequently be optimised.\n\n### Overview of features\n\n| Workflow | Features |\n|------------------------------|---------------------------------------------------------------------------------------------------------------------------------|\n| Construct a dynamical model | Implement coupled systems of differential equations |\n| | States can be n-dimensional and of different sizes, allowing users to build models with subprocesses |\n| | Allows n-dimensional model states to be labelled with coordinates and dimensions by using `xarray.Dataset}` to store simulation output |\n| | Easy indexing, manipulating, saving, and piping to third-party software of model output by formatting simulation output as `xarray.Dataset` |\n| Simulating the model | Continuous and discrete deterministic simulation or discrete stochastic simulation (Jump processes, Gillespie's Stochastic Simulation Algorithm or Tau-Leaping) |\n| | Vary model parameters during the simulation generically using a complex function |\n| | Use *draw functions* to perform repeated simulations for sensitivity analysis. With multiprocessing support |\n| Calibrate the model | Construct and maximize a posterior probability function |\n| | Automatic alignment of data and model forecast over timesteps and coordinates |\n| | Nelder-Mead Simplex and Particle Swarm Optimization for point estimation of model parameters |\n| | Pipeline to and backend for `emcee.EnsembleSampler` to perform Bayesian inference of model parameters |\n\n### Getting started\n\nThe [quistart tutorial](quickstart.md) will teach you the basics of building and simulating models with n-dimensional labeled states in pySODM. It will demonstrate how to vary model parameters over the course of a simulation and how to perform repeated simulations with sampling of model parameters.\n\nThe [workflow](worfklow.md) tutorial provides a step-by-step introduction to a modeling and simulation workflow by inferring the distributions of the model parameters of a simple compartmental disease model using a synthetic dataset. \n\nThe [enzyme kinetics](enzyme_kinetics.md) and [influenza 17-18](influenza_1718.md) case studies apply the modeling and simulation workflow to more advanced, real-world problems. In the enzyme kinetics case study, a 1D packed-bed reactor model is implemented in pySODM by reducing the two PDEs to a set of coupled ODEs by using the method-of-lines. In the Influenza 17-18 case study, a stochastic, age-structured model for influenza is developped and calibrated to the Influenza incidence data reported by the Belgian Federal Institute of Public Health. These case studies mainly serve to demonstrate pySODM's capabilities across scientific disciplines and highlight the arbitrarily complex nature of the models that can be built with pySODM. For an academic description of pySODM and on the Enzyme Kinetics and Influenza 17-18 case studies, checkout our [manuscript](https://arxiv.org/abs/2301.10664).\n\n### Versions\n\n- Version 0.2.0 (2023-01-19, PR #25)\n > Introduction of `dimensions_per_state` in model declaration, allowing the user to define models where states can have different sizes.\n - Version 0.2.1 (2023-01-27, PR #30)\n > Fixed bugs encountered when incorporating pySODM into the SARS-CoV-2 Dynamic Transmission Models. More thorough checks on `bounds` in the log posterior probability function. Finished manuscript.\n - Version 0.2.2 (2023-01-27, PR #31)\n > Published to pyPI.\n - Version 0.2.3 (2023-05-04, PR #46)\n > Fixed minor bugs encountered when using pySODM for a dynamic input-output model of the Belgian economy. Published to pyPI.\n - Version 0.2.4 (2023-12-04, PR #62)\n > Validated the use of Python 3.11. Efficiency gains in simulation of jump processes. Ommitted dependency on Numba. All changes related to publishing our software manuscript in Journal of Computational Science. Improved nomenclature in model defenition.\n- Version 0.1 (2022-12-23, PR #14)\n > Application pySODM to three use cases. Documentation website. Unit tests for ODE, JumpProcess and calibration. \n - Version 0.1.1 (2023-01-09, PR #20)\n > Start of semantic versions: Major.Minor.Patch\n - Version 0.1.2 (2023-01-11, PR #23)\n > Calibration of 1-D model parameters generalized to n-dimensions.\n > Added 'aggregation functions' to the `log_posterior_probability` class to perform custom aggregations of model output before matching with data.\n > `xarray.DataArray`/`xarray.Dataset` can be used as datasets during calibration. Internally converted to `pd.DataFrame`.\n- Version 0.0 (2022-11-14)\n - First pySODM version. Obtained by splitting the generally applicable parts from the ad-hoc parts in UGentBiomath/COVID19-Model. Without documentation website. \n- Pre-development (2020-05-01 - 2022-11-24)\n - Code developped to model the spread of SARS-CoV-2 in Belgium (UGentBiomath/COVID19-Model).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simulating and Optimising Dynamical Models",
"version": "0.2.4",
"project_urls": {
"Homepage": "https://github.com/twallema/pySODM"
},
"split_keywords": [
"ode",
"pde",
"simulation",
"calibration",
"gillespie",
"xarray",
"emcee"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5fc252effda2411ed5f80b96e4134fdcb494b67cfa39a697a6f17b6adcdee6eb",
"md5": "b8f9d44df77b5eb9192208c1bd0e182e",
"sha256": "146a1c33d96d8d5a7c52f1313d99e12d8ea5a0d4f65a50911a77f83ed571aa65"
},
"downloads": -1,
"filename": "pySODM-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8f9d44df77b5eb9192208c1bd0e182e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 46105,
"upload_time": "2023-12-04T15:46:32",
"upload_time_iso_8601": "2023-12-04T15:46:32.791640Z",
"url": "https://files.pythonhosted.org/packages/5f/c2/52effda2411ed5f80b96e4134fdcb494b67cfa39a697a6f17b6adcdee6eb/pySODM-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-04 15:46:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "twallema",
"github_project": "pySODM",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pysodm"
}
JSON
