Introduction

The Nucleus for European Modelling of the Ocean (NEMO) is a framework of ocean related engines, namely OPA^1.1 for the ocean dynamics and thermodynamics, LIM^1.2 for the sea-ice dynamics and thermodynamics, TOP^1.3 for the biogeochemistry (both transport (TRP) and sources minus sinks (LOBSTER, PISCES)^1.4. 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 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 Madec et al. [1998]. 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. Chapter 2 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 temperature, salinity and an equation of seawater). The equations are written in a curvilinear coordinate system, with a choice of vertical coordinates ($z$ or $s$, with the rescaled height coordinate formulation z*, or s*). Momentum equations are formulated in the vector invariant form or in the flux form. Dimensional units in the meter, kilogram, second (MKS) international system are used throughout.

The following chapters deal with the discrete equations. Chapter 3 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. Chapter 4 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 (z* or s*) is used (the level position then vary in time as a function of the sea surface heigh). The following two chapters (5 and 6) 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 (chapter 7) 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 [Valcke, 2006]. Two-way nesting is also available through an interface to the AGRIF package (Adaptative Grid Refinement in FORTRAN) [Debreu et al., 2008]. The interface code for coupling to an alternative sea ice model (CICE, Hunke and Lipscomb [2008]) 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 (chapter 8). 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.

Physical parameterisations are described in chapters 9 and 10. 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, 1990] with a space and time variable coefficient Tréguier et al. [1997]. 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 [1993], Pacanowski and Philander [1981], or Umlauf and Burchard [2003] mixing schemes.

CPP keys and namelists are used for inputs to the code.

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 :

 

#if defined key_option1    


This part of the FORTRAN code will be active   


only if key_option1 is activated at compiling step 

#endif  

Namelists

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:

1. A reference namelist ( in CONFIG/SHARED/namelist_ref ) is read first. This file contains all the namelist variables which are initialised to default values
2. A configuration namelist ( in CONFIG/CFG_NAME/EXP00/namelist_cfg ) is read aferwards. This file contains only the namelist variables which are changed from default values, and overwrites those.

A template can be found in 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.

Model outputs management and specific online diagnostics are described in chapters 11. The diagnostics includes the output of all the tendencies of the momentum and tracers equations, the output of tracers tendencies averaged over the time evolving mixed layer, the output of the tendencies of the barotropic vorticity equation, the computation of on-line floats trajectories... Chapter 12 describes a tool which reads in observation files (profile temperature and salinity, sea surface temperature, sea level anomaly and sea ice concentration) and calculates an interpolated model equivalent value at the observation location and nearest model timestep. Originally developed of data assimilation, it is a fantastic tool for model and data comparison. Chapter 13 describes how increments produced by data assimilation may be applied to the model equations. Finally, Chapter 16 provides a brief introduction to the pre-defined model configurations (water column model, ORCA and GYRE families of configurations).

The model is implemented in 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...). Those rules are briefly presented in Appendix E and a more complete document is available on the NEMO web site.

