% ================================================================
% Chapter Ñ Configurations
% ================================================================
\chapter{Configurations}
\label{CFG}
\minitoc

\newpage
$\ $\newline    % force a new ligne

% ================================================================
% Introduction
% ================================================================
\section{Introduction}
\label{CFG_intro}


The purpose of this part of the manual is to introduce the \NEMO predefined configuration. 
These configurations are offered as means to explore various numerical and physical options, 
thus allowing the user to verify that the code is performing in a manner consistent with that 
we are running. This form of verification is critical as one adopts the code for his or her particular 
research purposes. The test cases also provide a sense for some of the options available 
in the code, though by no means are all options exercised in the predefined configurations.


%There is several predefined ocean configuration which use is controlled by a specific CPP key. 

%The key set the domain sizes (\jp{jpiglo}, \jp{jpjglo}, \jp{jpk}), the mesh and the bathymetry, 
%and, in some cases, add to the model physics some specific treatments.


% ================================================================
% 1D model functionality
% ================================================================
\section{Water column model: 1D model (C1D) (\key{c1d})}
\label{CFG_c1d}

The 1D model option simulates a stand alone water column within the 3D \NEMO system. 
It can be applied to the ocean alone or to the ocean-ice system and can include passive tracers 
or a biogeochemical model. It is set up by defining the \key{c1d} CPP key. 
The 1D model is a very useful tool  
\textit{(a)} to learn about the physics and numerical treatment of vertical mixing processes ; 
\textit{(b)} to investigate suitable parameterisations of unresolved turbulence (surface wave
breaking, Langmuir circulation, ...) ; 
\textit{(c)} to compare the behaviour of different vertical mixing schemes  ; 
\textit{(d)} to perform sensitivity studies on the vertical diffusion at a particular point of an ocean domain ; 
\textit{(d)} to produce extra diagnostics, without the large memory requirement of the full 3D model.

The methodology is based on the use of the zoom functionality over the smallest possible 
domain : a 3 x 3 domain centred on the grid point of interest (see \S\ref{MISC_zoom}), 
with some extra routines. There is no need to define a new mesh, bathymetry, 
initial state or forcing, since the 1D model will use those of the configuration it is a zoom of. 
The chosen grid point is set in par\_oce.F90 module by setting the \jp{jpizoom} and \jp{jpjzoom} 
parameters to the indices of the location of the chosen grid point.

The 1D model has some specifies. First, all the horizontal derivatives are assumed to be zero. 
Therefore a simplified \rou{step} routine is used (\rou{step\_c1d}) in which both lateral tendancy 
terms and lateral physics are not called, and the vertical velocity is zero (so far, no attempt at
introducing a Ekman pumping velocity has been made).
Second, the two components of the velocity are moved on a $T$-point. 
This requires a specific treatment of the Coriolis term (see \rou{dyncor\_c1d}) and of the 
dynamic time stepping (\rou{dynnxt\_c1d}).
All the relevant modules can be found in the NEMOGCM/NEMO/OPA\_SRC/C1D directory of 
the \NEMO distribution.

% to be added:  a test case on the yearlong Ocean Weather Station (OWS) Papa dataset of Martin (1985)

% ================================================================
% ORCA family configurations
% ================================================================
\section{ORCA family: global ocean with tripolar grid (\key{orca\_rX})}
\label{CFG_orca}

The ORCA family is a series of global ocean configurations that are run together with 
the LIM sea-ice model (ORCA-LIM) and possibly with PISCES biogeochemical model 
(ORCA-LIM-PISCES), using various resolutions.


