pydac3 3.0.0__tar.gz

pydac3-3.0.0/.gitignore

@@ -0,0 +1,44 @@
+# Python bytecode / cache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Jupyter and IPython history
+.ipynb_checkpoints/
+*.ipynb~
+
+# Local logs/output
+*.log
+*.tmp
+*.bak
+
+# Environment / virtualenvs (in case local)
+.venv/
+env/
+venv/
+
+# Mac/Windows/Linux system files
+.DS_Store
+Thumbs.db
+
+# Test cache
+.cache/
+.pytest_cache/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Simulation results
+simulation_results/*
+
+# Jacobian masks are generated in memory; no cache folder may come back
+src/pydac/core/sparsity_patterns/*/
+
+.vscode/
+
+# Run folders and saved files written by the tutorials (from any folder)
+examples/**/simulation_results/
+output_cases/

pydac3-3.0.0/CITATION.cff

@@ -0,0 +1,29 @@
+# Citation metadata. At each GitHub release Zenodo adds the DOI and the release date;
+# the paper becomes `preferred-citation` once it is published.
+cff-version: 1.2.0
+message: "If you use pyDAC in your research, please cite it as below."
+title: "pyDAC: simulation of adsorption-based direct air capture processes"
+type: software
+authors:
+  - given-names: Mattia
+    family-names: Galanti
+  - given-names: Ivo
+    family-names: Roghair
+  - given-names: Martin
+    name-particle: van
+    family-names: Sint Annaland
+license: MIT
+version: 3.0.0
+repository-code: "https://github.com/process-intensification-lab/pyDAC"
+keywords:
+  - direct air capture
+  - adsorption
+  - TVSA
+  - cyclic adsorption
+  - packed bed
+  - process simulation
+abstract: >-
+  pyDAC simulates adsorption cycles composed from configurable steps (by default a
+  steam-assisted temperature-vacuum swing adsorption, TVSA, cycle) for CO2 direct air capture
+  in 1D and 2D packed beds: single step sequences, cycles to cyclic steady state with KPIs, and
+  local NSGA-II optimization of the operating conditions.

pydac3-3.0.0/CONTRIBUTING.md

