source: trunk/NEMO/DOC/BETA/Chapters/0_page_de_garde_old.tex @ 707

%\begin{figure}[htbp]
%\centerline{\includegraphics[width=1.64in,height=11.72in]{OPA9_Chap_0_Introduction1.eps}}
%\label{fig1}
%\end{figure}

\textbf{Institut Pierre Simon Laplace}

\textbf{des Sciences de l'Environnement Global}

\textit{Notes du P\^{o}le de Mod\'{e}lisation}

NEMO : the OPA ocean engine

(NEMO version 2.3)

Gurvan Madec, {\ldots} 

Laboratoire d'Oc\'{e}anographie et du Climat: Exp\'{e}rimentation 

et Approches Num\'{e}riques

%\begin{figure}[htbp]
%\centerline{\includegraphics[width=4.58in,height=4.35in]{OPA9_Chap_0_Introduction2.eps}}
%\label{fig2}
%\end{figure}

\newpage 
\begin{center}
NEMO : the OPA ocean engine
\end{center}

Gurvan Madec

Laboratoire d'Oc\'{e}anographie et du Climat: Exp\'{e}rimentation Approches 
Num\'{e}riques

CNRS/IRD/UPMC, UMR 7617

\subsection{Abstract}
\label{subsec:abstract}
OPA is the ocean engine of NEMO, a framework of ocean related components 
developed for both research and operational purposes. It is a primitive 
equation model adapted to regional and global ocean circulation. It is 
intended to be a flexible tool for studying the ocean and its interactions 
with the others components of the earth climate system (atmosphere, sea-ice, 
biogeochemical tracers, ...) over a wide range of space and time scales. 
Prognostic variables are the three-dimensional velocity field, the sea 
surface height, the temperature and the salinity. In the horizontal 
direction, the model uses a curvilinear orthogonal grid and in the vertical 
direction, a $z$ full or partial step 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 a 1.5 turbulent closure or a KPP scheme for the vertical 
mixing. Within NEMO, OPA is interfaced with a sea-ice model (LIM), passive 
tracer and biogeochemical models (TOP) and, via the OASIS coupler, with 
several atmospheric general circulation models. In addition, it can be run 
on many different computers, including shared and distributed memory 
multiprocessor computers.

\textsc{\textbf{R\'{e}sum\'{e}}}

OPA est le moteur oc\'{e}anique de NEMO, un syst\`{e}me de mod\'{e}lisation 
de l'oc\'{e}an d\'{e}velopp\'{e} \`{a} des fins de recherche et 
d'oc\'{e}anographie op\'{e}rationnelle. Ce moteur est un mod\`{e}le aux 
\'{e}quations primitives de la circulation oc\'{e}anique r\'{e}gionale et 
globale. Il se veut un outil flexible pour \'{e}tudier sur un vaste spectre 
spatiotemporel l'oc\'{e}an et ses interactions avec les autres composantes 
du syst\`{e}me climatique terrestre (atmosph\`{e}re, glace de mer, traceurs 
biog\'{e}ochimiques...). Les variables pronostiques sont le champ 
tridimensionnel de vitesse, la hauteur de la mer , la temperature et la 
salinit\'{e}. La distribution des variables se fait sur une grille $C$ 
d'Arakawa tridimensionnelle utilisant une coordonn\'{e}e verticale $z$ \`{a} 
niveaux entiers ou partiels, ou une coordonn\'{e}e$ s$, ou encore une 
combinaison des deux. Diff\'{e}rents choix sont propos\'{e}s pour 
d\'{e}crire la physique oc\'{e}anique, incluant notamment une fermeture 
turbulente d'ordre 1.5 ou un sch\'{e}ma KPP pour le m\'{e}lange vertical. 
Via l'infrastructure NEMO, OPA est interfac\'{e} avec un mod\`{e}le de glace 
de mer, des mod\`{e}les biog\'{e}ochimiques et de traceur passif, et, via le 
coupleur OASIS, \`{a} plusieurs mod\`{e}les de circulation g\'{e}n\'{e}rale 
atmosph\'{e}rique. En outre, il peut \^{e}tre ex\'{e}cut\'{e} sur de 
nombreux calculateurs, y compris des calculateurs multiprocesseurs \`{a} 
m\'{e}moire partag\'{e}e ou distribu\'{e}e.

\newpage 
\textbf{PLAN :}

Put it here

\textsc{\textbf{Disclaimer 1}}

\textsc{\textbf{Foreword 3}}

\textsc{\textbf{Introduction 4}}

\textsc{\textbf{Disclaimer}}

OPA (an acronym for Ocean PArall\'{e}lis\'{e}) is the ocean component of 
NEMO (Nucleus for European Modelling of the Ocean (\underline 
{www.locean-ipsl.upmc.fr/NEMO}). Like all components of NEMO, it is 
developed under the CECILL license, which is a french adaptation of the GNU 
\textbf{GPL} (General Public license). Anyone may use OPA 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 OPA.

The OPA OGCM reference in papers and other publications is as follows: 

Madec, G., 2007: NEMO: the OPA ocean engine. Note du P\^{o}le de 
mod\'{e}lisation, Institut Pierre-Simon Laplace (IPSL), France, N\r{ }XX, 
YYpp.

Gurvan Madec: gm@locean-ipsl.upmc.fr

{\ldots}.

\textsc{\textbf{Foreword}}

OPA is the ocean engine of the Nucleus of European Model of the Ocean 
(NEMO). This model, like all research tools, is in perpetual evolution. The 
present document describes the OPA model include in the release 2.3 of NEMO. 
This is the release 9 of OPA. This version differs significantly from 
version 8, documented in Madec \textit{et al.} (1998). The major modifications are 

(1) transition to full native Fortran 90, deep code restructuring and 
drastic reduction of CPP keys, 

(2) introduction of partial step representation of bottom topography 

(3) reactivation of a terrain-following vertical coordinate 
($s-$coordinates) with the addition of several options for pressure gradient 
computation, 

(4) mixed $z-s$ coordinate

(5) more choices for the treatment of the free surface: full explicit, 
split-explicit , filtered and rigid-lid 

(6) non linear free surface option (variable level thickness distributed on 
the whole water column) 

(7) additional schemes for vector and flux forms of the momentum advection

(8) addition of several advection schemes on tracers

(9) implementation of the AGRIF package (Adaptative Grid Refinement in 
Fortran)

(10) online diagnostics : tracers trend in the mixed layer and vorticity 
balance

(11) rewriting of the I/O management

(12) OASIS 3 and 4 couplers interfacing with atmospheric global circulation 
models.

In addition, several minor modifications in the coding have been introduced 
with the constant concern of improving performance on both scalar and vector 
computers. 

At the time of this writing, the current release is NEMO 2.3. The new 
surface module described in this document is not yet part of the current 
distribution.

\newpage 

\textsc{\textbf{Introduction}}

The Nucleus for European Modelling of the Ocean (NEMO) is a framework of 
ocean related engines, namely OPA for the Ocean dynamics and thermodynamics, 
LIM for the sea-ice dynamics and thermodynamics, TOP for the biogeochemistry 
(both transport (TRP) and sources minus sinks (LOBSTER, PISCES). It is 
intended to be a flexible tool for studying the ocean and its interactions 
with the others 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 
OPA ocean model 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 (\underline {www.locean-ipsl.upmc.fr/NEMO}). 

The ocean component of NEMO has been developed from the OPA8.2 model 
described in Madec \textit{et al.} (1998). This model has been used for a wide range of 
applications, either regional or global, as a forced ocean model or coupled 
with the atmosphere. A complete list of references is found on the NEMO web 
site. 

This manual is organised in four parts. The first part presents the model 
basics, i.e. the equations and their assumptions, the vertical coordinates 
used, and the subgrid scale physics. This part deals with the continuous 
equations of the model (primitive equations, with potential temperature, 
salinity and an equation of state). The equations are written in a 
curvilinear coordinate system, with a choice of vertical coordinates ($z$, $s$, 
and variable volumes). Momentum equations are formulated in the vector 
invariant form. The model equations are written in dimensional units in the 
meter, kilogram, second (MKS) international system 

The following chapters deal with the discrete equations. The second chapter 
presents the space and time domain. The model is discretised on a staggered 
grid (Arakawa C grid) with masking of land areas. Vertical discretisation 
uses $z$ coordinates (including partial step), $s$ (terrain-following) coordinate 
(fixed volume thickness and linear free surface), or$ s* $coordinate (variable 
volume thickness and nonlinear free surface). The following chapters 
describe the discretisation of the prognostic equations (momentum and 
tracers). Explicit, split-explicit or implicit free surface formulations are 
implemented as well as arid-lid approximation. 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).

Physical parameterisations are described in chapters The model includes an 
implicit treatment of vertical viscosity and diffusivity. The lateral 
Laplacian and biharmonic viscosity and diffusion can be rotated following a 
geopotential or neutral direction. There is an optional eddy induced 
velocity (Gent and McWilliams 1992) with a space and time variable 
coefficient, with options to compute the coefficients with Tr\'{e}guier et 
al. (199X), or Visbeck et al. XXX) schemes. The model has vertical harmonic 
viscosity and diffusion with a space and time variable coefficient, with 
options to compute the coefficients with Blanke and Delecluse (1992), Large 
et al. (1994), or Pacanowski and Philander (1981) mixing schemes.

Optional tidal mixing parametrisation

Other model characteristics (chapter {\ldots}) are the lateral boundary 
conditions. 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. 

Surface boundary conditions 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).Interactive coupling to Atmospheric models is 
possible via the OASIS (ref!!!) coupler. 

Specific online diagnostics are available in the model: output of all the 
tendencies of the momentum and tracers equations, output of tracers 
tendencies averaged over the time evolving mixed layer.

The model is implemented in Fortran 90, with preprocessing (C preprocessor). 
It runs under UNIX. It is optimized for vector computers and parallelised by 
domain decomposition with MPI. All input and output is done in NetCDF 
(Network Common Data Format) with a optional direct access format for 
output. To ensure the clarity and readability of the code it is necessary to 
follow \textit{coding rules}. 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 presented in a document 
available on the NEMO web site..

The model is organized with a high internal modularity based on physics. In 
particular, each trend (e.g., a term in the rhs of the prognostic equation) 
for momentum and tracers is computed in a dedicated module. To make it 
easier for the user to find his way around the code, the module names follow 
the \textit{three-letter rule}. Each module name is made of three-letter sequences. For example, 
TRADMP.F90 is a module related to the TRAcers equation, computing the 
DaMPing. The complete list of module names is presented in annex. 
Furthermore, modules are organized in a few directories that correspond to 
their category, as indicated by the first three letters of their name. 

The manual follows this organization. After the presentation of the 
continuous equations (chapter 1), the following chapters refer to specific 
terms of the equations each associated with a group of modules .

\begin{table}[htbp]
\begin{center}
\begin{tabular}{|p{143pt}|l|l|}
\hline
Chapter 2& 
DOM& 
Model DOMain \\
\hline
Chapter 3& 
DYN& 
DYNamic equations (momentum) \\
\hline
Chapter 4& 
TRA& 
TRAcer equations (potential temperature and salinity) \\
\hline
Chapter 5 & 
SBC& 
Surface Boundary Conditions \\
\hline
Chapter 6& 
LDF& 
Lateral DiFfusion (parameterisations) \\
\hline
Chapter 7& 
ZDF& 
Vertical DiFfusion  \\
\hline
Chapter 8& 
OBC, lbclnk module& 
Lateral boundary conditions  \\
\hline
Chapter 9& 
miscellaneous& 
 \\
\hline
\end{tabular}
\label{tab1}
\end{center}
\end{table}

\textbf{Nota Bene :}

Red color : not in the current reference version (v2.3beta) but expected 
soon

Yellow : missing references, text to be updated{\ldots}

\end{document}