%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
\begin{figure}[!t]   \begin{center}
\includegraphics[width=0.98\textwidth]{./TexFiles/Figures/Fig_ORCA_NH_mesh.pdf}
\caption{  \label{Fig_MISC_ORCA_msh}     
ORCA mesh conception. The departure from an isotropic Mercator grid start poleward of 20\deg N.
The two "north pole" are the foci of a series of embedded ellipses (blue curves) 
which are determined analytically and form the i-lines of the ORCA mesh (pseudo latitudes). 
Then, following \citet{Madec_Imbard_CD96}, the normal to the series of ellipses (red curves) is computed 
which provide the j-lines of the mesh (pseudo longitudes).  }
\end{center}   \end{figure}
%>>>>>>>>>>>>>>>>>>>>>>>>>>>>

% -------------------------------------------------------------------------------------------------------------
%       ORCA tripolar grid
% -------------------------------------------------------------------------------------------------------------
\subsection{ORCA tripolar grid}
\label{CFG_orca_grid}

The ORCA grid is a tripolar is based on the semi-analytical method of \citet{Madec_Imbard_CD96}. 
It allows to construct a global orthogonal curvilinear ocean mesh which has no singularity point inside 
the computational domain since two north mesh poles are introduced and placed on lands.
The method involves defining an analytical set of mesh parallels in the stereographic polar plan, 
computing the associated set of mesh meridians, and projecting the resulting mesh onto the sphere. 
The set of mesh parallels used is a series of embedded ellipses which foci are the two mesh north 
poles (Fig.~\ref{Fig_MISC_ORCA_msh}). The resulting mesh presents no loss of continuity in 
either the mesh lines or the scale factors, or even the scale factor derivatives over the whole 
ocean domain, as the mesh is not a composite mesh. 
%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
\begin{figure}[!tbp]  \begin{center}
\includegraphics[width=1.0\textwidth]{./TexFiles/Figures/Fig_ORCA_NH_msh05_e1_e2.pdf}
\includegraphics[width=0.80\textwidth]{./TexFiles/Figures/Fig_ORCA_aniso.pdf}
\caption {  \label{Fig_MISC_ORCA_e1e2}
\textit{Top}: Horizontal scale factors ($e_1$, $e_2$) and 
\textit{Bottom}: ratio of anisotropy ($e_1 / e_2$)
for ORCA 0.5\deg ~mesh. South of 20\deg N a Mercator grid is used ($e_1 = e_2$) 
so that the anisotropy ratio is 1. Poleward of 20\deg N, the two "north pole" 
introduce a weak anisotropy over the ocean areas ($< 1.2$) except in vicinity of Victoria Island 
(Canadian Arctic Archipelago). }
\end{center}   \end{figure}
%>>>>>>>>>>>>>>>>>>>>>>>>>>>>


The method is applied to Mercator grid ($i.e.$ same zonal and meridional grid spacing) poleward 
of $20\deg$N, so that the Equator is a mesh line, which provides a better numerical solution 
for equatorial dynamics. The choice of the series of embedded ellipses (position of the foci and 
variation of the ellipses) is a compromise between maintaining  the ratio of mesh anisotropy 
($e_1 / e_2$) close to one in the ocean (especially in area of strong eddy activities such as 
the Gulf Stream) and keeping the smallest scale factor in the northern hemisphere larger 
than the smallest one in the southern hemisphere.
The resulting mesh is shown in Fig.~\ref{Fig_MISC_ORCA_msh} and \ref{Fig_MISC_ORCA_e1e2} 
for a half a degree grid (ORCA\_R05). The smallest ocean scale factor is found in along  
Antarctica, while the ratio of anisotropy remains close to one except near the Victoria Island 
in the Canadian Archipelago. 

% -------------------------------------------------------------------------------------------------------------
%       ORCA-LIM(-PISCES) configurations
% -------------------------------------------------------------------------------------------------------------
\subsection{ORCA pre-defined resolution}
\label{CFG_orca_resolution}


The NEMO system is provided with five built-in ORCA configurations which differ in the 
horizontal resolution. The value of the resolution is given by the resolution at the Equator 
expressed in degrees. Each of configuration is set through a CPP key, \key{orca\_rX} 
(with X being an indicator of the resolution), which set the grid size and configuration 
name parameters  (Tab.~\ref{Tab_ORCA}).
.

