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
Commits on Source (11)
Hide whitespace changes
Inline Side-by-side
Showing
with 435 additions and 161 deletions
doc/latex/TOP/figures/workflow.md 0 → 100644
View file @ 43a90959
# Create workflow using Mermaid
### Initialization procedure (called by OCE/nemogcm.F90)
```mermaid
graph LR
subgraph " "
trc_init["trc_init (trcini.F90)"] --> trc_nam["trc_nam (trcnam.F90) <br> initialize TOP tracers and run setting"]
trc_init --> trc_ini_sms["trc_ini_sms <br> initialize each submodule"]
trc_init --> trc_ini_trp["trc_ini_trp <br> initialize transport for tracers"]
trc_init --> trc_ice_ini["trc_ice_ini <br> initialize tracers in seaice "]
trc_init --> trc_ini_state["trc_ini_state <br> read BGC tracers from a restart or input data"]
end
```
### Time marching procedure (called by OCE/stp.F90)
```mermaid
graph LR
subgraph " "
trc_stp --> trc_wri["trc_wri <br> call XIOS for output of data"]
trc_stp --> trc_sms["trc_sms <br> BGC trends from each submodule"]
trc_stp --> trc_trp["trc_trp (TRP/trctrp.F90)<br> compute physical trends"]
trc_trp --> trc_bc["trc_bc <br> surface and coastal BCs trends"]
trc_trp --> trc_dmp["trc_dmp <br> tracer damping"]
trc_trp --> trc_ldf["trc_ldf <br> lateral diffusion"]
trc_trp --> trc_zdf["trc_zdf <br> vertical mixing & after tracer"]
trc_trp --> trc_nxt["trc_atf <br> time filtering of 'now' tracer fields <br> (Lateral Boundary Conditions called here)"]
trc_trp --> trc_rad["trc_rad <br> Correct artificial negative concentrations"]
trc_stp --> trc_rst_wri["trc_rst_wri <br> tracers restart files"]
end
```
doc/latex/TOP/main/abstract.tex
View file @ 43a90959
......@@ -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.
......
doc/latex/TOP/main/bibliography.bib
View file @ 43a90959
......@@ -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,45 @@
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}
}
@article{ morel_1988,
author = {Morel, Andr{\'e}},
title = {Optical modeling of the upper ocean in relation to its biogenous matter content (case I waters)},
journal = {Journal of geophysical research: oceans},
volume = {93},
number = {C9},
pages = {10749--10768},
year = {1988},
publisher = {Wiley Online Library}
}
@article{ lengaigne_2007,
author = {Lengaigne, Matthieu and Menkes, Christophe and Aumont, Olivier and Gorgues, Thomas and Bopp, Laurent and Andr{\'e}, Jean-Michel and Madec, Gurvan},
title = {Influence of the oceanic biology on the tropical Pacific climate in a coupled general circulation model},
journal = {Climate Dynamics},
volume = {28},
number = {5},
pages = {503--516},
year = {2007},
publisher = {Springer}
}
@article{ morel_2001,
author = {Morel, Andr{\'e} and Maritorena, St{\'e}phane},
title = {Bio-optical properties of oceanic waters: A reappraisal},
journal = {Journal of Geophysical Research: Oceans},
volume = {106},
number = {C4},
pages = {7163--7180},
year = {2001},
publisher = {Wiley Online Library}
}
doc/latex/TOP/main/chapters.tex
View file @ 43a90959
\subfile{../subfiles/model_structure}
\subfile{../subfiles/model_description}
\subfile{../subfiles/model_setup}
\subfile{../subfiles/miscellaneous}
doc/latex/TOP/main/introduction.tex
View file @ 43a90959
......@@ -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/model_description.tex
View file @ 43a90959
......@@ -11,9 +11,9 @@
\chapter{Model Description}
\label{chap:ModDes}
\chaptertoc
%\chaptertoc
\section{Basics}
\section{The transport-reaction equation}
\label{sec:Bas}
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 :
......@@ -23,17 +23,17 @@ The time evolution of any passive tracer $C$ is given by the transport equation,
\label{Eq_tracer}
\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 \cite{nemo_manual}).
where expressions of $D^{lC}$ and $D^{vC}$ depend on the choice for the lateral and vertical subgrid scale parameterizations (see sections 4.2 and 4.3 in 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.
The second term (within brackets) represents the advection of the tracer in three dimensions.
It can be interpreted as the budget between the incoming and outgoing tracer fluxes in a volume $T$-cells $b_t= e_{1t}\,e_{2t}\,e_{3t}$
The third term represents the change due to lateral diffusion.
The third term represents the change due to lateral diffusion.
The fourth term denotes the change due to vertical diffusion, parameterized as eddy diffusion to represent vertical turbulent fluxes :
......@@ -44,103 +44,123 @@ D^{vC} = \frac{1}{e_{3t}} \frac{\partial}{\partial k} \left[ A^{vT} \frac{\par
where $A^{vT}$ is the vertical eddy diffusivity coefficient of active tracers.
\section{The NEMO-TOP interface}
\label{sec:TopInt}
\section{Physical transport component (TRP)}
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 to simulate marine biogeochemical cycles.
TOP interface has the following location in the code repository : \path{<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}
% ----------------------------------------------------------
\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 damping 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 advection schemes used for the passive tracers are the same as those used for $T$ and $S$. They are described in section 4.1 of the 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.
This choice is made in \textit{namelist\_top} (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}, as it is done for the active tracers counterparts.
Note that Centred (cen), Flux Corrected Transport (fct), Upstream-Biased (ubs), and QuiCKest (qck) parameterizations 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}
%----------------------------------------------------------------------------------------------------------
%--------------------------------------------------------------------------------------------------------
\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.
After NEMO v4.0, the lateral diffusion of passive tracers uses exactly the same form of active tracers, meaning that the numerical scheme is inherited from the physical setup and forced to 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}.
The choice of the numerical scheme is then set in the \forcode{&namtra_ldf} namelist section for the dynamic described in section 4.2 of 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}.
\textit{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}
%---------------------------------------------------------------------------------------------------------
%--------------------------------------------------------------------------------------------------------
%-----------------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 :
%-----------------The code allows also 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 :
%-----------------\begin{equation} \label{eq:traqsr_iradiance}
%-----------------Aht = Aht * rn_fact_lap * \exp( - \max( 0., z -1000 ) / 1000} \quad \text{for $L=1$ to $N$}
%-----------------\end{equation}
\subsection{Vertical sinking of particles}
The module \textit{trc\_sink} computes the vertical flux of tracers that undergo to gravitational sinking (e.g., particulated matter). 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 (\textit{nitermax}) can be specified in the namelist. This allows 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}
%--------------------------------------------------------------------------------------------------------
\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.
Boolean variables are defined in \textit{namelist\_top\_ref} to specify which tracers are affected by the restoring procedure.
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.
This netcdf file can be generated using the \textit{DMP\_TOOLS} tool.
%------------------------------------------namtrc_dmp----------------------------------------------------
\nlst{namtrc_dmp}
%-----------------------------------------------------------------------------------------------------------
%--------------------------------------------------------------------------------------------------------
\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.
Some numerical schemes can generate negative values of passive tracers concentration, thus leading to unrealistic features.
For example, isopycnal diffusion can created local extrema, meaning that negative concentrations are allowed to generate.
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 (e.g., in PISCES).
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 \textit{true}.
%------------------------------------------namtrc_rad----------------------------------------------------
\nlst{namtrc_rad}
%----------------------------------------------------------------------------------------------------------
%--------------------------------------------------------------------------------------------------------
\subsection{Offline transport mode}
\label{Offline}
Coupling passive tracers offline with NEMO requires a set of physical fields computed in a previous ocean simulation.
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 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}
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}
\section{Forcing and Boundary conditions (BC)}
\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.
In TOP, 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 (see also Sec. 6.2 of NEMO manual). Through the same facility one can apply coastal inputs/loads (coastal boundary conditions) and to specify the treatment of lateral open boundary conditions. For the latter, the spatial interpolation functionality should not be activated.
%------------------------------------------namtrc_bc----------------------------------------------------
\nlst{namtrc_cfg}
%---------------------------------------------------------------------------------------------------------
The entire set of boundary conditions is activated with the paramter \forcode{ln_trcbc = .true.} in namtrc\_cfg (more details in Model Setup section).
\subsubsection{Surface and lateral boundaries}
\subsection*{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}
%-------------------------------------------------------------------------------------------------------
\subsection*{Lateral 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).
The BDY for passive tracer are set together with the physical oceanic variables (ln?bdy =.true.). Boundary conditions are set in the structure used to define the passive tracer properties in the « obc » column. These boundary conditions are applied on the segments defined for the physical system, as described in the BDY section of NEMO 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
......@@ -148,29 +168,23 @@ The BDY for passive tracer are set together with the physical oceanic variables
%------------------------------------------namtrc_bdy----------------------------------------------------
\nlst{namtrc_bdy}
%----------------------------------------------------------------------------------------------------------
%--------------------------------------------------------------------------------------------------------
\subsubsection{Sedimentation of particles}
\subsection{Sea-ice interface}
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}
\subsection*{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}
\subsection*{Antarctic 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.
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 (e.g., 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.
For icebergs, a homogeneous distribution of biogeochemical tracers is applied from the surface to a depth that can be defined in \textit{\&namtrc\_ais}, with a default values of 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 by the NEMO physical core. The AIS tracer supply is activated by setting \textit{ln\_trcais} to \textit{true} in the \textit{\&namtrc} section.
\begin{figure}[!h]
\centering
......@@ -181,19 +195,39 @@ For icebergs, a homogeneous distribution of biogeochemical tracers is applied fr
%------------------------------------------namtrc_ais----------------------------------------------------
\nlst{namtrc_ais}
%---------------------------------------------------------------------------------------------------------
%--------------------------------------------------------------------------------------------------------
\subsection{Vertical light penetration}
A dedicated module (\forcode{trcopt}) allows to compute form the sea surface solar radiation the amount of light that penetrate into the ocean interior depending on the chlorophyll field.
The visible part of solar radiation is used to derive the photosynthetic available radiation (PAR) using a simplified version of the model by \cite{morel_1988}, as described in \cite{lengaigne_2007}.
\section{The SMS modules}
In a nutshell, visible light is split into three wavebands (blue: 400–500 nm, green: 500–600 nm, red: 600–700 nm) and for each one the chlorophyll-dependent attenuation coefficients are fitted
to the coefficients computed from the full spectral model of \cite{morel_1988} (as modified in \cite{morel_2001}) assuming the same power-law expression.
The available light is then converted to PAR using a time-space constant value (\forcode{parlux}) or
by prescribing a spatially variable distribution of the fraction of the downwelling shortwave radiation (\forcode{sn_par}),
as specified with the logical parameter \forcode{ln_varpar}.
The \forcode{light_loc} parameter allows to select the way that light is computed within the gridcell volume, namely as the mean value at the cell center (\forcode{'center'}) or integrated within the cell (\forcode{'integral'}).
%--------------------------------------------namopt------------------------------------------------------
\nlst{namopt}
%--------------------------------------------------------------------------------------------------------
\section{“Source minus Sinks” modules (SMS)}
\label{SMS_models}
%------------------------------------------namtrc_sms----------------------------------------------------
%\nlst{namtrc}
%-------------------------------------------------------------------------------------------------------------
%--------------------------------------------------------------------------------------------------------
\subsection{Ideal Age}
%------------------------------------------namage----------------------------------------------------
%---------------------------------------------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 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}).
......@@ -232,7 +266,7 @@ Since this relaxation is applied explicitly, the relaxation rate should in princ
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 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:
To ensure that the forcing is independent from 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}
\label{eq:TOP-age-mixed}
......@@ -255,7 +289,7 @@ This implementation was first used in the CORE-II intercomparison runs described
\nlst{namcfc}
%----------------------------------------------------------------------------------------------------------
Chlorofluorocarbons 11 and 12 (CFC-11 and CFC-12), and sulfur hexafluoride (SF6), are synthetic chemicals manufactured for industrial and domestic applications from the early 20th century onwards.
Chlorofluorocarbons 11 and 12 (CFC-11 and CFC-12) and sulfur hexafluoride (SF6) are synthetic chemicals manufactured for industrial and domestic applications from the early 20th century onwards.
CFC-11 (CCl$_{3}$F) is a volatile liquid at room temperature, and was widely used in refrigeration.
CFC-12 (CCl$_{2}$F$_{2}$) is a gas at room temperature, and, like CFC-11, was widely used as a refrigerant,
and additionally as an aerosol propellant.
......@@ -267,16 +301,6 @@ These declines have been driven by the Montreal Protocol (effective since August
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. \\
% Chlorofluorocarbons 11 and 12 (CFC-11 and CFC-12), and sulfur hexafluoride (SF6),
% are greenhouse gases that have been released into the atmosphere by human activities.
% In the case of CFC-11 and CFC-12, this release began in the 1930s, and atmospheric
% concentrations increased until around the late 1990s afterwhich they began to decline in
% response to the Montreal Protocol.
% In the case of SF6, release began in the 1950s
% This release began in the 1930s for CFC-11 and CFC-12, and the 1950s for SF6, and
% regularly increasing their atmospheric concentration until the 1090s, 2000s for respectively CFC11, CFC12,
% and is still increasing, and SF6 (see Figure \autoref{img_cfcatm}). \\
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 ventilation of the latter via transport and mixing.
......@@ -346,8 +370,7 @@ Sc = a0 + (a1 \, \cdot \, T) + (a2 \, \cdot \, T^2) + (a3 \, \cdot \, T^3) + (
The solubility, $Sol$, used in Equation \autoref{equ_C_sat} is calculated in mol~l$^{-1}$~atm$^{-1}$,
and is specific for each gas.
It has been experimentally estimated by \citet{warner_1985} as a function of temperature
and salinity:
It has been experimentally estimated by \citet{warner_1985} as a function of temperature and salinity:
% AXY: this equation looks both weird and possibly wrong; it doesn't look like the one in the
% code version that I have to hand, although this might be out of date; in any case, I'dag
......@@ -381,13 +404,13 @@ This property, when divided by the surface CFC concentration, estimates the loca
% The standard outputs of the CFC module are the CFCs concentration in the sea water, and the records of the outputs-frequency-averaged as well as the total air-sea fluxes.
% Using XIOS, it is also possible to ask for the CFCs vertical inventory in the output file (see Figure cfc inventory example ?).
\subsubsection{Notes}
\subsubsection*{Notes}
In comparison to the OMIP protocol, the CFC module in NEMO has several differences:
% 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. This may be corrected in a future 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.\\
\begin{table}[!t]
......@@ -430,21 +453,21 @@ SF6 & & 3177.5 & -200.57 & 6.8865 & -0.13335 & 0.0010877 \\
\begin{figure}[!h]
\centering
\includegraphics[width=0.80\textwidth]{CFC-atm-evol}
\includegraphics[width=0.70\textwidth]{CFC-atm-evol}
\caption{Atmospheric CFC11, CFC12 and SF6 partial pressure evolution in both hemispheres.}
\label{img_cfcatm}
\end{figure}
\begin{figure}[!h]
\centering
\includegraphics[width=0.80\textwidth]{CFC_solub}
\includegraphics[width=0.70\textwidth]{CFC_solub}
\caption{CFC11 solubility in mol m$^{-3}$ pptv$^{-1}$, calculated from the World Ocean Atlas 2013 temperature and salinity annual climatology.}
\label{img_cfcsol}
\end{figure}
\begin{figure}[!h]
\centering
\includegraphics[width=0.80\textwidth]{CFC_inventory}
\includegraphics[width=0.70\textwidth]{CFC_inventory}
\caption{CFC11 vertical inventory in $\mu$mol m$^{-2}$, from one of the UK Earth System Model 1 model (UKESM1 - which uses NEMO as ocean component, with TOP for the passive tracers) historical run at year 2000.}
\label{img_cfcinv}
\end{figure}
......@@ -462,7 +485,7 @@ SF6 & & 3177.5 & -200.57 & 6.8865 & -0.13335 & 0.0010877 \\
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.
\subsubsection{Method}
\subsection*{Method}
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:
......@@ -551,7 +574,7 @@ The following parameters intervening in the air-sea exchange rate are set in \te
It should be adjusted so that the globally averaged $\cd$ piston velocity is $\kappa_\cd = 16.5\pm 3.2$ cm/h \citep{naegler_2009}.
%The sensitivity to this parametrization is discussed in section \autoref{sec:result}.
%
\item Chemical enhancement (term $b$ in Eq. \autoref{eq:wanchem}) may be set on/off by means of the logical variable \forcode{ln\_chemh}.
\item Chemical enhancement (term $b$ in Eq. \autoref{eq:wanchem}) may be set on/off by means of the logical variable \forcode{ln_chemh}.
\end{itemize}
%
......@@ -597,7 +620,7 @@ Time on x-axis is in simulation year.\label{fig:drift} }
The $\Dcq$ is illustrated for the three zonal bands (upper, middle, and lower curves correspond to latitudes $> 20$N, $\in [20\mathrm{S},20\mathrm{N}]$, and $< 20$S, respectively.} \label{fig:bomb}
\end{figure}
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.}).
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.
......@@ -613,13 +636,13 @@ 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:
\begin{itemize}
\item Specify the starting date of the experiment: \forcode{nn\_date0} in \texttt{namelist}. \forcode{nn\_date0} is written as Year0101 where Year may take any positive value (AD).
\item Then the parameters \forcode{nn\_rstctl} in \texttt{namelist} (on-line) and \forcode{nn\_rsttr} in \texttt{namelist\_top} (off-line) must be \textbf{set to 0} at the start of the experiment (force the date to \forcode{nn\_date0} for the \textbf{first} experiment year).
\item These two parameters (\forcode{nn\_rstctl} and \forcode{nn\_rsttr}) have then to be \textbf{set to 2} for the following years (the date must be read in the restart file).
\item Specify the starting date of the experiment: \forcode{nn_date0} in \texttt{namelist}. \forcode{nn_date0} is written as Year0101 where Year may take any positive value (AD).
\item Then the parameters \forcode{nn_rstctl} in \texttt{namelist} (on-line) and \forcode{nn_rsttr} in \texttt{namelist\_top} (off-line) must be \textbf{set to 0} at the start of the experiment (force the date to \forcode{nn_date0} for the \textbf{first} experiment year).
\item These two parameters (\forcode{nn_rstctl} and \forcode{nn_rsttr}) have then to be \textbf{set to 2} for the following years (the date must be read in the restart file).
\end{itemize}
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.
Note that \forcode{tyrc14_beg} (\texttt{namelist\_c14}) is not used in this context.
%
\textbf{Transient: Past}
......@@ -646,9 +669,9 @@ These atmospheric values are reproduced in Fig. \autoref{fig:paleo}.
Dates in these files are expressed as yr BP.
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.
The true experiment starting date is given by \forcode{tyrc14\_beg} (in yr BP) in \texttt{namelist\_c14}.
In consequence, \forcode{nn\_date0} in \texttt{namelist} MUST be set to 00010101.\\
Then the parameters \forcode{nn\_rstctl} in \texttt{namelist} (on-line) and \forcode{nn\_rsttr} in \texttt{namelist\_top} (off-line) must be set to 0 at the start of the experiment (force the date to \forcode{nn\_date0} for the first experiment year).
The true experiment starting date is given by \forcode{tyrc14_beg} (in yr BP) in \texttt{namelist\_c14}.
In consequence, \forcode{nn_date0} in \texttt{namelist} MUST be set to 00010101.\\
Then the parameters \forcode{nn_rstctl} in \texttt{namelist} (on-line) and \forcode{nn_rsttr} in \texttt{namelist\_top} (off-line) must be set to 0 at the start of the experiment (force the date to \forcode{nn_date0} for the first experiment year).
These two parameters have then to be set to 2 for the following years (read the date in the restart file). \\
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.
......@@ -709,7 +732,7 @@ N_A \Rq_\mathrm{oxa} \overline{\Ct} \left( \int_\Omega \Rq d\Omega \right) /10^{
where $N_A$ is the Avogadro's number ($N_A=6.022\times10^{23}$ at/mol), $\Rq_\mathrm{oxa}$ is the oxalic acid radiocarbon standard \cite[$\Rq_\mathrm{oxa}=1.176\times10^{-12}$;][]{stuiver_1977}, and $\Omega$ is the ocean volume.
Bomb $\cq$ inventories are traditionally reported in units of $10^{26}$ atoms, hence the denominator in \autoref{eq:inv}.
All transformations from second to year, and inversely, are performed with the help of the physical constant \forcode{rsiyea} the sideral year length expressed in seconds\footnote{The variable (\forcode{nyear\_len}) which reports the length in days of the previous/current/future year (see \textrm{oce\_trc.F90}) is not a constant. }.
All transformations from second to year, and inversely, are performed with the help of the physical constant \forcode{rsiyea} the sideral year length expressed in seconds\footnote{The variable (\forcode{nyear_len}) which reports the length in days of the previous/current/future year (see \textrm{oce\_trc.F90}) is not a constant. }.
The global transfer velocities represent time-averaged\footnote{the actual duration is set in \texttt{iodef.xml}} global integrals of the transfer rates:
......@@ -775,43 +798,9 @@ Be aware that lateral boundary conditions are applied in trcnxt routine.
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).
\item \textit{trcwri\_my\_trc.F90} : This routine performs the output of the model tracers using IOM module (see NEMO manual Chapter on Output and Diagnostics).
It is possible to place here the output of additional variables produced by the model, if not done elsewhere in the code, using the call to \textit{iom\_put}.
\end{itemize}
\section{The Offline Option}
\label{Offline}
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 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}
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}
doc/latex/TOP/subfiles/model_setup.tex
View file @ 43a90959
......@@ -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).
......@@ -76,7 +76,7 @@ Lateral and surface boundary conditions for passive tracers are prescribed in \t
\nlst{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). \\
......@@ -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/miscellaneous.tex → doc/latex/TOP/subfiles/model_structure.tex
View file @ 43a90959
\documentclass[../main/TOP_manual]{subfiles}
\begin{document}
\chapter{Miscellaneous}
\section{TOP synthetic Workflow}
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.
%\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}
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
\begin{minted}{bash}
NEMO_MYBGC OPA_SRC TOP_SRC
\end{minted}
and the related cpp\_MYBGC.fcm 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
\begin{minted}{bash}
makenemo -n NEMO_MYBGC -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 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
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 -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}
\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}
doc/namelists/namopt 0 → 100644
View file @ 43a90959
!-----------------------------------------------------------------------
&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 @ 43a90959
......@@ -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.
/