# Changeset 10496

Ignore:
Timestamp:
2019-01-10T12:22:27+01:00 (15 months ago)
Message:

Global review of the foreword and introduction chapters of the manual

Location:
NEMO/trunk/doc/latex/NEMO/subfiles
Files:
2 edited

### Legend:

Unmodified
 r10442 % ================================================================ % Chapter Foreword % ================================================================ \chapter*{Foreword} % ================================================================ % Abstract % ================================================================ \section*{Abstract} \chapter*{Abstract} The ocean engine of NEMO (Nucleus for European Modelling of the Ocean) is a primitive equation model adapted to regional and global ocean circulation problems. It is intended to be a flexible tool for studying the ocean and its interactions with the others components of the earth climate system over a wide range of space and time scales. \vspace{-40pt} Prognostic variables are the three-dimensional velocity field, a non-linear sea surface height, the \textit{Conservative} Temperature and the \textit{Absolute} Salinity. In the horizontal direction, the model uses a curvilinear orthogonal grid and in the vertical direction, a full or partial step $z$-coordinate, or $s$-coordinate, or a mixture of the two. The distribution of variables is a three-dimensional Arakawa C-type grid. Various physical choices are available to describe ocean physics, including TKE, and GLS vertical physics. {\small The ocean engine of NEMO (Nucleus for European Modelling of the Ocean) is a primitive equation model adapted to regional and global ocean circulation problems. It is intended to be a flexible tool for studying the ocean and its interactions with the others components of the earth climate system over a wide range of space and time scales. Prognostic variables are the three-dimensional velocity field, a non-linear sea surface height, the \textit{Conservative} Temperature and the \textit{Absolute} Salinity. In the horizontal direction, the model uses a curvilinear orthogonal grid and in the vertical direction, a full or partial step $z$-coordinate, or $s$-coordinate, or a mixture of the two. The distribution of variables is a three-dimensional Arakawa C-type grid. Various physical choices are available to describe ocean physics, including TKE, and GLS vertical physics. Within NEMO, the ocean is interfaced with a sea-ice model (LIM or CICE), passive tracer and biogeochemical models (TOP) and, via the OASIS coupler, with several atmospheric general circulation models. It also support two-way grid embedding via the AGRIF software. } Within NEMO, the ocean is interfaced with a sea-ice model (SI$^3$) %or \href{https://github.com/CICE-Consortium/CICE}{CICE}), passive tracer and biogeochemical models (TOP-PISCES) and, via the \href{https://portal.enes.org/oasis}{OASIS} coupler, with several atmospheric general circulation models. It also support two-way grid embedding via the \href{http://agrif.imag.fr}{AGRIF} software. % ================================================================ % Disclaimer % ================================================================ \chapter*{Disclaimer} \section*{Disclaimer} Like all components of NEMO, the ocean component is developed under the \href{http://www.cecill.info/}{CECILL license}, which is a French adaptation of the GNU GPL (General Public License). Anyone may use it freely for research purposes, and is encouraged to communicate back to the NEMO team its own developments and improvements. Like all components of NEMO, the ocean component is developed under the \href{http://www.cecill.info}{CECILL license}, which is a French adaptation of the GNU GPL (General Public License). Anyone may use it freely for research purposes, and is encouraged to communicate back to the NEMO team its own developments and improvements. The model and the present document have been made available as a service to the community. We cannot certify that the code and its manual are free of errors. Bugs are inevitable and some have undoubtedly survived the testing phase. Users are encouraged to bring them to our attention. The author assumes no responsibility for problems, errors, or incorrect usage of NEMO. \vspace{1cm} NEMO reference in papers and other publications is as follows: % ================================================================ % Citation % ================================================================ \section*{Citation} Reference for papers and other publications is as follows: \vspace{0.5cm} Madec, G., and the NEMO team, 2008: NEMO ocean engine. \textit{Note du P\^ole de mod\'{e}lisation}, Institut Pierre-Simon Laplace (IPSL), France, No 27, ISSN No 1288-1619.\\ {\sffamily NEMO ocean engine, Madec Gurvan and NEMO System Team, NEMO Consortium, Issue 27, Notes du Pôle de modélisation de l'Institut Pierre-Simon Laplace (IPSL), ISSN 1288-1619, \href{http://doi.org/10.5281/zenodo.1464816}{doi:10.5281/zenodo.1464816} } % ================================================================ % External resources % ================================================================ \section*{External resources} \vspace{0.5cm} Additional information can be found on \href{http://www.nemo-ocean.eu/}{www.nemo-ocean.eu}. \vspace{0.5cm} Additional information can be found on the \href{http://www.nemo-ocean.eu}{website} of the project and the \href{http://forge.ipsl.jussieu.fr/nemo}{forge platform} of the source code. A \href{http://listes.ipsl.fr/sympa/info/nemo-newsletter}{newsletter list} is also open for subscription to receive top-down communication from the consortium (announcements, job opportunities, ...). \biblio
 r10442 The Nucleus for European Modelling of the Ocean (\NEMO) is a framework of ocean related engines, namely OPA \footnote{OPA = Oc\'{e}an PArall\'{e}lis\'{e}} for the ocean dynamics and thermodynamics, LIM \footnote{LIM = Louvain la-neuve Ice Model} for the sea-ice dynamics and thermodynamics, TOP \footnote{TOP = Tracer in the Ocean Paradigm} for the biogeochemistry (both transport (TRP) and sources minus sinks (LOBSTER \footnote{LOBSTER = Lodyc Ocean Biogeochemical SysTem for Ecosystem and Resources}, PISCES \footnote{PISCES = Pelagic Interactions Scheme for Carbon and Ecosystem Studies})). namely OPA \footnote{OPA: Oc\'{e}an PArall\'{e}lis\'{e} (french)} for the ocean dynamics and thermodynamics, SI$^3$ \footnote{SI$^3$: Sea-Ice modelling Integrated Initiative} for the sea-ice dynamics and thermodynamics, TOP \footnote{TOP: Tracer in the Ocean Paradigm} for the biogeochemistry (both transport (TRP) and sources minus sinks (PISCES \footnote{PISCES: Pelagic Interactions Scheme for Carbon and Ecosystem Studies})). It is intended to be a flexible tool for studying the ocean and its interactions with the other components of the earth climate system (atmosphere, sea-ice, biogeochemical tracers, ...) over a wide range of space and time scales. This documentation provides information about the physics represented by the ocean component of \NEMO and a wide range of space and time scales. This manual provides information about the physics represented by the ocean component of \NEMO and the rationale for the choice of numerical schemes and the model design. More specific information about running the model on different computers, or how to set up a configuration, are found on the \NEMO web site (www.nemo-ocean.eu). The ocean component of \NEMO has been developed from the OPA model, release 8.2, described in \citet{Madec1998}. This model has been used for a wide range of applications, both regional or global, as a forced ocean model and as a model coupled with the sea-ice and/or the atmosphere. For the use of framework, a guide which gathers the \texttt{README} files spread out in the source code can be build and exported in web or printable format (see \path{./doc/rst}). An online version of the guide is also available on the \href{http://forge.ipsl.jussieu.fr/nemo}{\NEMO forge platform}. The ocean component of \NEMO has been developed from the legacy of the OPA model, release 8.2, described in \citet{Madec1998}. This model has been used for a wide range of applications, both regional or global, as a forced ocean model and as a model coupled with the sea-ice and/or the atmosphere. This manual is organised in as follows. (primitive equations, with temperature, salinity and an equation of seawater). The equations are written in a curvilinear coordinate system, with a choice of vertical coordinates ($z$, $s$, \zstar, \sstar, \ztilde, \stilde, and a mixture of them). ($z$, $s$, \zstar, \sstar, \ztilde, \stilde, and a mix of them). Momentum equations are formulated in vector invariant or flux form. Dimensional units in the meter, kilogram, second (MKS) international system are used throughout. The following chapters deal with the discrete equations. \autoref{chap:STP} presents the time domain. The model time stepping environment is a three level scheme in which the tendency terms of the equations are evaluated either centered in time, or forward, or backward depending of the nature of the term. The model time stepping environment is a three level scheme in which the tendency terms of the equations are evaluated either centered in time, or forward, or backward depending of the nature of the term. \autoref{chap:DOM} presents the space domain. The model is discretised on a staggered grid (Arakawa C grid) with masking of land areas. Vertical discretisation used depends on both how the bottom topography is represented and whether the free surface is linear or not. Full step or partial step $z$-coordinate or $s$- (terrain-following) coordinate is used with linear free surface (level position are then fixed in time). In non-linear free surface, the corresponding rescaled height coordinate formulation (\zstar or \sstar) is used Vertical discretisation used depends on both how the bottom topography is represented and whether the free surface is linear or not. Full step or partial step $z$-coordinate or $s$- (terrain-following) coordinate is used with linear free surface (level position are then fixed in time). In non-linear free surface, the corresponding rescaled height coordinate formulation (\zstar or \sstar) is used (the level position then vary in time as a function of the sea surface heigh). The following two chapters (\autoref{chap:TRA} and \autoref{chap:DYN}) describe the discretisation of the prognostic equations for the active tracers and the momentum. Explicit, split-explicit and filtered free surface formulations are implemented. A number of numerical schemes are available for momentum advection, for the computation of the pressure gradients, as well as for the advection of tracers (second or higher order advection schemes, including positive ones). Surface boundary conditions (\autoref{chap:SBC}) can be implemented as prescribed fluxes, or bulk formulations for the surface fluxes (wind stress, heat, freshwater). A number of numerical schemes are available for momentum advection, for the computation of the pressure gradients, as well as for the advection of tracers (second or higher order advection schemes, including positive ones). Surface boundary conditions (\autoref{chap:SBC}) can be implemented as prescribed fluxes, or bulk formulations for the surface fluxes (wind stress, heat, freshwater). The model allows penetration of solar radiation. There is an optional geothermal heating at the ocean bottom. Within the \NEMO system the ocean model is interactively coupled with a sea ice model (LIM) and with biogeochemistry models (PISCES, LOBSTER). Within the \NEMO system the ocean model is interactively coupled with a sea ice model (SI$^3$) and a biogeochemistry model (PISCES). Interactive coupling to Atmospheric models is possible via the OASIS coupler \citep{OASIS2006}. Two-way nesting is also available through an interface to the AGRIF package (Adaptative Grid Refinement in \fortran) \citep{Debreu_al_CG2008}. The interface code for coupling to an alternative sea ice model (CICE, \citet{Hunke2008}) has now been upgraded so that it works for both global and regional domains, although AGRIF is still not available. % Needs to be reviewed %The interface code for coupling to an alternative sea ice model (CICE, \citet{Hunke2008}) has now been upgraded so %that it works for both global and regional domains, although AGRIF is still not available. Other model characteristics are the lateral boundary conditions (\autoref{chap:LBC}). Global configurations of the model make use of the ORCA tripolar grid, with special north fold boundary condition. Free-slip or no-slip boundary conditions are allowed at land boundaries. Closed basin geometries as well as periodic domains and open boundary conditions are possible. Closed basin geometries as well as periodic domains and open boundary conditions are possible. Physical parameterisations are described in \autoref{chap:LDF} and \autoref{chap:ZDF}. \citet{Treguier1997}. The model has vertical harmonic viscosity and diffusion with a space and time variable coefficient, with options to compute the coefficients with \citet{Blanke1993}, \citet{Pacanowski_Philander_JPO81}, or \citet{Umlauf_Burchard_JMS03} mixing schemes. \vspace{1cm} with options to compute the coefficients with \citet{Blanke1993}, \citet{Pacanowski_Philander_JPO81}, or \citet{Umlauf_Burchard_JMS03} mixing schemes. %%gm    To be put somewhere else .... \noindent CPP keys and namelists are used for inputs to the code.  \newline \noindent \index{CPP keys} CPP keys \newline %%nm    We should consider creating a glossary for all this kind of stuff (terms, acronyms and symbols) %%      http://en.wikibooks.org/wiki/LaTeX/Glossary \noindent CPP keys and namelists are used as inputs to the code. \noindent \index{CPP keys} CPP keys Some 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. Usual coding looks like : Usual coding looks like: \begin{forlines} #if defined key_option1 The 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: containing all the \fortran namelists needed. The implementation in NEMO uses a 2-step process. For each \fortran namelist, two files are read: \begin{enumerate} \item A reference namelist (in \path{CONFIG/SHARED/namelist_ref}) is read first. A reference namelist (in \path{./cfgs/SHARED/namelist_ref}) is read first. This file contains all the namelist variables which are initialised to default values \item A configuration namelist (in \path{CONFIG/CFG_NAME/EXP00/namelist_cfg}) is read aferwards. A configuration namelist (in \path{./cfgs/CFG_NAME/EXP00/namelist_cfg}) is read aferwards. This file contains only the namelist variables which are changed from default values, and overwrites those. \end{enumerate} A template can be found in \path{NEMO/OPA_SRC/module.example}. The effective namelist, taken in account during the run, is stored at execution time in an output\_namelist\_dyn (or \_ice or \_top) file. \vspace{1cm} an \texttt{output\_namelist\_dyn} (or \texttt{\_ice} or \texttt{\_top}) file. %%gm  end (water column model, ORCA and GYRE families of configurations). The model is implemented in \fninety, with preprocessing (C-pre-processor). %%nm: Add some words on the NEMO dependencies The model is implemented in \fninety, with preprocessing (C pre-processor). It runs under UNIX. It is optimized for vector computers and parallelised by domain decomposition with MPI. The coding rules for OPA include conventions for naming variables, with different starting letters for different types of variables (real, integer, parameter\ldots). Those rules are briefly presented in \autoref{apdx:D} and a more complete document is available on the \NEMO web site. Those rules are briefly presented in \autoref{apdx:D} and a more complete document is available . The model is organized with a high internal modularity based on physics. is computed in a dedicated module. To make it easier for the user to find his way around the code, the module names follow a three-letter rule. For example, \mdl{traldf} is a module related to the TRAcers equation, computing the Lateral DiFfussion. For example, \mdl{traldf} is a module related to the TRAcers equation, computing the Lateral DiFfussion. %The complete list of module names is presented in \autoref{apdx:D}.      %====>>>> to be done ! Furthermore, modules are organized in a few directories that correspond to their category, as indicated by the first three letters of their name (\autoref{tab:chap}). as indicated by the first three letters of their name (\autoref{tab:chapters}). The manual mirrors the organization of the model. After the presentation of the continuous equations (\autoref{chap:PE}), the following chapters refer to specific terms of the equations each associated with a group of modules (\autoref{tab:chap}). the following chapters refer to specific terms of the equations each associated with a group of modules (\autoref{tab:chap}). %--------------------------------------------------TABLE-------------------------------------------------- \begin{table}[!t] % \begin{center} \begin{tabular}{|p{143pt}|l|l|} \hline \caption{ \protect\label{tab:chap}   Organization of Chapters mimicking the one of the model directories. } \caption{ \protect\label{tab:chapters} Organization of Chapters mimicking the one of the model directories. } \begin{center} \begin{tabular}{|l|l|l|}  \hline \autoref{chap:STP}   & -                 & model time STePping environment \\    \hline \autoref{chap:DOM}   & DOM    & model DOMain \\    \hline \autoref{chap:TRA}   & TRA    & TRAcer equations (potential temperature and salinity) \\   \hline \autoref{chap:DYN}   & DYN    & DYNamic equations (momentum) \\      \hline \autoref{chap:SBC}   & SBC    & Surface Boundary Conditions \\       \hline \autoref{chap:LBC}   & LBC    & Lateral Boundary Conditions (also OBC and BDY)  \\     \hline \autoref{chap:LDF}   & LDF    & Lateral DiFfusion (parameterisations) \\   \hline \autoref{chap:ZDF}   & ZDF    & vertical (Z) DiFfusion (parameterisations)  \\      \hline \autoref{chap:DIA}   & DIA    & I/O and DIAgnostics (also IOM, FLO and TRD) \\      \hline \autoref{chap:OBS}   & OBS    & OBServation and model comparison  \\    \hline \autoref{chap:ASM}   & ASM    & ASsiMilation increment  \\     \hline \autoref{chap:MISC}  & SOL    & Miscellaneous  topics (including solvers)  \\       \hline \autoref{chap:CFG}   &  -        & predefined configurations (including C1D) \\     \hline \begin{tabular}{|l|l|l|} \hline \autoref{chap:STP}  & -   & model time STePping environment \\ \hline \autoref{chap:DOM}  & DOM & model DOMain \\ \hline \autoref{chap:TRA}  & TRA & TRAcer equations (potential temperature and salinity) \\ \hline \autoref{chap:DYN}  & DYN & DYNamic equations (momentum) \\ \hline \autoref{chap:SBC}  & SBC & Surface Boundary Conditions \\ \hline \autoref{chap:LBC}  & LBC & Lateral Boundary Conditions (also OBC and BDY)  \\ \hline \autoref{chap:LDF}  & LDF & Lateral DiFfusion (parameterisations) \\ \hline \autoref{chap:ZDF}  & ZDF & vertical (Z) DiFfusion (parameterisations)  \\ \hline \autoref{chap:DIA}  & DIA & I/O and DIAgnostics (also IOM, FLO and TRD) \\ \hline \autoref{chap:OBS}  & OBS & OBServation and model comparison  \\ \hline \autoref{chap:ASM}  & ASM & ASsiMilation increment  \\ \hline \autoref{chap:MISC} & SOL & Miscellaneous  topics (including solvers)  \\ \hline \autoref{chap:CFG}  & -   & predefined configurations (including C1D) \\ \hline \end{tabular} \end{center} %-------------------------------------------------------------------------------------------------------------- %% nm: the following section has to vastly remodeled to focus only on well-identified versions of NEMO %% (3.4, 3.6, 4.0 and further releases). Then its formatting must be improved too. \subsubsection{Changes between releases} NEMO/OPA, like all research tools, is in perpetual evolution. The present document describes the OPA version include in the release 3.4 of NEMO. This release differs significantly from version 8, documented in \citet{Madec1998}.\\ $\bullet$ The main modifications from OPA v8 and NEMO/OPA v3.2 are :\\ \begin{enumerate} This release differs significantly from version 8, documented in \citet{Madec1998}. \\ The main modifications from OPA v8 and NEMO/OPA v3.2 are : \begin{itemize} \item transition to full native \fninety, deep code restructuring and drastic reduction of CPP keys; partial reactivation of a terrain-following vertical coordinate ($s$- and hybrid $s$-$z$) with the addition of several options for pressure gradient computation \footnote{Partial support of $s$-coordinate: there is presently no support for neutral physics in \footnote{ Partial support of $s$-coordinate: there is presently no support for neutral physics in $s$-coordinate and for the new options for horizontal pressure gradient computation with a non-linear equation of state. }; } ; \item more choices for the treatment of the free surface: full explicit, split-explicit or filtered schemes, and suppression of the rigid-lid option; \item non linear free surface associated with the rescaled height coordinate \zstar or \textit{s}; non linear free surface associated with the rescaled height coordinate \zstar or $s$; \item additional schemes for vector and flux forms of the momentum advection; (C-grid rheology and new thermodynamics including bulk ice salinity) \citep{Vancoppenolle_al_OM09a, Vancoppenolle_al_OM09b} \end{enumerate} \vspace{1cm} $\bullet$ The main modifications from NEMO/OPA v3.2 and v3.3 are :\\ \begin{enumerate} \end{itemize} The main modifications from NEMO/OPA v3.2 and v3.3 are: \begin{itemize} \item introduction of a modified leapfrog-Asselin filter time stepping scheme \item Linear-tangent and Adjoint component (TAM) added, phased with v3.0 \end{enumerate} \end{itemize} \vspace{1cm} In addition, several minor modifications in the coding have been introduced with the constant concern of improving the model performance. \vspace{1cm} $\bullet$ The main modifications from NEMO/OPA v3.3 and  v3.4 are :\\ \begin{enumerate} improving the model performance. The main modifications from NEMO/OPA v3.3 and v3.4 are: \begin{itemize} \item finalisation of above iso-neutral mixing \citep{Griffies_al_JPO98}"; \item "Neptune effect" parametrisation; \item horizontal pressure gradient suitable for s-coordinate; \item semi-implicit bottom friction; \item semi -implicit bottom friction; \item finalisation of the merge of passive and active tracers advection-diffusion modules; \item a new bulk formulae (so-called MFS); \item use fldread for the off-line tracer component (OFF\_SRC); \item use MPI point to point communications  for north fold; \item use MPI point to point communications for north fold; \item diagnostic of transport; \end{enumerate} \vspace{1cm} $\bullet$ The main modifications from NEMO/OPA v3.4 and  v3.6 are :\\ \begin{enumerate} \item ... ; \end{enumerate} \vspace{1cm} $\bullet$ The main modifications from NEMO/OPA v3.6 and  v4.0 are :\\ \begin{enumerate} \item new definition of configurations ; \item bulk formulation ; \item NEMO-wave large scale interactions ; \item ... ; \end{enumerate} \end{itemize} The main modifications from NEMO/OPA v3.4 and v3.6 are: \begin{itemize} \item ...; \end{itemize} The main modifications from NEMO/OPA v3.6 and v4.0 are: \begin{itemize} \item new definition of configurations; \item bulk formulation; \item NEMO-wave large scale interactions; \item ...; \end{itemize} \biblio