Metadata-Version: 2.1
Name: asdm
Version: 0.0.3
Summary: Agile System Dynamics Engine
Author-email: Wang Zhao <wang.zhao@strath.ac.uk>, Matt Stammers <matt@reallyusefulmodels.com>
License: MIT License
        
        Copyright (c) 2022 W.Zh
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/wzh1895/ASDM.git
Requires-Python: >=3.9.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib (>=3.5.1)
Requires-Dist: networkx (>=2.6.3)
Requires-Dist: numpy (>=1.21.5)
Requires-Dist: pandas (>=1.3.5)
Requires-Dist: pymc3 (>=3.11.4)
Requires-Dist: scipy (>=1.7.1)
Requires-Dist: theano-pymc (>=1.1.2)
Requires-Dist: lxml (>=4.9.1)
Requires-Dist: beautifulsoup4 (>=4.11.1)
Requires-Dist: tqdm (>=4.64.0)
Requires-Dist: ipywidgets (>=7.6.5)
Requires-Dist: openpyxl (>=3.0.10)
Requires-Dist: ipykernel (>=6.22.0)
Requires-Dist: streamlit (>=1.20.0)
Provides-Extra: dev
Requires-Dist: mkdocs-material ; extra == 'dev'
Requires-Dist: mkdocs ; extra == 'dev'
Requires-Dist: mkdocstrings-python ; extra == 'dev'
Requires-Dist: mkdocstrings ; extra == 'dev'
Requires-Dist: nbstripout ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: requests-cache ; extra == 'dev'
Requires-Dist: pyyaml ; extra == 'dev'
Provides-Extra: eda
Requires-Dist: black ; extra == 'eda'
Requires-Dist: bokeh ; extra == 'eda'
Requires-Dist: holoviews ; extra == 'eda'
Requires-Dist: isort ; extra == 'eda'
Requires-Dist: jupyterlab-code-formatter ; extra == 'eda'
Requires-Dist: jupyterlab ; extra == 'eda'
Requires-Dist: seaborn ; extra == 'eda'

# ASDM

## **Agile System Dynamics Modelling**

This project is a Python-based tool that could be used for building, simulating, calibrating, and carrying out analyses of System Dynamics (SD) models.

## How to use

### Python version

The library is tested under Python 3.9.0 on Ubuntu Linux and Windows. It is supposed to work also on higher versions of Python. If you encounter problems using it please open an issue.

### OS

It has been noticed that on macOS, the multi-thread sampling of PyMC3 does not work well. This is due to the fact that macOS handles multiprocess in a different way. The impact is that we can only use one thread to do multi-chain MCMC sampling which is much slower.

Although the rest of the functionalities of ASDM still work on macOS, we recommend that you switch to Linux for the optimal parameter estimation experience.

### Dependencies

We recommend that you use pip to install asdm but if you do wish to develop it further pipenv instructions are provided. 

## Tutorial Notebooks

We use a series of Jupyter Notebooks to provide functionality guidance for the users.

1. [SD Modelling](https://github.com/wzh1895/ASDM/blob/main/Demo_SD_modelling.ipynb)

- Creating an SD model from scratch
  - Adding stocks, flows, auxiliaries
  - Support for nonlinear functions (MIN, MAX, etc.)
  - Support for stochastic functions (random binomial trial, etc.)
- Running simulations
- Exporting and examing simulation outcomes
- Displaying simulation outcomes as graph

## Why ASDM?

Acknowledging that there are a number of SD tools that enable simulating SD models in a Python environment (see [PySD](https://github.com/JamesPHoughton/pysd) and [venpy](https://github.com/pbreach/venpy.git)), we build ASDM to bring the capability of **structure modelling** to the Python SD community. ASDM allows users to create an SD model from scratch and edit model structure as needed. With a native Python implementation of stock-and-flow structure, ASDM allows building SD models without software like [Vensim](https://vensim.com/) and [Stella](https://www.iseesystems.com/store/products/stella-architect.aspx).

The long-term goal ASDM intends to achieve is an approach for **data-informed structure modelling** where data can be used to finetune SD model structure automatically. This is both an extension of data-informed SD model parameter estimation, and an innovative way to discover feedback structures from data.

## Limitations

The main drawback at the moment is that we have not been working a lot on **translating Vensim/Stella models** into the format that ASDM uses, although [PySD](https://github.com/JamesPHoughton/pysd) has proved this fully doable. This functionality is in our development roadmap.

We have neither been working a lot on **the speed of simulation**. Although simulating large SD models given mordern computer specs would not be extremely time-consuming, in tasks involing Monte Carlo simulation (such as parameter estimation) the speed of running a model can matter a lot more. Acceleration is in our development roadmap too.

## Docs

Full docs are incoming

## Licence

ASDM is made public under the MIT licence.

## Authors
**Wang Zhao**  
PhD candidate at University of Strathclyde, UK   
<wang.zhao@strath.ac.uk>  

**Matt Stammers**  
MD candidate at University of Southampton, UK   
<m.stammers@soton.ac.uk>  
