Tutorials for users
===================

All tutorials assume that you already have successfully :doc:`installed</installation>` pyCIF.

.. tip::

    **Running examples with Docker**

    All YAML examples listed in :doc:`/yaml-examples/index` are run automatically by the CI pipeline.
    To reproduce them locally:

    1. Pull the pyCIF Docker image (see the :doc:`installation guide</installation>`).
    2. Download the reference test data (the CI pipeline fetches it via ``gitlab-ci.yml``).
    3. Pick a YAML file from :doc:`/yaml-examples/index`, adjust ``rootdir`` and ``outdir`` to match your paths, and run::

           python -m pycif path/to/your_config.yml

    The :doc:`CHIMERE ready-made tutorial<first-simu-readymade/index>` walks through this workflow step by step.

Tutorials by model
------------------

.. toctree::
    :maxdepth: 1

    chimere_tutos/index
    lmdz_tutos/index


Tutorials by theme
------------------

.. toctree::
    :maxdepth: 1

    first-simu-readymade/index
    first-simu/index
    first-comp-to-obs/index
    first-inversion/index
    elaborated-inputs/index
    superobs
    testing-codes/index
    further-inversions/index
    further-simus/index
    response-functions/index
    using-transforms/index
    post-processing/index
    autocompletion

..
    XXX TODO: document how to run CHIMERE manually from $WORKDIR using run.py.
    Steps to cover:
    - reload the necessary environment modules (``module load …``)
    - set the number of MPI processes from the namelist (``nzdoms * nmdoms + 1``)
    - launch with ``mpirun "run_options" -np $NBPROC chimere.e``
      where ``run_options`` in ``__init__.py`` is
      ``--oversubscribe -mca btl self,sm,tcp``
    - ``$NBPROC`` must match the value ``nzdoms * nmdoms + 1`` in ``chimere.nml``