Test of the adjoint (adjtl_test
/ std
)¶
Description¶
This mode is dedicated to testing the adjoint of the observation operator for a given configuration setup.
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 setup are very high, it is possible to execute a adjoint test with a simplified setup (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: (mandatory)
Scale of the increments to do the test. The following equation is used: \(\delta x = \delta i \;.\; \sigma_\mathbf{x}\)
accepted type: <class ‘float’>
Optional arguments¶
incrmode: (optional): cst
Type of increments to use in the test.
accepted values:
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: (optional): control
Reference space to apply the test of the adjoint
accepted values:
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: (optional): adj
Which type of test to run
accepted values:
adj: The full test of the adjoint
tltaylor: Taylor test
tllinearity: Test the linearity of the tangent linear
reload_results: (optional): False
Reload results from previously compiled test. If True does not recomputed the tangentlinear and/or the adjoint
accepted type: <class ‘bool’>
random_seed: (optional): 0
Seed to use in the test of the adjoint for generating random numbers; used only with incrmode = rand
accepted type: <class ‘int’>
check_transforms: (optional): 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, subsimulation 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.accepted type: <class ‘bool’>
use_forward: (optional): False
Force using the forward model instead of the tangent linear. WARNING: this works only if the model is linear
accepted type: <class ‘bool’>
taylor_iter: (optional): 1
Number of iterations for the Taylor test
accepted type: <class ‘int’>
lambdalin: (optional): 0.1
Factor to use to perturb increments in the Taylor and linearity tests
accepted type: <class ‘float’>
Requirements¶
The current plugin requires the present plugins to run properly:
Requirement name 
Requirement type 
Explicit definition 
Any valid 
Default name 
Default version 

obsvect 
False 
True 
standard 
std 

controlvect 
True 
True 
standard 
std 

obsoperator 
True 
True 
standard 
std 
Yaml template¶
Please find below a template for a Yaml configuration:
1mode:
2 plugin:
3 name: adjtl_test
4 version: std
5 type: mode
6
7 # Mandatory arguments
8 increments: XXXXX
9
10 # Optional arguments
11 incrmode: XXXXX
12 testspace: XXXXX
13 testtype: XXXXX
14 reload_results: XXXXX
15 random_seed: XXXXX
16 check_transforms: XXXXX
17 use_forward: XXXXX
18 taylor_iter: XXXXX
19 lambdalin: XXXXX