Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
No results found
Show changes
Hide whitespace changes
Inline Side-by-side
doc/latex/TOP/subfiles/model_setup.tex
View file @ 478dca63
......@@ -24,13 +24,13 @@ There are only two entry points in the NEMOGCM model for passive tracers :
\section{ Setting up a passive tracer configuration}
%------------------------------------------namtrc_int----------------------------------------------------
\nlst{namtrc}
%-------------------------------------------------------------------------------------------------------------
%--------------------------------------------------------------------------------------------------------
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{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
......@@ -38,15 +38,15 @@ As a reminder, the revisited structure of TOP interface now counts for five diff
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}
%---------------------------------------------------------------------------------------------------------
\nlstlocal{nam_trc_age}
%--------------------------------------------------------------------------------------------------------
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}
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).
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).
......@@ -55,12 +55,12 @@ There are three options to initialize TOP tracers in the \textit{namelist\_top }
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}
%---------------------------------------------------------------------------------------------------------
\nlstlocal{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}
\nlstlocal{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}).
......@@ -73,10 +73,10 @@ A multiplicative factor can also be set for each tracer (\textit{rn\_trfac}).
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}
\nlstlocal{namtrc_bc_cfg}
%---------------------------------------------------------------------------------------------------------
\subsection{Antartic Ice Sheet tracer supply}
\subsection{Antarctic 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). \\
......@@ -89,13 +89,13 @@ You have to choose between two options depending whether the cavities under ice
\end{itemize}
%------------------------------------------namisf----------------------------------------------------
\nlst{namisf_cfg_eORCA1}
\nlstlocal{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}
\nlstlocal{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 :
......@@ -105,7 +105,7 @@ The freshwater flux from ice shelves and icebergs is based on observations and m
\end{itemize}
%------------------------------------------namtrc_ais----------------------------------------------------
\nlst{namtrc_ais_cfg}
\nlstlocal{namtrc_ais_cfg}
%---------------------------------------------------------------------------------------------------------
Two options for tracer concentrations in iceberg and ice shelf can be set with the namelist parameter \textit{nn\_ais\_tr}:
......@@ -116,5 +116,93 @@ Two options for tracer concentrations in iceberg and ice shelf can be set with t
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.
\section{Coupling an external BGC model using NEMO framework}
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. \\ \\
Before compiling the code it is necessary to create the new configuration folder
\begin{minted}{bash}
$[nemo-code-root]> mkdir cfgs/NEMO_MYBGC
\end{minted}
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, by including OCE and TOP components
\begin{minted}{bash}
$[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.
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 \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. \\
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
src::MYBGC::initialization <MYBGCPATH>/initialization
src::MYBGC::pelagic <MYBGCPATH>/pelagic
src::MYBGC::benthic <MYBGCPATH>/benthic
bld::pp::MYBGC 1
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/<subfolders>.\\
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. \\
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
src::MYBGC::initialization <MYBGCPATH>/initialization
src::MYBGC::pelagic <MYBGCPATH>/pelagic
src::MYBGC::benthic <MYBGCPATH>/benthic
bld::pp::MYBGC 1
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/<subfolders>.\\
The compilation will be performed similarly to in the previous case with the following
\begin{minted}{bash}
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:
\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}
doc/latex/TOP/subfiles/model_structure.tex 0 → 100644
View file @ 478dca63
\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 following figures are screenshot of the mermaid plot genereted when accessing TOP/figures/workflow.md within gitlab
% this plots should be rewritten, e.g., using tikz graphic package
The workflow of the TOP interface within the NEMO framework is organized around two main blocks of the code, the initialization (\autoref{fig:topinit}) and time marching or "stepping" (\autoref{fig:topstep}) procedures.\\
The initialization (\forcode{trc_init}) of passive tracers variables and parameters include reading namelist, set initial tracer fields (either read restart or read data), and specific initialisation for each SMS module.
%tikz common preamble
\tikzstyle{process} = [rectangle, minimum width=1cm, minimum height=1cm, text centered, align=center, draw=black, fill=orange!20]
\tikzstyle{line} = [thick,-,>=stealth]
\tikzstyle{arrow} = [thick,->,>=stealth]
\newcommand*{\connectorH}[2]{
\draw[arrow] (#1) -- ++(1.cm,0) |- (#2);
}
% initialization workflow
%
\begin{figure}[ht]
\begin{center}
\vspace{0cm}
\begin{tikzpicture}[node distance=1.5cm and 1cm]
\node (main) [process, xshift=0 cm]
{nemo\verb!_!init \\ (nemogcm.F90) \\ NEMO General Initialisations};
\node (ini) [process, yshift=-3.5cm, xshift=3.5cm]
{trc\verb!_!init \\ (trcini.F90) \\ TOP Initialisation};
\node (ini1) [process, yshift=-0.5cm, xshift=11cm]
{trc\verb!_!nam (trcnam.F90)\\ initialize TOP tracers and run setting};
\node (ini2) [process, yshift=-2cm, xshift=11cm]
{trc\verb!_!ini\verb!_!sms \\ initialize each SMS sub-module};
\node (ini3) [process, yshift=-3.5cm, xshift=11cm]
{trc\verb!_!ini\verb!_!trp \\ initialize transport for tracers};
\node (ini4) [process, yshift=-5cm, xshift=11cm]
{trc\verb!_!ice\verb!_!ini \\ initialize tracers in seaice};
\node (ini5) [process, yshift=-6.5cm, xshift=11cm]
{trc\verb!_!ini\verb!_!state \\ set initial state from restart or inputdata};
\draw [arrow] (main.south) |- (ini.west);
\connectorH{ini.east}{ini1.west}
\connectorH{ini.east}{ini2.west}
\connectorH{ini.east}{ini3.west}
\connectorH{ini.east}{ini4.west}
\connectorH{ini.east}{ini5.west}
\end{tikzpicture}
\caption{TOP interface initialization workflow}
\label{fig:topinit}
\end{center}
\end{figure}
In the time-marching procedure of the model (trc\_stp), trends are computed for all tracers in relation to biogeochemical processes (source minus sinks of each TOP sub-module),
physical transport (advective \& diffusive, forcing and boundary conditions) and output is managed using the I/O library XIOS.
% stepping workflow
%
\renewcommand*{\connectorH}[2]{
\draw[arrow] (#1) -- ++(2.cm,0) |- (#2);
}
\begin{figure}[ht]
\begin{center}
\vspace{0cm}
\begin{tikzpicture}[node distance=1.5cm and 1cm]
\node (main) [process, xshift=0 cm]
{trc\verb!_!stp \\ (trcstp.F90) \\ TOP time marching};
\node (wri) [process, yshift=-2.25cm, xshift=3.5cm]
{trc\verb!_!wri \\ (trcwri.F90) \\ call XIOS for output of data};
\node (sms) [process, yshift=-4.25cm, xshift=3.5cm]
{trc\verb!_!sms \\ (trcsms.F90) \\ BGC trends of each sub-module};
\node (trp) [process, yshift=-6.25cm, xshift=3.5cm]
{trc\verb!_!trp \\ (TRP/trctrp.F90) \\ compute physical trends};
\node (ini1) [process, yshift=-2.5cm, xshift=13cm]
{trc\verb!_!bc (trcbc.F90)\\ surface and coastal BCs trends};
\node (ini2) [process, yshift=-4cm, xshift=13cm]
{trc\verb!_!dmp (TRP/trcdmp.F90)\\ tracer damping};
\node (ini3) [process, yshift=-5.5cm, xshift=13cm]
{trc\verb!_!ldf (TRP/trcldf.F90)\\ lateral diffusion};
\node (ini4) [process, yshift=-7.0cm, xshift=13cm]
{trc\verb!_!zdf (TRP/trczdf.F90) \\ vertical mixing after tracer};
\node (ini5) [process, yshift=-8.5cm, xshift=13cm]
{trc\verb!_!aft (TRP/trcatf.F90) \\ time filtering of 'now' tracer fields \\ (Lateral Boundary Conditions called here)};
\node (ini6) [process, yshift=-10.0cm, xshift=13cm]
{trc\verb!_!rad (TRP/trcrad.F90) \\ Correct artificial negative concentrationst};
\node (rst) [process, yshift=-8.25 cm, xshift=3.5cm]
{trc\verb!_!rst \\ (trcrst.F90) \\ write restart files};
\draw [arrow] (main.south) |- (wri.west);
\draw [arrow] (main.south) |- (sms.west);
\draw [arrow] (main.south) |- (trp.west);
\draw [arrow] (main.south) |- (rst.west);
\connectorH{trp.east}{ini1.west}
\connectorH{trp.east}{ini2.west}
\connectorH{trp.east}{ini3.west}
\connectorH{trp.east}{ini4.west}
\connectorH{trp.east}{ini5.west}
\connectorH{trp.east}{ini6.west}
\end{tikzpicture}
\caption{TOP interface time-marching workflow (called by stp in \forcode{OCE/step.F90}}
\label{fig:topstep}
\end{center}
\end{figure}
\end{document}
doc/latex/global/document.tex
View file @ 478dca63
......@@ -7,7 +7,6 @@
%% Layout
\documentclass[fontsize=10pt,twoside,abstract,draft]{scrreprt}
%\documentclass[fontsize=10pt,twoside,abstract ]{scrreprt}
%% Overall configuration
\input{../../global/preamble}
......
doc/latex/global/highlighting.tex
View file @ 478dca63
......@@ -29,4 +29,5 @@
%% Namelists inclusion
\newcommand{\nlst}[1]{\forfile{../../../namelists/#1}}
\newcommand{\nlstlocal}[1]{\forfile{../namelists/#1}}
doc/manual_build.sh
View file @ 478dca63
#!/bin/sh
#set -x
# Available manuals
manuals='NEMO SI3 TOP'
# Initialization of the options
x_p='' ; x_r=''
# Choice of the options ---
while getopts hpr: option; do
case $option in
('h') cat <<EOF
Usage:
------
./manual_build.sh [-p] [-r version ] manual
Mandatory
Chose one model manual among ${manuals} or all (if not provided compile "NEMO")
Optional
-p Produce manual with figures and disable draft watermark
-r Specify the release version number of the manual(s) instead of the branch name
EOF
exit 0 ;;
('p') x_p=0 ; shift ;;
('r') x_r=${OPTARG}; shift 2;;
esac
done
shift $(($OPTIND));
VER_NUM=${x_r}
DRAFT=${x_p}
CMP_NAM=$1
## Initialisation
##---------------
## Default selection for models
if [ "$1" = 'all' ]; then
models='NEMO SI3 TOP'
elif [ "$1" = '' ]; then
# Model
if [ "${CMP_NAM}" == 'all' ] ; then
models="$manuals"
elif [ "${CMP_NAM}" == '' ]; then
models='NEMO'
elif [[ "${manuals}" == *"${CMP_NAM}"* ]] ; then
models="${CMP_NAM}"
else
models=$*
echo "No entry for manual ${CMP_NAM}"
exit
fi
# Version
version=`git symbolic-ref -q --short HEAD || git describe --tags --exact-match || "orphan"`
if [ "x${VER_NUM}" != 'x' ] ; then
version=${VER_NUM}
fi
# Draft mode
ifdraft=1 ; draft_opt="using draft mode"
if [ "x${DRAFT}" != 'x' ] ; then
ifdraft=0 ; draft_opt=""
fi
echo "Compiling ${models} manual(s) at version ${version} ${draft_opt} \n"
# Set version
version=`echo $version | sed -e 's;_;\\\\\\\_;g'`
prefile="latex/global/preamble.tex"
sed -i '' -e "s;\\\def\\\ver.*;\\\def\\\ver{$version};" ${prefile}
# Set draft mode
docfile="latex/global/document.tex"
pkgfile="latex/global/packages.tex"
draft_opt=`grep draft $docfile`
pkg_dft=`grep draftwatermark $pkgfile | sed -e "s;%;;g"`
if [ $ifdraft == 1 ] && [ "x$draft_opt" == "x" ] ; then
sed -i '' -e "s;,abstract;,abstract,draft;" $docfile
sed -i '' -e "s;.*draftwatermark.*;\\$pkg_dft;" $pkgfile
elif [ $ifdraft == 0 ] && [ "x$draft_opt" != "x" ] ; then
sed -i '' -e "s;abstract,draft;abstract;" $docfile
sed -i '' -e "s;.*draftwatermark.*;%\\$pkg_dft;" $pkgfile
fi
# Echo current font path
fontawesome=`grep defaultfontfeatures latex/global/packages.tex | sed -e 's/.*=\(.*\)}/\1/'`
echo "Fontawesome path is $fontawesome \n"
# Source shared functions
. tools/shr_func.sh
......@@ -29,7 +100,7 @@ fi
##-------------------
for model in $models; do
echo $model
echo "Start compiling manual for $model"
# clean $model
build $model
printf "\t¤ End of building run\n"
......
doc/namelists/namopt 0 → 100644
View file @ 478dca63
!-----------------------------------------------------------------------
&namtrc_opt ! light availability in the water column
!-----------------------------------------------------------------------
! ! file name ! frequency (hours) ! variable ! time interp. ! clim ! 'yearly'/ ! weights ! rotation ! land/sea mask !
! ! ! (if <0 months) ! name ! (logical) ! (T/F) ! 'monthly' ! filename ! pairing ! filename !
sn_par = 'par.orca' , 24 , 'fr_par' , .true. , .true. , 'yearly' , '' , '' , ''
cn_dir = './' ! root directory for the location of the dynamical files
ln_varpar = .true. ! Read PAR from file
parlux = 0.43 ! Fraction of shortwave as PAR
light_loc = 'center' ! Light location in the water cell ('center', 'integral')
/
doc/namelists/namtrc
View file @ 478dca63
......@@ -19,7 +19,7 @@
!
jp_dia3d = 0 ! Number of 3D diagnostic variables
jp_dia2d = 0 ! Number of 2D diagnostic variables
!_____________!___________!_________________________________________!____________!________________!
! ! name ! title of the field ! units ! init from file !
! sn_tracer(1) = 'tracer ', 'Tracer Concentration ', ' - ' , .false.
/