Quickstart

This page gets you from a fresh Python environment to your first OpenAirClim simulation in a few minutes, using the example configuration and a set of randomly generated emission inventories. For installation alternatives, custom input data and everything else, see the User Guide.

Install OpenAirClim

Install OpenAirClim from PyPI with pip (Python 3.11 or later required). We recommend installing into a virtual environment rather than system-wide:

python -m venv .venv
source .venv/bin/activate  # for Windows: source .venv\Scripts\activate
pip install openairclim

or, with conda:

conda create --name oac python=3.14
conda activate oac
conda install openairclim

Both include everything needed to run the core model and the Graphical User Interface. See Installation for uv/pixi installs.

Download the repository data

OpenAirClim’s simulations require response surface and background concentration data, published independently of openairclim at dlr-pa/oac-data. With the environment activated (as above), fetch the data version matching your installed release into a shared, per-user cache with:

oac-download-data

This only needs to be run once per machine.

Get the example

Download example.toml into a new working directory, then generate the emission inventories it references:

cd path/to/working/directory
oac-create-artificial-inventories --output-dir input/

Run OpenAirClim

oac-run example.toml

(equivalently, python -m openairclim example.toml, or oac.run("example.toml") from within Python). Note that if there are any relative links in the config file (e.g. dir = "input/"), you must be in the right working directory, in this case the directory created above, for OpenAirClim to run successfully.

Look at the results

The example.toml config file defines the output directory as results/. In this folder, you can find:

  • example.nc - time series of emissions, concentrations, radiative forcing and temperature change for each species

  • example_metrics.nc - the requested climate metrics (AGWP, ATR, AGTP)

  • one PNG plot per species (e.g. example_CO2.png), since output.run_plots = true in the example configuration

Each of these carries embedded metadata (which config produced it, when, with which OpenAirClim version) - see Output data for how to use it to trace a result back to its configuration.

Next steps

  • Explore configurations and results interactively with the Graphical User Interface.

  • The User Guide covers the configuration file in full, building your own emission inventories and time evolutions, and the contrail module.

  • The Demonstrations walk through worked examples in more depth.