doc/latex/TOP/main/abstract.tex

@@ -9,7 +9,7 @@ It is intended to be a flexible tool for studying the on/offline oceanic tracers
 the biogeochemical processes (``green ocean''),
 as well as its interactions with the other components of the Earth climate system over
 a wide range of space and time scales.
-\TOP\ is interfaced with the \NEMO\ ocean engine, and,
+\TOP\ is directly interfaced with the \NEMO\ ocean engine, and,
 via the \href{http://portal.enes.org/oasis}{OASIS} coupler,
 with several atmospheric general circulation models.
 %It also supports two-way grid embedding by means of the \href{http://agrif.imag.fr}{AGRIF} software.
@@ -23,4 +23,4 @@ enabling the use of all available advection and diffusion schemes in both on- an
 \TOP\ is designed to handle multiple oceanic tracers through a modular approach and
 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}{Biogeochemical Flux Model}).

doc/latex/TOP/main/bibliography.bib

@@ -305,18 +305,17 @@
 }
 
 @Manual{	  nemo_manual,
-  author	= {Madec Gurvan and NEMO System Team},
+  author	= {{NEMO System Team}},
   title		= {NEMO ocean engine},
   organization	= {NEMO Consortium},
-  journal	= {Notes du Pôle de modélisation de l\'Institut
-		  Pierre-Simon Laplace (IPSL)},
+  journal	= {Scientific Notes of Climate Modelling Center},
+  institution   = {Institut Pierre-Simon Laplace (IPSL)},
   issn		= {1288-1619},
   number	= {27},
   publisher	= {Zenodo},
   doi		= {10.5281/zenodo.1464816},
   url		= {https://zenodo.org/record/1464816},
-  edition	= {TBD},
-  year		= {TBD}
+  year          = {2022}
 }
 
 @Article{	  meunier_2014,
@@ -679,4 +678,12 @@
   publisher	= {Elsevier BV}
 }
 
-
+@Article{          bfm_nemo_coupling,
+  author        = {Lovato, T. and Vichi, M. and Butenschön, M.},
+  title         = {Coupling BFM with Ocean models: the NEMO model V3.6
+                  (Nucleus for the European Modelling of the Ocean)},
+  journal       = {BFM Report series},
+  number        = 2,
+  year          = 2020,
+  url           = {https://bfm-community.github.io/www.bfm-community.eu/files/bfm-nemo-manual_r1.1_202006.pdf}
+}

doc/latex/TOP/main/chapters.tex

+\subfile{../subfiles/model_structure}
 \subfile{../subfiles/model_description}
 \subfile{../subfiles/model_setup}
 \subfile{../subfiles/miscellaneous}

doc/latex/TOP/main/introduction.tex

@@ -12,13 +12,13 @@ It includes three independent components :
         \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
         \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 physical variables that were previously stored on disk
+        \item an offline transport interface, which is a simplified version of the NEMO core workflow that read a set of physical fields previously stored on disk
 \end{itemize}
 
 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{online coupling} : the evolution of passive tracers is computed along with the ocean physical dynamics
         \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}
 
@@ -28,14 +28,5 @@ TOP is designed to handle multiple oceanic tracers through a modular approach an
         \item the ocean water age module (AGE) tracks down the time-dependent spread of surface waters into the ocean interior
         \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 (\eg, 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, ECO3M)
 \end{itemize}
-
-\begin{figure}[ht]
-\begin{center}
-\vspace{0cm}
-\includegraphics[width=0.80\textwidth]{Fig_TOP_design}
-\caption{Schematic view of the NEMO-TOP component}
-\label{topdesign}
-\end{center}
-\end{figure}

doc/latex/TOP/subfiles/miscellaneous.tex

@@ -18,9 +18,9 @@ A synthetic description of the TOP interface workflow is given below to summariz
 \begin{minted}{bash}
 nemogcm
     !                      
-    nemo_init           !   NEMO General Initialisations
+    nemo_ini            !   NEMO General Initialisations
          !                   
-         trc_init                              ! TOP  Initialisations 
+         trc_ini                               ! TOP  Initialisations
     !
     stp()                   !   NEMO Time-stepping
         !
@@ -103,28 +103,34 @@ IF( MY_TRC )    trc_wri_my_trc()      ! MY_TRC  tracers
 The coupling with an external BGC model through the NEMO compilation framework can be achieved in different ways according to the degree of coding complexity of the Biogeochemical model, like e.g., the whole code is made only by one file or it has multiple modules and interfaces spread across several subfolders.\\ \\
 Beside the 6 core files of MY\_TRC module, see (see \label{Mytrc}, let's assume an external BGC model named \textit{"MYBGC"} and constituted by a rather essential coding structure, likely few Fortran files. The new coupled configuration name is NEMO\_MYBGC. \\ \\
 The best solution is to have all files (the modified MY\_TRC routines and the BGC model ones) placed in a unique folder with root \path{<MYBGCPATH>} and to use the \textit{makenemo} external readdressing of MY\_SRC folder. \\ \\
-The coupled configuration listed in \textbf{cfg.txt}  will look like
+Before compiling the code it is necessary to create the new configuration folder
 
 \begin{minted}{bash}
-   NEMO_MYBGC OPA_SRC TOP_SRC
+    $[nemo-code-root]> mkdir cfgs/NEMO_MYBGC
 \end{minted}
-and the related cpp\_MYBGC.fcm content will be
-%
+
+and add in it the configuration file cpp\_MYBGC.fcm whose content will be
+
 \begin{minted}{bash}
     bld::tool::fppkeys   key_xios key_top
 \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, by including OCE and TOP components
 
 \begin{minted}{bash}
-   makenemo -n NEMO_MYBGC -m <arch_my_machine> -j 8 -e <MYBGCPATH>
+    $[nemo-code-root]> ./makenemo -r GYRE_PISCES -n NEMO_MYBGC -d "OCE TOP" -m <arch_my_machine> -j 8 -e <MYBGCPATH>
 \end{minted}
 
-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 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.
+After the compilation, the coupled configuration will be listed in \textbf{work\_cfg.txt} and it will look like
+
+\begin{minted}{bash}
+    NEMO_MYBGC OCE TOP
+\end{minted}
 
-The compilation of more articulated BGC model code \& infrastructure, like in the case of BFM (BFM-NEMO coupling manual), requires some additional features. \\ \\
+The compilation of more articulated BGC model code \& infrastructure, like in the case of BFM \citep{bfm_nemo_coupling}, 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. \\ \\
+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
 
@@ -145,7 +151,7 @@ where MYBGC\_MACROS is the space delimited list of macros used in MYBGC model fo
 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
+makenemo -r 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:
@@ -155,9 +161,9 @@ 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.  \\ \\
+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.  \\ \\
+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.
 

doc/latex/TOP/subfiles/model_setup.tex

@@ -30,7 +30,7 @@ As a reminder, the revisited structure of TOP interface now counts for five diff
 
 \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{MY\_TRC}, template for creation of new modules couplings (see section 3.2) or user defined passive tracer dynamics
         \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
@@ -46,7 +46,7 @@ The modular approach was also implemented in the definition of the total number
 \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).
+In addition to providing name and metadata for tracers, the use of initial and boundary conditions is also defined here (\textit{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).
 

doc/latex/TOP/subfiles/model_structure.tex

+\documentclass[../main/TOP_manual]{subfiles}
+
+\begin{document}
+
+\chapter{TOP structure and workflow}
+\label{chap:ModDes}
+
+TOP is the NEMO hardwired interface toward biogeochemical models, which provides the physical constraints/boundaries for oceanic tracers (Fig. ~\ref{fig:topstructure}).
+
+Based on a modular structure, this component allows one to exploit available built-in 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{<nemo-repository>/src/TOP/}
+
+and the following modules are available:
+
+%-----------  tableau  ------------------------------------
+\begin{itemize}
+        \item \textbf{TRP}    	 :    Interface to NEMO physical core for computing tracers transport
+        \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 \cite{aumont_2015} for a complete description
+\end{itemize}
+%----------------------------------------------------------
+
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[width=0.70\textwidth]{Fig_TOP_design}
+\caption{Schematic view of the TOP interface within NEMO framework}
+\label{fig:topstructure}
+\end{center}
+\end{figure}
+
+\pagebreak
+
+The workflow of the TOP interface within the NEMO framework is organized around two main blocks of the code, the initialization (trc\_ini) and time marching (trc\_stp) procedures, as in the following
+
+\begin{minted}{bash}
+nemogcm
+    !
+    nemo_ini            !   NEMO General Initialisations
+         !
+         trc_ini                               ! 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}
+
+\end{document}