Add Sphinx-based Documentation

Dockerfile

@@ -1,12 +1,16 @@
-ARG OSP_CORE_IMAGE=simphony/osp-core:latest
-FROM $OSP_CORE_IMAGE
+FROM ubuntu:20.04
 LABEL maintainer="mohsen.shiea@polito.it"
 LABEL dockerfile.version="1.1"
 
+ENV DEBIAN_FRONTEND=noninteractive
+
 # Install requirements
 RUN apt-get update && apt-get -y upgrade && apt-get install -y \
-    git graphviz wget build-essential g++ gfortran libgfortran5 openmpi-bin libopenmpi-dev make libssl-dev libblas-dev liblapack-dev \
-    apt-transport-https software-properties-common openssh-client bash-completion bash-builtins libnss-wrapper vim nano tree curl unzip
+    git graphviz wget build-essential g++ gfortran libgfortran5 openmpi-bin \
+    libopenmpi-dev make libssl-dev libblas-dev liblapack-dev \
+    apt-transport-https software-properties-common openssh-client \
+    bash-completion bash-builtins libnss-wrapper vim nano tree curl unzip \
+    python3-pip
 
 RUN cd / && mkdir cmake && cd cmake && \
     CMAKE_VERSION=3.20.1 && \
@@ -29,10 +33,9 @@ RUN cd / && mkdir sundials && cd sundials && \
     make install && \
     cd .. && rm -r builddir cvode-${CVODE_VERSION} cvode-${CVODE_VERSION}.tar.gz
 
-RUN cd /usr/bin && rm python3 && ln -s python3.6 python3 && \
-    wget -O - http://dl.openfoam.org/gpg.key | apt-key add - && add-apt-repository http://dl.openfoam.org/ubuntu && \
+RUN wget -O - http://dl.openfoam.org/gpg.key | apt-key add - && add-apt-repository http://dl.openfoam.org/ubuntu && \
     apt-get update && apt-get install -y --no-install-recommends openfoam8 && \
-    cd /usr/bin && rm python3 && ln -s python3.7 python3 && rm -rf /var/lib/apt/lists/*
+    rm -rf /var/lib/apt/lists/*
 
 ENV user=simdomeuser HOME=/home/simdomeuser
 
@@ -52,10 +55,10 @@ RUN mkdir -p $HOME/simdome/wrappers/simdome_wet_synthesis && \
 COPY --chown=$user . $HOME/simdome/wrappers/simdome_wet_synthesis
 WORKDIR $HOME/simdome/wrappers/simdome_wet_synthesis
 
-ENV PATH=$PATH:$HOME/.local/bin
+ENV PATH=$HOME/.local/bin:$PATH
 
-RUN pip install matplotlib scipy \
-    && pico install ontology.wet_synthesis.yml \
-    && python setup.py install --user
+RUN pip install matplotlib scipy
+RUN pip install .
+RUN pico install ontology.wet_synthesis.yml
 
 CMD ["/bin/bash", "-c", "source /opt/openfoam8/etc/bashrc && /bin/bash" ]

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,88 @@
 # 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) and [7-zip](https://www.7-zip.org/). 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%;
+  }
+}