Version 5 (modified by avidard, 11 years ago) (diff)

Last edited Timestamp?

Tangent Linear Validation


The tangent validation test checks that the Tangent Linear model L is a first order approximation of the model M. We can then write a second order Taylor expansion as follows:

M(X0+p.dX) = M(X0) + L(p.dX) + e


X0: initial state vector
dX: perturbation state vector
p: scale factor
e: residual 

when the factor p tends to zero we have:

-1- M(X0+p.dX) - M(X0) tends to L(p.dX)
-2- e is equivalent to O(p^2), means Norm(e,.) <= K.p^2 (with K a constant)

This means that for a given p0, for p smaller than p0 the error of the Linear Tangent with respect to the model is decreasing as p2.

First order validation

Let's note

Np = M(X0+p.dX) - M(X0)
Lp = L(p.dX)

the first order validation checks:

for a given p0, for all p>p0:
Ep = Norm(Np,.)/Norm(Lp,.) tends to 1

Second order validation

the second order validation ensure that the residu is controlled. We check then:

for a given p0, for all p>p0:
Rp = Norm(Np - Lp,.) behaves as p^2

note that we can also perform the following equivalent tests:

test expression behaviour
b Norm((Np - Lp)/Lp,.) p
c Norm((Ep - 1,.)/p constant
d Norm((Ep - Lp/(p.Lp),.) constant

Note that the second order test is not relevant if M is linear. L must be exact and this test will only give information on the actual machine error.


We need to compute Np, Lp, Ep and Rp for different value of p. It means that we need to run several time the model M. As we wish not to modify the model, multiple run of the model currently means launched several times the executable. A dedicate driver is developp to be able to run in the same executable the model M and its tangent L. This driver is used as soon as the the logicals ln_tst_tan (tangent test switch) and ln_tst (general test switch) are set to .true. in the namtst namelist. (we also have to choose between testing the main routine step or individual options, as for adjoint test, with ln_tst_tan_cpd (swith for testing individual options) set to .false. or .true.)


The test is built as follows:

Loop on p:
 * IF p=0:
  * Write to file M(X0)
 * ELSE:
  * compute p.dX
  * compute M(X0+p.dX), L(pdX)
  * read M(X0)
  * write to file Np, Lp, Ep and Rp
End Loop
Concatenate outputs files

How to Run the test

runnemo_tgt.ksh (only ORCA2_Z31 cfg) is a dedicated script to run tangent test of TAM. Basics options are:

  • t: defined working directory target
  • A: compiler setting base
  • j: direct trajectory file directory (default value is corresponding outer loop directory)
  • v: experiment target (= nemotam)
  • k: non-perturbated outputs directory
  • f: diagnostic files directory
  • note: for 'k' and 'f' options, you must indicate the relative path with respect to 't' option

Example: runnemo_tgt.ksh -t $mypath -A mycomp - j $traj -v nemotam -k $nopert -f $diag

  • non perturbated outputs is be saved into $mypath/$nopert directory
  • final diagnostic outputs is saved into $mypath/$diag directory


To run the some adjoint test we need the following features:

  • a direct trajectory (computed with NEMO)
  • additionnal namelist to rule loop number and actual p
    • namtst_tlm (tangent test parameter: see example in setup_tam_orca2)
  • runnemo_tgt.ksh script uses two short python codes ( and to save intermediate outputs and build-up the final outputs.


The outputs, located in $mypath/$diag/ directory, is called tan_diag.global_0000.

Test Pass Criteria

With the above notations, we focus on Ep and Rp.


All subroutines tested both criteria except for:

  • dynspg_flt: fails on Rp criteria, root cause under investigation
  • traadv_cen2: fails on the Rp criteria due to tangent approximation (not considering the volume finite part of the scheme).