CROCO User Guide

CROCO User Guide

CROCO User Guide

Gildas Cambon, Patrick Marchesiello, Pierrick Penven (IRD), Laurent Debreu (INRIA), Rachid Benshila (CNRS), Swen Jullien (Ifremer)

Model description

CROCO is an evolution of ROMS maintained by IRD, INRIA, CNRS, IFREMER and SHOM, French institutes working on environmental sciences and applied mathematics. The main originality of this version is its 2 way nesting capability but is otherwise close to the UCLA version regarding the numerical kernel. CROCO is quickly presented below with a description its numerical algorithms and physical parametrizations. Then the 2-way nesting capability is summarized. Finally, the model configuration options and parameters are described in details to help building model configurations. Additional information can be found in a series of papers and documents available on the CROCO web site : in the documentation section.

Numerical kernel

CROCO solves the primitive equations in an Earth-centered rotating environment, based on the Boussinesq approximation and hydrostatic vertical momentum balance. It is discretized in coastline- and terrain-following curvilinear coordinates using high-order numerical methods. it is a split-explicit, free-surface ocean model, where short time steps are used to advance the surface elevation and barotropic momentum, with a much larger time step used for temperature, salinity, and baroclinic momentum. The model has a 2-way time-averaging procedure for the barotropic mode, which satisfies the 3D continuity equation. The specially designed 3rd order predictor-corrector time step algorithm allows a substantial increase in the permissible time-step size. The complete time stepping algorithm is described in Shchepetkin and McWilliams (2005). Associated with the 3rd order time-stepping, a 3rd-order, upstream-biased advection scheme allows the generation of steep gradients, enhancing the effective resolution of the solution for a given grid size (Shchepetkin and McWilliams, 1998). Because of the implicit diffusion in the upstream-biased advection scheme, explicit lateral viscosity is not needed in CROCO, except in sponge layers near the open boundaries where it increases smoothly close to the lateral open boundaries. For tracers, A 3rd-order upstream-biased advection scheme is also implemented but the diffusion part of this scheme is rotated along isopycnal surfaces to avoid spurious diapycnal mixing and loss of water masses (Marchesiello et al., 2009; Lemarié et al., 2012). If a lateral boundary faces the open ocean, an active, implicit, upstream biased, radiation condition connects the model solution to the surroundings (Marchesiello et al., 2001). CROCO also include an accurate pressure gradient algorithm (Shchepetkin and McWilliams, 2003) and a variety of features including turbulent closure schemes for surface and benthic boundary layers and interior mixing; wetting and drying; sediment and biological models; OASIS coupler interface for CROCO-WRF coupling (in preparation); and data assimilation (3DVAR developed at JPL but not (yet) freely distributed).

Time-stepping diagram

Figure 1: CROCO time stepping diagram from Shchepetkin and Mcwilliams (2009)


CROCO has been designed to be optimized on both shared and distributed memory parallel computer architectures. Parallelization is done by two dimensional sub-domains partitioning. Multiple sub-domains can be assigned to each processor in order to optimize the use of processor cache memory. This allow super-linear scaling when performance growth even faster than the number of CPUs.

Nesting capabilities

To address the challenge of bridging the gap between near-shore and offshore dynamics, a nesting capability has been added to CROCO and tested for the California Upwelling System (Debreu et al., 2012; Penven et al., 2006). The method chosen for embedded griding takes advantage of the AGRIF (Adaptive Grid Refinement in Fortran) package (Debreu and Blayo, 2003, 2008; Blayo and Debreu, 1999; Debreu and Vouland, 2003; Debreu, 2000). AGRIF is a Fortran 95 package for the inclusion of adaptive mesh refinement features within a finite difference numerical model. One of the major advantages of AGRIF in static-grid embedding is the ability to manage an arbitrary number of fixed grids and an arbitrary number of embedding levels.

Figure 2: Temporal coupling between a parent and a child grid for a refinement factor of 3. The coupling is done at the baroclinic time step.

A recursive integration procedure manages the time evolution for the child grids during the time step of the parent grids (Fig. 2). In order to preserve the CFL criterion, for a typical coefficient of refinement (say, a factor of 3 for a 5 km resolution grid embedded in a 15 km grid), for each parent time step the child must be advanced using a time step divided by the coefficient of refinement as many time as necessary to reach the time of the parent (Fig. 2). For simple 2-level embedding, the procedure is as follows:

  1. Advance the parent grid by one parent time step.
  2. Interpolate the relevant parent variables in space and time to get the boundary conditions for the child grid.
  3. Advance the child grid by as much child time steps as necessary to reach the new parent model time.
  4. Update point by point the parent model by averaging the more accurate values of the child model (in case of 2-way nesting).

The recursive approach used in AGRIF allows the specification of any number of nesting levels. Additional CPP options are related to AGRIF, they are in set_global_definitions.h and set_obc_definitions.h files. These are default options intended for nesting developers and should not be edit by standard users.

For a better understanding of ROMS nesting capabilties using AGRIF, check the published articles on CROCO/ROMS nesting implementation and also the AGRIF project homepage:

  1. CROCO/ROMS 1 way nesting : Evaluation and application of the ROMS 1-way, embedding procedure to the central california upwelling system, (Penven et al., 2006)
  2. CROCO/ROMS 2 way nesting: Two-way nesting in split-explicit ocean models: algorithms, implementation and validation. (Debreu et al., 2012)
  3. AGRIF homepage :

Turbulent closure

A non-local, K-profile planetary (KPP) boundary layer scheme (Large, 1994) parameterizes the unresolved physical vertical subgrid-scale processes. A generic two-equation turbulence closure model called Generalized Length Scale (GLS) scheme is also available (Umlauf and Burchard, 2003; Warner et al. 2005) with k-kl scheme (~ MY2.5) as default choice. For lateral subgrid-scale mixing, the Smagorinsky model is available.

Wetting and Drying

The processes of wetting and drying have important physical and biological impacts on shallow water systems. Flooding and dewatering effects on coastal mud flats and beaches occur on various time scales ranging from storm surge, periodic rise and fall of the tide, to infragravity wave motions. To correctly simulate these physical processes with a numerical model requires the capability of the computational cells to become flooded and dewatered. Warner et al. (2013) proposed a method for wetting and drying based on an approach consistent with a cell-face blocking algorithm. The method allows water to always flow into any cell, but prevents outflow from a cell when the total depth in that cell is less than a user defined critical value. See Warner et al. (2013) for details.

Wave-current interactions

A vortex-force formalism for the interaction of surface gravity waves and currents is implemented in CROCO (Uchiyama et al., 2010). Eulerian wave-averaged current equations for mass, momentum, and tracers are included based on an asymptotic theory by McWilliams et al. (2004) plus non-conservative wave effects due to wave breaking, associated surface roller waves, bottom streaming, and wave-enhanced vertical mixing and bottom drag especially for coastal and nearshore applications. The currents are coupled with a spectrum-peak WKB wave-refraction model that includes the effect of currents on waves, or, alternatively, a spectrum-resolving wave model (e.g., WAVEWATCH3) can be used (OASIS coupling to be done). In nearshore applications, the currents’ cross-shore and vertical structure is shaped by the wave effects of near-surface breaker acceleration, vertical component of vortex force, and wave-enhanced pressure force and bottom drag.

Sediment dynamics

Regarding the time and space resolution considered, the explicit solution refers to quantities averaged over both wind-wave and swell periods and averaged over sub-mesoscale eddy scales. One of the crucial ingredients in the sediment transport model is a reliable representation of the wave-averaged hydrodynamics and turbulence. In particular a sufficiently high near-bottom resolution is required. The wave boundary layer is not resolved explicitly, but the lower part of the velocity and sediment concentration profile in the current boundary layer is important for the calculation of the sediment transport rates. Similarly, an accurate assessment of the bottom boundary shear stress (including effect of waves) is required since it determines the initiation of grain motion and settling and resuspension of suspended load. Thus, the sediment concentration and current velocity profiles in the unresolved part of the near-bottom layer have to be parameterized. Characterization of the sediments (mainly density and grain size, making general assumptions about shape and cohesiveness) is done either as a time-dependent prescribed function at the point sources or at the sea bed as an initial (space-dependent) condition. Along with bed sediment properties, characteristics of bed form roughness is also provided as initial input. Sediment concentration may be considered as passive with respect to the flow density or as active if concentration values require such (the latter is not implemented yet). See Blaas et al. (2007) and the report given on the documentation section for details.