%--------------------------------------------------TABLE--------------------------------------------------
\begin{table}[!t]     \begin{center}
\begin{tabular}{p{4cm} c c c c}
CPP key          	             & \jp{jp\_cfg} &  \jp{jpiglo} & \jp{jpiglo} &       \\  
\hline  \hline
\key{orca\_r4} 	    &        4         &         92     &      76      &       \\
\key{orca\_r2}       &        2         &       182     &    149      &        \\
\key{orca\_r1}       &        1         &       362     &     292     &        \\
\key{orca\_r05}     &        05       &       722     &     511     &        \\
\key{orca\_r025}   &        025     &      1442    &   1021     &        \\
%\key{orca\_r8}       &        8         &      2882    &   2042     &        \\
%\key{orca\_r12}     &      12         &      4322    &   3062      &       \\
\hline   \hline
\end{tabular}
\caption{ \label{Tab_ORCA}   
Set of predefined parameters for ORCA family configurations.
In all cases, the name of the configuration is set to "orca" ($i.e.$ \jp{cp\_cfg}~=~orca). }
\end{center}
\end{table}
%--------------------------------------------------------------------------------------------------------------


The ORCA\_R2 configuration has the following specificity : starting from a 2\deg~ORCA mesh, 
local mesh refinements were applied to the Mediterranean, Red, Black and Caspian Seas, 
so that the resolution is $1\deg \time 1\deg$ there. A local transformation were also applied 
with in the Tropics in order to refine the meridional resolution up to 0.5\deg at the Equator.

The ORCA\_R1 configuration has only a local tropical transformation  to refine the meridional 
resolution up to 1/3\deg~at the Equator. Note that the tropical mesh refinements in ORCA\_R2 
and R1 strongly increases the mesh anisotropy there.

The ORCA\_R05 and higher global configurations do not incorporate any regional refinements.  

For ORCA\_R1 and R025, setting the configuration key to 75 allows to use 75 vertical levels, 
otherwise 46 are used. In the other ORCA configurations, 31 levels are used 
(see Tab.~\ref{Tab_orca_zgr} and Fig.~\ref{Fig_zgr}).

Only the ORCA\_R2 is provided with all its input files in the \NEMO distribution. 
It is very similar to that used as part of the climate model developed at IPSL for the 4th IPCC 
assessment of climate change (Marti et al., 2009). It is also the basis for the \NEMO contribution 
to the Coordinate Ocean-ice Reference Experiments (COREs) documented in \citet{Griffies_al_OM09}. 

This version of ORCA\_R2 has 31 levels in the vertical, with the highest resolution (10m) 
in the upper 150m (see Tab.~\ref{Tab_orca_zgr} and Fig.~\ref{Fig_zgr}). 
The bottom topography and the coastlines are derived from the global atlas of Smith and Sandwell (1997). 
The default forcing employ the boundary forcing from \citet{Large_Yeager_Rep04} (see \S\ref{SBC_blk_core}), 
which was developed for the purpose of running global coupled ocean-ice simulations 
without an interactive atmosphere. This \citet{Large_Yeager_Rep04} dataset is available 
through the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}. 
The "normal year" of \citet{Large_Yeager_Rep04} has been chosen of the \NEMO distribution 
since release v3.3. 

ORCA\_R2 pre-defined configuration can also be run with an AGRIF zoom over the Agulhas 
current area ( \key{agrif}  defined) and,  by setting the key \key{arctic} or \key{antarctic}, 
a regional Arctic or peri-Antarctic configuration is extracted from an ORCA\_R2 or R05 configurations
using sponge layers at open boundaries. 

% -------------------------------------------------------------------------------------------------------------
%       GYRE family: double gyre basin
% -------------------------------------------------------------------------------------------------------------
\section{GYRE family: double gyre basin (\key{gyre})}
\label{MISC_config_gyre}

