Quick Start

Quick Start#

This page walks you through running your first pyCIF simulation in a few minutes, using the built-in Toy Gaussian model — a lightweight analytical transport model that requires no external data or compiled code.

Tip

The fastest way to get started is with the CIF Docker image, which ships with all dependencies pre-installed. Pull it with:

docker pull pycif/pycif-ubuntu:latest

Then jump straight to Step 3 — Run pyCIF.

Step 1 — Install pyCIF#

If you have not installed pyCIF yet, follow the installation guide. The short version:

pip install --user pycif-*-py3-none-any.whl   # from a downloaded wheel

or directly from the repository:

git clone git@gitlab.in2p3.fr:satinv/cif.git
cd cif
pip install --user --editable .

Step 2 — Get the example configuration file#

Download the ready-made YAML configuration for the toy forward simulation:

config_fwd_long_noMCF.yml

Alternatively, browse it online: Configuration Forward Long Nomcf.

Open the file and set the two path variables near the top:

rootdir: &rootdir /path/to/cif/sources/   # where pyCIF is installed / cloned
outdir:  &outdir  /path/to/output/dir/    # where results will be written

Everything else is plug-and-play — no other edits are required for this first run.

Step 3 — Run pyCIF#

python -m pycif path/to/config_fwd_long_noMCF.yml

pyCIF will print progress to the terminal and write a log file (pycif.logtest) in outdir.

The simulation covers five days (2010-01-01 to 2010-01-05) with a Gaussian plume model, synthetic meteorology and five randomly placed observation stations. It completes in a few seconds on any modern laptop.

Step 4 — Explore the outputs#

Results are written to ${outdir}/fwd_long_noMCF/:

fwd_long_noMCF/
├── config_fwd_long_noMCF.yml   ← copy of the config used
├── pycif.logtest               ← full run log
├── VERSION                     ← git commit ID for reproducibility
├── controlvect/                ← control-vector data (correlation matrix, …)
├── datavect/
│   ├── fluxes/CH4/             ← input fluxes
│   └── meteo/                  ← synthetic meteorological fields
├── model/
│   └── H_matrix.pickle         ← saved observation operator matrix
└── obsoperator/
    └── fwd_0000/
        ├── obsvect/            ← simulated concentrations (monitor.nc)
        └── controlvect/        ← netCDF-format control vector snapshot

Open obsoperator/fwd_0000/obsvect/ to find monitor.nc files containing the simulated concentrations at each station.

Next steps#