Biogeochemical models

CROCO comes with series of biogeochemical (BGC) models of increasing complexity, from relatively simple 5- or 7-component NPZD (Gruber et al., 2006, 2011) and N2P2Z2D2 BioEBUS model (Gutknecht, 2013) that proved well suited to upwelling regions to 24-component PISCES (Aumont et al., 2005).

BioEBUS is a nitrogen-based model (Fig. 1) derived from a N2P2Z2D2 evolution of ROMS NPZD model (Gruber et al., 2006, 2011) and accounting for the main planktonic communities in upwelling ecosystems associated oxygen minimum zones (OMZs). It is validated in Gutknecht et al. (2013) using available satellite and in situ data in the northern part of the Benguela upwelling system. In this model, phytoplankton and zooplankton are split into small (PS and ZS: flagellates and ciliates, respectively) and large (PL and ZL: diatoms and copepods, respectively) organisms. Detritus are also separated into small and large particulate compartments (DS and DL). A semi-labile dissolved organic nitrogen (DON) compartment was added since DON can be an important reservoir of OM and can potentially play an important role in supplying nitrogen or carbon from the coastal region to the open ocean (Huret et al., 2005). The pool of dissolved inorganic nitrogen is split into nitrate (NO3-), nitrite (NO2-) and ammonium (NH4+) species to have a detailed description of the microbial loop: ammonification/nitrification processes under oxic conditions, and denitrification/anammox processes under suboxic conditions (Yakushev et al., 2007). These processes are directly oxygen dependent, so an oxygen (O2) equation was also introduced in BioEBUS with the source term (photosynthesis), sink terms (zooplankton respiration, bacteria re-mineralisation) and sea–air O2 fluxes following Pena et al. (2010) and Yakushev et al. (2007). To complete this nitrogen-based model, nitrous oxide (N2O) was introduced using the parameterization of Suntharalingam et al. (2000, 2012). It allows determining the N2O production under oxygenated conditions and at low-oxygen levels, mimicking the N2O production from nitrification and denitrification processes. The SMS terms of BioEBUS and parameter values are described in detail in Gutknecht et al. (2013).

PISCES was developed for NEMO (the French ocean climate model). It was implemented in CROCO for its supposed suitability for a wide range of oceanic regimes. PISCES currently has five modeled limiting nutrients for phytoplankton growth: Nitrate and Ammonium, Phosphate, Silicate and Iron. Phosphate and nitrate+ammonium are linked by constant Redfield ratios but the nitrogen pool undergoes nitrogen fixation and denitrification. Four living compartments are represented: two phytoplankton size-classes/groups corresponding to nanophytoplankton and diatoms, and two zooplankton size classes which are micro-zooplankton and mesozooplankton. For phytoplankton, prognostic variables are total biomass, the iron, chlorophyll and silicon contents. This means that the Fe/C, Chl/C and Si/C ratios of both phytoplankton groups are fully predicted by the model. For zooplankton, only the total biomass is modeled. For all species, the C/N/P/O2 ratios are supposed constant and are not allowed to vary. The Redfield ratio O/C/N/P is set to 172/122/16/1. In addition, the Fe/C ratio of both zooplankton groups is kept constant. No silicified zooplankton is assumed. The bacterial pool is not yet explicitly modeled. There are three non-living compartments: semi-labile dissolved organic matter, small and big sinking particles. The iron, silicon and calcite pools of the particles are explicitly modeled and their ratios are allowed to vary. The sinking speed of the particles is not altered by their content in calcite and biogenic silicate (”The ballast effect”). The latter particles are assumed to sink at the same speed as big organic matter particles. All the non-living compartments experience aggregation due to turbulence and differential settling. In addition to the ecosystem model, PISCES also simulates dissolved inorganic carbon, total alkalinity and dissolved oxygen. The latter tracer is also used to define the regions where oxic or anoxic remineralization takes place. see Aumont et al. (2005) in the documentation section for details.

Ocean-Atmosphere coupling

Coupling is actually available with atmosphere and/or wave. It has been designed for compatibility with WRF and WWIII and uses OASIS-MCT coupler.

Non-Boussinesq/Non-Hydrostatic mode

The Non-Hydrostatic approach is based on the relaxation of the Boussinesq approximation instead of solving a Poisson system. It allows to replace the barotropic mode by a full 3D so-called fast mode  resolving the waves of a velocity to the sound speed. The barotropic mode is part of this “fast” mode. Depending on the physical problem, the sound speed can be slightly decrease to the maximum wave velocity one wants to solve.

Comparison of ROMS versions