@@ -0,0 +1,240 @@
+# Contributing to pyDAC
+
+This page is for developers working in a clone of the repository. To use pyDAC, read
+[`README.md`](README.md) instead. Rules come first, each with its reason in one line.
+
+## Using pyDAC or changing it
+
+| You want to | Install | Which code runs |
+|---|---|---|
+| use pyDAC | `python -m pip install pydac3` ([README](README.md#2-install-pydac)) | a copy fixed at install time; files you edit are not used |
+| change pyDAC | a clone, installed editable (`python -m pip install -e .`) | the clone's `src/pydac/`: an edit is used at the next import |
+
+An editable install copies no code: it points the environment at the clone. Everything
+below is about the second row.
+
+## Environment
+
+- **One dedicated environment per clone, never shared between clones.** An editable
+  install points the environment at one clone; a second clone in the same environment
+  silently runs the first one's code.
+- **Disable the user site.** Packages under `~/.local` shadow the environment's own
+  numpy, scipy and pandas: set `PYTHONNOUSERSITE=1` in the shell that runs pyDAC.
+- **Pick the light or the exact environment.** The light one takes the newest allowed
+  version of every dependency and works with any supported Python; the exact one is the
+  qualification lock, the only one in which your numbers match the qualified ones digit
+  for digit and the `qualification` tests hold.
+
+Get the code: fork the repository on GitHub (if you plan to propose changes) and clone
+your fork:
+
+```bash
+git clone https://github.com/<your-user>/pyDAC.git
+cd pyDAC
+```
+
+**Light environment**, from the root of the clone, with Python 3.11 to 3.14:
+
+```bash
+export PYTHONNOUSERSITE=1
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e .
+python -m pip install --group test
+python -m pip check
+python -c "import site, pydac; print(site.ENABLE_USER_SITE, pydac.__file__)"
+```
+
+**Exact environment**, from the root of the clone, with Python 3.12 (the lock is written
+for it):
+
+```bash
+export PYTHONNOUSERSITE=1
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --require-hashes -r ci/qualification-lock-py3.12.txt
+python -m pip install --no-deps -e .
+python -m pip check
+python -c "import site, pydac; print(site.ENABLE_USER_SITE, pydac.__file__)"
+```
+
+In both, the last line must print `False` and a path inside this clone's `src/pydac/`.
+The name `.venv` is the one VS Code detects on its own. The lock already holds pytest.
+
+- **Restart running Python sessions after editing sources.** An editable install reads
+  the sources when a module is first imported; a running interpreter or notebook kernel
+  keeps the old code until it restarts.
+- **Reinstall after changing `pyproject.toml`** (dependencies, entry points, metadata):
+  run `python -m pip install --no-deps -e .` again. Until then the installed metadata is
+  stale, which is why `importlib.metadata.version("pydac3")` is never used as the
+  version.
+
+## What is supported
+
+| Level | What | Promise |
+|---|---|---|
+| Command | `pydac steps`, `pydac css`, `pydac nsga2`, `pydac validate` and their flags | documented; changes announced in the release notes |
+| API | the names in `pydac.__all__` | documented; changes announced in the release notes |
+| Internal | every other module under `src/pydac/` | shipped and importable, no stability promise |
+| Clone tools | `runners/`, `tests/`, `docs/`, `ci/` | for working in a clone; not in the wheel |
+
+User documentation shows only commands and `pydac.__all__` names.
+
+## Running from VS Code
+
+The files in [`runners/`](runners/) are launchers for this clone; they are not shipped in
+the wheel. The step, CSS and campaign runners call the `pydac` command with the constants
+at their top; `validate_config.py` has no constants and passes its command-line arguments
+to `pydac validate`:
+
+| Runner | Same as |
+|---|---|
+| `runners/run_steps_simulation.py` | `pydac steps` |
+| `runners/run_css_simulation.py` | `pydac css` |
+| `runners/run_NSGA2.py` | `pydac nsga2` |
+| `runners/validate_config.py` | `pydac validate` |
+
+| Constant | Effect |
+|---|---|
+| `CONFIG_PATH` | a partial preset, as `--config` |
+| `DEVELOPMENT_SETTINGS` | settings applied after the preset and before `--set` |
+| `CASE_PATH` | a complete case run exactly, as `--case` |
+| `RESUME_PATH` | a saved run to continue, as `--resume` |
+| `OVERWRITE` | replace this case's existing run folder, as `--overwrite` (step and CSS runners only) |
+
+- Precedence: built-in defaults < `CONFIG_PATH` (or `--config`) < `DEVELOPMENT_SETTINGS`
+  < `--set`. `pydac` itself never reads these constants; only the runner passes them.
+- `CASE_PATH` refuses `CONFIG_PATH`, `--config`, `--set` and non-empty
+  `DEVELOPMENT_SETTINGS`: a frozen case runs exactly as saved.
+- Running the same case twice is refused (exit code `2`) while its run folder exists:
+  set `OVERWRITE = True`, resume it, or change `execution.extra_tag`. A campaign has no
+  `OVERWRITE`: continue it with `RESUME_PATH`, or delete its folder yourself.
+- A CSS (cyclic steady state) run that stops at `execution.max_cycles` without reaching CSS exits with code
+  `3` when `execution.require_css` is true. Errors go to stderr.
+- Select this clone's `.venv` as the VS Code interpreter.
+
+## Tests
+
+```bash
+python -m pytest -q -m "not qualification"
+```
+
+The light environment installs pytest with `--group test`, which needs pip 25.1 or
+newer. Tests marked `qualification` compare fingerprints and numbers that hold only in
+the exact environment; inside it, run the full suite with `python -m pytest -q`.
+
+## Proposing a change
+
+- **Open an issue before the code** for anything beyond a small fix: say what you want to
+  change and why. A change to the physics core needs the maintainer's agreement first
+  ([below](#physics-core-maintainer-review)).
+- **One topic per pull request, on its own branch** of your fork, started from `main`:
+  a reviewer can then accept or refuse each change on its own.
+- **Run the checks in your clone before opening the pull request:**
+
+  ```bash
+  python -m pytest -q -m "not qualification"
+  python docs/check_links.py
+  ```
+
+  New behaviour comes with a test that fails without it.
+- **Open the pull request against `main`.** CI builds the wheel, installs it on Linux
+  (Python 3.11 to 3.14) and on Windows, runs the tests, a short run of the `pydac`
+  command and the link check. A pull request is merged with CI green and the
+  maintainer's review.
+- **Say in the pull request whether results change, and which cases you compared.** The
+  `qualification` job of CI fails when numbers move; a change that moves them on purpose
+  needs the reason, and the maintainer regenerates the baseline.
+- **Keep the documentation in step.** A change to a command, a setting or a
+  `pydac.__all__` name updates the guide or the manual in the same pull request, and its
+  description says what users will notice, for the release notes.
+
+## Code rules
+
+- **Absolute imports only:** `from pydac.config import ...`. No `sys.path` edits and no
+  imports of `src.` or of top-level folders; with the `src/` layout, `import pydac` works
+  from a clone only through the editable install.
+- **No formatter or linter pass.** A formatting pass rewrites every line of the physics
+  files, which would hide the physical changes under review; do not reformat code you do
+  not change.
+- **Code headers cite reference sections** (`# Guide: docs/manual/01_inputs.md §3`), and
+  `docs/check_links.py` checks them. When you renumber or move a section, update every
+  header that cites it.
+- **Plain words in code and messages.** Write what a rule does, not an internal decision
+  label.
+
+## Physics core: maintainer review
+
+Changes to [`src/pydac/core/column_model.py`](src/pydac/core/column_model.py) and to
+anything under [`src/pydac/post_processing/`](src/pydac/post_processing/) need the
+maintainer's review before they are written: open an issue that states what you intend
+to change, why (the physical or numerical reasoning) and the expected effect on results.
+These files define what pyDAC computes and reports.
+
+## Extending the model
+
+An isotherm or a kinetic law of your own can be used without changing pyDAC: register it from
+Python ([Extending pyDAC](docs/guide/08_extending.md)). Adding one to the package, so that
+every user and the `pydac` command know it, or adding a species, is code work in a clone;
+pull requests are welcome. The contract each addition must meet is in
+[`docs/manual/01_inputs.md` §10](docs/manual/01_inputs.md#10-extending-the-contract):
+
+- **Species:** a `SpeciesProperties` entry in
+  [`src/pydac/core/species_catalog.py`](src/pydac/core/species_catalog.py) (molar mass,
+  Lennard-Jones parameters, Fuller volume, conductivity and Shomate heat-capacity
+  coefficients).
+- **Isotherm:** an entry in `EQUILIBRIUM_REGISTRY` in
+  [`src/pydac/core/isotherm_models.py`](src/pydac/core/isotherm_models.py).
+- **Kinetic model:** an entry in `KINETIC_REGISTRY` in
+  [`src/pydac/core/kinetic_models.py`](src/pydac/core/kinetic_models.py).
+
+The built-in registries, the species catalog and the bed-architecture registry are read-only
+at run time. `pydac.register_equilibrium` and `pydac.register_kinetics` add models for one
+Python session only, beside the built-in ones, and refuse a built-in name.
+
+## Saved files and versions
+
+- A change to the shape of a saved file (case, run folder records, campaign checkpoint)
+  bumps that file's version number.
+- Readers keep accepting every older version; a newer version than the reader knows is
+  refused with a message naming the file.
+- A new case field needs a case-schema version bump and an upgrade step that gives
+  older cases the value reproducing what they computed
+  ([`src/pydac/config/migrations.py`](src/pydac/config/migrations.py)).
+- From a later release on, each release will add a small set of frozen saved files under
+  `tests/data/`, with a test that the installed package reads, reports, replays and
+  continues them.
+
+## Dependency pins
+
+`pymrm` is pinned exactly (`pymrm==2.1.10`) because pyDAC calls internals of it that
+changed after that version; `scikit-sundae` is held to 1.1.x and `pandas` below 3.
+Raising any of these is a release decision: rerun the qualified cases in the new
+environment and compare them with the current results first.
+
+## Tools
+
+| Task | Command |
+|---|---|
+| Regenerate the JSON schema of the case document after changing a default or rule | `python -m pydac.config.schema_generation` |
+| Draw the analytical Jacobian sparsity mask | `python -m pydac.core.sparsity_patterns.analytical_sparsity --nz 10 --nr 5 --out FOLDER` |
+| Check a step's recorded Jacobians against the analytical mask | `python -m pydac.core.sparsity_patterns.numerical_sparsity FOLDER --nz 10 --nr 5` |
+| Check documentation links and code `# Guide:` headers | `python docs/check_links.py` |
+| Regenerate the smoke-test baseline (qualification environment only) | `python tests/tools/generate_v3_smoke_baseline.py` |
+
+Environment variables for developers (do not set them for production runs). The two
+solver switches are recorded in each run's provenance (`software.solver_environment`); the
+other two are not:
+
+| Variable | Effect |
+|---|---|
+| `PYDAC_NO_ENV_WARNING=1` | silences the dedicated-environment warning of the `pydac` command |
+| `PYDAC_PROFILE=PATH` | replaces the built-in defaults with a complete JSON profile |
+| `PYDAC_RHS_CSR_OPERATORS=0` | applies the fixed operators in their original sparse format (A/B checks) |
+| `PYDAC_CACHE_SLICE_WRITE=0` | disables the contiguous-slice writes of the operator cache (A/B checks) |
+
+## Releases
+
+- The version lives in one place, `src/pydac/utils/version.py`.
+- A published tag is never moved or re-created; a fix is a new version.

pydac3-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mattia Galanti, Ivo Roghair, Martin van Sint Annaland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydac3-3.0.0/PKG-INFO

@@ -0,0 +1,298 @@
+Metadata-Version: 2.5
+Name: pydac3
+Version: 3.0.0
+Summary: Simulation of adsorption-based direct air capture processes.
+Project-URL: Repository, https://github.com/process-intensification-lab/pyDAC
+Project-URL: Issues, https://github.com/process-intensification-lab/pyDAC/issues
+Author: Mattia Galanti, Ivo Roghair, Martin van Sint Annaland
+Maintainer-email: Mattia Galanti <mattiagalanti1@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: TVSA,adsorption,cyclic adsorption,direct air capture,packed bed,process simulation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.8.1
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: pymoo>=0.6.2
+Requires-Dist: pymrm==2.1.10
+Requires-Dist: scikit-sundae<1.2,>=1.1
+Requires-Dist: scipy>=1.13.1
+Requires-Dist: seaborn>=0.13
+Provides-Extra: all
+Requires-Dist: argcomplete; extra == 'all'
+Provides-Extra: completion
+Requires-Dist: argcomplete; extra == 'completion'
+Description-Content-Type: text/markdown
+
+# pyDAC
+
+pyDAC simulates adsorption-based direct air capture (DAC) processes. It solves the
+coupled mass, energy and momentum balances of a sorbent column in 1D or 2D
+(axisymmetric) and runs adsorption cycles step by step or to cyclic steady state (CSS).
+A cycle is composed from configurable steps (adsorption, blowdown, heating, purge, steam-
+or wall-heated desorption, cooling, pressurization); the default is a steam-assisted
+temperature-vacuum swing adsorption (TVSA) cycle. pyDAC reports process key performance
+indicators (KPIs) and optimizes operating conditions with the NSGA-II genetic algorithm
+(non-dominated sorting genetic algorithm II).
+
+pyDAC 3.0.0, development status Beta. MIT license.
+
+## Installation
+
+### 1. Create a dedicated environment
+
+Install pyDAC in an environment of its own: never in the system Python, a conda `base`
+environment, or an environment shared with other projects. pyDAC fixes the versions of
+some dependencies (`pymrm==2.1.10`, `pandas<3`, `scikit-sundae` 1.1.x), and pip silently
+replaces versions that are already installed, so a shared environment can break pyDAC
+or the other project without any message.
+
+Linux, with `venv`:
+
+```bash
+python3 -m venv pydac-env
+source pydac-env/bin/activate
+```
+
+Windows (PowerShell), with `venv`:
+
+```powershell
+py -m venv pydac-env
+pydac-env\Scripts\Activate.ps1
+```
+
+With conda instead:
+
+```bash
+conda create -n pydac python=3.12
+conda activate pydac
+```
+
+With uv instead (`uv` environments have no `pip`; write `uv pip` where this page writes
+`python -m pip`):
+
+```bash
+uv venv pydac-env
+source pydac-env/bin/activate
+```
+
+### 2. Install pyDAC
+
+```bash
+python -m pip install pydac3
+```
+
+The distribution is called `pydac3`; the package you import and the command you run are
+both `pydac`. `pip install pydac` installs an unrelated project.
+
+One install contains everything: step runs, CSS runs, case validation and NSGA-II
+optimization (pymoo is a regular dependency). `pydac get-started my_pydac` copies the tutorials
+and the user guide into a new folder
+([Get the tutorials](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/guide/01_installation.md#get-the-tutorials-and-this-guide)). The optional extra `completion` adds shell
+completion for the `pydac` command (`python -m pip install "pydac3[completion]"`).
+
+Python 3.11 to 3.14 on Linux (x86_64) is supported. Windows is being tested; macOS is
+neither tested nor supported.
+
+**Want to adapt pyDAC to your own needs, or help improve it?** Install it from a clone in
+editable mode instead; then an edit in `src/pydac/` is used at the next import:
+
+```bash
+git clone https://github.com/process-intensification-lab/pyDAC.git
+cd pyDAC
+python -m pip install -e .
+```
+
+[`CONTRIBUTING.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/CONTRIBUTING.md) gives the full procedure (dedicated environment, light or
+exact dependencies, tests) and how to propose a change.
+
+### 3. Check the environment
+
+```bash
+python -m pip check
+pydac --version
+python -c "import pydac; print(pydac.__file__)"
+```
+
+`pip check` must report no broken requirements, and the printed path must lie inside
+the environment you created. A path in the user site instead (for example under
+`~/.local/lib/`) means a user-site installation shadows the environment; set
+`PYTHONNOUSERSITE=1` or remove that installation.
+
+When the `pydac` command runs outside a virtual environment or a conda environment
+other than `base`, it prints a one-line warning on stderr and continues. Set
+`PYDAC_NO_ENV_WARNING=1` to silence it, for example in a container that uses the system
+Python on purpose. `import pydac` never prints it.
+
+### Exact reproduction
+
+To reproduce the qualified environment exactly (every package pinned, with hashes;
+Python 3.12), install from the lock file into a second fresh environment, from the
+root of a clone:
+
+```bash
+python3.12 -m venv pydac-exact
+source pydac-exact/bin/activate
+python -m pip install --require-hashes -r ci/qualification-lock-py3.12.txt
+python -m pip install --no-deps .
+```
+
+## Tutorials
+
+**The best way to learn pyDAC is the seven tutorials. Start with
+[01 First steps](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/examples/notebooks/01_first_steps.ipynb)**, then follow them in order.
+`pydac get-started my_pydac` copies them, with the user guide, into a new folder. Each
+tutorial is a notebook and states its runtime (from a few minutes to about 40). Tutorials
+01-06 also run from the terminal, with the commands in [`examples/README.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/examples/README.md);
+tutorial 07 needs Python, because it registers its own isotherm.
+
+| Tutorial | What it shows |
+|---|---|
+| [01 First steps](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/examples/notebooks/01_first_steps.ipynb) | a step run, the KPI table of each step, step profile plots, time- or event-based stop |
+| [02 Build your own case](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/examples/notebooks/02_custom_case.ipynb) | replace the defaults block by block (column, gas, sorbent, isotherm, kinetics, steps); a 2D TSA step run |
+| [03 A cycle at its periodic state](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/examples/notebooks/03_css_tvsa.ipynb) | a CSS run of the built-in TVSA cycle in 2D, the cycle KPIs, where the CO2 and the energy go |
+| [04 1D or 2D](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/examples/notebooks/04_1d_vs_2d.ipynb) | the same cycle in 1D, in 2D and in 2D with wall channeling |
+| [05 An optimization campaign](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/examples/notebooks/05_nsga2_trial.ipynb) | a trial NSGA-II campaign: variables, bounds, constraints, the Pareto front |
+| [06 Reproduce the breakthrough validation](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/examples/notebooks/06_breakthrough_validation.ipynb) | the 2D model of the pyDAC paper against the measurements of Zanco et al. |
+| [07 Your own isotherm](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/examples/notebooks/07_new_isotherm.ipynb) | a new sorbent from the literature, its isotherm registered from Python and run |
+
+## Quick start from the terminal
+
+A case is the complete set of inputs of one simulation. Write the built-in case to a
+file, here with a coarse 1D grid and at most three cycles:
+
+```bash
+pydac validate --set grid.nz=25 --set grid.nr=1 --set execution.max_cycles=3 --set execution.require_css=false --export-case my_case.json
+```
+
+`my_case.json` holds every input of the simulation. To change it, prefer settings over
+editing the file: they recompute the fields that depend on others, such as the bed length
+from its volume ([Cases and settings](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/guide/03_cases.md)). Then run it exactly as
+saved; it repeats the cycle until cyclic steady state, here for at most three cycles;
+this coarse case reaches CSS at cycle 3:
+
+```bash
+pydac css --case my_case.json
+```
+
+The run takes one to two minutes. It writes everything under
+`simulation_results/cyclic_mode/packed_bed_XXXXXXXX/`, where `XXXXXXXX` is the start of
+the case fingerprint, and prints that run folder as its last line. Inside,
+`1D_mode/cycle_N/` holds each cycle and `1D_mode/kpis/` the KPI tables of the final
+cycle. Running the same case again is refused while that folder exists: continue it with
+`--resume`, replace it with `--overwrite`, or set another `execution.extra_tag`.
+
+The other commands are `pydac steps` (startup, then each listed step once),
+`pydac nsga2` (an optimization campaign) and `pydac validate`. Each lists its options
+with `--help`; `pydac validate --show-settings` lists the settings with their built-in
+defaults. Instead of a complete case, `--config` takes a partial preset whose omitted
+fields take the built-in defaults, for example
+[`examples/cases/quick_1D.json`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/examples/cases/quick_1D.json) from the repository:
+
+```bash
+pydac css --config examples/cases/quick_1D.json --dry-run
+```
+
+Exit codes: `0` success, `1` failure after the run started, `2` invalid command-line
+arguments, configuration error or refused request, `3` CSS not reached while
+`execution.require_css` is true.
+
+## Quick start from Python
+
+The same steps through the Python API, in a script or a notebook. This loads the saved
+case, changes one setting, runs it and reads two KPIs:
+
+```python
+import pydac
+
+case = pydac.load_case("my_case.json", settings={"execution.max_cycles": 4})
+result = pydac.run_css(case)
+print(result.folder, result.css_reached, result.cycle)
+
+kpis = pydac.CycleKPIs(pydac.CycleDataLoader(result.folder).load())
+print(f"CO2 recovery: {100 * kpis.recovery('CO2'):.1f} %")
+print(f"Productivity: {kpis.productivity():.2f} kg CO2 per m3 bed per day")
+```
+
+`pydac.load_case(path, exact=True)` runs a complete case exactly, as `--case` does. The
+supported API is the set of names in `pydac.__all__`: `load_case`, `export_case`,
+`export_settings`, `run_steps`, `run_css`, `run_nsga2`, `resume`, `report`, `get_started`,
+`RunResult`, `ConfigurationError`, `RunRefused`, `ExperimentConfig`, `CycleDataLoader`,
+`CycleKPIs`, `register_equilibrium`, `register_kinetics`, `EquilibriumSystem`, `KineticLaw`,
+`EquilibriumRegistryEntry`, `KineticRegistryEntry` and the version string `__version__`.
+
+## Reproducibility
+
+Every run folder contains the resolved case (`resolved_config.json`), its fingerprint
+(`case_metadata.json`) and a provenance record: the pyDAC version, the Python version,
+the platform and the versions of the numerical dependencies. Run from a clone, the
+record also says whether the checkout had uncommitted changes; it does not record the Git
+revision, so keep the commit of an unreleased checkout yourself. To
+rerun a result, run its `resolved_config.json` with `--case` (in another output root, or
+with `--overwrite`); to rebuild the environment, use the lock file above.
+
+## Documentation
+
+Read in this order: the tutorials (above) teach pyDAC on real runs; the user guide is
+the reference for using it, in more technical detail; the reference manual describes how pyDAC
+works inside, in full technical detail, for contributors and for checking the model. The
+documentation index is [`docs/README.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/README.md). The user guide explains how to use
+pyDAC:
+
+- [Installation](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/guide/01_installation.md): environments, Jupyter, shell
+  completion, exact reproduction, troubleshooting.
+- [Quick start](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/guide/02_quickstart.md): one case from the terminal, a script
+  and a notebook; the Python API and its errors.
+- [Cases and settings](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/guide/03_cases.md): presets, settings, frozen cases,
+  model choices, `null`, fingerprints.
+- [Running steps and cycles](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/guide/04_running.md): step sequence, stop rules,
+  resume, replay, report, run folders, exit codes.
+- [Optimization campaigns](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/guide/05_optimization.md): NSGA-II campaigns, bounds,
+  constraints, stop rules, continuing and reporting a campaign.
+- [Results](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/guide/06_results.md): run folders, KPI files, reading results from
+  Python, which folders to trust.
+- [Reproducibility](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/guide/07_reproducibility.md): sharing a case, provenance,
+  the exact environment, compatibility across versions.
+- [Extending pyDAC](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/guide/08_extending.md): your own isotherms and kinetic laws,
+  registered from Python; what needs a change to the package.
+
+The reference chapters describe the model and the code:
+
+| Chapter | Contents |
+|---|---|
+| [`00_framework_map.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/manual/00_framework_map.md) | Layers, entry points and what a run does end to end |
+| [`01_inputs.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/manual/01_inputs.md) | Cases, presets, settings and the case document |
+| [`02_pydac_core.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/manual/02_pydac_core.md) | Model construction, state vector, solver and cycle orchestration |
+| [`03_pymrm_discretization.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/manual/03_pymrm_discretization.md) | Finite-volume operators and boundary conditions |
+| [`04_governing_equations.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/manual/04_governing_equations.md) | Balances and closures, and where the code assembles them |
+| [`05_cycle_steps.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/manual/05_cycle_steps.md) | Each cycle step: physics, boundary conditions, stop rules |
+| [`06_post_processing.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/manual/06_post_processing.md) | KPIs, separators, plots and result files |
+| [`07_nsga2_optimization.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/docs/manual/07_nsga2_optimization.md) | NSGA-II campaigns |
+
+To work on pyDAC itself, read [`CONTRIBUTING.md`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/CONTRIBUTING.md).
+
+## How to cite
+
+If you use pyDAC in your research, please cite it with the metadata in
+[`CITATION.cff`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/CITATION.cff). Each GitHub release has its own DOI on Zenodo; once the
+pyDAC paper is published, it becomes the preferred citation.
+
+## License and authors
+
+pyDAC is released under the MIT license ([`LICENSE`](https://github.com/process-intensification-lab/pyDAC/blob/v3.0.0/LICENSE)). Authors: Mattia
+Galanti, Ivo Roghair and Martin van Sint Annaland (Eindhoven University of Technology).
+Maintainer: Mattia Galanti.
+
+## Acknowledgements
+
+We thank Shell Global Solutions International BV for financial support.