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:

python3 -m venv pydac-env
source pydac-env/bin/activate

Windows (PowerShell), with venv:

py -m venv pydac-env
pydac-env\Scripts\Activate.ps1

With conda instead:

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):

uv venv pydac-env
source pydac-env/bin/activate

2. Install pyDAC

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). 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:

git clone https://github.com/process-intensification-lab/pyDAC.git
cd pyDAC
python -m pip install -e .

CONTRIBUTING.md gives the full procedure (dedicated environment, light or exact dependencies, tests) and how to propose a change.

3. Check the environment

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:

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, 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; tutorial 07 needs Python, because it registers its own isotherm.

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:

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). 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:

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 from the repository:

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:

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. The user guide explains how to use pyDAC:

• Installation: environments, Jupyter, shell completion, exact reproduction, troubleshooting.
• Quick start: one case from the terminal, a script and a notebook; the Python API and its errors.
• Cases and settings: presets, settings, frozen cases, model choices, null, fingerprints.
• Running steps and cycles: step sequence, stop rules, resume, replay, report, run folders, exit codes.
• Optimization campaigns: NSGA-II campaigns, bounds, constraints, stop rules, continuing and reporting a campaign.
• Results: run folders, KPI files, reading results from Python, which folders to trust.
• Reproducibility: sharing a case, provenance, the exact environment, compatibility across versions.
• Extending pyDAC: 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:

To work on pyDAC itself, read CONTRIBUTING.md.

How to cite

If you use pyDAC in your research, please cite it with the metadata in 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). 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.