Last edited [[Timestamp]]
= ''' Tangent Linear Validation ''' =

[[PageOutline]]

== Principle ==
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
}}}
with,
{{{
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)
and
-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 p^2.

=== 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.

== Implementation ==

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

=== Process ===
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

== Requierements ==
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 (filesmove.py and diagmerge.py) to save intermediate outputs and build-up the final outputs.


== 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.

== Results ==
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).