= Name and subject of the action

Last edition: '''[[Wikinfo(changed_ts)]]''' by '''[[Wikinfo(changed_by)]]'''

The PI is responsible to closely follow the progress of the action, 
and especially to contact NEMO project manager if 
the delay on preview (or review) are longer than the 2 weeks expected.

[[PageOutline(2, , inline)]]

== Summary

||=Action       || optimisation of the vertical scale factor e3 computation          ||
||=PI(S)        || Techene, Madec                                                 ||
||=Digest       || compute e3 on the fly from e3_0(:,:,:,Ktl) * ( 1 + ssh(:,:,Ktl) / h_0( :,: ) * mask( :,:,: ) instead of storing e3t/u/v/w/f... ||
||=Dependencies || If any                                                ||
||=Branch       || source:/NEMO/branches/2020/dev_r12377_KERNEL-06_techene_e3 ||
||=Previewer(s) || Madec, Chanut, Masson                                 ||
||=Reviewer(s)  || Madec                                                 ||
||=Ticket       || #2385                                                 ||

=== Description


The current e3[P] at P-point computation uses interpolation of the r3t 4D table at P = {u-, v-, w-, f-, uw-, vw-} points. This means 7 4D tables stored in memory. 
The proposed optimisation consists in computing e3[P](ji,jj,jk,Ktl) on the fly using the r3[P] = ssh[P] / h_0 and the e3[P]_0. r3[P] is a 2D table, then this means only 4 2D tables stored in memory.
z-tilde management is done through e3[P]_0 that may varies with time in the z-tilde case.
Asselin filter management is done recomputing r3[P] directly with the filtered ssh.


=== Implementation

{{{#!box width=35em help
Describe flow chart of the changes in the code. \\
List the Fortran modules and subroutines to be created/edited/deleted. \\
Detailed list of new variables to be defined (including namelists), \\
give for each the chosen name and description wrt coding rules.
}}}

Eventually, all the dom_vvl_interpol call are removed, each time e3 is called we use a substitute to replace e3 by e3_0 (1 + ssh / h_0). For backward compatibility a cpp key manages the use of the new version vs. the old version. We will duplicate modules such as step and domvvl into stepLF and domQE (QE stands for Quasi Eulerian) and create a subtitute module. 

Integrated in mid merge trunk. 

List the Fortran modules and subroutines to be created.
substitute.F90

''...''

=== Documentation updates

{{{#!box width=55em help
Using previous parts, define the main changes to be done in the NEMO literature 
(manuals, guide, web pages, …).
}}}

''...''

== Preview 

{{{#!box width=50em info
[[Include(wiki:Developers/DevProcess#preview_)]]
}}}

Step 1 : Check the error for e3t, e3w between the current way to compute e3 at T-, W-point and the proposed way to compute e3 at T-, W-point.
- prints added with no change in the results
Step 2 : First we change only the core routine in domvvl which should be changed into domQE.
- add new variables, duplicate step into steplf and domvvl into domQE
- change interpolation routines into scaling routines in domQE
Step 3 : Then we change the Asselin filtering routine indeed because water forcing are applied locally.
- change Asselin routines (maybe not required since e3 scale with vertical with JC modif)
Step 4 : Finally we remove the interpol routine in the whole code
- remove interpolating routine in all the code (AGRIF, OFF,...) 
- use a SUBSTITUTE when there are e3 CALL
- make some changes in step and domQE to have the whole thing consistent
jpjm1
''...''

== Tests

{{{#!box width=50em info
[[Include(wiki:Developers/DevProcess#tests)]]
}}}

''...''
We want to track and maybe explain the differences observed at every steps. 
Reference set up : For that we produce a reference data set with the trunk -r 12377 using the GYRE_PISCES configuration where top cpp_key has been removed. We run it on 120 time steps. The drag coefficient is zero. We XIOS output an averaged field every 5 days. 

Step 1 : We print MAXVAL of error between both way to compute the vertical scale factors at each time step, note that we cancelled forcing (in the r12377 revision it should not change anything since water forcings such as run off and emp scale with the vertical).

error between proposed and former way to compute vertical scale factors at time kt = 1, 120, 85
e3t (1)
0.0000000000000000
3999.6591076268369
4.54747350886E-013
e3t (2)
5.68434188608E-014
5.11590769747E-013
4.54747350886E-013
e3w
'''4.64477238892E-007
6.13657050507E-006
5.27333801869E-006'''
gde3w
1.81898940354E-012
2.72848410531E-012
2.72848410531E-012

QUESTION : Why do we have such an error on the e3w scale factors ? It is not consistent with machine accuracy error. It seems to be related to the e3w_0 computation. How do we compute e3w_0 ? 
OK SOLVED ! THIS IS A KIND OF ERROR IN THE CODE !!! DUE TO THE FACT THAT E3W_0(jk) != 0.5 * ( E3T_0(jk) + E3T_0(jk-1) )...


Step 2 : Change the code in domvvl turn into domqe. Duplicate step.F90 into steplf.F90 and call domqe routines inside.

We observe small errors but not errors at the truncature level as expected with the curent trunk version. This is due to the differences spotted above. 
WE CAN NO LONGER USE THE TRUNK PRODUCTION AS A REFERENCE... 


== Review

{{{#!box width=50em info
[[Include(wiki:Developers/DevProcess#review)]]
}}}

''...''