Overhaul docs and convert to Sphinx

Replaces the TeX-based documentation with an rst-based one using Sphinx.
The documentation is completely reworked. GitHub Actions are used to
automatically build the docs and publish them on cadet.github.io.

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/README.md

@@ -0,0 +1,13 @@
+## CADET Documentation
+
+
+To build the documentation locally, install sphinx and other dependencies by running
+
+```
+pip install -r requirements.txt
+```
+
+Then, run `sphinx-multiversion ./ ./build/`. 
+
+This documentation is published under https://cadet.github.io
+Any changes to the documentation will automatically be pushed to the github-pages repository (https://github.com/cadet/cadet.github.io) using github actions.

doc/_static/css/custom.css

@@ -0,0 +1,11 @@
+/** css/custom.css **/
+
+/* This line is theme specific - it includes the base theme CSS */
+@import '../alabaster.css';  /* for Alabaster */
+/*@import 'theme.css';       /* for the Read the Docs theme */
+
+div.sphinxsidebar {
+	height: 100vh;
+	overflow: auto;
+}
+

doc/_templates/page.html

@@ -0,0 +1,17 @@
+{% extends "!page.html" %}
+{% block body %}
+{% if current_version and latest_version and current_version != latest_version %}
+<p>
+  <strong>
+    {% if current_version.is_released %}
+    You're reading an old version of this documentation.
+    If you want up-to-date information, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
+    {% else %}
+    You're reading the documentation for a development version.
+    For the latest released version, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
+    {% endif %}
+  </strong>
+</p>
+{% endif %}
+{{ super() }}
+{% endblock %}%

doc/_templates/versioning.html

@@ -0,0 +1,8 @@
+{% if versions %}
+<h3>{{ _('Versions') }}</h3>
+<ul>
+      {%- for item in versions %}
+        <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+          {%- endfor %}
+</ul>
+{% endif %}

doc/conf.py

@@ -0,0 +1,89 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+from datetime import date
+
+# -- Project information -----------------------------------------------------
+project = 'CADET'
+copyright = f'2008-{date.today().year}'
+author = 'CADET Authors'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.todo',
+    'sphinx.ext.githubpages',
+    'sphinx_sitemap',
+    'sphinxcontrib.bibtex',
+    'sphinx_multiversion',
+]
+
+# Bibliography
+bibtex_bibfiles = ['literature.bib']
+
+# Multiversion
+smv_released_pattern = r'^tags/.*$'         # Tags only
+smv_tag_whitelist = r'^v\d+\.\d+\.\d+$'     # Include tags like "v2.1.1"
+smv_branch_whitelist = r"^master$"          # Only use master branch
+smv_remote_whitelist = r"^origin$"          # Use branches from remote origin
+smv_outputdir_format = '{ref.name}'         # Use the branch/tag name
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# Support for labelling and referencing equations
+numfig = True
+math_numfig = True
+numfig_secnum_depth = 2
+math_eqref_format = '{number}'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+html_theme_options = {
+    # 'logo': 'cadet_logo.png',
+    # 'description': 'Chromatography Analysis and Design Toolkit',
+    'sidebar_collapse': True,
+    'fixed_sidebar': True,
+    'show_powered_by': False,
+}
+
+html_favicon = '_static/cadet_icon.png'
+html_title = 'CADET'
+html_baseurl = 'https://cadet.github.io/'
+html_static_path = ['_static']
+html_extra_path = ['robots.txt', 'google7a5fbf15028eb634.html']
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        'searchbox.html',
+        'versioning.html'
+    ]
+}
+
+html_style = 'css/custom.css'
+

doc/examples/batch_chromatography.rst

@@ -0,0 +1,3 @@
+Batch chromatography
+====================
+

doc/examples/breakthrough.py

