= 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       || Common scheme for vertical penetration of visible light  (IMMERSE T5.2)      ||
||=PI(S)        || T. Lovato                                                 ||
||=Digest       || Develop a common scheme to treat light penetration along the water column     ||
||=Dependencies || If any                                                ||
||=Branch       || source:/NEMO/branches/2020/dev_r12985_TOP-04_IMMERSE_BGC_interface ||
||=Previewer(s) || M. Butenschön                                                 ||
||=Reviewer(s)  || M. Butenschön                                                  ||
||=Ticket       || #2489                                                ||

=== Description

{{{#!box width=55em
Implement a common interface to handle the propagation of visible light  within the water column layers, as also described in IMMERSE T5.2\\
}}}

''...''

=== Implementation

{{{#!box width=55em
Develop a standalone module to compute vertical light propagation {{{src/TOP/trcopt.F90}}}

This module will receive surface radiation (namely qsr) from OCE component and the 3D chlorophyll field from the coupled BGC model.
These data are needed to compute the light attenuation coefficients of each RGB wavelength and the module will return updated fields of '''photosynthetic active radiation (PAR)''' needed for \\
'''1)''' the BGC feedback toward ocean physics ({{{ln_qsr_bio}}} option) through the updated {{{etot3}}} 3D field,\\
'''2)''' vertical distribution of total PAR ({{{etot}}}) and, optionally, the PAR contribution for each wavelength needed to drive BGC models. \\

In the computation of PAR passed to BGC models, two different choices are provided in order to compute a) the light in the water cell '''center''' (as in PISCES) or b) the '''integral''' of light within the water cell (as in BFM or ERSEM). the {{{light_loc}}} flag will be used.

Also common diagnostic fields will be included for light at the euphotic depth, euphotic layer depth, and weighted broadband attenuation coefficient.

Finally, a dedicated namelist {{{nam_trcopt}}} is added to {{{namelist_top_ref}}}

}}}

''...''

=== Documentation updates

{{{#!box width=55em
Update description of light computation for BGC models and update namelist_top.
}}}

''...''

== Preview 

{{{#!box width=50em
The proposed code is a new functionality for the TOP interface that needs to be explicitly called by the coupled BGC model, so there are no interferences with existing NEMO code or configurations (some of the computations are also compatible with the PISCES model).

The changes proposed to the namelist_top are adequately supporting the functionality of the module.
}}}

''...''

== Tests
{{{ #!box width=50em 
'''Module development''' 
- [http://forge.ipsl.jussieu.fr/nemo/browser/NEMO/branches/2020/dev_r12985_TOP-04_IMMERSE_BGC_interface/src/TOP/trcopt.F90 trcopt.F90] module created within src/TOP folder
- add to {{{namelist_top_ref}}} specific namelist [http://forge.ipsl.jussieu.fr/nemo/browser/NEMO/branches/2020/dev_r12985_TOP-04_IMMERSE_BGC_interface/cfgs/SHARED/namelist_top_ref#L102 nam__trcopt]


The module allows to \\
- prescribe PAR conversion factor from external file\\
- set irradiance to PAR fixed conversion factor {{{parlux}}}\\
- select the type of light computation to be passed to BGC coupled models by setting the {{{light_loc}}} option to '''center''' (light in the middle of the water cell) and '''integral''' (light integrated over the water cell thickness)
- provide diagnostics for euphotic layer depth {{{heup}}} and weighted broadband attenuation coefficient {{{xeps}}}.

'''NOTE''' the two additional diagnostics ({{{heup}}}, {{{xeps}}}) were included under a new group named '''top_shared''' in [http://forge.ipsl.jussieu.fr/nemo/browser/NEMO/branches/2020/dev_r12985_TOP-04_IMMERSE_BGC_interface/cfgs/SHARED/field_def_nemo-oce.xml#L1000 field_def_nemo-oce.xml]


----


'''Module testing'''

In this case SETTE tests won’t provide adequate info as the module needs to be plugged to be active, so testing  was carried out by applying MY_SRC modifications to a new configuration based on ORCA2_ICE_PISCES to evaluate the module outcomes wrt existing code.
The following diff show changes that have to be applied to plug the module within a BGC model:

{{{p4zopt.F90}}}
{{{
19d18
<    USE trcopt, ONLY: trc_opt
88,97d86
<       call trc_opt(kt, knt, Kbb, Kmm, zchl3d, ze1, ze2, ze3)
<       IF( lk_iomput .AND.  knt == nrdttrc ) THEN
<          CALL iom_put( "etot3_trc" , etot3(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
<          CALL iom_put( "etot_trc" , etot(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
<          CALL iom_put( "ze1_trc" , ze1(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
<          CALL iom_put( "ze2_trc" , ze2(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
<          CALL iom_put( "ze3_trc" , ze3(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
<       ENDIF
<
<       !
245,251d233
<       ENDIF
<       IF( lk_iomput .AND.  knt == nrdttrc ) THEN
<          CALL iom_put( "etot3_pis" , etot3(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
<          CALL iom_put( "etot_pis" , etot(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
<          CALL iom_put( "ze1_pis" , ze1(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
<          CALL iom_put( "ze2_pis" , ze2(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
<          CALL iom_put( "ze3_pis" , ze3(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht

}}}

{{{trcini.F90}}}
{{{
27d26
<    USE trcopt          ! light module
75d73
<       CALL trc_opt_ini          ! Light module
298d295
<       USE trcopt        , ONLY:   trc_opt_alloc
308d304
<       ierr = ierr + trc_opt_alloc()
}}}

Here attached also the archive [http://forge.ipsl.jussieu.fr/nemo/attachment/wiki/2020WP/TOP-04_lovato_IMMERSE_BGC_interface/opt_ORCA2_ICE_PISCES.tgz opt_ORCA2_ICE_PISCES.tgz] with the configuration folder used for the verification (copy it to /cfgs and uncompress).
'''Note that test output fields are defined in the .xmls files contained in .tgz archive.'''

By using the default option {{{light_loc = 'center'}}} the difference in total PAR compared to the same PISCES parametrization after 1 year are close to the numerical NC float rounding (~5.e-15). Differences are mainly due to a slightly different sequence of math operations in the two schemes.

[[Image(etot_1year_surface_center_option.png, width=100%)]]

A comparison between the two options {{{light_loc = 'integral'}}}-{{{light_loc = 'center'}}} indicated that the light integration over the water cell thickness provides, as expected, slightly higher values. Clearly longer comparison will deviate due to the feedback loop between the light and chla from phytoplankton.

[[Image(etot_surface_diff_integral-central.png, width=100%)]]



}}}

''...''

== Review

{{{#!box width=50em
'''Assessments:'''
* Is the proposed methodology now implemented? YES
* Are the code changes in agreement with the flowchart defined at preview step? YES
* Are the code changes in agreement with the list of routines and variables as proposed at preview step? YES
* Is the in-line documentation accurate and sufficient? YES
* Do the code changes comply with NEMO coding standards? YES
* Is the development documented with sufficient details for others to understand the impact of the change? YES

Given these assessments, this development can now be accepted for integration within NEMO.
}}}

''...''