New URL for NEMO forge!

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 NEMO/trunk/doc/latex/NEMO/subfiles – NEMO

source: NEMO/trunk/doc/latex/NEMO/subfiles/introduction.tex @ 11435

Last change on this file since 11435 was 11435, checked in by nicolasmartin, 3 years ago

Various corrections on chapters

Cleaning the indexes by fixing/removing wrong entries (or appending a ? to unknown items) and
improve the classification with new index definitions for CPP keys and namelist blocks:

  • from \key{...} cmd, key_ prefix no longer precedes the index entry
  • namelist block declaration moves from \ngn{nam...} to \nam{...} (i.e. \ngn{namtra\_ldf} -> \nam{tra\_ldf}) The expected prefix nam is added to the printed word but not the index entry.

Now we have indexes with a better sorting instead of all CPP keys under 'K' and namelists blocks under 'N'.

Fix missing space issues with alias commands by adding a trailing backslash (\NEMO\, \ie\, \eg\, ...).
There is no perfect solution for this, and I prefer not using a particular package to solve it.

Review the initial LaTeX code snippet for the historic changes in chapters

Finally, for readability and future diff visualisations, please avoid writing paragraphs with continuous lines.
Break the lines around 80 to 100 characters long

File size: 17.5 KB
3%% Remove section heading (no section here)
8% ================================================================
10% ================================================================
14The Nucleus for European Modelling of the Ocean (\NEMO) is a framework of ocean related engines,
15namely OPA \footnote{OPA: Oc\'{e}an PArall\'{e}lis\'{e} (french)} for the ocean dynamics and thermodynamics,
16SI$^3$ \footnote{SI$^3$: Sea-Ice modelling Integrated Initiative} for the sea-ice dynamics and thermodynamics,
17TOP \footnote{TOP: Tracer in the Ocean Paradigm} for the biogeochemistry
18(both transport (TRP) and sources minus sinks
19(PISCES \footnote{PISCES: Pelagic Interactions Scheme for Carbon and Ecosystem Studies})).
20It is intended to be a flexible tool for studying the ocean and its interactions with the other components of
21the earth climate system (atmosphere, sea-ice, biogeochemical tracers, ...) over
22a wide range of space and time scales.
23This manual provides information about the physics represented by the ocean component of \NEMO\ and
24the rationale for the choice of numerical schemes and the model design.
25For the use of framework,
26a guide which gathers the \texttt{README} files spread out in the source code can be build and
27exported in web or printable format (see \path{./doc/rst}).
28An online version of the guide is also available on the
29\href{}{\NEMO\ forge platform}.
31The ocean component of \NEMO\ has been developed from the legacy of the OPA model, release 8.2,
32described in \citet{madec.delecluse.ea_NPM98}.
33This model has been used for a wide range of applications, both regional or global, as a forced ocean model and
34as a model coupled with the sea-ice and/or the atmosphere.
36This manual is organised in as follows.
37\autoref{chap:PE} presents the model basics, \ie\ the equations and their assumptions,
38the vertical coordinates used, and the subgrid scale physics.
39This part deals with the continuous equations of the model
40(primitive equations, with temperature, salinity and an equation of seawater).
41The equations are written in a curvilinear coordinate system, with a choice of vertical coordinates
42($z$, $s$, \zstar, \sstar, \ztilde, \stilde, and a mix of them).
43Momentum equations are formulated in vector invariant or flux form.
44Dimensional units in the meter, kilogram, second (MKS) international system are used throughout.
46The following chapters deal with the discrete equations.
47\autoref{chap:STP} presents the time domain.
48The model time stepping environment is a three level scheme in which
49the tendency terms of the equations are evaluated either centered in time, or forward, or backward depending of
50the nature of the term.
51\autoref{chap:DOM} presents the space domain.
52The model is discretised on a staggered grid (Arakawa C grid) with masking of land areas.
53Vertical discretisation used depends on both how the bottom topography is represented and whether
54the free surface is linear or not.
55Full step or partial step $z$-coordinate or $s$- (terrain-following) coordinate is used with linear free surface
56(level position are then fixed in time).
57In non-linear free surface, the corresponding rescaled height coordinate formulation (\zstar or \sstar) is used
58(the level position then vary in time as a function of the sea surface heigh).
59The following two chapters (\autoref{chap:TRA} and \autoref{chap:DYN}) describe the discretisation of
60the prognostic equations for the active tracers and the momentum.
61Explicit, split-explicit and filtered free surface formulations are implemented.
62A number of numerical schemes are available for momentum advection,
63for the computation of the pressure gradients, as well as for the advection of tracers
64(second or higher order advection schemes, including positive ones).
66Surface boundary conditions (\autoref{chap:SBC}) can be implemented as prescribed fluxes, or bulk formulations for
67the surface fluxes (wind stress, heat, freshwater).
68The model allows penetration of solar radiation.
69There is an optional geothermal heating at the ocean bottom.
70Within the \NEMO\ system the ocean model is interactively coupled with a sea ice model (SI$^3$) and
71a biogeochemistry model (PISCES).
72Interactive coupling to Atmospheric models is possible via the \href{}{OASIS coupler}.
73Two-way nesting is also available through an interface to the AGRIF package
74(Adaptative Grid Refinement in \fortran) \citep{debreu.vouland.ea_CG08}.
75% Needs to be reviewed
76%The interface code for coupling to an alternative sea ice model (CICE, \citet{Hunke2008}) has now been upgraded so
77%that it works for both global and regional domains, although AGRIF is still not available.
79Other model characteristics are the lateral boundary conditions (\autoref{chap:LBC}).
80Global configurations of the model make use of the ORCA tripolar grid, with special north fold boundary condition.
81Free-slip or no-slip boundary conditions are allowed at land boundaries.
82Closed basin geometries as well as periodic domains and open boundary conditions are possible.
84Physical parameterisations are described in \autoref{chap:LDF} and \autoref{chap:ZDF}.
85The model includes an implicit treatment of vertical viscosity and diffusivity.
86The lateral Laplacian and biharmonic viscosity and diffusion can be rotated following
87a geopotential or neutral direction.
88There is an optional eddy induced velocity \citep{gent.mcwilliams_JPO90} with a space and time variable coefficient
90The model has vertical harmonic viscosity and diffusion with a space and time variable coefficient,
91with options to compute the coefficients with \citet{blanke.delecluse_JPO93}, \citet{pacanowski.philander_JPO81}, or
92\citet{umlauf.burchard_JMR03} mixing schemes.
94%%gm    To be put somewhere else ....
95%%nm    We should consider creating a glossary for all this kind of stuff (terms, acronyms and symbols)
97\noindent CPP keys and namelists are used as inputs to the code.
99\noindent \index{CPP keys} CPP keys
101Some CPP keys are implemented in the \fortran code to allow code selection at compiling step.
102This selection of code at compilation time reduces the reliability of the whole platform since
103it changes the code from one set of CPP keys to the other.
104It is used only when the addition/suppression of the part of code highly changes the amount of memory at run time.
105Usual coding looks like:
108#if defined key_option1
109   ! This part of the \fortran code will be active
110   ! only if key_option1 is activated at compiling step
114\noindent \index{Namelist} Namelists
116The namelist allows to input variables (character, logical, real and integer) into the code.
117There is one namelist file for each component of \NEMO\ (dynamics, sea-ice, biogeochemistry...)
118containing all the \fortran namelists needed.
119The implementation in \NEMO\ uses a 2-step process.
120For each \fortran namelist, two files are read:
124  A reference namelist (in \path{./cfgs/SHARED/namelist_ref}) is read first.
125  This file contains all the namelist variables which are initialised to default values
127  A configuration namelist (in \path{./cfgs/CFG_NAME/EXP00/namelist_cfg}) is read aferwards.
128  This file contains only the namelist variables which are changed from default values, and overwrites those.
130A template can be found in \path{NEMO/OPA_SRC/module.example}.
131The effective namelist, taken in account during the run, is stored at execution time in
132an \texttt{output\_namelist\_dyn} (or \texttt{\_ice} or \texttt{\_top}) file.
133%%gm  end
135Model outputs management and specific online diagnostics are described in \autoref{chap:DIA}.
136The diagnostics includes the output of all the tendencies of the momentum and tracers equations,
137the output of tracers tendencies averaged over the time evolving mixed layer,
138the output of the tendencies of the barotropic vorticity equation,
139the computation of on-line floats trajectories...
140\autoref{chap:OBS} describes a tool which reads in observation files
141(profile temperature and salinity, sea surface temperature, sea level anomaly and sea ice concentration)
142and calculates an interpolated model equivalent value at the observation location and nearest model timestep.
143Originally developed of data assimilation, it is a fantastic tool for model and data comparison.
144\autoref{chap:ASM} describes how increments produced by data assimilation may be applied to the model equations.
145Finally, \autoref{chap:CFG} provides a brief introduction to the pre-defined model configurations
146(water column model, ORCA and GYRE families of configurations).
148%%nm: Add some words on the \NEMO\ dependencies
149The model is implemented in \fninety, with preprocessing (C pre-processor).
150It runs under UNIX.
151It is optimized for vector computers and parallelised by domain decomposition with MPI.
152All input and output is done in NetCDF (Network Common Data Format) with a optional direct access format for output.
153To ensure the clarity and readability of the code it is necessary to follow coding rules.
154The coding rules for OPA include conventions for naming variables,
155with different starting letters for different types of variables (real, integer, parameter\ldots).
156Those rules are briefly presented in \autoref{apdx:coding} and a more complete document is available .
158The model is organized with a high internal modularity based on physics.
159For example, each trend (\ie, a term in the RHS of the prognostic equation) for momentum and tracers
160is computed in a dedicated module.
161To make it easier for the user to find his way around the code, the module names follow a three-letter rule.
162For example, \mdl{traldf} is a module related to the TRAcers equation, computing the Lateral DiFfussion.
163%The complete list of module names is presented in \autoref{apdx:coding}.      %====>>>> to be done !
164Furthermore, modules are organized in a few directories that correspond to their category,
165as indicated by the first three letters of their name (\autoref{tab:chapters}).
167The manual mirrors the organization of the model.
168After the presentation of the continuous equations (\autoref{chap:PE}),
169the following chapters refer to specific terms of the equations each associated with a group of modules
174  \caption{
175    \protect\label{tab:chapters}
176    Organization of Chapters mimicking the one of the model directories.
177  }
178  \begin{center}
179    \begin{tabular}{|l|l|l|}
180      \hline
181      \autoref{chap:STP}  & -   & model time STePping environment \\
182      \hline
183      \autoref{chap:DOM}  & DOM & model DOMain \\
184      \hline
185      \autoref{chap:TRA}  & TRA & TRAcer equations (potential temperature and salinity) \\
186      \hline
187      \autoref{chap:DYN}  & DYN & DYNamic equations (momentum) \\
188      \hline
189      \autoref{chap:SBC}  & SBC & Surface Boundary Conditions \\
190      \hline
191      \autoref{chap:LBC}  & LBC & Lateral Boundary Conditions (also OBC and BDY)  \\
192      \hline
193      \autoref{chap:LDF}  & LDF & Lateral DiFfusion (parameterisations) \\
194      \hline
195      \autoref{chap:ZDF}  & ZDF & vertical (Z) DiFfusion (parameterisations)  \\
196      \hline
197      \autoref{chap:DIA}  & DIA & I/O and DIAgnostics (also IOM, FLO and TRD) \\
198      \hline
199      \autoref{chap:OBS}  & OBS & OBServation and model comparison  \\
200      \hline
201      \autoref{chap:ASM}  & ASM & ASsiMilation increment  \\
202      \hline
203      \autoref{chap:MISC} & SOL & Miscellaneous  topics (including solvers)  \\
204      \hline
205      \autoref{chap:CFG}  & -   & predefined configurations (including C1D) \\
206      \hline
207    \end{tabular}
208  \end{center}
212%% nm: the following section has to vastly remodeled to focus only on well-identified versions of \NEMO
213%% (3.4, 3.6, 4.0 and further releases). Then its formatting must be improved too.
214\subsubsection{Changes between releases}
216\NEMO/OPA, like all research tools, is in perpetual evolution.
217The present document describes the OPA version include in the release 3.4 of \NEMO.
218This release differs significantly from version 8, documented in \citet{madec.delecluse.ea_NPM98}. \\
220The main modifications from OPA v8 and \NEMO/OPA v3.2 are :
224  transition to full native \fninety, deep code restructuring and drastic reduction of CPP keys;
226  introduction of partial step representation of bottom topography
227  \citep{barnier.madec.ea_OD06, le-sommer.penduff.ea_OM09, penduff.le-sommer.ea_OS07};
229  partial reactivation of a terrain-following vertical coordinate ($s$- and hybrid $s$-$z$) with
230  the addition of several options for pressure gradient computation
231  \footnote{
232    Partial support of $s$-coordinate: there is presently no support for neutral physics in
233    $s$-coordinate and for the new options for horizontal pressure gradient computation with
234    a non-linear equation of state.
235  }
236  ;
238  more choices for the treatment of the free surface: full explicit, split-explicit or filtered schemes,
239  and suppression of the rigid-lid option;
241  non linear free surface associated with the rescaled height coordinate \zstar or $s$;
243  additional schemes for vector and flux forms of the momentum advection;
245  additional advection schemes for tracers;
247  implementation of the AGRIF package (Adaptative Grid Refinement in \fortran) \citep{debreu.vouland.ea_CG08};
249  online diagnostics : tracers trend in the mixed layer and vorticity balance;
251  rewriting of the I/O management with the use of an I/O server;
253  generalized ocean-ice-atmosphere-CO2 coupling interface, interfaced with OASIS 3 coupler;
255  surface module (SBC) that simplify the way the ocean is forced and include two bulk formulea (CLIO and CORE) and
256  which includes an on-the-fly interpolation of input forcing fields;
258  RGB light penetration and optional use of ocean color
260  major changes in the TKE schemes: it now includes a Langmuir cell parameterization \citep{axell_JGR02},
261  the \citet{mellor.blumberg_JPO04} surface wave breaking parameterization, and has a time discretization which
262  is energetically consistent with the ocean model equations \citep{burchard_OM02, marsaleix.auclair.ea_OM08};
264  tidal mixing parametrisation (bottom intensification) + Indonesian specific tidal mixing
265  \citep{koch-larrouy.madec.ea_GRL07};
267  introduction of LIM-3, the new Louvain-la-Neuve sea-ice model
268  (C-grid rheology and new thermodynamics including bulk ice salinity)
269  \citep{vancoppenolle.fichefet.ea_OM09*a, vancoppenolle.fichefet.ea_OM09*b}
272The main modifications from \NEMO/OPA v3.2 and v3.3 are:
276  introduction of a modified leapfrog-Asselin filter time stepping scheme
277  \citep{leclair.madec_OM09};
279  additional scheme for iso-neutral mixing \citep{griffies.gnanadesikan.ea_JPO98}, although it is still a "work in progress";
281  a rewriting of the bottom boundary layer scheme, following \citet{campin.goosse_T99};
283  addition of a Generic Length Scale vertical mixing scheme, following \citet{umlauf.burchard_JMR03};
285  addition of the atmospheric pressure as an external forcing on both ocean and sea-ice dynamics;
287  addition of a diurnal cycle on solar radiation \citep{bernie.guilyardi.ea_CD07};
289  river runoffs added through a non-zero depth, and having its own temperature and salinity;
291  CORE II normal year forcing set as the default forcing of ORCA2-LIM configuration;
293  generalisation of the use of \mdl{fldread} for all input fields (ocean climatology, sea-ice damping...);
295  addition of an on-line observation and model comparison (thanks to NEMOVAR project);
297  optional application of an assimilation increment (thanks to NEMOVAR project);
299  coupling interface adjusted for WRF atmospheric model;
301  C-grid ice rheology now available fro both LIM-2 and LIM-3 \citep{bouillon.maqueda.ea_OM09};
303  LIM-3 ice-ocean momentum coupling applied to LIM-2;
305  a deep re-writting and simplification of the off-line tracer component (OFF\_SRC);
307  the merge of passive and active advection and diffusion modules;
309  Use of the Flexible Configuration Manager (FCM) to build configurations,
310  generate the Makefile and produce the executable;
312  Linear-tangent and Adjoint component (TAM) added, phased with v3.0
317In addition, several minor modifications in the coding have been introduced with the constant concern of
318improving the model performance.
320The main modifications from \NEMO/OPA v3.3 and v3.4 are:
323\item finalisation of above iso-neutral mixing \citep{griffies.gnanadesikan.ea_JPO98}";
324\item "Neptune effect" parametrisation;
325\item horizontal pressure gradient suitable for s-coordinate;
326\item semi -implicit bottom friction;
327\item finalisation of the merge of passive and active tracers advection-diffusion modules;
328\item a new bulk formulae (so-called MFS);
329\item use fldread for the off-line tracer component (OFF\_SRC);
330\item use MPI point to point communications for north fold;
331\item diagnostic of transport;
334The main modifications from \NEMO/OPA v3.4 and v3.6 are:
337 \item ...;
340The main modifications from \NEMO/OPA v3.6 and v4.0 are:
343\item new definition of configurations;
344\item bulk formulation;
345\item \NEMO-wave large scale interactions;
346\item ...;
353%% Restore section heading
354\rehead{Sect.\ \thesection\ \rightmark}
Note: See TracBrowser for help on using the repository browser.