@@ -0,0 +1,141 @@
+# Import libraries
+import numpy as np
+import matplotlib.pyplot as plt
+
+from cadet import Cadet
+Cadet.cadet_path = '/path/to/cadet-cli'
+
+# Create model object
+model = Cadet()
+
+# Number of unit operations
+model.root.input.model.nunits = 3
+
+# Inlet
+model.root.input.model.unit_000.unit_type = 'INLET'
+model.root.input.model.unit_000.ncomp = 1
+model.root.input.model.unit_000.inlet_type = 'PIECEWISE_CUBIC_POLY'
+
+# General Rate Model
+model.root.input.model.unit_001.unit_type = 'GENERAL_RATE_MODEL'
+model.root.input.model.unit_001.ncomp = 1
+
+## Geometry
+model.root.input.model.unit_001.col_length = 0.1                # m
+model.root.input.model.unit_001.cross_section_area = 0.01       # m
+model.root.input.model.unit_001.col_porosity = 0.37             # -
+model.root.input.model.unit_001.par_porosity = 0.33             # -
+model.root.input.model.unit_001.par_radius = 1e-6               # m
+
+## Transport
+model.root.input.model.unit_001.col_dispersion = 1e-8           # m^2 / s (interstitial volume)
+model.root.input.model.unit_001.film_diffusion = [1e-5]         # m / s
+model.root.input.model.unit_001.par_diffusion = [1e-10,]        # m^2 / s (mobile phase)  
+model.root.input.model.unit_001.par_surfdiffusion = [0.0,]      # m^2 / s (solid phase)
+
+## Adsorption
+model.root.input.model.unit_001.adsorption_model = 'MULTI_COMPONENT_LANGMUIR'
+model.root.input.model.unit_001.adsorption.is_kinetic = True    # Kinetic binding
+model.root.input.model.unit_001.adsorption.mcl_ka = [1.0,]      # m^3 / (mol * s)   (mobile phase)
+model.root.input.model.unit_001.adsorption.mcl_kd = [1.0,]      # 1 / s (desorption)
+model.root.input.model.unit_001.adsorption.mcl_qmax = [100.0,]  # mol / m^3   (solid phase)
+
+## Initial conditions
+model.root.input.model.unit_001.init_c = [0.0,]
+model.root.input.model.unit_001.init_q = [0.0,]
+
+## Discretization
+### Grid cells
+model.root.input.model.unit_001.discretization.ncol = 20
+model.root.input.model.unit_001.discretization.npar = 5
+
+### Bound states
+model.root.input.model.unit_001.discretization.nbound = [1]
+
+### Other options
+model.root.input.model.unit_001.discretization.par_disc_type = 'EQUIDISTANT_PAR'    
+model.root.input.model.unit_001.discretization.use_analytic_jacobian = 1
+model.root.input.model.unit_001.discretization.reconstruction = 'WENO'
+model.root.input.model.unit_001.discretization.gs_type = 1
+model.root.input.model.unit_001.discretization.max_krylov = 0
+model.root.input.model.unit_001.discretization.max_restarts = 10
+model.root.input.model.unit_001.discretization.schur_safety = 1.0e-8
+
+model.root.input.model.unit_001.discretization.weno.boundary_model = 0
+model.root.input.model.unit_001.discretization.weno.weno_eps = 1e-10
+model.root.input.model.unit_001.discretization.weno.weno_order = 3
+
+## Outlet
+model.root.input.model.unit_002.unit_type = 'OUTLET'
+model.root.input.model.unit_002.ncomp = 1
+
+# Sections 
+model.root.input.solver.sections.nsec = 1
+model.root.input.solver.sections.section_times = [0.0, 1200,]   # s
+model.root.input.solver.sections.section_continuity = []
+
+# Inlet sections
+model.root.input.model.unit_000.sec_000.const_coeff = [1.0e-3,] # mol / m^3
+model.root.input.model.unit_000.sec_000.lin_coeff = [0.0,]
+model.root.input.model.unit_000.sec_000.quad_coeff = [0.0,]
+model.root.input.model.unit_000.sec_000.cube_coeff = [0.0,]
+
+# Switches
+model.root.input.model.connections.nswitches = 1
+model.root.input.model.connections.switch_000.section = 0
+model.root.input.model.connections.switch_000.connections = [
+    0, 1, -1, -1, 60/1e6,  # [unit_000, unit_001, all components, all components, Q/ m^3*s^-1 
+    1, 2, -1, -1, 60/1e6]  # [unit_001, unit_002, all components, all components, Q/ m^3*s^-1 
+
+# Solver settings
+model.root.input.model.solver.gs_type = 1
+model.root.input.model.solver.max_krylov = 0
+model.root.input.model.solver.max_restarts = 10
+model.root.input.model.solver.schur_safety = 1e-8
+
+# Number of cores for parallel simulation
+model.root.input.solver.nthreads = 1
+
+# Tolerances for the time integrator
+model.root.input.solver.time_integrator.abstol = 1e-6
+model.root.input.solver.time_integrator.algtol = 1e-10
+model.root.input.solver.time_integrator.reltol = 1e-6
+model.root.input.solver.time_integrator.init_step_size = 1e-6
+model.root.input.solver.time_integrator.max_steps = 1000000
+
+# Return data
+model.root.input['return'].split_components_data = 0
+model.root.input['return'].split_ports_data = 0
+model.root.input['return'].unit_000.write_solution_bulk = 1
+model.root.input['return'].unit_000.write_solution_inlet = 1
+model.root.input['return'].unit_000.write_solution_outlet = 1
+
+# Copy settings to the other unit operations
+model.root.input['return'].unit_001 = model.root.input['return'].unit_000
+model.root.input['return'].unit_002 = model.root.input['return'].unit_000
+
+# Solution times
+model.root.input.solver.user_solution_times = np.linspace(0, 1200, 1001)
+
+# Save and run simulation
+model.filename = 'model.h5'
+model.save()
+
+data = model.run()
+
+if data.returncode == 0:
+    print("Simulation completed successfully")
+    model.load()   
+else:
+    print(data)
+    raise Exception("Simulation failed")
+
+# Plot restuls
+plt.figure()
+
+time = model.root.output.solution.solution_times
+c = model.root.output.solution.unit_001.solution_outlet
+plt.plot(time/60, c)
+plt.xlabel('$time~/~min$')
+plt.ylabel('$Outlet~concentration~/~mol \cdot m^{-3} $')
+plt.show()

doc/examples/index.rst

@@ -0,0 +1,12 @@
+.. _examples:
+
+Examples
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   reaction_cstr
+   rtd
+   batch_chromatography
+   load_wash_elute

doc/examples/load_wash_elute.rst

@@ -0,0 +1,3 @@
+Load Wash Elute
+===============
+

doc/examples/reaction_cstr.rst

@@ -0,0 +1,2 @@
+Chemical reactions
+==================

doc/examples/rtd.rst

@@ -0,0 +1,3 @@
+Residence time distributions
+============================
+