How to run TL and adjoint tests

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 the first inversion tutorials.

The simplest approach is to start from an existing inversion YAML and change only the mode 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):

CHIMERE (requires reference test data):

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

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

Adjoint test#

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

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:

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.