pydac3 3.0.0__py3-none-any.whl

pydac/__init__.py

@@ -0,0 +1,59 @@
+"""pyDAC: simulation of adsorption-based direct air capture processes.
+
+The supported Python API (the same layer the ``pydac`` command uses)::
+
+    import pydac
+
+    case = pydac.load_case("my_case.json", settings={"execution.max_cycles": 30})
+    result = pydac.run_css(case)            # RunResult: folder, css_reached, cycle, ...
+    pydac.report(result.folder, fmt="png")
+    kpis = pydac.CycleKPIs(pydac.CycleDataLoader(result.folder).load())
+
+Names are imported on first use, so ``import pydac`` stays light: numpy,
+matplotlib and pymoo load only when a name that needs them is used.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+from pydac.utils.version import __version__
+
+_EXPORTS = {
+    "load_case": "pydac.api",
+    "export_case": "pydac.api",
+    "export_settings": "pydac.api",
+    "run_steps": "pydac.api",
+    "run_css": "pydac.api",
+    "run_nsga2": "pydac.api",
+    "resume": "pydac.api",
+    "report": "pydac.api",
+    "RunResult": "pydac.api",
+    "ConfigurationError": "pydac.config.errors",
+    "RunRefused": "pydac.config.errors",
+    "ExperimentConfig": "pydac.config.schema",
+    "CycleDataLoader": "pydac.post_processing.metrics.cycle_data_loader",
+    "CycleKPIs": "pydac.post_processing.kpi.cycle_kpis",
+    "register_equilibrium": "pydac.extensions",
+    "register_kinetics": "pydac.extensions",
+    "get_started": "pydac.starter_kit",
+    "EquilibriumSystem": "pydac.core.isotherm_models",
+    "KineticLaw": "pydac.core.kinetic_models",
+    "EquilibriumRegistryEntry": "pydac.utils.model_registry",
+    "KineticRegistryEntry": "pydac.utils.model_registry",
+}
+
+__all__ = ["__version__", *_EXPORTS]
+
+
+def __getattr__(name: str):
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module 'pydac' has no attribute {name!r}")
+    value = getattr(importlib.import_module(module), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_EXPORTS))

pydac/_kit/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.

pydac/_kit/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.

pydac/_kit/README.md

@@ -0,0 +1,262 @@
+# 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](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`](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](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`](examples/README.md);
+tutorial 07 needs Python, because it registers its own isotherm.
+
+| Tutorial | What it shows |
+|---|---|
+| [01 First steps](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](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](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](examples/notebooks/04_1d_vs_2d.ipynb) | the same cycle in 1D, in 2D and in 2D with wall channeling |
+| [05 An optimization campaign](examples/notebooks/05_nsga2_trial.ipynb) | a trial NSGA-II campaign: variables, bounds, constraints, the Pareto front |
+| [06 Reproduce the breakthrough validation](examples/notebooks/06_breakthrough_validation.ipynb) | the 2D model of the pyDAC paper against the measurements of Zanco et al. |
+| [07 Your own isotherm](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](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`](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`](docs/README.md). The user guide explains how to use
+pyDAC:
+
+- [Installation](docs/guide/01_installation.md): environments, Jupyter, shell
+  completion, exact reproduction, troubleshooting.
+- [Quick start](docs/guide/02_quickstart.md): one case from the terminal, a script
+  and a notebook; the Python API and its errors.
+- [Cases and settings](docs/guide/03_cases.md): presets, settings, frozen cases,
+  model choices, `null`, fingerprints.
+- [Running steps and cycles](docs/guide/04_running.md): step sequence, stop rules,
+  resume, replay, report, run folders, exit codes.
+- [Optimization campaigns](docs/guide/05_optimization.md): NSGA-II campaigns, bounds,
+  constraints, stop rules, continuing and reporting a campaign.
+- [Results](docs/guide/06_results.md): run folders, KPI files, reading results from
+  Python, which folders to trust.
+- [Reproducibility](docs/guide/07_reproducibility.md): sharing a case, provenance,
+  the exact environment, compatibility across versions.
+- [Extending pyDAC](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`](docs/manual/00_framework_map.md) | Layers, entry points and what a run does end to end |
+| [`01_inputs.md`](docs/manual/01_inputs.md) | Cases, presets, settings and the case document |
+| [`02_pydac_core.md`](docs/manual/02_pydac_core.md) | Model construction, state vector, solver and cycle orchestration |
+| [`03_pymrm_discretization.md`](docs/manual/03_pymrm_discretization.md) | Finite-volume operators and boundary conditions |
+| [`04_governing_equations.md`](docs/manual/04_governing_equations.md) | Balances and closures, and where the code assembles them |
+| [`05_cycle_steps.md`](docs/manual/05_cycle_steps.md) | Each cycle step: physics, boundary conditions, stop rules |
+| [`06_post_processing.md`](docs/manual/06_post_processing.md) | KPIs, separators, plots and result files |
+| [`07_nsga2_optimization.md`](docs/manual/07_nsga2_optimization.md) | NSGA-II campaigns |
+
+To work on pyDAC itself, read [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## How to cite
+
+If you use pyDAC in your research, please cite it with the metadata in
+[`CITATION.cff`](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`](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.

pydac/_kit/docs/guide/01_installation.md

@@ -0,0 +1,244 @@
+---
+title: "Installation"
+toc: true
+toc-depth: 3
+embed-resources: true
+---
+
+> **New to pyDAC? Do the [tutorials](../../examples/README.md) first, starting with
+> [01 First steps](../../examples/notebooks/01_first_steps.ipynb).** They teach pyDAC step by
+> step on real runs; this guide is the reference behind them and goes into more technical detail.
+
+This page installs pyDAC in an environment of its own, checks it, and connects it to
+Jupyter and to your shell. The [README](../../README.md) gives the short version.
+
+## What you need
+
+- Python 3.11, 3.12, 3.13 or 3.14.
+- Linux (x86_64) is the supported platform. Windows is being tested; macOS is neither
+  tested nor supported.
+- About 1 GB of disk space for the environment (see
+  [What gets installed](#what-gets-installed)).
+
+## Why pyDAC needs its own environment
+
+pyDAC fixes the versions of some dependencies: `pymrm==2.1.10`, `pandas<3` and
+`scikit-sundae` 1.1.x. pip silently replaces versions that are already installed: in an
+environment that already had pandas 3.0.6, installing pyDAC downgraded it to 2.3.3
+without a question. In a shared environment, installing pyDAC can therefore break another
+project, and installing another project can break pyDAC.
+
+Install pyDAC only in a new environment created for it. Never use:
+
+- the system Python;
+- the conda `base` environment;
+- an environment shared with another project.
+
+## Create the environment
+
+Pick one tool. Each block creates an environment and activates it; later commands on this
+page run inside the active environment.
+
+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:
+
+```bash
+conda create -n pydac python=3.12
+conda activate pydac
+```
+
+With uv:
+
+```bash
+uv venv pydac-env
+source pydac-env/bin/activate
+```
+
+A uv environment has no `pip`: wherever this page writes `python -m pip`, write `uv pip`
+instead.
+
+Activate the environment again in every new terminal before you use pyDAC.
+
+## Install pyDAC
+
+```bash
+python -m pip install pydac3
+```
+
+Until pyDAC 3.0.0 is on PyPI, install it from a clone of the repository:
+
+```bash
+git clone https://github.com/process-intensification-lab/pyDAC.git
+cd pyDAC
+python -m pip install .
+```
+
+One install contains every workflow: step runs, cyclic steady state (CSS) runs, case
+validation and NSGA-II optimization. Shell completion is an optional extra, see
+[Shell completion](#shell-completion).
+
+### Names
+
+| Name | What it is |
+|---|---|
+| `pydac3` | the distribution: the name you give to `pip install` |
+| `pydac` | the package you import (`import pydac`) and the command you run (`pydac css`) |
+| pyDAC | the project |
+
+`pip install pydac` installs an unrelated project with the same name. If you installed it
+by mistake, remove it with `python -m pip uninstall pydac`.
+
+### What gets installed
+
+The environment holds about 100 packages and 0.9 GB. pyDAC's own dependencies are numpy,
+scipy, pandas, matplotlib, seaborn, pymoo, scikit-sundae and pymrm; pymrm 2.1.10 in turn
+requires its documentation, notebook and test tools (sphinx, ipython, ipykernel, nbclient,
+pytest, numba and others). They are installed even though pyDAC does not call them. One
+useful consequence: the environment already holds a Jupyter kernel (ipykernel), so VS Code
+or an existing Jupyter installation can run notebooks on it
+([Use pyDAC in Jupyter](#use-pydac-in-jupyter)). The browser interface itself (JupyterLab
+or Notebook) is not included: install it separately if you want it.
+
+### Get the tutorials and this guide
+
+The installed package also holds a starter kit: the README, the licence, the citation
+file, this guide and the tutorials (cases, notebooks and data). Copy it into a new
+folder:
+
+```bash
+pydac get-started my_pydac
+cd my_pydac
+```
+
+(`pydac.get_started("my_pydac")` does the same from Python.) The folder has the layout
+of the repository, so the tutorials run as written in
+[`examples/README.md`](../../examples/README.md) from inside it. The kit has no source code,
+tests or developer manual: its links to the manual open it in the public repository, at
+the version you installed. `pydac get-started` refuses a folder that already holds files. A clone
+of the repository already has everything; it needs no kit.
+
+## Check the environment
+
+```bash
+python -m pip check
+pydac --version
+python -c "import pydac; print(pydac.__file__)"
+```
+
+A correct environment prints:
+
+- `No broken requirements found.`;
+- `pydac 3.0.0` (the installed version);
+- a path inside the environment you created, ending in `site-packages/pydac/__init__.py`.
+
+If the path lies in the user site instead (for example under `~/.local/lib/`), a
+package installed with `pip install --user` shadows the environment's own. A venv
+ignores the user site, but a conda environment searches it before its own packages. Set
+`PYTHONNOUSERSITE=1` in the shell before running pyDAC, or remove the user-site
+installation.
+
+### The environment warning
+
+When the `pydac` command runs outside a dedicated environment, it prints one line on
+stderr and continues:
+
+```text
+Warning: pydac is running outside a dedicated environment (PREFIX). pyDAC pins some dependencies, and pip replaces installed versions without asking: install it in its own venv or conda environment (README, Installation). PYDAC_NO_ENV_WARNING=1 silences this.
+```
+
+The command counts as dedicated when it runs in a virtual environment (venv, uv) or in a
+conda environment other than `base`. The warning never stops a run. `import pydac` never
+prints it, so in scripts and notebooks the check above is your only safeguard. To silence
+it on purpose, for example in a container that uses the system Python by design, set
+`PYDAC_NO_ENV_WARNING=1`.
+
+## Use pyDAC in Jupyter
+
+Register the environment as a Jupyter kernel, once, with the environment active:
+
+```bash
+python -m ipykernel install --user --name pydac-env --display-name "Python (pyDAC)"
+```
+
+In Jupyter (or VS Code), select the kernel "Python (pyDAC)". A notebook running on another
+kernel imports another environment's packages, or none. To check from a notebook cell:
+
+```python
+import sys
+import pydac
+
+print(sys.executable)
+print(pydac.__file__)
+```
+
+Both paths must lie inside the pyDAC environment. To remove the kernel later:
+
+```bash
+jupyter kernelspec uninstall pydac-env
+```
+
+## Shell completion
+
+The `completion` extra adds tab completion of the `pydac` subcommands and flags in bash
+and zsh:
+
+```bash
+python -m pip install "pydac3[completion]"
+eval "$(register-python-argcomplete pydac)"
+```
+
+The second line enables completion in the current shell; run it again in each new shell
+after activating the environment. Then `pydac cs` + Tab completes to `pydac css`, and
+`pydac css --ov` + Tab lists `--overwrite` and `--overwrite-case`.
+
+## Exact reproduction
+
+To rebuild the environment in which pyDAC was qualified, every package at the exact
+version and checked against its hash, use the lock file of the repository. It is written
+for Python 3.12. From the root of a clone, in a second fresh environment:
+
+```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 .
+```
+
+`--no-deps` installs pyDAC itself without letting pip change any version the lock fixed.
+
+## Update or remove
+
+To update pyDAC, run `python -m pip install --upgrade pydac3` in its environment, then
+`python -m pip check`. A new pyDAC version may require other dependency versions; if
+`pip check` reports a conflict, create a new environment instead of repairing the old one.
+
+To remove pyDAC, delete the environment: the `pydac-env` folder, or
+`conda env remove -n pydac`. Remove the Jupyter kernel as shown above.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| `pydac: command not found` | The environment is not active. Activate it (`source pydac-env/bin/activate`). |
+| `pydac.__file__` points into `~/.local` | A user-site installation shadows the environment. Set `PYTHONNOUSERSITE=1`, or uninstall the user-site copy. |
+| `pip check` reports a broken requirement | Another install changed a version pyDAC fixes. Create a new environment and install pyDAC alone in it. |
+| `import pydac` fails in a notebook | The notebook runs another kernel. Select "Python (pyDAC)" (see [Use pyDAC in Jupyter](#use-pydac-in-jupyter)). |
+| `pip install pydac` installed version 0.0.x | That is an unrelated project. Uninstall it and install `pydac3`. |
+
+## Related pages
+
+- [README](../../README.md): overview and quick start.
+- [CONTRIBUTING](../../CONTRIBUTING.md): the environment for working on pyDAC itself.