
% ================================================================
% INTRODUCTION
% ================================================================

\chapter{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 (www.locean-ipsl.upmc.fr/NEMO). 

The ocean component of \NEMO has been developed from the OPA8.2 model described in \citet{Madec1998}. 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 as follows. Chapter~\ref{PE} 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. Chapter~\ref{DOM} 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).

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

Surface boundary conditions (chapter~\ref{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). Interactive coupling to Atmospheric models is possible via the OASIS coupler \citep{OASIS2006}. 

Physical parameterisations are described in chapters~\ref{LDF} and \ref{ZDF}. 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 \citep{Gent1990} with a space and time variable coefficient \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{Large1994}, or \citet{PacPhil1981} mixing schemes.

Specific online diagnostics (not documented yet) 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 \textsc{Fortran 90}, with preprocessing (C-pre-processor). 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 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 three-letter rule.  Each module name is made of three-letter sequences. For example, \mdl{tradmp} 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 \ref{PE}), the following chapters refer to specific terms of the equations each associated with a group of modules .


\begin{table}[htbp] \label{tab1}
%\begin{center} \begin{tabular}{|p{143pt}|l|l|}	\hline
\begin{center} \begin{tabular}{|l|l|l|}	\hline
Chapter \ref{DOM}	& DOM		& Model DOMain \\		\hline
Chapter \ref{TRA}	& TRA		& TRAcer equations (potential temperature and salinity) \\   \hline
Chapter \ref{DYN}	& DYN		& DYNamic equations (momentum) \\		\hline
Chapter \ref{SBC} 	& SBC		& Surface Boundary Conditions \\			\hline
Chapter \ref{LBC}	& LBC		& Lateral Boundary Conditions  \\ 		\hline
Chapter \ref{LDF}	& LDF		& Lateral DiFfusion (parameterisations) \\	\hline
Chapter \ref{ZDF}	& ZDF		& Vertical DiFfusion  \\		\hline
Chapter \ref{MISC}	& ...		& Miscellaneous  topics	 \\			\hline
\end{tabular} 	\end{center}
\end{table}

In the current release (v2.3), LBC directory (see Chap.~\ref{LBC}) does not yet exist. When created LBC will gather OBC directory (Open Boundary Condition), \mdl{lbclnk}, \mdl{mppini} and \mdl{lib\_mpp} modules. 

 \vspace{1cm}   Nota Bene : \vspace{0.25cm}

OPA, like all research tools, is in perpetual evolution. The present document describes the OPA model include in the release 2.3 of NEMO. This release differs significantly from version 8, documented in \citet{Madec1998}. The major modifications are :\\
(1) transition to full native \textsc{Fortran} 90, deep code restructuring and drastic reduction of CPP keys, \\
(2) introduction of partial step representation of bottom topography \\
(3) 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 $s$-coordinate and for the new options for horizontal pressure gradient computation with true equation of state.}, \\ 
(4) more choices for the treatment of the free surface: full explicit, split-explicit , filtered and rigid-lid \\
(5) non linear free surface option (variable level thickness distributed on the whole water column) \\
(6) additional schemes for vector and flux forms of the momentum  advection \\
(7) addition of several advection schemes on tracers \\
 (8) implementation of the AGRIF package (Adaptative Grid Refinement in \textsc{Fortran} ) \\
(9) online diagnostics : tracers trend in the mixed layer and vorticity balance \\
(10) rewriting of the I/O management \\
(11) 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.


\colorbox{red}{Red color}: not in the current reference version (v2.3) but expected soon.
 
\colorbox{yellow}{Yellow color}: missing references, text to be updated.

