Test of the adjoint adj-tl_test/std

Description

This mode is dedicated to testing the adjoint of the observation operator for a given configuration set-up.

For every inversion case study, it is necessary to compute a test of the adjoint before running a full variational inversion. It allows to detect any error specific to your test case and that were never met before. If the computation costs of the inversion set-up are very high, it is possible to execute a adjoint test with a simplified set-up (e.g. with a shorter period), but it is important to include configurations that can generate errors (month of February, several months/years in a row, etc.).

This test consists in checking that: \(\langle \mathcal{H}(\delta \mathbf{x}) \vert \mathcal{H}(\delta \mathbf{x}) \rangle = \langle \delta \mathbf{x} \vert \mathcal{H}^* \circ \mathcal{H}(\delta \mathbf{x}) \rangle\).

\(\mathcal{H}(\delta \mathbf{x})\) is computed with the tangent linear model, and then \(\mathcal{H}^*\circ \mathcal{H}(\delta \mathbf{x})\) is calculated with the adjoint.

In principle, the two terms of the equation are never exactly equal. Nevertheless, the difference should never exceed several times the machine accuracy.

YAML arguments

The following arguments are used to configure the plugin. pyCIF will return an exception at the initialization if mandatory arguments are not specified, or if any argument does not fit accepted values or type:

Mandatory arguments

increments : float, mandatory

Scale of the increments to do the test. The following equation is used: \(\delta x = \delta i \;.\; \sigma_\mathbf{x}\)

Optional arguments

incrmode : “cst” or “rand”, optional, default “cst”

Type of increments to use in the test.

• “cst”: Increments are the same for all dimensions of the control vector

• “rand”: Increments are selected randomly with a Normal distribution centered to zero with standard deviation ${increments}

testspace : “control” or “chi”, optional, default “control”

Reference space to apply the test of the adjoint

• “control”: The test is applied in the control space

• “chi”: The test is applied is the reduction \(\chi\) space; this includes multiplication by the square root of the matrix \(\mathbf{B}\); it is recommended to do this test before an inversion using error correlations

testtype : “adj” or “tltaylor” or “tllinearity”, optional, default “adj”

Which type of test to run

• “adj”: The full test of the adjoint

• “tltaylor”: Taylor test

• “tllinearity”: Test the linearity of the tangent linear

reload_results : bool, optional, default False

Reload results from previously compiled test. If True does not recomputed the tangent-linear and/or the adjoint

random_seed : int, optional, default 0

Seed to use in the test of the adjoint for generating random numbers; used only with incrmode = rand

check_transforms : bool, optional, default False

Check whether individual transformation pass the test of the adjoint. Transformations are printed out in the order they are run in forward.

For each transformation, the output reads as follows:

transformation_ID, transformation_name, sub-simulation date: \(\langle \mathcal{H}(\delta \mathbf{x}) \vert \mathcal{H}(\delta \mathbf{x}) \rangle\) / \(\langle \delta \mathbf{x} \vert \mathcal{H}^* \circ \mathcal{H}(\delta \mathbf{x}) \rangle\)

The output is printed out both in the main pyCIF log file and in a dedicated file check_transforms.log in your work directory.

use_forward : bool, optional, default False

Force using the forward model instead of the tangent linear. WARNING: this works only if the model is linear

taylor_iter : int, optional, default 1

Number of iterations for the Taylor test

lambdalin : float, optional, default 0.1

Factor to use to perturb increments in the Taylor and linearity tests

Requirements

The current plugin requires the present plugins to run properly:

Requirement name	Requirement type	Explicit definition	Any valid	Default name	Default version
obsvect	ObsVect	False	True	standard	std
controlvect	ControlVect	True	True	standard	std
obsoperator	ObsOperator	True	True	standard	std

YAML template

Please find below a template for a YAML configuration:

mode:
  plugin:
    name: adj-tl_test
    version: std
    type: mode

  # Mandatory arguments
  increments: XXXXX  # float

  # Optional arguments
  incrmode: XXXXX  # cst|rand
  testspace: XXXXX  # control|chi
  testtype: XXXXX  # adj|tltaylor|tllinearity
  reload_results: XXXXX  # bool
  random_seed: XXXXX  # int
  check_transforms: XXXXX  # bool
  use_forward: XXXXX  # bool
  taylor_iter: XXXXX  # int
  lambdalin: XXXXX  # float