.. _lmdz-first-simu-readymade:

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

This tutorial runs a forward simulation of
:doc:`LMDz-SACS</documentation/plugins/models/lmdz>` 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
:doc:`complete LMDz-SACS tutorial<../first-simu/lmdz-sacs/index>`.

.. contents::
   :local:

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

.. code-block:: bash

    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:

.. code-block:: bash

    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:

* :doc:`Short forward simulation — ACAD standard dynamics</yaml-examples/lmdz/config_fwd_short_setup_acad>`
  (CO₂, no chemistry, 2 months, Docker platform)

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:

.. code-block:: yaml

    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
======================

.. code-block:: bash

    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:

.. code-block:: bash

    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:

.. code-block:: text

    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 :doc:`testing-codes</usertutos/testing-codes/index>`.
  Use :doc:`this YAML</yaml-examples/lmdz/config_adjtltest_short_setup_acad_rand-incr_chi-testspace_fullperiod>`
  as a starting point.

* Switch to the CH₄ configuration with chemistry:
  :doc:`Forward short reference LMDZ</yaml-examples/lmdz/config_fwd_short_ref_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
  :doc:`complete LMDz-SACS tutorial<../first-simu/lmdz-sacs/index>`.

* All available LMDz YAML examples (forward, adjoint tests, multiple dynamics variants)
  are listed in :doc:`/yaml-examples/lmdz/index`.