Add Sphinx-based Documentation

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2021, Politecnico di Torino, MuSyChEn group developers
+Copyright (c) 2023, Politecnico di Torino, MuSyChEn group developers
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -1,67 +1,91 @@
 # Wet Synthesis
-A collection of wrappers around solvers to simulate the wet-synthesis of Ni-Mn-Co Hydroxides 
 
-*Contact*: [Mohsen Shiea](mailto:mohsen.shiea@polito.it), 
+<!---introduction-start-c0e9f6f2-->
+
+A collection of [SimPhoNy](https://github.com/simphony/simphony-osp)
+[wrappers](https://simphony.readthedocs.io/en/v3.9.0/overview.html#fetch-data-from-a-database-run-a-simulation-and-immediately-store-the-results)
+around a CFD-PBE solver to simulate the wet-synthesis of Ni-Mn-Co Hydroxides.
+
+- CFD-PBE Wrapper: This wrapper prepares a simulation case folder based on the
+  user inputs and executes a solver for Computational Fluid Dynamics-Population
+  Balance Equation (CFD-PBE) simulation of NMC hydroxide precipitation. 
+
+- Compartment Wrapper: This wrapper is aimed at simulating the NMC hydroxide 
+  precipitation in a pilot CSTR reactor, by using the compartment model. 
+  Currently, it can be used only to divide the reactor into the compartments.
+
+*Contact*: [Andrea Querio](mailto:andrea.querio@polito.it), 
 [Daniele Marchisio](mailto:daniele.marchisio@polito.it), 
 [Antonio Buffo](mailto:antonio.buffo@polito.it) and 
 [Gianluca Boccardo](mailto:gianluca.boccardo@polito.it) from the 
-Multiphase Systems and Chemical Engineering research group, Politecnico di Torino.
+[Multiphase Systems and Chemical Engineering research group](https://www.disat.polito.it/research/research_groups/musychen), 
+[Politecnico di Torino](https://www.polito.it/).
 
-**Index**
-- [Wet Synthesis](#Wet-Synthesis)
-  - [CFD-PBE Wrapper](#CFD-PBE-Wrapper)
-  - [Compartment Wrapper](#Compartment-Wrapper)
-  - [Compatibility](#Compatibility)
-  - [Requirements](#Requirements)
-  - [Installation](#Installation)
-  - [Docker Container](#Docker-Container)
-  - [Usage](#Usage)
+<!---introduction-end-c0e9f6f2-->
 
-## CFD-PBE Wrapper
-This wrapper prepares a simulation case folder based on the user inputs and executes a solver for Computational Fluid Dynamics-Population Balance Equation (CFD-PBE) simulation of NMC hydroxide precipitation. 
-## Compartment Wrapper
-This wrapper is aimed at simulating the NMC hydroxide precipitation in a pilot CSTR reactor, by using the compartment model. Currently, it can be used only to divide the reactor into the compartments.
+## Installation
 
-## Requirements
-- [OSP core](https://github.com/simphony/osp-core)
-- [OpenFOAM](https://openfoam.org/)
-- [Ansys Fluent](https://www.ansys.com/products/fluids/ansys-fluent)
-- [7-zip](https://www.7-zip.org/)
+<!---installation-start-880c326a-->
 
-## Compatibility
+The wet synthesis wrappers require a working installation of 
+[OpenFOAM 8](https://openfoam.org/version/8/), 
+[SUNDIALS](https://github.com/LLNL/sundials) 
+([v6.1.1](https://github.com/LLNL/sundials/releases/tag/v6.1.1) is known to 
+work),
+[7-zip](https://www.7-zip.org/),
+[Anaconda3](https://www.anaconda.com/)
+([v4.8.2](https://repo.anaconda.com/archive/) is known to work), and the [CFD-PBE solver from the GitHub repository of Politecnico di Torino](https://github.com/mulmopro/wet-synthesis-route). Follow the links to find 
+installation instructions for each tool.
 
-The following table describes the version compatibility between the [OSP core](https://github.com/simphony/osp-core) package and documentation presented in this project.
+Once the requirements have been installed, clone the Wet Synthesis Wrappers 
+repository and install them.
 
-| __Wrapper development__ | __OSP core__ |
-|:-----------------------:|:------------:|
-|          1.0.0          |     3.4.x    |
+```shell
+git clone https://github.com/simphony/simdome_wet_synthesis.git
+pip install ./simdome_wet_synthesis
+```
 
-The releases of OSP core are available [here](https://github.com/simphony/osp-core).
+Then install the required ontology.
 
-## Installation
-### ontology:
-```sh
-pico install ontology.wet_synthesis.yml
+```shell
+pico install simdome_wet_synthesis/ontology.wet_synthesis.yml
 
 # If you have issues using pico directly, you can use
-python -m osp.core.pico install ontology.wet_synthesis.yml
+# python -m osp.core.pico install simdome_wet_synthesis/ontology.wet_synthesis.yml
 ```
-### wrappers:
-```sh
-python3 setup.py install
-apt-get install graphviz
+
+<!---installation-end-880c326a-->
+
+<!---installation-start-f7fde43d-->
+
+### Docker 
+
+Alternatively, it is possible to execute the wrapper in a Docker container.
+Clone the repository and enter the newly created directory
+
+```shell
+git clone https://github.com/simphony/simdome_wet_synthesis.git
+cd simdome_wet_synthesis
 ```
-More information can be found in the documentation for [installation of OSP core](https://simphony.readthedocs.io/en/latest/installation.html)
 
-## Docker Container
-### Image creation:
+and then run
+
 ```sh
-./docker_install.sh
+docker build -t simdome/wet_synthesis .
 ```
-### Launch container:
+
+to create the docker image. After that, run
+
 ```sh
 ./run_container.sh
 ```
 
-## Usage
-Two scripts are provided in the folder "examples" for the usage of the wrappers. It should be noted that the user is responsible for providing the OpenFOAM solver or Ansys Fluent executables. Moreover, the user should place the template case folders and mesh files in the corresponding folders found in the address "osp/wrappers/wet_synthesis_wrappers/cases/precNMC".
+to get access to a shell inside a container based on the image that has just
+been built.
+
+<!---installation-end-f7fde43d-->
+
+## Documentation
+
+Visit [the documentation](https://simdomewetsynthesis.readthedocs.io)
+to learn how to use the wrappers.

docs/conf.py

@@ -0,0 +1,54 @@
+"""Configuration file for the Sphinx documentation builder."""
+
+# --- Project information --- #
+
+project = "Wet Synthesis"
+copyright = (
+    "2023, Multiphase Systems and Chemical Engineering research group,"
+    "Politecnico di Torino"
+)
+author = (
+    "Multiphase Systems and Chemical Engineering research group,"
+    "Politecnico di Torino"
+)
+
+# --- General configuration --- #
+
+extensions = [
+    "myst_parser",  # Markdown support
+    "sphinx.ext.autodoc",  # API reference
+    "sphinx.ext.napoleon",  # Google and NumPy style docstrings support
+    "sphinx.ext.viewcode",  # Link to source in API reference
+    "sphinx_copybutton",  # Copy button for code blocks
+    "nbsphinx",  # Jupyter notebook support
+    "IPython.sphinxext.ipython_console_highlighting",  # Syntax highlighting
+    "sphinx.ext.autosectionlabel",  # Auto-generate section labels.
+    "sphinx_panels",  # Show panels in a grid layout or as drop-downs
+]
+
+master_doc = "index"
+
+myst_heading_anchors = 5
+
+suppress_warnings = ["autosectionlabel.*"]
+exclude_patterns = ["**.ipynb_checkpoints"]
+nbsphinx_allow_errors = False
+
+
+# --- HTML output options --- #
+html_theme = "sphinx_book_theme"
+html_favicon = "static/favicon.png"  # Noto Sans open book emoji
+html_logo = "static/logo.png"
+html_theme_options = {
+    "github_url": "https://github.com/simphony/simdome_wet_synthesis",
+    "repository_url": "https://github.com/simphony/simdome_wet_synthesis",
+    "use_repository_button": True,
+    "repository_branch": "main",
+    "path_to_docs": "docs",
+    "logo_only": True,
+    "show_navbar_depth": 1,
+}
+
+
+html_static_path = ["static"]
+html_css_files = ["custom.css"]

docs/index.md

@@ -0,0 +1,15 @@
+# Wet Synthesis
+
+```{include} ../README.md
+   :start-after: <!---introduction-start-c0e9f6f2-->
+   :end-before: <!---introduction-end-c0e9f6f2-->
+```
+
+```{toctree}
+:hidden: true
+:maxdepth: 2
+
+installation
+usage
+Licence <https://github.com/simphony/simdome_wet_synthesis/blob/master/LICENSE>
+```

docs/installation.md

@@ -0,0 +1,26 @@
+# Installation
+
+```{include} ../README.md
+   :start-after: <!---installation-start-880c326a-->
+   :end-before: <!---installation-end-880c326a-->
+```
+
+```{note}
+OpenFOAM uses a collection of files packed together in a so-called 
+"case folder" as input. The Wet Synthesis Wrappers include templates for those 
+case folders, that are modified before running each simulation according to the
+parameters passed from SimPhoNy in the form of
+[CUDS objects](https://simphony.readthedocs.io/en/v3.9.0/jupyter/cuds_api.html)
+(see the [usage section](./usage.md)).
+
+Such templates are included in the Python package, in the folder
+`osp/wrappers/wet_synthesis_wrappers/cases`. If you wish OpenFOAM to behave
+in a way that is not covered by the parameters that are passed from SimPhoNy,
+then you will have to modify the case folder templates before installing the 
+package.
+```
+
+```{include} ../README.md
+   :start-after: <!---installation-start-f7fde43d-->
+   :end-before: <!---installation-end-f7fde43d-->
+```

docs/requirements.txt

@@ -0,0 +1,10 @@
+jinja2 >= 3.0.3, < 4
+jupyter >= 1.0.0, < 2
+markupsafe >= 2.1.1, < 3
+myst-parser >= 0.18.0, < 0.19
+nbsphinx >= 0.8.9, < 0.9
+sphinx >= 4.4.0, < 5
+sphinx-autobuild==2021.3.14
+sphinx_book_theme >= 0.3.2, < 0.4
+sphinx-copybutton >= 0.5.0, < 0.6
+sphinx-panels >= 0.6.0, < 0.7

docs/static/custom.css

@@ -0,0 +1,25 @@
+.caption-text,
+h1,
+h2,
+h3,
+h4 {
+  color: #6580a1 !important;
+}
+
+.btn-outline-primary {
+  border-color: #6580a1 !important;
+}
+
+.btn-outline-primary:hover {
+  background-color: #6580a1 !important;
+  color: azure !important;
+}
+
+@media (min-width: 1200px) {
+  .container-xl {
+    max-width: 1550px;
+  }
+  #site-navigation {
+    max-width: 20%;
+  }
+}

docs/usage.md

@@ -0,0 +1,95 @@
+# Usage
+
+The SimDOME Wet Synthesis Wrappers can be applied to two use-cases.
+
+- CFD-PBE Wrapper
+- Compartment Wrapper
+
+A brief description of each use case can be found on the 
+[introductory page](index.md).
+
+The simulation inputs must be instantiated as 
+[CUDS objects](https://simphony.readthedocs.io/en/v3.9.0/jupyter/cuds_api.html)
+using the entities from the `wet_synthesis` namespace. The namespace is 
+included in the Wet Synthesis ontology (see 
+[installation](installation.md)). The instantiation can be done directly in the
+corresponding wrapper session, by spawning either a 
+`osp.wrappers.wet_synthesis_wrappers.CfdPbeSession` object for the CFD-PBE 
+Wrapper use-case or a `osp.wrappers.wet_synthesis_wrappers.CompartmentSession`
+for the Compartment Wrapper use-case. To access the `wet_synthesis` namespace 
+and the two session classes, you may import them as follows.
+
+```python
+from osp.core.namespaces import wet_synthesis
+from osp.wrappers.wet_synthesis_wrappers import CfdPbeSession
+from osp.wrappers.wet_synthesis_wrappers import CompartmentSession
+```
+
+A diagram depicting the input and output patterns of CUDS objects that the 
+wrappers expect and produce is shown below.
+
+<figure style="display: table; text-align:center; margin-left: auto; margin-right:auto">
+
+![Wet Synthesis inputs and outputs](./static/graph_pattern.drawio.svg)
+
+<figcaption style="display: table-caption; caption-side: bottom; text-align:center">
+
+_Diagram showing the pattern of input CUDS objects that the Wet Synthesis 
+Wrappers expect to find in the session's knowledge graph and the CUDS objects 
+that are produced as simulation outputs._
+
+</figcaption>
+
+</figure>
+
+Once you have imported the namespace and the session class of your choice, you 
+may instantiate your inputs, run the simulation, and process the results.
+
+```python
+with CfdPbeSession(end_time=None, write_interval=None,
+                   num_moments=4, num_proc=1,
+                   dummy=False) as session:
+    # Initialize the session with a `WetSynthesisWrapper` object.
+    wrapper = wet_synthesis.WetSynthesisWrapper(session=session)
+
+    # Create and link your CUDS objects here.
+    # accuracy_level = ..., pressure = ..., temperature = ...
+    # ...
+    # solid_particle.add(density, molecular_weight, shape_factor,
+    #                    rel=wet_synthesis.hasProperty)
+    # ...
+    # wrapper.add(accuracy_level, pressure, size_distribution, ...)
+    # ...
+
+    # Run the simulation
+    session.run()
+
+    # Process and/or export your simulation results
+    # ...
+```
+
+Both session classes accept several keyword arguments that control the 
+simulation in various ways:
+
+- `delete_simulation_files` _(default: `True`)_: As described in the 
+  [installation section](installation.md), a "case folder" for OpenFOAM is 
+  created from a template before the simulation is run. The folder is 
+  additionally populated with results produced by OpenFOAM during the
+  simulation. Some results are transformed into CUDS objects, but others are
+  not. You can peek into this folder to get this extra information, or 
+  alternatively, set this keyword argument to `True` if you do not need it, so
+  that the folder is automatically deleted when the simulation ends.
+- `end_time`: Amount of simulated time to run OpenFOAM for (e.g. `0.03`). If 
+  set to `None`, an automatic guess will be used instead.
+- `write_interval`: Controls how often data is written to the OpenFOAM output
+  file. If set to `None`, a default of `100` time steps is used.
+- `num_moments`: A value needs to be set, but it will be ignored and replaced
+  by `4`, since at the moment, the wrapper is not capable of adapting the case 
+  template to more/fewer moments.
+- `num_proc`: Number of processors to be used for the calculation (e.g. `3`).
+- `dummy`: When set to `True`, a special dummy set of moments is used so that
+  the simulation ends after a short time, useful for development and debugging 
+  purposes. It should normally be set to `False`.
+
+Two complete examples of use (one for each use case) are provided in the 
+[`examples` folder](https://github.com/simphony/simdome_wet_synthesis/tree/master/examples).