RealmEurope-WorldUS West CoastUS East Coast
Introductory year1999 (AGRIF), 2016( CROCO20021998
ParallelizationMPI or OpenMP (Hybrid branch exists)Hybrid MPI-OpenMPMPI or OpenMP
NestingOnline at barotropic levelOff-line (On-line at baroclinic level and not yet operational)Off-line
Data assimilation3DVAR4DVAR
Wave-Current interactionMcWilliams et al. (2004)McWilliams et al. (2004)Mellor (2003) and McWilliams et al. (2004)
Air-sea couplingHome made + OASISHome madeMCT
Sediment DynamicsBlaas et al. (2007)Blaas et al. (2007)Blaas et al. (2007), Warner et al. (2008)
BiogeochemistryNPZD Gruber et al. (2006), PISCESNPZD Gruber et al. (2006)EcoSim, NEMURO, NPZD Franks, NPZD Powell, Fennel
Sea icenonenoneBudgell (2005)
Vertical mixingKPP, GLSKPP, GLSKPP, GLS
Wetting-DryingWarner et al. (2013)noneWarner et al. (2013)
2D momentumGeneralized FB (AB3-AM4)LF-AM3 with FB feedback
3D momentumLF-AM3AB3
TracersLF-AM3 with stabilizing correction for isopycnal hyperdiffusionLF-TR with explicit geopotential diffusion (no stabilizing correction: strong stability constraint)
Internal wavesLF-AM3 with FB feedbackGeneralized FB (AB3-TR)
Coupling stagePredictorCorrector 
3D advection1.580.72
Internal waves1.851.14

Model Parameters : param.h

In this section, we present the more important parameters to configure your own run. These parameters are :

Test case or realistic run
#if defined BASIN − − − − − > Test case
parameter (LLm0= 60, MMm0= 50, N= 10)
#elif defined REGIONAL => Realistic run
#elif defined BENGUELA LR
parameter (LLm0= 41, MMm0= 42, N= 32) !<== BENGUELA LR
# else
parameter (LLm0=39, MMm0= 32, N= 20)
# endif
Grid size– LLm0: Dimension (ghost points included) in the ξ direction.
– MMm0: Dimension (ghost points included) in the η direction.
– N: Number of ρ-vertical points, in the vertical grid.
! Domain subdivision parameters:
! ====== =========== ===========
! NPP Maximum allowed number of parallel threads;
! NSUB X,NSUB E Number of SHARED memory subdomains in XI- and
! ETA-directions;
! NNODES Total number of MPI processes (nodes);
! NP XI,NP ETA Number of MPI subdomains in XI- and ETA-directions;

In the case of OpenMP parallelization, NPP is the number of cpu used 
in the computation, 
in the case of MPI parallelization, it is equal to to NNODES. 
AUTOTLING (implemented by Laurent Debreu): cpp-key that enable 
to compute the optimum subdomains partition in terms of 
computation time.
#if defined SSH TIDES || defined UV TIDES
      integer Ntides
      parameter (Ntides=8) => Number of wave in the total tidal signal

CPP options : cppdefs.h

ROMS extensively uses the C preprocessor (cpp) during compilation to replace code statements, insert files into the code, and select relevant parts of the code depending on its directives. There are numerous CPP options that can be activated in header files cppdefs.h (for users) and set_global_definitions.h (for developers mainly). In this section, we present the CPP keys that define numerical and physical options in CROCO, then give a description for each set of keys.


CPP OPTIONSDescription
BASINMust be defined for running the Basin example
CANYON_AMust be defined for running the Canyon_A example
CANYON_BMust be defined for running the Canyon_B example
EQUATORMust be defined for running the Equator example
GRAV_ADJMust be defined for running the Gravitational Adjustment example
ACOUSTICMust be defined for running the accoustic example
INNERSHELFMust be defined for running the Inner Shelf example
OVERFLOWMust be defined for running the Gravitational/Overflow example
SEAMOUNTMust be defined for running the Seamount example
SHELFRONTMust be defined for running the Shelf Front example
SOLITONMust be defined for running the Equatorial Rossby Wave example
UPWELLINGMust be defined for running the Upwelling example
INTERNALMust be defined for running the Internal tides example
VORTEXMust be defined for running the Baroclinic Vortex example
JETMust be defined for running the Jet example
THACKERMust be defined for running the Thacker example
TANKMust be defined for running the Tank example
S2DVMust be defined for running the S2DV example
RIPMust be defined for running the Rip current example
SHOREFACEMust be defined for running the Shoreface example
SWASHMust be defined for running the Swash example
REGIONALMust be defined if running realistic regional simulations


CPP OPTIONSDescription
OPENMPActivate Open-MP parallelization protocol
MPIActivate MPI parallelization protocol
PARALLEL_FILESActivate parallel I/O writing
XIOSUse external server for output
AUTOTILINGActivate subdomains partitionning optimization.

Preselected options :

# ifdef MPI
# endif 
# undef XIOS


CPP OPTIONSDescription
AGRIFActivate nesting capabilities (1-WAY by default)
AGRIF_2WAYActivate 2-WAY nesting (update parent solution by child solution)

Open Boundary conditions

CPP OPTIONSDescription
OBC_EASTOpen eastern boundary
OBC_WESTOpen western boundary
OBC_SOUTHOpen southern boundary
OBC_NORTHOpen northern boundary


CPP OPTIONSDescription
TIDESActivate tidal forcing at open boundaries
SSH_TIDESprocess and use tidal sea level data
UV_TIDESprocess and use tidal currents data
TIDERAMPApply ramping on tidal forcing (1 day) at initialization. Warning! This should be undefined if restarting the model.

Preselected options :

# ifdef TIDES 
#  define SSH_TIDES 
#  define UV_TIDES 
#  define TIDERAMP 
# endif


CPP OPTIONSDescription
BIOLOGYActivate biogeochemical modeling
FLOATSActivate floats
STATIONSStore high frequency model outputs at stations
PASSIVE_TRACERAdd a passive tracer
SEDIMENTActivate sediment modeling
BBLActivate bottom boundary layer parametrization

Preselected options :

# undef BIOLOGY 
# undef FLOATS 
# undef STATIONS 
# undef SEDIMENT 
# undef BBL

Grid configuration

CPP OPTIONSDescription
CURVGRIDActivate curvilinear coordinate transformation
SPHERICALActivate longitude/latitude grid positioning
MASKINGActivate land masking
WET_DRYActivate wetting-Drying scheme
NEW_S_COORDChoose new vertical S-coordinates

Preselected options :

The Wetting-Drying scheme is derived from John Warner’s code (Rutgers ROMS) and adapted to the time stepping scheme of CROCO. The main idea is to cancel the outgoing momentum flux (not the incoming) from a grid cell if its total depth is below a threshold value (critical depth Dcrit between 5 and 20 cm according to local slope; Dcrit min and max adjustable in param.h). This scheme is tested in the Thacker case producing oscillations in a rotating bowl for which an analytical solution is known.

# define CURVGRID
# define SPHERICAL
# define MASKING
# undef WET_DRY
# undef NEW_S_COORD

Model dynamics

CPP OPTIONSDescription
SOLVE3Dsolve 3D primitive equations
UV_CORActivate Coriolis terms
UV_ADVActivate advection terms
NBQActivate non-boussinesq option

Preselected options :

# define SOLVE3D 
# define UV_COR 
# define UV_ADV 
# undef NBQ

Lateral Momentum Advection

CPP OPTIONSDescription
UV_HADV_UP3Activate 3rd-order upstream biased advection scheme
UV_HADV_UP5Activate 35rd-order upstream biased advection scheme
UV_HADV_C2Activate 2nd-order centred advection scheme (should be used with explicit momentum mixing)
UV_HADV_C4Activate 4th-order centred advection scheme (should be used with explicit momentum mixing)
UV_HADV_C6Activate 6th-order centred advection scheme (should be used with explicit momentum mixing)
UV_HADV_WENO5Activate WENO 5th-order advection scheme
UV_HADV_TVDActivate Total Variation Diminushing scheme

Preselected options :

These options are set in set_global_definitions.h as the default UV_HADV_UP3 is the only one recommended for standard users.

# define UV_HADV_UP3
# undef  UV_HADV_UP5
# undef  UV_HADV_C2
# undef  UV_HADV_C4
# undef  UV_HADV_C6 
# undef  UV_HADV_WENO5
# undef  UV_HADV_TVD

Lateral Momentum Mixing

CPP OPTIONSDescription
UV_MIX_GEOActivate mixing on geopotential (constant depth) surfaces
UV_MIX_SActivate mixing on iso-sigma (constant sigma) surfaces
UV_VIS2Activate Laplacian horizontal mixing of momentum
UV_VIS4Activate Bilaplacian horizontal mixing of momentum
UV_VIS_SMAGOActivate Smagorinsky parametrization of turbulent viscosity (only with UV_VIS2)
UV_VIS_SMAGO3DActivate 3D Smagorinsky parametrization of turbulent viscosity

Explicit lateral momentum mixing may be only useful when implicit dissipation in UV_HADV_UP3 is not large enough to account for subgrid-scale turbulence resulting from large shear currents (for example in the case of western boundary currents). In this case, Smagorinsky parametrization is recommended (define UV_VIS2 below).

Preselected options :

# undef UV_VIS2
# ifdef UV_VIS2
#  define UV_MIX_S
#  define UV_VIS_SMAGO
# endif

# define VIS_COEF_3D

# ifdef UV_MIX_S 
# elif defined UV_MIX_GEO
# else
# define UV_MIX_S /* Default*/
# endif

Lateral Tracer Advection

CPP OPTIONSDescription
TS_HADV_UP33rd-order upstream-biased advection scheme
TS_HADV_RSUP3Split and rotated 3rd-order upstream-biased advection scheme
TS_HADV_UP55th-order upstream-biased advection scheme
TS_HADV_RSUP5Split and rotated 3rd-order upstream-biased advection scheme with reduced dispersion/diffusion
TS_HADV_C44th-order centered advection scheme
TS_HADV_C66th-order centered advection scheme
TS_HADV_WENO55th-order WENOZ quasi-monotone advection scheme for all tracers
BIO_HADV_WENO55th-order WENOZ quasi-monotone advection scheme for passive tracers (including biology and sediment tracers)

Preselected options :

TS_HADV_RSUP3 is recommended for realistic applications with variable bottom topography as it strongly reduces diapycnal mixing. It splits the UP3 scheme into 4th-order centered advection and rotated bilaplacian diffusion with grid-dependent diffusivity. It calls for CPP options in set_global_definitions.h for the explicit treatment of bilaplacian diffusion (see below). TS_HADV_RSUP3 is expensive in terms of computational cost and requires more than 30 sigma levels to perform properly. Therefore, for small domains dominated by open boundary fluxes, TS_HADV_UP5 may present a cheaper alternative and good compromise. TS_HADV_RSUP5 is still experimental but allows a decrease in numerical diffusivity compared to TS_HADV_RSUP3 by using 6th order rather than 4th-order centered advection (it resembles in spirit a split-rotated UP5 scheme but the use of bilaplacian rather than trilaplacian diffusion keeps it 3rd order). TS_HADV_C4 has no implicit diffusion and is thus accompanied by rotated Smagorinsky diffusion defined in set_global_definitions.h; it is not recommended for usual applications. For RSUP family, by default the diffusive part is oriented along geopotential.

# undef  TS_HADV_UP3
# define TS_HADV_RSUP3
# undef  TS_HADV_UP5
# undef  TS_HADV_RSUP5 
# undef  TS_HADV_C4
# undef  TS_HADV_C6 
# undef  TS_HADV_WENO5
# if defined PASSIVE_TRACER || defined BIOLOGY || defined SEDIMENT
#  define BIO_HADV_WENO5
# endif

Lateral Tracer Mixing

CPP OPTIONSDescription
TS_MIX_ISOActivate mixing along isopycnal (isoneutral) surfaces
TS_MIX_GEOActivate mixing along geopotential surfaces
TS_MIX_SActivate mixing along iso-sigma surfaces
TS_DIF2Activate Laplacian horizontal mixing of tracer
TS_DIF4Activate Bilaplacian horizontal mixing of tracer
TS_MIX_IMPActivate stabilizing correction of rotated diffusion (used with TS_MIX_ISO and TS_MIX_GEO)

Preselected options :

These options are preselected in set_global_definitions.h for compliance with Advection options:

#ifdef TS_HADV_RSUP3 /* Rotated-Split 3rd-order scheme is: */
# define TS_HADV_C4  /* 4th-order centered advection */
# define TS_DIF4 /* + Hyperdiffusion  */
# define TS_MIX_GEO /* rotated along geopotential surfaces */
# define TS_MIX_IMP /* with Semi-Implicit Time-Stepping */
# define DIF_COEF_3D 


CPP OPTIONSDescription
ZNUDGINGActivate nudging layer for zeta.
M2NUDGINGActivate nudging layer for barotropic velocities.
M3NUDGINGActivate nudging layer for baroclinic velocities.
TNUDGINGActivate nudging layer for tracer.
ROBUST_DIAGActivate strong tracer nudging in the interior for diagnostic simulations.

Preselected options :

The nudging layer has the same extension as the sponge layer. In nudging layers, tracer and momentum fields are nudged towards climatological values at a time scale Tau_out (possibly different for momentum and tracers) that is given in namelist


# define ZNUDGING 
# define M2NUDGING 
# define M3NUDGING 
# define TNUDGING 
# undef ROBUST_DIAG 
# endif

Vertical mixing

CPP OPTIONSDescription
BODYFORCEApply surface and bottom stresses as body-forces
ANA_VMIXActivate analytical viscosity/diffusivity coefficients
BVF_MIXINGActivate a simple mixing scheme based on the Brunt-Väisälä frequency
LMD_MIXINGActivate Large/McWilliams/Doney mixing (turbulent closure for interior and planetary boundary layers) with following options
LMD_SKPPActivate surface boundary layer KPP mixing
LMD_BKPPActivate bottom boundary layer KPP mixing
LMD_RIMIXActivate shear instability interior mixing
LMD_CONVECActivate convection interior mixing
LMD_DDMIXActivate double diffusion interior mixing
LMD_NONLOCALActivate nonlocal transport for SKPP
GLS_MIXINGActivate Generic Length Scale scheme as implemented by Warner et al. (2005), default is k-kl (see below)
GLS_MIX2017Activate Generic Length Scale scheme with a sligthly different implementation (under test), default is k-epsilon (see below)
GLS_KKLActivate K-KL (K=TKE; L=length Scale) as in Mellor-Yamada 2.5 (1974)
GLS_KOMEGAActivate K-OMEGA (OMEGA=frequency of TKE dissipation) originating from Kolmogorov (1942)
GLS_KEPSILONActivate K-EPSILON (EPSILON=TKE dissipation) as in Jones and Launder (1972)
GLS_GENActivate generic model of Umlauf and Burchard (2003)

Preselected options :

#undef BVF_MIXING 
#define LMD_MIXING
#undef GLS_MIX2017
# ifdef LMD_MIXING 
# define LMD_SKPP 
# define LMD_BKPP 
# define LMD_RIMIX 
# define LMD_CONVEC 
# undef LMD_DDMIX 
# define LMD_NONLOCAL 

Equation of state

CPP OPTIONSDescription
SALINITYActivate salinity as an active tracer
NONLIN_EOSActivate nonlinear equation of state
SPLIT_EOSActivate the split of the nonlinear equation of state in adiabatic and compressible parts for reduction of pressure gradient errors

Preselected options :

# define SALINITY 
# define NONLIN_EOS 
# define SPLIT_EOS

Surface forcing

CPP OPTIONSDescription
BULK_FLUXActivate bulk formulation for surface heat fluxes
BULK_FAIRALLChoose Fairall formulation (default: COAMPS formulation)
BULK_EPAdd in bulk formulation for fresh water fluxes
BULK_LWAdd in long-wave radiation feedback from model SST
BULK_SMFLUXAdd in bulk formulation for surface momentum fluxes
SST_SKINActivate skin sst computation (Zeng & Beljaars, 2005)
ONLINERead native files and perform online interpolation on ROMS grid (default cubic interpolation)
QCORRECTIONActivate linearized bulk formulation providing heat flux correction dQdSST for nudging towards model SST
SFLX_CORRActivate freshwater flux correction around model SSS
ANA_DIURNAL_SWActivate analytical diurnal modulation of short wave radiations (only appropriate if there is no diurnal cycle in data)

Preselected options :

ONLINE option is an alternative to pre-processing of surface forcing data, that can be useful for long-term simulations, especially if handling multiple configurations. ONLINE option calls for CUBIC_INTERP in set_global_definitions.h.

# ifdef BULK_FLUX 
# define BULK_LW
# define BULK_EP
# define BULK_SMFLUX
# undef SST_SKIN
# undef ONLINE
# else 
# define SFLX_CORR 
# endif


CPP OPTIONSDescription
OW_COUPLINGActivate Ocean-Wave coupling
OA_COUPLINGActivate Ocean-Atmosphere coupling
OA_MCTUse OASIS-MCT for coupling
XIOSUse an external library for output

Preselected options :

Coupling is designed to be used with WRF atmospheric model developed at NCAR and/or WWIII wave model. Those model are not provided for download with CROCO and need to be installed separately. Note that the coupling relies on OASIS-MCT coupler (to install).

XIOS is an external library for output (developed at IPSL) providing for flexibility and design to improve performances for HPC : see

#undef XIOS

Sponge layer

CPP KEY NAMEDescription
SPONGEActivate areas of enhanced viscosity and diffusivity near lateral open boundaries.
SPONGE_GRIDAutomatic setting of the sponge width and value
SPONGE_DIF2Sponge on tracers (default)
SPONGE_VIS2Sponge on momentum (default)
SPONGE_SEDSponge on sediment (default)

SPONGE is preselected in cppdefs.h and calls for SPONGE_GRID in set_global_definitions.h. SPONGE_GRID selects the sponge layer extension (10 points with cosine shape function) and viscosity and diffusivity values according to the horizontal resolution.

Lateral forcing

CPP OPTIONSDescription
CLIMATOLOGYActivate processing of 2D/3D climatological data for nudging layers and open boundary forcing
ZCLIMATOLOGYActivate processing of sea level
M2CLIMATOLOGYActivate processing of barotropic velocities
M3CLIMATOLOGYActivate processing of baroclinic velocities
TCLIMATOLOGYActivate processing of tracers
ZNUDGINGActivate nudging layer for sea level
M2NUDGINGActivate nudging layer for barotropic velocities
M3NUDGINGActivate nudging layer for baroclinic velocities
TNUDGINGActivate nudging layer for tracers
ROBUST_DIAGActivate nudging over the whole domain
FRC_BRYActivate processing of 1D/2D climatological or simulation/reanalysis data at open boundary points
Z_FRC_BRYActivate open boundary forcing for sea level
M2_FRC_BRYActivate open boundary forcing for barotropic velocities
M3_FRC_BRYActivate open boundary forcing for baroclinic velocities
T_FRC_BRYActivate open boundary forcing for tracers

Preselected options :

FRC_BRY is useful for inter-annual forcing on high-resolution domains. FRC_BRY is compatible with CLIMATOLOGY that can still be used for nudging layers.

# define ZNUDGING
# define M2NUDGING
# define M3NUDGING
# define TNUDGING
# endif 
# undef FRC_BRY 
# ifdef FRC_BRY 
#  define Z_FRC_BRY 
#  define M2_FRC_BRY 
#  define M3_FRC_BRY 
#  define T_FRC_BRY 
# endif

Bottom Forcing

CPP OPTIONSDescription
ANA_BSFLUXActivate analytical bottom salinity flux (generally 0)
ANA_BTFLUXActivate analytical bottom temperature flux (generally 0)

Preselected options :

# define ANA_BSFLUX 
# define ANA_BTFLUX

Point Sources – Rivers

CPP OPTIONSDescription
PSOURCEActivate point sources (rivers)
ANA_PSOURCEuse analytical vertical profiles for point sources (set in set_global_definitions.h)
PSOURCE_NCFILERead variable river transports in netcdf file
PSOURCE_NCFILE_TSRead variable river concentration in netcdf file

Open boundary conditions II

CPP OPTIONSDescription
OBC_VOLCONSActivate mass conservation enforcement at open boundaries (with OBC_M2ORLANSKI)
OBC_M2SPECIFIEDActivate specified open boundary conditions for barotropic velocities
OBC_M2ORLANSKIActivate radiative open boundary conditions for barotropic velocities
OBC_M2FLATHERActivate Flather open boundary conditions for barotropic velocities
OBC_M2CHARACTActivate open boundary conditions based on characteristic methods barotropic velocities
OBC_M3SPECIFIEDActivate specified open boundary conditions for baroclinic velocities
OBC_M3ORLANSKIActivate radiative open boundary conditions for baroclinic velocities
OBC_TSPECIFIEDActivate specified open boundary conditions for tracers
OBC_TORLANSKIActivate radiative open boundary conditions for tracers
OBC_TUPWINDActivate upwind open boundary conditions for tracers

Preselected options :

For non-tidal forcing, the combination of OBC_M2ORLANSKI and OBC_VOLCONS often provides the best performances in terms of transparency of barotropic flow at the open boundaries. OBC_M2CHARACT is near as good and also provides proper conditions for tidal forcing.

# ifdef TIDES 
#  define OBC_M2FLATHER 
# else 
# undef OBC_M2FLATHER 
# define OBC_M2CHARACT 
#  define OBC_VOLCONS 
# endif 
# endif 
# define OBC_M3ORLANSKI 

Input- Output – Diagnostics

CPP OPTIONSDescription
AVERAGESProcess and output time-averaged data
AVERAGES_KProcess and output time-averaged vertical mixing
DIAGNOSTICS_TSStore and output budget terms of the tracer equations
DIAGNOSTICS_TS_ADVChoose advection rather than transport formulation for tracer budgets
DIAGNOSTICS_TS_MLDIntegrate tracer budgets over the mixed-layer depth
DIAGNOSTICS_UVStore and output budget terms of the momentum equations
XIOSUse XIOS IO server

Preselected options :

# define AVERAGES 
# define AVERAGES_K 
# endif
# undef XIOS

Biogeochemical models

CPP OPTIONSDescription
PISCESActivate 24-component PISCES biogeochemical model
BIO_NChlPZDActivate 5-component NPZD type model
BIO_N2PZD2Activate 7-component NPZD type model
BIO_BioEBUSActivate 12-component NPZD type model

Preselected options :

# ifdef BIOLOGY 
# undef PISCES
# define BIO_NChlPZD
# undef BIO_N2ChlPZD2 
# undef BIO_BioEBUS 
# endif

Sediment dynamics model

CPP OPTIONSDescription
ANA_SEDIMENTSet analytical sediment ripple and bed parameters
ANA_WWAVEAnalytical (constant) wave (hs,Tp,Dir) values.
SUSPLOADActivate suspended load transport
BEDLOADActivate bedload transport
MORPHODYNActivate morphodynamics
ANA_BPFLUXSet kinematic bottom flux of sediment tracer (if different from 0)
SLOPE_NEMETHNemeth formulation for avalanching ( Nemeth et al, 2006)
SLOPE_LESSERLesser formulation for avalanching (Lesser et al, 2004)
BEDLOAD_SOULSBYSoulsby formulation for bedload ( Soulsby, R.L. and J.S. Damgaard, 2005)
BEDLOAD_MPMMeyer-Peter-Muller formulation for bedload (Meyer-Peter, E. and R. Muller, 1948)

Preselected options :

# define SUSPLOAD
# define BEDLOAD
# ifdef BEDLOAD
# if (defined WAVE_OFFLINE || defined WKB_WWAVE || defined ANA_WWAVE\
|| defined OW_COUPLING)
# define Z0_BL
# define Z0_RIP
# else
# define BEDLOAD_MPM
# endif
# endif