The model is organized with a high internal modularity based on physics. For example, each trend ($i.e.$, 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 a three-letter rule. For example, traldf.F90 is a module related to the TRAcers equation, computing the Lateral DiFfussion. Furthermore, modules are organized in a few directories that correspond to their category, as indicated by the first three letters of their name (Tab. 1.1).

The manual mirrors the organization of the model. After the presentation of the continuous equations (Chapter 2), the following chapters refer to specific terms of the equations each associated with a group of modules (Tab. 1.1).

Table 1.1: Organization of Chapters mimicking the one of the model directories.

Chapter 3	-	model time STePping environment
Chapter 4	DOM	model DOMain
Chapter 5	TRA	TRAcer equations (potential temperature and salinity)
Chapter 6	DYN	DYNamic equations (momentum)
Chapter 7	SBC	Surface Boundary Conditions
Chapter 8	LBC	Lateral Boundary Conditions (also OBC and BDY)
Chapter 9	LDF	Lateral DiFfusion (parameterisations)
Chapter 10	ZDF	vertical (Z) DiFfusion (parameterisations)
Chapter 11	DIA	I/O and DIAgnostics (also IOM, FLO and TRD)
Chapter 12	OBS	OBServation and model comparison
Chapter 13	ASM	ASsiMilation increment
Chapter 15	SOL	Miscellaneous topics (including solvers)
Chapter 16	-	predefined configurations (including C1D)

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 Madec et al. [1998].

$\bullet$ The main modifications from OPA v8 and NEMO/OPA v3.2 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 [Penduff et al., 2007, Le Sommer et al., 2009, Barnier et al., 2006];
3. partial reactivation of a terrain-following vertical coordinate ($s$- and hybrid $s$-$z$) with the addition of several options for pressure gradient computation ^1.5;
4. more choices for the treatment of the free surface: full explicit, split-explicit or filtered schemes, and suppression of the rigid-lid option;
5. non linear free surface associated with the rescaled height coordinate z* or s;
6. additional schemes for vector and flux forms of the momentum advection;
7. additional advection schemes for tracers;
8. implementation of the AGRIF package (Adaptative Grid Refinement in FORTRAN) [Debreu et al., 2008];
9. online diagnostics : tracers trend in the mixed layer and vorticity balance;
10. rewriting of the I/O management with the use of an I/O server;
11. generalized ocean-ice-atmosphere-CO2 coupling interface, interfaced with OASIS 3 coupler ;
12. surface module (SBC) that simplify the way the ocean is forced and include two bulk formulea (CLIO and CORE) and which includes an on-the-fly interpolation of input forcing fields ;
13. RGB light penetration and optional use of ocean color
14. major changes in the TKE schemes: it now includes a Langmuir cell parameterization [Axell, 2002], the Mellor and Blumberg [2004] surface wave breaking parameterization, and has a time discretization which is energetically consistent with the ocean model equations [Marsaleix et al., 2008, Burchard, 2002];
15. tidal mixing parametrisation (bottom intensification) + Indonesian specific tidal mixing [Koch-Larrouy et al., 2007];
16. introduction of LIM-3, the new Louvain-la-Neuve sea-ice model (C-grid rheology and new thermodynamics including bulk ice salinity) [Vancoppenolle et al., 2009a, Vancoppenolle et al., 2009b]

$\bullet$ The main modifications from NEMO/OPA v3.2 and v3.3 are :

1. introduction of a modified leapfrog-Asselin filter time stepping scheme [Leclair and Madec, 2009];
2. additional scheme for iso-neutral mixing [Griffies et al., 1998], although it is still a "work in progress";
3. a rewriting of the bottom boundary layer scheme, following Campin and Goosse [1999];
4. addition of a Generic Length Scale vertical mixing scheme, following Umlauf and Burchard [2003];
5. addition of the atmospheric pressure as an external forcing on both ocean and sea-ice dynamics;
6. addition of a diurnal cycle on solar radiation [Bernie et al., 2007];
7. river runoffs added through a non-zero depth, and having its own temperature and salinity;
8. CORE II normal year forcing set as the default forcing of ORCA2-LIM configuration ;
9. generalisation of the use of fldread.F90 for all input fields (ocean climatology, sea-ice damping...) ;
10. addition of an on-line observation and model comparison (thanks to NEMOVAR project);
11. optional application of an assimilation increment (thanks to NEMOVAR project);
12. coupling interface adjusted for WRF atmospheric model;
13. C-grid ice rheology now available fro both LIM-2 and LIM-3 [Bouillon et al., 2009];
14. LIM-3 ice-ocean momentum coupling applied to LIM-2 ;
15. a deep re-writting and simplification of the off-line tracer component (OFF_SRC) ;
16. the merge of passive and active advection and diffusion modules ;
17. Use of the Flexible Configuration Manager (FCM) to build configurations, generate the Makefile and produce the executable ;
18. Linear-tangent and Adjoint component (TAM) added, phased with v3.0

In addition, several minor modifications in the coding have been introduced with the constant concern of improving the model performance.

$\bullet$ The main modifications from NEMO/OPA v3.3 and v3.4 are :

1. finalisation of above iso-neutral mixing [Griffies et al., 1998]";
2. "Neptune effect" parametrisation;
3. horizontal pressure gradient suitable for s-coordinate;
4. semi-implicit bottom friction;
5. finalisation of the merge of passive and active tracers advection-diffusion modules;
6. a new bulk formulae (so-called MFS);
7. use fldread for the off-line tracer component (OFF_SRC) ;
8. use MPI point to point communications for north fold;
9. diagnostic of transport ;

$\bullet$ The main modifications from NEMO/OPA v3.4 and v3.6 are :

1. I/O management: NEMO in now interfaced with XIOS, a Input/Output server having a versatile xml user interface, and allowing I/O to be performed on dedicated processors thus improving scalability and performance on massively parallel platforms.
2. ICB module [Marsh et al., 2015]: icebergs as lagrangian floats ;
3. SAS: Stand Alone Surface module allowing testing of forcing set with bulk formulae, to run sea-ice models without ocean, to run ICB icebergs module alone, and to test AGRIF with sea-ice
4. ISF : Under ice-selves cavities (parametrisation and/or explicit representation)
5. Coupled interface for next IPCC requirements (multi category sea-ice, calving and iceberg module)
6. Ocean and ice allowed to be explicitly coupled through OASIS, using StandAlone Surface module)
7. On line coarsening of ocean I/O
8. Major evolution of LIM3 sea-ice model [Rousset et al., 2015]
9. Open boundaries: completion of BDY/OBC merge : BDY is now the only Open boundary module available
10. re-visit of the specification of heat/salt(tracers)/mass fluxes ;
11. levitating or fully embedded sea-ice (for LIM and CICE) ;
12. a new parameterization of mixing induced by breaking internal waves (de Lavergne et al. in prep.) And also:
13. update of AGRIF package and AGRIF compatibility with LIM2 sea-ice model ;
14. A new vertical sigma coordinate stretching function [Siddorn and Furner, 2012] ;
15. Smagorinsky eddy coefficients: the Griffies and Hallberg [2000] Smagorinsky type diffusivity/viscosity for lateral mixing has been introduced ;
16. Standard Fox Kemper parametrisation
17. Analytical tropical cyclones taken in account using track and magnitude observations (Vincent et al. JGR 2012a,b) ;
18. OBS: observation operators improved and now available in Standalone mode ;
19. Log layer option for bottom friction
20. Faster split-explicit time stepping ;
21. Z-tilde ALE coordinates [Leclair and Madec, 2011] ;
22. implicit bottom friction ;
23. Runoff improved and SBC with BGC
24. MPP assessment and optimisation
25. First steps of wave coupling

    Features becoming obsolete: LIM2 (replaced by LIM3 monocategory) ; IOIPSL (replaced by XIOS) ;

    Features that has been removed : LOBSTER (now included in PISCES) ; OBC, replaced by BDY ;

Footnotes

... OPA^1.1

OPA = Océan PArallélisé

... LIM^1.2

LIM= Louvain)la-neuve Ice Model

... TOP^1.3

TOP = Tracer in the Ocean Paradigm

... PISCES)^1.4

Both LOBSTER and PISCES are not acronyms just name

... computation^1.5

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.