New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
introduction.tex in branches/2017/dev_merge_2017/DOC/tex_sub – NEMO

source: branches/2017/dev_merge_2017/DOC/tex_sub/introduction.tex @ 9389

Last change on this file since 9389 was 9389, checked in by nicolasmartin, 6 years ago

Starting to use minted macros to highlight namelists parameters: \textit -> \forcode
Work in progress as all escape characters (\) have to be removed in namelist parameter ids
Then several \np macros along with their paramater values with will be replaced by \forcode{np = value} apart from section headings for indexing
Fixes: style issue by reordering preamble section, removing \np macros inside equations and editing path to NEMO_manual.tex for subfiles.

File size: 16.8 KB
Line 
1\documentclass[../tex_main/NEMO_manual]{subfiles}
2\begin{document}
3
4% ================================================================
5% INTRODUCTION
6% ================================================================
7
8\chapter{Introduction}
9
10The Nucleus for European Modelling of the Ocean (\NEMO) is a framework of ocean
11related engines, namely OPA\footnote{OPA = Oc\'{e}an PArall\'{e}lis\'{e}} for the
12ocean dynamics and thermodynamics, LIM\footnote{LIM = Louvain la-neuve Ice
13Model} for the sea-ice dynamics and thermodynamics, TOP\footnote{TOP = Tracer
14in the Ocean Paradigm} for the biogeochemistry (both transport (TRP) and sources
15minus sinks (LOBSTER\footnote{LOBSTER = Lodyc Ocean Biogeochemical SysTem for
16Ecosystem and Resources}, PISCES\footnote{PISCES = Pelagic Interactions Scheme for
17Carbon and Ecosystem Studies}). It is intended to be a flexible tool for studying
18the ocean and its interactions with the other components of the earth climate system
19(atmosphere, sea-ice, biogeochemical tracers, ...) over a wide range of space and time scales.
20This documentation provides information about the physics represented by the ocean
21component of \NEMO and the rationale for the choice of numerical schemes and
22the model design. More specific information about running the model on different
23computers, or how to set up a configuration, are found on the \NEMO web site
24(www.nemo-ocean.eu).
25
26The ocean component of \NEMO has been developed from the OPA model,
27release 8.2, described in \citet{Madec1998}. This model has been used for a wide
28range of applications, both regional or global, as a forced ocean model and as a
29model coupled with the sea-ice and/or the atmosphere. 
30
31This manual is organised in as follows. Chapter~\ref{PE} presents the model basics,
32$i.e.$ the equations and their assumptions, the vertical coordinates used, and the
33subgrid scale physics. This part deals with the continuous equations of the model
34(primitive equations, with temperature, salinity and an equation of seawater).
35The equations are written in a curvilinear coordinate system, with a choice of vertical
36coordinates ($z$, $s$, \textit{z*}, \textit{s*}, $\tilde{z}$, $\tilde{s}$, and a mixture of them).
37Momentum equations are formulated in vector invariant or flux form.
38Dimensional units in the meter, kilogram, second (MKS) international system
39are used throughout.
40
41The following chapters deal with the discrete equations. Chapter~\ref{STP} presents the
42time domain. The model time stepping environment is a three level scheme in which
43the tendency terms of the equations are evaluated either centered  in time, or forward,
44or backward depending of the nature of the term.
45Chapter~\ref{DOM} presents the space domain. The model is discretised on a staggered
46grid (Arakawa C grid) with masking of land areas. Vertical discretisation used depends
47on both how the bottom topography is represented and whether the free surface is linear or not.
48Full step or partial step $z$-coordinate or $s$- (terrain-following) coordinate is used
49with linear free surface (level position are then fixed in time). In non-linear free surface,
50the corresponding rescaled height coordinate formulation (\textit{z*} or \textit{s*}) is used
51(the level position then vary in time as a function of the sea surface heigh).
52The following two chapters (\ref{TRA} and \ref{DYN}) describe the discretisation of the
53prognostic equations for the active tracers and the momentum. Explicit, split-explicit
54and filtered free surface formulations are implemented.
55A number of numerical schemes are available for momentum advection, for the computation
56of the pressure gradients, as well as for the advection of tracers (second or higher
57order advection schemes, including positive ones).
58
59Surface boundary conditions (chapter~\ref{SBC}) can be implemented as prescribed
60fluxes, or bulk formulations for the surface fluxes (wind stress, heat, freshwater). The
61model allows penetration of solar radiation  There is an optional geothermal heating at
62the ocean bottom. Within the \NEMO system the ocean model is interactively coupled
63with a sea ice model (LIM) and with biogeochemistry models (PISCES, LOBSTER).
64Interactive coupling to Atmospheric models is possible via the OASIS coupler
65\citep{OASIS2006}. Two-way nesting is also available through an interface to the
66AGRIF package (Adaptative Grid Refinement in \textsc{Fortran}) \citep{Debreu_al_CG2008}.
67The interface code for coupling to an alternative sea ice model (CICE, \citet{Hunke2008})
68has now been upgraded so that it works for both global and regional domains, although AGRIF
69is still not available.
70
71Other model characteristics are the lateral boundary conditions (chapter~\ref{LBC}). 
72Global configurations of the model make use of the ORCA tripolar grid, with special north
73fold boundary condition. Free-slip or no-slip boundary conditions are allowed at land
74boundaries. Closed basin geometries as well as periodic domains and open boundary
75conditions are possible.
76
77Physical parameterisations are described in chapters~\ref{LDF} and \ref{ZDF}. The
78model includes an implicit treatment of vertical viscosity and diffusivity. The lateral
79Laplacian and biharmonic viscosity and diffusion can be rotated following a geopotential
80or neutral direction. There is an optional eddy induced velocity \citep{Gent1990} with a
81space and time variable coefficient \citet{Treguier1997}. The model has vertical harmonic
82viscosity and diffusion with a space and time variable coefficient, with options to compute
83the coefficients with \citet{Blanke1993}, \citet{Pacanowski_Philander_JPO81},
84or \citet{Umlauf_Burchard_JMS03} mixing schemes.
85 \vspace{1cm}
86 
87%%gm    To be put somewhere else ....
88
89\noindent CPP keys and namelists are used for inputs to the code.  \newline
90
91\noindent \index{CPP keys} CPP keys \newline
92Some CPP keys are implemented in the FORTRAN code to allow code selection at compiling step. This selection of code at compilation time reduces the reliability of the whole platform since it changes the code from one set of CPP keys to the other. It is used only when the addition/suppression of the part of code highly changes the amount of memory at run time.
93Usual coding looks like :
94\vspace{-10pt}
95\begin{forlines}
96#if defined key_option1
97   ! This part of the FORTRAN code will be active
98   ! only if key_option1 is activated at compiling step
99#endif
100\end{forlines}
101
102\noindent \index{Namelist} Namelists
103
104The namelist allows to input variables (character, logical, real and integer) into the code. There is one namelist file for each component of NEMO (dynamics, sea-ice, biogeochemistry...) containing all the FOTRAN namelists needed. The implementation in NEMO uses a two step process. For each FORTRAN namelist, two files are read:
105\begin{enumerate}
106\item A reference namelist (in \path{CONFIG/SHARED/namelist_ref}) is read first. This file contains all the namelist variables which are initialised to default values 
107\item A configuration namelist (in \path{CONFIG/CFG_NAME/EXP00/namelist_cfg}) is read aferwards. This file contains only the namelist variables which are changed from default values, and overwrites those.
108\end{enumerate}
109A template can be found in \path{NEMO/OPA_SRC/module.example}.
110The effective namelist, taken in account during the run, is stored at execution time in an output\_namelist\_dyn (or \_ice or \_top) file.
111 \vspace{1cm}
112
113%%gm  end
114
115Model outputs management and specific online diagnostics are described in chapters~\ref{DIA}.
116The diagnostics includes the output of all the tendencies of the momentum and tracers equations,
117the output of tracers tendencies averaged over the time evolving mixed layer, the output of
118the tendencies of the barotropic vorticity equation, the computation of on-line floats trajectories...
119Chapter~\ref{OBS} describes a tool which reads in observation files (profile temperature
120and salinity, sea surface temperature, sea level anomaly and sea ice concentration)
121and calculates an interpolated model equivalent value at the observation location
122and nearest model timestep. Originally developed of data assimilation, it is a fantastic
123tool for model and data comparison. Chapter~\ref{ASM} describes how increments
124produced by data assimilation may be applied to the model equations.
125Finally, Chapter~\ref{CFG} provides a brief introduction to the pre-defined model
126configurations (water column model, ORCA and GYRE families of configurations).
127
128The model is implemented in \textsc{Fortran 90}, with preprocessing (C-pre-processor).
129It runs under UNIX. It is optimized for vector computers and parallelised by domain 
130decomposition with MPI. All input and output is done in NetCDF (Network Common Data
131Format) with a optional direct access format for output. To ensure the clarity and
132readability of the code it is necessary to follow coding rules. The coding rules for OPA
133include conventions for naming variables, with different starting letters for different types
134of variables (real, integer, parameter\ldots). Those rules are briefly presented in
135Appendix~\ref{Apdx_D} and a more complete document is available on the \NEMO web site.
136
137The model is organized with a high internal modularity based on physics. For example,
138each trend ($i.e.$, a term in the RHS of the prognostic equation) for momentum and
139tracers is computed in a dedicated module.  To make it easier for the user to find his way
140around the code, the module names follow a three-letter rule. For example, \mdl{traldf} 
141is a module related to the TRAcers equation, computing the Lateral DiFfussion.
142%The complete list of module names is presented in Appendix~\ref{Apdx_D}.      %====>>>> to be done !
143Furthermore, modules are organized in a few directories that correspond to their category,
144as indicated by the first three letters of their name (Tab.~\ref{Tab_chap}).
145
146The manual mirrors the organization of the model.
147After the presentation of the continuous equations (Chapter \ref{PE}), the following chapters
148refer to specific terms of the equations each associated with a group of modules (Tab.~\ref{Tab_chap}).
149
150
151%--------------------------------------------------TABLE--------------------------------------------------
152\begin{table}[!t]
153%\begin{center} \begin{tabular}{|p{143pt}|l|l|} \hline
154\caption{ \protect\label{Tab_chap}   Organization of Chapters mimicking the one of the model directories. }
155\begin{center}    \begin{tabular}{|l|l|l|}   \hline
156Chapter \ref{STP} & -                 & model time STePping environment \\    \hline
157Chapter \ref{DOM} & DOM    & model DOMain \\    \hline
158Chapter \ref{TRA} & TRA    & TRAcer equations (potential temperature and salinity) \\   \hline
159Chapter \ref{DYN} & DYN    & DYNamic equations (momentum) \\      \hline
160Chapter \ref{SBC}    & SBC    & Surface Boundary Conditions \\       \hline
161Chapter \ref{LBC} & LBC    & Lateral Boundary Conditions (also OBC and BDY)  \\     \hline
162Chapter \ref{LDF} & LDF    & Lateral DiFfusion (parameterisations) \\   \hline
163Chapter \ref{ZDF} & ZDF    & vertical (Z) DiFfusion (parameterisations)  \\      \hline
164Chapter \ref{DIA} & DIA    & I/O and DIAgnostics (also IOM, FLO and TRD) \\      \hline
165Chapter \ref{OBS} & OBS    & OBServation and model comparison  \\    \hline
166Chapter \ref{ASM} & ASM    & ASsiMilation increment  \\     \hline
167Chapter \ref{MISC}   & SOL    & Miscellaneous  topics (including solvers)  \\       \hline
168Chapter \ref{CFG} &  -        & predefined configurations (including C1D) \\     \hline
169\end{tabular} 
170\end{center}   \end{table}
171%--------------------------------------------------------------------------------------------------------------
172
173
174\subsubsection{Changes between releases}
175NEMO/OPA, like all research tools, is in perpetual evolution. The present document describes
176the OPA version include in the release 3.4 of NEMO.  This release differs significantly
177from version 8, documented in \citet{Madec1998}.\\
178
179$\bullet$ The main modifications from OPA v8 and NEMO/OPA v3.2 are :\\
180\begin{enumerate}
181\item transition to full native \textsc{Fortran} 90, deep code restructuring and drastic
182reduction of CPP keys;
183\item introduction of partial step representation of bottom topography \citep{Barnier_al_OD06, Le_Sommer_al_OM09, Penduff_al_OS07};
184\item partial reactivation of a terrain-following vertical coordinate ($s$- and hybrid $s$-$z$)
185with the addition of several options for pressure gradient computation \footnote{Partial
186support of $s$-coordinate: there is presently no support for neutral physics in $s$-
187coordinate and for the new options for horizontal pressure gradient computation with
188a non-linear equation of state.};
189\item more choices for the treatment of the free surface: full explicit, split-explicit or filtered
190schemes, and suppression of the rigid-lid option;
191\item non linear free surface associated with the rescaled height coordinate 
192\textit{z*} or  \textit{s};
193\item additional schemes for vector and flux forms of the momentum  advection;
194\item additional advection schemes for tracers;
195\item implementation of the AGRIF package (Adaptative Grid Refinement in \textsc{Fortran}) \citep{Debreu_al_CG2008};
196\item online diagnostics : tracers trend in the mixed layer and vorticity balance;
197\item rewriting of the I/O management with the use of an I/O server;
198\item generalized ocean-ice-atmosphere-CO2 coupling interface, interfaced with OASIS 3 coupler ;
199\item surface module (SBC) that simplify the way the ocean is forced and include two
200bulk formulea (CLIO and CORE) and which includes an on-the-fly interpolation of input forcing fields ;
201\item RGB light penetration and optional use of ocean color
202\item major changes in the TKE schemes: it now includes a Langmuir cell parameterization  \citep{Axell_JGR02},
203the \citet{Mellor_Blumberg_JPO04} surface wave breaking parameterization, and has a time discretization
204which is energetically consistent with the ocean model equations \citep{Burchard_OM02, Marsaleix_al_OM08};
205\item tidal mixing parametrisation (bottom intensification) + Indonesian specific tidal mixing \citep{Koch-Larrouy_al_GRL07};
206\item introduction of LIM-3, the new Louvain-la-Neuve sea-ice model (C-grid rheology and
207new thermodynamics including bulk ice salinity) \citep{Vancoppenolle_al_OM09a, Vancoppenolle_al_OM09b}
208\end{enumerate}
209
210 \vspace{1cm}
211$\bullet$ The main modifications from NEMO/OPA v3.2 and  v3.3 are :\\
212\begin{enumerate}
213\item introduction of a modified leapfrog-Asselin filter time stepping scheme \citep{Leclair_Madec_OM09};
214\item additional scheme for iso-neutral mixing \citep{Griffies_al_JPO98}, although it is still a "work in progress";
215\item a rewriting of the bottom boundary layer scheme, following \citet{Campin_Goosse_Tel99};
216\item addition of a Generic Length Scale vertical mixing scheme, following \citet{Umlauf_Burchard_JMS03};
217\item addition of the atmospheric pressure as an external forcing on both ocean and sea-ice dynamics;
218\item addition of a diurnal cycle on solar radiation \citep{Bernie_al_CD07};
219\item river runoffs added through a non-zero depth, and having its own temperature and salinity;
220\item CORE II normal year forcing set as the default forcing of ORCA2-LIM configuration ;
221\item generalisation of the use of \mdl{fldread} for all input fields (ocean climatology, sea-ice damping...) ;
222\item addition of an on-line observation and model comparison (thanks to NEMOVAR project);
223\item optional application of an assimilation increment (thanks to NEMOVAR project);
224\item coupling interface adjusted for WRF atmospheric model;
225\item C-grid ice rheology now available fro both LIM-2 and LIM-3 \citep{Bouillon_al_OM09};
226\item LIM-3 ice-ocean momentum coupling applied to LIM-2 ;
227\item a deep re-writting and simplification of the off-line tracer component (OFF\_SRC) ;
228\item the merge of passive and active advection and diffusion modules ;
229\item  Use of the Flexible Configuration Manager (FCM) to build configurations, generate the Makefile and produce the executable ;
230\item Linear-tangent and Adjoint component (TAM) added, phased with v3.0
231\end{enumerate}
232 \vspace{1cm}
233In addition, several minor modifications in the coding have been introduced with the constant
234concern of improving the model performance.
235
236 \vspace{1cm}
237$\bullet$ The main modifications from NEMO/OPA v3.3 and  v3.4 are :\\
238\begin{enumerate}
239\item finalisation of above iso-neutral mixing \citep{Griffies_al_JPO98}";
240\item "Neptune effect" parametrisation;
241\item horizontal pressure gradient suitable for s-coordinate;
242\item semi-implicit bottom friction;
243\item finalisation of the merge of passive and active tracers advection-diffusion modules;
244\item a new bulk formulae (so-called MFS);
245\item use fldread for the off-line tracer component (OFF\_SRC) ;
246\item use MPI point to point communications  for north fold;
247\item diagnostic of transport ;
248\end{enumerate}
249
250
251 \vspace{1cm}
252$\bullet$ The main modifications from NEMO/OPA v3.4 and  v3.6 are :\\
253\begin{enumerate}
254 \item ... ;
255\end{enumerate}
256
257
258 \vspace{1cm}
259$\bullet$ The main modifications from NEMO/OPA v3.6 and  v4.0 are :\\
260\begin{enumerate}
261\item new definition of configurations ;
262\item bulk formulation ;
263\item ... ;
264\end{enumerate}
265
266
267\end{document}
Note: See TracBrowser for help on using the repository browser.