The GYRE configuration \citep{Levy_al_OM10} have been built to simulated 
the seasonal cycle of a double-gyre box model. It consist in an idealized domain 
similar to that used in the studies of \citet{Drijfhout_JPO94} and \citet{Hazeleger_Drijfhout_JPO98, 
Hazeleger_Drijfhout_JPO99, Hazeleger_Drijfhout_JGR00, Hazeleger_Drijfhout_JPO00}, 
over which an analytical seasonal forcing is applied. This allows to investigate the 
spontaneous generation of a large number of interacting, transient mesoscale eddies 
and their contribution to the large scale circulation. 

The domain geometry is a closed rectangular basin on the $\beta$-plane centred 
at $\sim 30\deg$N and rotated by 45\deg, 3180~km long, 2120~km wide 
and 4~km deep (Fig.~\ref{Fig_MISC_strait_hand}). 
The domain is bounded by vertical walls and by a ßat bottom. The configuration is 
meant to represent an idealized North Atlantic or North Pacific basin. 
The circulation is forced by analytical profiles of wind and buoyancy ßuxes. 
The applied forcings vary seasonally in a sinusoidal manner between winter 
and summer extrema \citep{Levy_al_OM10}. 
The wind stress is zonal and its curl changes sign at 22\deg N and 36\deg N. 
It forces a subpolar gyre in the north, a subtropical gyre in the wider part of the domain 
and a small recirculation gyre in the southern corner. 
The net heat ßux takes the form of a restoring toward a zonal apparent air 
temperature profile. A portion of the net heat ßux which comes from the solar radiation
is allowed to penetrate within the water column. 
The fresh water ßux is also prescribed and varies zonally. 
It is determined such as, at each time step, the basin-integrated ßux is zero. 
The basin is initialised at rest with vertical profiles of temperature and salinity 
uniformly applied to the whole domain.

The GYRE configuration is set through the \key{gyre} CPP key. Its horizontal resolution 
(and thus the size of the domain) is determined by setting \jp{jp\_cfg} in \hf{par\_GYRE} file: \\
\jp{jpiglo} $= 30 \times$ \jp{jp\_cfg} + 2   \\
\jp{jpjglo} $= 20 \times$ \jp{jp\_cfg} + 2   \\
Obviously, the namelist parameters have to be adjusted to the chosen resolution.
In the vertical, GYRE uses the default 30 ocean levels (\jp{jpk}=31) (Fig.~\ref{Fig_zgr}).

The GYRE configuration is also used in benchmark test as it is very simple to increase 
its resolution and as it does not requires any input file. For example, keeping a same model size 
on each processor while increasing the number of processor used is very easy, even though the 
physical integrity of the solution can be compromised.

%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
\begin{figure}[!t]   \begin{center}
\includegraphics[width=1.0\textwidth]{./TexFiles/Figures/Fig_GYRE.pdf}
\caption{  \label{Fig_GYRE}   
Snapshot of relative vorticity at the surface of the model domain 
in GYRE R9, R27 and R54. From \citet{Levy_al_OM10}.}
\end{center}   \end{figure}
%>>>>>>>>>>>>>>>>>>>>>>>>>>>>

% -------------------------------------------------------------------------------------------------------------
%       EEL family configuration
% -------------------------------------------------------------------------------------------------------------
\section{EEL family: periodic channel}
\label{MISC_config_EEL}

\begin{description}
\item[\key{eel\_r2}]  to be described....
\item[\key{eel\_r5}]  
\item[\key{eel\_r6}]  
\end{description}

% -------------------------------------------------------------------------------------------------------------
%       POMME configuration
% -------------------------------------------------------------------------------------------------------------
\section{POMME: mid-latitude sub-domain}
\label{MISC_config_POMME}


\key{pomme\_r025} : to be described....