Changeset 14929

Timestamp:

2021-05-31T10:57:04+02:00 (3 years ago)

Author:

rlod

Message:

Finalization of TOP documentation: 2020 shared action, https://forge.ipsl.jussieu.fr/nemo/wiki/2020WP/PUB-02_Ethe_TOP_DOC, C. Ethe & R. Person, thanks to O. Aumont

Location:

NEMO/trunk/doc/latex/TOP

Files:

• main/abstract.tex (modified) (1 diff)
• main/authors.tex (modified) (1 diff)
• main/bibliography.bib (modified) (4 diffs)
• main/introduction.tex (modified) (2 diffs)
• subfiles/miscellaneous.tex (modified) (3 diffs)
• subfiles/model_description.tex (modified) (27 diffs)
• subfiles/model_setup.tex (modified) (2 diffs)

NEMO/trunk/doc/latex/TOP/main/abstract.tex

@@ -24 +24 @@
 it includes different sub-modules: ocean water age, inorganic carbon (CFCs) \& radiocarbon (C14b),
 built-in biogeochemical model (PISCES), and prototype for user-defined cases or
-coupling with alternative biogeochemical models (\eg \href{http://www.bfm-community.eu}{BFM}).
+coupling with alternative biogeochemical models (\eg, \href{http://www.bfm-community.eu}{BFM}).

NEMO/trunk/doc/latex/TOP/main/authors.tex

@@ -5 +5 @@
 Georges Nurser         \\
 Julien Palmi\'{e}ri    \\
+Renaud Person    \\
 Andrew Yool

NEMO/trunk/doc/latex/TOP/main/bibliography.bib

@@ -187 +187 @@
 }
 
+@article{         getzlaff_2013,
+  author        = {Getzlaff, Julia and Dietze, Heiner},
+  title         = {Effects of increased isopycnal diffusivity
+                  mimicking the unresolved equatorial intermediate
+                  current system in an earth system climate model},
+  year          = {2013},
+  volume        = {40},
+  number        = {10},
+  pages         = {2166--2170},
+  doi           = {10.1002/grl.50419},
+  url           = {https://dx.doi.org/10.1002/grl.50419},
+  journal       = {Geophysical Research Letters},
+  publisher     = {Wiley Online Library}
+}
+
 @techreport{      gibson_trpt86,
   title         = "Standards for software development and maintenance",
@@ -271 +286 @@
   journal   = {Limnology and Oceanography},
   publisher = {Wiley}
+}
+
+@Article{         mathiot_explicit_2017,
+  author        = {Mathiot, Pierre and Jenkins, Adrian and Harris, Christopher 
+                  and Madec, Gurvan},
+  title         = {Explicit representation and parametrised impacts of under 
+                  ice shelf seas in the z∗ coordinate ocean model {NEMO} 3.6},
+  year          = {2017},
+  volume        = {10},
+  number        = {7},
+  month         = jul,
+  pages         = {2849--2874},
+  issn          = {1991-9603},
+  doi           = {10.5194/gmd-10-2849-2017},
+  url           = {https://www.geosci-model-dev.net/10/2849/2017/},
+  journal       = {Geoscientific Model Development},
+  publisher = {Copernicus GmbH}
 }
 
@@ -448 +480 @@
 }
 
+@Article{         person_sensitivity_2019,
+  author        = {Person, Renaud and Aumont, Olivier and Madec, Gurvan and 
+                   Vancoppenolle, Martin and Bopp, Laurent and Merino, Nacho},
+  title         = {Sensitivity of ocean biogeochemistry to the iron supply from the 
+                  {Antarctic} {Ice} {Sheet} explored with a biogeochemical model},
+  year          = {2019},
+  volume        = {16},
+  number        = {18},
+  month         = sep,
+  pages         = {3583--3603},
+  issn          = {1726-4189},
+  doi           = {10.5194/bg-16-3583-2019},
+  url           = {https://www.biogeosciences.net/16/3583/2019/},
+  journal       = {Biogeosciences},
+  publisher = {Copernicus GmbH}
+}
+
 @Article{     reimer_2013,
   author = {Reimer, Paula J and Bard, Edouard and Bayliss, Alex and
@@ -630 +679 @@
   publisher = {Elsevier BV}
 }
+
+

NEMO/trunk/doc/latex/TOP/main/introduction.tex

@@ -11 +11 @@
 \begin{itemize}
         \item a transport code TRP sharing the same advection/diffusion routines with the dynamics, with specific treatment of some features like the surface boundary
-conditions, or the positivity of passive tracers concentrations
+conditions or the positivity of passive tracers concentrations
         \item sources and sinks - SMS - models that can be typically biogeochemical, biological or radioactive
-        \item an offline option which is a simplified OPA 9 model using fields of physics variables that are previously stored to disk
+        \item an offline option which is a simplified OPA 9 model using fields of physical variables that were previously stored on disk
 \end{itemize}
 
-There is two ways of coupling TOP to the dynamics :
+There are two ways of coupling TOP to the dynamics :
 
 \begin{itemize}
         \item \textit{online coupling} : the evolution of passive tracers is computed along with the dynamics
-        \item \textit{offline coupling} : the fields of physics variables are read from files and interpolated at each model time step, with no constraints on the time sampling in the input files
+        \item \textit{offline coupling} : the physical variable fields are read from files and interpolated at each model time step, with no constraints on the temporal sampling in the input files
 \end{itemize}
 
-TOP is designed to handle multiple oceanic tracers through a modular approach and it includes different sub-modules :
+TOP is designed to handle multiple oceanic tracers through a modular approach and includes different sub-modules :
 
 \begin{itemize}
         \item the ocean water age module (AGE) tracks down the time-dependent spread of surface waters into the ocean interior
-        \item inorganic carbon (e.g. CFCs, SF6) and radiocarbon (C14) passive tracers can be modeled to assess ocean absorption timescales of anthropogenic emissions and further address water masses ventilation
+        \item inorganic (\eg, CFCs, SF6) and radiocarbon (C14) passive tracers can be modeled to assess ocean absorption timescales of anthropogenic emissions and further address water masses ventilation
         \item a built-in biogeochemical model (PISCES) to simulate lower trophic levels ecosystem dynamics in the global ocean
-        \item a prototype tracer module (MY\_TRC) to enable user-defined cases or the coupling with alternative biogeochemical models ( e.g. BFM, MEDUSA, ERSEM, BFM, ECO3M)
+        \item a prototype tracer module (MY\_TRC) to enable user-defined cases or the coupling with alternative biogeochemical models (\eg, BFM, MEDUSA, ERSEM, BFM, ECO3M)
 \end{itemize}
 
@@ -36 +36 @@
 \vspace{0cm}
 \includegraphics[width=0.80\textwidth]{Fig_TOP_design}
-%\includegraphics[height=6cm,angle=-00]{Fig_TOP_design}
-\caption{A schematic view of NEMO-TOP component}
+\caption{Schematic view of the NEMO-TOP component}
 \label{topdesign}
 \end{center}

NEMO/trunk/doc/latex/TOP/subfiles/miscellaneous.tex

@@ -7 +7 @@
 \section{TOP synthetic Workflow}
 
-\subsection{Model initialization}
+A synthetic description of the TOP interface workflow is given below to summarize the steps involved in the computation of biogeochemical and physical trends and their time integration and outputs, by reporting also the principal Fortran subroutine herein involved.
 
-\subsection{Time marching procedure}
+%\begin{figure}[!h]
+%  \centering
+%  \includegraphics[width=0.80\textwidth]{Top_FlowChart}
+%  \caption{Schematic view of NEMO-TOP flowchart}
+%  \label{img_cfcatm}
+%\end{figure} 
+
+\begin{minted}{bash}
+nemogcm
+    !                      
+    nemo_init           !   NEMO General Initialisations
+         !                   
+         trc_init                              ! TOP  Initialisations 
+    !
+    stp()                   !   NEMO Time-stepping
+        !
+        trc_stp()                            ! TOP time-stepping
+            !
+            trc_wri()           ! I/O manager : Output of passive tracers 
+            trc_sms()           ! Sinks and sources program manager
+            trc_trp()            ! Transport of passive tracers
+            trc_rst_wri()      ! Write tracer restart file
+            trd_mxl_trc()     ! trends: Mixed-layer
+\end{minted}
+
+\subsection{Model initialization (./src/TOP/trcini.F90)}
+
+This module consists on inital set up of passive tracers variables and parameters  : read the namelist, set initial tracer fields (either read restart or read data or analytical formulation and  specific initailisation in each SMS module  ( analytical initialisation of tracers or constant values )
+
+\begin{minted}{bash}
+trc_init                              ! TOP  Initialisations 
+    !    
+    IF( PISCES )    trc_ini_pisces()     !  PISCES bio model
+    IF( MY_TRC)    trc_ini_my_trc()    !  MY_TRC model
+    IF( CFCs     )    trc_ini_cfc   ()       !  CFCs
+    IF( C14       )    trc_ini_c14   ()       !  C14 model
+    IF( AGE      )    trc_ini_age   ()       !  AGE tracer
+    !
+    IF( REST   )    trc_rst_read()         ! Restart from a file  
+    ELSE            trc_dta()                   ! Initialisation from data
+\end{minted}
+
+\subsection{BGC trends computation (./src/TOP/trcsms.F90)}
+
+This is the main module where the passive tracers source minus sinks of each TOP sub-module is managed.    
+
+\begin{minted}{bash}
+trc_sms()                               ! Sinks and sources prooram manager
+    ! 
+    IF( PISCES  )    trc_sms_pisces()         ! main program of PISCES 
+    IF( CFCs     )    trc_sms_cfc()               ! surface fluxes of CFC
+    IF( C14       )    trc_sms_c14()               ! surface fluxes of C14
+    IF( AGE       )    trc_sms_age()              ! Age tracer
+    IF( MY_TRC)    trc_sms_my_trc()         ! MY_TRC  tracers
+\end{minted}
+
+\subsection{Physical trends computation (./src/TOP/TRP/trctrp.F90)}
+
+This is the main module where the passive tracers transport is managed. All the physical trends is calculated ( advective \& diffusive trends, surface BC from freshwater or external inputs ) 
+
+\begin{minted}{bash}
+trc_trp()       ! Transport of passive tracers
+    !
+    trc_sbc()         ! Surface boundary condition of freshwater flux
+    trc_bc()           ! Surface and lateral Boundary Conditions 
+    trc_ais()          ! Tracers from Antarctic Ice Sheet (icb, isf)               
+    trc_bbl()          ! Advective (and/or diffusive) bottom boundary layer scheme
+    trc_dmp()        ! Internal damping trends
+    trc_bdy()         ! BDY damping trends
+    trc_adv()         ! Horizontal & Vertical advection 
+    trc_ldf()           ! Lateral mixing
+    trc_zdf()          ! Vert. mixing & after tracer
+    trc_atf()           ! Time filtering of "now" tracer fields    
+    trc_rad()         ! Correct artificial negative concentrations
+\end{minted}
+
+\subsection{Outputs  (./src/TOP/TRP/trcwri.F90)}
+
+This is the main module where the passive tracer outputs of each TOP sub-module is managed using the I/O library XIOS.
+
+\begin{minted}{bash}
+trc_wri()                               ! I/O manager : Output of passive tracers 
+!
+IF( PISCES   )    trc_wri_pisces()      ! Output of PISCES diagnostics 
+IF( CFCs      )    trc_wri_cfc()            ! Output of Cfcs diagnostics
+IF( C14         )    trc_wri_c14()           ! surface fluxes of C14
+IF( AGE        )    trc_wri_age()           ! Age tracer
+IF( MY_TRC )    trc_wri_my_trc()      ! MY_TRC  tracers
+\end{minted}
 
 \section{Coupling an external BGC model using NEMO framework}
@@ -27 +115 @@
 \end{minted}
 
-the compilation with \textit{makenemo} will be executed through the following syntax
+The compilation with \textit{makenemo} will be executed through the following syntax
 
 \begin{minted}{bash}
    makenemo -n NEMO_MYBGC -m <arch_my_machine> -j 8 -e <MYBGCPATH>
 \end{minted}
-%The makenemo feature ?-e? was introduced to readdress at compilation time the standard MY_SRC folder (usually found in NEMO configurations) with a user defined external one.
-%
-%
-%The compilation of more articulated BGC model code & infrastructure, like in the case of BFM (?BFM-NEMO coupling manual), requires some additional features.
-%
-%As before, let?s assume a coupled configuration name NEMO_MYBGC, but in this case MYBGC model root becomes <MYBGCPATH> that contains 4 different subfolders for biogeochemistry, named initialization, pelagic, and benthic, and a separate one named nemo_coupling including the modified MY_SRC routines. The latter folder containing the modified NEMO coupling interface will be still linked using the makenemo ?-e? option.
-%
-%In order to include the BGC model subfolders in the compilation of NEMO code, it will be necessary to extend the configuration cpp_NEMO_MYBGC.fcm file to include the specific paths of MYBGC folders, as in the following example
-%
+
+The makenemo feature \textit{-e} was introduced to readdress at compilation time the standard MY\_SRC folder (usually found in NEMO configurations) with a user defined external one. \\ \\
+
+The compilation of more articulated BGC model code \& infrastructure, like in the case of BFM (BFM-NEMO coupling manual), requires some additional features. \\ \\
+
+As before, let's assume a coupled configuration name NEMO\_MYBGC, but in this case MYBGC model root becomes <MYBGCPATH> that contains 4 different subfolders for biogeochemistry, named initialization, pelagic, and benthic, and a separate one named nemo\_coupling including the modified MY\_SRC routines. The latter folder containing the modified NEMO coupling interface will be still linked using the makenemo \textit{-e} option. \\ \\
+
+In order to include the BGC model subfolders in the compilation of NEMO code, it will be necessary to extend the configuration \textit{cpp\_NEMO\_MYBGC.fcm} file to include the specific paths of MYBGC folders, as in the following example
+
 \begin{minted}{bash}
    bld::tool::fppkeys   key_xios key_top
@@ -49 +137 @@
 
    bld::pp::MYBGC      1
-   bld::tool::fppflags::MYBGC   %FPPFLAGS
-   bld::tool::fppkeys   %bld::tool::fppkeys MYBGC_MACROS
+   bld::tool::fppflags::MYBGC   \%FPPFLAGS
+   bld::tool::fppkeys                  \%bld::tool::fppkeys MYBGC_MACROS
 \end{minted}
 
-%where MYBGC_MACROS is the space delimited list of macros used in MYBGC model for selecting/excluding specific parts of the code. The BGC model code will be preprocessed in the configuration BLD folder as for NEMO, but with an independent path, like NEMO_MYBGC/BLD/MYBGC/<subforlders>.
-%
-%The compilation will be performed similarly to in the previous case with the following
-%
-%makenemo -n NEMO_MYBGC -m <arch_my_machine> -j 8 -e <MYBGCPATH>/nemo_coupling
-%Note that, the additional lines specific for the BGC model source and build paths, can be written into a separate file, e.g. named MYBGC.fcm, and then simply included in the cpp_NEMO_MYBGC.fcm as follow
-%
-%bld::tool::fppkeys  key_zdftke key_dynspg_ts key_xios key_top
-%inc <MYBGCPATH>/MYBGC.fcm
-%This will enable a more portable compilation structure for all MYBGC related configurations.
-%
-%Important: the coupling interface contained in nemo_coupling cannot be added using the FCM syntax, as the same files already exists in NEMO and they are overridden only with the readdressing of MY_SRC contents to avoid compilation conflicts due to duplicate routines.
-%
-%All modifications illustrated above, can be easily implemented using shell or python scripting to edit the NEMO configuration cpp.fcm file and to create the BGC model specific FCM compilation file with code paths.
+where MYBGC\_MACROS is the space delimited list of macros used in MYBGC model for selecting/excluding specific parts of the code. The BGC model code will be preprocessed in the configuration BLD folder as for NEMO, but with an independent path, like NEMO\_MYBGC/BLD/MYBGC/<subfolders>.\\
+
+The compilation will be performed similarly to in the previous case with the following
+
+\begin{minted}{bash}
+makenemo -n NEMO_MYBGC -m <arch_my_machine> -j 8 -e <MYBGCPATH>/nemo_coupling
+\end{minted}
+
+Note that, the additional lines specific for the BGC model source and build paths, can be written into a separate file, e.g. named MYBGC.fcm, and then simply included in the cpp\_NEMO\_MYBGC.fcm as follow:
+
+\begin{minted}{bash}
+bld::tool::fppkeys  key_zdftke key_dynspg_ts key_xios key_top
+inc <MYBGCPATH>/MYBGC.fcm
+\end{minted}
+
+This will enable a more portable compilation structure for all MYBGC related configurations.  \\ \\
+
+Important: the coupling interface contained in nemo\_coupling cannot be added using the FCM syntax, as the same files already exists in NEMO and they are overridden only with the readdressing of MY\_SRC contents to avoid compilation conflicts due to duplicate routines.  \\ \\
+
+All modifications illustrated above, can be easily implemented using shell or python scripting to edit the NEMO configuration cpp.fcm file and to create the BGC model specific FCM compilation file with code paths.
 
 \end{document}

NEMO/trunk/doc/latex/TOP/subfiles/model_description.tex

@@ -17 +17 @@
 \label{sec:Bas}
 
-The time evolution of any passive tracer $C$ follows the transport equation, which is similar to that of active tracer - temperature or salinity :
+The time evolution of any passive tracer $C$ is given by the transport equation, which is similar to that of active tracer - temperature or salinity :
 
 \begin{equation}
@@ -24 +24 @@
 \end{equation}
 
-where expressions of $D^{lC}$ and $D^{vC}$ depend on the choice for the lateral and vertical subgrid scale parameterizations, see equations 5.10 and 5.11 in \citep{nemo_manual}
-
-{S(C)} , the first term on the right hand side of \autoref{Eq_tracer}; is the SMS - Source Minus Sink - inherent to the tracer.
-In the case of biological tracer such as phytoplankton, {S(C)} is the balance between phytoplankton growth and its decay through mortality and grazing.
-In the case of a tracer comprising carbon,  {S(C)} accounts for gas exchange, river discharge, flux to the sediments, gravitational sinking and other biological processes.
-In the case of a radioactive tracer, {S(C)} is simply loss due to radioactive decay.
+where expressions of $D^{lC}$ and $D^{vC}$ depend on the choice for the lateral and vertical subgrid scale parameterizations (see Equations 5.10 and 5.11 in \cite{nemo_manual}).
+
+{S(C)}, the first term on the right hand side of \autoref{Eq_tracer}, is the SMS - Sources Minus Sinks - inherent to the tracer.
+In the case of a biological tracer such as phytoplankton, {S(C)} is the balance between phytoplankton growth and its loss through mortality and grazing.
+In the case of a tracer comprising carbon,  {S(C)} accounts for gas exchange, river discharge, flux to the sediments, gravitational sinking and other biogeochemical processes.
+In the case of a radioactive tracer, {S(C)} is simply the loss due to radioactive decay.
 
 The second term (within brackets) represents the advection of the tracer in the three directions.
@@ -36 +36 @@
 The third term  represents the change due to lateral diffusion.
 
-The fourth term is change due to vertical diffusion, parameterized as eddy diffusion to represent vertical turbulent fluxes :
+The fourth term denotes the change due to vertical diffusion, parameterized as eddy diffusion to represent vertical turbulent fluxes :
 
 \begin{equation}
@@ -43 +43 @@
 \end{equation}
 
-where $A^{vT}$ is the vertical eddy diffusivity coefficient of active tracers
+where $A^{vT}$ is the vertical eddy diffusivity coefficient of active tracers.
 
 \section{The NEMO-TOP interface}
 \label{sec:TopInt}
 
-TOP is the NEMO hardwired interface toward biogeochemical models and provide the physical constraints/boundaries for oceanic tracers.
+TOP is the NEMO hardwired interface toward biogeochemical models, which provides the physical constraints/boundaries for oceanic tracers.
 It consists of a modular framework to handle multiple ocean tracers, including also a variety of built-in modules.
 
-This component of the NEMO framework allows one to exploit available modules  and further develop a range of applications, spanning from the implementation of a dye passive tracer to evaluate dispersion processes (by means of MY\_TRC), track water masses age (AGE module), assess the ocean interior penetration of persistent chemical compounds (e.g., gases like CFC or even PCBs), up to the full set of equations involving marine biogeochemical cycles.
+This component of the NEMO framework allows one to exploit available modules  and further develop a range of applications, spanning from the implementation of a dye passive tracer to evaluate dispersion processes (by means of MY\_TRC), track water masses age (AGE module), assess the ocean interior penetration of persistent chemical compounds (e.g., gases like CFC or even PCBs), up to the full set of equations to simulate marine biogeochemical cycles.
 
 TOP interface has the following location in the code repository : \path{<repository>/src/TOP/}
@@ -60 +60 @@
 \begin{itemize}
         \item \textbf{TRP}           :    Interface to NEMO physical core for computing tracers transport
-        \item \textbf{CFC}     :    Inert carbon tracers (CFC11,CFC12, SF6)
+        \item \textbf{CFC}     :    Inert tracers (CFC11,CFC12, SF6)
         \item \textbf{C14}     :    Radiocarbon passive tracer
         \item \textbf{AGE}     :    Water age tracking
         \item \textbf{MY\_TRC}  :   Template for creation of new modules and external BGC models coupling
-        \item \textbf{PISCES}    :   Built in BGC model.
-See \citep{aumont_2015} for a throughout description.
+        \item \textbf{PISCES}    :   Built in BGC model. See \cite{aumont_2015} for a complete description
 \end{itemize}
 %  ----------------------------------------------------------
@@ -71 +70 @@
 \section{The transport component : TRP}
 
-The passive tracer transport component  shares the same advection/diffusion routines with the dynamics, with specific treatment of some features like the surface boundary conditions, or the positivity of passive tracers concentrations.
+The passive tracer transport component shares the same advection/diffusion routines with the dynamics, with specific treatment of some features like the surface boundary conditions, or the positivity of passive tracers concentrations.
 
 \subsection{Advection}
+
+The advection schemes used for the passive tracers are the same as those used for $T$ and $S$. They are described in section 5.1 of \cite{nemo_manual}.
+The choice of an advection scheme can be selected independently and can differ from the ones used for active tracers.
+This choice is made in \textit{namelist\_to}p (ref or cfg) in the namelist block \textit{namtrc\_adv}, by setting to \textit{true} one and only one of the logicals \textit{ln\_trcadv\_xxx}, the same way of what is done for dynamics.
+cen2, MUSCL2, and UBS are not \textit{positive} schemes meaning that negative values can appear in an initially strictly positive tracer field which is advected, implying that artificial extrema are permitted. Their use is not recommended for passive tracers.
+
 %------------------------------------------namtrc_adv----------------------------------------------------
 \nlst{namtrc_adv}
-%-------------------------------------------------------------------------------------------------------------
-The advection schemes used for the passive tracers are the same than the ones for $T$ and $S$ and described in section 5.1 of \citep{nemo_manual}.
-The choice of an advection scheme  can be selected independently and  can differ from the ones used for active tracers.
-This choice is made in the \textit{namtrc\_adv} namelist, by  setting to \textit{true} one and only one of the logicals \textit{ln\_trcadv\_xxx}, the same way of what is done for dynamics.
-cen2, MUSCL2, and UBS are not \textit{positive} schemes meaning that negative values can appear in an initially strictly positive tracer field which is advected, implying that false extrema are permitted.
-Their use is not recommended on passive tracers
+%----------------------------------------------------------------------------------------------------------
 
 \subsection{Lateral diffusion}
+
+In NEMO v4.0, diffusion of passive tracers has necessarily the same form as the active tracer diffusion, meaning that the numerical scheme must be the same.
+However the passive tracer mixing coefficient can be chosen as a multiple of the active ones by changing the value of \textit{rn\_ldf\_multi} in namelist \textit{namtrc\_ldf}.
+The choice of the numerical scheme is then set in the \forcode{&namtra_ldf} namelist section for the dynamic described in section 5.2 of \cite{nemo_manual}.
+
+rn\_fact\_lap is a factor used to increase zonal equatorial diffusion for depths beyond 200 m. It can be useful to achieve a better representation of Oxygen Minimum Zone (OMZ) in some biogeochemical models, especially at coarse resolution \citep{getzlaff_2013}.
+
 %------------------------------------------namtrc_ldf----------------------------------------------------
 \nlst{namtrc_ldf}
-%-------------------------------------------------------------------------------------------------------------
-In NEMO v4.0, the passive tracer diffusion has necessarily the same form as the active tracer diffusion, meaning that the numerical scheme must be the same.
-However the passive tracer mixing coefficient can be chosen as a multiple of the active ones by changing the value of \textit{rn\_ldf\_multi} in namelist \textit{namtrc\_ldf}.
-The choice of numerical scheme is then set in the \forcode{&namtra_ldf} namelist for the dynamic described in section 5.2 of \citep{nemo_manual}.
+%---------------------------------------------------------------------------------------------------------
 
 %-----------------We also offers the possibility to increase zonal equatorial diffusion for passive tracers by introducing an enhanced zonal diffusivity coefficent in the equatorial domain which can be defined by the equation below :
@@ -98 +102 @@
 \subsection{Tracer damping}
 
+The use of newtonian damping  to climatological fields or observations is also coded, sharing the same routine as that of active tracers.
+Boolean variables are defined in the namelist\_top\_ref to select the tracers on which restoring is applied.
+Options are defined through the \textit{\&namtrc\_dmp} namelist variables.
+The restoring term is added when the namelist parameter \textit{ln\_trcdmp} is set to \textit{true}.
+The restoring coefficient is a three-dimensional array read in a file, whose name is specified by the namelist variable \textit{cn\_resto\_tr}.
+This netcdf file can be generated using the DMP\_TOOLS tool.
+
 %------------------------------------------namtrc_dmp----------------------------------------------------
 \nlst{namtrc_dmp}
-%-------------------------------------------------------------------------------------------------------------
-
-The use of newtonian damping  to climatological fields or observations is also coded, sharing the same routine dans active tracers.
-Boolean variables are defined in the namelist\_top\_ref to select the tracers on which restoring is applied
-Options are defined through the \nam{trc_dmp}{trc\_dmp} namelist variables.
-The restoring term is added when the namelist parameter \np{ln\_trcdmp} is set to true.
-The restoring coefficient is a three-dimensional array read in a file, which name is specified by the namelist variable \np{cn\_resto\_tr}.
-This netcdf file can be generated using the DMP\_TOOLS tool.
+%-----------------------------------------------------------------------------------------------------------
 
 \subsection{Tracer positivity}
+
+Some numerical schemes can generate negative values of passive tracers concentration, which is obviously unrealistic.
+For example,  isopycnal diffusion can created local extrema, meaning that negative concentrations can be generated.
+The trcrad routine artificially corrects negative concentrations with a very crude solution that either sets negative concentrations to zero without adjusting the tracer budget (CFCs or C14 chemical coumpounds), or by removing negative concentrations while computing the corresponding tracer content that is added and then, adjusting the tracer concentration using a multiplicative factor so that the total tracer concentration is preserved (PISCES model). 
+The treatment of negative concentrations is an option and can be selected in the namelist \textit{\&namtrc\_rad} by setting the parameter \textit{ln\_trcrad}  to true.
 
 %------------------------------------------namtrc_rad----------------------------------------------------
 \nlst{namtrc_rad}
-%-------------------------------------------------------------------------------------------------------------
-
-Sometimes, numerical scheme can generates negative values of passive tracers concentration that must be positive.
-For exemple,  isopycnal diffusion can created extrema.
-The trcrad routine artificially corrects negative concentrations with a very crude solution that either sets negative concentration to zero without adjusting the tracer budget, or by removing negative concentration and keeping mass conservation.
-The treatment of negative concentrations is an option and can be selected in the namelist \nam{trc_rad}{trc\_rad} by setting the parameter \np{ln\_trcrad}  to true.
+%----------------------------------------------------------------------------------------------------------
+
+\subsection{Tracer boundary conditions}
+
+In NEMO, different types of boundary conditions can be specified for biogeochemical tracers. For every single variable, it is possible to define a field of surface boundary conditions, such as deposition of dust or nitrogen, which is then interpolated to the grid and timestep using the fld\_read function. The same facility is available to include river inputs or coastal erosion (coastal boundary conditions) and the treatment of open boundary conditions. For lateral boundary conditions, spatial interpolation should not be activated.
+
+%------------------------------------------namtrc_bc----------------------------------------------------
+\nlst{namtrc_cfg}
+%---------------------------------------------------------------------------------------------------------
+
+\subsubsection{Surface and lateral boundaries}
+
+The namelist \textit{\&namtrc\_bc}  is in file \textit{namelist\_top\_cfg}  and allows to specify the name of the files, the frequency of the input and the time and space interpolation as done for any other field using the fld\_read interface.
+
+%------------------------------------------namtrc_bc----------------------------------------------------
+\nlst{namtrc_bc}
+%---------------------------------------------------------------------------------------------------------
+\subsubsection{Open boundaries}
+
+The BDY for passive tracer are set together with the physical oceanic variables (lnbdy  =.true.). Boundary conditions are set in the structure used to define the passive tracer properties in the « cbc » column. These boundary conditions are applied on the segments defined for the physical core of NEMO (see BDY description in the User Manual).
+\begin{itemize}
+   \item cn\_trc\_dflt : the type of OBC applied to all the tracers
+   \item cn\_trc :  the boundary condition used for tracers with data file
+\end{itemize} 
+
+%------------------------------------------namtrc_bdy----------------------------------------------------
+\nlst{namtrc_bdy}
+%----------------------------------------------------------------------------------------------------------
+
+\subsubsection{Sedimentation of particles}
+
+This module computes the vertical flux of particulate matter due to gravitational sinking. It also offers a temporary solution for the problem that may arise in specific situation where the CFL criterion is broken for vertical sedimentation of particles. To avoid this, a time splitting algorithm has been coded. The number of iterations niter necessary to respect the CFL criterion is dynamically computed. A specific maximum number of iterations nitermax may be specified in the namelist. This is to avoid a very large number of iterations when explicit free surface is used, for instance. If niter is larger than the prescribed nitermax, sinking speeds are clipped so that the CFL criterion is respected. The numerical scheme used to compute sedimentation is based on the MUSCL advection scheme.
+
+%------------------------------------------namtrc_bdy----------------------------------------------------
+\nlst{namtrc_snk}
+%----------------------------------------------------------------------------------------------------------
+
+\subsubsection{Sea-ice growth and melt effect}
+
+NEMO provides three options for the specification of tracer concentrations in sea ice: (-1) identical tracer concentrations in sea ice and ocean, which corresponds to no concentration/dilution effect upon ice growth and melt; (0) zero concentrations in sea ice, which gives the largest concentration-dilution effect upon ice growth and melt; (1) specified concentrations in sea ice, which gives a possibly more realistic effect of sea ice on tracers. Option (-1) and (0) work for all tracers, but (1) is currently only available for PISCES.
+
+%------------------------------------------namtrc_ice----------------------------------------------------
+\nlst{namtrc_ice}
+%---------------------------------------------------------------------------------------------------------
+
+\subsubsection{Antartic Ice Sheet tracer supply}
+
+The external input of biogeochemical tracers from the Antarctic Ice Sheet (AIS) is represented by associating a tracer content with the freshwater flux from icebergs and ice shelves \citep{person_sensitivity_2019}. This supply is currently implemented only for dissolved Fe (\autoref{img_icbisf}) and is effective in model configurations with south-extended grids (eORCA1 and eORCA025). As the ORCA2 grid does not extend south into Antarctica, the external source of tracers from the AIS cannot be enabled in this configuration. 
+
+For icebergs, a homogeneous distribution of biogeochemical tracers is applied from the surface to a depth that can be defined in \textit{\&namtrc\_ais}, currently set at 120 m. It should be noted that the freshwater flux from icebergs affects only the ocean properties at the surface. For ice shelves, biogeochemical tracers follow the explicit or parameterized representation of freshwater flux distribution modeled in NEMO. The AIS tracer supply is activated by setting \textit{ln\_trcais} to \textit{true} in the \textit{\&namtrc} section.
+
+\begin{figure}[!h]
+   \centering
+   \includegraphics[width=0.80\textwidth]{ICB-ISF-Feflx}
+   \caption{Annual Fe fluxes from icebergs and ice shelves in the Southern Ocean.}
+   \label{img_icbisf}
+\end{figure}
+
+%------------------------------------------namtrc_ais----------------------------------------------------
+\nlst{namtrc_ais}
+%---------------------------------------------------------------------------------------------------------
 
 \section{The SMS modules}
@@ -129 +193 @@
 \subsection{Ideal Age}
 %------------------------------------------namage----------------------------------------------------
-%
 \nlst{namage}
 %----------------------------------------------------------------------------------------------------------
 
 An `ideal age' tracer is integrated online in TOP when \textit{ln\_age} = \texttt{.true.} in namelist \textit{namtrc}.
-This tracer marks the length of time in units of years that fluid has spent in the interior of the ocean, insulated from exposure to the atmosphere.
+This tracer marks the duration in units of years that fluid has spent in the interior of the ocean, insulated from exposure to the atmosphere  (\autoref{img_ageatl} and \autoref{img_age200}).
+
+\begin{figure}[!h]
+   \centering
+   \includegraphics[width=0.80\textwidth]{Age_Atl}
+   \caption{Vertical distribution of the Age tracer in the Atlantic Ocean at 35°W from a 62-year simulation.}
+   \label{img_ageatl}
+\end{figure}
+
+\begin{figure}[!h]
+   \centering
+   \includegraphics[width=0.80\textwidth]{Age_200m}
+   \caption{Age tracer at 200 m depth from a 62-year simulation.}
+   \label{img_age200}
+\end{figure}
+
 Thus, away from the surface for $z<-H_{\mathrm{Age}}$ where $H_{\mathrm{Age}}$ is specified by the \textit{namage} namelist variable \textit{rn\_age\_depth}, whose default value is 10~m, there is a source $\mathrm{SMS_{\mathrm{Age}}}$ of the age tracer $A$:
 
@@ -151 +229 @@
 
 where the relaxation rate $\lambda_{\mathrm{Age}}$  (units $\mathrm{s}\;^{-1}$) is specified by the \textit{namage} namelist variable \textit{rn\_age\_kill\_rate} and has a default value of 1/7200~s.
-Since this relaxation is applied explicitly, this relaxation rate in principle should not exceed $1/\Delta t$, where $\Delta t$ is the time step used to step forward passive tracers (2 * \textit{nn\_dttrc * rn\_rdt} when the default  leapfrog time-stepping scheme is employed).
+Since this relaxation is applied explicitly, the relaxation rate should in principle not exceed $1/\Delta t$, where $\Delta t$ is the time step used to step forward passive tracers (2 * \textit{nn\_dttrc * rn\_rdt} when the default  leapfrog time-stepping scheme is employed).
 
 Currently the 1-dimensional reference depth of the grid boxes is used rather than the dynamically evolving depth to determine whether the age tracer is incremented or relaxed to zero.
-This means that the tracer only works correctly in z-coordinates.
-To ensure that the forcing is independent of the level thicknesses, where the tracer cell at level $k$ has its upper face $z=-depw(k)$ above the depth $-H_{\mathrm{Age}}$, but its lower face $z=-depw(k+1)$ below that depth, then the age source
+This means that the age tracer module only works correctly in z-coordinates.
+To ensure that the forcing is independent of the level thicknesses, where the tracer cell at level $k$ has its upper face $z=-depw(k)$ above the depth $-H_{\mathrm{Age}}$, but its lower face $z=-depw(k+1)$ below that depth, then the age source is computed as:
 
 \begin{equation}
@@ -169 +247 @@
 \end{align}
 
-
-This implementation was first used in the CORE-II intercomparison runs described e.g.\ in \citet{danabasoglu_2014}.
+This implementation was first used in the CORE-II intercomparison runs described in \citet{danabasoglu_2014}.
 
 \subsection{Inert carbons tracer}
@@ -184 +261 @@
 and additionally as an aerosol propellant.
 SF6 (SF$_{6}$) is also a gas at room temperature, with a range of applications based around its property as an excellent electrical insulator (often replacing more toxic alternatives).
-All three are relatively inert chemicals that are both non-toxic and non-flammable, and their wide use has led to their accumulation within the Earth's atmosphere.
-Large-scale production of CFC-11 and CFC-12 began in the 1930s, while production of SF6 began in the 1950s, and their atmospheric concentration time-histories are shown in Figure \autoref{img_cfcatm}.
-As can be seen in the figure, while the concentration of SF6 continues to rise to the present  day, the concentrations of both CFC-11 and CFC-12 have levelled off and declined since around the 1990s.
+All three gases are relatively inert chemicals that are both non-toxic and non-flammable, and their wide use has led to their accumulation in the atmosphere.
+Large-scale production of CFC-11 and CFC-12 began in the 1930s, while production of SF6 began in the 1950s, and the time-histories of their atmospheric concentrations are shown in Figure \autoref{img_cfcatm}.
+As can be seen in the figure, while the concentration of SF6 continues to rise to the present day, concentrations of both CFC-11 and CFC-12 have levelled off and declined since around the 1990s.
 These declines have been driven by the Montreal Protocol (effective since August 1989), which has banned the production of CFC-11 and CFC-12 (as well as other CFCs) because of their role in the depletion of
-stratospheric ozone (O$_{3}$), critical in decreasing the flux of ultraviolet radiation to the Earth's surface.
-Separate to this role in ozone-depletion, all three chemicals are significantly more potent greenhouse gases
+stratospheric ozone (O$_{3}$), critical in decreasing the flux of ultraviolet radiation to the Earth's surface. All three chemicals are also  significantly more potent greenhouse gases
 than CO$_{2}$ (especially SF6), although their relatively low atmospheric concentrations limit their role in climate change. \\
 
@@ -204 +280 @@
 The ocean is a notable sink for all three gases, and their relatively recent occurrence in the atmosphere, coupled to the ease of making high precision measurements of their dissolved concentrations, has made them
 valuable in oceanography. % for tracking interior ventilation and mixing.
-Because they only enter the ocean via surface air-sea exchange, and are almost completely chemically and biologically inert, their distribution within the ocean interior reveals its ventilation via transport and mixing.
-Measuring the dissolved concentrations of the gases -- as well as the mixing ratios between them -- shows circulation pathways within the ocean as well as water mass ages (i.e. the time since last contact with the
+Because they only enter the ocean via surface air-sea exchange, and are almost completely chemically and biologically inert, their distribution within the ocean interior reveals ventilation of the latter via transport and mixing.
+Measuring the dissolved concentrations of these gases -- as well as the mixing ratios between them -- shows circulation pathways within the ocean as well as water mass ages (i.e. the time since has been last in contact with the
 atmosphere).
-This feature of the gases has made them valuable across a wide range of oceanographic problems.
-One use lies in ocean modelling, where they can be used to evaluate the realism of the circulation and
-ventilation of models, key for understanding the behaviour of wider modelled marine biogeochemistry (e.g. \citep{dutay_2002,palmieri_2015}). \\
+This feature has made them valuable across a wide range of oceanographic problems.
+In ocean modelling, they can be used to evaluate the realism of the simulated circulation and
+ventilation patterns, which is key for understanding the behaviour of modelled marine biogeochemistry (e.g. \citep{dutay_2002,palmieri_2015}). \\
 
 Modelling these gases (henceforth CFCs) in NEMO is done within the passive tracer transport module, TOP, using the conservation state equation \autoref{Eq_tracer}
 
-Advection and diffusion of the CFCs in NEMO are calculated by the physical module, OPA,
+Advection and diffusion of the CFCs in NEMO are calculated by the physical module, TRP,
 whereas sources and sinks are done by the CFC module within TOP.
-The only source for CFCs in the ocean is via air-sea gas exchange at its surface, and since CFCs are generally
+The only source of CFCs to the ocean is via air-sea gas exchange at its surface, and since CFCs are generally
 stable within the ocean, we assume that there are no sinks (i.e. no loss processes) within the ocean interior.
 Consequently, the sinks-minus-sources term for CFCs consists only of their air-sea fluxes, $F_{cfc}$, as
@@ -233 +309 @@
 $C_{surf}$ is the local surface concentration of the CFC tracer within the model (in mol~m$^{-3}$);
 and $f_{i}$ is the fractional sea-ice cover of the local ocean (ranging between 0.0 for ice-free ocean,
-through to 1.0 for completely ice-covered ocean with no air-sea exchange).
+ to 1.0 for completely ice-covered ocean with no air-sea exchange).
 
 The saturation concentration of the CFC, $C_{sat}$, is calculated as follows:
@@ -312 +388 @@
 % AXY: consider an itemized list here if you've got a list of differences
 
-For instance, C$_{sat}$ is calculated for a fixed surface pressure of 1atm, what could be corrected in a further version of the module.
+For instance, C$_{sat}$ is calculated for a fixed surface pressure of 1atm. This may be corrected in a future version of the module.
 
 
@@ -333 +409 @@
 
 \begin{table}[!t]
-\caption{Coefficients for fit of the CFCs Schmidt number (Eq. \autoref{equ_Sc}). }
+\caption{Coefficients for fit of the CFCs Schmidt number (Eq. \autoref{equ_Sc}).}
 \vskip4mm
 \centering
@@ -384 +460 @@
 %----------------------------------------------------------------------------------------------------------
 
-The C14 package implemented in NEMO by Anne Mouchet models ocean $\Dcq$.
+The C14 package has been implemented in NEMO by Anne Mouchet $\Dcq$.
 It offers several possibilities: $\Dcq$ as a physical tracer of the ocean ventilation (natural $\cq$), assessment of bomb radiocarbon uptake, as well as transient studies of paleo-historical ocean radiocarbon distributions.
 
@@ -390 +466 @@
 
 Let  $\Rq$ represent the ratio of $\cq$ atoms to the total number of carbon atoms in the sample, i.e. $\cq/\mathrm{C}$.
-Then, radiocarbon anomalies are reported as
+Then, radiocarbon anomalies are reported as:
 
 \begin{equation}
@@ -397 +473 @@
 
 where $\Rq_{\textrm{ref}}$ is a reference ratio.
-For the purpose of ocean ventilation studies $\Rq_{\textrm{ref}}$ is set to one.
+For the purpose of ocean ventilation studies, $\Rq_{\textrm{ref}}$ is set to one.
 
 Here we adopt the approach of \cite{fiadeiro_1982} and \cite{toggweiler_1989a,toggweiler_1989b} in which  the ratio $\Rq$ is transported rather than the individual concentrations C and $\cq$.
@@ -464 +540 @@
 The radiocarbon decay rate (\forcode{rlam14}; in \texttt{trcnam\_c14} module) is set to $\lambda=(1/8267)$ yr$^{-1}$ \citep{stuiver_1977}, which corresponds to a half-life of 5730 yr.\\[1pt]
 %
-The Schmidt number $Sc$, Eq. \autoref{eq:wanc14}, is calculated with the help of the formulation of \cite{wanninkhof_2014}.
+The Schmidt number $Sc$, Eq. \autoref{eq:wanc14}, is calculated using the formulation of \cite{wanninkhof_2014}.
 The $\cd$ solubility $K_0$ in \autoref{eq:Rspeed} is taken from \cite{weiss_1974}. $K_0$ and $Sc$ are computed with the OGCM temperature and salinity fields (\texttt{trcsms\_c14} module).\\[1pt]
 %
@@ -522 +598 @@
 \end{figure}
 
-Performing this type of experiment requires that a pre-industrial equilibrium run be performed beforehand (\forcode{ln\_rsttr} should be set to \texttt{.TRUE.}).
-
-An exception to this rule is when wishing to perform a perturbation bomb experiment as was possible with the package \texttt{C14b}.
+Performing this type of experiment requires that a pre-industrial equilibrium run has been performed beforehand (\forcode{ln\_rsttr} should be set to \texttt{.TRUE.}).
+
+An exception to this rule is when performing a perturbation bomb experiment as was possible with the package \texttt{C14b}.
 It is still possible to easily set-up that type of transient experiment for which no previous run is needed.
-In addition to the instructions as given in this section it is however necessary to adapt the \texttt{atmc14.dat} file so that it does no longer contain any negative $\Dcq$ values (Suess effect in the pre-bomb period).
+In addition to the instructions given in this section, it is however necessary to adapt the \texttt{atmc14.dat} file so that it does no longer contain any negative $\Dcq$ values (Suess effect in the pre-bomb period).
 
 The model  is integrated from a given initial date following the observed records provided from 1765 AD on ( Fig. \autoref{fig:bomb}).
@@ -535 +611 @@
 Dates in these forcing files are expressed as yr AD.
 
-To ensure that the atmospheric forcing is applied properly as well as that output files contain consistent dates and inventories the experiment should be set up carefully:
+To ensure that the atmospheric forcing is applied properly as well as that output files contain consistent dates and inventories, the experiment should be set up carefully:
 
 \begin{itemize}
@@ -543 +619 @@
 \end{itemize}
 
-If the experiment date is outside the data time span then the first or last atmospheric concentrations are prescribed depending on whether the date is earlier or later.
-Note that \forcode{tyrc14\_beg} (\texttt{namelist\_c14}) is not used in this context.
+If the experiment date is outside the data time span, the first or last atmospheric concentrations are then prescribed depending on whether the date is earlier or later.
+   Note that \forcode{tyrc14\_beg} (\texttt{namelist\_c14}) is not used in this context.
 
 %
@@ -582 +658 @@
 
 All output fields in Table \autoref{tab:out} are routinely computed.
-It depends on the actual settings in \texttt{iodef.xml} whether they are stored or not.
+It depends on the actual settings in \texttt{iodef.xml} whether they are saved or not.
 %
 \begin{table}[!h]
@@ -645 +721 @@
 \subsection{PISCES biogeochemical model}
 
-PISCES is a biogeochemical model which simulates the lower trophic levels of marine ecosystem (phytoplankton, microzooplankton and mesozooplankton) and the biogeochemical cycles of carbonand of the main nutrients (P, N, Fe, and Si).
-The  model is intended to be used for both regional and global configurations at high or low spatial resolutions as well as for  short-term (seasonal, interannual) and long-term (climate change, paleoceanography) analyses.
+PISCES is a biogeochemical model that simulates the lower trophic levels of marine ecosystem (phytoplankton, microzooplankton, and mesozooplankton) and the biogeochemical cycles of carbon and of the main nutrients (P, N, Si, and Fe) (\autoref{img_piscesdesign} and \autoref{img_pisces}).
+
+\begin{figure}[ht]
+   \begin{center}
+      \vspace{0cm}
+      \includegraphics[width=0.80\textwidth]{Fig_PISCES_model}
+      \caption{Schematic view of the PISCES-v2 model (figure by Jorge Martinez-Rey).}
+      \label{img_piscesdesign}
+   \end{center}
+\end{figure}
+
+\begin{figure}[!h]
+   \centering
+   \includegraphics[width=0.80\textwidth]{PISCES_tracers}
+   \caption{Surface concentrations of NO$_{3}$, PO$_{4}$, total chlorophyll, and air-sea CO$_{2}$ flux from the last year of a 62-year simulation.}
+   \label{img_pisces}
+\end{figure}
+
+The  model is intended to be used for both regional and global configurations at high or low spatial resolutions as well as for short-term (seasonal, interannual) and long-term (climate change, paleoceanography) analyses. 
+
 Two versions of PISCES are available in NEMO v4.0 :
 
-PISCES-v2, by setting in namelist\_pisces\_ref  \np{ln\_p4z} to true,  can be seen as one of the many Monod models \citep{monod_1958}.
-It assumes a constant Redfield ratio and phytoplankton growth depends on the external concentration in nutrients.
-There are twenty-four prognostic variables (tracers) including two phytoplankton compartments  (diatoms and nanophytoplankton), two zooplankton size-classes (microzooplankton and  mesozooplankton) and a description of the carbonate chemistry.
-Formulations in PISCES-v2 are based on a mixed Monod/Quota formalism: On one hand, stoichiometry of C/N/P is fixed and growth rate of phytoplankton is limited by the external availability in N, P and Si.
-On the other hand, the iron and silicium quotas are variable and growth rate of phytoplankton is limited by the internal availability in Fe.
-Various parameterizations can be activated in PISCES-v2, setting for instance the complexity of iron chemistry or the description of particulate organic materials.
-
-PISCES-QUOTA has been built on the PISCES-v2 model described in \citet{aumont_2015}.
-PISCES-QUOTA has thirty-nine prognostic compartments.
-Phytoplankton growth can be controlled by five modeled limiting nutrients: Nitrate and Ammonium, Phosphate, Silicate and Iron.
-Five living compartments are represented: Three phytoplankton size classes/groups corresponding to picophytoplankton, nanophytoplankton and diatoms, and two zooplankton size classes which are microzooplankton and mesozooplankton.
-For phytoplankton, the prognostic variables are the carbon, nitrogen, phosphorus,  iron, chlorophyll and silicon biomasses (the latter only for diatoms).
-This means that the N/C, P/C, Fe/C and Chl/C ratios of both phytoplankton groups as well as the Si/C ratio of diatoms are prognostically predicted  by the model.
-Zooplankton are assumed to be strictly homeostatic \citep[e.g.,][]{sterner_2003,woods_2013,meunier_2014}.
-As a consequence, the C/N/P/Fe ratios of these groups are maintained constant and are not allowed to vary.
-In PISCES, the Redfield ratios C/N/P are set to 122/16/1 \citep{takahashi_1985} and the -O/C ratio is set to 1.34 \citep{kortzinger_2001}.
-No silicified zooplankton is assumed.
-The bacterial pool is not yet explicitly modeled.
+\begin{itemize}
+   \item PISCES-v2, by setting \textit{ln\_p4z} = \texttt{.true.} in \textit{namelist\_pisces\_ref}. This version can be seen as one of the many Monod models \citep{monod_1958}. It assumes a constant Redfield ratio and phytoplankton growth depends on the external concentration in nutrients. There are twenty-four prognostic variables (tracers) including two phytoplankton compartments  (diatoms and nanophytoplankton), two zooplankton size-classes (microzooplankton and  mesozooplankton) and a description of the carbonate chemistry. Formulations in PISCES-v2 are based on a mixed Monod/Quota formalism: On one hand, stoichiometry of C/N/P is fixed and growth rate of phytoplankton is limited by the external availability in N, P, and Si. On the other hand, the iron and silicium quotas are variable and growth rate of phytoplankton is limited by the internal availability in Fe. Various parameterizations can be activated in PISCES-v2, setting for instance the complexity of iron chemistry or the description of particulate organic materials.
+   
+   \item PISCES-QUOTA, by setting \textit{ln\_p5z} = \texttt{.true.} in \textit{namelist\_pisces\_ref}. This version has been built on the PISCES-v2 model described in \citet{aumont_2015}. PISCES-QUOTA has thirty-nine prognostic compartments. Phytoplankton growth is controlled by five modeled limiting nutrients: Nitrate and Ammonium, Phosphate, Silicate, and Iron. Five living compartments are represented: Three phytoplankton size classes/groups corresponding to picophytoplankton, nanophytoplankton, and diatoms, and two zooplankton size classes, which are microzooplankton and mesozooplankton. For phytoplankton, the prognostic variables are the carbon, nitrogen, phosphorus,  iron, chlorophyll and silicon biomasses (the latter only for diatoms). This means that the N/C, P/C, Fe/C, and Chl/C ratios of the three phytoplankton groups as well as the Si/C ratio of diatoms are prognostically predicted by the model. Zooplankton are assumed to be strictly homeostatic \citep[e.g.,][]{sterner_2003,woods_2013,meunier_2014}. As a consequence, the C/N/P/Fe ratios of these groups are maintained constant and are not allowed to vary. In PISCES, the Redfield ratios C/N/P are set to 122/16/1 \citep{takahashi_1985} and the -O/C ratio is set to 1.34 \citep{kortzinger_2001}. No silicified zooplankton is assumed. The bacterial pool is not yet explicitly modeled.
+\end{itemize}
 
 There are three non-living compartments: Semi-labile dissolved organic matter, small sinking particles, and large sinking particles.
 As a consequence of the variable stoichiometric ratios of phytoplankton and of the stoichiometric regulation of zooplankton, elemental ratios in organic matter cannot be supposed constant anymore as that was the case in PISCES-v2.
-Indeed, the nitrogen, phosphorus, iron, silicon and calcite pools of the particles are now all explicitly modeled.
+Indeed, the nitrogen, phosphorus, iron, silicon, and calcite pools of the particles are now all explicitly modeled.
 The sinking speed of the particles is not altered by their content in calcite and biogenic silicate (''The ballast effect'', \citep{honjo_1996,armstrong_2001}).
 The latter particles are assumed to sink at the same speed as the large organic matter particles.
@@ -678 +759 @@
 \label{Mytrc}
 
-The NEMO-TOP has only one built-in biogeochemical model - PISCES - but there are several BGC models - MEDUSA, ERSEM, BFM or ECO3M - which are meant to be coupled with the NEMO dynamics.
-Therefore it was necessary to provide to the users a framework for easily add their own BGCM model, that can be a single passive tracer.
+NEMO-TOP has one built-in biogeochemical model - PISCES - but there are several BGC models - MEDUSA, ERSEM, BFM or ECO3M - which are meant to be used within the NEMO plateform.
+Therefore it was necessary to provide to the users a framework to easily add their own BGCM model.
 The generalized interface is pivoted on MY\_TRC module that contains template files to build the coupling between NEMO and any external BGC model.
-The call to MY\_TRC is activated by setting  \textit{ln\_my\_trc} = \texttt{.true.} in namelist \textit{namtrc}
+Call to MY\_TRC is activated by setting  \textit{ln\_my\_trc} = \texttt{.true.} in namelist \textit{namtrc}.\\
 
 The following 6 fortran files are available in MY\_TRC with the specific purposes here described.
@@ -692 +773 @@
   \item \textit{trcsms\_my\_trc.F90} :  The routine performs the call to Boundary Conditions and its main purpose is to contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model.
 Be aware that lateral boundary conditions are applied in trcnxt routine.
-IMPORTANT: the routines to compute the light penetration along the water column and the tracer vertical sinking should be defined/called in here, as generalized modules are still missing in the code.
- \item \textit{trcice\_my\_trc.F90} : Here it is possible to prescribe the tracers concentrations in the seaice that will be used as boundary conditions when ice melting occurs (nn\_ice\_tr =1 in namtrc\_ice).
+IMPORTANT: the routines to compute light penetration along the water column and the tracer vertical sinking should be defined/called in here, as generalized modules are still missing in the code.
+ \item \textit{trcice\_my\_trc.F90} : Here it is possible to prescribe the tracers concentrations in sea ice that will be used as boundary conditions when ice formation and melting occurs (nn\_ice\_tr =1 in namtrc\_ice).
 See e.g. the correspondent PISCES subroutine.
  \item \textit{trcwri\_my\_trc.F90} : This routine performs the output of the model tracers using IOM module (see Manual Chapter Output and Diagnostics).
@@ -702 +783 @@
 \label{Offline}
 
-%------------------------------------------namtrc_sms----------------------------------------------------
-\nlst{namdta_dyn}
-%-------------------------------------------------------------------------------------------------------------
-
-Coupling passive tracers offline with NEMO requires precomputed  physical fields from OGCM.
-Those fields are read from files and interpolated on-the-fly at each model time step
-At least the following dynamical parameters should be absolutely passed to the transport : ocean velocities, temperature, salinity, mixed layer depth and for ecosystem models like PISCES, sea ice concentration, short wave radiation at the ocean surface, wind speed (or at least, wind stress).
-The so-called offline mode is useful since it has lower computational costs for example to perform very longer simulations - about 3000 years - to reach equilibrium of CO2 sinks for climate-carbon studies.
-
-The offline interface is located in the code repository : \path{<repository>/src/OFF/}.
-It is activated by adding the CPP key  \textit{key\_offline} to the CPP keys list.
-There are two specifics routines for the Offline code :
+Coupling passive tracers offline with NEMO requires precomputed physical fields
+ from OGCM. Those fields are read in files and interpolated on-the-fly at each model
+ time step. There are two sets of fields to perform offline simulations :
 
 \begin{itemize}
-   \item \textit{dtadyn.F90} :  this module allows to read and compute the dynamical fields at each model time-step
-   \item \textit{nemogcm.F90} :  a degraded version of the main nemogcm.F90 code of NEMO to manage the time-stepping
+   \item linear free surface ( ln\_linssh = .true. )  where the vertical scale factor is constant with time. At least, the following dynamical parameters should be absolutely passed
+   to transport : the effective ocean transport velocities (eulerian plus the eddy induced plus all others parameterizations), vertical diffusion coefficient and the freshwater flux
+.
+   %------------------------------------------namtrc_sms----------------------------------------------------
+   \nlst{namdta_dyn_linssh}
+   %-----------------------------------------------------------------------------------------------------------
+   \item non linear free surface ( ln\_linssh = .false. or key\_qco ) : the same fields than the ones in the linear free surface case. In addition, the horizontal divergence transport is needed to  recompute the time evolution of the sea surface heigth and the vertical scale factor and depth, and thus the time evolution of the vertical transport velocity.
+   %------------------------------------------namtrc_sms----------------------------------------------------
+   \nlst{namdta_dyn_nolinssh}
+   %-----------------------------------------------------------------------------------------------------------
 \end{itemize}
 
-%-
-%-
-%-
-%-  Describes here the specifities of oflline : At least the dynamical variables needed - u/v/w transport T/S for isopycnal MLD for biogeo models etc ...
-%-  the specfities of vvl - ssh + runoffs and how to
-%-
+Additionally, temperature, salinity, and mixed layer depth are needed to compute slopes for isopycnal diffusion. Some ecosystem models like PISCES need sea ice concentration, short-wave radiation at the ocean surface, and wind speed (or at least, wind stress). 
+
+The so-called offline mode is useful since it has lower computational costs for example to perform very longer simulations – about 3000 years - to reach equilibrium of CO$_{2}$ sinks for climate-carbon studies.
+
+The offline interface is located in the code repository : <repository>/src/OFF/. It is activated by adding the\textit{ key\_offline} CPP key to the CPP keys list. 
+There are
+two specifics routines for the offline code :
+\begin{itemize}
+   \item dtadyn.F90 : this module reads and computes the dynamical fields at
+each model time-step
+   \item nemogcm.F90 : a degraded version of the main nemogcm.F90 code of NEMO to
+manage the time-stepping
+\end{itemize}
+
+
 \end{document}

NEMO/trunk/doc/latex/TOP/subfiles/model_setup.tex

@@ -5 +5 @@
 \chapter{ Model Setup}
 
+The usage of TOP is activated i) by including in the configuration definition the component TOP and ii) by adding the macro key\_top in the configuration CPP file (see for more details “Learn more about the model”).
+As an example, the user can refer to already available configurations in the code, ORCA2\_ICE\_PISCES being the NEMO biogeochemical demonstrator and GYRE\_BFM to see the required configuration elements to couple with an external biogeochemical model (see also Section 4).\\
+Note that, since version 4.0, TOP interface core functionalities are activated by means of logical keys and all submodules preprocessing macros from previous versions were removed.\\
+
+Below is the list of preprocessing keys that apply to the TOP interface (beside key\_top):
+\begin{itemize}
+   \item key\_xios use XIOS I/O
+   \item key\_agrif enables AGRIF coupling
+   \item key\_trdtrc and key\_trdmxl\_trc trend computation for tracers
+\end{itemize}
+
+There are only two entry points in the NEMOGCM model for passive tracers :
+\begin{itemize}
+   \item initialization (trcini) : general initialization of global variables and parameters of BGCM
+   \item time-stepping (trcstp) : time-evolution of SMS first, then time evolution of tracers by transport
+\end{itemize}
+
 \section{ Setting up a passive tracer configuration}
 %------------------------------------------namtrc_int----------------------------------------------------
@@ -10 +27 @@
 %-------------------------------------------------------------------------------------------------------------
 
-The usage of TOP is activated
-
-\begin{itemize}
-         \item by including in the configuration definition the component TOP\_SRC
-         \item by adding the macro \textit{key\_top} in the configuration cpp file
-\end{itemize}
-
-As an example, the user can refer to already available configurations in the code, GYRE\_PISCES being the NEMO biogeochemical demonstrator and GYRE\_BFM to see the required configuration elements to couple with an external biogeochemical model (see also section \S\ref{SMS_models}) .
-
-Note that, since version 4.0, TOP interface core functionalities are activated by means of logical keys and all submodules preprocessing macros from previous versions were removed.
-
-There are only three specific keys remaining in TOP
-
-\begin{itemize}
-        \item \textit{key\_top} : to enables passive tracer module
-        \item \textit{key\_trdtrc} and \textit{key\_trdmxl\_trc} : trend computation for tracers
-\end{itemize}
-
-For a remind, the revisited structure of TOP interface now counts for five different modules handled in namelist\_top :
+As a reminder, the revisited structure of TOP interface now counts for five different modules handled in namelist\_top :
 
 \begin{itemize}
         \item \textbf{PISCES}, default BGC model
         \item \textbf{MY\_TRC}, template for creation of new modules couplings (maybe run a single passive tracer)
-        \item \textbf{CFC}, inert carbon tracers dynamics (CFC11,CFC12,SF6) Updated with OMIP-BGC guidelines (Orr et al, 2016)
+        \item \textbf{CFC}, inert tracers dynamics (CFC$_{11}$,CFC$_{12}$,SF$_{6}$) updated based on OMIP-BGC guidelines (Orr et al, 2016)
         \item \textbf{C14}, radiocarbon passive tracer
-        \item \textbf{AGE}, water age tracking revised implementation
+        \item \textbf{AGE}, water age tracking
 \end{itemize}
 
-The modular approach was implemented also in the definition of the total number of passive tracers (jptra). This results from to user setting from the namelist \textit{namtrc}
+For inert, C14, and Age tracers, all variables settings (\textit{sn\_tracer} definitions) are hard-coded in \textit{trc\_nam\_*} routines. For instance, for Age tracer:
+%------------------------------------------namtrc_int----------------------------------------------------
+\nlst{nam_trc_age}
+%---------------------------------------------------------------------------------------------------------
 
-\section{ TOP Tracer Initialisation}
+The modular approach was also implemented in the definition of the total number of passive tracers (jptra) which is specified by the user in  \textit{namtrc}
+
+\section{ TOP Tracer Initialization}
+
+Two main types of data structure are used within TOP interface to initialize tracer properties and to provide related initial and boundary conditions. 
+In addition to providing name and metadata for tracers, the use of initial and boundary conditions is also defined here (sn\_tracer).
+The data structure is internally initialized by the code with dummy names and all initialization/forcing logical fields are set to \textit{false} .
+Below are listed some features/options of the TOP interface accessible through the \textit{namelist\_top\_ref} and modifiable by means of \textit{namelist\_top\_cfg} (as for NEMO physical ones).
+
+There are three options to initialize TOP tracers in the \textit{namelist\_top } file: (1) initialization to hard-coded constant values when \textit{ln\_trcdta} at \textit{false}, (2) initialization from files when \textit{ln\_trcdta} at \textit{true}, and (3) initialisation from restart files by setting \textit{ln\_rsttr} to \textit{true} in \textit{namelist}.
+
+In the following, an example of the full structure definition is given for four tracers (DIC, Fe, NO$_{3}$, PHY) with initial conditions and different surface boundary and coastal forcings for DIC, Fe, and NO$_{3}$: 
+
+%------------------------------------------namtrc_int----------------------------------------------------
+\nlst{namtrc_cfg}
+%---------------------------------------------------------------------------------------------------------
+
+You have to activate which tracers (\textit{sn\_tracer}) you want to initialize by setting them to \texttt{true} in the  column. 
+
+\nlst{namtrc_dta_cfg}
+
+In \textit{namtrc\_dta}, you prescribe from which files the tracer are initialized (\textit{sn\_trcdta}). 
+A multiplicative factor can also be set for each tracer (\textit{rn\_trfac}). 
+
 
 \section{ TOP Boundaries Conditions}
 
+\subsection{Surface and lateral boundaries}
+
+Lateral and surface boundary conditions for passive tracers are prescribed in \textit{namtrc\_bc} as well as whether temporal interpolation of these files is enabled. Here we show the cases of Fe and NO$_{3}$ from dust and rivers with different output frequencies.
+ 
+%------------------------------------------namtrc_bc----------------------------------------------------
+\nlst{namtrc_bc_cfg}
+%---------------------------------------------------------------------------------------------------------
+
+\subsection{Antartic Ice Sheet tracer supply}
+
+As a reminder, the supply of passive tracers from the AIS is currently implemented only for dissolved Fe. The activation of this Fe source is done by setting \textit{ln\_trcais} to \textit{true} and by adding the Fe tracer (\textit{sn\_tracer(2) = .true.}) in the 'ais' column in \textit{\&namtrc} (see section 2.2). \\
+
+As the external source of Fe from the AIS is represented by associating  a sedimentary Fe content (with a solubility fraction) to the freshwater fluxes of icebergs and ice shelves, these fluxes have to be activated in \textit{namelist\_cfg}. The reading of the freshwater flux file from ice shelves is activated in \textit{namisf} with the namelist parameter \textit{ln\_isf} set to \textit{true}.
+
+You have to choose between two options depending whether the cavities under ice shelves are open or not in your grid configuration:
+\begin{itemize}
+   \item ln\_isfcav\_mlt = .false. (resolved cavities)
+   \item ln\_isfpar\_mlt = .true. (parameterized distribution for unopened cavities)
+\end{itemize}
+
+%------------------------------------------namisf----------------------------------------------------
+\nlst{namisf_cfg_eORCA1}
+%-----------------------------------------------------------------------------------------------------
+
+Runoff from icebergs is activated by setting \textit{ln\_rnf\_icb} to \textit{true} in the \textit{\&namsbc\_rnf} section of \textit{namelist\_cfg}.
+
+%------------------------------------------namsbc_rnf--------------------------------------------------
+\nlst{namsbc_rnf_cfg_eORCA1}
+%---------------------------------------------------------------------------------------------------------
+
+The freshwater flux from ice shelves and icebergs is based on observations and modeled climatologies and is available for eORCA1 and eORCA025 grids :
+\begin{itemize}
+   \item runoff-icb\_DaiTrenberth\_Depoorter\_eORCA1\_JD.nc
+   \item runoff-icb\_DaiTrenberth\_Depoorter\_eORCA025\_JD.nc 
+\end{itemize}
+
+%------------------------------------------namtrc_ais----------------------------------------------------
+\nlst{namtrc_ais_cfg}
+%---------------------------------------------------------------------------------------------------------
+
+Two options for tracer concentrations in iceberg and ice shelf can be set with the namelist parameter \textit{nn\_ais\_tr}:
+\begin{itemize}
+   \item 0 : null concentrations corresponding to dilution of BGC tracers due to freshwater fluxes from icebergs and ice shelves
+   \item 1 : prescribed concentrations set with the \textit{rn\_trafac} factor
+\end{itemize}
+
+The depth until which Fe from melting iceberg is delivered can be set with the namelist parameter \textit{rn\_icbdep}. The value of 120 m is the average underwater depth of the different iceberg size classes modeled by the NEMO iceberg module, which was used to produce the freshwater flux climatology of icebergs.
+
+
 \end{document}