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

Last change on this file was 14929, checked in by rlod, 5 months ago

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

File size: 8.4 KB
Line 
1\documentclass[../main/TOP_manual]{subfiles}
2
3\begin{document}
4
5\chapter{Miscellaneous}
6
7\section{TOP synthetic Workflow}
8
9A 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.
10
11%\begin{figure}[!h]
12%  \centering
13%  \includegraphics[width=0.80\textwidth]{Top_FlowChart}
14%  \caption{Schematic view of NEMO-TOP flowchart}
15%  \label{img_cfcatm}
16%\end{figure}
17
18\begin{minted}{bash}
19nemogcm
20    !                     
21    nemo_init           !   NEMO General Initialisations
22         !                   
23         trc_init                              ! TOP  Initialisations
24    !
25    stp()                   !   NEMO Time-stepping
26        !
27        trc_stp()                            ! TOP time-stepping
28            !
29            trc_wri()           ! I/O manager : Output of passive tracers
30            trc_sms()           ! Sinks and sources program manager
31            trc_trp()            ! Transport of passive tracers
32            trc_rst_wri()      ! Write tracer restart file
33            trd_mxl_trc()     ! trends: Mixed-layer
34\end{minted}
35
36\subsection{Model initialization (./src/TOP/trcini.F90)}
37
38This 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 )
39
40\begin{minted}{bash}
41trc_init                              ! TOP  Initialisations
42    !   
43    IF( PISCES )    trc_ini_pisces()     !  PISCES bio model
44    IF( MY_TRC)    trc_ini_my_trc()    !  MY_TRC model
45    IF( CFCs     )    trc_ini_cfc   ()       !  CFCs
46    IF( C14       )    trc_ini_c14   ()       !  C14 model
47    IF( AGE      )    trc_ini_age   ()       !  AGE tracer
48    !
49    IF( REST   )    trc_rst_read()         ! Restart from a file 
50    ELSE            trc_dta()                   ! Initialisation from data
51\end{minted}
52
53\subsection{BGC trends computation (./src/TOP/trcsms.F90)}
54
55This is the main module where the passive tracers source minus sinks of each TOP sub-module is managed.   
56
57\begin{minted}{bash}
58trc_sms()                               ! Sinks and sources prooram manager
59    !
60    IF( PISCES  )    trc_sms_pisces()         ! main program of PISCES
61    IF( CFCs     )    trc_sms_cfc()               ! surface fluxes of CFC
62    IF( C14       )    trc_sms_c14()               ! surface fluxes of C14
63    IF( AGE       )    trc_sms_age()              ! Age tracer
64    IF( MY_TRC)    trc_sms_my_trc()         ! MY_TRC  tracers
65\end{minted}
66
67\subsection{Physical trends computation (./src/TOP/TRP/trctrp.F90)}
68
69This 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 )
70
71\begin{minted}{bash}
72trc_trp()       ! Transport of passive tracers
73    !
74    trc_sbc()         ! Surface boundary condition of freshwater flux
75    trc_bc()           ! Surface and lateral Boundary Conditions
76    trc_ais()          ! Tracers from Antarctic Ice Sheet (icb, isf)               
77    trc_bbl()          ! Advective (and/or diffusive) bottom boundary layer scheme
78    trc_dmp()        ! Internal damping trends
79    trc_bdy()         ! BDY damping trends
80    trc_adv()         ! Horizontal & Vertical advection
81    trc_ldf()           ! Lateral mixing
82    trc_zdf()          ! Vert. mixing & after tracer
83    trc_atf()           ! Time filtering of "now" tracer fields   
84    trc_rad()         ! Correct artificial negative concentrations
85\end{minted}
86
87\subsection{Outputs  (./src/TOP/TRP/trcwri.F90)}
88
89This is the main module where the passive tracer outputs of each TOP sub-module is managed using the I/O library XIOS.
90
91\begin{minted}{bash}
92trc_wri()                               ! I/O manager : Output of passive tracers
93!
94IF( PISCES   )    trc_wri_pisces()      ! Output of PISCES diagnostics
95IF( CFCs      )    trc_wri_cfc()            ! Output of Cfcs diagnostics
96IF( C14         )    trc_wri_c14()           ! surface fluxes of C14
97IF( AGE        )    trc_wri_age()           ! Age tracer
98IF( MY_TRC )    trc_wri_my_trc()      ! MY_TRC  tracers
99\end{minted}
100
101\section{Coupling an external BGC model using NEMO framework}
102
103The 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.\\ \\
104Beside 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. \\ \\
105The 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. \\ \\
106The coupled configuration listed in \textbf{cfg.txt}  will look like
107
108\begin{minted}{bash}
109   NEMO_MYBGC OPA_SRC TOP_SRC
110\end{minted}
111and the related cpp\_MYBGC.fcm content will be
112%
113\begin{minted}{bash}
114    bld::tool::fppkeys   key_xios key_top
115\end{minted}
116
117The compilation with \textit{makenemo} will be executed through the following syntax
118
119\begin{minted}{bash}
120   makenemo -n NEMO_MYBGC -m <arch_my_machine> -j 8 -e <MYBGCPATH>
121\end{minted}
122
123The 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. \\ \\
124
125The compilation of more articulated BGC model code \& infrastructure, like in the case of BFM (BFM-NEMO coupling manual), requires some additional features. \\ \\
126
127As 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. \\ \\
128
129In 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
130
131\begin{minted}{bash}
132   bld::tool::fppkeys   key_xios key_top
133
134   src::MYBGC::initialization         <MYBGCPATH>/initialization
135   src::MYBGC::pelagic                <MYBGCPATH>/pelagic
136   src::MYBGC::benthic                <MYBGCPATH>/benthic
137
138   bld::pp::MYBGC      1
139   bld::tool::fppflags::MYBGC   \%FPPFLAGS
140   bld::tool::fppkeys                  \%bld::tool::fppkeys MYBGC_MACROS
141\end{minted}
142
143where 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>.\\
144
145The compilation will be performed similarly to in the previous case with the following
146
147\begin{minted}{bash}
148makenemo -n NEMO_MYBGC -m <arch_my_machine> -j 8 -e <MYBGCPATH>/nemo_coupling
149\end{minted}
150
151Note 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:
152
153\begin{minted}{bash}
154bld::tool::fppkeys  key_zdftke key_dynspg_ts key_xios key_top
155inc <MYBGCPATH>/MYBGC.fcm
156\end{minted}
157
158This will enable a more portable compilation structure for all MYBGC related configurations.  \\ \\
159
160Important: 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.  \\ \\
161
162All 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.
163
164\end{document}
Note: See TracBrowser for help on using the repository browser.