Merge branch 'master' into spelling-fix

.gitignore

@@ -189,3 +189,6 @@ coverage.xml
 
 # Mac crap
 .DS_Store
+
+# changelog
+./docs/source/changelog.md

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ repos:
     hooks:
       - id: black-jupyter
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.0.0
+    rev: v3.1.0
     hooks:
     -   id: pyupgrade
         args: [--py38-plus]

CHANGELOG.md

@@ -6,33 +6,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- Release notes generated using configuration in .github/release.yml at master -->
 
-# 2.2.0
-## Highlights
+## 2.2.0
+### Highlights
 With the 2.2 release, the EMAworkbench can now connect to [Vadere](https://www.vadere.org/) models on pedestrian dynamics. When inspecting a Prim Box peeling trajectory, multiple points on the peeling trajectory can be inspected simultaneously by inputting a list of integers into [`PrimBox.inspect()`](https://emaworkbench.readthedocs.io/en/latest/ema_documentation/analysis/prim.html#ema_workbench.analysis.prim.PrimBox.inspect).
 
 When running experiments with multiprocessing using the [`MultiprocessingEvaluator`](https://emaworkbench.readthedocs.io/en/latest/ema_documentation/em_framework/evaluators.html#ema_workbench.em_framework.evaluators.MultiprocessingEvaluator), the number of processes can now be controlled using a negative integer as input for `n_processes` (for example, `-2` on a 12-thread CPU results in 10 threads used). Also, it will now default to max. 61 processes on windows machines due to limitations inherent in Windows in dealing with higher processor counts.  Code quality, CI, and error reporting also have been improved. And finally, generating these release notes is now automated.
 
-## What's Changed
-### 🎉 New features added
+### What's Changed
+#### 🎉 New features added
 * Vadere model connector by @floristevito in https://github.com/quaquel/EMAworkbench/pull/145
 
-### 🛠 Enhancements made
+#### 🛠 Enhancements made
 * Improve code quality with static analysis by @EwoutH in https://github.com/quaquel/EMAworkbench/pull/119
 * prim.py: Make `PrimBox.peeling_trajectory["id"]` int instead of float by @EwoutH in https://github.com/quaquel/EMAworkbench/pull/121
 * analysis: Allow optional annotation of plot_tradeoff graphs by @EwoutH in https://github.com/quaquel/EMAworkbench/pull/123
 * evaluators.py: Allow MultiprocessingEvaluator to initialize with cpu_count minus N processes by @EwoutH in https://github.com/quaquel/EMAworkbench/pull/140
 * `PrimBox.inspect()` now can also take a list of integers (aside from a single int) to inspect multiple points at once by @quaquel in https://github.com/quaquel/EMAworkbench/commit/6d83a6c33442ad4dce0974a384b03a225aaf830d (see also issue https://github.com/quaquel/EMAworkbench/issues/124)
 
-### 🐛 Bugs fixed
+#### 🐛 Bugs fixed
 * fixed typo in lake_model.py by @JeffreyDillonLyons in https://github.com/quaquel/EMAworkbench/pull/136
 
-### 📜 Documentation improvements
+#### 📜 Documentation improvements
 * Docs: Installation.rst: Add how to install master or custom branch by @EwoutH in https://github.com/quaquel/EMAworkbench/pull/122
 * Docs: Replace all http links with secure https URLs by @EwoutH in https://github.com/quaquel/EMAworkbench/pull/134
 * Maintain release notes at CHANGELOG.md and include them in Readthedocs by @quaquel in https://github.com/quaquel/EMAworkbench/commit/ebdbc9f5c77693fc75911ead472b420065dfe2aa
 * Fix badge links in readme by @quaquel in https://github.com/quaquel/EMAworkbench/commit/28569bdcb149c070c329589969179be354b879ec
 
-### 🔧 Maintenance
+#### 🔧 Maintenance
 * feature_scoring: fix Regressor criterion depreciation by @EwoutH in https://github.com/quaquel/EMAworkbench/pull/125
 * feature_scoring.py: Change `max_features` in get_rf_feature_scores to `"sqrt"` by @EwoutH in https://github.com/quaquel/EMAworkbench/pull/129
 * CI: Use Pytest instead of Nose, update default build to Python 3.10 by @EwoutH in https://github.com/quaquel/EMAworkbench/pull/131
@@ -52,7 +52,7 @@ When running experiments with multiprocessing using the [`MultiprocessingEvaluat
 
 
 
-## New Contributors
+### New Contributors
 * @JeffreyDillonLyons made their first contribution in https://github.com/quaquel/EMAworkbench/pull/136
 * @rhysits made their first contribution in https://github.com/quaquel/EMAworkbench/pull/144
 * @floristevito made their first contribution in https://github.com/quaquel/EMAworkbench/pull/145

CONTRIBUTING.md

@@ -27,6 +27,20 @@ For a simple single-file code or docs change, you can also just edit any file in
 ## Maintainers
 _This section is targeted at the maintainers_
 
+### Merging Pull Requests
+Pull requests should be merged in a way that only [atomic commits](https://en.wikipedia.org/wiki/Atomic_commit) make it in the main branch. This keeps the git commit history clean and tidy, and therefore useful. This means every commit only pertains one fix or feature, and can't be breaked into multiple commits without breaking things. It also means no merge commits are allowed. For more about atomic commits, see [one](https://www.pauline-vos.nl/atomic-commits/) and [two](https://www.aleksandrhovhannisyan.com/blog/atomic-git-commits/).
+
+There are two ways to do this:
+ - For (reducing to) a _single_ commit: Use the _Squash and merge_ button in the GitHub UI. Make sure the commit message and description are properly formatted and contain all the improtant information from the PR when squashing.
+ - For (keeping) _multiple_ commits: Merge from the command line. First make sure all commits are atomic and contain proper commit messages. Us git amend, reset and rebase if nessesary. Then do a [fast-forward](https://blog.mergify.com/what-is-a-git-merge-fast-forward/) merge, using:
+   ```
+   git fetch origin
+   git checkout master
+   git merge --ff-only -S origin/BRANCH-TO-MERGE
+   git push origin
+   ```
+   In which `BRANCH-TO-MERGE` the branch is of the PR you want to merge, and `-S` makes sure you sign the commits.
+
 ### Releases
 The release process has been updated starting at the 2.2.0 release. To create a new release, follow the following steps:
  1. Make sure all PRs have a clear title and are labeled with at least one label. These will be used when drafting the changelog using the [.github/release.yml](https://github.com/quaquel/EMAworkbench/blob/master/.github/release.yml) configuration.

README.md

@@ -1,36 +1,43 @@
-## Exploratory Modeling workbench
-This is a stable version of the EMA workbench currently under
-development at Delft University of Technology.
-
 [![Build Status](https://github.com/quaquel/EMAworkbench/actions/workflows/ci.yml/badge.svg?master)](https://github.com/quaquel/EMAworkbench/actions)
 [![Coverage Status](https://coveralls.io/repos/github/quaquel/EMAworkbench/badge.svg?branch=master)](https://coveralls.io/github/quaquel/EMAworkbench?branch=master)
 [![Documentation Status](https://readthedocs.org/projects/emaworkbench/badge/?version=latest)](http://emaworkbench.readthedocs.org/en/latest/?badge=master)
 [![PyPi](https://img.shields.io/pypi/v/ema_workbench.svg)](https://pypi.python.org/pypi/ema_workbench)
 [![PyPi](https://img.shields.io/pypi/dm/ema_workbench.svg)](https://pypi.python.org/pypi/ema_workbench)
 
-If you are interested in using the most recent version of the workbench  and
-would like to contribute to its further development, contact Jan Kwakkel at
-Delft University of Technology.
+# Exploratory Modeling workbench
+
+Exploratory Modeling and Analysis (EMA) is a research methodology that uses computational experiments to analyze complex and uncertain systems ([Bankes, 1993](http://www.jstor.org/stable/10.2307/171847)). That is, exploratory modeling aims at offering computational decision support for decision making under [deep uncertainty](http://inderscience.metapress.com/content/y77p3q512x475523/) and [robust decision making](http://en.wikipedia.org/wiki/Robust_decision_making).
+
+The EMA workbench aims at providing support for performing exploratory modeling with models developed in various modelling packages and environments. Currently, the workbench offers connectors to [Vensim](https://vensim.com/), [Netlogo](https://ccl.northwestern.edu/netlogo/), [Simio](https://www.simio.com/), [Vadere](https://www.vadere.org/) and Excel.
+
+The EMA workbench offers support for designing experiments, performing the experiments - including support for parallel processing on both a single machine as well as on clusters-, and analysing the results. To get started, take a look at the high level overview, the tutorial, or dive straight into the details of the API.
+
+The EMA workbench currently under development at Delft University of Technology. If you would like to collaborate, open an issue/discussion or contact [Jan Kwakkel](https://www.tudelft.nl/en/tpm/our-faculty/departments/multi-actor-systems/people/professors/prof-drir-jh-jan-kwakkel).
+
+## Documentation
 
-The workbench is available from pip. Version 1.x is compatible with both
-python 2 and 3, while the 2.x branch requires python 3.8 or newer.
+Documentation for the workbench is availabe at [Read the Docs](https://emaworkbench.readthedocs.io/en/latest/index.html), including an introduction on Exploratory Modeling, tutorials and documentation on all the modules and functions.
 
+There are also a lot of example models available at [ema_workbench/examples](ema_workbench/examples), both for pure Python models and some using the different connectors. A release notes for each new version are available at [CHANGELOG.md](CHANGELOG.md).
 
-# Releasing
+## Installation
 
-Releases are published automatically when a tag is pushed to GitHub.
+The workbench is available from [PyPI](https://pypi.org/project/ema-workbench/), and currently requires Python 3.8 or newer. It can be installed with:
+```
+pip install -U ema_workbench
+```
+To also install some recommended packages for plotting, testing and Jupyter support, use the `recommended` extra:
+```
+pip install -U ema_workbench[recommended]
+```
+There are way more options installing the workbench, including installing connector packages, edible installs for development, installs of custom forks and branches and more. See [Installing the workbench](https://emaworkbench.readthedocs.io/en/latest/installation.html) in the docs for all options.
 
-```bash
+## Contributing
 
-   # Set next version number
-   export RELEASE=x.x.x
+We greatly appreciate contributions to the EMA workbench! Reporting [Issues](https://github.com/quaquel/EMAworkbench/issues) such as bugs or unclairties in the documentation, opening a [Pull requests](https://github.com/quaquel/EMAworkbench/pulls) with code or documentation improvements or opening a [Discussion](https://github.com/quaquel/EMAworkbench/discussions) with a question, suggestions or comment helps us a lot.
 
-   # Create tags
-   git commit --allow-empty -m "Release $RELEASE"
-   git tag -a $RELEASE -m "Version $RELEASE"
+Please check [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
 
-   # Push
-   git push upstream --tags # for a fork
+## License
 
-   # use git push origin --tags if on origin
-```
+This repository is licensed under BSD 3-Clause License. See [LICENSE.md](LICENSE.md).

docs/source/getting_started/other_packages.rst

@@ -0,0 +1,35 @@
+
+********************
+Alternative packages
+********************
+So how does the workbench differ from other open source tools available for
+exploratory modeling? In Python there is `rhodium <https://github.com/Project-Platypus/Rhodium>`_,
+in R there is the `open MORDM <https://github.com/OpenMORDM/OpenMORDM>`_ toolkit, and there is also
+`OpenMole <https://openmole.org>`_. Below we discuss the key differences with rhodium. Given a lack of
+familiarity with the other tools, we wont comment on those.
+
+.. _workbench_vs_rhodium:
+
+The workbench versus rhodium
+============================
+For Python, the main alternative tool is `rhodium <https://github.com/Project-Platypus/Rhodium>`_,
+which is part of `Project Platypus <https://github.com/Project-Platypus>`_. Project Platypus is a collection of
+libraries for doing many objective optimization (`platypus-opt <https://platypus.readthedocs.io/en/latest/>`_), setting
+up and performing simulation experiments (`rhodium <https://github.com/Project-Platypus/Rhodium>`_), and
+scenario discovery using the Patient Rule Induction Method (`prim <https://github.com/Project-Platypus/PRIM>`_). The
+relationship between the workbench and the tools that form project platypus is a
+bit messy. For example, the workbench too relies on `platypus-opt <https://platypus.readthedocs.io/en/latest/>`_ for many
+objective optimization, the `PRIM <https://github.com/Project-Platypus/PRIM>`_ package is a, by now very dated, fork of the
+prim code in the workbench, and both `rhodium <https://github.com/Project-Platypus/Rhodium>`_ and the workbench rely on
+`SALib <https://salib.readthedocs.io>`_ for global sensitivity analysis. Moreover, the API
+of `rhodium <https://github.com/Project-Platypus/Rhodium>`_ was partly inspired by an older version of the
+workbench, while new ideas from the rhodium API have in turned resulting in profound changes in the API of the
+workbench.
+
+Currently, the workbench is still actively being developed. It is also not just used
+in teaching but also for research, and in practice by various organization globally.
+Moreover, the workbench is quite a bit more developed when it comes to providing off
+the shelf connectors for some popular modeling and simulation tools. Basically,
+everything that can be done with project Platypus can be done with the workbench
+and then the workbench offers additional functionality, a more up to date code
+base, and active support.