#####################################
How to run TL and adjoint tests
#####################################

This page explains how to test the tangent-linear (TL) and adjoint codes of models driven by pyCIF.
The tests verify the mathematical consistency of the TL/adjoint operators
and should be run before any inversion.
For background on inversions, see :doc:`the first inversion tutorials</usertutos/first-inversion/index>`.

The simplest approach is to start from an existing inversion YAML and change only the
:doc:`mode</documentation/plugins/modes/index>` block and the ``workdir``.

Ready-made YAML examples
------------------------

The CI pipeline provides ready-to-run adjoint-test configurations for several models.
Download one and adjust ``rootdir`` / ``outdir`` to your local paths.

**Toy Gaussian model** (no external data required):

* :doc:`Constant increments, full control space </yaml-examples/dummy/config_adjtltest_long_full_cst-incr_control-testspace_fullperiod>`
* :doc:`Random increments, chi test space </yaml-examples/dummy/config_adjtltest_long_full_rand-incr_chi-testspace_fullperiod>`
* Many more variants available in :doc:`/yaml-examples/dummy/index`.

**CHIMERE** (requires reference test data):

Download both CHIMERE archives and extract them into the same directory:

.. code-block:: bash

    wget https://sharebox.lsce.ipsl.fr/index.php/s/zUpoUXODKFLZJrf/download -O data1.tar.gz
    wget https://sharebox.lsce.ipsl.fr/index.php/s/GgTDXL8peF4BOuV/download -O data2.tar.gz
    mkdir -p /tmp/PYCIF_DATA_TEST
    tar -xf data1.tar.gz -C /tmp/PYCIF_DATA_TEST
    tar -xf data2.tar.gz -C /tmp/PYCIF_DATA_TEST

Ready-to-run YAML examples (adjust ``rootdir`` and ``outdir`` after downloading):

* :doc:`Short simulation, constant increments, control space </yaml-examples/chimere/config_adjtltest_short_ref_chimere_cst-incr_control-testspace_fullperiod>`
* :doc:`Short simulation, random increments, chi space </yaml-examples/chimere/config_adjtltest_short_ref_chimere_rand-incr_chi-testspace_fullperiod>`
* Many more variants (EDGAR and MELCHIOR setups) available in :doc:`/yaml-examples/chimere/index`.

Adjoint test
-------------

The ``adj-tl_test`` mode checks that the adjoint satisfies the identity
:math:`\langle H x, y \rangle = \langle x, H^T y \rangle` up to machine precision.
Key options:

.. code-block:: yaml

    mode:
      plugin:
        name: adj-tl_test
        version: std
      increments: 0.2    # relative perturbation amplitude
      incrmode: cst      # 'cst' for constant, 'rand' for random increments
      testspace: control # 'control' or 'chi'

Run with:

.. code-block:: bash

    python -m pycif path/to/your_adjtltest_config.yml

A successful test prints a ratio close to 1.0 for the adjoint identity check.

TL test
-------

The TL test verifies that the tangent-linear operator is a consistent linearisation of the
non-linear forward operator. Use the same ``adj-tl_test`` mode as above;
the TL check is performed automatically alongside the adjoint check.