Rhodium docs (#184)

* comparison to rhodium added to docs * changelog now is not tracked ind ./docs/source folder (so only one instance of file exists in root)
quaquel · Oct 25, 2022 · 6652129 · 6652129
1 parent 3c18600
commit 6652129
Show file tree

Hide file tree

Showing 7 changed files with 56 additions and 38 deletions.
diff --git a/.gitignore b/.gitignore
@@ -189,3 +189,6 @@ coverage.xml
 
 # Mac crap
 .DS_Store
+
+# changelog
+./docs/source/changelog.md
diff --git a/CHANGELOG.md b/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 processer 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

diff --git a/docs/source/changelog.md b/docs/source/changelog.md
diff --git a/docs/source/installation.rst → docs/source/getting_started/installation.rst b/docs/source/installation.rst → docs/source/getting_started/installation.rst
diff --git a/docs/source/getting_started/other_packages.rst b/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.
diff --git a/docs/source/overview.rst → docs/source/getting_started/overview.rst b/docs/source/overview.rst → docs/source/getting_started/overview.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -31,7 +31,7 @@ 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>`_.
+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.
@@ -43,15 +43,19 @@ 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 details of the API. For a comparison between the workbench and
+`rhodium <https://github.com/Project-Platypus/Rhodium>`_, see
+:doc:`this discusion </getting_started/other_packages>`.
+
 
 .. toctree::
    :maxdepth: 1
    :caption: Getting Started
 
-   ./overview
-   ./installation
-   ./changelog
+   ./getting_started/overview
+   ./getting_started/installation
+   ./getting_started/other_packages
+   ./getting_started/changelog
 
 .. toctree::
    :maxdepth: 1