Bottom Boundary Layer model

CPP OPTIONSDescription
ANA_WWAVESet analytical wave forcing
ANA_BSEDIMSet analytical bed parameters (if SEDIMENT is undefined)
Z0_BLCompute bedload roughness for ripple predictor and sediment purposes
Z0_RIPDetermine bedform roughness ripple height and ripple length for sandy beds
Z0_BIODetermine (biogenic) bedform roughness ripple height and ripple length for silty beds

Preselected options :

# ifdef BBL
# define ANA_WWAVE
# ifdef SEDIMENT
#  undef ANA_BSEDIM
# else
#  define ANA_BSEDIM
# endif
# undef Z0_BL
# ifdef Z0_BL
#  define Z0_RIP
# endif
# undef Z0_BIO
# endif

Wave-Current interactions

CPP OPTIONSDescription
MRL_WCISet wave-current interaction model
ANA_WWAVEAnalytical values for waves
WAVE_OFFLINESet-wave offline (read from file) forcing
WKB_WWAVESet WKB wave model
OW_COUPLINGSet wave coupling for WWIII (to install separately)
MRL_CEWSet current feedback on waves
WKB_OBC_WESTSet East/West/North/South offshore forcing for WKB model
ANA_BRY_WKBAnalytical boundary wave foring (from
WAVE_BREAK_CT93Thornton and Guza (1983, JGR) wave breaking (for WKB)
WAVE_BREAK_TG86Church and Thornton (1993, Coastal Eng.) wave breaking (for WKB)
WAVE_BREAK_TG86AAnother Church and Thornton formulation
WAVE_ROLLERSet wave roller model
WAVE_STREAMINGSet bottom wave streaming
WAVE_FRICTIONSet bottom friction in WKB model (used for streaming)
WAVE_RAMPSet wave forcing ramp using wave_ramp parameter

Preselected options in RIP test case:

# ifdef MRL_WCI
#  define WKB_WWAVE
#  define WKB_OBC_WEST
#  define WAVE_ROLLER
#  define MRL_CEW
#  define WAVE_RAMP
# define WAVE_BREAK_CT93
# endif

Summary of CPP options available for realistic regional simulations

 REGIONALrealistic configuration
Configuration Name  
O-A Coupling  
Open Boundary Conditions  
Grid Configuration  
 WET_DRYWetting-Drying scheme
Model dynamics  
Lateral Momentum Advection  
 UV_HADV_UP3default and recommended
 UV_HADV_C4no implicit diffusion: calls for UV_VIS_SMAGO in set_global_definitions.h
Lateral Momentum Mixing  
 UV_MIX_GEOexpensive and generally useless
Lateral Tracer Advection  
 TS_HADV_UP3default; nice and cheap but produces large spurious diapycnal mixing above topographic slopes and thus erosion of water masses
 TS_HADV_RSUP3recommended in realistic applications to preserve water masses; requires more than 30 sigma levels to work properly
 TS_HADV_UP5cheaper than TS_HADV_RSUP, it is; a compromise between computational cost and water mass preservation
 TS_HADV_C4no implicit diffusion: calls for UV_DIF_SMAGO in set_global_definitions.h
 TS_HADV_WENO5Quasi-monotone (and positive) scheme, preserves for spurious tracer oscillation.
 BIO_HADV_WENO5Positive scheme for passive/biology/sediment tracers if active tracers’ scheme is not TS_HADV_WENO5
Lateral Tracer Mixing  
 TS_MIX_ISOThese options are now given in set_global_definitions.h as they are intimately related to Advection options
Vertical Mixing  
 LMD_MIXINGLarge, McWilliams & Doney (1994)
 GLS_MIXINGWarner et al. (2005)
Equation of State  
Surface Forcing  
Sponge Layer  
Lateral Forcing  
 CLIMATOLOGY2D/3D fields covering the whole domainallows nudging layers to be set
 FRC_BRY1D/2D fields covering the boundary points only; does not allow nudging layers to be set but can be used with CLIMATOLOGY
Bottom Forcing  
Point Sources – Rivers  
Open Boundary Conditions  





OBC_M2CHARACT recommended for tides



OBC_M3ORLANSKI recommended



OBC_TORLANSKI recommended
Input/Output and Diagnostics  
Choice of Biology models  
Lagrangian floats model  
Sediment dynamics model  
Bottom Boundary Layer model  

Namelist : (Example of South Benguela Test Case)

South Benguela TEST MODEL
time_stepping: NTIMES dt

720 3600 60 1
S-coord: THETA_S, THETA_B, Hc (m)
7.0d0 2.0d0 200.0d0
grid: filename
forcing: filename
bulk_forcing: filename
climatology: filename
boundary: filename
initial: NRREC filename
restart: NRST, NRPFRST / filename
history: LDEFHIS, NWRT, NRPFHIS / filename
averages: NTSAVG, NAVG, NRPFAVG / filename
primary_history_fields: zeta UBAR VBAR U V wrtT(1:NT)
T T T T T 30*T
auxiliary_history_fields: rho Omega W Akv Akt Aks HBL HBBL Bostr Wstr Ustr Vstr rsw rlw lat sen HEL
F F T F T F T T T T T T 10*F

gls_history_fields: Akk Akp TKE GLS Lscale

primary_averages: zeta UBAR VBAR U V wrtT(1:NT)
T T T T T 30*T
auxiliary_averages: rho Omega W Akv Akt Aks HBL HBBL Bostr Wstr Ustr Vst rsw rlw lat sen HEL
F T T F T F T T T T T T 10*F

gls_averages: Akk Akp TKE GLS Lscale


lateral_visc: VISC2, VISC4 [/sec for all]
0. 0.
tracer_diff2: TNU2(1:NT) [/sec for all]
30 ∗ 0.d0
tracer_diff4: TNU4(1:NT) [/sec for all]
30 ∗ 0.d11
vertical_mixing: Akv_bak, Akt_bak [/sec]

0.d0 30 ∗ 0.d0
bottom_drag: RDRG [m/s], RDRG2, Zob [m], Cdb_min, Cdb_max
3.0d−04 0.d−3 0.d−3 1.d−4 1.d−1

nudg_cof: TauT_in, TauT_out, TauM_in, TauM_out [days for all]
1. 360. 3. 360.
diagnostics: ldefdia nwrtdia nrpfdia /filename
T 72 0
diag_avg: ldefdia_avg ntsdia_avg nwrtdia_avg nprfdia_avg /filename
T 0
diag3D_history_fields: diag_tracers3D(1:NT)
diag3D_history_fields: diag_tracers3D(1:NT)
diag2D_average_fields: diag_tracers2D_avg(1:NT)
diag2D_average_fields: diag_tracers2D_avg(1:NT)
diagnosticsM: ldefdiaM nwrtdiaM nrpfdiaM /filename
T 72 0
diagM_avg: ldefdiaM_avg ntsdiaM_avg nwrtdiaM_avg nprfdiaM_avg /filename
T 1 72 0
diagM_history_fields: diagM_momentum(1:2)
diagM_average_fields: diagM_momentum_avg(1:2)
diagnostics_bio: ldefdiabio nwrtdiabio nrpfdiabio /filename
T 72 0
diagbio_avg: ldefdiabio_avg ntsdiabio_avg nwrtdiabio_avg nprfdiabio_avg /filename
T 72 0

diagbioFlux_history_fields: wrtdiabioFlux
diagbioVSink_history_fields: wrtdiabioVSink
diagbioGasExc_history_fields: wrtdiabioGasExc
diagbioFlux_average_fields: wrtdiabioFlux_avg
diagbioVSink_average_fields: wrtdiabioVSink_avg
diagbioGasExc_average_fields: wrtdiabioGasExc_avg
biology: forcing file
sediments: input file
sediment_history_fields: bed_thick bed_poros be3d_fra(sand,silt)
bbl_history_fields: Abed Hripple Lripple Zbnot Zbapp Bostrw
floats: LDEFFLT, NFLT, NRPFFLT / inpname, hisname
T 6 0
float_fields: Grdvar Temp Salt Rho Vel
stations: LDEFSTA, NSTA, NRPFSTA / inpname, hisname
T 400 0
station_fields: Grdvar Temp Salt Rho Vel
psource: Nsrc Isrc Jsrc Dsrc Qbar [m3/s] Lsrc Tsrc
3 54 1 200. T T 5. 0.
3 40 0 200. T T 5. 0.
psource_ncfile: Nsrc Isrc Jsrc Dsrc qbardir Lsrc Tsrc runoff file name
24 35 0 -1 30*T 5.0 0.0
35 13 1 -1 30*T 5.0 0.0

online: byear bmonth recordsperday byearend bmonthend / data path
2000 1 4 2000 3

wkb_history_fields: swh frq action k_xi k_eta eps_b eps_d Erol eps_r

wkb_wwave: amp [m], ang [deg], prd [s], tide [m], B_tg, gamma_tg

0.5 -1. 10. 0.0 1.3 0.38
wkb_roller: roller_sinb roller_fraction

0.1 0.5


 NTIMES : Number of time-steps required for the simulation
 dt : Baroclinic time step [in s]
 NDTFAST : Number of barotropic time-steps between each baroclinic time step. For 2D configurations, ndtfast should be unity
 NINFO : Number of time-steps between printing of single line information to standard output.
 THETA_S: S-coordinate surface control parameter
 THETA_B: S-coordinate bottom control parameter
 Hc(m): Width of surface or bottom boundary layer in which higher vertical resolution is required during stretching
 filename: Name of grid file.
 filename: Name of surface forcing file : wind stress, atmospheric fluxes (E-P, net heat fluxes) and heat flux correction dQ/dSST for nudging towards SST.
 filename: Name of bulk forcing file used for atmospheric forcing with oceanic feedback
 filename: Name of climatology data files used for open boundary forcing and nudging layers. This file contains 2D/3D arrays covering the whole computational domain.
 filename: Name of boundary data file. This file contains 1D/2D arrays covering open-boundary sections only. They are well suited for long-term simulations with intra-seasonal and inter-annual forcing.
 NRREC: Switch to indicate start or re-start from a previous solution. nrrec is the time index of the initial or re-start NetCDF file assigned for initialization. If nrrec is negative (say nrrec = -1), the model will start from the most recent time record. That is, the initialization record is assigned internally.
 filename: Name of file containing the initial state.
 NRST: Number of time-steps between writing of re-start fields


  • 0: write several records every NRST time steps
  • >0: create more than one file (with sequential numbers) and write NRPRST records per file
  • -1: overwrite record every NRST time steps
 filename: name of restart file
 LDEFHIS: flag (T/F) for writing history files
 NWRT: Number of time-steps between writing of history fields


  • 0: write several records every NWRT time steps
  • >0: create more than one file (with sequential numbers) and write NRPHIS records per file
  • -1: overwrite record every NWRT time steps
 filename: Name of history file
 NTSAVG: Starting timestep for the accumulation of output time-averaged data. For instance, you might want to average over the last day of a thirty-day run.
 NAVG: Number of time-steps between writing of averaged fields


  • 0: write several records every NAVG time steps
  • >0: create more than one file (with sequential numbers) and write NRPFAVG records per file
  • -1: overwrite record every NAVG time steps
 filename: Name of average file
primary_history _fields 
 Flags for writing primary variables in history NetCDF file
auxiliary_history _fields 
 Flags for writing auxiliary variables in history NetCDF file
 Flags for writing primary variables in average NetCDF file
 Flags for writing auxiliary variables in average NetCDF file
rho0Mean density used in the Boussinesq equation.
 VISC2: Laplaplacian background viscosity in m2/s (with UV_VIS2 CPP option)
 VISC4: Bilaplacian background viscosity in m4/s (with UV_VIS4 CPP option)
 TNU2(1:NT): Laplacian background diffusivity in m2/s for each tracer (with TS_DIF2 CPP option)
 TNU4(1:NT): Laplacian background diffusivity in m4/s for each tracer (with TS_DIF4 CPP option)
 Constant vertical viscosity coefficient in m2/s for analytical vertical mixing scheme (with ANA_VMIX CPP option)
 RDRG [m/s]: Drag coefficient for linear bottom stress formulation
 RDRG2: Drag coefficient for constant quadratic bottom stress formulation
 Zob [m]: Roughness length for Von-Karman quadratic bottom stress formulation
 Cdb_min: Minimum value of drag coefficient for Von-Karman quadratic bottom stress formulation
 Cdb_max: Maximum value of drag coefficient for Von-Karman quadratic bottom stress formulation.
 Free- or partial- or no-slip wall boundary condition. 1 means free slip conditions are used.
 sponge parameters are only needed if SPONGE_GRID is undefined in set_global_definitions.h; otherwise, these parameters are assigned internally.
 X_SPONGE [m]: width of sponge layers
 V_SPONGE [m2/s]: viscosity/diffusivity values in sponge layers. These values follow a cosine profile from zero interior value to V_SPONGE at the boundary.
 TauT_in [days]: Short nudging time scale used in radiative open boundary conditions for tracer signal propagating inward the computational domain. This coefficient is used at boundary points and imposes strong nudging towards external data
 TauT_out [days]: Long nudging time scale used in radiative open boundary conditions for tracer signal propagating outward the computational domain. This coefficient is used at boundary points and imposes mild nudging towards external data. If CLIMATOLOGY is defined, it is also used in nudging layers with gradual decrease (cosine profile) from the open boundary to the inner border of the nudging layer.
 TauM_in [days]: Same as above, but for momentum equations
 TauM_out [days]: Same as above, but for momentum equations
 ldefdia: flag that activates the storage of the instantaneous tracer budget terms in a diagnostic file
 nwrtdia: Number of time-steps between writing of diagnostic fields


  • 0: write several records every NWRTDIA time steps
  • >0: create more than one file (with sequential numbers) and write NRPFDIA records per file
  • -1: overwrite record every NWRTDIA time steps
 filename: Name of instantaneous tracer diagnostic file
 ldefdia_avg: flag that activates the storage of averaged tracer budget terms in a diagnostic file
 ntsdia_avg: Starting timestep for the accumulation of output time-averaged data. For instance, you might want to average over the last day of a thirty-day run.
 nwrtdia_avg: Number of time-steps between writing of averaged diagnostic fields


  • 0: write several records every NWRTDIA_AVG time steps
  • >0: create more than one file (with sequential numbers) and write NRPFDIA_AVG records per file
  • -1: overwrite record every NWRTDIA_AVG time steps
 filename: Name of average tracer diagnostic file
diag3D_history _fields 
 flag to select which tracer equation (temp, salt, etc …) to store in diagnostic file. These terms are 3D.
diag2D_history _fields 
 flags to select which tracer equation integrated over the mixed layer depth (cf DIAGNOSTICS_TS_MLD) to store in diagnostic file. These terms are 2D.
diag3D_average _fields 
 same as diag3D_history _fields but for averaged fields
diag2D_average _fields 
 same as diag2D_history _fields but for averaged fields
 Same format as diagnostics but for momentum equations
 Same format as diag_avg but for momentum equations
diagM_history _fields 
 flag to select which momentum equation (u,v) to store in diagnostic file. These terms are 3D.
diagM_average _fields 
 same as diagM_history _fields but for averaged fields
 Same format as diagnostics but for biogeochemical budget terms (other than advection/diffusion)
 Same format as diag_avg but for biogeochemical budget terms (other than advection/diffusion)
 Flag (T or F) to select which biogechemical tracer flux to store in diagnostic file. These terms are 3D. (For NPZD type model)
 Flag (T or F) to select which biogechemical tracer sinking flux equation to store in diagnostic file. These terms are 3D. This is for NPZD type model(BIO_NChlPZD, BIO_N2ChlPZD2 and BIO_BioEBUS), you need to follow the biogechemical tracers order.
 Flag (T or F) to select which biogechemical tracer Gas exchange flux equation to store in diagnostic file. These terms are 2D.
 Same as above but averaged
 Same as above but averaged
 Same as above but averaged
 Name of file containing the Iron dust forcing used in the PISCES biogeochemical model
 input file: sediment parameters input file
sediment_history _fields 
 Flags for storing sediment fields in history file
 bed_thick: Thickness of sediment bed layer (m)
 bed_poros: Porosity of sediment bed layer (no unit)
 bed_fra(sand,silt): Volume fraction of sand/silt in bed layer (no unit)
 Flags for storing bbl fields in history file
 Abed: Bed wave excursion amplitude (m)
 Hripple: Bed ripple length (m)
 Lripple: Bed ripple length (m)
 Zbnot: Physical hydraulic bottom roughness (m)
 Zbapp: Apparent hydraulic bottom roughness (m)
 Bostrw: Wave-induced kinematic bottom stress (m)
 Lagrangian floats application. Same format as diagnostics
 inpname, hisname
 Type of fields computed for each lagrangian floats
 Fixed station application. Same format as diagnostics
 inpname, hisname
 Nsrc: point source number
 Isrc: I point source indice
 Jsrc: J point source indice
 Dsrc: Direction of point source flow (u=0,v=1)
 Qbar [m3/s]: Total transport at point source
 Lsrc: Logical switch for type of tracer to apply
 Tsrc: Tracer value
 Nsrc: point source number
 Isrc: I point source indice
 Jsrc: J point source indice
 Dsrc: Direction of point source flow (u=0,v=1)
 qbardir: Orientation


South=0 or North=0,

East=0 or West=1

 Lsrc: Logical switch for type of tracer to apply
 Tsrc: Tracer value in case of analytical value [ #undef PSOURCE_NCFILE_TS ]
 runoff file name: Input netCDF runoff file


- either only run-off flows

- either run-off and tracers concentrations

Table 23: Description of the file


  • Aumont, O. 2005. PISCES biogeochemical model description. Internal report, 36 pages
  • Beckmann, A., Haidvogel, D.B., 1993. Numerical simulation of flow around a tall isolated seamount. Part I: Problem formulation and model accuracy. Journal of Physical Oceanography 23, 1736-1753.
  • Blanke, B., Roy, C., Penven, P., Speich, S., McWilliams, J.C., Nelson, G., 2002. Linking wind and upwelling interannual variability in a regional model of the southern Benguela, Geophysical Research Letters 29, 2188-2191.
  • Blaas, M., C. Dong, P. Marchesiello, J.C. McWilliams, K.D. Stolzenbach, 2007: Sediment-transport modeling on Southern Californian shelves: A ROMS case study. Continental Shelf Research, 27, 832-853.
  • Blayo, E., Debreu, L., 1999. Adaptive mesh refinement for finite-difference ocean models: First experiments. Journal of Physical Oceanography 29, 1239-1250.
  • Carton, J.A., Giese, B.S., Grodsky, S.A., 2005. Sea level rise and the warming of the oceans in the Simple Ocean Data Assimilation (SODA) ocean reanalysis. Journal of Geophysical Research 110, C09006, doi:10.1029/2004JC002817.
  • Casey, K.S., Cornillon, P., 1999. A comparison of satellite and in situ based sea surface temperature climatologies. Journal of Climate 12, 1848-1863.
  • Conkright, M.E., R.A. Locarnini, H.E. Garcia, T.D. O Brien, T.P. Boyer, C. Stephens, J.I. Antonov, 2002. World Ocean Atlas 2001: Objective Analyses, Data Statistics, and Figures, CD-ROM Documentation. National Oceanographic Data Center, Silver Spring, MD, 17 pp.
  • Da Silva, A.M., Young, C.C., Levitus, S. 1994. Atlas of surface marine data 1994, Vol. 1, algorithms and procedures, NOAA Atlas NESDIS 6, U. S. Department of Commerce, NOAA, NESDIS, USA, 74 pp.
  • Debreu, L., 2000. Raffinement adaptatif de maillage et méthodes de zoom – application aux modèles d’océan, 2000, Ph.D. thesis, Université Joseph Fourier, Grenoble.
  • Debreu, L., Blayo, E., 2003. AGRIF: Adaptive Grid Refinement In Fortran. submitted to ACM Transactions on Mathematical Software – TOMS.
  • Debreu, L., Vouland, C., 2003. AGRIF: Adaptive Grid Refinement In Fortran. [Available online].
  • Debreu, L., Blayo, E., 2008. Special Issue on Multi-Scale Modelling: Nested Grid and Unstructured Mesh Approaches. Ocean Dynamics 58, 415-428. doi 10.1007/s10236-008-0150-9
  • Debreu, L., P. Marchesiello, P. Penven, and G. Cambon, 2012 : Two-way nesting in split-explicit ocean models: algorithms, implementation and validation. Ocean Modelling, 49-50, 1-21.
  • Di Lorenzo, E., Miller, A.J., Neilson, D.J., Cornuelle, B.D., Moisan, J.R., 2003. Modeling observed California Current mesoscale eddies and the ecosystem response . International Journal of Remote Sensing, in press.
  • Egbert, G., Erofeeva, S., 2002. Efficient inverse modeling of barotropic ocean tides, Journal of Atmospheric and Oceanic Technology 19, 183-204.
  • Fairall, C.W., E.F. Bradley, E.F., Rogers D.P., Edson J.B., Young G.S. 1996. Bulk parameterization of air-sea fluxes for topical ocean-global atmosphere Coupled-Ocean Atmosphere Response Experiment, JGR, 101, 3747-3764
  • Flather, R.A., 1976. A tidal model of the northwest European continental shelf. Mémoires de la Société Royale des Sciences de Liège, 10, 141-164.
  • Gruber, N., Lachkar, Z., Frenzel, H., Marchesiello, P., Munnich, M., McWilliams, J. C., Nagai, T., and Plattner, G.-K, 2011.: Eddy-induced reduction of biological production in eastern boundary upwelling systems, Nat. Geosci., 4, 787–792.
  • Gruber, N., H. Frenzel, S.C. Doney, P. Marchesiello, J. C. McWilliams, J. R. Moisan, J. Oram, G.-K., Plattner, and K.D. Stolzenbach, 2006: Eddy-resolving simulation of plankton ecosystem dynamics in the California Current System. Deep-Sea Research I, 53, 1483-1516.
  • Gutknecht, E., Dadou, I., Le Vu, B., Cambon, G., Sudre, J., Garc ̧on, V., Machu, E., Rixen, T., Kock, A., Flohr, A., Paulmier, A., and Lavik, G.: Coupled physical/biogeochemical modeling includ- ing O2-dependent processes in the Eastern Boundary Upwelling Systems: application in the Benguela, Biogeosciences, 10, 3559– 3591, doi:10.5194/bg-10-3559-2013, 2013.
  • Haidvogel, D.B., Arango, H.G., Hedstrom, K. , Beckmann, A., Malanotte-Rizzoli, P., Shchepetkin, A.F., 2000. Model Evaluation Experiments in the North Atlantic Basin: Simulations in Nonlinear Terrain-Following Coordinates. Dynamics of Atmospheres and Oceans 32 , 239-281.
  • Haney, R.L., 1991. On the pressure force over steep topography in sigma coordinate ocean models. Journal of Physical Oceanography 21, 610-619.
  • Hedstrom, K. S., 1997. SCRUM Manuel, Institute of Marine and Coastal Sciences, Rutgers University, USA
  • Hedstroem, K. S., 2009. DRAFT Technical Manual for a Coupled Sea-Ice/Ocean Circulation Model (Version 3), U.S Department of the Interior, Mineral Management Service, Anchorage, Alaska, Arctic Region Supercomputing Center, University of Alaska Fairbanks, Contract M07PC13368
  • Jackett, D.R., McDougall, T.J., 1995. Minimal Adjustment of Hydrostatic Profiles to Achieve Static Stability. Journal of Atmospheric and Oceanic Technology 12, 381-389.
  • Large, W.G., McWilliams, J.C., Doney, S.C., 1994. Oceanic vertical mixing: a review and a model with a nonlocal boundary layer parameterization. Reviews in Geophysics 32, 363-403.
  • Lemarié, F., J. Kurian, A.F. Shchepetkin, M.J. Molemaker, F. Colas, and J.C. McWilliams, 2011: Are there inescapable issues prohibiting the use of terrain-following coordinates in climate models. Ocean Modelling, 42, 57-79.
  • Lemarié, F., L. Debreu, A.F. Shchepetkin, and J.C. McWilliams, 2012: On the stability and accuracy of the harmonic and biharmonic adiabatic mixing operators in ocean models. Ocean Modelling.
  • MacCready, P. M., R. D. Hetland, W. R. Geyer, Long-Term Isohaline Salt Balance in an Estuary. Continental Shelf Research, 22, 1591-1601.
  • Marchesiello, P., Debreu, L., Couvelard, X. 2009. Spurious diapycnal mixing in terrain-following coordinate models: The problem and a solution. Ocean Modelling 26, 156-169.
  • Marchesiello, P., McWilliams, J.C., Shchepetkin, A., 2001. Open boundary condition for long-term integration of regional oceanic models. Ocean Modelling 3, 1-21.
  • Marchesiello, P., McWilliams, J.C., Shchepetkin, A., 2003. Equilibrium structure and dynamics of the California Current System. Journal of Physical Oceanography 33, 753-783.
  • McWilliams, J. C., Restrepo, J. M., Lane, E. M., 7 2004. An asymptotic theory for the interaction of waves and currents in coastal waters. Journal of Fluid Mechanics 511, 135–178.
  • Penven, P., Roy C., Lutjeharms, J.R.E., Colin de verdière, A., Johnson, A., Shillington, F., Fréon, P., Brundrit, G., 2001. A regional hydrodynamic model of the Southern Benguela. South African Journal of Science 97, 472-476.
  • Penven, P., Debreu, L., Marchesiello, P., McWilliams, J.C., 2006. Application of the ROMS embedding procedure for the Central California Upwelling System. Ocean Modelling 12, 157-187.
  • Penven, P., Marchesiello, P., Debreu, L., Lefèvre, J., 2007. Software tools for pre- and post-processing of oceanic regional simulations. Environmental Modelling and Software, in press.
  • Reynolds, R.W., Smith, T.M., 1994. Improved global sea surface temperature analyses using optimum interpolation. Journal of Climate. 7, 929-948.
  • Shchepetkin, A.F., McWilliams, J.C., 1998. Quasi-monotone advection schemes based on explicit locally adaptive dissipation. Monthly Weather Review 126, 1541-1580.
  • Shchepetkin, A.F., McWilliams, J.C., 2005. Regional Ocean Model System: a split-explicit ocean model with a free-surface and topography-following vertical coordinate. Ocean Modelling 9, 347-404.
  • Shchepetkin A.F, McWilliams J.C., 2009. Computational kernel algorithms for fine-scale, multiprocess, longtime oceanic simulations, In: P.G. Ciarlet, Editor(s), Handbook of numerical analysis, Elsevier, 2009, Volume 14, Pages 121-183.
  • Smith, W.H.F., Sandwell, D.T., 1997. Global seafloor topography from satellite altimetry and ship depth soundings. Science 277, 1957-1962.
  • Uchiyama, Y., McWilliams, J. C., Restrepo, J. M., 2009. Wave-current interac- tion in nearshore shear instability analyzed with a vortex force formalism. Journal of Geophysical Research: Oceans 114 (C6),
  • Warner, J. C., Defne, Z., Haas, K., Arango, H. G., 2013. A wetting and drying scheme for ROMS. Computers and Geosciences 58 (0), 54 – 61.
  • Wunsch, C., Zlotnicki., V., 1999. The consortium for estimating the circulation and climate of the ocean (ECCO) – Science goals and task plan – Report N°1. Techical report, Jet Propulsion Laboratory – Massachusetts Institute of Technology – Scripps Institution of Oceanography.