First forward simulation with LMDz-SACS (ready-made files)

First forward simulation with LMDz-SACS (ready-made files)#

This tutorial runs a forward simulation of LMDz-SACS using the academic (ACAD) reference dataset — the same data used by the CI pipeline, so it is guaranteed to work. The ACAD setup uses a coarse 16×9×19 grid and a simple CO₂ tracer without chemistry, making it the fastest path to a first working simulation.

For a detailed description of every input file and configuration option, see the complete LMDz-SACS tutorial.

1. Download the reference data#

Two archives are required. Extract both into the same parent directory (/tmp/PYCIF_DATA_TEST/ below, adjust to your preference):

wget https://sharebox.lsce.ipsl.fr/index.php/s/Z0KBiONVQLCWHrV/download -O lmdz1.tar.gz
wget https://sharebox.lsce.ipsl.fr/index.php/s/oIemGgBNNbrq6mF/download -O lmdz2.tar.gz
mkdir -p /tmp/PYCIF_DATA_TEST/LMDZ
tar -xf lmdz1.tar.gz -C /tmp/PYCIF_DATA_TEST/LMDZ
tar -xf lmdz2.tar.gz -C /tmp/PYCIF_DATA_TEST/LMDZ

After extraction, /tmp/PYCIF_DATA_TEST/LMDZ/ should contain at least the ACAD/ subdirectory, which holds all input files for this tutorial.

2. Get the LMDz-SACS executable#

The ACAD YAML is configured with auto-recompile: true, so pyCIF will attempt to compile the model automatically from the sources in dir_sources. Set dir_sources to your local model_sources/DISPERSION_gch directory.

Alternatively, compile manually once:

cd model_sources/DISPERSION_gch
./compile_dispersion

This produces dispersion.e (~30 MB). Point fileexec in the YAML to its absolute path.

3. Download and adapt the YAML#

Download the ready-to-run YAML for the ACAD academic setup:

All paths in the YAML that reference /tmp/PYCIF_DATA_TEST/LMDZ/ACAD/ should already match if you used the default extraction directory above. Adjust the following variables to match your environment:

rootdir: &rootdir /path/to/CIF/          # root of the pyCIF source tree
outdir:  &outdir  /path/to/output/dir/   # where workdir subdirectories are created

model:
  fileexec: /path/to/dispersion.e        # compiled LMDz-SACS executable
  dir_sources: !join [*rootdir, /model_sources/DISPERSION_gch]

All other paths in the YAML already point to /tmp/PYCIF_DATA_TEST/LMDZ/ACAD/.

4. Run the simulation#

python -m pycif path/to/config_fwd_short_setup_acad.yml

If you are using the Docker image, mount your data and output directories into the container:

docker run --rm \
    -v /tmp/PYCIF_DATA_TEST:/tmp/PYCIF_DATA_TEST \
    -v /path/to/output:/path/to/output \
    pycif:latest python -m pycif path/to/config_fwd_short_setup_acad.yml

5. Check the outputs#

After a successful run, workdir (e.g. <outdir>/fwd_short_setup_acad/) contains:

workdir/
├── config_fwd_short_setup_acad.yml   copy of the YAML used for this run
├── pycif.logtest                      pyCIF log file
├── VERSION                            git commit used for this run
├── controlvect/                       control vector data
├── datavect/
│   ├── flux/CO2/                      CO₂ emission fluxes
│   ├── inicond/CO2/                   initial condition
│   └── meteo/                         mass-flux meteorological fields
├── model/                             model run directory
└── obsoperator/
    └── fwd_0000/
        ├── controlvect/               control vector snapshot
        └── obsvect/                   simulated concentrations at observation sites

Check that obsoperator/fwd_0000/obsvect/ is populated; this confirms that the forward simulation completed and the observation operator was applied.

6. Going further#

  • Run an adjoint test with the same data: see testing-codes. Use this YAML as a starting point.

  • Switch to the CH₄ configuration with chemistry: Forward short reference LMDZ uses the simple dataset (already downloaded above) with a 96×96×39 global grid.

  • For the full explanation of every YAML section and input file, see the complete LMDz-SACS tutorial.

  • All available LMDz YAML examples (forward, adjoint tests, multiple dynamics variants) are listed in Examples for LMDZ.