source: NEMO/branches/2018/dev_r10164_HPC09_ESIWACE_PREP_MERGE/doc/latex/NEMO/subfiles/introduction.tex @ 10368

Last change on this file since 10368 was 10368, checked in by smasson, 22 months ago

dev_r10164_HPC09_ESIWACE_PREP_MERGE: merge with trunk@10365, see #2133

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