Installation

Note

This guide describes how to set up OpenAirClim as a developer, i.e. if you are planning on contributing code or documentation. If you only want to use OpenAirClim, see the user guide instead - it is lighter-weight and does not require git.

Cloning the repository

Unlike a user installation, development requires the full repository, including the test suite, lock files and CI configuration - none of which are published to PyPI or conda-forge. Clone it from GitHub:

cd path/to/working/dir
git clone https://github.com/dlr-pa/oac.git
cd oac

See Workflows for the branching model and how to open a pull request.

Setting up your environment

We recommend Python 3.13 for development. Development tooling (Black, Prospector, which wraps pylint, mypy and pyroma) is pinned to Python <3.14 because Prospector’s mypy integration currently crashes outright for 3.14 (an upstream incompatibility unrelated to OpenAirClim). This pin is thus developer-tooling-only and doesn’t affect which Python versions are supported by OpenAirClim (defined by requires-python in pyproject.toml). If you set up your environment with pip rather than conda or pixi, you are responsible for picking a 3.11-3.13 interpreter yourself for the same reason. Note that we are considering moving towards ruff (see #149), which would solve this problem.

Installation with pixi (recommended)

pixi installs every environment this repository defines (default, docs and dev) from the committed pixi.lock, for reproducible dependency versions across contributors and CI - conda-forge for compiled/system packages, PyPI for everything else. It also picks the pinned Python version automatically, so you do not need to worry about the note above:

pixi install --all

Run commands inside the dev environment with pixi run -e dev, e.g.:

pixi run -e dev test

Alternatively, activate it directly:

pixi shell -e dev

pixi task list shows every task available (linting, building the docs, checking the packaged distribution, …) - the sections below give the ones you will use most.

Installation with conda

conda env create -f environment_dev.yaml
conda activate oac
pip install -e .

environment_dev.yaml includes the gui, docs and test extras, so you do not need to update the environment with the other yaml files.

Installation with venv

To create a virtual environment and install an editable version of OpenAirClim with all development extras (gui, docs, test and linting tools), you will need a 3.11-3.13 interpreter already installed (see the note above):

python3.13 -m venv .venv
source .venv/bin/activate  # for Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -e ".[dev]"

The dev extra pulls in the narrower gui, docs and test extras too, so install one of those instead if you only need part of it, e.g. pip install -e ".[test]".

Creating test fixture data

The test suite relies on small, synthetic fixture files (emission inventories, response surfaces, background concentrations, example config files) rather than the real repository data described below. These are not committed to the repository and must be generated once, into tests/core/repository/:

python -m openairclim.utils.create_test_files -o tests/core/repository/

With pixi, this happens automatically whenever you run the test suite (see below), so you do not need to run it yourself unless you want the fixture files without also running the tests:

pixi run -e dev create-test-files

This is what tests/conftest.py’s shared valid_config/working_dir fixtures resolve against. If you add code that requires new kinds of test data, extend openairclim/utils/create_test_data.py (the underlying dataset builders) and create_test_files.py (which writes them to disk) rather than creating new fixtures elsewhere.

Running the test suite

First, run create-test-files as described above, so that the test fixtures are generated. Then use one of the following commands to run the tests.

With pixi:

pixi run -e dev test

Without pixi:

pytest tests/

Tests are named *_test.py and mirror the openairclim source tree 1:1, e.g. tests/gui/tabs/scenario_test.py tests openairclim/gui/tabs/scenario.py.

Downloading repository data

Unlike the test suite, actually running OpenAirClim (e.g. the bundled example, the demo notebooks, or manual testing) requires the real response surface and background concentration data. This works exactly as for users - see Downloading repository data - and is not required just to develop or test code.

Building the documentation

The docs extra (included by default with the pixi/conda commands above, or via pip install -e ".[docs]") installs Sphinx and the theme/extensions this site uses. Build it locally with:

pixi run -e docs docs-build

# or, without pixi:
sphinx-build -M html docs/source docs/build

To remove a previous build (e.g. to force a full rebuild):

pixi run -e docs docs-clean

# or, without pixi:
sphinx-build -M clean docs/source docs/build

Open docs/build/html/index.html in a browser to view it. The demonstration notebooks under docs/source/demos are MyST Markdown notebooks executed by myst_nb, not covered by pytest - verify any change touching file resolution in those notebooks with an actual docs build, not just the test suite. Execution is cached and only reruns when a notebook’s content changes.

Running code quality checks

Pull requests are checked with Black and Prospector. With pixi, run them against the whole openairclim/tests trees:

pixi run -e dev style        # black --check + full prospector report
pixi run -e dev correctness  # faster pyflakes+mypy subset (the required check)

pixi run -e dev black         # reformats in place, not just --check

Note the pixi tasks always lint the full openairclim/tests trees.

You can also run the underlying tools directly (without pixi), e.g. against just your changed files:

black --check --diff <changed files>
prospector <changed files>

# or, the faster subset which is part of the lint.yml workflow
prospector --tool pyflakes --tool mypy -s medium <changed files>