CROCO Technical and Numerical Documentation

Croco Documentation Release 2.1.2 S. Jullien, M. Caillaud, R. Benshila, L. Bordois, G. Cambon, F. Dufois, F. Dumas, J. Gula, M. Le Corre, S. Le Gac, S. Le Gentil, F. Lemarié, P. Marchesiello, G. Morvan, J. Pianezze, L. Renault, A.L. Schaefer, M. Schreiber, S. Theetten and S. Valat, Nov 18, 2025 CONTENTS 1 Model Documentation 3 1.1 Governing Equations ......................................... 3 1.1.1 Primitive Equations ..................................... 3 1.1.2 Quasi-Hydrostatic Equations ................................ 6 1.1.3 Wave-averaged Equations .................................. 6 1.1.4 Non-Hydrostatic, Non-Boussinesq Equations ....................... 10 1.2 Model variables ........................................... 11 1.2.1 Domain variables (grid.h).................................. 11 1.2.2 Barotropic variables (ocean2d.h).............................. 12 1.2.3 Tri-dimensionnal variables (ocean3d.h).......................... 12 1.2.4 Surface forcing (forces.h) .................................. 13 1.3 Grid and Coordinates ......................................... 14 1.3.1 Vertical Grid parameters .................................. 15 1.3.2 Grid staggering ....................................... 17 1.3.3 Wetting-Drying ....................................... 17 1.4 Numerics ............................................... 17 1.4.1 Overview .......................................... 17 1.4.2 Time Stepping ........................................ 18 1.4.3 Advection Schemes ..................................... 22 1.4.4 Pressure gradient ...................................... 28 1.4.5 Equation of State ...................................... 28 1.4.6 Wetting and Drying ..................................... 28 1.4.7 Non-Boussinesq Solver ................................... 29 1.5 Parametrizations ........................................... 29 1.5.1 Vertical mixing parametrizations .............................. 29 1.5.2 Horizontal diffusion ..................................... 35 1.5.3 Bottom friction ....................................... 37 1.6 Parallelisation ............................................ 37 1.6.1 Parallel strategy overview .................................. 38 1.6.2 Variable placement for staggered grids ........................... 41 1.6.3 Loops and indexes for staggered grids ........................... 41 1.6.4 Halo layer exchanges .................................... 42 1.6.5 Dealing with outputs .................................... 42 1.6.6 Run with GPU ....................................... 43 1.7 Atmospheric Surface Boundary Layer ................................ 44 1.8 Open boundaries conditions ..................................... 48 1.8.1 OBC ............................................. 48 1.8.2 Sponge Layer ........................................ 49 1.8.3 Nudging layers ....................................... 49 1.8.4 Lateral forcing ....................................... 50 1.9 Rivers ................................................. 51 1.10 Tides ................................................. 52 1.11 Wavemaker .............................................. 54 1.11.1 Formulation ......................................... 54 i 1.11.2 Input parameters ...................................... 54 1.11.3 JONSWAP spectrum .................................... 55 1.12 Nesting Capabilities ......................................... 56 1.13 Other modules : sediment models, flow-obstruction models, biology models ........... 57 1.13.1 Bottom Boundary Layer model ............................... 57 1.13.2 Sediment models ...................................... 59 1.13.3 OBSTRUCTIONS module : flow in presence of various obstructions ...........115 1.13.4 Biogeochemical models ...................................127 1.13.5 Lagrangian floats ......................................128 1.14 Coupling CROCO with other models ................................128 1.14.1 OASIS philosophy .....................................129 1.14.2 Detailed OASIS implementation ..............................132 1.14.3 Coupled variables ......................................137 1.14.4 Grids ............................................144 1.15 I/O and Online Diagnostics .....................................145 1.15.1 General ouptut options ...................................145 1.15.2 Advanced diagnostics options ...............................146 1.16 Testing CROCO ...........................................150 1.16.1 Test Script ..........................................150 1.16.2 Review of test cases .....................................161 1.17 Appendices ..............................................236 1.17.1 cppdefs.h ..........................................236 1.17.2 croco.in ...........................................245 1.17.3 Comparison of ROMS and CROCO versions .......................251 2 Tutorials 255 2.1 System requirements .........................................255 2.1.1 Disk space ..........................................255 2.1.2 Compilers and Libraries ..................................255 2.1.3 Environment variables ...................................255 2.2 Download ...............................................256 2.2.1 Downloading CROCO ...................................256 2.2.2 Getting other codes (coupling) ...............................256 2.3 Contents & Architecture .......................................258 2.3.1 Architecture .........................................258 2.3.2 Contents of CROCO source code ..............................258 2.4 Summary of essential steps .....................................258 2.5 Test Cases ..............................................260 2.5.1 BASIN ...........................................260 2.5.2 Set up you own test case ..................................262 2.6 Preparing a regional configuration ..................................265 2.7 Preprocessing .............................................266 2.7.1 Matlab Tools : croco_tools .................................267 2.7.2 Python Tools : croco_pytools ................................267 2.8 Compiling ..............................................267 2.8.1 cppdefs.h ..........................................268 2.8.2 param.h ...........................................271 2.8.3 Compilation using jobcomp ................................272 2.8.4 Compilation options ....................................273 2.8.5 Tips in case of errors during compilation ..........................273 2.9 Running the model ..........................................274 2.9.1 Edit croco.in ........................................274 2.9.2 Run the model ........................................277 2.9.3 Tips in case of BLOW UP or ERROR ...........................278 2.10 Increasing the resolution: BENGUELA_VHR ...........................279 2.11 Running with interannual forcing ..................................279 2.11.1 Run after classical interannual pre-processing .......................279 2.11.2 Alternative method: online interpolation of atmospheric bulk forcing ...........283 ii 2.12 Nesting Tutorial ...........................................284 2.13 Adding Rivers ............................................284 2.13.1 Constant flow and concentration ..............................284 2.13.2 Variable flow read in a netCDF file and constant concentration .............285 2.13.3 Variable flow and variable concentration from a netCDF file ..............285 2.13.4 Using a nest .........................................286 2.14 Adding tides .............................................286 2.14.1 Pre-processing .......................................286 2.14.2 Compiling ..........................................286 2.14.3 Running ...........................................287 2.15 Post processing ............................................287 2.15.1 Matlab Tools : croco_tools .................................287 2.15.2 Python Tools : croco_pytools ................................287 2.16 NBQ Tutorial .............................................288 2.16.1 Some important points about Large-Eddy Simulations (LES) ...............288 2.16.2 KH_INST Test Case ....................................290 2.16.3 Set up your own NBQ configuration ............................292 2.16.4 NBQ OPTIONS .......................................293 2.16.5 Appendix : some words on CROCO-NBQ kernel .....................293 2.17 Coupling tutorial ...........................................294 2.17.1 Summary of steps for coupling ...............................294 2.17.2 Compiling in coupled mode ................................295 2.17.3 Simple CROCO-TOY coupled example ..........................303 2.17.4 Advanced coupling tutorial .................................308 2.18 Littoral tutorial ............................................341 2.19 Realistic coastal configuration ....................................345 2.20 XIOS .................................................345 2.21 Tips ..................................................348 2.21.1 Tips in case of errors during compilation ..........................348 2.21.2 TIPS for errors at runtime ..................................349 2.21.3 Analytical forcing ......................................349 2.21.4 MUSTANG tips .......................................350 Bibliography 355 iii iv Croco Documentation, Release 2.1.2 CROCO is an oceanic modeling system built upon ROMS_AGRIF and maintained by IRD, INRIA, CNRS, IFREMER and SHOM, French institutes working on environmental sciences and applied mathematics. An important objective for CROCO is to resolve very fine scales (especially in the coastal area), and their interactions with larger scales. It includes new capabilities such as a non-hydrostatic solver, ocean-wave-atmosphere coupling, evolving sediment dynamics and marine biogeochemistry, new high-order numerical schemes for advection and mixing, and a dedicated I/O server (XIOS). A toolbox for preand post-processing, CROCO_TOOLS, accompanies the source code. CROCO will keep evolving and integrating new capabilities in the following years. CONTENTS 1 Croco Documentation, Release 2.1.2 2 CONTENTS CHAPTER ONE MODEL DOCUMENTATION 1.1 Governing Equations Related CPP options: SOLVE3D Solve 3D primitive equations UV_COR Activate Coriolis terms UV_ADV Activate advection terms NBQ Activate non-boussinesq option CROCO_QH Activate quasi-hydrostatique option MRL_WCI Activate wave-current interactions Preselected options: # define SOLVE3D # define UV_COR # define UV_ADV # undef NBQ # undef CROCO_QH # undef MRL_WCI Presentation By default (#undef NBQ), CROCO solves the primitive equations as in ROMS, from which it inherited the robustness and efficiency of its time-splitting implementation [Shchepetkin and McWilliams, 2005,Debreu et al., 2012] and the NBQ option proposes an extension for nonhydrostatic applications. In CROCO’s time-splitting algorithm, the ”slow mode” is similar to ROMS internal (baroclinic) mode described in Shchepetkin and McWilliams [2005], whereas, the ”fast mode” can include, in addition to the external (barotropic) mode, the pseudo-acoustic mode that allows computation of the nonhydrostatic pressure within a non-Boussinesq approach [Auclair et al., 2018]. In this case, the slow internal mode is also augmented by a prognostic equation of vertical velocity, replacing the hydrostatic equation. Another option (CROCO_QH) extends the PE equations to form the quasi-hydrostatic equations, relaxing the hypothesis of weak horizontal Coriolis force [Marshall et al., 1997], thus adding a nonhydrostatic pressure component that is solved diagnostically. Then another option (MRL_WCI) treats the wave-averaged equations [McWilliams et al., 2004] with wave-current interaction terms that are both conservative and non-conservative (needing parametrizations). 1.1.1 Primitive Equations At resolutions larger than 1 km (more marginally above 100 m), The ocean is a fluid that can be described as a good approximation by the primitive equations (PE). The PE equations are simplifications from the Navier-Stokes equations made from scale considerations, along with a nonlinear equation of state, which couples the two active tracers (temperature and salinity): •Hydrostatic hypothesis: the vertical momentum equation is reduced to a balance between the vertical pressure gradient and the buoyancy force (non-hydrostatic processes such as convection must be parametrized) •Boussinesq hypothesis: density variations are neglected except in their contribution to the buoyancy force 3 Croco Documentation, Release 2.1.2 of breaker. 𝐻𝑟𝑚𝑠 is the RMS wave height. For the DUCK94 experiment, Uchiyama et al. [2010] suggest 𝛾𝑏= 0.4 and 𝐵𝑏= 0.8, while for Biscarrosse Beach, Marchesiello et al. [2015] use 𝛾𝑏= 0.3and 𝐵𝑏= 1.3from calibration with video cameras. For 𝜖𝑤𝑑, the dissipation caused by bottom viscous drag on the primary waves, we use a parameterization for the realistic regime of a turbulent wave boundary layer, consistent with the WKB spectrum-peak wave modeling: 𝜖𝑤𝑑 =1 2√𝜋𝜌𝑓𝑤𝑢3 𝑜𝑟𝑏 where 𝑢𝑜𝑟𝑏 is the wave orbital velocity magnitude and 𝑓𝑤is a wave friction factor, function of roughness length 𝑧0: 𝑢𝑜𝑟𝑏 =𝜎𝐻𝑟𝑚𝑠 2 sinh 𝑘𝐷 𝑓𝑤= 1.39 (︂𝜎𝑧0 𝑢𝑜𝑟𝑏 )︂0.52 1.1.4 Non-Hydrostatic, Non-Boussinesq Equations The full set of Navier-Stokes equations for a free-surface ocean is explicitly integrated in the non-hydrostatic, non-Boussinesq version of CROCO (#define NBQ). In this approach, acoustic waves are solved explicitly to avoid Boussinesq-degeneracy, which inevitably leads to a 3D Poisson system in non-hydrostatic Boussinesq methods – detrimental to computational costs and challenging to implement within a split-explicit barotropic/baroclinic model. NBQ equations include the momentum and continuity equations, the surface kinematic relation (for free surface), temperature, salinity – or other tracer 𝐶– and the equation of state, which reads in Cartesian coordinates: 𝜕𝜌𝑢 𝜕𝑡 + ∇.(𝜌 v𝑢)−𝜌𝑓𝑣 +𝜌˜ 𝑓𝑤 =−𝜕𝑃 𝜕𝑥 +𝜆𝜕 ∇. v 𝜕𝑥 +ℱ𝑢+𝒟𝑢 𝜕𝜌𝑣 𝜕𝑡 + ∇.(𝜌 v𝑣) + 𝜌𝑓𝑢 =−𝜕𝑃 𝜕𝑦 +𝜆𝜕 ∇. v 𝜕𝑦 +ℱ𝑣+𝒟𝑣 𝜕𝜌𝑤 𝜕𝑡 + ∇.(𝜌 v𝑤)−𝜌˜ 𝑓𝑢 =−𝜕𝑃 𝜕𝑧 −𝜌𝑔 +𝜆𝜕( ∇. v) 𝜕𝑧 +ℱ𝑤+𝒟𝑤 𝜕𝜌 𝜕𝑡 =− ∇.(𝜌 v) 𝜕𝜉 𝜕𝑡 =𝑤𝑓|𝑧=𝜉− v|𝑧=𝜉. ∇𝜉 𝜕𝜌𝐶 𝜕𝑡 =− ∇.(𝜌 v𝐶) + ℱ𝐶+𝒟𝐶 𝜆is the second (bulk) viscosity associated with compressibility (it can be used to damp acoustic waves). A relation between 𝜌and 𝑃is now required. To that end, and as part of a time-splitting approach, density is decomposed into slow and fast components based on a first-order decomposition concerning total pressure. In the following, 𝑠and 𝑓subscripts refer to slow and fast-mode components, respectively: 𝜌=𝜌𝑠(𝑇, 𝑆, 𝑃) + 𝜌𝑓=𝑐−2 𝑠𝑃𝑓 ⏞ ⏟ 𝜕𝜌 𝜕𝑃 𝑇,𝑆 𝛿𝑃 +𝑂(𝛿𝑃2) 𝑃=𝑃𝑎𝑡𝑚 +∫︁𝜉 𝑧 (𝜌𝑠−𝜌0)𝑔 𝑑𝑧′ ⏟ ⏞ 𝑆𝐿𝑂𝑊 +𝜌0𝑔(𝜉−𝑧) + 𝑃𝑓 ⏞ ⏟ 𝛿𝑃 ⏟ ⏞ 𝐹 𝐴𝑆𝑇 𝑐𝑠is the speed of sound and 𝛿𝑃 =𝑃𝑓is the nonhydrostatic pressure. The Navier-Stokes equations are then integrated with two different time steps within the time-splitting approach. The slow mode is identical to ROMS, whereas the fast mode (in the NBQ equations) is 3D and the fast time step 10 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 includes the integration of the compressible terms of the momentum and continuity equations. In vector form: 𝜕𝜌 v 𝜕𝑡 =− ∇.(𝜌 v⊗ v)−2𝜌 Ω× v− ∇(∫︁𝜉𝑓 𝑧 (𝜌𝑠−𝜌0)𝑔 𝑑𝑧′) +  ℱ v+ 𝒟 v ⏟ ⏞ 𝑆𝐿𝑂𝑊 −𝜌0𝑔 ∇𝜉𝑓− ∇𝑃𝑓+𝜌 g+𝜆 ∇( ∇. v) ⏟ ⏞ 𝐹 𝐴𝑆𝑇 𝜕𝜌𝑓 𝜕𝑡 =−𝜕𝜌𝑠 𝜕𝑡 − ∇.(𝜌 v) 𝑃𝑓=𝑐2 𝑠𝜌𝑓 𝜕𝜉𝑓 𝜕𝑡 =𝑤𝑓|𝑧=𝜉− v𝑓|𝑧=𝜉. ∇𝜉𝑓 𝜕𝜌𝐶𝑠 𝜕𝑡 =− ∇.(𝜌 v𝐶𝑠) + ℱ𝐶+𝒟𝐶 𝜌𝑠=𝜌(𝑇𝑠, 𝑆𝑠, 𝜉𝑓) 𝜌=𝜌𝑠+𝜌𝑓 The momentum is integrated both in slow and fast modes but the right-hand-side of the equation is split in two parts: a slow part, made of slowly varying terms (advection, Coriolis force, baroclinic pressure force and viscous dissipation), and a fast part, made of fast-varying terms (the surface-induced and compressible pressure force, the weight and the dissipation associated with bulk-viscosity). This momentum equation is numerically integrated twice, once with a large time-step keeping the fast part constant, and once with a smaller time-step keeping the slow part constant. This is much more computationally efficient than integrating the whole set of equations at the same fast time step. More details can be found in Auclair et al. [2018]. Note that the solved acoustic waves can become pseudo-acoustic if their phase speed 𝑐𝑠is artificially slowed down (it is a model input). In this case, high-frequency processes associated with bulk compressibility may be unphysical, but a coherent solution for slow non-hydrostatic dynamics is preserved, while the CFL constraint is relaxed. 1.2 Model variables Model variables are defined in .h Fortran 77 files : 1.2.1 Domain variables (grid.h) grid.h : Environmental two-dimensional arrays associated with curvilinear horizontal coordinate system h : Model topography (bottom depth [m] at RHO-points.) dh : Topograhy increment in case of moving bathymetry f : Coriolis parameter [1/s]. fomn : Compound term, f/[pm*pn] at RHO points. angler : Angle [radians] between XI-axis and the direction to the EAST at RHO-points. latr : Latitude (degrees_north) at RHO-, U-, and V-points. latu latv lonr : Longitude (degrees_east) at RHO-, U-, and V-points. lonu lonv xp : XI-coordinates [m] at PSI-points. 1.2. Model variables 11 Croco Documentation, Release 2.1.2 xr : XI-coordinates [m] at RHO-points. yp : ETA-coordinates [m] at PSI-points. yr : ETA-coordinates [m] at RHO-points. pm : Coordinate transformation metric “m” [1/meters] associated with the differential distances in XI. pn : Coordinate transformation metric “n” [1/meters]associated with the differential distances in ETA. om_u : Grid spacing [meters] in the XI -direction at U-points. om_v : Grid spacing [meters] in the XI -direction at V-points. on_u : Grid spacing [meters] in the ETA-direction at U-points. on_v : Grid spacing [meters] in the ETA-direction at V-points. dmde : ETA-derivative of inverse metric factor “m”, d(1/M)/d(ETA). dndx : XI-derivative of inverse metric factor “n”, d(1/N)/d(XI). pmon_p : Compound term, pm/pn at PSI-points. pmon_r : Compound term, pm/pn at RHO-points. pmon_u : Compound term, pm/pn at U-points. pnom_p : Compound term, pn/pm at PSI-points. pnom_r : Compound term, pn/pm at RHO-points. pnom_v : Compound term, pn/pm at V-points. rmask : Land-sea masking arrays at RHO-,U-,Vand PSI-points (rmask,umask,vmask) = (0=Land, 1=Sea) umask vmask pmask : pmask=(0=Land, 1=Sea, 1-gamma2 =boundary). reducu : reduction coefficient along x-axis for rivers sections reducv : reduction coefficient along y-axis for rivers sections 1.2.2 Barotropic variables (ocean2d.h) ocean2d.h : 2D dynamical variables for fast mode zeta,rzeta : Free surface elevation [m] and its time tendency; ubar,rubar : Vertically integrated 2D velocity components in vbar,rvbar : XIand ETA-directions and their time tendencies; 1.2.3 Tri-dimensionnal variables (ocean3d.h) ocean3d.h : 3D tracers dynamical variables for baroclinic mode u,v : 3D velocity components in XIand ETA-directions t : tracer array (temperature, salinity, passive tracers, sediment) Hz : level thickness z_r : depth at rho point z_w : depth at w point 12 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 Huon : transport a U point Hvon : transport at V point We, Wi : vertical velocity (explicit, implicit) rho : density anomaly rho1 : potential density at 1 atm 1.2.4 Surface forcing (forces.h) forces.h : Surface momemtum flux (wind stress) : sustr : XIand ETA-components of kinematic surface momentum flux svstr : wind stresses) defined at horizontal Uand V-points.dimensioned as [m^2/s^2]. Bottom mometum flux : bustr : XIand ETA-components of kinematic bottom momentum flux bvstr : (drag) defined at horizontal Uand V-points [m^2/s^2].! Surface tracers fluxes : stflx : Kinematic surface fluxes of tracer type variables at horizontal RHO-points. Physical dimensions [degC m/s] - temperature; [PSU m/s] - salinity. dqdt : Kinematic surface net heat flux sensitivity to SST [m/s]. sst : Current sea surface temperature [degree Celsius]. dqdtg : Two-time-level grided data for net surface heat flux sstg : sensitivity to SST grided data [Watts/m^2/Celsius] and sea surface temperature [degree Celsius]. dqdtp : Two-time-level point data for net surface heat flux sstp : sensitivity to SST grided data [Watts/m^2/Celsius] and sea surface temperature [degree Celsius]. tsst : Time of sea surface temperature data. sss : Current sea surface salinity [PSU]. tair : surface air temperature at 2m [degree Celsius]. wsp : wind speed at 10m [degree Celsius]. rhum : surface air relative humidity 2m [fraction] prate : surface precipitation rate [cm day-1] radlw : net terrestrial longwave radiation [Watts meter-2] radsw : net solar shortwave radiation [Watts meter-2] patm2d : atmospheric pressure above mean seal level paref : reference pressure to compute inverse barometer effect srflx : Kinematic surface shortwave solar radiation flux [degC m/s] at horizontal RHO-points Wind induced waves everything is defined at rho-point : wfrq : wind-induced wave frequency [rad/s] uorb : xi-component of wave-induced bed orbital velocity [m/s] vorb : eta-component of wave-induced bed orbital velocity [m/s] 1.2. Model variables 13 Croco Documentation, Release 2.1.2 wdrx : cosine of wave direction [non dimension] wdre : sine of wave direction [non dimension] whrm : (RMS) wave height (twice the wave amplitude) [m] wepb : breaking dissipation rate (epsilon_b term) [m3/s3] wepd : frictional dissipation rate (epsilon_d term) [m3/s3] wepr :roller dissipation rate (epsilon_r term) [m3/s3] wbst : frictional dissipation stress (e_d k/sigma) [m2/s2] Wave averaged quantities : brk2dx : xi-direciton 2D breaking dissipation (rho) brk2de : eta-direction 2D breaking dissipation (rho) frc2dx : xi-direciton 2D frictional dissipation (rho) frc2de : eta-direction 2D frictional dissipation (rho) ust2d : xi-direciton Stokes transport (u-point) vst2d : eta-direciton Stokes transport (v-point) sup : quasi-static wave set-up (rho-point) calP : pressure correction term (rho-point) Kapsrf : Bernoulli head terrm at the surface (rho-point) brk3dx : xi-direciton 3D breaking dissipation (rho) brk3de : eta-direction 3D breaking dissipation (rho) ust : xi-direciton 3D Stokes drift velocity (u-point) vst : eta-direciton 3D Stokes drift velocity (v-point) wst : vertical 3D Stokes drift velocity (rho-point) Kappa : 3D Bernoulli head term (rho-point) kvf : vertical vortex force term (K term, 3D, rho-point) Akb : breaking-wave-induced additional diffusivity (w-point) Akw : wave-induced additional diffusivity (rho-point) E_pre : previous time-step value for Akw estimation (rho) frc3dx : xi-direciton 3D frictional dissipation (rho) frc3de : eta-direction 3D frictional dissipation (rho) 1.3 Grid and Coordinates Related CPP options: CURVGRID Activate curvilinear coordinate transformation SPHERICAL Activate longitude/latitude grid positioning MASKING Activate land masking WET_DRY Activate wetting-Drying scheme NEW_S_COORD Choose new vertical S-coordinates Preselected options: # define CURVGRID # define SPHERICAL # define MASKING # undef WET_DRY # undef NEW_S_COORD 14 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 1.3.1 Vertical Grid parameters Two vertical transformations are available for the generalized vertical terrain-following vertical system : By default, we have : 𝑧(𝑥, 𝑦, 𝜎, 𝑡) = 𝑧0(𝑥, 𝑦, 𝜎) + 𝜁(𝑥, 𝑦, 𝑡)[︂1 + 𝑧0(𝑥, 𝑦, 𝜎) ℎ(𝑥, 𝑦)]︂(1.1) 𝑧0(𝑥, 𝑦, 𝜎) = ℎ𝑐𝜎+ [ℎ(𝑥, 𝑦)−ℎ𝑐]𝐶𝑠(𝜎)(1.2) When activating the cpp key NEW_S_COORD, we have: 𝑧(𝑥, 𝑦, 𝜎, 𝑡) = 𝜁(𝑥, 𝑦, 𝜎)+[𝜁(𝑥, 𝑦, 𝑡) + ℎ(𝑥, 𝑦)] 𝑧0(𝑥, 𝑦, 𝜎)(1.3) 𝑧0(𝑥, 𝑦, 𝜎) = ℎ𝑐𝜎+ℎ(𝑥, 𝑦)𝐶𝑠(𝜎) ℎ𝑐+ℎ(𝑥, 𝑦)(1.4) with : •𝑧0(𝑥, 𝑦, 𝜎)a nonlinear vertical transformation •𝜁(𝑥, 𝑦, 𝜎)the free-surface •ℎ(𝑥, 𝑦)the ocean bottom •𝜎a fractional vertical stretching coordinate, −1≤𝜎≤0 •ℎ𝑐a positive thickness controlling the stretching •𝐶𝑠(𝜎)a nondimensional, monotonic, vertical stretching, −1≤(𝐶𝜎)≤0 Vertical grid stretching is controlled by the following parameters, which have to be set similarly in croco.in, and crocotools_param.m: theta_s Vertical S-coordinate surface stretching parameter. When building the climatology and initial CROCO files, we have to define the vertical grid. Warning! The different vertical grid parameters should be identical in this crocotools_param.m and in croco.in. This is a serious cause of bug. theta_b Vertical S-coordinate bottom stretching parameter. hc Vertical S-coordinate Hc parameter. It gives approximately the transition depth between the horizontal surfacelevels and the bottom terrain following levels. (Note it should be inferior to hmin in case of Vtransform =1). Then we have, with 𝑁the number of vertical levels: •with the old transformation : 𝐶𝑠(𝜎) = (1 −𝜃𝑏)𝑠𝑖𝑛ℎ(𝜃𝑠𝜎) 𝑠𝑖𝑛ℎ(𝜃𝑠)+𝜃𝑏[︂0.5𝑡𝑎𝑛ℎ ((𝜎+ 0.5) 𝜃𝑠) 𝑡𝑎𝑛ℎ(0.5𝜃𝑠)−0.5]︂ •with NEW_S_COORD defined : 𝑠𝑐 =𝜎−𝑁 𝑁(1.5) 𝑐𝑠𝑓 =1.−𝑐𝑜𝑠ℎ(𝜃𝑠𝑠𝑐) 𝑐𝑜𝑠ℎ(𝜃𝑠)−1.if 𝜃𝑏>0, 𝑐𝑠𝑓 =−𝑠𝑐2otherwise (1.6) 𝐶𝑠(𝜎) = 𝑒𝜃𝑏𝑐𝑠𝑓 −1. 1.−𝑒−𝜃𝑏if 𝜃𝑠>0, 𝐶𝑠(𝜎) = 𝑐𝑠𝑓 otherwise (1.7) Other parameters have to be set to prepare the grid file in crocotools_param.m: 1.3. Grid and Coordinates 15 Croco Documentation, Release 2.1.2 vtransform S-coordinate type (1: old- ; 2: newcoordinates). It is associated to #NEW_S_COORD cpp-keys in CROCO source code. hmin Minimum depth in meters. The model depth is cut at this level to prevent, for example, the occurrence of model grid cells without water. This does not influence the masking routines. At lower resolution, hmin should be quite large (for example, 150m for dl=1/2). Otherwise, since topography smoothing is based on, the bottom slopes can be totally eroded. hmax_coast Maximum depth under the mask. It prevents selected isobaths (here 500 m) from going under the mask. If this is the case, this could be a source of problems for western boundary currents (for example). hmax Maximum depth rtarget This variable controls the maximum value of the -parameter that measures the slope of the sigma layers [Beckmann and Haidvogel, 1993] : To prevent horizontal pressure gradient errors, well in terrain-following coordinate models [Haney, 1991], realistic topography requires some smoothing. Empirical results have shown that reliable model results are obtained if it does not exceed 0.2. n_filter_deep_topo Number of passes of a Hanning filter to prevent the occurrence of noise and isolated seamounts on deep regions. n_filter_final Number of passes of a Hanning filter at the end of the smoothing process to be sure that no noise is present in the topography. The effects of theta_s, theta_b, hc, and N can be tested using the Matlab script : croco_tools/ Preprocessing_tools/test_vgrid.m Below are some examples of different vertical choices (Courtesy of ROMS-RUTGERS team) : Vtransform=1, 𝜃𝑆= 7.0, 𝜃𝐵= 0.1Vtransform=1, 𝜃𝑆= 7.0, 𝜃𝐵= 1.0 Vtransform=1, 𝜃𝑆= 7.0, 𝜃𝐵= 3.0 Vtransform =1, 𝜃𝑆= 7.0, 𝜃𝐵= 1.0 Vtransform=2, 𝜃𝑆= 7.0, 𝜃𝐵= 1.0 Vtransform=2, 𝜃𝑆= 7.0, 𝜃𝐵= 3.0 16 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 1.3.2 Grid staggering The discretization is based on a staggered grid where not all variables are stored at the same grid points. The free-surface (zeta), density (rho), and active/passive tracers (t) are located at the center of the cell whereas the horizontal velocity (u and v) are located at the edges of the cell. ---- v(i,j+1)---- | | | | u(i,j) rho(i,j) u(i+1,j) | | | | ---- v(i,j) ---- More information about this and the array indices when using MPI parallelisation is given in staggered grids. 1.3.3 Wetting-Drying 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. 1.4 Numerics 1.4.1 Overview CROCO solves the primitive equations in an Earth-centered rotating environment. It is discretized in coastlineand 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 complete time stepping algorithm is described in Shchepetkin and McWilliams [2005]; see also Soufflet et al. [2016]. 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. Combined with the 3rd order time-stepping, a 3rdor 5th-order, upstream-biased horizontal advection scheme (alternatively WENO or TVD for monotonicity preservation) allows the generation of steep gradients, enhancing the effective resolution of the solution for a given grid size [Soufflet et al., 2016,Shchepetkin and McWilliams, 1998, Ménesguen et al., 2018,Borges et al., 2008]. Because of the implicit diffusion in upstream advection schemes, explicit lateral viscosity is not needed in CROCO for damping numerical dispersion errors. For vertical advection, SPLINE or WENO5 schemes are proposed (besides lower-order schemes). For SPLINES (default), an option for an adaptive, Courant-number-dependent implicit scheme is propose that has the advantage to render vertical advection unconditionally stable while maintaining good accuracy in locations with small Courant numbers [Shchepetkin, 2015]. This is also available for tracers. Tracers are treated similarly to momentum. A 3rdor 5th-order upstream-biased horizontal advection scheme is implemented, but in regional configurations the diffusion part of this scheme is rotated along isopycnal surfaces to avoid spurious diapycnal mixing and loss of water masses [Marchesiello and Estrade, 2009,Lemarié et al., 2012]. For regional/coastal applications, a highly accurate pressure gradient scheme [Shchepetkin and McWilliams, 2003] limits the other type of errors (besides spurious diacpynal mixing) frequently associated with terrain-following coordinate models. 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]. It comes with sponge layers for a better transition between interior and boundary solutions (explicit Laplacian diffusion and/or newtonian damping) 1.4. Numerics 17 Croco Documentation, Release 2.1.2 For nearshore problems, where waves becomes the dominant forcing of circulation, a vortex-force formalism for the interaction of surface gravity waves and currents is implemented in CROCO [Uchiyama et al., 2010]. CROCO can be used either as a Boussinesq/hystrostatic model, or a non-hydrostatic/non-Boussinesq model (NBQ; Auclair et al. [2018]). The NBQ solver is relevant in problems from a few tens of meters to LES or DNS resolutions. It comes with shock-capturing advection schemes (WENO5, TVD) and fully 3D turbulent closure schemes (GLS, Smagorinsky). CROCO includes a variety of additional features, e.g., 1D turbulent closure schemes (KPP, GLS) for surface and benthic boundary layers and interior mixing; wetting and drying; sediment and biological models; AGRIF interface for 2-way nesting; OASIS coupler for ocean-waves-atmosphere coupling... 1.4.2 Time Stepping CROCO is discretized in time using a third-order predictor-corrector scheme (referred to as LFAM3) for tracers and baroclinic momentum. 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 tracers, 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 is described in Shchepetkin and McWilliams [2005] and is summarized in this subsection. Fig. 1: Fig: schematic view of the Croco predictor-corrector hydrostatic kernel General structure of the time-stepping: call prestep3D_thread() ! Predictor step for 3D momentum and tracers call step2d_thread() ! Barotropic mode call step3D_uv_thread() ! Corrector step for momentum call step3D_t_thread() ! Corrector step for tracers 1.4.2.1 3D momentum and tracers Predictor-corrector approach : Leapfrog (LF) predictor with 3rd-order Adams-Moulton (AM) interpolation (LFAM3 timestepping). This scheme is used to integrate 3D advection, the pressure gradient term, the continuity equation and the Coriolis term which are all contained in the RHS operator (the time tendencies). For a given quantity 𝑞with 𝑞𝑡= RHS(𝑞)we can write ⎧ ⎪ ⎪ ⎨ ⎪ ⎪ ⎩ 𝑞𝑛+1,⋆ =𝑞𝑛−1+ 2𝛥𝑡 RHS {𝑞𝑛}(LF) 𝑞𝑛+1 2=5 12 𝑞𝑛+1,⋆ +2 3𝑞𝑛−1 12 𝑞𝑛−1(AM3) 𝑞𝑛+1 =𝑞𝑛+𝛥𝑡 RHS {︁𝑞𝑛+1 2}︁(corrector) 18 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 which can be rewritten in a compact way as used in the Croco code : 𝑞𝑛+1 2=(︂1 2−𝛾)︂𝑞𝑛−1+(︂1 2+𝛾)︂𝑞𝑛+ (1 −𝛾)𝛥𝑡 RHS {𝑞𝑛} 𝑞𝑛+1 =𝑞𝑛+𝛥𝑡 RHS {︁𝑞𝑛+1 2}︁ with 𝛾=1 6. Physical parameterizations for vertical mixing, rotated diffusion and viscous/diffusion terms are computed once per time-step using an Euler step. 1.4.2.2 Tracers-momentum coupling The numerical integration of internal waves can be studied using the following subsystem of equations ⎧ ⎪ ⎪ ⎪ ⎨ ⎪ ⎪ ⎪ ⎩ 𝜕𝑧𝑤+𝜕𝑥𝑢= 0 𝜕𝑧𝑝+𝜌𝑔 = 0 𝜕𝑡𝑢+1 𝜌0 𝜕𝑥𝑝= 0 𝜕𝑡𝜌+𝜕𝑧(𝑤𝜌)=0 Predictor step: 𝜕𝑥𝑝𝑛=𝑔 𝜕𝑥(︂∫︁0 𝑧 𝜌𝑛𝑑𝑧)︂→𝑢𝑛+1 2=(︂1 2−𝛾)︂𝑢𝑛−1+(︂1 2+𝛾)︂𝑢𝑛+ (1 −𝛾)∆𝑡 𝜌0 (𝜕𝑥𝑝𝑛) 𝑤𝑛=−∫︁𝑧 −𝐻 𝜕𝑥𝑢𝑛𝑑𝑧′→𝜌𝑛+1 2=(︂1 2−𝛾)︂𝜌𝑛−1+(︂1 2+𝛾)︂𝜌𝑛+ (1 −𝛾)∆𝑡 𝜕𝑧(𝑤𝑛𝜌𝑛) Corrector step: 𝜕𝑥𝑝𝑛+1 2=𝑔 𝜕𝑥(︂∫︁0 𝑧 𝜌𝑛+1 2𝑑𝑧)︂→𝑢𝑛+1 =𝑢𝑛+∆𝑡 𝜌0 (𝜕𝑥𝑝𝑛+1 2) 𝑤𝑛+1 2=−∫︁𝑧 −𝐻 𝜕𝑥{︃3𝑢𝑛+1 2 4+𝑢𝑛+𝑢𝑛+1 8}︃𝑑𝑧′→𝜌𝑛+1 =𝜌𝑛+ ∆𝑡 𝜕𝑧(𝑤𝑛+1 2𝜌𝑛+1 2) 1.4. Numerics 19 Croco Documentation, Release 2.1.2 Fig. 3: Fig: amplification errors (left) and phase errors (right) for linear advection of order 2 to 6. 1.4.3.6.3 Splines reconstruction and Akima 4th-order schemes Similar to a 4th-order compact scheme, the interfacial values for the splines reconstruction scheme are obtained as a solution of a tridiagonal problem Hz𝑘+1𝑞𝑘−1 2+ 2(Hz𝑘+ Hz𝑘+1)𝑞𝑘+1 2+ Hz𝑘𝑞𝑘+3 2= 3(Hz𝑘𝑞𝑘+1 + Hz𝑘+1𝑞𝑘) where 𝑞𝑘values should be understood in a finite-volume sense (i.e. as an average over a control volume). Fig. 4: Fig: amplification errors (left) and phase errors (right) for linear advection of order 5 and 6 and for Splines reconstruction. The AKIMA scheme corresponds to a 4th-order accurate scheme where an harmonic averaging of the slopes is used instead of the algebraic average used for a standard C4 scheme 𝑞𝑘+1 2=𝑞𝑘+1 +𝑞𝑘 2−𝛿𝑞𝑘+1 −𝛿𝑞𝑘 6𝛿𝑞𝑘=⎧ ⎨ ⎩ 2𝛿𝑞𝑘+1 2𝛿𝑞𝑘−1 2 𝛿𝑞𝑘+1 2+𝛿𝑞𝑘−1 2 ,if 𝛿𝑞𝑘+1 2𝛿𝑞𝑘−1 2>0 0,otherwise 26 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 1.4.3.6.4 Adaptively implicit vertical advection Idea: the vertical velocity Ωis split between an explicit and implicit contribution depending on the local Courant number Ω = Ω(e)+Ω(i),Ω(e)=Ω 𝑓(𝛼𝑧 adv, 𝛼max), 𝑓(𝛼𝑧 adv, 𝛼max) = {︂1, 𝛼𝑧 adv ≤𝛼max 𝛼/𝛼max, 𝛼𝑧 adv > 𝛼max •Ω(𝑒)is integrated with an explicit scheme with CFL 𝛼max. •Ω(𝑖)is integrated with an implicit upwind Euler scheme. •𝑓(𝛼𝑧 adv, 𝛼max)is a function responsible for the splitting of Ωbetween an explicit and an implicit part. This approach has the advantage to render vertical advection unconditionally stable and to maintain good accuracy in locations with small Courant numbers. The current implementation is based on the SPLINES scheme for the explicit part. 1.4.3.6.5 Total variation bounded scheme (WENO5) Fig. 5: Fig: different stencils used to evaluate the interfacial value 𝑞𝑘+1 2with WENO5 scheme Nonlinear weighting between 3 evaluations of interfacial values based on 3 different stencils 𝑞𝑘−1 2=𝑤0𝑞(0) 𝑘−1 2 +𝑤1𝑞(1) 𝑘−1 2 +𝑤2𝑞(2) 𝑘−1 2 where the weights are subject to the following constraints: 1. Convexity ∑︀2 𝑗=0 𝑤𝑗= 1. 2. ENO property (Essentially non oscillatory). 3. 5th-order if 𝑞(𝑥)is smooth. The resulting scheme is not monotonicity-preserving but instead it is Total Variation Bounded (TVB). 1.4.3.6.6 Total variation diminishing scheme 1.4.3.6.7 Upwinding of nonlinear terms In CROCO the nonlinear advection terms are formulated as in Lilly (1965) : 𝜕𝑡(Hz𝑢) + 𝜕𝑥((Hz 𝑢)𝑢) + 𝜕𝑦((Hz 𝑣)𝑢) + ... (1.13) 𝜕𝑡(Hz𝑣) + 𝜕𝑥((Hz 𝑢)𝑣) + 𝜕𝑦((Hz 𝑣)𝑣) + ... (1.14) which are discretised with third order accuracy as (︁^ (Hz 𝑢)𝑢)︁𝑖,𝑗 = ( ] Hz 𝑢)C4 𝑖,𝑗 𝑢UP3 𝑖,𝑗 (1.15) (︁^ (Hz 𝑣)𝑢)︁𝑖+1 2,𝑗+1 2 = (  Hz 𝑣)C4 𝑖+1 2,𝑗+1 2𝑢UP3 𝑖+1 2,𝑗+1 2 (1.16) 1.4. Numerics 27 Croco Documentation, Release 2.1.2 where the direction for upwinding is selected considering 𝑢upw 𝑖,𝑗 =𝑢𝑖+1 2,𝑗 +𝑢𝑖−1 2,𝑗, 𝑣upw 𝑖+1 2,𝑗+1 2 = (Hz 𝑣)𝑖,𝑗+1 2+ (Hz 𝑣)𝑖+1,𝑗+1 2 1.4.4 Pressure gradient This section is still under redaction. Meanwhile, please refer to Shchepetkin and McWilliams [2003]. 1.4.5 Equation of State Related CPP options: SALINITY Activate salinity as an active tracer NONLIN_EOS Activate nonlinear equation of state SPLIT_EOS Activate 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 The density is obtained from temperature and salinity (if SALINITY defined) via a choice of linear 𝜌(𝑇)or nonlinear 𝜌(𝑇, 𝑆, 𝑃)equation of state (EOS) described in Shchepetkin and McWilliams [2003]. The nonlinear EOS corresponds to the UNESCO formulation as derived by Jackett and Mcdougall [1995] that computes in situ density as a function of potential temperature, salinity and pressure. To reduce errors of pressure-gradient scheme associated with nonlinearity of compressibility effects, Shchepetkin and McWilliams [2003] introduced a Taylor expansion of this EOS that splits it into an adiabatic and a linearized compressible part (SPLIT_EOS): 𝜌=𝜌0+𝜌1(𝑇, 𝑆) + 𝑞1(𝑇, 𝑆)|𝑧| where 𝜌1(𝑇, 𝑆)is the sea-water density perturbation at the standard pressure of 1 Atm (sea surface), 𝑞1is the compressibility coefficient, and |𝑧|is absolute depth, i.e. the distance from free-surface to the point at which density is computed. This splitting of the EOS into two separate contributions allows for the representation of spatial derivatives of density as the sum of adiabatic derivatives and the compressible part. This makes it straightforward to remove pressure effects so as to reduce pressure gradient errors, compute neutral directions, enforce stable stratification, compute Brunt-Väisäla frequency etc. The Brunt-Väisäla frequency 𝑁(at horizontal 𝜌and vertical 𝑤points) is defined by: 𝑁2=−𝑔 𝜌0 𝜕𝜌𝜃 𝜕𝑧 where 𝜌𝜃is potential density, .i.e., the density that a parcel would acquire if adiabatically brought to depth 𝑧𝑤. 1.4.6 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 28 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 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. 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. 1.4.7 Non-Boussinesq Solver CROCO can be used in a Boussinesq hystrostatic mode, or a non-hydrostatic, non-boussinesq mode (NBQ). The Non-Hydrostatic approach is based on the relaxation of the Boussinesq approximation instead of solving a Poisson system. It replaces the barotropic mode solver by a fully 3D fast mode solver, resolving all waves down to acoustic waves. The barotropic mode is part of the fast mode in this case. Depending on the physical problem, the sound speed can be decreased to the maximum wave velocity one wants to solve. The NH solver can be used in problems from a few tens of meters to LES or DNS resolutions. It comes with monotonicity preserving advection schemes (WENO5, TVD) and fully 3D turbulent closure schemes. Related CPP options (for users): NBQ Activates Non-hysrostatic, non-Boussinesq solver 1.5 Parametrizations 1.5.1 Vertical mixing parametrizations CROCO contains a variety of methods for setting the vertical viscous and diffusive coefficients. The choices range from simply choosing fixed values to the KPP and the generic lengthscale (GLS) turbulence closure schemes. See Large [1998] for a review of surface ocean mixing schemes. Many schemes have a background molecular value which is used when the turbulent processes are assumed to be small (such as in the interior). Related CPP options: ANA_VMIX Analytical definition BVF_MIXING Brunt-Vaisaleafrequency based LMD_MIXING K-profile parametrisation GLS_MIXING Generic lengthscale parametrisation Preselected options: NONE : default is no mixing scheme 1.5.1.1 Analytical definition Related CPP options: ANA_VMIX Analytical definition Preselected options: NONE A profile for mixing coeefficient 𝐾𝑚,𝑠(𝑧)can be set in ana_vmix routine for variables Akv (viscosity) and Akt (diffusivity), which is called at each time step. In this case, background coeeficients read in croco.in can be used. 1.5. Parametrizations 29 Croco Documentation, Release 2.1.2 1.5.1.2 BVF mixing Related CPP options: BVF_MIXING Brunt-Vaisala frequency based Preselected options: NONE It computes diffusivity using a Brunt-Vaisala frequency based vertical mixing scheme. Viscosity is set to its background. In static unstable regime, diffusivity is enhanced. •If 𝑁2(𝑧)<0: 𝐾𝑚,𝑠(𝑧) = 0.1 m2s−1 •If 𝑁2(𝑧)>0: 𝐾𝑚,𝑠(𝑧) = 10−7/√︀𝑁2(𝑧), 𝐾min 𝑚,𝑠 ≤𝐾𝑚,𝑠(𝑧)≤𝐾max 𝑚,𝑠 Default bounds are quite restrictive : 𝐾min 𝑚,𝑠 = 3 ×10−5m2s−1, 𝐾max 𝑚,𝑠 = 4 ×10−4m2s−1 1.5.1.3 K-profile parametrization Large et al. [1994] Related CPP options: KPP-related options : LMD_MIXING K-profile parametrisation LMD_SKPP Activate surface boundary layer KPP mixing LMD_SKPP2005 Activate surface boundary layer KPP mixing (2005 version) LMD_BKPP Activate bottom boundary layer KPP mixing LMD_BKPP2005 Activate bottom boundary layer KPP mixing (2005 version) LMD_RIMIX Activate shear instability interior mixing LMD_CONVEC Activate convection interior mixing LMD_DDMIX Activate double diffusion interior mixing LMD_NONLOCAL Activate nonlocal transport for SKPP LMD_LANGMUIR Activate Langmuir turbulence mixing Preselected options: # ifdef LMD_MIXING # define LMD_SKPP # define LMD_BKPP # define LMD_RIMIX # define LMD_CONVEC # undef LMD_DDMIX # define LMD_NONLOCAL # undef LMD_LANGMUIR # endif 30 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 #if defined LMD_SKPP # define LMD_SKPP2005 #endif #ifdef LMD_BKPP # undef LMD_BKPP2005 #endif Surface boundary layer •LMD_SKPP [Large et al., 1994] –Step 1 : Compute boundary layer depth ℎ𝑏𝑙(𝑧𝑟→𝑧𝑁) Ri𝑏(𝑧) = 𝑔(𝑧𝑟−𝑧) (𝜌(𝑧)−𝜌𝑟)/𝜌0 |u(𝑧)−(uℎ)𝑟|2+𝑉2 𝑡(𝑧),Ri𝑏(−ℎ𝑏𝑙) = Ri𝑐𝑟 –Step 2 : In the stable case math::(B_f > 0) : h_{bl} = min( h_{bl}, h_{ek}, h_{mo} ) ℎ𝑒𝑘 = 0.7𝑢⋆/𝑓, ℎ𝑚𝑜 =𝑢3 ⋆/(𝜅𝐵𝑓). –Step 3 : Compute turbulent viscosity and diffusivity 𝐾𝑚,𝑠(𝑧) = 𝑤𝑚,𝑠 ℎ𝑏𝑙 𝐺(𝑧/ℎ𝑏𝑙), 𝑤𝑚,𝑠 =𝜅 𝑢⋆𝜓𝑚,𝑠(𝑧𝐵𝑓/𝑢3 ⋆) Choice of the critical Richardson number Ri𝑐𝑟 :Ri𝑐𝑟 ∈[0.15,0.45] •LMD_SKPP2005 [Shchepetkin and McWilliams, 2005] –Criteria for ℎ𝑏𝑙 : integral layer where production of turbulence by shear balances dissipation by the stratification Cr(𝑧) = ∫︁𝜁 𝑧𝒦(𝑧′){︂|𝜕𝑧′uℎ|2−𝑁2 Ri𝑐𝑟 −𝐶𝐸𝑘 𝑓2}︂𝑑𝑧′+𝑉2 𝑡(𝑧) (𝜁−𝑧),Cr(−ℎ𝑏𝑙)=0 –Consistent with the original KPP Cr(−ℎ𝑏𝑙) = 0 ⇒(𝜁−𝑧)∫︀𝜁 𝑧𝒦(𝑧′)𝑁2(𝑧′)𝑑𝑧′ (𝜁−𝑧)∫︀𝜁 𝑧𝒦(𝑧′){︁|𝜕𝑧uℎ|2−𝐶𝐸𝑘 𝑓2}︁𝑑𝑧′+𝑉2 𝑡(𝑧) = Ri𝑐𝑟 Advantages : -> consistent with Ekman problem -> tends to give deeper boundary layers : (𝜁−𝑧)∫︀𝜁 𝑧|𝜕𝑧′uℎ|2𝑑𝑧′≥ |uℎ(𝑧)−uℎ(𝜁)|2. •cpp key LMD_LANGMUIR [McWilliams and Sullivan, 2000] Following the work of McWilliams and Sullivan [2000], we introduce in KPP an enhancement factor E to the turbulent velocity scale as a function of the turbulent Langmuir number 𝐿𝑎𝑡=√︀𝑢⋆/𝑢𝑆𝑡𝑜𝑘𝑒𝑠, but this function is taken as in Van Roekel et al. [2012] which gives good results in Li et al. [2016] – still assuming that Stokes drift is aligned with the surface wind stress: 𝑤𝑚,𝑠 =𝜅 𝑢⋆ 𝜑𝑚,𝑠 𝐸, 𝐸 =√︁1+0.104𝐿𝑎−2 𝑡+ 0.034𝐿𝑎−4 𝑡 Interior scheme 𝐾𝑚,𝑠(𝑧) = 𝐾sh 𝑚,𝑠(𝑧) + 𝐾iw 𝑚,𝑠(𝑧) + 𝐾dd 𝑚,𝑠(𝑧) •cpp key LMD_RIMIX, RI_(H-V)SMOOTH [Large et al., 1994] Ri𝑔=𝑁2/[︀(𝜕𝑧𝑢)2+ (𝜕𝑧𝑣)2]︀ 𝐾sh 𝑚,𝑠(𝑧) = ⎧ ⎪ ⎨ ⎪ ⎩ 𝐾0,𝑐 Ri𝑔<0←[LMD_CONVEC] 𝐾0[︁1−(Ri𝑔 Ri0)3]︁0<Ri𝑔<Ri0 0 Ri0<Ri𝑔 𝐾0= 5 ×10−3m2s−1,Ri0= 0.7 1.5. Parametrizations 31 Croco Documentation, Release 2.1.2 •cpp key LMD_NUW_GARGETT (Gargett & Holloway) 𝐾iw 𝑚(𝑧) = 10−6 √︀max(𝑁2(𝑧),10−7), 𝐾iw 𝑠(𝑧) = 10−7 √︀max(𝑁2(𝑧),10−7) •cpp key LMD_DDMIX (cf Large et al. [1994], eqns (31)) Bottom boundary layer •cpp key LMD_BOTEK : Bottom Ekman layer ℎEk = min {︂0.3𝑢⋆,𝑏 |𝑓|, ℎ}︂ 𝜎𝑘+1 2= (𝑧𝑘+1 2−ℎ)/ℎEk 𝐾Ek 𝑘+1 2= max {4𝜅 𝑢⋆,𝑏 ℎEk 𝜎(1 −𝜎), 𝐾min} AKv𝑘+1 2= AKv𝑘+1 2+𝐾Ek 𝑘+1 2 AKt𝑘+1 2= AKt𝑘+1 2+𝐾Ek 𝑘+1 2 •cpp key LMD_BKPP (Bottom KPP 1994) Same rationale than surface KPP but this time we search for the critical value Ricr (≈0.3) starting from the bottom ℎbbl = min (︂ℎbbl,0.7𝑢⋆,𝑏 |𝑓|)︂𝐾𝑚,𝑠(𝑧) = 𝜅 𝑢⋆,𝑏 ℎ𝑏𝑏𝑙 𝐺(𝜎), 𝜎 =(𝑧−ℎ) ℎ𝑏𝑏𝑙 1.5.1.4 Generic length scale GLS-related options : GLS_MIXING Activate Generic Length Scale scheme, default is k-epsilon (see below) GLS_KOMEGA Activate K-OMEGA (OMEGA=frequency of TKE dissipation) originating from Kolmogorov [1942] GLS_KEPSILON Activate K-EPSILON (EPSILON=TKE dissipation) as in Jones and Launder [1972] GLS_GEN Activate generic model of Umlauf and Burchard [2003] CANUTO_A Option for CANUTO A stability function (default, see below) GibLau_78 Option for Gibson and Launder [1978] stability function MelYam_82 Option for Mellor and Yamada [1982] stability function KanCla_94 Option for Kantha and Clayson [1994] stability function Luyten_96 Option for Luyten [1996] stability function CANUTO_B Option for CANUTO B stability function Cheng_02 Option for Cheng et al. [2002] stability function Preselected options for GLS: #ifdef GLS_MIXING # if defined GLS_KOMEGA # elif defined GLS_KEPSILON # elif defined GLS_GEN # else # define GLS_KEPSILON # endif # if defined CANUTO_A # elif defined GibLau_78 # elif defined MelYam_82 # elif defined KanCla_94 (continues on next page) 32 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 (continued from previous page) # elif defined Luyten_96 # elif defined CANUTO_B # elif defined Cheng_02 # else # define CANUTO_A # endif #endif The objective of this section is to describe the current implementation of a Generic Length Scale (GLS) turbulence scheme in CROCO that computes the turbulent viscosity 𝐾𝑚and diffusivity 𝐾𝑠. First of all, as usually done in most implementations, the assumption of an horizontally homogeneous flow is made. Following Umlauf and Burchard [2003], the equations satisfied by the two prognostic variables 𝑘(the kinetic energy) and 𝜓(the generic length scale) are 𝜕𝑡𝑘=𝜕𝑧(𝐾𝑘𝜕𝑧𝑘) + 𝑃+𝐵−𝜀, 𝐾𝑘=𝐾𝑚/Sc𝑘 𝜕𝑡𝜓=𝜕𝑧(𝐾𝜓𝜕𝑧𝜓) + 𝜓𝑘−1(︀𝛽1𝑃+𝛽± 3𝐵−𝛽2𝜀)︀, 𝐾𝜓=𝐾𝑚/Sc𝜓 where the 𝛽𝑗(j=1,3) are constants to be defined, 𝑃represents the TKE production by vertical shear 𝑃= 𝐾𝑚[︀(𝜕𝑧𝑢)2+ (𝜕𝑧𝑣)2]︀and 𝐵the TKE destruction by stratification 𝐵=−𝐾𝑠𝑁2(with 𝑁2the local Brunt-Vaisala frequency). The dissipation rate 𝜀is related to the generic length scale 𝜓following 𝜀= (𝑐0 𝜇)3+𝑝/𝑛𝑘3/2+𝑚/𝑛𝜓−1/𝑛, 𝜓 = (𝑐0 𝜇)𝑝𝑘𝑚𝑙𝑛, 𝑙 = (𝑐0 𝜇)3𝑘3/2𝜀−1 with 𝑙a mixing length and 𝑐0 𝜇a constant (whose value is between 0.526 and 0.555) to be defined. Depending on the parameter values for the triplet (𝑚, 𝑛, 𝑝)the GLS scheme will either correspond to a 𝑘−𝜀, a 𝑘−𝜔or the so-called generic [Umlauf and Burchard, 2003] turbulence scheme (to simplify the code and because this scheme do not generally outperform other schemes, the possibility to use the so-called 𝑘-𝑘𝑙 scheme is not implemented in Croco). Since the equations for 𝑒and 𝜓bear lots of similarities, to avoid excessive code duplication, a unique equation is solved for a quantity 𝒯𝑖encompassing 𝑘(when 𝑖=𝑖tke) and 𝜓(when 𝑖=𝑖gls,𝑖gls =𝑖tke + 1) such that 𝜕𝑡𝒯𝑖=𝜕𝑧(𝐾𝒯𝑖𝜕𝑧𝒯𝑖)+(𝑐1 𝑖𝑃+𝑐3,± 𝑖𝐵−𝑐2 𝑖𝜀), 𝐾𝒯𝑖=𝐾𝑚/Sc𝒯𝑖 where Sc𝒯𝑖tke = Sc𝑘,Sc𝒯𝑖gls = Sc𝜓 and 𝑐1 𝑖= (𝑖gls −𝑖)+(𝑖−𝑖tke)𝛽1𝑒−1𝜓 𝑐2 𝑖= (𝑖gls −𝑖)+(𝑖−𝑖tke)𝛽2𝑒−1𝜓 𝑐3,± 𝑖= (𝑖gls −𝑖)+(𝑖−𝑖tke)𝛽± 3𝑒−1𝜓 In practice this explains why in the code the two prognostic quantities 𝑘and 𝜓are stored in a single array trb(i,j,k,ntime,ngls) avec ngls = 2,𝑖tke = 1 and 𝑖gls = 2. Once the quantities 𝑘and 𝜓(hence 𝜀) are known, the turbulent viscosity/diffusivity are given by 𝐾𝑚=𝑐𝜇(︂𝑘2 𝜀)︂=𝑐𝜇 (𝑐0 𝜇)3(𝑙√𝑘), 𝐾𝑠=𝑐′ 𝜇(︂𝑘2 𝜀)︂=𝑐′ 𝜇 (𝑐0 𝜇)3(𝑙√𝑘). where 𝑐𝜇and 𝑐′ 𝜇are determined through so-called stability functions (see below). Choice of parameter values and stability functions A particular GLS occurence is defined by the following parameters : •The exponents (𝑚, 𝑛, 𝑝)in the definition of 𝜀 •The Schmidt numbers Sc𝑘and Sc𝜓 1.5. Parametrizations 33 Croco Documentation, Release 2.1.2 •The coefficients 𝛽𝑗(j=1,3) •The constant 𝑐0 𝜇 •The stability functions which are generally function of 𝛼𝑀=(︂𝑘 𝜀)︂2[︀(𝜕𝑧𝑢)2+ (𝜕𝑧𝑣)2]︀, 𝛼𝑁=(︂𝑘 𝜀)︂2 𝑁2 Where (𝑚, 𝑛, 𝑝),Sc𝑘,Sc𝜓,𝛽𝑗(j=1,3) are tied to a particular choice of GLS scheme (see table below) while 𝑐0 𝜇,𝑐𝜇 and 𝑐′ 𝜇are tied to a particular choice of stability function. The formulation of numerous stability functions can be reconciled when written using the generic form 𝑐𝜇=𝑛0+𝑛1𝛼𝑁+𝑛2𝛼𝑀 𝑑0+𝑑1𝛼𝑁+𝑑2𝛼𝑀+𝑑3𝛼𝑁𝛼𝑀+𝑑4𝛼2 𝑁+𝑑5𝛼2 𝑀 𝑐′ 𝜇=𝑛′ 0+𝑛′ 1𝛼𝑁+𝑛′ 2𝛼𝑀 𝑑0+𝑑1𝛼𝑁+𝑑2𝛼𝑀+𝑑3𝛼𝑁𝛼𝑀+𝑑4𝛼2 𝑁+𝑑5𝛼2 𝑀 where a given choice of stability function will define the parameter values for 𝑛𝑖,𝑑𝑗, and 𝑛′ 𝑘. In Croco, 7 options are available, these are referred to CANUTO-A, CANUTO-B, Gibson and Launder [1978], Mellor and Yamada [1982], Kantha and Clayson [1994], Luyten [1996], Cheng et al. [2002]. Table 1: Table: parameter values corresponding to each particular GLS model GLS model 𝑚 𝑛 𝑝 𝛽1𝛽2𝛽− 3𝛽+ 3Sc𝑒Sc𝜓 𝑘−𝜔0.5 -1 -1 0.555 0.833 -0.6 1 0.5 0.5 𝑘−𝜀1.5 -1 3 1.44 1.92 -0.4 1 1 0.7692 Gen 1 -0.67 0 1 1.22 0.05 1 1.25 0.9345 The quantities 𝛼𝑁and 𝛼𝑀in the formulation of 𝑐𝜇and 𝑐′ 𝜇must satisfy some constraints to guarantee the regularity of numerical solutions. In CROCO, the following steps are done: 1. Apply the Galperin et al. [1988] limitation i.e. 𝑙≤𝑙lim =𝛽galp√︀2𝑘/𝑁2on 𝜓with 𝛽galp = 0.53. The first step is to use this mixing length 𝑙lim to compute 𝜓min = (𝑐0 𝜇)𝑝𝑘𝑚(𝑙lim)𝑛and to correct 𝜓to satisfy the constraint 𝜓= max (𝜓, 𝜓min) here the max function is used since the exponent 𝑛is negative whatever the GLS scheme. 2. Compute the dissipation rate 𝜀= (𝑐0 𝜇)3+𝑝/𝑛𝑘3/2+𝑚/𝑛𝜓−1/𝑛 and correct it 𝜀= max (𝜀, 𝜀min), 𝜀min = 10−12 m2s−3 3. Compute 𝛼𝑁and 𝛼𝑀, and apply “stability and realisability” constraints following Umlauf and Burchard [2003] (their Sec. 4). A first constraint applies on 𝛼𝑁to ensure that −𝜕𝛼𝑁(𝑐′ 𝜇/𝛼𝑁)>0to prevent the occurence of oscillations in 𝑐′ 𝜇. This translates into the following limiter 𝛼min 𝑁=−(𝑑1+𝑛′ 0) + √︀(𝑑1+𝑛′ 0)2−4𝑑0(𝑑4+𝑛′ 1) 2(𝑑4+𝑛′ 1), 𝛼𝑁= min (︀max(0.73𝛼min 𝑁),1010)︀ where the coefficient 0.73 is used to ensure the so-called realisability and has been empirically computed thanks to Table 3 in Umlauf and Burchard [2003] in order to satisfy their constraint (48). Then an upper limit is applied on 𝛼𝑀to ensure that 𝜕𝛼𝑀(𝑐𝜇√𝛼𝑀)≥0which is also a prerequisite for stability reasons 𝛼max 𝑀=𝑑0𝑛0+ (𝑑0𝑛1+𝑑1𝑛0)𝛼𝑁+ (𝑑1𝑛1+𝑑4𝑛0)𝛼2 𝑁+𝑑4𝑛1𝛼3 𝑁 𝑑2𝑛0+ (𝑑2𝑛1+𝑑3𝑛0)𝛼𝑁+ (𝑑3𝑛1)𝛼2 𝑁 , 𝛼𝑀= min (𝛼𝑀, 𝛼max 𝑀) Once those quantities are computed, stability functions are evaluated as well as the turbulent viscosity/diffusivity. 34 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 Surface and bottom boundary conditions In current version of Croco, both 𝑘and 𝜓are formulated with Neumann boundary conditions at the top and at the bottom. However the nature of those boundary conditions also requires the determination of bottom and surface values for 𝑘and 𝜓. •For turbulent kinetic energy, the “diagnostic” surface and bottom values are given by 𝑘sfc = (𝑢𝑠 ⋆/𝑐0 𝜇)2, 𝑘bot = (𝑢𝑏 ⋆/𝑐0 𝜇)2 and simple homogeneous Neumann boundary conditions are applied 𝐾𝑘𝜕𝑧𝑘|sfc = 0, 𝐾𝑘𝜕𝑧𝑘|bot = 0 In practice, due to the placement of 𝑘and 𝜓on the computational grid, the Neumann boundary condition is not applied strictly at the surface (resp. at the bottom) but at 𝑧=𝑧𝑁(resp. 𝑧=𝑧1) whereas the surface (resp. bottom) is located at 𝑧=𝑧𝑁+1/2(resp. 𝑧=𝑧1/2) with 𝑁the number of vertical levels (i.e. the number of cells in the vertical). •For the generic length scale, a roughness is defined as 𝑧0,𝑠 = max {︂10−2m,𝐶ch 𝑔(𝑢𝑠 ⋆)2}︂, 𝐶ch = 1400 at the surface and 𝑧0,𝑏 = max {︀10−4m,Zob}︀ at the bottom with Zob a user defined roughness length (usually Zob = 10−2m). Again, the boundary conditions are applied at the center of the shallowest and deepest grid cells and not at their interfaces which means that the relevant length scales are 𝐿sfc =𝜅(︂𝛥𝑧𝑁 2+𝑧0,𝑠)︂, 𝐿bot =𝜅(︂𝛥𝑧1 2+𝑧0,𝑏)︂ with 𝜅the von Karman constant. Moreover TKE values are interpolated at 𝑧=𝑧𝑁and 𝑧=𝑧1 𝑘sfc =1 2(︀𝑘sfc +𝑘N−1/2)︀,𝑘bot =1 2(︀𝑘bot +𝑘3/2)︀ where 𝑘sfc and 𝑘bot are the diagnostic values given above. The “diagnostic” surface and bottom values for 𝜓are thus given by 𝜓sfc = (𝑐0 𝜇)𝑝(𝐿sfc)𝑛(𝑘sfc)𝑚, 𝜓bot = (𝑐0 𝜇)𝑝(𝐿bot)𝑛(𝑘bot)𝑚 Then the surface and bottom flux are defined as ℱsfc 𝜓=𝐾𝜓𝜕𝑧𝜓|sfc =−𝑛(𝑐0 𝜇)𝑝+1 𝜅 Sc𝜓 (𝑘sfc)𝑚+1/2(𝐿sfc)𝑛 ℱbot 𝜓=𝐾𝜓𝜕𝑧𝜓|bot =−𝑛(𝑐0 𝜇)𝑝+1 𝜅 Sc𝜓 (𝑘bot)𝑚+1/2(𝐿bot)𝑛 which correspond to the Neumann boundary conditions applied in the code. 1.5.2 Horizontal diffusion 1.5.2.1 Lateral Momentum Mixing Related CPP options: 1.5. Parametrizations 35 Croco Documentation, Release 2.1.2 Istr,Iend are the limits of the sub-domains (without overlap). They are calculated at the beginning of the subroutine by including Computation of Istr,Iend and use of working arrays. 1.6.4 Halo layer exchanges CROCO makes use 2 or 3 ghost cells depending on the chosen numerical schemes. In the example above (2 ghosts cells), for correct exchanges, after computation: •𝜂has to be valid on (1:Iend) •𝑢has to be valid on (1:Iend) except on the left domain (2:Iend) IstrU is the lower limit of validity of the Upoints. Computation of auxiliary indexes is done by including a file: subroutine step2D_FB_tile (Istr, Iend, Jstr, Jend, zeta_new, ... ... #include "compute_auxiliary_bounds.h" ! Compute IstrU, IstrR 1.6.5 Dealing with outputs By default, with MPI activated input and output files are treated in a pseudo-sequential way, and one NetCDFfile corresponds to the whole domain. This has drawbacks when using a large number of computational cores, since each core is writing its part of the domain sequentially, the time dedicated to outputs increase with the number of cores. Three alternatives are implemented within CROCO. Splited files (#define PARALLEL_FILES) 42 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 In this case, each core is writing its part only of the domain in separated files (one per MPI domain). This writing is performed concurrently. One other advantage is to avoid the creation of huge output files. The domain related output files can be recombined using ncjoin utility (in fortran) compiled in the same time than CROCO. Note that in this case, input files have to be splited as well, using partit utility. Parallel NetCDF(#define NC4PAR) This option requires NetcDF4 verion, installed with parallel capabilities. All cores are writing concurrently but in the same time. IO server (#define XIOS) XIOS is an external IO server interfaced with CROCO. Informations about use and installation can be found there https://forge.ipsl.jussieu.fr/ioserver. In this case, output variables are defined in .xml files. See also the Diagnostics chapter. 1.6.6 Run with GPU •OpenACC directive-based approach is the most appropriate method to develop the GPU version of croco. Low development cost, a single program repository can be shared by CPU and GPU. Similar to OpenMP style which is familiar to many users. An openacc compiler compatible is necessary : only nvfortran, and old pgi have been tested. •To run croco on GPUs, the key OPENACC as to be set in the cppdefs.h file. With MPI, all the mpi process are dispatch over the GPUs. Effiency is better with one or two mpi by GPU card. #define OPENACC 1.6.6.1 General implementation Implementation is done by inserting basic OpenACC directives : •Kernels or parallel directives : Basically, inserted into the outermost of nested loops •Loop independent/seq directives : Inserted according to the loop algorithms No quantitative configurations for GPU threads are specified. Gang or vector clauses are not applied, leaving it to the compiler’s decision. Exemple from pre_step3.F !$acc kernels if(compute_on_device) default(present) !$acc end kernels !$acc parallel loop if(compute_on_device) default(present) 1.6.6.2 Data directives Remove redundant data transfer between CPU and GPU. There is one main copy data to device, on copy-back before output. The file copy_to_devices.h do this job. Python script common2device.py generate the file copy_to_devices.h and have to be rerun when *.h files are modified. 1.6.6.3 3D loop tunning with preprocessing by compilation For GPU efficiency some 3D loops have to be reordered or variable expand. This is done by en additional preprocesing (in python). And it’s added in jobcomp compilation procedure. Two kind of transformations, first one transforms 2D variables internal to loops in 3D variables. Second restructures loop with z dependencies. Example 1: 1.6. Parallelisation 43 Croco Documentation, Release 2.1.2 # if defined OPENACC DOEXTEND(k,1,N,FX,FE,WORK) # endif ... FX(i,j) will become FX_3D(i,j,k) (FE_3D, WORK_3D ) # if defined OPENACC ENDDOEXTEND # endif Example 2: DOLOOP2D(Istr,Iend,Jstr,Jend) do k=1,N do i=Istr,Iend DC(i,k)=1./Hz_half(i,j,k) enddo enddo ... ENDDOLOOP2D Become in CPU version: !$acc kernels if(compute_on_device) default(present) !$acc loop private( DC, FC, CF) do j=Jstr,Jend do k=1,N do i=Istr,Iend DC(i,k)=1.D0/Hz_half(i,j,k) enddo enddo do i=Istr,Iend DC(i,0)=cdt*pn(i,j)*pm(i,j) enddo ... enddo And become in GPU version : !$acc kernels if(compute_on_device) default(present) DO j=Jstr,Jend !$acc loop private(DC1D,CF1D,FC1D) vector DO i=Istr,Iend do k=1,N DC1D(k)=1.D0/Hz_half(i,j,k) enddo DC1D(0)=cdt*pn(i,j)*pm(i,j) ENDDO ... ENDDO 1.7 Atmospheric Surface Boundary Layer There are two ways to force CROCO with atmospheric fields. The first is the use of classical bulk parameterization (BULK_FLUX cpp key). Four have been updated and implemented in CROCO (COARE3.0, ECUMEV0, ECUMEV6 and WASP). The second is the use of a simplified atmospheric model (ABL1D cpp key, Lemarié et al. [2021]) on top of the bulk parameterization. 44 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 òNote •ABL1D forcing strategy is still under evaluation. •In both cases, the use of a bulk parameterization (BULK_FLUX) is mandatory. Below you’ll find the CPP keys for these two forcing capabilities and their descriptions : BULK_FLUX’s related CPP options: CPP options Description BULK_FLUX Activate bulk formulation for surface turbulent fluxes (by default, COARE3.0 parametrization is used) BULK_ECUMEV0 Use ECUMEv0 bulk formulation instead of COARE3.0 formulation BULK_ECUMEV6 Use ECUMEv6 bulk formulation instead of COARE3.0 formulation BULK_WASP Use WASP bulk formulation instead of COARE3.0 formulation BULK_GUSTINESS Add in gustiness effect on the surface wind module. Can be used for both bulk parametrizations. BULK_LW Add in long-wave radiation feedback from model SST SFLUX_CFB Activate current feedback on ... [Renault et al., 2020] CFB_STRESS ... surface stress, using the Stress-Correction Approach (by default when SFLUX_CFB is defined) CFB_WIND_TRA ... surface wind for turbulent heat fluxes computation, using the Wind-Correction Approach (by default when SFLUX_CFB is defined) SST_SKIN Activate skin sst computation [Zeng and Beljaars, 2005] ONLINE Read native files and perform online interpolation on CROCO grid (default cubic interpolation) QCORRECTION Activate heat flux correction around model SST (if BULK_FLUX is undefined) SFLX_CORR Activate freshwater flux correction around model SSS (if BULK_FLUX is undefined) ANA_DIURNAL_SW Activate analytical diurnal modulation of short wave radiations (only appropriate if there is no diurnal cycle in data) RAIN_FLUX Add E-P flux into the mass budget (added in omega) By default COARE3.0 parametrization is used with GUSTINESS effects. To change bulk parametrization, one has to define one of the following cpp keys (not additional) : •define BULK_ECUMEV0 to use ECUME_v0 parametrization 1.7. Atmospheric Surface Boundary Layer 45 Croco Documentation, Release 2.1.2 •define BULK_ECUMEV6 to use ECUME_v6 parametrization •define BULK_WASP to use WASP parametrization .Warning It is possible to add GUSTINESS effects for all parametrizations by defining BULK_GUSTINESS cpp key ABL1D’s related CPP options: CPP options Description ABL1D Activate ABL1d model and BULK_FLUX parametrization ANA_ABL_LSDATA Impose large scale forcing data for analytical simulations ANA_ABL_VGRID Compute vertical grid for ABL1d online for analytical simulations STRESS_AT_RHO_POINTS Compute stress at rho points ABL_NUDGING Active nudging for ... ABL_NUDGING_DYN ... dynamic (two components of the horizontal wind speed) ABL_NUDGING_TRA ... tracers (air temperature and specific humidity) ABL_DYN_RESTORE_EQ Active Equator dynamic restoration ONLINE related CPP options: ONLINE option is an alternative to pre-processing of surface forcing data for both forcing strategy (ABL1D / BULK_FLUX), that can be useful for long-term and/or high resolution simulations, especially if handling multiple configurations. ONLINE option calls for CUBIC_INTERP in set_global_definitions.h. CPP options Description ECMWF Use ECMWF atm fluxes AROME Use METEO FRANCE fluxes READ_PATM Read atmospheric pressure instead of using default reference pressure and take into account the atmospherical pressure gradient in the equations OBC_PATM In the case of READ_PATM, inverse barometer effect to the open boundaries if the atmospherical pressure is read in the meteo file. ONLINE variables description The following table describe what is expected in online forcing file. 46 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 variables option given cppkey Long name units AROME ERA_ECMWF Temperature above ground Kelvin t2m T2M specific humidity Kg/Kg rh Q precipitation rate Kg.m-2.s-1 rain TP Upward Net short wave W.m-2 swhf SSR Downward long wave W.m-2 lwhf STRD U component of wind m/s u10m U10M V component of wind m/s v10m V10M Pressure at sea level Pa pmer msl time vector days time time .Warning For AROME time units must be in days since 1900-01-01 òNote Long wave flux is either downward or net given your inputs in atmospherical modeles : •First case : You have a downward flux only. So you have to add BULK_LW option to compute the net flux. •Second case : You already have a net long flux. You must remove the BULK_LW to not take twice the feedback into account. Preselected options (cppdefs.h): # undef BULK_FLUX # ifdef BULK_FLUX # undef BULK_ECUMEV0 # undef BULK_ECUMEV6 # undef BULK_WASP # define BULK_GUSTINESS # define BULK_LW # undef SST_SKIN # undef ANA_DIURNAL_SW # undef ONLINE # ifdef ONLINE # undef AROME # undef ERA_ECMWF # endif # undef READ_PATM # ifdef READ_PATM # define OBC_PATM # endif # else # define QCORRECTION # define SFLX_CORR # undef SFLX_CORR_COEF # define ANA_DIURNAL_SW # endif # undef SFLUX_CFB # undef SEA_ICE_NOFLUX 1.7. Atmospheric Surface Boundary Layer 47 Croco Documentation, Release 2.1.2 Preselected options (cppdefs_dev.h): #ifdef BULK_FLUX # ifdef ONLINE # define CUBIC_INTERP # endif # ifdef BULK_ECUMEV0 # define BULK_GUSTINESS # elif defined BULK_ECUMEV6 # define BULK_GUSTINESS # elif defined BULK_WASP # define BULK_GUSTINESS # endif #endif #ifdef SFLUX_CFB # ifdef BULK_FLUX # define CFB_STRESS # define CFB_WIND_TRA # else # undef CFB_STRESS # undef CFB_WIND_TRA # endif #endif 1.8 Open boundaries conditions If a lateral boundary faces the open ocean, robust open boundary conditions (OBCs) are needed [Marchesiello et al., 2001]. Forcing of tracer and baroclinic flow is applied via an adaptive radiation condition, which helps perturbations to leave the domain with only a small effect on the interior solution. The same method can be applied to the depth-averaged flow, but (for tidal forcing in particular) we generally prefer the incoming characteristic of the shallow water system as in Flather-type conditions [Marchesiello et al., 2001,Blayo and Debreu, 2005]. This allows long-wave data to be forced in, while those generated inside the domain can leave it, which also guarantees the quasi-conservation of mass and energy across the open boundary. A Sponge layer is added near the open boundaries to limit small-scale effects and ease the transition between the interior solution and the boundary data. The boundary data can be applied only at the boundary (see BRY strategy below) or in a nudging layer (CLIMATOLOGY strategy). This set of OBCs are given as default if no other choice is made. They have performed well in most applications, from the deep ocean to the coastal areas. For details, refer to Marchesiello et al. [2001] and Blayo and Debreu [2005]. 1.8.1 OBC Related CPP options: OBC_EAST Open eastern boundary OBC_WEST Open western boundary OBC_SOUTH Open southern boundary OBC_NORTH Open northern boundary Related CPP options: 48 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 OBC_M2SPECIFIED Activate specified OBCs for barotropic velocities OBC_M2CHARACT Activate OBCs from characteristic methods for barotropic velocities (default) OBC_M2ORLANSKI Activate radiative OBCs for barotropic velocities OBC_VOLCONS Enforce mass conservation at open boundaries (with OBC_M2ORLANSKI) OBC_M3SPECIFIED Activate specified OBCs for baroclinic velocities OBC_M3ORLANSKI Activate radiative OBCs for baroclinic velocities (default) OBC_TSPECIFIED Activate specified OBCs for tracers OBC_TORLANSKI Activate radiative OBCs for tracers (default) OBC_TUPWIND Activate upwind OBCs for tracers 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. However, OBC_M2CHARACT is near as good and also provides the best conditions for tidal forcing. It is therefore set as default in cppdefs_dev.h. Preselected options (in cppdefs_dev.h but set your own choice in cppdefs.h if needed): # undef OBC_M2SPECIFIED # define OBC_M2CHARACT # undef OBC_M2ORLANSKI # ifdef OBC_M2ORLANSKI # define OBC_VOLCONS # endif # define OBC_M3ORLANSKI # define OBC_TORLANSKI # undef OBC_M3SPECIFIED # undef OBC_TSPECIFIED 1.8.2 Sponge Layer SPONGE is preselected in cppdefs.h and calls for SPONGE_GRID in cppdefs_dev.h. SPONGE_GRID selects the sponge layer extension (10 points with cosine shape function) and viscosity and diffusivity values according to the horizontal resolution (limited by the CFL stability conditions). Related CPP options: SPONGE Activate areas of enhanced viscosity and diffusivity near lateral open boundaries. SPONGE_GRID Automatic setting of the sponge width and value SPONGE_DIF2 Sponge on tracers (default) SPONGE_VIS2 Sponge on momentum (default) SPONGE_SED Sponge on sediment (default) 1.8.3 Nudging layers 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 croco.in Related CPP options: ZNUDGING Activate nudging layer for sea level M2NUDGING Activate nudging layer for barotropic velocities M3NUDGING Activate nudging layer for baroclinic velocities TNUDGING Activate nudging layer for tracers ROBUST_DIAG Activate nudging over the whole domain 1.8. Open boundaries conditions 49 Croco Documentation, Release 2.1.2 1.8.4 Lateral forcing 1.8.4.1 CLIMATOLOGY strategy Related CPP options: CLIMATOLOGY Activate processing of 2D/3D data (climatological or simulation/reanalysis) used as forcing at the open boundary points + nudging layers ZCLIMATOLOGY Activate processing of sea level M2CLIMATOLOGY Activate processing of barotropic velocities M3CLIMATOLOGY Activate processing of baroclinic velocities TCLIMATOLOGY Activate processing of tracers 1.8.4.2 BRY strategy 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. Related CPP options: FRC_BRY Activate processing of 1D/2D data used as forcing at open boundary points strictly Z_FRC_BRY Activate open boundary forcing for sea level M2_FRC_BRY Activate open boundary forcing for barotropic velocities M3_FRC_BRY Activate open boundary forcing for baroclinic velocities T_FRC_BRY Activate open boundary forcing for tracers Preselected options (cppdefs.h): # define CLIMATOLOGY # ifdef CLIMATOLOGY # define ZCLIMATOLOGY # define M2CLIMATOLOGY # define M3CLIMATOLOGY # define TCLIMATOLOGY # define ZNUDGING # define M2NUDGING # define M3NUDGING # define TNUDGING # undef ROBUST_DIAG # endif # undef FRC_BRY # ifdef FRC_BRY # define Z_FRC_BRY # define M2_FRC_BRY # define M3_FRC_BRY # define T_FRC_BRY # endif 50 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 1.9 Rivers Related CPP options: PSOURCE Activate point sources (rivers) ANA_PSOURCE use analytical vertical profiles for point sources (set in set_global_definitions.h) PSOURCE_NCFILE Read variable river transports in netcdf file PSOURCE_NCFILE_TS Read variable river concentration in netcdf file PSOURCE_MASS Apply point source as volume vertical influx at rho point instead of a flux through u,v interfaces ANA_PSOURCE gives the vertical distribution of point source outflow. The default shape is an exponential vertical distribution. The vertical shape can be customized in subroutine ana_psource in analytical.F An example of runoff file with PSOURCE_NCFILE is given below netcdf croco_runoff { dimensions: qbar_time =28193 ; n_qbar =9; runoffname_StrLen =30 ; two =2; temp_src_time =10690 ; salt_src_time =10690 ; variables: double qbar_time(qbar_time) ; qbar_time:long_name ="runoff time" ; qbar_time:units ="days" ; qbar_time:cycle_length =0. ; qbar_time:long_units ="days since 1900-01-01" ; char runoff_name(n_qbar, runoffname_StrLen) ; runoff_name:long_name ="runoff name" ; double runoff_position(n_qbar, two) ; runoff_position:long_name ="position of the runoff (by line) in the CROCO grid" ; double runoff_direction(n_qbar, two) ; runoff_direction:long_name ="direction/sense of the runoff (by line) in the CROCO␣ ˓→grid" ; double Qbar(n_qbar, qbar_time) ; Qbar:long_name ="runoff discharge" ; Qbar:units ="m3.s-1" ; double temp_src_time(temp_src_time) ; temp_src_time:cycle_length =0. ; temp_src_time:long_units ="days since 1900-01-01" ; double salt_src_time(salt_src_time) ; salt_src_time:cycle_length =0. ; salt_src_time:long_units ="days since 1900-01-01" ; double temp_src(n_qbar, temp_src_time) ; temp_src:long_name ="runoff temperature" ; temp_src:units ="Degrees Celcius" ; double salt_src(n_qbar, temp_src_time) ; (continues on next page) 1.9. Rivers 51 Croco Documentation, Release 2.1.2 bottom, which enters the Reynolds-averaged Navier-Stokes equations as a boundary conditions for momentum in the x and y directions: 𝐾𝑚 𝜕𝑢 𝜕𝑠 =𝜏𝑏𝑥 𝐾𝑚 𝜕𝑣 𝜕𝑠 =𝜏𝑏𝑦 Determination of the BBL is even more important for the sediment-transport formulations because bottom stress determines the transport rate for bedload and the resuspension rate for suspended sediment. CROCO implements either of two methods for representing BBL processes: (1) simple drag-coefficient expressions or (2) more complex formulations that represent the interactions of wave and currents over a moveable bed. The drag-coefficient methods implement formulae for linear bottom friction, quadratic bottom friction, or a logarithmic profile. The other, more complex wave-current BBL model is described by Blaas et al. [2007] with an example of its use on the Southern California continental shelf. The method uses efficient wave-current BBL computations developed by Soulsby [1995] in combination with sediment and bedform roughness estimates of Grant and Madsen [1982], Nielsen [1986] and Li and Amos [2001]. Linear/quadratic drag The linear and/or quadratic drag-coefficient methods depend only on velocity components u and v in the bottom grid cell and constant, spatially-uniform coefficients 𝛾1and 𝛾2specified as input: 𝜏𝑏𝑥 = (𝛾1+𝛾2√︀𝑢2+𝑣2)𝑢 𝜏𝑏𝑦 = (𝛾1+𝛾2√︀𝑢2+𝑣2)𝑣 where 𝛾1is the linear drag coefficient and 𝛾2is the quadratic drag coefficient. The user can choose between linear or quadratic drag by setting one of these coefficients to zero. The bottom stresses computed from these formulae depend on the elevation of u and v (computed at the vertical mid-elevation of the bottom computational cell). Therefore, in this s-coordinate model, the same drag coefficient will be imposed throughout the domain even though the vertical location of the velocity is different. Logarithmic drag (with roughness length 𝑧0) To prevent this problem, the quadratic drag 𝛾2can be computed assuming that flow in the BBL has the classic vertical logarithmic profile defined by a shear velocity 𝑢*and bottom roughness length 𝑧0(m) as: |𝑢|=𝑢* 𝜅ln (︂𝑧 𝑧0)︂ where |𝑢|=√𝑢2+𝑣2, friction velocity 𝑢*=√𝜏𝑏, z is the elevation above the bottom (vertical mid-elevation point of the bottom cell), 𝜅= 0.41 is von Kármán’s constant. 𝑧0is an empirical parameter. It can be constant (default) or spatially varying. Kinematic stresses are calculated as` 𝜏𝑏𝑥 =𝜅2 ln2(𝑧/𝑧0)√︀𝑢2+𝑣2𝑢 𝜏𝑏𝑦 =𝜅2 ln2(𝑧/𝑧0)√︀𝑢2+𝑣2𝑣 The advantage of this approach is that the velocity and the vertical elevation of that velocity are used in the equation. Because the vertical elevation of the velocity in the bottom computational cell will vary spatially and temporally, the inclusion of the elevation provides a more consistent formulation. Combined wave-current drag (BBL) To provide a more physically relevant value of 𝑧0, especially when considering waves and mobile sediments, a more complex formulation is available (BBL). The short (order 10-s) oscillatory shear of wave-induced motions in a thin (a few cm) wave-boundary layer produces turbulence and generates large instantaneous shear stresses. The turbulence enhances momentum transfer, effectively increasing the bottom-flow coupling and the frictional drag exerted on the wave-averaged flow. The large instantaneous shear stresses often dominate sediment resuspension and enhance bedload transport. Sediment 58 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 transport can remold the bed into ripples and other bedforms, which present roughness elements to the flow. Bedload transport can also induce drag on the flow, because momentum is transferred to particles as they are removed from the bed and accelerated by the flow. Resuspended sediments can cause sediment-induced stratification and, at high concentrations, change the effective viscosity of the fluid. The BBL parameterization implemented in CROCO requires inputs of velocities u and v at reference elevation z, representative wave-orbital velocity amplitude 𝑢𝑏, wave period T, and wave propagation direction 𝜃(degrees, clockwise from north). The wave parameters may be the output of a wave model such as WKB or WW3 or simpler calculations based on specified surface wave parameters. Additionally the BBL models require bottom sediment characteristics (median grain diameter 𝐷50, mean sediment density 𝜌𝑠, and representative settling velocity 𝑤𝑠); these are constant (ANA_BSEDIM) or based on the composition of the uppermost active layer of the bed sediment during the previous time step if the sediment model is used. The wave-averaged, combined wave–current bottom stress is expressed as function of 𝜏𝑤and 𝜏𝑐(i.e., the stress due to waves in the absence of currents and due to currents in the absence of waves, respectively) according to Soulsby [1995]: ¯𝜏𝑤𝑐 =𝜏𝑐(︃1+1.2(︂𝜏𝑤 𝜏𝑤+𝜏𝑐)︂3.2)︃ The maximum wave–current shear stress within a wave cycle is obtained by adding ¯𝜏𝑤𝑐 and 𝜏𝑤(with 𝜑the angle between current and waves): 𝜏𝑤𝑐 =(︀(¯𝜏𝑤𝑐 +𝜏𝑤cos 𝜑)2+ (𝜏𝑤sin 𝜑)2)︀1/2 The stresses 𝜏𝑐and 𝜏𝑤are determined using: 𝜏𝑐=𝜅2 ln2(𝑧/𝑧0)|𝑢|2 𝜏𝑤= 0.5𝜌𝑓𝑤𝑢2 𝑏 𝑢𝑏, the bottom orbital velocity, is determined from the significant wave height 𝐻𝑠and peak frequency 𝜔𝑝using the Airy wave theory: 𝑢𝑏=𝜔𝑝 𝐻𝑠 2 sinh 𝑘ℎ with h the local depth and k the local wave number from the dispersion relation. The wave-friction factor 𝑓𝑤is, according to Soulsby [1995]: 𝑓𝑤= 1.39(𝑢𝑏/𝜔𝑝𝑧0)−0.52 The wave–current interaction in the BBL is taken into account only if 𝑢𝑏>1cm/s; otherwise, current-only conditions apply. Shear stress for sediment resuspension and roughness length due to bed form To determine the shear stress relevant for sediment resuspension and the roughness length due to bed forms, we follow the concept of Li and Amos [2001] briefly summarized here. First, the maximum wave–current skin friction 𝜏𝑠is computed from the equations above, using the Nikuradse roughness 𝑧0=𝐷50/12. A bed-load layer develops as soon as the maximum wave–current skin friction 𝜏𝑠exceeds the critical stress 𝜏𝑐𝑟. This layer affects the stress effective for ripple formation and sediment resuspension. Subsequently, for sandy locations, ripple height and length are computed, leading to a spaceand time-dependent ripple roughness length 𝑧0=𝑧𝑟𝑖𝑝, which is used to compute the drag on the flow (instead of a constant value when BBL is not activated). This drag provides boundary conditions to the momentum and turbulence equations (KPP or GLS). 1.13.2 Sediment models There are two sediment models in CROCO: the USGS model derived from the UCLA/USGS ROMS community, and MUSTANG derived from the Ifremer SIAM/MARS community. 1.13. Other modules : sediment models, flow-obstruction models, biology models 59 Croco Documentation, Release 2.1.2 1.13.2.1 USGS Sediment Model This USGS sediment model is derived from the UCLA/USGS ROMS community. See Blaas et al. [2007], Warner et al. [2008] and Shafiei [2021] for details. Regarding the time and space resolution considered, the explicit solution generally refers to quantities averaged over wave periods, although the implementation of a nonhydrostatic solver in CROCO opens the way to a waveresolved approach. One of the crucial ingredients in the sediment transport model is a reliable representation of wave-averaged (or wave-resolved) hydrodynamics and turbulence. In the wave-averaged approach, 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 wave effects) is required since it determines the initiation of grain motion and settling and resuspension of suspended load (see BBL). 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 (soon space-dependent) condition. 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). 1.13.2.1.1 Sediment bed The sediment bed is represented by three-dimensional arrays with a fixed number of layers beneath each horizontal model cell. Each cell of each layer in the bed is initialized with a thickness, sediment-class distribution, porosity, and age. The mass of each sediment class in each cell can be determined from these values and the grain density. The bed framework also includes two-dimensional arrays that describe the evolving properties of the seabed, including bulk properties of the surface layer (active layer thickness, mean grain diameter, mean density, mean settling velocity, mean critical stress for erosion) and descriptions of the subgrid scale morphology (ripple height and wavelength). These properties are used to estimate bed roughness in the BBL formulations and feed into the bottom stress calculations. The bottom stresses are then used by the sediment routines to determine resuspension and transport, providing a feedback from the sediment dynamics to the hydrodynamics. The bed layers are modified at each time step to account for erosion and deposition and track stratigraphy. At the beginning of each time step, an active layer thickness 𝑧𝑎is calculated [Harris and Wiberg, 1997]. 𝑧𝑎is the minimum thickness of the top bed layer. If the top layer is thicker than 𝑧𝑎, no action is required. If the top layer is less than 𝑧𝑎, then the top layer thickness is increased by entraining sediment mass from deeper layers until the top layer thickness equals 𝑧𝑎. If sediment from deeper than the second layer is mixed into the top layer, the bottom layer is split to enforce a constant number of layers and conservation of sediment mass. Each sediment class can be transported by suspended-load and/or bedload (below). Suspended-load mass is exchanged vertically between the water column and the top bed layer. Mass of each sediment class available for transport is limited to the mass available in the active layer. Bedload mass is exchanged horizontally within the top layer of the bed. Mass of each sediment class available for transport is limited to the mass available in the top layer. Suspended-sediment that is deposited, or bedload that is transported into a computational cell, is added to the top bed layer. If continuous deposition results in a top layer thicker than a user-defined threshold, a new layer is provided to begin accumulation of depositing mass. The bottom two layers are then combined to conserve the number of layers. After erosion and deposition have been calculated, the active-layer thickness is recalculated and bed layers readjusted to accommodate it. This step mixes away any very thin layer (less than the active layer thickness) of newly deposited material. Finally the surficial sediment characteristics, such as D50, ripple geometry, etc., are updated and made available to the bottom stress calculations. 1.13.2.1.2 Suspended-sediment transport The concentration of sediment suspended in the water column is transported, like other conservative tracers (e.g., temperature and salinity) by solving the advection–diffusion equation with a source/sink term for vertical settling and erosion: 𝜕𝐶 𝜕𝑡 ⏟ ⏞ 𝑅𝐴𝑇 𝐸 =− ∇. v𝐶 ⏟ ⏞ 𝐴𝐷𝑉 𝐸𝐶𝑇 𝐼𝑂𝑁 +𝒟𝐶 ⏟ ⏞ 𝑀𝐼𝑋𝐼𝑁𝐺 −𝜕𝑤𝑠𝐶 𝜕𝑧 ⏟ ⏞ 𝑆𝐸𝑇 𝑇 𝐿𝐼𝑁𝐺 +𝐸 𝛿𝑧𝑏𝑧=𝑧𝑏 ⏟ ⏞ 𝐸𝑅𝑂𝑆𝐼𝑂𝑁 60 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 𝐶is the Reynolds-averaged, wave-averaged (unless used in wave-resolving mode) sediment concentration of a particular size class;  vis the flow velocity (it is the Lagrangian velocity  v𝐿in wave-averaged equations, comprising the Stokes drift  v𝑆). For each size class, the source or sink term represents the net of upward flux of eroded material E and downward settling, i.e., the deposition flux. 𝑤𝑠is the settling velocity, dependent on sediment grain size, but independent of flow conditions and concentrations. It is an input parameter of the model (WSED in sediment.in; see below). Settling is computed via a semi-Lagrangian advective flux algorithm, which is unconditionally stable [Durran, 2010]. It uses a piece-wise parabolic vertical reconstruction of the suspended sediment for high-order interpolation, with WENO constraints to avoid oscillations. 𝐸is the erosion flux at the sea floor and is only applied to the first grid level of height 𝑧𝑏and cell size 𝛿𝑧𝑏. The erosion flux for each class is given by: 𝐸=𝐸0(1 −𝑝)𝜑(︂𝜏𝑠 𝜏𝑐−1)︂for 𝜏𝑠> 𝜏𝑐 𝐸0is an empirical erosion rate (ERATE parameter in sediment.in; see below); p is the sediment porosity; 𝜑is the volumetric fraction of sediment of the class considered; 𝜏𝑐is the critical shear stress; and 𝜏𝑠is the shear stress magnitude on the grains (skin stress due to wave-induced bed orbital velocities and mean bottom currents; see BBL). The critical shear stress is the threshold for the initiation of sediment motion. Zero-flux boundary conditions are imposed at the surface and bottom in the vertical diffusion equation. Lateral open boundaries are treated as other tracers according to Marchesiello et al. [2001]. A quasi-monotonic 5th-order advection scheme (WENO5-Z, Borges et al. [2008]) can be used for horizontal and vertical advection of all tracers, including sediments. 1.13.2.1.3 Bedload transport The bedload flux 𝑞𝑏, which is considered unresolved by the model can be calculated using different bedload models implemented in CROCO. The formulation by Meyer-Peter Muller [Meyer-Peter and Müller, 1948] is suited to rivers or continental shelf problems, where nonlinear wave effects are small. For nearshore applications, where wave nonlinearity is important, the bedload transport formulation proposed by van der A et al. (2013) is implemented as in Shafiei [2021] following Kalra et al. [2019] with some modifications. Each formulation depends on the characteristics of individual sediment classes, including median size 𝑑50, grain density 𝜌𝑠, specific density in water 𝑠=𝜌/𝜌𝑠, and critical shear stress 𝜏𝑐. Non-dimensional transport rates Φare calculated for each sediment class and converted to dimensional bedload transport rates 𝑞𝑏using: 𝑞𝑏= Φ√︁(𝑠−1)𝑔𝑑3 50𝜌𝑠 These are horizontal vector quantities with directions that correspond to the combined bed-stress vectors. Details on the computation of Φdiffers in the Meyer-Peter Müeller or van der A formulations. Slope effect: bedload fluxes are corrected to account for the avalanche process, i.e., the gravitational flow of sand occuring when the bottom slope exceeds the critical slope angle: 𝑞𝑏,𝑠𝑙𝑜𝑝𝑒 =𝑞𝑏(︂0.65 (0.65 −tan 𝛽) cos 𝛽)︂, This correction considers the effect of the bed slope 𝛽= tan−1(𝑑𝑧𝑏/𝑑𝑥). The value 0.65 is derived from the consideration of an angle of repose of 33∘. Bedload numerics: bedload fluxes are computed at grid-cell centers and are limited by the availability of each sediment class in the top layer. Fluxes are then interpolated on cell faces using an upwind approach, either 1rstorder (e.g., Lesser et al. [2004]) or 5th order, or even a WENO5 interpolation to avoid oscillations. Flux differences are then used to determine changes of sediment mass in the bed at each grid cell. 1.13.2.1.3.1 Meyer-Peter Müller : Transport by currents Meyer-Peter Müller [Meyer-Peter and Müller, 1948] formulation : Φ = 𝑚𝑎𝑥 [︀8(𝜃𝑠−𝜃𝑐)1.5,0]︀ 1.13. Other modules : sediment models, flow-obstruction models, biology models 61 Croco Documentation, Release 2.1.2 where Φis the magnitude of the non-dimensional transport rate for each sediment class, 𝜃𝑠is the non-dimensional Shields parameter for skin stress: 𝜃𝑠=𝜏𝑠 (𝑠−1)𝑔𝑑50 𝜃𝑐is the critical Shields parameter, and 𝜏𝑠the magnitude of total skin-friction component of bottom stress computed from: 𝜏𝑠=√︁𝜏2 𝑠𝑥 +𝜏2 𝑠𝑦 where 𝜏𝑠𝑥 and 𝜏𝑠𝑦 are the skin-friction components of bed stress, from currents alone or the maximum wavecurrent combined stress, in the x and y directions. These are computed at cell faces (u and v locations) and then interpolated to cell centers ( 𝜌points). The bedload transport vectors are partitioned into x and y components based on the magnitude of the bed shear stress as: 𝑞𝑏𝑥 =𝑞𝑏 𝜏𝑠𝑥 𝜏𝑠 𝑞𝑏𝑦 =𝑞𝑏 𝜏𝑠𝑦 𝜏𝑠 1.13.2.1.3.2 van der A (2013): Transport by nonlinear waves The SANTOSS bedload model is based on the half-wave cycle concept proposed by Dibajnia and Watanabe [1993] that captures asymmetric transport by non-linear waves and the effect of phase lag between mobilization and transport. CROCO contains an adapted version by Shafiei [2021], based on the implementation of Kalra et al. [2019]. In our formulation, the effect of wave-averaged currents is removed by default (assuming that the transport by currents is effectively performed by the suspended load model) and it thus only retains the nonlinear effects of waves. In the brief presentation below, we retain the current terms for completeness, but focus on wave effects. The method to obtain bedload transport under asymmetric waves can be divided into three major steps (van der A, 2013) [Kalra et al., 2019]. In the first step, the asymmetric waveform based on the Ursell number is evaluated using wave statistics. The Shields parameter for each half cycle of the wave form is computed in the second step. Finally, a phase lag is estimated from the velocity and sediment concentrations that determine the amount of bedload transported in the half cycle following mobilization. The non-dimensional bedload transport rate Φis thus given by: Φ = 1 𝑇[︃𝜃𝑐 𝜃𝑐1/2𝑇𝑐(︂Ω𝑐𝑐 +𝑇𝑐 2𝑇𝑐𝑢 Ω𝑡𝑐)︂+𝜃𝑡 𝜃𝑡1/2𝑇𝑡(︂Ω𝑡𝑡 +𝑇𝑡 2𝑇𝑡𝑢 Ω𝑐𝑡)︂]︃, where 𝑇, 𝑇𝑐, 𝑇𝑡, 𝑇𝑐𝑢 and 𝑇𝑡𝑢 are the wave period, duration of wave crest half cycle, duration of wave trough half cycle, duration of accelerating flow within the crest half cycle and duration of accelerating flow within the trough half cycle respectively, 𝜃𝑐and 𝜃𝑡represent the Shields numbers associated with the wave crest and trough half cycles. The sand load transported during the crest period is the combination of Ω𝑐𝑐 (mobilized during the crest period) and Ω𝑡𝑐 (mobilized during the trough period). Similarly, Ω𝑡𝑡 and Ω𝑐𝑡 are the sand load transported during the trough period (mobilized during the trough and crest periods respectively). The sand load transported during each half-cycle is conventionally modeled according to a power law of Shields number: Ω𝑖= max (︁11 (︀𝜃𝑖−𝜃𝑐𝑟)︀1.2,0)︁, where 𝜃𝑐𝑟 is the critical Shields number and, hereafter, the subscript “i” is either “c” for crest or “t” for trough half cycles. To determine Ω𝑐𝑡 and Ω𝑡𝑐, i.e., the portion of the bedload remaining in suspension to be transported in the next half cycle, a phase lag parameter is evaluated. Let’s assume a two-dimensional (x,z) cross-shore problem for simplicity. The Shields number for the peak or trough (𝜃𝑖=𝜃𝑡or 𝜃𝑐) is calculated according to: 𝜃𝑖= 1 2𝑓𝑤𝛿𝑖|𝑢𝑖,𝑟|𝑢𝑖,𝑟 (𝑠−1)𝑔𝑑50 . 62 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 𝑢𝑖,𝑟 is the representative cross-shore combined wave-current velocity at trough or crest half cycles calculated as: 𝑢𝑖,𝑟 =ˆ𝑢𝑖 √2+|𝑢𝛿|, where ˆ𝑢𝑖is the peak crest or trough orbital velocities, 𝑢𝛿is the steady current velocity at the top of the wave boundary layer. 𝑓𝑤𝛿𝑖 is the linear wave-current friction factor at crest or trough calculated by Ribberink [1998]: 𝑓𝑤𝛿𝑖 =ˆ𝑢 𝑢𝛿+ ˆ𝑢𝑓𝑤𝑖 +𝑢𝛿 𝑢𝛿+ ˆ𝑢𝑓𝛿 where ˆ𝑢is the representative orbital velocity amplitude for the whole flow cycle (given by ˆ𝑢=√2𝑢𝑜𝑟𝑏). 𝑓𝛿is the current-related friction factor dependent on a current-related roughness 𝑘𝑠𝛿 and 𝑓𝑤𝑖 is the wave friction factor, calculated separately for the crest and trough half-cycles and depends on a wave-related roughness 𝑘𝑠𝑤. If the representative orbital excursion amplitude ˆ𝑎= ˆ𝑢𝑇/2𝜋is large enough (i.e., greater than 1.587 𝑘𝑠𝑤): 𝑓𝑤𝑖 = 0.00251 𝑒5.21[︂(︂2𝑇𝑖𝑢 𝑇𝑖)︂2.6^𝑎 𝑘𝑠𝑤 ]︂−0.19 , otherwise, 𝑓𝑤𝑖 = 0.3. If 𝑢𝛿= 0 (𝑢𝑖,𝑟 = ˆ𝑢𝑖/√2and 𝑓𝑤𝛿𝑖 =𝑓𝑤𝑖), the effect of currents is completely removed from the bedload transport calculation. This choice represents our default to avoid double counting the transport by wave-averaged currents. Finally, following Kalra et al. [2019], after calculating Φ, we apply to 𝑞𝑏a bedload factor 𝑓𝑏𝑙𝑑 (bedload_coeff in CROCO). This factor allows us to adjust the relative contribution to sediment transport of wave-induced bedload compared to the suspended load transported by mean currents. In this way, we have a better control of the antagonistic mechanisms that govern onshore and offshore transports respectively. 1.13.2.1.4 Morphology The bed evolution (variation in time of 𝑧𝑏, the height of the bed), is calculated from the divergence of sediment fluxes (Exner equation), which results from the difference between erosion and sedimentation of suspended sediments. In wave-averaged equations, where residual wave effects need to be parametrized as bedload fluxes 𝑞𝑏, the bed evolution also arises from the divergence of these fluxes. 𝜕𝑧𝑏 𝜕𝑡 =−𝑓𝑚𝑜𝑟 1−𝑝(︂𝜕𝑞𝑏 𝜕𝑥 −𝑤𝑠 𝜕𝐶 𝜕𝑧 +𝐸)︂. This equation accounts for a morphological acceleration factor 𝑓𝑚𝑜𝑟 (morph_fac in CROCO). A value of 1 has no effect, and values greater than 1 accelerate the bed response. The concept of morphological acceleration is based on the fact that morphodynamic changes are slower than hydrodynamic ones [van Rijn, 1993]. In this case, the bed evolution can be accelerated without affecting the hydro-morphological solution. The increased rate of morphological change can be useful for simulating evolution over long time periods. Strategies for morphological updating are described by Roelvink [2006] and implemented in CROCO following Warner et al. [2008]. In our implementation, bedload fluxes, erosion, and deposition rates are multiplied by 𝑓𝑚𝑜𝑟, while the magnitude of sediment concentrations in the water column is not modified – just the exchange rate to and from the bed. For both bedload and suspended load, sediment is limited in availability, based on the true amount of sediment mass (not multiplied by the scale factor). For dynamical consistency, the vertical velocity is modified (in omega.F) by the rate of change of vertical grid levels 𝑑𝑧/𝑑𝑡, adjusting to the moving sea floor and free surface (grid “breathing” component; Shchepetkin and McWilliams [2005]). This method is mass conserving and retains tracer constancy preservation. 1.13.2.1.5 Sediment Density Witt CPP SED_DENS, effects of suspended sediment on the density field are included with terms for the weight of each sediment class in the equation of state for seawater density as: 𝜌=𝜌𝑤𝑎𝑡𝑒𝑟 + 𝑁𝑠𝑒𝑑 ∑︁ 𝑚=1 𝐶𝑚 𝜌𝑠,𝑚 (𝜌𝑠,𝑚 −𝜌𝑤𝑎𝑡𝑒𝑟) 1.13. Other modules : sediment models, flow-obstruction models, biology models 63 Croco Documentation, Release 2.1.2 This enables the model to simulate processes where sediment density influences hydrodynamics, such as density stratification and gravitationally driven flows. Related CPP options: SUSPLOAD Activate suspended load transport BEDLOAD Activate bedload transport MORPHODYN Activate morphodynamics BEDLOAD_VANDERA van der A formulation for bedload (van der A et al., 2013) BEDLOAD_MPM Meyer-Peter-Muller formulation for bedload [Meyer-Peter and Müller, 1948] SLOPE_LESSER Lesser formulation for avalanching [Lesser et al., 2004] SLOPE_NEMETH Nemeth formulation for avalanching (Nemeth et al, 2006) BEDLOAD_UP1 Bedload flux interpolation: upwind 1rst order BEDLOAD_UP5 Bedload flux interpolation: upwind 5th order BEDLOAD_WENO5 Bedload flux interpolation: WENO 5th order ANA_SEDIMENT Set analytical sediment size, initial ripple and bed parameters ANA_BPFLUX Set kinematic bottom flux of sediment tracer (if different from 0) SPONGE_SED Gradually reduce erosion/deposition near open boundaries SED_DENS Activate the effect of suspended sediment on the density field Preselected options: #ifdef SEDIMENT # undef MUSTANG # define ANA_SEDIMENT # define SPONGE_SED # define Z0_BL # define Z0_RIP # ifdef BEDLOAD # ifdef BEDLOAD_VANDERA /* default BEDLOAD scheme */ # elif defined BEDLOAD_MPM # elif defined BEDLOAD_WULIN # elif defined BEDLOAD_MARIEU # else # if (defined WAVE_OFFLINE || defined WKB_WWAVE ||\ defined ANA_WWAVE || defined OW_COUPLING) # define BEDLOAD_VANDERA # else # define BEDLOAD_MPM # endif # endif # ifdef BEDLOAD_UP1 /* default INTERPOLATION */ # elif defined BEDLOAD_UP5 # elif defined BEDLOAD_WENO5 # else # define BEDLOAD_UP1 # endif # ifdef SLOPE_LESSER /* default SLOPE scheme */ # elif defined SLOPE_NEMETH # elif defined SLOPE_KIRWAN # else # define SLOPE_LESSER # endif # endif /* BEDLOAD */ #endif /* SEDIMENT */ Parameters in sediment.in 64 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 1Stitle (a80) CROCO -Sediment -Test 2Sd(1-NST), CSED, SRHO, WSED, ERATE, TAU_CE, TAU_CD, BED_FRAC(1:NLAY) 0.125 9.9 2650. 9.4 25.0e-5 0.05 0.14 0.4 0.4 0.050 0.0 2650. 1.6 4.0e-5 0.01 0.14 0.6 0.6 3BTHK(1:NLAY) 1. 10. 4BPOR(1:NLAY) 0.41 0.42 5Hrip 0.03 6Lrip 0.14 7bedload_coeff 0. 8morph_fac 10. 9transC 0.03 10 transN 0.2 11 tcr_min 0.03 12 tcr_max 5.5 13 tcr_slp 0.3 14 tcr_off 1. 15 tcr_tim 28800. 16 L_ADS L_ASH L_COLLFRAG L_TESTCASE F T F F 17 F_DP0 F_NF F_DMAX F_NB_FRAG F_ALPHA F_BETA F_ATER F_ERO_FAC F_ ˓→ERO_NBFRAG F_COLLFRAGPARAM F_CLIM F_ERO_IV 0.000004 2. 0.0015 2. 0.35 0.15 0. 0. ␣ ˓→2. 0.01 0.001 1 18 MUD_FRAC_EQ [1:NMUD] 0.10 0.20 0.40 0.20 0.10 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 (continues on next page) 1.13. Other modules : sediment models, flow-obstruction models, biology models 65 Croco Documentation, Release 2.1.2 (continued from previous page) 19 MUD_T_DFLOC 200. 99 END of sediment input data GLOSSARY CARD 1: String with a maximum of eighty characters. •Stitle : Sediment case title. CARD 2: Sediment grain parameters & initial values (NST lines) •Sd : Diameter of grain size class [mm]. •CSED : Initial concentration (spatially uniform) [kg/m3]. •SRHO : Density of sediment material of size class [kg/m3]. Quartz: SRHO=2650 𝑘𝑔/𝑚3 •WSED : Settling velocity of size class [mm/s]. Typically [Soulsby, 1997]: WSED = 103(𝑣𝑖𝑠𝑐 (√10.362+ 1.049𝐷3−10.36) / 𝐷50 [mm/s] with –𝐷=𝐷50 (𝑔(SRHO/𝜌0−1) /(𝑣𝑖𝑠𝑐2) )0.33333 –𝐷50 = 10−3𝑆𝑑 [m] –𝑣𝑖𝑠𝑐 = 1.3 10−3/𝜌0[m2/s] •ERATE : Erosion rate of size class [kg/m2/s]. Typically: ERATE = 10−3𝛾0WSED SRHO [𝑘𝑔/𝑚2/𝑠] with 𝛾0= 10−3−10−5[Smith and McLean, 1977] •TAU_CE : Critical shear stress for sediment motion [N/m2] (initiation of bedload for coarses, suspension for fines). Typically : TAUCE=6.4 10−7𝜌0WSED2[N/m2] •TAU_CD : Critical shear stress for deposition of cohesive sediments [N/m2] •BED_FRAC : Volume fraction of each size class in each bed layer (NLAY columns) [0<BED_FRAC<1] CARD 3: Sediment bed thickness, 1st field is top layer (‘delt_a’) •BTHK : Initial thicknesses of bed layers [m] Bthk(1) active layer thickness, fixed in simulation unless SUM(Bthk(:))<Bthk(1) CARD 4: Sediment bed porosity •BPOR : Initial porosity of bed layers [m] used in ana_sediment ifdef ANA_SEDIMENT (not in init.nc) 66 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 CARD 5: Bottom ripple height •Hrip : Initial ripple height [m] used in ana_sediment ifdef ANA_SEDIMENT (not in init.nc) CARD 6: Bottom ripple length •Lrip : Initial ripple length [m] used in ana_sediment ifdef ANA_SEDIMENT (not in init.nc) CARD 7: Bedload coefficient •bedload_coeff : factor limiting the magnitude of bedload flux 0<bedload_coef<1 CARD 8: Morphological acceleration factor •morph_fac : factor accelerating bed evolution morph_fac>=1 CARD 9 : •transC : Cohesive transitionUnder that value of total mud fraction entire bed behaves as a non-cohesive bed CARD 10 : •transN : Noncohesive transitionOver that value of total mud fraction entire bed behaves as a cohesive bed CARD 11 : •tcr_min : Minimum shear for erosion CARD 12 : •tcr_max : Maximum shear for erosion CARD 13 : •tcr_slp : Tau_crit profile slope CARD 14 : •tcr_off : Tau_crit profile offset CARD 15 : •tcr_tim : Tau_crit consolidation rate CARD 16 : booleans for flocculation •L_ADS : Boolean set to .true. if differential settling aggregation •L_ASH : Boolean set to .true. if shear aggregation 1.13. Other modules : sediment models, flow-obstruction models, biology models 67 Croco Documentation, Release 2.1.2 •ws_hind_opt_n(): choice of hindered settling formulation: 0 no hindered settling, 1 Scott, 2 Winterwerp, 3 Wolanski (see Settling velocity) •ws_hind_para_n(1:2,num substance): 2 additional parameters (see Settling velocity) •diam_n(): diameter of particles (m) (used only if #key_mustang_flocmod is activated see FLOCMOD ) òNote If nv_mud = 0 this namelist is not read. &nmlpartnc namelist: each parameter is a vector of length nv_ncp •name_var_n(): name of variable •long_name_var_n(): long name of variable •standard_name_var_n(): standard name of variable •unit_var_n(): string, unit of concentration of variable •flx_atm_n(): uniform atmospherical deposition (unit/m2/s) •cv_rain_n(): concentration in rainwater (kg/m3 of water) •cini_wat_n(): initial concentration in water column (kg/m3) •cini_air_n(): initial concentration in air •l_out_subs_n(): saving in output file if TRUE •init_cv_name_n(): name of substance read from initial condition file •obc_cv_name_n(): name of substance read from obc file •cini_sed_n(): initial concentration in sediment (quantity/kg of dry sediment) (only if cppkey MUSTANG) •tocd_n(): critical stress of deposition (N/m2) (only if cppkey MUSTANG) •ros_n(): density of particle (kg/m3) (only if cppkey MUSTANG) •cobc_wat_n(): boundaries uniform and constant concentration (kg/m3) •ws_free_opt_n(): integer, choice of free settling formulation: 0 constant, 1 Van Leussen, 2 Winterwerp, 3 Wolanski (see Settling velocity) •ws_free_min_n(): minimum setling velocity (m/s) (see Settling velocity) •ws_free_max_n(): maximum setling velocity (m/s) (see Settling velocity) •ws_free_para_n(1:4,num substance): 4 additional parameters (see Settling velocity) •ws_hind_opt_n(): choice of hindered settling formulation: 0 no hindered settling, 1 Scott, 2 Winterwerp, 3 Wolanski (see Settling velocity) •ws_hind_para_n(1:2,num substance): 2 additional parameters (see Settling velocity) òNote If nv_ncp = 0 this namelist is not read. If MUSTANG cpp key is not defined, cini_sed_n,tocd_n,ros_n,ws_free_opt_n,ws_free_para_n, ws_hind_opt_n,ws_hind_para_n are not read and must not be present &nmlpartsorb namelist: each parameter is a vector of length nv_sorb •name_var_n(): name of variable •long_name_var_n(): long name of variable 74 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 •standard_name_var_n(): standard name of variable •unit_var_n(): string, unit of concentration of variable •flx_atm_n(): uniform atmospherical deposition (unit/m2/s) •cv_rain_n(): concentration in rainwater (kg/m3 of water) •cini_wat_n(): initial concentration in water column (kg/m3) •cini_air_n(): initial concentration in air •l_out_subs_n(): saving in output file if TRUE •init_cv_name_n(): name of substance read from initial condition file •obc_cv_name_n(): name of substance read from obc file •cini_sed_n(): initial concentration in sediment (quantity/kg of dry sediment) (only if cppkey MUSTANG) •cobc_wat_n(): boundaries uniform and constant concentration (kg/m3) •name_varpc_assoc_n(): name of associated particulate substance on which this substance is sorbed òNote If nv_sorb = 0 this namelist is not read. If MUSTANG cpp key is not defined, cini_sed_n is not read and must not be present &nmlvardiss namelist: each parameter is a vector of length nv_dis •name_var_n(): name of variable •long_name_var_n(): long name of variable •standard_name_var_n(): standard name of variable •unit_var_n(): string, unit of concentration of variable •flx_atm_n(): uniform atmospherical deposition (unit/m2/s) •cv_rain_n(): concentration in rainwater (kg/m3 of water) •cini_wat_n(): initial concentration in water column (kg/m3) •cini_air_n(): initial concentration in air •l_out_subs_n(): saving in output file if TRUE •init_cv_name_n(): name of substance read from initial condition file •obc_cv_name_n(): name of substance read from obc file •cini_sed_n(): initial concentration in sediment (quantity/kg of dry sediment) (only if cppkey MUSTANG) •cobc_wat_n(): boundaries uniform and constant concentration (kg/m3) òNote If nv_dis = 0 this namelist is not read. If MUSTANG cpp key is not defined, cini_sed_n is not read and must not be present &nmlvarfix namelist: each parameter is a vector of length nv_fix •name_var_fix(): name of variable •long_name_var_fix(): long name of variable •standard_name_var_fix(): standard name of variable 1.13. Other modules : sediment models, flow-obstruction models, biology models 75 Croco Documentation, Release 2.1.2 •unit_var_fix(): string, unit of concentration of variable •cini_wat_fix(): initial concentration in water column (kg/m3) •l_out_subs_fix(): saving in output file if TRUE •init_cv_name_fix(): name of substance read from initial condition file òNote If nv_fix = 0 this namelist is not read. &nmlvarbent namelist: each parameter is a vector of length nv_bent •name_var_bent(): name of variable •long_name_var_bent(): long name of variable •standard_name_var_bent(): standard name of variable •unit_var_bent(): string, unit of concentration of variable •cini_bent(): initial concentration •l_out_subs_bent(): saving in output file if TRUE òNote If nv_bent = 0 or cppkey key_benthic is not defined, this namelist is not read. &nmlsubmassbalance namelist: (see also: Details on submassbalance computation) •submassbalance_l: activate submassblance computation if TRUE and if cppkeys SUBSTANCE_SUBMASSBALANCE is defined •submassbalance_nb_border: number of polygons and lines •submassbalance_input_file: path of the input file (see format information here: submassbalance input file format) (if ‘’ or ‘all_domain’, only one budget zone is taking into account (all the domain) and any fluxes threw open borders) •submassbalance_output_file: path of the output file (in netcdf, more information here: submassbalance output file format) •submassbalance_dtout: = output frequency in hours (h) •submassbalance_date_start: = starting date for budget/fluxes computing, exemple ‘1999/01/01 00:00:00’ òNote If cppkey SUBSTANCE_SUBMASSBALANCE is not defined, this namelist is not read. 1.13.2.2.2.4 Input file: Mustang namelist òNote If the user does not specify a parameter in the namelist file, the default value in MUSTANG_NAMELIST/paraMUSTANG_default.txt is used 76 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 This default input files incorporates all the parameters that are needed for both V1 or V2 MUSTANG versions. Therefore, not all parameters are used, depending on the set of CPP keys or booleans included in the MUSTANG input file itself. All the parameters in the paraMUSTANG_default.txt are read first, before reading the user-defined input file defined in croco.in. The parameters defined in the user-defined namelist file will overwrite those defined in the default file. The user-defined input file can either be a full copy of the default input file, or only define the parameters that matter the most for a specific configuration. In the later case, even if the parameters are not mentionned, the namelist group section needs to be present in the file even if empty, e.g.: &namsedim_deposition / Mustang input file contains at least 10 namelists and at most 16 namelists depending on the cppkeys key_MUSTANG_V2, key_MUSTANG_debug, key_MUSTANG_flocmod key_MUSTANG_lateralerosion, key_noTSdiss_insed: •namsedim_init: relative to sediment initialization •namsedim_layer: relative to sediment layers characterization and active layer •namsedim_bottomstress: relative to bottom shear stress •namsedim_deposition: relative to sediment deposition •namsedim_erosion: relative to sediment erosion •namsedim_poro: relative to porosity •namsedim_bedload: relative to sediment bedload (only if key_MUSTANG_V2) •namsedim_lateral_erosion: relative to lateral sediment erosion (only if key_MUSTANG_lateralerosion) •namsedim_consolidation: relative to sediment consolidation •namsedim_diffusion: relative to dissolved diffusion in sediment •namsedim_bioturb: relative to bioturbation in sediment •namsedim_morpho: relative to morphodynamic •namtempsed: relative to temperature estimation in sediment (only if !defined key_noTSdiss_insed) •namsedoutput: parameters used for output results in the file sediment •namsedim_debug: output for debug (only if key_MUSTANG_debug and key_MUSTANG_V2) •namflocmod: parameters using for FLOCMOD module (only if key_MUSTANG_flocmod) •namdredging: relative to dredging feature (see also: Details on dredging effect) Each namelist is described bellow with the description of each parameter. &namsedim_init: •date_start_dyninsed: starting date for dynamic processes in sediment •date_start_morpho: starting date for morphodynamic processes •l_unised: set to .true. for a uniform bottom initialization, set to .false. to read initialisation from filerepsed file •filrepsed: file path from which the model is initialized for the continuation of a previous run or a non-uniform initialisation used if l_unised = .false. •hseduni: initial uniform sediment thickness (m) •cseduni: initial sediment concentration (kg/m3) 1.13. Other modules : sediment models, flow-obstruction models, biology models 77 Croco Documentation, Release 2.1.2 •l_unised_adjust_hsed: set to .true. if we want to adjust the sediment thickness in order to be coherent with sediment parameters (calculation of a new hseduni based on cseduni, cvolmax values, and csed_ini of each sediment) •csed_mud_ini: mud concentration into initial sediment (kg/m3) (if = 0. ==> csed_mud_ini = cfreshmud) •ksmiuni: lower grid cell index in the sediment •ksmauni: upper grid cell index in the sediment •sini_sed: initial interstitial water uniform salinity (in the sediment) (PSU) •tini_sed: initial interstitial water uniform temperature (in the sediment) (Celsius degree) •poro_mud_ini: if key_MUSTANG_V2 only, initial porosity of mud fraction •l_initsed_vardiss: set to .true. if initialization of dissolved variables, temperature and salinity in sediment (will be done with concentrations in water at bottom (k=1)) &namsedim_layer: •l_dzsminuni: set to .false. if dzsmin vary with sediment bed composition, else dzsmin = dzsminuni (used if key_MUSTANG_V2 only) •dzsminuni: minimum sediment layer thickness (m) (used if key_MUSTANG_V2 only) •dzsmin: minimum sediment layer thickness (m) •dzsmax_bottom: maximum thickness of bottom layers which result from the fusion when ksdmax is exceeded (m) •l_dzsmaxuni: if set to .true. dzsmax = dzsmaxuni , if set to .false. then linearly computed in MUSTANG_sedinit from dzsmaxuni to dzsmaxuni/100 depending on water depth •dzsmaxuni: uniform maximum thickness for the superficial sediment layer (m), must be >0 •nlayer_surf_sed: number of layers below the sediment surface that can not be melted (max thickness = dzsmax) •k1HW97: ref value k1HW97 = 0.07, parameter to compute active layer thickness [Harris and Wiberg, 1997] (key_MUSTANG_V2 only) •k2HW97: ref value k2HW97 = 6.0, parameter to compute active layer thickness [Harris and Wiberg, 1997] (key_MUSTANG_V2 only) •fusion_para_activlayer: criterion cohesiveness for fusion in active layer (key_MUSTANG_V2 only): –0: no fusion, –= 1: frmudcr1, –> 1: between frmudcr1 & frmudcr2 &namsedim_bottomstress, this part combine bottom stress and roughness parameters: •l_z0seduni: if true, z0seduni is used; if false z0sed is computed from sediment diameter •z0seduni: uniform bed roughness (m) •z0sedmud: mud (i.e.minimum) bed roughness (m) (used only if l_unised is false) •z0sedbedrock: bed roughness for bedrock (no sediment) (m) (used only if l_unised is false) •l_fricwave: if true the wave related friction factor is computed from wave orbital velocity and period; if false then fricwav namelist value is used (see wave skin friction) •fricwav: default value is 0.06, wave related friction factor (used for bottom shear stress computation if l_fricwave is false) •l_z0hydro_coupl_init: if true the evaluation of z0 hydro depends on sediment composition at the beginning of the simulation •l_z0hydro_coupl: if true the evaluation of z0 hydro depends on sediment composition along the run 78 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 •coef_z0_coupl: if l_z0hydro_coupl is true, parameter to compute z0hydro in the first centimeter z0hydro = coef_z0_coupl * sand diameter •z0_hydro_mud: if l_z0hydro_coupl is true, z0hydro if pure mud (m) •z0_hydro_bed: if l_z0hydro_coupl is true, z0hydro if no sediment (m) &namsedim_deposition: •cfreshmud: prescribed fresh deposit concentration in kg/m3 (must be around 100 if consolidation or higher (300-500 if no consolidation) •csedmin: concentration of the upper layer under which there is fusion with the underlying sediment cell (in kg/m3) •cmudcr: critical relative concentration of the surface layer above which no mixing is allowed with the underlying sediment (in kg/m3) •aref_sand: reference height above sediment in meter. Used for computing of sand deposit for sand extrapolation on water column and correct sand transport, value by default = 0.02 correspond to Van Rijn experiments. DO NOT CHANGED IF NOT EXPERT. ( see Treatment of high settling velocities: SAND variables) •cvolmaxsort: maximum volumic concentration of sorted sand •cvolmaxmel: maximum volumic concentration of mixed sediments •slopefac: slope effect multiplicative on sliding part of deposit (only if key_MUSTANG_slipdeposit see sliding fluxes) &namsedim_erosion: •activlayer: active layer thickness (m) •frmudcr2: critical mud fraction under which the behaviour is purely sandy •coef_frmudcr1: such that critical mud fraction under which sandy behaviour (frmudcr1=min(coef_frmudcr1*d50 sand,frmudcr2)) •x1toce_mud: mud erosion parameter: toce = x1_toce_mud*(relative mud concentration)**x2_toce_mud •x2toce_mud: mud erosion parameter: toce = x1_toce_mud*(relative mud concentration)**x2_toce_mud •E0_sand_option: choice of formulation for E0_sand evaluation: –0: E0_sand = E0_sand_Cst read in this namelist –1: E0_sand evaluated with Van Rijn [1984] formulation –2: E0_sand evaluated with erodimetry (min(0.27,1000*d50-0.01)*toce**n_eros_sand) –3: E0_sand evaluated with Wu and Lin [2014] formulation •E0_sand_Cst: constant erosion flux for sand (used if E0_sand_option= 0) •E0_sand_para: coefficient used to modulate erosion flux for sand (=1 if no correction ) •n_eros_sand: parameter for erosion flux for sand (E0_sand*(tenfo/toce-1.)**n_eros_sand ). WARNING: choose parameters compatible with E0_sand_option (example: n_eros_sand=1.6 for E0_sand_option=1) •E0_mud: parameters for erosion flux for pure mud •E0_mud_para_indep: parameter to correct E0_mud in case of erosion class by class in non cohesive regime (key_MUSTANG_V2 only) •n_eros_mud: E0_mud*(tenfo/toce-1.)**n_eros_mud •ero_option: choice of erosion formulation for mixing sand-mud. These formulations are debatable and must be considered carefully by the user. Other laws are possible and could be programmed. –0: pure mud behavior (for all particles and whatever the mixture) –1: linear interpolation between sand and mud behavior, depend on proportions of the mixture –2: formulation derived from that of J. Vareilles (2013) 1.13. Other modules : sediment models, flow-obstruction models, biology models 79 Croco Documentation, Release 2.1.2 –3: formulations proposed by Mengual et al. [2017] with exponential coefficients depend on proportions of the mixture •l_xexp_ero_cst: set to .true. if xexp_ero estimated from empirical formulation, depending on frmudcr1 (key_MUSTANG_V2 only) •xexp_ero: used only if ero_option=3: adjustment on exponential variation (more brutal when xexp_ero high) •tau_cri_option: ichoice of critical stress formulation –0: Shields –1: Wu and Lin [2014] •tau_cri_mud_option_eroindep: choice of mud critical stress formulation –0: x1toce_mud*cmudr**x2toce_mud –1: toce_meansan if somsan>eps (else->case0) –2: minval(toce_sand*cvsed/cvsed+eps) if >0 (else->case0) –3: min( case 0; toce(isand2) ) (key_MUSTANG_V2 only) •l_eroindep_noncoh: –set to .true. in order to activate independant erosion for the different sediment classes sands and muds –set to .false. to have the mixture mud/sand eroded as in version V1 (key_MUSTANG_V2 only) •l_eroindep_mud: –set to .true. if mud erosion independant for sands erosion –set to .false. if mud erosion proportionnal to total sand erosion (key_MUSTANG_V2 only) •l_peph_suspension: set to .true. if hindering / exposure processes in critical shear stress estimate for suspension (key_MUSTANG_V2 only) &namsedim_poro: •poro_option: choice of porosity formulation –1: Wu and Li [2017] (incompatible with consolidation)) –2: mix ideal coarse/fine packing •poro_min: minimum porosity below which consolidation is stopped •Awooster: parameter of the formulation of Wooster et al. [2008] for estimating porosity associated to the non-cohesive sediment see Cui et al. [1996] ; ref value = 0.42 •Bwooster: parameter of the formulation of Wooster et al. [2008] for estimating porosity associated to the non-cohesive sediment see Cui et al. [1996] ; ref value = -0,458 •Bmax_wu: maximum portion of the coarse sediment class participating in filling; ref value = 0.65 &namsedim_bedload: (key_MUSTANG_V2 only) •l_peph_bedload: set to .true. if hindering / exposure processes in critical shear stress estimate for bedload •l_slope_effect_bedload: set to .true. if accounting for slope effects in bedload fluxes (Lesser formulation) •alphabs: coefficient for slope effects (default coefficients Lesser et al. [2004], alphabs = 1.) •alphabn: coefficient for slope effects (default coefficients Lesser et al. [2004], default alphabn is 1.5 but can be higher, until 5-10 (Gerald Herling experience)) •hmin_bedload: no bedload in u/v directions if h0+ssh <= hmin_bedload in neighbouring cells •l_fsusp: limitation erosion fluxes of non-coh sediment in case of simultaneous bedload transport, according to Wu & Lin formulations. Set to .true. if erosion flux is fitted to total transport should be set to .false. if E0_sand_option=3 (Wu & Lin) &namsedim_lateral_erosion: (see Lateral erosion) 80 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 •coef_erolat: slope effect multiplicative factor •coef_tauskin_lat: parameter to evaluate the lateral stress as a function of the average tangential velocity on the vertical •l_erolat_wet_cell: set to .true in order to take into account wet cells lateral erosion •htncrit_eros: critical water height so as to prevent erosion under a given threshold (the threshold value is different for flooding or ebbing, cf. Hibma’s PhD, 2004, page 78) &namsedim_consolidation: •l_consolid: set to .true. if sediment consolidation is accounted for •dt_consolid: time step for consolidation processes in sediment (will use in fact the min between dt_consolid, dt_diffused if l_diffused, dt_bioturb if l_bioturb) •subdt_consol: sub time step for consolidation processes in sediment (< or = min(dt_consolid, ..))(will use in fact the min between subdt_consolid, subdt_bioturb if l_bioturb) •csegreg: DO NOT CHANGE VALUE if not expert, default 250.0 •csandseg: DO NOT CHANGE VALUE if not expert, default 1250.0 •xperm1: parameter to compute permeability permeability=xperm1*d50*d50*voidratio**xperm2 •xperm2: parameter to compute permeability permeability=xperm1*d50*d50*voidratio**xperm2 •xsigma1: parameter used in Merckelbach and Kranenburg [2004] formulation. DO NOT CHANGE VALUE if not expert, default 6.0e+05 •xsigma2: real, parameter used in Merckelbach and Kranenburg [2004] formulation. DO NOT CHANGE VALUE if not expert, default 6 &namsedim_diffusion: •l_diffused: set to .true. if taking into account dissolved diffusion in sediment and at the water/sediment interface •dt_diffused: time step for diffusion processes in sediment (will use in fact the min between dt_diffused, dt_consolid if l_consolid, dt_bioturb if l_bioturb) •choice_flxdiss_diffsed: choice for expression of dissolved fluxes at sediment-water interface –1: Fick law: gradient between Cv_wat at dz(1)/2 –2: Fick law: gradient between Cv_wat at distance epdifi •xdifs1: diffusion coefficients within the sediment •xdifsi1: diffusion coefficients at the water sediment interface •epdifi: diffusion thickness in the water at the sediment-water interface •fexcs: factor of eccentricity of concentrations in vertical fluxes evaluation (.5 a 1) (numerical scheme for dissolved diffusion/advection(by consol) in sediment) &namsedim_bioturb: •l_bioturb: set to .true. if taking into account particulate bioturbation (diffusive mixing) in sediment •l_biodiffs: set to .true. if taking into account dissolved bioturbation diffusion in sediment •dt_bioturb: time step for bioturbation processes in sediment (will use in fact the min between dt_bioturb, dt_consolid if l_consolid, dt_diffused if l_diffused) •subdt_bioturb: sub time step for bioturbation processes in sediment (< or = min(dt_bioturb, ..)) (will use in fact the min between subdt_bioturb, subdt_consolid if l_consolid) •xbioturbmax_part: max particular bioturbation coefficient by bioturbation Db (in surface) •xbioturbk_part: coef (slope) for part. bioturbation coefficient between max Db at sediment surface and 0 at bottom 1.13. Other modules : sediment models, flow-obstruction models, biology models 81 Croco Documentation, Release 2.1.2 •dbiotu0_part: max depth beneath the sediment surface below which there is no bioturbation •dbiotum_part: sediment thickness where the part-bioturbation coefficient Db is constant (max) •xbioturbmax_diss: max diffusion coeffient by biodiffusion Db (in surface) •xbioturbk_diss: coef (slope) for biodiffusion coefficient between max Db at sediment surface and 0 at bottom •dbiotu0_diss: max depth beneath the sediment surface below which there is no bioturbation •dbiotum_diss: sediment thickness where the diffsolved-bioturbation coefficient Db is constant (max) •frmud_db_min: mud fraction limit (min) below which there is no Biodiffusion •frmud_db_max: mud fraction limit (max)above which the biodiffusion coefficient Db is maximum (muddy sediment) &namsedim_morpho: •l_morphocoupl: set to .true if coupling module morphodynamic, see Morphodynamic •MF: morphological factor: multiplication factor for morphological evolutions, equivalent to a “time acceleration” (morphological evolutions over a MF*T duration are assumed to be equal to MF * the morphological evolutions over T). •dt_morpho: time step for morphodynamic (s) •l_MF_dhsed: –set to .true. if morphodynamic applied with sediment height variation amplification –set to .false. if morphodynamic is applied with erosion/deposit fluxes amplification &namtempsed: (only if !defined key_noTSdiss_insed) •mu_tempsed1: parameters used to estimate thermic diffusitiy function of mud fraction •mu_tempsed2: parameters used to estimate thermic diffusitiy function of mud fraction •mu_tempsed3: parameters used to estimate thermic diffusitiy function of mud fraction •epsedmin_tempsed: sediment thickness limits for estimation heat loss at bottom, if hsed < epsedmin_tempsed: heat loss at sediment bottom = heat flux a sediment surface •epsedmax_tempsed: sediment thickness limits for estimation heat loss at bottom, if hsed > epsedmax_tempsed: heat loss at sediment bottom = 0. &namsedoutput: •l_outsed_nb_lay_sed: boolean, set to true to output the number of sediment layers (upper sediment layer index named ksma) •l_outsed_hsed: boolean, set to true to output sediment height (m) •l_outsed_dzs: boolean, set to true to output sediment layer thickness (m) •l_outsed_temp_sed: boolean, set to true to output temperature in sediment layers •l_outsed_salt_sed: boolean, set to true to output salinity in sediment layers •l_outsed_cv_sed: boolean, set to true to output concentration of sediment class (kg/m3). Note that if in substance namelist l_out_subs_n boolean of the class is set to false, the corresponding variable is not outputed •l_outsed_ws: boolean, set to true to output settling welocity of sediment class (m/s). Note that it is not outputed for gravels, sands andif l_out_subs_n boolean of the class is set to false in substance namelist •l_outsed_z0sed: boolean, set to true to output skin roughness length (m) •l_outsed_z0hydro: boolean, set to true to output hydrodynamic roughness length (m) •l_outsed_tauskin: boolean, set to true to output total bottom shear stress (N/m2) 82 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 •l_outsed_tauskin_cw: boolean, set to true to output current bottom shear stress and wave bottom shear stress (N/m2) •l_outsed_poro: boolean, set to true to output porosity of sediment layers •l_outsed_toce: boolean, set to true to output critical shear stress for each sediment class. Note that if in substance namelist l_out_subs_n boolean of the class is set to false, the corresponding variable is not outputed •l_outsed_flx_s2w_w2s: boolean, set to true to output erosion fluxes and deposition fluxes (kg/m-2) •l_outsed_frmudsup: boolean, set to true to output mud fraction in the interface sediment/water layer •l_outsed_dzs_ksmax: boolean, set to true to output the interface sediment/water layer thickness (m) •l_outsed_pephm_fcor: boolean, set to true to output the hindering exposure factor on critical shear stress for each class •l_outsed_theoric_active_layer: boolean, set to true to output theoretical active layer thickness according Harris and Wiberg 1997 •l_outsed_ero_details: boolean, set to true to output time elapsed in the cohesive/non-cohesive erosion regime and part of erosion iterations in each regime •l_outsed_bedload: boolean, set to true to output beadload components on x and y axis (kg/m/s) and divergence of bedload fluxes •l_outsed_fsusp: boolean, set to true to output the fraction of transport in suspension •l_outsed_consolidation: boolean, set to true to output consolidation variables •choice_nivsed_out: choice of saving output –1: all the layers (ksdmin to ksdmax) are saved (k=1: bottom layer) (nk_nivsed_out, ep_nivsed_out, epmax_nivsed_out are not used) –2: only save the nk_nivsed_out surficial layers (k=1: layer most bottom) –3: each layers from sediment surface are saved till the thickness epmax_nivsed_out (which must be non zero and > dzsmax (k=1: bottom layer) ) This option is not recommended if l_dzsmaxuni=.False. –4: 1 to 5 layers of constant thickness are saved; thickness are selected with ep_nivsed_out and concentrations are interpolated to describe the sediment thickness (k=1: surface layer) the thickness of the bottom layer (nk_nivsed_out+1) will vary depending on the total thickness of sediment in the cell •nk_nivsed_out: number of saved sediment layers –unused if choice_nivsed_out = 1 –<ksdmax if choice_nivsed_out = 2, –unused if choice_nivsed_out = 3 –<6 if choice_nivsed_out = 4, •ep_nivsed_out(): 5 values of sediment layer thickness (mm), beginning with surface layer (used if choice_nivsed_out=4) •epmax_nivsed_out: maximum thickness (mm) for output each layers of sediment (used if choice_nivsed_out=3). Below the layer which bottom level exceed this thickness, an addition layer is an integrative layer till bottom &namsedim_debug: •l_debug_effdep: set to .true. if print some informations for debugging MUSTANG deposition •l_debug_erosion: set to .true. if print informations for debugging in erosion routines •date_start_debug: string, starting date for write debugging informations •lon_debug: define mesh location where we print these informations •lat_debug: define mesh location where we print these informations 1.13. Other modules : sediment models, flow-obstruction models, biology models 83 Croco Documentation, Release 2.1.2 (continued from previous page) ˓→ref="b_3D"/> <field id="temp_sed" long_name="Temperature in the seabed" unit="Celsius" grid_ref="b_ ˓→3D"/> <field id="salt_sed" long_name="Salinity in the seabed" unit="PSU" grid_ref="b_3D"/> <field id="dzs" long_name="Sediment layer thickness" unit="m" grid_ref="b_3D"/> <field id="z0sed" long_name="Skin roughness length" unit="m"/> <field id="z0hydro" long_name="Hydrodynamic roughness length" unit="m"/> <field id="tauskin" long_name="Total bottom shear stress" unit="N meter-2"/> <field id="tauskin_c" long_name="Current-induced bottom shear stress" unit="N meter-2 ˓→"/> <field id="tauskin_w" long_name="Wave-induced bottom shear stress" unit="N meter-2"/> <field id="hsed" long_name="Bottom thickness" unit="m"/> <field id="ksma" long_name="Upper sediment layer index" unit="no unit"/> Other fields are available depending on namsedoutput namelist and activation of cppkeys #key_MUSTANG_V2, #key_MUSTANG_bedload : •settling velocities for sediment of type MUD if l_outsed_ws is set to True : <field id="MUD_ws" long_name="Settling velocity" unit="m/s" grid_ref="rho_3D" /> •critical shear stress if l_outsed_toce is set to True : <field id="MUD_toce" long_name="critical shear stress" unit="N/m2"/> •erosion and deposition fluxes if l_outsed_flx_s2w_w2s is set to True : <field id="MUD_flx_s2w" long_name="erosion flux" unit="kg.m-2"/> <field id="MUD_flx_w2s" long_name="deposition flux" unit="kg.m-2"/> <field id="flx_s2w_noncoh" long_name="erosion flux of non-cohesive sediments␣ ˓→(sum: isand1 to isand2)" unit="kg.m-2"/> <field id="flx_w2s_noncoh" long_name="deposition flux of non-cohesive sediments␣ ˓→(sum: isand1 to isand2)" unit="kg.m-2"/> <field id="flx_s2w_coh" long_name="erosion flux of cohesive sediments (sum:␣ ˓→imud1 to imud2)" unit="kg.m-2"/> <field id="flx_w2s_coh" long_name="deposition flux of cohesive sediments (sum:␣ ˓→imud1 to imud2)" unit="kg.m-2"/> •mud fraction in the upper sediment layer if l_outsed_frmudsup is set to True : <field id="frmudsup" long_name="mud fraction in the ksmax layer" unit="no unit"/> •layer thickness in the upper sediment layer if l_outsed_dzs_ksmax is set to True : <field id="dzs_ksmax" long_name="layer thickness at sediment surface" unit="m"/> •if #key_MUSTANG_V2: –if l_outsed_pephm_fcor is set to True : <field id="SAND_pephm_fcor" long_name="Hindering exposure factor on toce"␣ ˓→unit="no unit"/> –if l_outsed_theoric_active_layer is set to True : <field id="theoric_active_layer" long_name="Theoretical active layer␣ ˓→thickness Harris and Wiberg 1997" unit="m"/> –if l_outsed_ero_details is set to True : 90 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 <field id="tero_noncoh" long_name="time elapsed in the non-cohesive erosion␣ ˓→regime" unit="h"/> <field id="tero_coh" long_name="time elapsed in the cohesive erosion regime"␣ ˓→unit="h"/> <field id="pct_iter_noncoh" long_name="part of erosion iterations in the non- ˓→cohesive regime" unit="percent"/> <field id="pct_iter_coh" long_name="part of erosion iterations in the␣ ˓→cohesive regime" unit="percent"/> <field id="niter_ero" long_name="number of iterations in sed_erosion during␣ ˓→time step" unit="no unit"/> •if #key_MUSTANG_V2 and #key_MUSTANG_bedload and l_outsed_bedload : <field id="SAND_flx_bx" long_name="Bedload flux along x-axis" unit="kg/m/s"/> <field id="SAND_flx_by" long_name="Bedload flux along y-axis" unit="kg/m/s"/> <field id="SAND_bil_bedload" long_name="Divergence of bedload flux" unit="kg.m-2 ˓→"/> <field id="SAND_fsusp" long_name="fraction of transport in suspension" unit="no␣ ˓→unit"/> <field id="flx_bx_int" long_name="Total bedload flux along x-axis" unit="kg/m/s"/ ˓→> <field id="flx_by_int" long_name="Total bedload flux along y-axis" unit="kg/m/s"/ ˓→> <field id="bil_bedload_int" long_name="Divergence of total bedload flux" unit= ˓→"kg.m-2"/> •if l_outsed_consolidation and l_dyn_insed : <field id="loadograv" long_name="excess of interstitial water pressure in the␣ ˓→middle of the layer" unit="-" grid_ref="b_3D"/> <field id="sigmadjge" long_name="sigma unseparated (without the share of water)"␣ ˓→unit="-" grid_ref="b_3D"/> <field id="sigmapsg" long_name="effective stress (transmitted from grain to␣ ˓→grain)" unit="-"grid_ref="b_3D"/> <field id="stateconsol" long_name="state of consolidation indicator" unit="-"␣ ˓→grid_ref="b_3D"/> <field id="permeab" long_name="permeability" unit="-" grid_ref="b_3D"/> <field id="hinder" long_name="shackling sand / gravel between 0 and 1'"unit="-"␣ ˓→grid_ref="b_3D"/> <field id="sed_rate" long_name="advection speed of mud particles" unit="-" grid_ ˓→ref="b_3D"/> <field id="dtsdzs" long_name="dtsdzs" unit="-" grid_ref="b_3D"/> 1.13.2.2.2.12 Available CPP keys The compulsory CPP keys to use MUSTANG in CROCO: •MUSTANG: activate module MUSTANG •SUBSTANCE: activate module SUBSTANCE •SALINITY: needed for SUBSTANCE •TEMPERATURE: needed for SUBSTANCE •USE_CALENDAR: needed for MUSTANG, issue with MUSTANG coupling timing otherwise •key_noTSdiss_insed: temperature, salinity and others dissolved variables are not computed in sediment. They have constant values and no fluxes of dissolved variables between water and sediment are computed. 1.13. Other modules : sediment models, flow-obstruction models, biology models 91 Croco Documentation, Release 2.1.2 •key_nofluxwat_IWS: no exchange water fluxes between water and sediment (recommended if key_noTSdiss_insed). The optional CPP keys, to choose processes or version: •key_MUSTANG_V2: to use MUSTANG in V2, without this key, the version V1 is used •MORPHODYN: to activate morphodynamic (l_morphocoupl must also be set to .true, see Morphodynamic) •SED_DENS: to activate the effect of suspended sediment on the density, see Effect on density •key_sand2D: to treat SAND in suspension as 2D variable, see Treatment of high settling velocities: SAND variables •MUSTANG_CORFLUX: to correct SAND horizontal fluxes, see Treatment of high settling velocities: SAND variables •WAVE_OFFLINE: to use wave in bed shear stress computation, see wave skin friction •key_MUSTANG_flocmod: to activate module floculation (FLOCMOD) •SUBSTANCE_SUBMASSBALANCE: to activate submassbalance computing (SUBMASSBALANCE) •key_tauskin_c_upwind: Upwind scheme for current-induced bottom shear stress, see Shear stress •key_tauskin_c_center: Compute bottom shear stress with 𝑢*directly at (rho) location (center of the cell), see Shear stress •key_tauskin_c_ubar: Shear stress computed form depth-averaged velocity, see Shear stress •PSOURCE_NCFILE and PSOURCE_NCFILE_TS: to read solid discharge in river from netcdf files •key_MUSTANG_slipdeposit: see Sliding fluxes •key_MUSTANG_lateralerosion: see Lateral erosion •key_MUSTANG_splitlayersurf : cutting of surface sediment layers to have regular and precise discretization at surface •key_MUSTANG_bedload: only with key_MUSTANG_V2, bedload processus included •key_MUSTANG_debug: only with key_MUSTANG_V2, choice print information during erosion or deposit process. Does not work in MPI print a lot of variable during run for debugging choice of coordinates of the point to be checked 1.13.2.2.3 MUSTANG technical documentation 1.13.2.2.3.1 Overall architecture of the module To compute sediment behavior, MUSTANG execute the steps : •Initialization of sediment variables from input files •Temporal loop with a sequence of forcing update, erosion phase, exchange between sediment and water, deposition phase, morphodynamic update and call to output feature MUSTANG module is integrated into CROCO code. It is composed of elements added to the existing code in a MUSTANG directory. The interface between the sedimentary module and the hydrodynamic code is done via : •plug_MUSTANG_CROCO.F90 which makes the 4 main subroutines available to the rest of the code : –mustang_init_main: initialization –mustang_update_main: update of forcing and erosion phase –mustang_deposition_main: deposition phase –mustang_morpho_main: to apply morphodynamic •modification of CROCO files : 92 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 –Initialization in main.F –Main calls in step.F –Treatment of settling and sediment/water exchanges in step3d_t.F –Input features in read_inp.F –Output features in: XIOS/send_xios_diags.F, OCEAN/wrt_his.F, OCEAN/wrt_rst.F, OCEAN/wrt_sta.F, OCEAN/nc_sta.h, OCEAN/ncscrum.h, OCEAN/nf_read.h, OCEAN/fillvalue.F, step_sta.F, sta.h –Wave forcing in OCEAN directory in files: forces.h, get_vbc.F, get_wwave.F, init_arrays.F, init_scalars.F –Test cases in OCEAN/ana_grid.F and OCEAN/ana_initial.F –Compilation and dimension in OCEAN directory in files: Makefile, jobcomp, param.h, cppdefs.h, cppdefs_dev.h Roughly, all sediment calculations are done in the MUSTANG fortran files, except for the advection part which is intimately linked to step3d_t.F. Modifications in CROCO files are mostly for I/O features or test cases analytical forcing. 1.13.2.2.3.2 Initialization The initialization must be done for water column variables and sediment bed variables. In the water column, the initialization is done from initial file if provided (see hydrodynamic code). If there is no initial file, the water concentrations are initialized from uniform value in SUBSTANCE namelist. To initialize the sediment cover, two options are available : •Uniform sediment cover In paraMUSTANG*.txt: l_unised = .true. ! boolean set to true for a uniform bottom initialization hseduni = 0.03 ! initial uniform sediment thickness(m) cseduni= 1500.0 ! initial sediment concentration csed_mud_ini = 550.0 ! mud concentration into initial sediment (if = 0. ==>␣ ˓→csed_mud_ini = cfreshmud) ksmiuni = 1 ! lower grid cell indices in the sediment ksmauni = 10 ! upper grid cell indices in the sediment And then, the fraction of each sediment variable in the seafloor is defined with cini_sed_n() in parasubsance_MUSTANG.txt •Read the sediment cover from a netcdf file (format of a RESTART file, see input file for sediment cover) .Warning •The restarts are not perfect restarts. To do a perfect restart, you will need to save the erosion and deposition fluxes in a restart file, as was done in MARS3D (cf. subroutine sed_outsaverestart in sed_MUSTANG_CROCO.F90). This has not been implemented yet. 1.13.2.2.3.3 Temporal loop In the temporal loop of CROCO model, the main calls to MUSTANG routines are in step3D_t_thread. call prestep3D_thread() call step2d_thread() call step3D_uv_thread() (continues on next page) 1.13. Other modules : sediment models, flow-obstruction models, biology models 93 Croco Documentation, Release 2.1.2 (continued from previous page) call step3D_t_thread() ----> call mustang_update_main() ----> call step3d_t -----------------> # include "t3dmix_tridiagonal_settling.h" ----> CALL mustang_deposition_main ----> CALL mustang_morpho_main The erosion and deposition phases are sequenced at each time step: •erosive phase is treated before the call to step3d_t (treatment of vertical advection). This phase contains: –calculation of the roughness and bottom shear stress, –calculation of the erosion fluxes for each class –evolution of the sedimentary bed from erosion: erosion layer managment –calculation of the tendency to deposition deposit fluxes. •exchanges from the water column point of view are processed in step3d_t via “t3dmix_tridiagonal_settling.h” and compute also the effective deposit fluxes •deposit step is processed after the call to step3d_t. This phase includes –calculation of the deposit for each class, –evolution of the sedimentary bed: deposition layer managment •morphodynamic coupling. The calculations are carried out cell by cell by considering most of the sedimentary variables at the center of the cell. The majority of the calculations are therefore carried out in 1DV. Certain calculations must however be carried out taking into account the adjacent meshes: •calculate skin stress has current are computed on the mesh edges •calculate the slope of the bottom and the coefficients necessary to take into account its effect on transport by bedload •calculate the correction of horizontal sand fluxes •calculate the fluxes entering a cell induced by bedload and suspension transport TODO: add a scheme to explain the two main phases: erosion/deposit 1.13.2.2.3.4 Roughness length Mustang use grain roughness length to evaluate moving conditions of particles. Mustang can also compute a form roughness length to account of ripple effect on flow and transmit it to the hydrodynamic code (here CROCO) The grain roughness length could be : •constant in time and uniform in space with l_z0seduni = .TRUE., in this case, the skin roughness length is equal to z0seduni namelist value (see namelist namsedim_bottomstress) •variable in time and space with l_z0seduni = .FALSE., in this case, the skin roughness length is computed at each time step from sediment bed composition in each cell (i,j) : –if bathymetry is not defined in the cell: z0sed = z0sedmud (see z0sedmud in namsedim_bottomstress) (to avoid division by zero in skinstress evaluation when neighbour cells are used) –if bathymetry is defined in the cell: ∗if sediment is not present, then z0sed = z0sedbedrock (see z0sedbedrock in namsedim_bottomstress) ∗if sediment is present, 94 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 ·if there is only mud in the superficial layer z0sed = z0seduni ·if there is sand or gravel, Nikuradse formulation is used (z0sed = diam/12) with diam corresponding to the ponderate sum of gravel and sand diameter 𝑑𝑖𝑎𝑚 =∑︀𝑖𝑠𝑎𝑛𝑑2 𝑛=𝑖𝑔𝑟𝑎𝑣1𝑐𝑣𝑠𝑒𝑑(𝑛, 𝑘𝑚𝑎𝑥)/𝑐𝑠𝑒𝑑𝑡𝑜𝑡(𝑛, 𝑘𝑚𝑎𝑥)*𝑑𝑖𝑎𝑚𝑒𝑡𝑒𝑟(𝑛) The form roughness length is computed and sent to CROCO only if l_z0hydro_coupl (at each time step) or l_z0hydro_coupl_init (just at initialization) : •if there is no sediment, z0hydro = z0_hydro_bed (see z0_hydro_bed in namsedim_bottomstress) •if there is sediment : –if there is more than 30% of mud in the first centimeter of sediment, z0hydro = z0_hydro_mud (see z0_hydro_mud in namsedim_bottomstress) –else the ponderate diameter of sand is used and z0hydro = coef_z0_coupl * ponderate diameter of sand (see coef_z0_coupl in namsedim_bottomstress). Note that gravel are not taking into account here 1.13.2.2.3.5 Shear stress The shear stress skin friction is computed following steps : •compute current skin friction •if cpp keys WAVE_OFFLINE is activated, compute wave skin friction •if cpp keys WAVE_OFFLINE is activated, compute combination between current and wave skin friction Current skin friction Current skin friction is computed from the friction velocity using a logarithmic profile. The friction velocity 𝑢* is computed from roughness length z0 and current component (bottom (u,v) or barotropic (ubar,vbar) using a logarithmic profile : 𝑢*=𝜅·√𝑢2+𝑣2 𝑙𝑛(𝑧 𝑧0)with 𝑧, height of the bottom cell. 1.13. Other modules : sediment models, flow-obstruction models, biology models 95 Croco Documentation, Release 2.1.2 or 𝑢*=𝜅·√𝑢𝑏𝑎𝑟2+𝑣𝑏𝑎𝑟2 𝑙𝑛(𝑧 𝑒·𝑧0)with 𝑧, the water height. Current skin friction is compute using : 𝑡𝑎𝑢𝑠𝑘𝑖𝑛_𝑐𝑢𝑟𝑟𝑒𝑛𝑡 =𝜌𝑤·(𝑢*)2 The following option are available via cpp keys : •default: compute 𝑢*components at (u,v) locations first and then at the center of the cell. This option use 12 points of current components (see figure below). •key_tauskin_c_center: compute 𝑢*directly at (rho) location (center of the cell) using immediate u,v components. This option use 4 points of current components (see figure below). •key_tauskin_c_ubar: compute 𝑢*using ubar,vbar value instead of bottom layer u,v values. •key_tauskin_c_upwind: depending on current direction, use only component upwind (not combinable with key_tauskin_c_center). This option use 8 to 12 points of current components (see figure below). •BBL: computation is done via BBL module of CROCO using constant roughness (from 160 microns diameter). This option is not recommended with MUSTANG due to constant roughness. Wave skin friction Wave skin friction is computed using Soulsby (1997) formula. 𝑡𝑎𝑢𝑠𝑘𝑖𝑛_𝑤𝑎𝑣𝑒 =1 2·𝜌𝑤·𝑓𝑤·𝑈𝑤𝑎𝑣𝑒2 With 96 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 •𝑓𝑤equal to fricwav namelist namsedim_bottomstress value or computed from WAVE_OFFLINE file variables (𝑈𝑤𝑎𝑣𝑒 and 𝑃 𝑤𝑎𝑣𝑒) and roughness if l_fricwave namelist namsedim_bottomstress value is True using 𝑓𝑤= 1.39 ·(𝑈𝑤𝑎𝑣𝑒·𝑃 𝑤𝑎𝑣𝑒 2·𝜋·𝑧0𝑠𝑒𝑑 )−0.52 •𝑈𝑤𝑎𝑣𝑒 and 𝑃 𝑤𝑎𝑣𝑒 reading from WAVE_OFFLINE file Combinaison of current and wave stresses Combinaison of current and wave stresses is done from Soulsby [1997] (Dynamics of marine sands - eq.69 and 70 page 92), 𝑡𝑎𝑢𝑠𝑘𝑖𝑛 equal to 𝑡𝑎𝑢_𝑚𝑎𝑥 𝑡𝑎𝑢_𝑚𝑒𝑎𝑛 =𝑡𝑎𝑢𝑠𝑘𝑖𝑛_𝑐𝑢𝑟𝑟𝑒𝑛𝑡 ·(︂1+1.2·(︁𝑡𝑎𝑢𝑠𝑘𝑖𝑛_𝑤𝑎𝑣𝑒 𝑡𝑎𝑢𝑠𝑘𝑖𝑛_𝑐𝑢𝑟𝑟𝑒𝑛𝑡+𝑡𝑎𝑢𝑠𝑘𝑖𝑛_𝑤𝑎𝑣𝑒 )︁3.2)︂ 𝑡𝑎𝑢_𝑚𝑎𝑥 =√︁(𝑡𝑎𝑢_𝑚𝑒𝑎𝑛 +𝑡𝑎𝑢𝑠𝑘𝑖𝑛_𝑤𝑎𝑣𝑒 ·|𝑐𝑜𝑠(𝑝ℎ𝑖)|)2+ (𝑡𝑎𝑢𝑠𝑘𝑖𝑛_𝑤𝑎𝑣𝑒 ·|𝑠𝑖𝑛(𝑝ℎ𝑖)|)2 With 𝑝ℎ𝑖 angle between current and wave. òNote abs() is used on cos() and sin() because of alternative direction of tau_w in the vector addition of tau_c and tau_w (see Soulsby [1997] (Dynamics of marine sands - figure 16 page 89)) 1.13.2.2.3.6 Settling The settling process is taken into account during the advection-diffusion scheme in the water column and in the exchange from water to sediment via the deposit fluxes. Settling velocity modelling strategy The settling velocity is the main variable of the settling process and is moddelled differently for each substance type : •GRAV: gravels are not transported in suspension, they have no settling velocity because they are not in the water column •SAND: sands have a constant settling velocity directly compute from Soulsby [1997] using their diameters defined in SUBSTANCE namelist &nmlsands (diam_n). 𝑊𝑠 = 10−6·(107.33+1.049·𝐷𝑠𝑡𝑎𝑟3)0.5−10.36 𝐷 With 𝐷𝑠𝑡𝑎𝑟 =𝐷·104·(𝑔·(𝜌𝑠 𝜌𝑤−1))1 3the dimensionless diameter of sediment and Ddiameter of sediment class, 𝜌𝑤water density and 𝜌𝑠sediment density. The resulting settling velocity could be high. 1.13. Other modules : sediment models, flow-obstruction models, biology models 97 Croco Documentation, Release 2.1.2 •MUD and Non Constitutive Particulate subtances: the settling velocity can vary in time and space depending on the parameters chosen by user in SUBSTANCE namelist &nmlmuds: ws_free_opt_n(), ws_free_min_n(), ws_free_max_n(), ws_free_para_n(1:4,num substance), ws_hind_opt_n(), ws_hind_para_n(1:2,num substance) ) or by cpp key for flocculation module (see Flocculation) If flocculation module is not used, settling velocity is the result of the choice on ws_free_opt_n and ws_hind_opt_n values in SUBSTANCE namelist &nmlmuds and is computed for every cell “i,j” and layer “k” in the water domain. 𝑊𝑠 =𝑚𝑎𝑥(𝑤𝑠_𝑓𝑟𝑒𝑒_𝑚𝑖𝑛_𝑛;𝑚𝑖𝑛(𝑤𝑠_𝑓𝑟𝑒𝑒_𝑚𝑎𝑥_𝑛;𝑊 𝑠𝑓𝑟𝑒𝑒 ·𝐻𝑖𝑛𝑑)) See appropriate chapters for details on free settling velocity and hindered settling parameter. •Sorbed substances: the settling velocity of sorbed substance is the same as the particulate susbtance to which it is associated •Dissolved and fixed substances: no settling velocity Free settling velocity 𝑊𝑠𝑓𝑟𝑒𝑒 the free settling velocity is computed from : •if ws_free_opt_n = 0: constant value, 𝑊𝑠𝑓𝑟𝑒𝑒 =𝑤𝑠_𝑓𝑟𝑒𝑒_𝑚𝑖𝑛_𝑛 •if ws_free_opt_n = 1: formulation of van Leussen [1994], 𝑊 𝑠𝑓𝑟𝑒𝑒 =𝑘𝐶𝑚·1+𝑎𝐺 1+𝑏𝐺2 With : –𝑘=𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(1) (= 0.0005 in the reference) –𝑚=𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(2) (= 1.2 in the reference) –𝑎=𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(3) (= 0.3 in the reference) –𝑏=𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(4) (= 0.09 in the reference) –𝐶= Sum of concentration of MUD substances in the layer –𝐺=√︁𝑡𝑢𝑟𝑏𝑢𝑙𝑒𝑛𝑐𝑒 𝑑𝑖𝑠𝑠𝑖𝑝𝑎𝑡𝑖𝑜𝑛 𝑟𝑎𝑡𝑒 𝑣𝑒𝑟𝑡𝑖𝑐𝑎𝑙 𝑣𝑖𝑠𝑐𝑜𝑠𝑖𝑡𝑦 𝑐𝑜𝑒𝑓𝑓𝑖𝑐𝑖𝑒𝑛𝑡 = turbulence energy 98 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 •if ws_free_opt_n = 2: formulation of Winterwerp [1999], 𝑊𝑠𝑓𝑟𝑒𝑒 =1 18 ·(𝜌𝑠−𝜌𝑤)𝑔 𝜌𝑤𝜈·𝐷𝑝3−𝑛𝑓 ·𝐷𝑒𝑛𝑓−1 With : –𝐷𝑒 =𝑚𝑎𝑥(𝐷𝑝 +𝑘𝑎·𝐶 𝑘𝑏·√𝐺;√︀𝜈 𝐺) –𝐷𝑝 =𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(1) = Primary Particle Diameter, (= 4.10-6 in the reference) –𝑘𝑎 =𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(2) = aggregation factor, (= 14.6 in the reference) –𝑘𝑏 =𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(3) = breakup factor, (= 30000 in the reference) –𝑛𝑓 =𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(4) = fractal dimension, (= 2 in the reference) –𝐶= Sum of concentration of MUD substances in the layer –𝐺=√︁𝑡𝑢𝑟𝑏𝑢𝑙𝑒𝑛𝑐𝑒 𝑑𝑖𝑠𝑠𝑖𝑝𝑎𝑡𝑖𝑜𝑛 𝑟𝑎𝑡𝑒 𝑣𝑒𝑟𝑡𝑖𝑐𝑎𝑙 𝑣𝑖𝑠𝑐𝑜𝑠𝑖𝑡𝑦 𝑐𝑜𝑒𝑓𝑓𝑖𝑐𝑖𝑒𝑛𝑡 = turbulence energy –𝜈= 0.00000102 𝑚2/𝑠 = water kinematic viscosity –𝑔= gravity –𝜌𝑠= sediment density –𝜌𝑤= water density •if ws_free_opt_n = 3: formulation of Wolanski et al. [1989], 𝑊𝑠𝑓𝑟𝑒𝑒 =𝑘𝐶𝑚 With : –𝑘=𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(1) (= 0.01 in the reference) –𝑚=𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(2) (= 2.1 in the reference) –𝐶= Sum of concentration of MUD substances in the layer Hindered settling parameter 𝐻𝑖𝑛𝑑 the hindered settling parameter is computed from : •if ws_hind_opt_n = 0: no hindered effect, 𝐻𝑖𝑛𝑑 = 1 •if ws_hind_opt_n = 1: formulation of Scott, 1984, 𝐻𝑖𝑛𝑑 = (1 −𝜑)𝑚 With : –𝜑=𝑚𝑖𝑛(1 ; 𝐶 𝑐𝑔𝑒𝑙 ) –𝐶= Sum of concentration of MUD substances in the layer –𝑐𝑔𝑒𝑙 =𝑤𝑠_ℎ𝑖𝑛𝑑_𝑝𝑎𝑟𝑎_𝑛(1) (= 40 in the reference) –𝑚=𝑤𝑠_ℎ𝑖𝑛𝑑_𝑝𝑎𝑟𝑎_𝑛(2) (= 4.5 in the reference) •if ws_hind_opt_n = 2: formulation of Winterwerp et al. [2002], 𝐻𝑖𝑛𝑑 = (1 −𝜑𝑣)𝑚·(1−𝜑) (1+2.5𝜑𝑣) With : –𝜑=𝐶 𝜌𝑠 –If ws_free_opt_n is not 2 then 𝜑𝑣=𝐶 𝑐𝑔𝑒𝑙 –If ws_free_opt_n is 2 then 𝜑𝑣=𝜑·(𝐷𝑒 𝐷𝑝 )3−𝑛𝑓 ∗𝐷𝑒 =𝑚𝑎𝑥(𝐷𝑝 +𝑘𝑎·𝐶 𝑘𝑏·√𝐺;√︀𝜈 𝐺) ∗𝐷𝑝 =𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(1) = Primary Particle Diameter, (= 4.10-6 in the reference) ∗𝑛𝑓 =𝑤𝑠_𝑓𝑟𝑒𝑒_𝑝𝑎𝑟𝑎_𝑛(4) = fractal dimension, (= 2 in the reference) –𝑐𝑔𝑒𝑙 =𝑤𝑠_ℎ𝑖𝑛𝑑_𝑝𝑎𝑟𝑎_𝑛(1) (= 40 in the reference) –𝑚=𝑤𝑠_ℎ𝑖𝑛𝑑_𝑝𝑎𝑟𝑎_𝑛(2) (= 1 in the reference) –𝐶= Sum of concentration of MUD substances in the layer 1.13. Other modules : sediment models, flow-obstruction models, biology models 99 Croco Documentation, Release 2.1.2 1.13.2.2.3.18 FLOCMOD execution FLOCMOD can be non-conservative for high shear rates and/or high SPM concentration. To prevent for instabilities, FLOCMOD includes a sub-time step algorithm. After mass exchange due to flocculation, FLOCMOD checks if the new floc size distribution is fully positive or null. If true, execution continues. Otherwise, the time step is divided by two and a new floc size distribution is recalculated. This time-step adaptation is applied as long as floc size distribution contains negative mass. Flocculation is then repeated until reaching a cumulated time step corresponding to the CROCO time step. It is possible to be slightly permissive and allow a small negative mass concentration (f_mneg_param). In this case, the class characterized by negative mass is set to 0 and the “corresponding added mass” is proportionally removed from the positive classes to be mass conservative. This can help to limit time step adaptation, and hence reduce computation costs. It is also possible to disconnect FLOCMOD when SPM concentration is very low. In FLOCMOD, this concentration threshold (in g/l) is defined in f_clim and set by default to 0.001 g/l. 1.13.2.2.3.19 Example Test cases are provided see FLOCMOD cases for more informations. 1.13.2.2.3.20 Erosion process òNote Patience, work in progress, meanwhile see: https://mars3d.ifremer.fr/docs/doc_MUSTANG/doc.MUSTANG. erosion.html Erosion fluxes Lateral erosion key_MUSTANG_lateralerosion òNote Patience, work in progress Erosion, layer managment 106 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 1.13.2.2.3.21 Deposit process òNote Patience, work in progress, meanwhile see: https://mars3d.ifremer.fr/docs/doc_MUSTANG/doc.MUSTANG. deposit.html Deposit processes are treated implicitly in water transport equations. First, deposition flux trends are evaluated for each variable before advection computations. Then after advection resolution, effective deposit is computed with new concentrations in water (estimated after transport and settling) and sediment layers are updated (see Deposition layer managment) Deposit fluxes TODO: add formulation used for deposit fluxes Sliding fluxes A sliding process of the fluid mud is implemented. Only MUD sediments are concerned by this feature. The modelling strategy consists in : •compute the part of mud which slides if the slope is steep •deposit this part towards lower neighboring cells according to the slope To activate this behavior, the cppkey #key_MUSTANG_slipdeposit must be define and the slopefac value in MUSTANG namelist &namsedim_deposition must be greater than 0. The part of mud which slides on each cell limit is the product of the slope by the deposit fluxe for each mud class in the cell and by the factor slopefac. No sediment slides if the slope is not positive. The sum of sliding sediment over the four cell’s limits could not be greater than the deposit flux computed in the cell. Deposit layer managment òNote Patience, work in progress 1.13. Other modules : sediment models, flow-obstruction models, biology models 107 Croco Documentation, Release 2.1.2 1.13.2.2.3.22 Consolidation The mixed-sediment consolidation model, detailed in [Grasso et al., 2015], is based on [Toorman, 1996] unifying theory for sedimentation and consolidation of several classes of sediment. Following Merckelbach’s derivation of Gibson equation, and using as state variable the mass concentration of each sediment class Ci, the mass conservation equation during consolidation can be written as: 𝜕𝐶𝑖 𝜕𝑡 = + 𝜕 𝜕𝑧 [𝑘 𝜌𝑤𝐶𝑖△(𝑙𝑜𝑎𝑑)] (Equation 2) with △(𝑙𝑜𝑎𝑑) = 𝐶𝜌𝑠−𝜌𝑤 𝜌𝑠+1 𝑔 𝜕𝜎′ 𝜕𝑧 where : •C is the sediment total mass concentration, assuming the same grain density 𝜌𝑠for all sediment classes i, •kis the permeability (m/s), •𝜌𝑤is the water density, •gthe gravity •𝜎′the effective stress. In order to account for segregation due to polydispersity during sedimentation, the sand settling velocity was chosen as the maximum between the sedimentation rate in Eq.2 and the hindered settling velocity 𝑊𝑠𝑠𝑖 hindered of the sand class si considered. The mud fraction, however, is only driven by the sedimentation rate in Eq. 2, so that finally the following equation 3 is solved: 𝜕𝐶𝑖 𝜕𝑡 = + 𝜕 𝜕𝑧 [𝐶𝑖𝑀𝐴𝑋(𝑘 𝜌𝑤𝐶𝑖△(𝑙𝑜𝑎𝑑), 𝑊𝑠𝑠𝑖,ℎ𝑖𝑛𝑑𝑒𝑟𝑒𝑑](Equation 3) We used a segregation formulation based on the relative mud concentration (𝐶𝑟𝑒𝑙𝑚𝑢𝑑): 𝐶𝑟𝑒𝑙𝑚𝑢𝑑 =𝐶𝑚𝑢𝑑 1−𝜙𝑠𝑎𝑛𝑑 =𝜙𝑟𝑒𝑙𝑚𝑢𝑑𝜌𝑠(Equation 4) with : •𝐶𝑚𝑢𝑑 the mass concentration of mud (clay and silt) •𝜙𝑠𝑎𝑛𝑑 the volumetric concentration of sand (grain diameter > 63 µm), to express the hindered settling of sand class si as: 𝑊𝑠𝑠𝑖,ℎ𝑖𝑛𝑑𝑒𝑟𝑒𝑑 =𝑊𝑠𝑠𝑖[1 −𝐶𝑟𝑒𝑙𝑚𝑢𝑑 𝐶𝑟𝑒𝑙𝑚𝑢𝑑𝑐𝑟𝑖𝑡 ]𝑝(Equation 5) where : –𝑊𝑠𝑠𝑖 is the non-hindered settling velocity estimated by Souslby’s (1997) formulation and the power p is defined as 4.65 according to Richardson and Zaki’s (1954) observations. –𝐶𝑟𝑒𝑙𝑚𝑢𝑑𝑐𝑟𝑖𝑡 is an empirical parameter calibrated in order that the sand settling becomes hindered by fine (muddy) particles when their relative concentration get close to a threshold value. The resolution of Eq.5 requires the specification of two constitutive relationships for the permeability and the effective stress, respectively (e.g. [Alexis et al., 1992]; [Toorman, 1999]). The permeability constitutive relationship is computed in coupling two formulations. The first is related to the void ratio e (e.g. [Bartholomeeusen et al., 2002]; [Le Hir et al., 2011]), which reads: 𝑘𝑒=𝑘1𝑒𝑘2(Equation 6) and the second is related to the relative volume fraction of fine particles relmud (see Eq.5), based on the fractal theory presented by [Merckelbach and Kranenburg, 2004] and [Merckelbach and Kranenburg, 2004], expressed as: 𝑘𝜙=𝐾𝑘·𝜙𝑟𝑒𝑙𝑚𝑢𝑑−𝑛(Equation 7) with 108 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 •𝑛=2 3−𝑛𝑓 •𝑛𝑓is the fractal number that characterizes the distribution of solids in the sediment. Similarly, this fractal theory enabled to compute the effective stress as: 𝜎′=𝐾𝑑·𝜙𝑟𝑒𝑙𝑚𝑢𝑑𝑛(Equation 8) where 𝑘1, 𝑘2, 𝐾𝑘, 𝐾𝑑, 𝑛 are empirical parameters. òNote In the code, values from [Grasso et al., 2015] are: •𝑘1= 2e-9 •𝑘2= 3.7 And in namsedim_consolidation, default parameters from [Grasso et al., 2015] are : •𝐾𝑘corresponding to xperm1 = 4e-12 •𝐾𝑑corresponding to xsigma1 = 6e+05 •𝑛corresponding to xsigma2 = 6 (and corresponding to xperm2 = -6) 1.13.2.2.3.23 Diffusion within sediment and at interface Cpp keys involved: #key_noTSdiss_insed #key_nofluxwat_IWS .Warning NOT TESTED YET IN CROCO Documentation to come after. Meanwhile: https://mars3d.ifremer.fr/docs/ doc_MUSTANG/doc.MUSTANG.diffu.html 1.13.2.2.3.24 Bioturbation .Warning NOT TESTED YET IN CROCO Documentation to come after. Meanwhile: https://mars3d.ifremer.fr/docs/ doc_MUSTANG/doc.MUSTANG.bioturb.html 1.13.2.2.3.25 Suspended sediment concentration effect on density Witt cpp key SED_DENS, effects of suspended sediment on the density field are included with terms for the weight of each sediment class in the equation of state for seawater density as: 𝜌=𝜌𝑤+ 𝑛𝑣𝑝𝑐 ∑︁ 𝑖=1 𝐶𝑖 𝜌𝑠,𝑖 (𝜌𝑠,𝑖 −𝜌𝑤) This enables the model to simulate processes where sediment density influences hydrodynamics, such as density stratification and gravitationally driven flows. òNote If key_sand2D is used, sand variable treated as 2D variable are excluded of the sum and do not modify density 1.13. Other modules : sediment models, flow-obstruction models, biology models 109 Croco Documentation, Release 2.1.2 1.13.2.2.3.26 Morphodynamic To activate morphodynamic means that the bathymetry used in the hydrodynamic model will evoluate with time. The following figure shows the difference between a non-morphodynamic (ie morphostatic) simulation and a morphodynamic simulation. The user needs to activate cpp key #MORPHODYN and to set to true the boolean l_morphocoupl (see &namsedim_morpho) to run in morphodynamic mode. The user can also accelerate morphologic evolution by using MF parameter (see &namsedim_morpho). In this case, two option are available to accelerate the changes : •MF could amplified directly sediment height variation (l_MF_dhsed = T) on water height. In this case, sediment height and the bed layers compositions are not modified. Bedrock location is modified. •MF could amplified erosion/deposition fluxes (l_MF_dhsed = F). In this case, depending on sediment classes in the simulation, the bed layer composition could be different from the case without MF or with (l_MF_dhsed = T) as coarse sediment settled before small one. Sediment height and bed layers compositions are modified but bedrock location is maintained. 1.13.2.2.4 Specific features 1.13.2.2.4.1 Available online diagnosis: SUBMASSBALANCE This functionnality allows you to compute for each substance : •fluxes through boundaries •budgets (stocks and fluxes ) in sub-domains By default, one domain is considered, containing all the computational grid. User can also define one or several subdomain and boundaries in a specific file (see submassbalance input file). To use this functionnality: set submassbalance_l=.true. in SUBSTANCE namelist and activate cppkey SUBSTANCE_SUBMASSBALANCE. Two type of borders can be defined: closedsub-domains or open boundaries. •For closed sub-domain (a budget sub-domain is only valid if the boundary is closed ), this functionnality computes: –net cumulated fluxes through water (since the start date of massbalance computation) in and out of a given sub-domain, 110 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 –net cumulated input fluxes into the sub-domain due to rivers discharges, –total budget of substance in the sub-domain (total budget must be constant if conservative substance), –stocks in the water column and in the sediment within the sub-domain (if MUSTANG is activated), –net cumulated input fluxes into the sub-domain due to bedload transport (if MUSTANG and bedload is activated). •For open boundaries, this functionnality computes: –net cumulated fluxes through boundaries (since the start date of massbalance computation), sign depending on the definition of each segment of the boundary. Boundaries and sub-domains are defined for all water column (from the surface water to the bottom). Submassbalance results are writen in a separate netcdf file (path defined in nmlsubmassbalance: parameter submassbalance_output_file) Each border can be retrieve by its name in border_name variable and each substance can be retrieve by its name in tracer_name variable. Units correspond to the unit of the substance, for example kg for sediment substance. “border_*” variables correspond to opened borders results and mask. “budget_*” variables correspond to closed domains results and mask. Mask variables allow the user to check the border definition : •border_mask_N and budget_mask_N: equals 1 if the mesh is a South boundary ; -1 if the mesh is a North boundary and 0 otherwise •border_mask_E and budget_mask_E: equals 1 if the mesh is a West boundary ; -1 if the mesh is an East boundary and 0 otherwise •budget_mask: equals 1 in the sub-domain and 0 out of the sub-domain Header of an example submassbalance output file: dimensions: xi_rho =821 ; (continues on next page) 1.13. Other modules : sediment models, flow-obstruction models, biology models 111 Croco Documentation, Release 2.1.2 (continued from previous page) eta_rho =623 ; lchain =200 ; time =UNLIMITED ; // (8748 currently) border =89 ; budget =3; tracer =3; variables: double xi_rho(xi_rho) ; xi_rho:units ="index x axis" ; double eta_rho(eta_rho) ; eta_rho:units ="index y axis" ; double time(time) ; time:units ="seconds since 1900-01-01" ; double lon_rho(eta_rho, xi_rho) ; lon_rho:long_name ="longitude of RHO-points" ; lon_rho:units ="degree_east" ; double lat_rho(eta_rho, xi_rho) ; lat_rho:long_name ="latitude of RHO-points" ; lat_rho:units ="degree_north" ; double border(border) ; char border_name(border, lchain) ; int border_mask_N(eta_rho, xi_rho, border) ; int border_mask_E(eta_rho, xi_rho, border) ; double budget(budget) ; char budget_name(budget, lchain) ; int budget_mask_N(eta_rho, xi_rho, budget) ; int budget_mask_E(eta_rho, xi_rho, budget) ; int budget_mask(eta_rho, xi_rho, budget) ; double tracer(tracer) ; char tracer_name(tracer, lchain) ; double border_flux(time, tracer, border) ; border_flux:description ="FLux through line" ; double budget_total(time, tracer, budget) ; budget_total:description ="Global budget (should be constant if conservative␣ ˓→var)" ; double budget_stwat(time, tracer, budget) ; budget_stwat:description ="Stock in water" ; double budget_stsed(time, tracer, budget) ; budget_stsed:description ="Stock in sediment" ; double budget_flux_ws(time, tracer, budget) ; budget_flux_ws:description ="FLux at interface water-sediment (> if from sed␣ ˓→to wat)" ; double budget_flux_obc(time, tracer, budget) ; budget_flux_obc:description ="FLux from zone boundaries (>if in)" ; double budget_flux_source(time, tracer, budget) ; budget_flux_source:description ="FLux from rivers" ; 1.13.2.2.4.2 Dredging effect This feature has been developed to account for the impact of dredging in estuaries, channels, and harbors, where these anthropogenic activities cannot be overlooked. During the simulation, sediment are removed from user defined areas in the domain and eventually discharged elsewhere in the domain. To enable this feature, the user must complete the dredging_location_file and dredging_settings_file with at least one dredging zone. (See namelist for dredging ,dredging setting file and dredging netcdf location file ) 112 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 An example of a namelist is given here : &namdredging dredging_location_file ='dredging_areas.nc' dredging_settings_file ='dredging_settings.txt' dredging_out_file ='dredging_out.nc' dredging_dumping_layer =1 dredging_dt =3600. dredging_dt_out =3600. / The feature operates using designated dredging and dumping zones defined by dredging_location_file and dredging_settings_file. During the simulation, at user-defined time intervals (dredging_dt), MUSTANG assesses the depth of dredging areas. If the depth in certain cells is too shallow based on user defined criteria for that area, sediment is removed until the criteria is achieved. The extracted sediment is then either discharged in the designated dumping zone or excluded from the computation. MUDS and SANDS dredged sediments are released into the water column at a user-defined sigma level (dredging_dumping_layer), while GRAVELS are deposited directly. The sediments are evenly distributed across the dumping area. The dredging and the dumping occur instantly. A dredging zone is characterized by: •a name •a location provided in a netcdf file •a dredging level in meter with a reference to the mean sea level (and positive towards the bottom) •a dumping zone where the dredged sediment is discharged. This is an option, the dredged sediment could also just be remove from the model domain. A dumping zone is characterized by: •a name •a location provided in a netcdf file This dredging feature can be first explored with the ESTUARY test case, see ESTUARY test case 1.13.2.2.4.3 Details of a dredging setting file The dredging setting file define the depth of the dredging in each area and the associated dumping area. It is a text file with a first line of header not read by MUSTANG. The file must contains one line by dredging area and the name must correspond to the name used in the dredging netcdf location file. In the example below, 3 zones are dredged. Zone_1 and zone_3 dredged sediments are dumped in a zone called dump_1. Zone_2 dredged sediments are dumped outside of the model area. The level of dredging is given in m/mean sea level. #Dredging_area depth(m/mean sea level) Dumping_area zone_1 20. dump_1 zone_2 16. none zone_3 25. dump_1 Tip To dump outside of the model area, put none in the dumping area column òNote Criteria to dredge 1.13. Other modules : sediment models, flow-obstruction models, biology models 113 Croco Documentation, Release 2.1.2 Sediment layers are dredged while h - (hsed - hsed_init) < dredg_depth With: •h: model bathymetry at initial state (m/mean sea level) •hsed: sediment height (m) •hsed_init: sediment_height at initial state (m). This is used to follow bedrock level even in morphostatic simulation. •dredg_depth: depth defined in the dredging_setting_file If the dredg_depth aimed is in the middle of a sediment layer, the layer is partially dredged. 1.13.2.2.4.4 Details of a dredging netcdf location file For each dredging or dumping name specified in the settings file, a corresponding variable of the same dimensions as the model must be present in the NetCDF file, containing: •0 = outside the area •1 = inside the area The total surface of each dumping zone is computed by summing the surface areas of all cells within the zone. These total surfaces are then used to evenly distribute the dredged sediments. An example of a netcdf file header is given below: dimensions: eta_rho =92 ; xi_rho =202 ; variables: double zone_1(eta_rho, xi_rho) ; double zone_2(eta_rho, xi_rho) ; double zone_3(eta_rho, xi_rho) ; double dump_1(eta_rho, xi_rho) ; òNote Overlapping dredging areas In case of overlapping dredging areas, the dredging depths defined in the dredging setting file are used to keep the deepest dredging zone in the corresponding cells. 1.13.2.2.4.5 Dredging output file For each dredging zone and each sediment class, MUSTANG compute the cummulative dredged mass over the simulation. The output file specified in dredging_out_file namelist parameter is a netcdf file with a variable cummulative_mass of dimention the number of sediment class and the number of dredging areas. An example of a netcdf file header is given below: dimensions: lchain = 200 ; time = UNLIMITED ; // (188 currently) area = 3 ; class = 2 ; variables: (continues on next page) 114 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 (continued from previous page) double time(time) ; time:units = "seconds since 1900-01-01" ; double area(area) ; char area_name(area, lchain) ; double class(class) ; char class_name(class, lchain) ; double cummulative_mass(time, class, area) 1.13.2.2.5 FAQ and known issues 1.13.2.2.5.1 Coarse sediment in MUSTANG In MUSTANG V1 (ie, when #key_MUSTANG_V2 is not defined), GRAVEL can not go in suspension, they will not move. Another way to deal with GRAVEL in V1 is to declare them as SAND. They will not travel far anyway in suspension, but at least they will impact the sediment dynamics. If their diameter is greater than 2 mm, they will not impact the mean critical bed shear stress (i.e. common critical bed shear stress for all sediment classes in V1). Nevertheless, MUSTANG V2 is recommended to deal with coarse sediment. 1.13.2.2.5.2 Not yet implemented features Bioturbation, diffusion within sediment and at interface are code but have not been tested yet. 1.13.2.2.5.3 MUSTANG V1 vs MUSTANG V2 Using the cppkey #key_MUSTANG_V2 is another way of dealing with erosion and deposition processes. A review of its implementation will be done in the next MUSTANG version to clarify it. The main differencies are: •porosity computation can be parametrize in V2 while in V1 it is constant •erosion as a mixture whatever the cohesive fraction in V1 versus erosion by class under conditions in V2 (which allow to add bedload in the process) 1.13.3 OBSTRUCTIONS module : flow in presence of various obstructions 1.13.3.1 Introduction In coastal environments, hydrodynamics is often modified by obstructions (natural or anthropogenic) such as seagrass meadows, oyster and mussels farming, salt-marsh and estuarine vegetation. The OBSTRUCTIONS module have been implemented to take account for these modifications of hydrodynamics induced by differents kinds of obstructions. This is a generic module adapted to various types of natural and anthropogenic obstructions that can be found in coastal ecosystems (i.e. rigid/flexible, submerged/emergent, upward/downward/3D). The module as been designed to need a minimal, optimized, number of empirical calibration parameters. Multiple obstruction types can be defined in the same grid cell. The influence of obstruction elements on three-dimensional flow is taken into account through: •the loss of momentum due to the drag exerted on obstruction elements •the balance between turbulence production and dissipation introduced within the k-𝜖turbulence closure scheme The OBSTRUCTIONS module is coupled with the hydrodynamic CROCO model. This module was primarily designed to describe the three-dimensional hydrodynamic effects of flexible seagrass Zostera noltei on flow Kombiadou et al. [2014]. In its updated present state (Ganthy et al. [2025]), the module allows the simulation of various types of obstructions. The numerical scheme has also been modified to allow 1.13. Other modules : sediment models, flow-obstruction models, biology models 115 Croco Documentation, Release 2.1.2 •r_l_obst_abdelrough_cste : To use a constant coefficient during Abdelrhman [2003] procedure used to compute obstruction macro-roughness •r_obst_c_crough_x0 : First coefficient for drag coefficient during Abdelrhman [2003] procedure •r_obst_c_crough_x1 : Second coefficient for drag coefficient during Abdelrhman [2003] procedure If obstructions do not fill completly the cell surface, a patchiness correction can be applied using the fraction of cell occupied by obstructions (given in position file) and several parametrization given in &obst_var_fracxy namelist: •r_l_obst_fracxy : boolean, True to take account for patchiness correction (if false, no correction is applied) •r_obst_fracxy_type : if r_l_obst_fracxy is True, choose the kind of correction method : –0 : patchiness correction is equal to the fraction of cell occupied by obstructions (given in position file) –1 : patchiness correction is equal to an exponential of the fraction of cell occupied by obstructions with one coefficient (r_obst_c_fracxy_k0) –2 : patchiness correction is equal to an exponential of the fraction of cell occupied by obstructions with several coefficients (r_obst_c_fracxy_k0, r_obst_c_fracxy_k1 and r_obst_c_fracxy_l) –3 : patchiness correction is equal to the product of the fraction of cell occupied by obstructions and r_obst_c_fracxy_k0 •r_obst_c_fracxy_k0 : Coefficient for the corrections type 1, 2 and 3 •r_obst_c_fracxy_k1 : First parameter for correction of the exponential coefficient (type 2) •r_obst_c_fracxy_l : Second parameter for correction of the exponential coefficient (type 2) If a sediment model is used (here available with MUSTANG), the OBSTRUCTIONS module can be used to modify the roughness length used to compute the bottom shear stress. The corresponding parameters are in &obst_var_bstress namelist: •r_l_obst_z0bstress : To activate the impact of obstruction on roughness length used to compute the bottom shear stress (only for UP type) •r_obst_z0bstress_option : Option to compute the obstruction induced roughness length: –0 : constant z0 (r_obst_c_z0bstress) –1 : parameterization •r_obst_c_z0bstress : Constant (uncorrected value of roughness length) •r_obst_c_z0bstress_x0 : First parameter for rouhgness length computation (in 3D) •r_obst_c_z0bstress_x1 : Second parameter for rouhgness length computation (in 3D) 1.13.3.2.3 Obstruction variable specific vertical distribution file To specified 3D obstruction or a variation of obstruction density on its height, a text file can be used to specified the fraction (in %, between 0 and 100) of density to apply at a fraction of height (in %, between 0 and 100) . Example for a density equal to 100% of the specified density through 0 to 50% of specified height and 50% above : name nb_hnorm 4 Hnorm nnorm 0. 100 50. 100 50.0001 50 100.100 50 END OF FILE 122 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 The number of vertical discretization is given on line number 3. The readed lines begin at line number 5. Example to specified a 3D obsctruction : Table nb_hnorm 4 Hnorm nnorm 0.0000 0 87.5 0 87.5001 100. 100.100 100. END OF FILE 1.13.3.2.4 Obstruction position file This file is a netcdf file containing the fraction of cell occupied by obstructions (value from 0 to 1) on the model grid. The dimension are the same as the grid file (eta_rho, xi_rho). The name of the variable must be pos_<obstruction name> (with obstruction name given in obst_var_main) Example with an obstruction named Obstruct : netcdf obstruction_seagrass_position { dimensions: eta_rho =7; time =UNLIMITED ; // (1currently) xi_rho =38 ; variables: float pos_Obstruct(time, eta_rho, xi_rho) ; pos_Obstruct:_FillValue =NaN ; double time(time) ; time:long_name ="time since initialization" ; time:units ="seconds since 2019/01/01 00:00:00" ; time:field ="time, scalar, series" ; time:standard_name ="time" ; time:axis ="T" ; } Only the first time index is read. 1.13.3.2.5 Obstruction initialization spatial file This file is a netcdf file containing the variables : height, density, width and thickness on the model grid. The dimension are the same as the grid file (eta_rho, xi_rho). The name of the variable must be : •height_f_<obstruction name> •dens_f_<obstruction name> •width_f_<obstruction name> •thick_f_<obstruction name> (with obstruction name given in obst_var_main) Example with an obstruction named Obstruct : ncdump -h../ktest/SEAGRASS_initspatial/spatial.nc netcdf spatial { (continues on next page) 1.13. Other modules : sediment models, flow-obstruction models, biology models 123 Croco Documentation, Release 2.1.2 (continued from previous page) dimensions: xi_rho =38 ; eta_rho =7; time =UNLIMITED ; // (1currently) variables: double time(time) ; time:long_name ="time since initialization" ; time:units ="seconds since 2019/01/01 00:00:00" ; time:field ="time, scalar, series" ; time:standard_name ="time" ; time:axis ="T" ; float height_f_Obstruct(time, eta_rho, xi_rho) ; height_f_Obstruct:long_name ="Obstruction forcing height for Obstruct" ; height_f_Obstruct:units ="m" ; height_f_Obstruct:field ="" ; height_f_Obstruct:coordinates ="time lat_rho lon_rho" ; float dens_f_Obstruct(time, eta_rho, xi_rho) ; dens_f_Obstruct:long_name ="Obstruction forcing density for Obstruct" ; dens_f_Obstruct:units ="m-2" ; dens_f_Obstruct:field ="" ; dens_f_Obstruct:coordinates ="time lat_rho lon_rho" ; float width_f_Obstruct(time, eta_rho, xi_rho) ; width_f_Obstruct:long_name ="Obstruction forcing width for Obstruct" ; width_f_Obstruct:units ="m" ; width_f_Obstruct:field ="" ; width_f_Obstruct:coordinates ="time lat_rho lon_rho" ; float thick_f_Obstruct(time, eta_rho, xi_rho) ; thick_f_Obstruct:long_name ="Obstruction forcing thickness for Obstruct" ; thick_f_Obstruct:units ="m" ; thick_f_Obstruct:field ="" ; thick_f_Obstruct:coordinates ="time lat_rho lon_rho" ; } Only the first time index is read. 1.13.3.2.6 Obstruction temporal file This file is a netcdf file containing the variables : height, density, width and thickness. The name of the variable must be : •height_f_<obstruction name> •dens_f_<obstruction name> •width_f_<obstruction name> •thick_f_<obstruction name> (with obstruction name given in obst_var_main) The only axis heare is time. The height, density, width and thickness values are applied where the fraction of cell occupied by obstructions is greater than 0 (given in position file). Example with an obstruction named Obstruct : netcdf timeserie2 { dimensions: time =UNLIMITED ; // (741 currently) variables: (continues on next page) 124 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 (continued from previous page) float dens_f_Obstruct(time) ; dens_f_Obstruct:long_name ="Obstruction forcing density for Obstruct" ; dens_f_Obstruct:units ="m-2" ; dens_f_Obstruct:field ="" ; dens_f_Obstruct:coordinates ="time lat_rho lon_rho" ; dens_f_Obstruct:cell_methods ="eta_rho, xi_rho: mean" ; float height_f_Obstruct(time) ; height_f_Obstruct:long_name ="Obstruction forcing height for Obstruct" ; height_f_Obstruct:units ="m" ; height_f_Obstruct:field ="" ; height_f_Obstruct:coordinates ="time lat_rho lon_rho" ; height_f_Obstruct:cell_methods ="eta_rho, xi_rho: mean" ; float thick_f_Obstruct(time) ; thick_f_Obstruct:long_name ="Obstruction forcing thickness for Obstruct" ; thick_f_Obstruct:units ="m" ; thick_f_Obstruct:field ="" ; thick_f_Obstruct:coordinates ="time lat_rho lon_rho" ; thick_f_Obstruct:cell_methods ="eta_rho, xi_rho: mean" ; double time(time) ; time:long_name ="time since initialization" ; time:units ="seconds since 2019/01/01 00:00:00" ; time:field ="time, scalar, series" ; time:standard_name ="time" ; time:axis ="T" ; float width_f_Obstruct(time) ; width_f_Obstruct:long_name ="Obstruction forcing width for Obstruct" ; width_f_Obstruct:units ="m" ; width_f_Obstruct:field ="" ; width_f_Obstruct:coordinates ="time lat_rho lon_rho" ; width_f_Obstruct:cell_methods ="eta_rho, xi_rho: mean" ; } 1.13.3.3 Outputs 1.13.3.3.1 Using CROCO output file To select whether a variable is written to the output file, the boolean in namelist &obst_output has to be filled in. òNote Variables dens_e, width_e, thick_e, theta, frac_xy, frac_z, a2d, s2d, s3d and drag are not allocated if not wanted in output. If you do not need them, put False in the corresponding boolean to reduce space disk and memory needs of your simulation 1.13.3.3.2 Using XIOS XIOS can be used to output the same variables as in CROCO output file. Example of a .xml field file for a case with one obstruction called “Obstruct”. The id of each field has to be coherent with the given name of obstruction. <field_group id="rho" grid_ref="rho_2D"> <field id="pos_Obstruct" long_name="Obstruction occupation rate for Obstruct" unit="-" grid_ref="rho_2D" /> <field id="height_f_Obstruct" (continues on next page) 1.13. Other modules : sediment models, flow-obstruction models, biology models 125 Croco Documentation, Release 2.1.2 (continued from previous page) long_name="Obstruction forcing height for Obstruct" unit="m" grid_ref="rho_2D" /> <field id="height_e_Obstruct" long_name="Obstruction effective height for Obstruct" unit="m" grid_ref="rho_2D" /> <field id="dens_f_Obstruct" long_name="Obstruction forcing density for Obstruct" unit="m-2" grid_ref="rho_2D" /> <field id="dens_e_Obstruct" long_name="Obstruction effective density for Obstruct" unit="m-2" grid_ref="rho_3D" /> <field id="width_f_Obstruct" long_name="Obstruction forcing width for Obstruct" unit="m" grid_ref="rho_2D" /> <field id="width_e_Obstruct" long_name="Obstruction effective width for Obstruct" unit="m" grid_ref="rho_3D" /> <field id="thick_f_Obstruct" long_name="Obstruction forcing thickness for Obstruct" unit="m" grid_ref="rho_2D" /> <field id="thick_e_Obstruct" long_name="Obstruction effective thickness for Obstruct" unit="m" grid_ref="rho_3D" /> <field id="theta_Obstruct" long_name="Obstruction bending angle for Obstruct" unit="deg" grid_ref="rho_3D" /> <field id="frac_xy_Obstruct" long_name="Obstruction fragmentation correction factor for Obstruct" unit="-" grid_ref="rho_2D" /> <field id="frac_z_Obstruct" long_name="Obstruction sigma fraction for Obstruct" unit="-" grid_ref="rho_2D" /> <field id="cd3d_Obstruct" long_name="Obstruction drag coefficient for Obstruct" unit="-" grid_ref="rho_3D" /> <field id="a2d_Obstruct" long_name="2D Obstruction horizontal area for Obstruct" unit="-" grid_ref="rho_2D" /> <field id="a3d_Obstruct" long_name="3D Obstruction horizontal area for Obstruct" unit="-" grid_ref="rho_3D" /> <field id="s2d_Obstruct" long_name="2D Obstruction vertical area for Obstruct" unit="-" grid_ref="rho_2D" /> <field id="s3d_Obstruct" long_name="3D Obstruction vertical area for Obstruct" unit="-" grid_ref="rho_3D" /> <field id="a2d_NoTurb" long_name="2D Obstruction horizontal area for NoTurb variables" unit="-" grid_ref="rho_2D" /> <field id="a2d_Turb" long_name="2D Obstruction horizontal area for Turb variables" unit="-" grid_ref="rho_2D" /> <field id="a2d_All" long_name="2D Obstruction horizontal area for All variables" (continues on next page) 126 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 (continued from previous page) unit="-" grid_ref="rho_2D" /> <field id="a3d_NoTurb" long_name="3D Obstruction horizontal area for NoTurb variables" unit="-" grid_ref="rho_3D" /> <field id="a3d_Turb" long_name="3D Obstruction horizontal area for Turb variables" unit="-" grid_ref="rho_3D" /> <field id="a3d_All" long_name="3D Obstruction horizontal area for All variables" unit="-" grid_ref="rho_3D" /> <field id="s2d_NoTurb" long_name="2D Obstruction vertical area for NoTurb variables" unit="-" grid_ref="rho_2D" /> <field id="s2d_Turb" long_name="2D Obstruction vertical area for Turb variables" unit="-" grid_ref="rho_2D" /> <field id="s2d_All" long_name="2D Obstruction vertical area for All variables" unit="-" grid_ref="rho_2D" /> <field id="s3d_NoTurb" long_name="3D Obstruction vertical area for NoTurb variables" unit="-" grid_ref="rho_3D" /> <field id="s3d_Turb" long_name="3D Obstruction vertical area for Turb variables" unit="-" grid_ref="rho_3D" /> <field id="s3d_All" long_name="3D Obstruction vertical area for All variables" unit="-" grid_ref="rho_3D" /> <field id="fuzvz_uz" long_name="Obstruction 3D friction force FUZ" unit="N.m-2" grid_ref="rho_3D" /> <field id="fuzvz_vz" long_name="Obstruction 3D friction force FVZ" unit="N.m-2" grid_ref="rho_3D" /> <field id="tau3d" long_name="Obstruction 3D turbulent dissipation" unit="N.m-2" grid_ref="rho_3D" /> </field_group> 1.13.3.4 Example A test case is provided with cppkey #SEAGRASS. See SEAGRASS for more informations. 1.13.4 Biogeochemical models CROCO comes with series of biogeochemical (BGC) models of increasing complexity, from relatively simple 5or 7-component NPZD [Gruber et al., 2006,Gruber et al., 2011] and N2P2Z2D2 BioEBUS model [Gutknecht et al., 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,Gruber et al., 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 1.13. Other modules : sediment models, flow-obstruction models, biology models 127 Croco Documentation, Release 2.1.2 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 Coba De La Peña 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], Suntharalingam et al. [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. Related CPP options: PISCES Activate 24-component PISCES biogeochemical model BIO_NChlPZD Activate 5-component NPZD type model BIO_N2PZD2 Activate 7-component NPZD type model BIO_BioEBUS Activate 12-component NPZD type model Preselected options: # ifdef BIOLOGY # undef PISCES # define BIO_NChlPZD # undef BIO_N2ChlPZD2 # undef BIO_BioEBUS # endif 1.13.5 Lagrangian floats 1.14 Coupling CROCO with other models CROCO is coupled to atmospheric and wave models through the OASIS-MCT (Ocean-Atmosphere-Sea-Ice-Soil, Model Coupling Toolkit) coupler developed by CERFACS (Toulouse, France). This coupler allows the atmospheric, oceanic, and wave models to run at the s ame time in parallel, it exchanges variables, and performs grid interpolations and time transformations if requested. OASIS is not an executable file, but a set of libraries pro128 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 viding functions which are called in the models themselves. The variables exchanged by the coupler, as well as the grid interpolations are specified through a namelist file (called namcouple). CROCO can therefore be coupled to any code in which OASIS-MCT is implemented. Non-exhaustively, here are some models including OASIS-MCT, that can be coupled to CROCO: •WRF (Weather Research and Forecast model developed at NCAR, Boulder, USA) •Meso-NH (Mesoscale Non-Hydrostatic model developed at Laboratoire d’Aérologie, Toulouse, France) •WW3 (WaveWatch III model developed at NCEP, USA, and Ifremer, France) •... Those model are not provided for download with CROCO and need to be installed separately, as well as OASISMCT library. A description of the OASIS-MCT features, its implementation in CROCO, WW3 and WRF codes, and the coupled variables that can be exchanged are given in the following. Datailed step by step coupled tutorial is also available in the Tutorials section. 1.14.1 OASIS philosophy 1.14.1.1 OASIS libraries OASIS-MCT libraries are: •psmile for coupling •mct (Argonne National Laboratory) for parallel exchanges •scrip (Los Alamos National Laboratory) for interpolations Functions provided by the OASIS-MCT framework are: òNote oasis_ /prism_ are new / old names for backward compatibility, both useable •Initialization and creation of a local communicator for internal parallel computation in each model: –oasis_init_comp / prism_init_comp_proto –oasis_get_localcomm / prism_get_localcomm_proto •Grid data definition for exchanges and interpolations: –oasis_write_grid –oasis_write_corner –oasis_write_area –oasis_write_mask –oasis_terminate_grids_writing –Partition and exchanged variables definition: ∗oasis_def_partition / prism_def_partition_proto ∗oasis_def_var / prism_def_var_proto ∗oasis_enddef / prism_enddef_proto –Exchange of coupling fields: ∗oasis_get / prism_get_proto ∗oasis_put / prism_put_proto 1.14. Coupling CROCO with other models 129 Croco Documentation, Release 2.1.2 –Finalization: ∗oasis_terminate / prism_terminate_proto These OASIS3-MCT intrinsic functions are called in each model involved in the coupling. Initialization phase, Definition phase, and Finalization phase are called only once in each simulation while Exchange phase is called every time step. The effective exchanges are done only at specified times, defined by the coupling frequency, although the Exchange phase is called every model time step. The coupling frequency is controlled through the OASIS3-MCT namcouple. 1.14.1.2 Coupling sequence The frequency of exchanges between two models is defined by the coupling time step. The coupling time step must be a multiple of the models time steps. An example of coupling sequence is pictured in the following Figure. In this example, the coupling time step is defined at 360s for both models. The wave model time step is 90s, so it will exchange every 4 time steps. The ocean model time step is 180s, so it will exchange every 2 time steps. Another coupling parameter defined in the namcouple is the lag. It is used by the OASIS coupler to synchronize the send and receive functions. The lag must be defined for each model at the same value than its own time step. For instance: •WAVE to OCEAN lag = dt wave = 90 •OCEAN to WAVE lag = dt ocean = 180 Therefore, receive and send functions have to be set at the same time in the model codes. OASIS will send the fields at the appropriate time thanks to the lag defined in the namcouple. The coupling sequence in each model is: 130 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 initialization oasis_time = 0 reception of coupled fields rcv(oasis_time) model time stepping computation t -> t+dt sending of coupled fields snd(oasis_time) increment of coupling time oasis_time = oasis_time + dt OASIS will exchange fields (get/put) if the time corresponds to a coupling time step, e.g. if: •oasis_time corresponds to a coupling time step for get •oasis_time + lag corresponds to a coupling time step for put IN THE MODEL IN OASIS receive (date) get(date) send(date) put(date+lag) OASIS is also able to store fields from a model if a time transformation is requested in the namcouple (keyword LOCTRANS + type of transformation, see next section). OASIS will store the fields until a coupling time step is reached, then it will apply the time transformation, interpolate spatially the field as specified in the namcouple, and exchange the field with the other model. 1.14.1.3 Restart files As reception of coupled fields is called before model computation, you need to create restart files for the coupler containing initial or restart fields for the first time step. These restart files are for OASIS, and therefore need to have variable names corresponding to OASIS namcouple coupled fields. The initial files for OASIS are named oasis_oce.nc and oasis_wave.nc in the example pirctured in the above Figure. oce_ini and wave_ini are not related to OASIS, they are usual initialization or restart files from your oceanic and wave model; e.g. in CROCO, oce_ini is croco_ini.nc, and in WW3, wave_ini is restart.ww3). Summary of the restart files: •oasis_oce.nc,oasis_wave.nc: restart files for OASIS, you need to create them at the beginning of the run, OASIS will overwrite them at the end of the run, and they will be available for next restart •oce_ini,wave_ini: correspond to croco_ini.nc,restart.ww3. These are your ocean and wave model initial or restart files Practical example of the coupling sequence pictured in the above Figure: oasis_time =0 #1 => get field from oasis_wave.nc rcv(0)=> in oasis: get(0) #2 => timestepping t=0+dt =0+180 =180 #3 => 180 is not a coupling time step, do nothing snd(0)=> in oasis: put(0+lag) =put(0+180)=put(180) oasis_time =oasis_time+dt =0+180 =180 #4 => 180 is not a coupling time step, do nothing rcv(180)=> in oasis: get(180) #5 => timestepping t=180+dt =180+180 =360 #6 => 360 is a coupling time step, put field snd(180)=> in oasis: put(180+lag) =put(180+180)=put(360) 1.14. Coupling CROCO with other models 131 Croco Documentation, Release 2.1.2 Fields sent by CROCO Name (units) name and eventual oper. in the model OASIS name SST (K) t(:,:,N,nnew,itemp) + 273.15 CROCO_SST U-component of current (m/s) u (at rho points): 0.5*(u(1:Lmmpi,1:Mmmpi,N,nnew) +u(2:Lmmpi+1,1:Mmmpi,N,nnew)) CROCO_UOCE V-component of current (m/s) v (at rho points): 0.5*(v(1:Lmmpi,1:Mmmpi,N,nnew) +v(1:Lmmpi,2:Mmmpi+1,N,nnew)) CROCO_VOCE Eastward component of current (m/s) u (at rho points) rotated eastwards (useful for rotated grids) (0.5 * (u(1:Lmmpi ,1:Mmmpi,N,nnew) + u(2:Lmmpi+1,1:Mmmpi,N,nnew)) ) * cos(angler(1:Lmmpi ,1:Mmmpi)) - (0.5 * (v(1:Lmmpi,1:Mmmpi ,N,nnew) + v(1:Lmmpi,2:Mmmpi+1,N,nnew)) ) * sin(angler(1:Lmmpi ,1:Mmmpi)) +u(2:Lmmpi+1,1:Mmmpi,N,nnew)) CROCO_EOCE Northward component of current (m/s) v (at rho points) rotated northward (useful for rotated grids) (0.5 * (u(1:Lmmpi ,1:Mmmpi,N,nnew) + u(2:Lmmpi+1,1:Mmmpi,N,nnew)) ) * sin(angler(1:Lmmpi ,1:Mmmpi)) + (0.5 * (v(1:Lmmpi,1:Mmmpi ,N,nnew) + v(1:Lmmpi,2:Mmmpi+1,N,nnew)) ) * cos(angler(1:Lmmpi ,1:Mmmpi)) CROCO_NOCE 138 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 Fields received by CROCO Name (units) name and eventual oper. in the model OASIS name U component of wind stress (N/m2) sustr (at u point): 0.5*(FIELD(io1,jo)+FIELD(io,jo))/rho0 if eastward, it is first rotated: FIELD = etau * cos(angler) + ntau * sin(angler) CROCO_UTAW or CROCO_ETAW V component of wind stress (N/m2) svstr (at v point): 0.5*(FIELD(io,jo1)+FIELD(io,jo))/rho if northward, it is first rotated: FIELD = ntau * cos(angler) - etau * sin(angler) CROCO_VTAW or CROCO_NTAW Wind stress module (N/m2) smstr = FIELD / rho0 CROCO_TAUM Surface net solar flux (W/m2) srflx = FIELD / (rho0*Cp) CROCO_SRFL Surface net non-solar flux (W/m2) stflx(:,:,itemp) = FIELD / (rho0*Cp) CROCO_STFL Evaporation-Precipitation (kg/m2/s) stflx(:,:,isalt) = FIELD / 1000 CROCO_EVPR Surface atmospheric pressure (Pa) patm2d = FIELD CROCO_PSFC Fields received by WRF Name (units) name (in the model) OASIS name SST (K) SST WRF_d01_EXT_d01_SST U component of current (m/s) UOCE WRF_d01_EXT_d01_UOCE V component of current (m/s) VOCE WRF_d01_EXT_d01_VOCE Eastward component of current (m/s) EOCE WRF_d01_EXT_d01_EOCE Northward component of current (m/s) NOCE WRF_d01_EXT_d01_NOCE 1.14. Coupling CROCO with other models 139 Croco Documentation, Release 2.1.2 Fields sent by WRF Name (units) name (in the model) OASIS name Surface net solar flux (W/m2) GSW WRF_d01_EXT_d01_SURF_NET_SOLAR Surface net non-solar flux (W/m2) GLWSTBOLT*EMISS*SST**4LH-HFX WRF_d01_EXT_d01_SURF_NET_NONSOLAR Evaporation-precipitation (kg/m2/s) QFX-(RAINCV+RAINNCV)/DT WRF_d01_EXT_d01_EVAP-PRECIP Surface atmospheric pressure (Pa) PSFC WRF_d01_EXT_d01_PSFC Wind stress module (N/m2) taut = rho * ust**2 WRF_d01_EXT_d01_TAUMOD U component of wind stress (N/m2) taui = taut * u_uo / wspd WRF_d01_EXT_d01_TAUX V component of wind stress (N/m2) tauj = taut * v_uo / wspd WRF_d01_EXT_d01_TAUY Eastward comp. of wind stress(N/m2) cosa * taui - sina * tauj WRF_d01_EXT_d01_TAUE Northward comp. of wind stress(N/m2) cosa * tauj + sina * taui WRF_d01_EXT_d01_TAUN òNote If you decide to couple CROCO with multiple WRF domains, variables coming from WRF will be defined by adding _EXT*. Here * corresponds to which domains the variable is coming (1=Parent, 2=Nest 1 ,...). 1.14.3.2 Coupling with a wave model When coupling CROCO to a wave model, the wave-current interactions have to be set on. At the moment, only mean wave parameters are exchanged, their contribution to ocean dynamics is computed into the wave-current interaction routine in CROCO. The following cpp-keys have to be set: # define OW_COUPLING # define MPI # define MRL_WCI òNote You also have to be careful to the choice of the momentum flux. For better consistency, here we suggest to account for the momentum flux seen by the wave model, and thus set: # undef BULK_FLUX # define WAVE_SMFLUX 140 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 Fields sent by CROCO Name (units) name and eventual oper. in the model OASIS name SSH (m) zeta CROCO_SSH U-component of current (m/s) u (at rho points): 0.5*(u(1:Lmmpi,1:Mmmpi,N,nnew) +u(2:Lmmpi+1,1:Mmmpi,N,nnew)) CROCO_UOCE V-component of current (m/s) v (at rho points): 0.5*(v(1:Lmmpi,1:Mmmpi,N,nnew) +v(1:Lmmpi,2:Mmmpi+1,N,nnew)) CROCO_VOCE Eastward component of current (m/s) u (at rho points) rotated to east (useful for rotated grids) (0.5 * (u(1:Lmmpi ,1:Mmmpi,N,nnew) + u(2:Lmmpi+1,1:Mmmpi,N,nnew)) ) * cos(angler(1:Lmmpi ,1:Mmmpi)) - (0.5 * (v(1:Lmmpi,1:Mmmpi ,N,nnew) + v(1:Lmmpi,2:Mmmpi+1,N,nnew)) ) * sin(angler(1:Lmmpi ,1:Mmmpi)) +u(2:Lmmpi+1,1:Mmmpi,N,nnew)) CROCO_EOCE Northward component of current (m/s) v (at rho points) rotated to north (useful for rotated grids) (0.5 * (u(1:Lmmpi ,1:Mmmpi,N,nnew) + u(2:Lmmpi+1,1:Mmmpi,N,nnew)) ) * sin(angler(1:Lmmpi ,1:Mmmpi)) + (0.5 * (v(1:Lmmpi,1:Mmmpi ,N,nnew) + v(1:Lmmpi,2:Mmmpi+1,N,nnew)) ) * cos(angler(1:Lmmpi ,1:Mmmpi)) CROCO_NOCE 1.14. Coupling CROCO with other models 141 Croco Documentation, Release 2.1.2 Fields received by CROCO Name (units) name and eventual oper. in the model OASIS name Significant wave height (m) whrm = FIELD * 0.70710678 CROCO_HS Mean wave period (s) -> frequency wfrq = 2*pi / FIELD CROCO_T0M1 Mean wave direction -> wavenumbers wdrx = cos(FIELD - angler) wdre = sin(FIELD - angler) CROCO_DIR U component of wave stress (m2/s2) twox (at u point): 0.5*(FIELD(io1,jo)+FIELD(io,jo)) if eastward, it is first rotated: FIELD = etwo * cos(angler) + ntwo * sin(angler) CROCO_UTWO or CROCO_ETWO V component of wave stress (m2/s2) twoy (at v point): 0.5*(FIELD(io,jo1)+FIELD(io,jo)) if northward, it is first rotated: FIELD = ntwo * cos(angler) - etwo * sin(angler) CROCO_VTWO or CROCO_NTWO U comp. of wind-to-wave stress (m2/s2) tawx (at u point): 0.5*(FIELD(io1,jo)+FIELD(io,jo)) if eastward, it is first rotated: FIELD = etaw * cos(angler) + ntaw * sin(angler) CROCO_UTAW or CROCO_ETAW V comp. of wind-to-wave stress (m2/s2) tawy (at v point): 0.5*(FIELD(io,jo1)+FIELD(io,jo)) if northward, it is first rotated: FIELD = ntaw * cos(angler) - etaw * sin(angler) CROCO_VTAW or CROCO_NTAW 142 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 Other optional fields enventually sent, if not, they are analytically computed in the MRL_WCI routine Bernoulli head pressure (N/m) bhd CROCO_BHD Wave-to-ocean TKE flux (W/m2) foc CROCO_FOC Mean wavelength (m) wlm CROCO_LM Wave orbital bottom velocity (m/s) ubr = sqrt(ubrx**2+ubry**2) CROCO_UBRX and CROCO_UBRY Stokes drift surface velocity (m/s) ust_ext = sqrt(ustx_ext**2+usty_ext**2) CROCO_USSX and CROCO_USSY Fields received by WW3 Name (units) name (in the model) OASIS name SSH = water level (m) LEV WW3__SSH Zonal current (m/s) CUR WW3_OSSU Meridional current (m/s) CUR WW3_OSSV Fields sent by WW3 Name (units) name (in the model) OASIS name Mean wave period (s) T0M1 WW3_T0M1 Significant wave height (m) HS WW3__OHS Mean wave direction THM WW3__DIR Zonal wave stress (N/m2) TWOX WW3_TWOX Meridional wave stress (N/m2) TWOY WW3_TWOY Zonal wind stress (N/m2) TAWX WW3_TAWX Meridional wind stress(N/m2) TAWY WW3_TAWY Other fields possibly sent, but not used in coupling with CROCO at the moment Bernoulli head pressure (N/m) BHD WW3__BHD Bottom orbital velocity (m/s) UBR WW3__UBR Wave-to-ocean TKE flux (W/m2) FOC WW3__FOC Mean wavelength (m) LM WW3___LM Wave peak frequency (/s) FP WW3___FP 1.14.3.3 Coupling atmosphere and wave models Fields received by WW3 Name (units) name (in the model) OASIS name Zonal wind (m/s) WND WW3__U10 Meridional wind (m/s) WND WW3__V10 Fields sent by WW3 Name (units) name (in the model) OASIS name Significant wave height (m) HS WW3__AHS Charnock coefficient ACHA WW3_ACHA Fields sent by WRF Name (units) name (in the model) OASIS name Zonal wind at first level( (m/s) u_uo WRF_d01_EXT_d01_WND_E_01 Meridional wind at first level (m/s) v_vo WRF_d01_EXT_d01_WND_N_01 1.14. Coupling CROCO with other models 143 Croco Documentation, Release 2.1.2 Fields received by WRF Name (units) name (in the model) OASIS name Charnock coefficient CHA_COEF WRF_d01_EXT_d01_CHA_COEF 1.14.3.4 Note on momentum flux when coupling 3 models As the wave model has a quite complex parameterization of wave generation by winds, which is in subtle balance with the wave dissipation, the wind stress for the wave model is computed by its own parameterization. Therefore, to ensure energetic consistency of the momentum flux when coupling 3 models, we prescribe the wind stress in CROCO as: sustr =sustr_from_atm_model -tawx +twox svstr =svstr_from_atm_model -tawy +twoy # where taw is stress from atm to waves # and two is stress from waves to ocean 1.14.3.5 Note on coupling with AGRIF You may decide to coupled CROCO while using AGRIF. To do so, the variables sent by the parent domain (0) and the child domains (1,2,...) must be separated. Thus the variables sent, in case of using AGRIF, take the radical defined above (CROCO_VAR) to which we add _0 (for parent) or _1 (for first child). This gives, for example for variable SST, CROCO_SST_0 or CROCO_SST_1 for parent and child respectively. For the variables received by CROCO, we will use its ability to handle CPLMASK. Each of the domains (parent or children) will be assigned a coupling mask named coupling_mask0.nc (parent), coupling_mask1.nc (child 1), each coupling mask being relative to its grid. The CROCO domain that receives a variable will be identified by its mask (CPLMASK*), which will be added to the previous radical. This will give CROCO_VAR_CPLMASK0 for the parent or CROCO_VAR_CPLMASK1 for child 1. This makes it easy to define the received variables in a case where one decides to couple CROCO-AGRIF with several WRF domains. In this case the variables will have the nomenclature CROCO_VAR_CPLMASK0 for the parent CROCO to which we add _EXT1 for the first domain of coupling_mask0.nc. By continuity _EXT2 will correspond to domain 2 of coupling_mask0.nc. Then the variables received by CROCO, in a case of CROCO-AGRIF/WRFnest simulation, will follow the format CROCO_VAR_CPLMASK*_EXT*. 1.14.4 Grids 1.14.4.1 OASIS grid files OASIS manage grids and interpolations by using dedicated grid files: •grids.nc •masks.nc •areas.nc (requested only for some of the interpolation types) These files can be automatically created by OASIS functions called in each model, or can be created by the user in advance if specificities are requested. Some facilities are provided in croco_tools/Coupling_tools to create such grids. If grids.nc,masks.nc,areas.nc exist in the working directory, they won’t be overwritten by OASIS functions. So, be sure to have the good files or remove them before running the coupled model. 1.14.4.2 Multiple model grids (nesting case) Multiple nested grids in the different models can be used in coupled mode. The variables are therefore exchanged from/to the different grids. To do so, each coupled variable is identified in the coupler with its grid number: 144 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 •For CROCO the last character of the OASIS variable name defines the domain –0 being the parent domain –1 the first child domain, etc. •For WRF the domains are defined by d01, d02, etc, and the target domain (CROCO for instance), by EXT_d01, EXT_d02, etc. For example if you are coupling 2 CROCO domains to one atmospheric domain, you will specify 2 types of exchanges in the namcouple: # exchange between CROCO parent domain to WRF domain SRMSSTV0 WRF_d01_EXT_d01_SST # exchange between CROCO child domain to WRF domain SRMSSTV1 WRF_d01_EXT_d02_SST If you are coupling 2 WRF domains to one CROCO domain: # exchange between WRF d01 domain to CROCO domain WRF_d01_EXT_d01_TAUMOD RRMTAUM0 # exchange between WRF d02 domain to CROCO domain WRF_d02_EXT_d01_TAUMOD RRMTAUM0 Related CPP options: OW_COUPLING Activate Ocean-Wave coupling OA_COUPLING Activate Ocean-Atmosphere coupling OA_MCT Use OASIS-MCT for coupling Preselected options: #undef OA_COUPLING #undef OW_COUPLING 1.15 I/O and Online Diagnostics 1.15.1 General ouptut options AVERAGES Process and output time-averaged data AVERAGES_K Process and output time-averaged vertical mixing XIOS Use XIOS IO server (only version >= 2 is supported) XIOS is an external library for output (developed at IPSL) providing for flexibility and design to improve performances for HPC : see http://forge.ipsl.jussieu.fr/ioserver Preselected options: # define AVERAGES # define AVERAGES_K # undef XIOS 1.15. I/O and Online Diagnostics 145 Croco Documentation, Release 2.1.2 1.15.2 Advanced diagnostics options DIAGNOSTICS_TS Store and output budget terms of the tracer equations DIAGNOSTICS_TS_ADV Choose advection rather than transport formulation for tracer budgets DIAGNOSTICS_TS_MLD Integrate tracer budgets over the mixing layer depth (hbl, defined as the turbulent layer from the mixing param) DIAGNOSTICS_TS_MLD_CRIT Integrate tracer budgets over the mixed-layer depth (MLD, defined with criterion in density, temperature or Brunt-Vaisala frequency) DIAGNOSTICS_TSVAR Store and output budget terms of the tracer variance equations (instead of tracer) DIAGNOSTICS_UV Store and output budget terms of the momentum equations. DIAGNOSTICS_BARO Isolate contribution from barotropic/baroclinic coupling (included in the vertical mixing term otherwise) for momentum, barotropic vorticity and kinetic energy budgets DIAGNOSTICS_VRT Store and output budget terms of the barotropic vorticity equation DIAGNOSTICS_EK Store and output budget terms of the kinetic energy equation (vertically integrated) DIAGNOSTICS_EDDY Store and output time-averaged quadratic quantities u^2, v^2, u*v, u*w, v*w, u*b, v*b, w*b, u*sustr, v*svstr, u*bustr, v*bvstr, zeta^2 DIAGNOSTICS_PV Store and output non conservative term in the momentum equations and diabatic term in the tracer equations. if DIAGNOSTICS_DISS is also defined, terms are multiplied by momentum and thermal/saline expension coefficients to be used to estimate kinetic and potential energy dissipation. Preselected options: # undef DIAGNOSTICS_TS Store and output budget terms of the tracer equations # undef DIAGNOSTICS_TS_ADV Choose advection rather than transport formulation for␣ ˓→tracer budgets # undef DIAGNOSTICS_TS_MLD Integrate tracer budgets over the mixed-layer depth # undef DIAGNOSTICS_TSVAR output budgets of tracer variance instead of tracer # undef DIAGNOSTICS_UV Store and output budget terms of the momentum equations # undef DIAGNOSTICS_BARO Isolate contribution from barotropic/baroclinic coupling # undef DIAGNOSTICS_VRT Store and output budget terms of the barotropic vorticity␣ ˓→equation # undef DIAGNOSTICS_EK Store and output budget terms of the kinetic energy␣ ˓→equation (vertically integrated) # undef DIAGNOSTICS_PV Store and output non conservative / diabatic terms # undef DIAGNOSTICS_EDDY Store and output time-averaged quadratic quantities 146 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 1.15.2.1 Energy budget terms The different budgets and their computation are detailled in https://www.jgula.fr/Croco/diagnostics_croco.pdf 1.15.2.2 Tracer budget terms DIAGNOSTICS_TS computes the tracer budgets in 3D. DIAGNOSTICS_TS_MLD computes the tracer budgets: •over the mixing layer (hbl, defined as the turbulent layer from the vertical mixing parametrization) •over the mixed layer (defined as the homogeneous surface layer) if DIAGNOSTICS_TS_MLD_CRIT is defined in addition. òNote To integrate tracer budgets over the mixed layer depth, the CPP key LMD_SKPP needs to be activated. Tracer budgets will be stored in croco_dia.nc (instantaneous) and/or croco_dia_avg.nc (average) output files. 1.15.2.2.1 Mixing layer calculation The turbulent mixing layer (hbl) is defined depending on the mixing parameterization (see Vertical mixing parametrizations). 1.15.2.2.2 Mixed layer calculation The mixed layer depth (MLD) is defined as the slice of the surface ocean where temperature, salinity and density are homogeneous. In reality, as the mixed layer is not perfectly homogeneous, a threshold value is applied to determine when temperature/density is no longer considered homogeneous. .Warning Temperature budget term is computed according to 4 criteria. But for the other tracers the only criteria is on density ! 4 criteria are available to compute the mixed layer, and the associated temperature budgets: •one density criterion (CRT1), which default value is set to 0.03 kg/m3 •two temperature critera (CRT2 and CRT3), which default values are respectively 0.2°C and 0.5°C •one Brunt-Vaisala frequency criterion (CRT4) based on the delta density threshold of CRT1. These default values are taken from [de Boyer Montegut C. et al., 2004]. òNote These values depend on the study area and are valid for deep waters. 1.15.2.2.2.1 Density criterion The MLD is evaluated as the depth where the density is equal to the density at a reference level plus the chosen threshold ([de Boyer Montegut C. et al., 2004]). The reference level is defined as the level with the depth closest to the reference depth defined in diag_mld_depth_ref, a user-modifiable parameter (and set to 10m by default). The threshold value and the reference depth are user-modifiable parameters. 1.15. I/O and Online Diagnostics 147 Croco Documentation, Release 2.1.2 Table 2 – continued from previous page KEYWORD DESCRIPTION diagbioVSink_history_fields 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. diagbioGasExc_history_fields Flag (T or F) to select which biogechemical tracer Gas exchange flux equation to store in diagnostic file. These terms are 2D. diagbioFlux_average_fields Same as above but averaged diagbioVSink_average_fields Same as above but averaged diagbioGasExc_average_fields Same as above but averaged biology Name of file containing the Iron dust forcing used in the PISCES biogeochemical model sediments 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) bbl_history_fieldsi 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) floats Lagrangian floats application. Same format as diagnostics LDEFFLT NFLT NRPFFLT inpname, hisname floats_fields Type of fields computed for each lagrangian floats station_fields Fixed station application. Same format as diagnostics LDEFSTA NSTA NRPFSTA inpname, hisname continues on next page 250 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 Table 2 – continued from previous page KEYWORD DESCRIPTION psource 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 psource_ncfile 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 1.17.3 Comparison of ROMS and CROCO versions Models CROCO ROMSUCLA ROMS-Rutgers / COASWT Origin UCLA-IRD-INRIAIFREMER-SHOMCNRS UCLA UCLA-Rutgers-USGS Maintenance IRD-INRIA-IFREMERSHOM-CNRS UCLA Rutgers-USGS Realm Europe-World US West Coast US East Coast Introductory year 1999 (AGRIF) 2016 (CROCO) 2002 1998 CODE FEATURES 1.17. Appendices 251 Croco Documentation, Release 2.1.2 Models CROCO ROMS-UCLA ROMS-Rutgers / COASWT Parallelization MPI or OpenMP (Hybrid branch exists) Hybrid MPI-OpenMP MPI or OpenMP Nesting Online at barotropic level Off-line (On-line at baroclinic level and not yet operational) Off-line Data assimilation 3DVAR 3DVAR 4DVAR Wave-current interact. McWilliams et al. [2004] McWilliams et al. [2004] Mellor [2003] McWilliams et al. [2004] Air-sea coupling OASIS-MCT Home made MCT Sediment Dynamics Blaas et al. [2007] MUSTANG Blaas et al. [2007] Blaas et al. [2007] Warner et al. [2008] Biogeochemistry NPZD Gruber et al. [2006], PISCES NPZD Gruber et al. [2006]EcoSim, NEMURO, NPZD Franks, NPZD Powell, Fennel Sea ice none none Budgell [2005] Vertical mixing KPP, GLS KPP, GLS KPP, GLS Wetting-Drying Warner et al. [2013] none Warner et al. [2013] TIME STEPPING Models CROCO ROMS-UCLA ROMS-Rutgers / COASWT 2D momentum Generalized FB AB3AM4 Generalized FB AB3AM4 LF-AM3 with FB feedback 3D momentum LF-AM3 LF-AM3 AB3 Tracers LF-AM3 with stabilizing correction for isopycnal hyperdiffusion LF-AM3 with stabilizing correction for isopycnal hyperdiffusion LF-TR with explicit geopotential diffusion (no stabilizing correction : strong stability constraint) Internal waves LF-AM3 with FB feedback LF-AM3 with FB feedback Generalized FB (AB3TR) Coupling stage Predictor Corrector 252 Chapter 1. Model Documentation Croco Documentation, Release 2.1.2 STABILITY CONSTRAINTS (Max Courant number) Models CROCO ROMS-UCLA ROMS-Rutgers / COASWT 2D 1.78 1.78 1.85 3D advection 1.58 1.58 0.72 Coriolis 1.58 1.58 0.72 Internal waves 1.85 1.85 1.14 1.17. Appendices 253 Croco Documentation, Release 2.1.2 254 Chapter 1. Model Documentation CHAPTER TWO TUTORIALS 2.1 System requirements 2.1.1 Disk space CROCO, CROCO_TOOLS and CROCO_PYTOOLS source codes require less than 500 MB of disk space. Climatological datasets, provided for regional configuration, require about 18 GB of disk space. 2.1.2 Compilers and Libraries CROCO uses Fortran routines as well as cpp-keys. The I/O are in netcdf. It therefore requires to have: •a C compiler •a Fortran compiler •a Netcdf library •MPI libraries and compilers if running in parallel CROCO_TOOLS use Matlab, and Python scripts. CROCO_PYTOOLS use Python scripts and Fortran files interfaced using f2py. 2.1.3 Environment variables A few environment variables for compilers and libraries should be declared to avoid issues when compiling and running CROCO. If you are using Intel compilers for instance, you should declare the followings (in your .bashrc file): export CC=icc export FC=ifort export F90=ifort export F77=ifort For Netcdf, you should also declare your netcdf path, and add it to the PATH and LD_LIBRARY_PATH environment variables. Here is an example: export NETCDF=$HOME/softs/netcdf export PATH=$NETCDF/bin:${PATH} export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${NETCDF}/lib òNote Common errors associated with Netcdf are usually solved by checking that Netcdf is correctly declared in your LD_LIBRARY_PATH 255 Croco Documentation, Release 2.1.2 2.2 Download 2.2.1 Downloading CROCO To perform a regional simulation using CROCO, the modeler needs: •the CROCO source code •the CROCO_TOOLS or CROCO_PYTOOLS scripts, which are tools for preand post-processing using Matlab and/or Python •Datasets to create the input files: –grid –surface atmospheric forcing –oceanic boundaries and initialization 2.2.1.1 Source code CROCO, CROCO_TOOLS and CROCO_PYTOOLS stable releases are available in the Download section: https: //www.croco-ocean.org/download/ They are available as tarball or can be checked-out using git. Follow instructions in the Download stable release section. 2.2.1.2 External datasets Some external datasets are needed by CROCO_TOOLS. Some of them, like bathymetry, tide atlas, atmospheric, oceanic and biogeochemical climatological datasets are directly available in the Datasets section as tarball archives. CROCO_TOOLS and CROCO_PYTOOLS also provide pre-processing scripts for the download and create interannual forcings as: •CFSR, ERA-interim, ERA5 ... for atmospheric forcing •SODA and MERCATOR for the oceanic boundaries and initialization •GLOFAS for the rivers 2.2.2 Getting other codes (coupling) •OASIS coupler To use CROCO in coupled mode (coupling with atmosphere and/or waves), OASIS3-MCT version 3 or later is required. òNote Older versions of OASIS do not include all the necessary functions as grid generation in parallel mode. If you want to use an older version, you need to create your grids.nc, masks.nc, and areas.nc files first, and comment the call to cpl_prism_grids in cpl_prism_define.F To download OASIS3-MCT, you need to register on OASIS website: https://oasis.cerfacs.fr/en/home/ Then, you can download the code from the website or use the git repository: https://gitlab.com/cerfacs/oasis3-mct We advise to use the latest stable release, ie the tag OASIS3-MCT_5.2 of the branch OASIS3-MCT_5.0 git clone --branch OASIS3-MCT_5.0 https://gitlab.com/cerfacs/oasis3-mct.git cd oasis3-mct git checkout OASIS3-MCT_5.2 256 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 •WW3 WaveWatch3 is now hosted on github on a public repository: https://github.com/NOAA-EMC/WW3 .Warning Currently the coupling tools provided in croco are designed to work with the WW3 6.07.1 release plus some additional changes in a few coupled routines in WW3 which are provided in the croco/SCRIPTS/ SCRIPTS_COUPLING/WW3_IN/modified_ftn directory. See readme_ww3_version in WW3_IN. More recent versions of WW3 contains these modifications, but as these more recent versions are currently not tagged as “releases”, we prefer to stick to the latest official release and just change these few modified routines. You can clone the WW3 6.07.1 version with: git clone --branch 6.07.1 --single-branch https://github.com/NOAA-EMC/WW3.git And copy the modified routines: cp ~/croco/croco/SCRIPTS/SCRIPTS_COUPLING/WW3_IN/modified_ftn/*.ftn ~/ww3/model/ftn/. •WRF Currently the distributed version of WRF does not include coupling with waves, and some other functionalities we have recently implemented. We therefore suggest to use the fork including modifications for coupling with WW3 and CROCO through the OASIS coupler, but note that this is a development version... https://github.com/ wrf-croco/WRF/tree/WRF-CROCO You can clone it with git : git clone https://github.com/wrf-croco/WRF.git A tag is available for using the up-to-date wrf-croco version. òNote If using older versions of the wrf-croco fork, you may encounter issues regarding a namelist variable named max_cpldom, which is present in the up-to-date version, but was inexistent in previous version (with older version, you should remove this variable from your namelist.input.base.complete file). We encourage to use the tagged up-to-date version. Other versions of WRF are available here: http://www2.mmm.ucar.edu/wrf/users/download/get_source.html https://github.com/wrf-model/WRF •WPS WRF pre-processing system is also needed to prepare WRF configurations. It is available on the following github repository: https://github.com/wrf-model/WPS You can clone it with git: git clone https://github.com/wrf-model/WPS.git You need to use the same WPS version than the WRF version you use. Currenlty the WRF version on the WRFCROCO fork is WRF4.2.1. You should therefore use the WPS 4.2 version. To do so, with git you can move to the appropriate tag: cd WPS git checkout tags/v4.2 2.2. Download 257 Croco Documentation, Release 2.1.2 2.3 Contents & Architecture 2.3.1 Architecture A classical work architecture consists in: croco/croco croco/croco_tools croco/croco_pytools CONFIGS To run a CROCO simulation, you need to follow these 3 steps: •complete the pre-processing (for realistic cases) => see Pre-processing tutorials using Matlab (croco_tools) or Python (croco_pytools) •set-up the parameters and setting files (param.h and cppdefs.h) and compiled the model •set-up the input file croco.in and run the model CROCO contents, main inputs and setting files are described in the following: 2.3.2 Contents of CROCO source code CROCO and its tools are distributed in separate repositories croco,croco_tools for Matlab version and croco_pytools for Python version. The croco repository contains the model itself with the following directories : AGRIF Agrif library for nesting BENCH Testing script CVTK Regression test library MPI_NOLAND Fortran utility to determine the optimal MPI decomposition to supress land computation MUSTANG MUSTANG sediment model source files OBSTRUCTION OBSTRUCTION module source files OCEAN CROCO source files PISCES PISCES biogeochemical model source files README.md Informations on CROCO version SCRIPTS Scripts for plurimonth runs, online analysis tools, and coupled simulations TEST_CASES Test cases namelists and useful files XIOS XIOS I/O server library create_config.bash Script to setup your configuration. It creates a configuration directory, and copy useful files in it from croco,croco_tools and croco_pytools sources 2.4 Summary of essential steps 1. Compilation CROCO needs to be compiled for each configuration (grid, MPI decomposition, paramterizations...). The files that need to be edited are (available in croco/OCEAN directory): 258 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 cppdefs.h CPP-keys* allowing to select configuration, numerical schemes, parameterizations, forcing and boundary conditions *CROCO 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. param.h Grid settings: the values of the model grid size are: LLm0 points in the X direction MMm0 points in the Y direction N vertical levels For realistic regional cases, LLm0 and MMm0 are given in croco_tools : by running make_grid.m or in croco_pytools : by running make_grid.py N is defined in crocotools_param.m or ibc.ini (IBC_Sigma_params) param.h also contains: Parallelisation settings, Tides, Wetting-Drying, Point sources, Floats, Stations specifications jobcomp the compilation script (including settings for paths, compilers, libraries, etc) 2. Namelist CROCO namelist input file croco.in contains several configurations settings such as: the time stepping, the vertical coordinate settings, the I/O settings and paths, some parameters for the model, ... It has to be edited before running. It is available in croco/OCEAN directory for regional configurations, and in croco/TEST_CASES directory for test cases. 3. Input files CROCO needs the following input files to run: •CROCO grid file: croco_grd.nc •CROCO surface forcing file: croco_frc.nc (or croco_blk.nc) •CROCO vertical boundary conditions: croco_bry.nc (or croco_clim.nc) •CROCO initial conditions: croco_ini.nc They can be created using the Preprocessing Tools (Matlab croco_tools or Python croco_pytools), see dedicated tutorials. These files are eventually not mandatory in test cases for which the useful settings are defined analytically within the CROCO code. 4. Run CROCO can be run in serial or parallel mode. See the run tutorial. 2.4. Summary of essential steps 259 Croco Documentation, Release 2.1.2 (continued from previous page) # Configuration name # ------------------ MY_CONFIG_NAME=BENGUELA_LR # Home and Work configuration directories # --------------------------------------- MY_CONFIG_HOME=~/CONFIGS MY_CONFIG_WORK=~/CONFIGS # Options of your configuration models_incroco=(all-prod ) Run create_config.bash: ./create_config.bash A directory named BENGUEAL_LR should be created. You can also manually create your configuration directory, by copying the required files from croco sources: mkdir ~/CONFIGS/BENGUELA_LR cd ~/CONFIGS/BENGUELA_LR # For compiling cp ~/croco/croco/OCEAN/cppdefs.h. cp ~/croco/croco/OCEAN/param.h. cp ~/croco/croco/OCEAN/jobcomp . # For running cp ~/croco/croco/OCEAN/croco.in . In your configuration working directory, you need at least the following files: •For compiling: –param.h –cppdefs.h –jobcomp •For running: –croco.in 2.7 Preprocessing Preprocessing phase contains all file and configuration preparation before running the model. Depending on the processes you want to take into account you will need diffrent steps of preprocessing, for example for running an interannual regional run you will first need to define : •the grid you will work on •the initial and boundary condition you will use •enventually the atmospheric, tidal or river forcing you will add •... Two possibilities are available to generate the accurate files : •croco_tools : historic tools based on Matlab scripts 266 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 •croco_pytools : tools based on Python scripts 2.7.1 Matlab Tools : croco_tools CROCO preprocessing tools have been developed under Matlab software by IRD researchers (former Roms_tools). These tools have been made to build easily regional configurations using climatological data. To use interannual data, some facilities are available (NCEP, CFSR, QuickScat data for atmospheric forcing, SODA and ECCO for lateral boundaries). However, to use other data, you will need to adapt the scripts. All utilities/toolbox requested for matlab crocotools programs are provided within the UTILITIES directory, or can be downloaded here: http: //www.croco-ocean.org/download/utilities/ The documentation for this toolbox is available at: https://croco-ocean.gitlabpages.inria.fr/croco_tools/ 2.7.2 Python Tools : croco_pytools These python tools bring together the methods of several users of the CROCO community but do not constitute a definitive toolbox. A new, more complete toolbox is under development by the CROCO team. For preprocessing, croco_pytools toolbox consists of prepro directory: a set of python routines, interface with fortran to process the grid and forcing files (initialization, open-boundary conditions, tides forcing, rivers forcing) The documentation for this toolbox is available at: https://croco-ocean.gitlabpages.inria.fr/croco_pytools/ 2.8 Compiling The files that you need to edit for compilation are: cppdefs.h CPP-keys* allowing to select configuration, numerical schemes, parameterizations, forcing and boundary conditions. * CROCO 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. param.h Grid settings, the values of the model grid size are: •LLm0 points in the X direction •MMm0 points in the Y direction •N vertical levels For realistic regional cases, LLm0 and MMm0 are given : •in croco_tools : by running make_grid.m •in croco_pytools : by running make_grid.py N is defined in crocotools_param.m or ibc.ini (IBC_Sigma_params) param.h also contains: Parallelisation settings Tides, Wetting-Drying, Point sources, Floats, Stations specifications jobcomp The compilation script (including settings for paths, compilers, libraries, etc) .Warning CROCO needs to be compiled for each configuration (domain, coupled, uncoupled, parameterizations...), i.e., each time you change something in cppdefs.h or param.h Let’s explore, check, and edit the 3 aforementionned files: 2.8. Compiling 267 Croco Documentation, Release 2.1.2 2.8.1 cppdefs.h Let’s explore, check, and edit: cppdefs.h 1. First section of cppdefs.h defines your configuration (test case or realistic regional case): #undef BASIN /* Basin Example */ #undef CANYON /* Canyon Example */ #undef EQUATOR /* Equator Example */ #undef INNERSHELF /* Inner Shelf Example */ #undef SINGLE_COLUMN /* 1DV vertical mixing Example */ #undef RIVER /* River run-off Example */ #undef OVERFLOW /* Gravitational/Overflow Example */ #undef SEAMOUNT /* Seamount Example */ #undef SHELFRONT /* Shelf Front Example */ #undef SOLITON /* Equatorial Rossby Wave Example */ #undef THACKER /* Thacker wetting-drying Example */ #undef UPWELLING /* Upwelling Example */ #undef VORTEX /* Baroclinic Vortex Example */ #undef INTERNAL /* Internal Tide Example */ #undef IGW /* COMODO Internal Tide Example */ #undef JET /* Baroclinic Jet Example */ #undef SHOREFACE /* Shoreface Test Case on a Planar Beach */ #undef RIP /* Rip Current Test Case */ #undef SANDBAR /* Bar-generating Flume Example */ #undef SWASH /* Swash Test Case on a Planar Beach */ #undef TANK /* Tank Example */ #undef MOVING_BATHY /* Moving Bathymetry Example */ #undef ACOUSTIC /* Acoustic wave Example */ #undef GRAV_ADJ /* Graviational Adjustment Example */ #undef ISOLITON /* Internal Soliton Example */ #undef KH_INST /* Kelvin-Helmholtz Instability Example */ #undef TS_HADV_TEST /* Horizontal tracer advection Example */ #undef DUNE /* Dune migration Example */ #undef SED_TOY /* 1DV sediment toy Example */ #undef TIDAL_FLAT /* 2DV tidal flat Example */ #undef ESTUARY /* 3D tidal estuary Example */ #undef KILPATRICK /* 2D sst front*/ #undef SEAGRASS /* 2DV over seagrass using OBSTRUCTION module*/ For the BENGUELA_LR case we are running, you should have: #define REGIONAL /* REGIONAL Applications */ 2. Then, in cppdefs.h, you have one section for each case. Let’s explore the REGIONAL case section: •First is the name of your configuration: #if defined REGIONAL /* !==================================================================== ! REGIONAL (realistic) Configurations !==================================================================== ! !---------------------- ! BASIC OPTIONS !---------------------- ! */ (continues on next page) 268 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 (continued from previous page) /* Configuration Name */ # define BENGUELA_LR •Then, you can set parallelization option (you can set define MPI if you want to run in parallel) /* Parallelization */ # undef OPENMP # undef MPI •Then, you can set I/O options (XIOS server, netcdf 4 parallel option, NB: we will have a dedicated tutorial on XIOS) /* I/O server */ # undef XIOS •Non-hydrostatic option /* Non-hydrostatic option */ # undef NBQ •Nesting settings /* Nesting */ # undef AGRIF # undef AGRIF_2WAY •Coupling with other models (atmosphere, waves) /* OA and OW Coupling via OASIS (MPI) */ # undef OA_COUPLING # undef OW_COUPLING •Including wave-current interactions /* Wave-current interactions */ # undef MRL_WCI •Managing open boundaries (you can choose to close one of the boundaries, useful in coastal cases) /* Open Boundary Conditions */ # undef TIDES # define OBC_EAST # define OBC_WEST # define OBC_NORTH # define OBC_SOUTH •Activating applications /* Applications */ # undef BIOLOGY # undef FLOATS # undef STATIONS # undef PASSIVE_TRACER # undef SEDIMENT # undef BBL •Defining a dedicated log file for CROCO standard output (default is undef but you can define LOGFILE to facilitate the reading of model output, particularly useful for coupled simulations) 2.8. Compiling 269 Croco Documentation, Release 2.1.2 /* dedicated croco.log file */ # undef LOGFILE .Warning Keep undef LOGFILE is you use Plurimonth run scritps as: run_croco_inter.bash because it already re-direct the CROCO output, and check it... •Time reference setting: .Warning By default no reference time is used, and time is referred to the beginning of the simulation only /* Calendar */ # undef USE_CALENDAR 3. Then you have detailed settings (you can find a description of available cpp keys in cppdefs.h). Let’s just highlight a few ones: •In grid configuration /* Grid configuration */ # define CURVGRID # define SPHERICAL # define MASKING # undef WET_DRY # define NEW_S_COORD .Warning you should check that the vertical coordinate setting NEW_S_COORD is in adequation with your pre-processing setting (vtransform=2 in crocotools_param.m). In croco_pytools, using NEW_S_COORD is mandatory. •In surface forcing subsection: –if you have prepared croco_frc.nc file (using make_frc.m) /* Surface Forcing */ # undef BULK_FLUX –if you have prepared croco_blk.nc file (using make_blk.m) /* Surface Forcing */ # define BULK_FLUX •Then, you have to set your lateral forcing according to your pre-processing as well: –If you have prepared croco_clm.nc file (using make_clim.m) /* Lateral Forcing */ # define CLIMATOLOGY and 270 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 # undef FRC_BRY –Or, if you have prepared croco_bry.nc file (using make_bry.m) /* Lateral Forcing */ # undef CLIMATOLOGY and # define FRC_BRY The other CPP-keys will be explored in other tutorials. 2.8.2 param.h param.h is composed of the following sections: •Dimensions of Physical Grid and array dimensions •MPI related variables •Number maximum of weights for the barotropic mode •OA-Coupling, Tides, Wetting-Drying, Point sources, Floast, Stations •Derived dimension parameters •I/O : flag for type sigma vertical transformation •Number of tracers •Tracer identification indices Most of the time you only need to check/edit the 2 first sections: 1. Check the grid settings: # elif defined BENGUELA_LR parameter (LLm0=41, MMm0=42, N=32) ! BENGUELA_LR •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. 2. Check and eventually edit the parallelization settings: #ifdef MPI integer NP_XI, NP_ETA, NNODES parameter (NP_XI=1, NP_ETA=4, NNODES=NP_XI*NP_ETA) parameter (NPP=1) parameter (NSUB_X=1, NSUB_E=1) #elif defined OPENMP parameter (NPP=4) •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. •AUTOTILING (implemented by L. Debreu): cpp-key that enable to compute the optimum subdomains partition in terms of computation time. 2.8. Compiling 271 Croco Documentation, Release 2.1.2 òNote MPI tiles should be at least 20x20 points. 2.8.3 Compilation using jobcomp Now that your input files are set up, you can proceed to compilation. You have to copy the jobcomp script in your working directory. Here we assume that you have set a few environment variables for compilers and libraries. Here is an example with Intel compilers and a netcdf library located in $HOME/softs/netcdf. Adapt these to your own settings (in your .bashrc file): # compilers export CC=icc export FC=ifort export F90=ifort export F77=ifort export MPIF90=mpiifort # netcdf library export NETCDF=$HOME/softs/netcdf export PATH=$NETCDF/bin:${PATH} export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${NETCDF}/lib To use the jobcomp script, you can first explore the available option through : ./jobcomp -h Available option are : •–src <path> : Specify the CROCO source directory (default: ../croco/OCEAN). •–fc <compiler> : Specify the Fortran compiler (default: gfortran). Available = gfortran, ifort, ifc, nvfortran, pgfortran •–mpif90 <compiler> : Specify the MPI Fortran compiler (default: mpif90). •–fflags <flags> : Specify the compilation flags –default: if fc=ifort or ifx : ‘-O2 -mcmodel=medium -fno-alias -i4 -r8 -fp-model precise’ . –default: if fc=gfortran : ‘-O2 -mcmodel=medium -fdefault-real-8 -fdefault-double-8 -std=legacy’ . –default: if fc=nvfortran or pgfortran : ‘-g -fast -r8 -i4 -mcmodel=medium -Mbackslash’ . •–jobs <flags> : Number of processes for compilation (default: 1). •–netcdf-inc <path> : Specify the NetCDF include directory. (default: nf-config –includedir) •–netcdf-lib <path> : Specify the NetCDF library directory. (default: nf-config –flibs) •–xios-dir <path> : Specify the XIOS root directory. (default: /root/xios) •–prism-dir <path> : Specify the OASIS-MCT root directory. (default: ../../../oasis3-mct/compile_oa3-mct) If you use default options, you can compile with : ./jobcomp > jobcomp.log Or you can for example use ifort instead of gfortran : ./jobcomp --fc ifort --mpif90 mpiifort > jobcomp.log 272 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 If compilation is successful, you should have a croco executable in your directory. You will also find a Compile directory containing the model source files: •.F files: original model source files that have been copied from ~/croco/croco/OCEAN •_.f files: pre-compiled files in which only parts defined by cpp-keys are kept •.o object files 2.8.4 Compilation options A very summarized information on compilation options is given here. For further details, search information on the web, or with your cluster assistance team. Useful informations can also be found on this page: http://www. idris.fr/jean-zay/cpu/jean-zay-cpu-comp_options.html •Optimization options: –-O0,-O1,-O2,-O3,-fast : optimization level. -O0 is no optimization, use it for debug. -O3 and -fast are more agressive optimization options that can lead to problems in reproducibility of your run (especially it is better to avoid -fast). –-xCORE-AVX2 : vectorization option, very agressive optimization => non-reproducibility of CROCO –-fno-alias,-no-fma,-ip : other optimization options, commonly used –-ftz: set to 0 denormal very small numbers. It is set by default with -O1,-O2,-O3 (can be a problem in calculation precision) •Debug options: -O0 -g -debug -fpe-all=0 -no-ftz -traceback -check all -fbacktrace -fbounds-check -finit-real=nan -finit-integer=8888 •Precision and writing options: –-fp-model precise: important to have good precision and reproducibility of your calculations –-assume byterecl: way of writing: byte instead of bit –-convert big_endian: way of writing binaries (important for avoiding huge negative numbers) –-i4, -r8``: way of writing integers and reals (important also for reproducibility between different clusters) –-72: specifies that the statement field of each fixed-form source line ends at column 72. –-mcmodel=medium -shared-intel : do not limit memory to 2Go for data (useful for writing large output files) 2.8.5 Tips in case of errors during compilation In case of strange errors during compilation (e.g. “catastrophic error: could not find ...”), try one of these solutions: •check your home space is not full ;-) •check your paths to compilers and libraries (especially Netcdf library) •check that you have the good permissions, and check that your executable files (configure, make...) do are executable •check that your shell scripts headers are correct or add them if necessary (e.g. for bash: #!/bin/bash) •try to exit/log out the machine, log in back, clean and restart compilation Errors and tips related to netcdf library: •with netcdf 4.3.3.1: need to add the following compilation flag for all models: -mt_mpi The error associated to a missing -mt_mpi flag is of this type: “ /opt/intel//impi/4.1.1.036/intel64/lib/libmpi_mt.so.4: could not read symbols: Bad value “ •with netcdf 4.1.3: do NOT add -mt_mpi flag 2.8. Compiling 273 Croco Documentation, Release 2.1.2 •with netcdf4, need to place hdf5 library path in your environment: export LD_LIBRARY_PATH=YOUR_HDF5_DIR/lib:$LD_LIBRARY_PATH •with netcdf 4, if you use the library splitted in 2: C part and Fortran part, you need to place links to C library before links to Fortran library and need to put both path in this same order in your LD_LIBRARY_PATH In case of ‘segmentation fault’ error: •try to allocate more memory with “unlimited -s unlimited” •try to launch the compilation as a job (batch) with more allocated memory 2.9 Running the model To run the model, you need to have completed pre-processing (for realistic cases) and compilation phases. In your working directory you need to have: •For an idealized simulation (e.g. test cases): croco # model executable croco.in # namelist file (available for each test case croco source directory:␣ ˓→TEST_CASES) •For a realistic simulation: croco # model executable croco.in # namelist file (available in croco source directory: OCEAN) # in CROCO_FILES: croco_grd.nc # grid file croco_bdy.nc or croco_clm.nc # lateral boundary condition file croco_frc.nc or croco_blk.nc # surface forcing file croco_ini.nc # initial condition file 2.9.1 Edit croco.in You first need to set all time, I/O, and different parameters in the CROCO namelist file: croco.in. CROCO namelist file croco.in is set by default for the BENGUELA_LR case. So you should have nothing to change. The detail of all croco.in sections can be found here: croco.in However you can check some settings: •Time stepping: time_stepping: NTIMES dt[sec] NDTFAST NINFO 720 3600 60 1 NTIMES: number of time steps dt[sec]: baroclinic time step NDTFAST: number of barotropic time steps in one baroclinic time step) òNote Your time steps should be set according to the stability constraints: – Barotropic mode ∆𝑡 ∆𝑥√︀𝑔𝐻 ≤0.89 274 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 Note that considering an Arakawa C-grid divides the theoretical stability limit by a factor of 2. So for instance for a maximum depth of 5000 m and a resolution of 30 km: ∆𝑡≤0.89∆𝑥 2.√𝑔𝐻 ∆𝑡≤60𝑠 – 3D advection With 60 barotropic time steps in one baroclinic time step, this results in a baroclinic time step of: ∆𝑡≤3600𝑠 You can check that this time step does not violate your CFL condition for your advection scheme. Typical CFL values for with Croco time-stepping algorithm are Advection scheme Max Courant number C2 1.587 UP3 0.871 SPLINES 0.916 C4 1.15 UP5 0.89 C6 1.00 In the present BENGUELA_LR case, we use UP3: ∆𝑡 ∆𝑥.𝑉𝑚𝑎𝑥 ≤0.871 𝑉𝑚𝑎𝑥 ≤0.87130000 3600 𝑉𝑚𝑎𝑥 ≤7.25𝑚/𝑠 which is a very large allowed maximum horizontal velocity. •Vertical coordinate parameters: .Warning These parameters should be set accordingly to pre-processing. S-coord: THETA_S, THETA_B, Hc (m) 7.0d0 2.0d0 200.0d0 •By default no reference time is used, and time is referred to the beginning of the simulation only using NTIMES. If you want to define the start and stop of the model by dates, you first need to edit cppdefs.h, define this key, and recompile the model: #define USE_CALENDAR Then edit croco.in input file: start_date: 2000-01-01 00:00:00 end_date: 2000-02-01 00:00:00 (continues on next page) 2.9. Running the model 275 Croco Documentation, Release 2.1.2 (continued from previous page) # Number of year that are considered to be part of the spin-up (i.e. 365 days␣ ˓→per year) NY_SPIN=0 Outputs settings # Output frequency [days] - case 1 : No USE_CALENDAR - DEFAULT # average ND_AVG=3 # history (if = -1 set equal to NUMTIMES, the end of each month/year) ND_HIS=-1 # restart (if = -1 set equal to NUMTIMES, the end of each month/year) ND_RST=-1 # Output frequency [hours] - case 2 : USE_CALENDAR - USED ONLY IF USE_CALENDAR # USE_CALENDAR=1 # # average (in hours) NHAVG_UC=$((24)) # history (in hours, if = -1 set equal t NUMTIMES*DT/3600, the end of each␣ ˓→month/year) NHHIS_UC=-1 # restart (in hours, if = -1 set equal to NUMTIMES*DT/3600, the end of each␣ ˓→month/year) NHRST_UC=-1 Restart settings # Restart file - RSTFLAG=0 --> No Restart # RSTFLAG=1 --> Restart RSTFLAG=0 # Exact restart - EXACT_RST=0 --> Exact restart OFF # - EXACT_RST=1 --> Exact restart ON EXACT_RST=0 2. Launch the simulation Copy the adequate job script cp ~/croco/croco/SCRIPTS/example_job_run_croco_inter.pbs . Check the MPI settings and launch the job qsub example_job_run_croco_inter.pbs 3. Check at your outputs: You should have croco_his_Y2000M1.nc croco_his_Y2000M2.nc croco_his_Y2000M3.nc croco_avg_Y2000M1.nc croco_avg_Y2000M2.nc croco_avg_Y2000M3.nc croco_rst.nc .Warning 282 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 If you have an error while you run did not BLOW UP, maybe it is because you have define LOGFILE in your cppdefs.h. For using run_croco_inter.in it should be undef. 2.11.2 Alternative method: online interpolation of atmospheric bulk forcing Instead of pre-processing your atmospheric bulk forcing, you can use online interpolation of atmospheric bulk forcing. To do so: 1. Your atmospheric files need to be in a format readable by CROCO: At the moment the following forcing are implemented for online interpolation: •In Matlab croco_tools : –CFSR data pre-formatted using the script Process_CFSR_files_for_CROCO.sh available in croco_tools –ERAI data pre-formatted using reformat_ECMWF.m (used in make_ECMWF.m in the croco_tools) –AROME data formatted in Meteo France framework •In Python croco_pytools: –ERAI data pre-formatted using download_era5.py 2. Edit cppdefs.h In Surface forcing section # define ONLINE # ifdef ONLINE # undef AROME # undef ERA_ECMWF # endif òNote for ONLINE interpolation, default is CFSR format. AROME and ERA_ECMWF are also available by defining the cpp-keys. 3. Re-compile the model First copy your old executable to keep it, then re-compile cp croco croco.bck ./jobcomp >jobcomp.log.online 4. Link or copy the CFSR files to your DATA directory mkdir DATA/CFSR_Benguela_LR/ #ln -s ~/DATA/METEOROLOGICAL_FORCINGS/CFSR/BENGUELA/CROCO_format/*2005*.nc DATA/ ˓→CFSR_Benguela_LR/. cp ~/DATA/METEOROLOGICAL_FORCINGS/CFSR/BENGUELA/CROCO_format/*2005*.nc DATA/CFSR_ ˓→Benguela_LR/. 5. Check and eventually edit croco_inter.in last section online: byear bmonth recordsperday byearend bmonthend /data path NYONLINE NMONLINE 4 2011 3 ../DATA/CFSR_Benguela_LR/ 6. Re-run the model 2.11. Running with interannual forcing 283 Croco Documentation, Release 2.1.2 qsub example_job_run_croco_inter.sh òNote In case of errors while using ONLINE, it is probably associated to time issues: check the time in your CFSR input files, and check your time origin Yorig. 2.12 Nesting Tutorial Nesting is performed in the model through the AGRIF library. To create a nested configuration: •If you are using Matlab croco_tools, follow the dedicated tutorial in https://croco-ocean.gitlabpages.inria.fr/ croco_tools/ •If you are using Python croco_pytools, follow the dedicated tutorial in https://croco-ocean.gitlabpages.inria. fr/croco_pytools/ 2.13 Adding Rivers If you want to include rivers in your simulation domain, there are several variables to define as: •the number of rivers: Nsrc •the position of the rivers on the model grid: Isrc and Jsrc •the zonal or meridional axis of the river flow: Dsrc •if flow (and concentration) is constant, the flow rate of the river (in m3/s): Qbar (positive or negative) •if flow (and concentration) is variable, and read from a netCDF file, the direction of the flow qbardir: –1 for west-east / south-north –-1 for east-west / north-south •the type of tracer advected by the river: Lsrc •the value/concentration: Tsrc 2.13.1 Constant flow and concentration For this you need to define the cpp-keys in cppdefs.h #define PSOURCE And re-compile. Then in the croco.in file psource: Nsrc Isrc Jsrc Dsrc Qbar [m3/s] Lsrc Tsrc 2 3 54 1 200. T T 20. 15. 3 40 0 200. T T 20. 15. where Nsrc=2 is the number of rivers processed, then each line describes a river. Let’s describe the parameter for river #1: •Isrc=3, Jsrc=54 are the i, j indices where the river is positioned •Dsrc=1 indicates the orientation (here meridional => along V direction) 284 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 •200 is the runoff flow value in m3/s, oriented to the east •T T are true/false indications for reading or not the following variables (here temperature and salinity) •20 and 15 are respectively the temperature and salinity of the river. You can edit these parameters. .Warning The sources points must be placed on U or V points on the C-grid and not on rho-points You can then run the model: qsub job_croco_mpi.pbs 2.13.2 Variable flow read in a netCDF file and constant concentration Instead of using a constant flow, you can use variable flow. For that you need read it from a netcdf file. First define the dedicated cpp-key in cppdefs.h #define PSOURCE_NCFILE And re-compile the model. Then you also need to prepare the netcdf river runoff input file. For that, you can choose one of the option : •If you are using Matlab croco_tools, you can use make_runoff (Rivers/make_runoff.m) which detect the main rivers located in your domain (from RUNOFF_DAI runoff climatology : a global monthly runoff climatology containing the 925 first rivers over the world, from Dai and Trenberth, 2000). See https:// croco-ocean.gitlabpages.inria.fr/croco_tools/ •If you are using Python croco_pytools, you can use make_rivers.py. See https://croco-ocean.gitlabpages. inria.fr/croco_pytools/ .Warning The order of the sources in the croco.in file must match the order of the netcdf file. It’s impliticly the case if you generate your runoff file with the croco_tools or croco_pytools which give you the lines to add into your croco.in 2.13.3 Variable flow and variable concentration from a netCDF file To run CROCO with a variable concentration of river tracers, you need to define the following cpp-key in cppdefs.h #define PSOURCE_NCFILE_TS You also need to prepare your netcdf input file following the tools documentation (Matlab or Python) and adapt your croco.in file : psource_ncfile: Nsrc Isrc Jsrc Dsrc qbardir Lsrc Tsrc runoff file name CROCO_FILES/croco_runoff.nc 2 25340-1 30*T16.0387 25.0368 30190-1 30*T16.1390 25.1136 You also can edit these parameters. 2.13. Adding Rivers 285 Croco Documentation, Release 2.1.2 .Warning The Tsrc value reported in croco.in are the annual-mean tracer values, they are just for information. The real tracer concentration (Tsrc) are read in the runoff netCDF file created. 2.13.4 Using a nest The above procedure can be applied to a nested grid to generate croco_runoff.nc.1 òNote The runoff has a default vertical profile defined in CROCO as an exponential vertical distribution of velocity. It is in analytical.F, subroutine ana_psource if you need to change it. 2.14 Adding tides Using the method described by Flather and Davies [1976], CROCO is able to propagate the different tidal constituents from its lateral boundaries. To do so, you will need to add the tidal components to the forcing file, and define the following cpp keys TIDES, SSH_TIDES and UV_TIDES and recompile the model using jobcomp. To work correctly, the model should use the characteristic method open boundary radiation scheme (cpp key OBC_M2CHARACT defined). .Warning To get a clean signal you need to provide harmonic components from both tide elevation and tide velocity. In case you don’t have velocity harmonics (not defined UV_TIDES) a set of reduced equation is available to compute velocity from SSH (OBC_REDUCED_PHYSICS) 2.14.1 Pre-processing To create a tidal forcing file: •If you are using Matlab croco_tools, follow the dedicated tutorial in https://croco-ocean.gitlabpages.inria.fr/ croco_tools/ •If you are using Python croco_pytools, follow the dedicated tutorial in https://croco-ocean.gitlabpages.inria. fr/croco_pytools/ 2.14.2 Compiling 1. Edit cppdefs.h for defining tides: /* Open Boundary Conditions */ # define TIDES /* Open Boundary Conditions */ # ifdef TIDES # define SSH_TIDES # define UV_TIDES # define POT_TIDES # undef TIDES_MAS # ifndef UV_TIDES (continues on next page) 286 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 (continued from previous page) # define OBC_REDUCED_PHYSICS # endif # define TIDERAMP # endif # define OBC_M2CHARACT # undef OBC_M2ORLANSKI # define OBC_M3ORLANSKI # define OBC_TORLANSKI # undef OBC_M2SPECIFIED # undef OBC_M3SPECIFIED # undef OBC_TSPECIFIED 2. Check/Edit param.h: #if defined SSH_TIDES || defined UV_TIDES integer Ntides ! Number of tides ! ====== == ===== # if defined IGW || defined S2DV parameter (Ntides=1) # else parameter (Ntides=10) # endif #endif .Warning The number of tide components must be coherent with the one defined in crocotools_param.m or in tides.ini 3. Re-compile the model: ./jobcomp >jobcomp_tide.log 2.14.3 Running Run the model qsub job_croco_mpi.pbs 2.15 Post processing 2.15.1 Matlab Tools : croco_tools The croco_gui utility has been developped under Matlab software to visualize CROCO outputs. The documentation for this toolbox is available at: https://croco-ocean.gitlabpages.inria.fr/croco_tools/ 2.15.2 Python Tools : croco_pytools These python tools bring together the methods of several users of the CROCO community but do not constitute a definitive toolbox. A new, more complete toolbox is under development by the CROCO team. For postprocessing, two directories of script are available : •croco_pyvisu: a vizualisation GUI •xcroco: for analysis based on xarray and xgcm 2.15. Post processing 287 Croco Documentation, Release 2.1.2 The documentation for this toolbox is available at: https://croco-ocean.gitlabpages.inria.fr/croco_pytools/ 2.16 NBQ Tutorial CROCO-NBQ kernel solves the compressible and non-hydrostatic Navier-Stokes equations. This kernel can be used to simulate complex nonlinear, nonhydrostatic physics in a realistic but computationally-affordable configuration. Non-hydrostatic effects become important when the horizontal and vertical scales of motion are similar. In oneanic models this typically arises with horizontal scales of the order of 1 km resolved with grid intervals of order 100 m. For motions of larger scale that are resolved with grid intervals of order 1 km, the hydrostatic approximation is well satisfied. Accurate simulation of nonhydrostatic effects requires to resolve very small horizontal scales. The explicit representation of fine-scale turbulent processes requires a significant number of fundamental numerical choices, such as adapted advective schemes, adaptaed parametrizations, adapted boundary conditions ... In the sections you will find some recommendations about the most adapted numerical schemes for Large-Eddy Simulations (LES). 2.16.1 Some important points about Large-Eddy Simulations (LES) •Momentum and tracer advection schemes : Many advection schemes are now implented in CROCO (i.e. section 4.3 of the model documentation) leading to one recurrent question: which scheme is the most apropriate for my configuration? Unfortunately, no advection scheme is perfect for all applications. In eddy-resolving ocean simulations significant gradients due to detached eddies or upwelling can be found. More particularly, in coastal eddy-resolving configurations, salinity may vary from river concentration to ocean concentration within a few kilometres in horizontal leading to the formation of even more stronger gradients. In such cases (if your solution has strong gradients, shocks or propagating fronts), it is recommend to use a total variation bounded (4.3.6.5) or a monotonicity-preserving scheme (section 4.3.6.6). An exemple of numerical artefacs related to the advection schemes: Gibbs phenomenon Numerical experiments with non-monotonic scheme show artificial oscillations of the solution near regions of sharp gradients (figure below). Non-monotonic vertical advection schemes (Akima for TS, Spline for UV) On the contrary, TVD and WENO5 schemes enable sharper shock predictions and as they preserve monotonicity they do not generate spurious oscillations in the solution (figure below). 288 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 Monotonic or quasi-monotonic vertical advection schemes (WENO5 for TS, TVD for UVW) Recommended advection schemes for LES : CPP options of Momentum Advection UV_HADV_WENO5 Activate 5th-order WENOZ quasi-monotone lateral advection scheme for UV UV_VADV_WENO5 Activate 5th-order WENOZ quasi-monotone vertical advection scheme for UV W_HADV_WENO5 Activate 5th-order WENOZ quasi-monotone lateral advection scheme for W (in NBQ simulation) W_VADV_WENO5 Activate 5th-order WENOZ quasi-monotone vertical advection scheme for W (in NBQ simulation) or UV_HADV_TVD Activate Total Variation Diminushing lateral advection scheme for UV UV_VADV_TVD Activate Total Variation Diminushing vertical advection scheme for UV W_HADV_TVD Activate Total Variation Diminushing lateral advection scheme for W (in NBQ simulation) W_VADV_TVD Activate Total Variation Diminushing vertical advection scheme for W (in NBQ simulation) CPP options of Tracer advection TS_HADV_WENO5 Activate 5th-order WENOZ quasi-monotone lateral tracer advection scheme TS_VADV_WENO5 Activate 5th-order WENOZ quasi-monotone vertical tracer advection scheme •Turbulence schemes : MILES & LES approaches In LES, direct transfer ends at the lowest scale resolved, and subgrid dissipation of energy is accomplished by implicit mixing of advection schemes, as well as by explicit parametrization provided by turbulent closure schemes. The choices of advection schemes and/or turbulent closure schemes are thus critical to represent correctly the turbulent energy cascade. Small scales tend to be more isotropic and homogeneous than the large ones, thus LES requires 3D turbulent closure schemes. Two options of 3D turbulent closure schemes are available in CROCO : A generic two-equation turbulence closure model called Generalized Length Scale (GLS) scheme & a Smagorinsky model (i.e. model documentation). An alternative approach is monotonically integrated LES (MILES). In MILES, the dissipative nature of monotonic advection schemes is exploited to provide an implicit model of turbulence. Related CPP options (for users): 2.16. NBQ Tutorial 289 Croco Documentation, Release 2.1.2 GLS_MIX2017_3D Activate 3D Generic Length Scale scheme UV_VIS_SMAGO_3D Activate 3D Smagorinsky SGS model •Options of Bottom boundary layer In coastal seas, the bottom mixed layers may occupy a considerable fraction of the water depth. In contrast, bottom mixed layers in ocean bassins cover only a small portion of the total depth of several thousands of meters. Moreover the strong dissipation of kinetic energy generated by the bed friction can be enhanced in shallow water. Hence the parametrization of the bottom boundary layer dynamic is particularly imortant in coastal large eddy simulations. Some new parametrization options are under development in CROCO to potentially improve the representation of the bottom boundary layers. BSTRESS_FAST allows solving the bottom friction term of the momentum equations at the fast time step (using part of the code structure inherited from the Non-Boussinesq solver). It avoids reducing the slow-mode (baroclinic) time step for cases with high bottom friction or/and high near bottom vertical resolution. This is not yet a default option as it needs further evaluation in various configurations. NBQ_FREESLIP imposes a free-slip boundary condition on the bottom (the normal component of the fluid velocity field is set to zero at the bottom level but the tangential component is unrestricted). This is not a default option, by default a no-slip condition is imposed on the bottom. Further evaluation in various configurations is needed. Related CPP options (for users): NBQ_FREESLIP Activate free-slip boundary condition on the bottom BSTRESS_FAST solve the bottom friction term of the momentum equations at the fast time step 2.16.2 KH_INST Test Case 1. Create a configuration directory: mkdir ~/CONFIGS/KH_INST 2. Copy the input files for compilation from croco sources: cd ~/CONFIGS/KH_INST cp ~/croco/croco/OCEAN/cppdefs.h. cp ~/croco/croco/OCEAN/param.h. cp ~/croco/croco/OCEAN/jobcomp . 3. Edit cppdefs.h for using KH_INST case # define KH_INST # undef REGIONAL Explore the CPP options selected for KH_INST case and undef MPI after #elif defined KH_INST # undef MPI You can check the KH_INST settings in param.h. 4. Edit the compilation script jobcomp: # set source, compilation and run directories # SOURCE=~/croco/croco/OCEAN SCRDIR=./Compile RUNDIR=`pwd` (continues on next page) 290 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 (continued from previous page) ROOT_DIR=$SOURCE/.. # # determine operating system # OS=`uname` echo "OPERATING SYSTEM IS: $OS" # # compiler options # FC=$FC # # set MPI directories if needed # MPIF90=$MPIF90 MPIDIR=$(dirname $(dirname $(which $MPIF90) )) MPILIB="-L$MPIDIR/lib -lmpi -limf -lm" MPIINC="-I$MPIDIR/include" # set NETCDF directories # #----------------------------------------------------------- # Use : #-lnetcdf : version netcdf-3.6.3 -- #-lnetcdff -lnetcdf : version netcdf-4.1.2 -- #-lnetcdff : version netcdf-fortran-4.2-gfortran -- #----------------------------------------------------------- # #NETCDFLIB="-L/usr/local/lib -lnetcdf" #NETCDFINC="-I/usr/local/include" NETCDFLIB=$(nf-config --flibs) NETCDFINC=-I$(nf-config --includedir) 5. Compile the model: ./jobcomp >jobcomp.log If compilation is successful, you should have a croco executable in your directory. You will also find a Compile directory containing the model source files: •.F files: original model source files that have been copied from ~/croco/croco/OCEAN •_.f files: pre-compiled files in which only parts defined by cpp-keys are kept •.o object files 6. Copy the namelist input file for KH_INST case: cp ~/croco/croco/TEST_CASES/croco.in.KH_INST croco.in Eventually edit it. 7. Run the model: ./croco croco.in >croco.out If your run is successful you should obtain the following files: 2.16. NBQ Tutorial 291 Croco Documentation, Release 2.1.2 •always check all the lines associated to netcdf library and dependencies in the generated configure.wrf:NETCDF4_IO_OPTS,NETCDF4_DEP_LIB,INCLUDE_MODULES (last line should be netcdf inlcude path), LIB_EXTERNAL (last line should be netcdf library and its dependencies). 2. Check and edit the generated configure.wrf file. Notably edit the parallel compiler lines DM_FC =mpiifort DM_CC =mpiicc 3. First compile in uncoupled mode ./compile em_real >& compile_uncoupled.log òNote WRF supports using multiple processors for compilation. The default number of processors used is 2. But you can compile with more processors by using the Jenvironment variable set (example for 8 processors: J=-j 8). òNote WRF compilation will take a while (about 1h) and may take a lot of memory. You may need to launch compilation in a job. Examples for a few machines are provided here, along with a script to help you compile: ~/croco/croco/SCRIPTS/SCRIPTS_COUPLING/WRF_IN/*.compile.wrf.* ~/croco/croco/SCRIPTS/SCRIPTS_COUPLING/WRF_IN/make_WRF_compil If compilation is successful, you will find in WRF main directory the following executables: •wrf.exe •real.exe •ndown.exe •tc.exe 4. Copy them to dedicated directory (as well as your configure.wrf, in case you need to recompile) mkdir exe_uncoupled cp configure.wrf exe_uncoupled/. cp main/*.exe exe_uncoupled/. cp compile_uncoupled.log exe_uncoupled/. 5. To compile in coupled mode, you need to edit configure.wrf, first copy it to configure.wrf.coupled cp configure.wrf configure.wrf.coupled And then edit configure.wrf.coupled # Just before: #### Architecture specific settings ####, add for OASIS: OA3MCT_ROOT_DIR = $(OASISDIR) # In: #### Architecture specific settings ####, add -Dkey_cpp_oasis3 : ARCH_LOCAL = -DNONSTANDARD_SYSTEM_FUNC -DWRF_USE_CLM $(NETCDF4_IO_ ˓→OPTS) -Dkey_cpp_oasis3 (continues on next page) 298 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 (continued from previous page) # In: # POSTAMBLE, add includes and libraries associated to OASIS before netcdf␣ ˓→ones, as follows: INCLUDE_MODULES = $(MODULE_SRCH_FLAG) \ $(ESMF_MOD_INC) $(ESMF_LIB_FLAGS) \ -I$(WRF_SRC_ROOT_DIR)/main \ -I$(WRF_SRC_ROOT_DIR)/external/io_netcdf \ -I$(WRF_SRC_ROOT_DIR)/external/io_int \ -I$(WRF_SRC_ROOT_DIR)/frame \ -I$(WRF_SRC_ROOT_DIR)/share \ -I$(WRF_SRC_ROOT_DIR)/phys \ -I$(WRF_SRC_ROOT_DIR)/chem -I$(WRF_SRC_ROOT_DIR)/inc \ -I$(OA3MCT_ROOT_DIR)/build/lib/mct \ -I$(OA3MCT_ROOT_DIR)/build/lib/psmile.MPI1 \ -I$(NETCDFPATH)/include \ LIB_EXTERNAL = \ -L$(WRF_SRC_ROOT_DIR)/external/io_netcdf -lwrfio_nf \ -L$(OA3MCT_ROOT_DIR)/lib -lpsmile.MPI1 -lmct -lmpeu - ˓→lscrip \ -L$(NETCDF)/lib -lnetcdff -lnetcdf Examples of configure.wrf.uncoupled and configure.wrf.coupled are provided in croco/ SCRIPTS/SCRIPTS_COUPLING/WRF_IN/CONFIGURE_WRF/. .Warning Compiling WRF in coupled mode required a lot of memory (>3.5Go). If needed, submit a job with extra-memory to compile. 6. To compile ./clean -a# clean before compilation cp configure.wrf.coupled configure.wrf ./compile em_real >& compile.coupled.log If compilation is successful, you will find in WRF main directory the following executables: •wrf.exe •real.exe •ndown.exe •tc.exe 7. Copy them to dedicated directory (as well as your configure.wrf, in case you need to recompile) mkdir exe_coupled cp configure.wrf exe_coupled/. cp main/*.exe exe_coupled/. cp compile.coupled.log exe_coupled/. òNote Using the WRF moving nest in coupled mode is possible, but only the parent static model can be coupled through OASIS. Feedback between the static parent domain and the moving nest are used to update fields 2.17. Coupling tutorial 299 Croco Documentation, Release 2.1.2 computed at high-resolution in the moving nest on one hand, and coupled to the ocean or wave model in the static parent domain on the other hand. To use this functionnality, WRF has to be compiled with the moving nest option, and a dedicated Registry.EM is available in WRF_IN/FOR_MOVING_NEST to allow the moving nest to receive surface updates from the parent static domain, that is coupled to the ocean or wave model. Copy this Registry.EM in your WRF/Registry directory before compiling with the moving nest option. Warning, this Registry.EM should not be used in “normal” mode (no moving nest). 2.17.2.5 Compiling WPS òNote Note that you should use the WPS version consistent with your WRF version! 1. Enter WPS directory, and configure your compilation cd ~/wrf/WPS ./clean -a ./configure Choose distributed memory option (dm) and compiler option in adequation with your machine setup. 2. Check and edit configure.wps, notably WRF_DIR and compilers WRF_DIR = ../WRF DM_FC =mpiifort DM_CC =mpiicc 3. Compile WPS ./compile >& compile_wps.log If compilation is successful, you will find in your WPS directory geogrid.exe ungrib.exe metgrid.exe Alternatively, a compile_wps.bash and examples of configure.wps are provided in the Coupling_tools/ WRF_WPS. 2.17.2.6 Compiling WW3 .Warning Currently the following compilation procedure, and coupling tools provided in croco are designed to work with the WW3 6.07.1 release plus some additional changes in a few coupled routines in WW3 which are provided in the croco/SCRIPTS/SCRIPTS_COUPLING/WW3_IN directory. See readme_ww3_version in this directory. More recent versions of WW3 contains these modifications, but as these more recent versions are currently not tagged as “releases”, we prefer to stick to the latest official release and just add the few modified routines. 1. First copy the modified routines into WW3 6.07.1 directory: cp ~/croco/croco/SCRIPTS/SCRIPTS_COUPLING/WW3_IN/modified_ftn/*.ftn ~/ww3/model/ ˓→ftn/. 300 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 2. Go to the model bin directory to perform the compilation: cd ~/ww3/model/bin WW3 compilation requests 3 files: •a switch file which contains the parallelisation, and the numerical parameterization setting. These swhiches are keywords listed in a so-called switch file. Many templates are provided by institutions with a suffix switch_*. This file is used during compilation. Open one of the coupled example switch file: switch_OASOCM (for coupling with an ocean model) or switch_OASACM (for coupling with an atmospheric model) –For running in coupled mode, some switches are mandatory: DIST MPI COU OASIS and OASOCM (for coupling with an ocean model) and/or OASACM (for coupling with an atmospheric model) –Also, the switches to interpolate in time current or wind need to be set to 0 in coupled case mode (and forced cases used to compare to coupled mode): CRT0 WNT0 •a comp.COMPILER file •a link.COMPILER file The 2 later files contain useful options and links for compilation. You therefore need to check the ones that you will use depending on you compiler and machine settings. In this tutorial, let’s take the example of comp.Intel and link.Intel files. 3. You can edit the compilation options in comp.Intel, for instance: opt="-c $list -O3 -ip -xHost -no-fma -fp-model precise -assume byterecl -fno- ˓→alias -fno-fnalias -module $path_m" 4. First we will compile WW3 in uncoupled mode. To do that, create an equivalent switch file than switch_OASOCM but without coupling switches: cp switch_OASOCM switch_UNCOUPLED In switch_UNCOUPLED, erase the following switches: COU OASIS OASOCM 5. Now you are ready to setup and compile WW3: ./w3_setup .. -c Intel -s UNCOUPLED ./w3_automake If compilation is successful, you will find your executables in ../exe, you should move these executables to a dedicated directory: mkdir ../exe_UNCOUPLED mv ../exe/* ../exe_UNCOUPLED/. 6. To compile in coupled mode, check that the $OASISDIR variable correctly refers to your OASIS compile directory, and re-setup and re-launch your compilation: For coupling with the ocean ./w3_clean -c ./w3_setup .. -c Intel -s OASOCM ./w3_automake If compilation is successful, you should move your executable to a proper directory mkdir ../exe_OASOCM mv ../exe/* ../exe_OASOCM/. For coupling with the atmosphere 2.17. Coupling tutorial 301 Croco Documentation, Release 2.1.2 ./w3_clean -c ./w3_setup .. -c Intel -s OASACM ./w3_automake If compilation is successful, you should move your executable to a proper directory mkdir ../exe_OASACM mv ../exe/* ../exe_OASACM/. For coupling with both the ocean and the atmosphere, first create a switch_OASOCM_OASACM cp switch_OASOCM switch_OASOCM_OASACM Edit it to have both OASOCM and OASACM switches F90 NOGRB NC4 TRKNC DIST MPI PR3 UQ FLX0 LN1 ST4 STAB0 NL1 BT4 DB1 MLIM TR0 BS0␣ ˓→IC2 IS0 REF1 XX0 WNT2 WNX1 RWND CRT0 CRX1 TIDE COU OASIS OASOCM OASACM O0 O1␣ ˓→O2 O2a O2b O2c O3 O4 O5 O6 O7 And compile ./w3_clean -c ./w3_setup .. -c Intel -s OASOCM_OASACM ./w3_automake If compilation is successful, you should move your executable to a proper directory mkdir ../exe_OASOCM_OASACM mv ../exe/* ../exe_OASOCM_OASACM/. òNote a script to help you compile the various mode is also available in: $HOME/croco/croco/SCRIPTS/ SCRIPTS_COUPLING/WW3_IN/make_WW3_compil 2.17.2.7 Tips in case of errors during compilation In case of strange errors during compilation (e.g. “catastrophic error: could not find ...”), try one of these solutions: •check your home space is not full ;-) •check your paths to compilers and libraries (especially Netcdf library) •check that you have the good permissions, and check that your executable files (configure, make...) do are executable •check that your shell scripts headers are correct or add them if necessary (e.g. for bash: #!/bin/bash) •try to exit/log out the machine, log in back, clean and restart compilation Errors and tips related to netcdf library: •with netcdf 4.3.3.1: need to add the following compilation flag for all models: -mt_mpi The error associated to a missing -mt_mpi flag is of this type: “ /opt/intel//impi/4.1.1.036/intel64/lib/libmpi_mt.so.4: could not read symbols: Bad value “ •with netcdf 4.1.3: do NOT add -mt_mpi flag •with netcdf4, need to place hdf5 library path in your environment: export LD_LIBRARY_PATH=YOUR_HDF5_DIR/lib:$LD_LIBRARY_PATH 302 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 •with netcdf 4, if you use the library splitted in 2: C part and Fortran part, you need to place links to C library before links to Fortran library and need to put both path in this same order in your LD_LIBRARY_PATH In case of ‘segmentation fault’ error: •try to allocate more memory with “unlimited -s unlimited” •try to launch the compilation as a job (batch) with more allocated memory 2.17.3 Simple CROCO-TOY coupled example For this first step towards coupling, we will just use the BENGUELA_LR configuration and add coupling with a toy model that mimics a wave model. The toy model is available in the croco/SCRIPTS/SCRIPTS_COUPLING/ TOY_IN. It consists of a few fortran routines, that exchange variables with OASIS to mimic a wave or atmosphere model. For a more advanced coupling with actual atmospheric and wave models, you can go to the other sections of the coupling tutorial. 2.17.3.1 Get necessary files First create the configuration, here named BENGUELA_TOY: mkdir BENGUELA_TOY Get the useful files for CROCO compilation and settings: cp ~/croco/croco/OCEAN/cppdefs.h. cp ~/croco/croco/OCEAN/param.h. cp ~/croco/croco/OCEAN/jobcomp . cp ~/croco/croco/OCEAN/croco.in . Get the TOY model: cp -r~/croco/croco/SCRIPTS/SCRIPTS_COUPLING/TOY_IN . Get the useful input files: wget "https://data-croco.ifremer.fr/CONFIGS_EXAMPLES/BENGUELA_LR_INPUT_FILES/CROCO_ ˓→FILES.tar.gz" tar -zxvf CROCO_FILES.tar.gz wget "https://data-croco.ifremer.fr/CONFIGS_EXAMPLES/BENGUELA_LR_INPUT_FILES/TOY_ ˓→FILES.tar.gz tar -zxvf TOY_FILES.tar.gz Get some useful scripts: cp -r~/croco/croco/SCRIPTS/SCRIPTS_COUPLING/SCRIPTS_TOOLBOX/OASIS_SCRIPTS . 2.17.3.2 Compile Compile OASIS For running in coupled mode, you need to have OASIS compiled. For OASIS follow the instructions in the Compilation section of the coupling tutorial. We assume here that you have OASIS compiled in ~/oasis/ compile_oasis3-mct Compile CROCO In cppdefs.h in the “REGIONAL (realistic) Configurations” section: 2.17. Coupling tutorial 303 Croco Documentation, Release 2.1.2 #define MPI #define OW_COUPLING #define MRL_WCI òNote MPI is mandatory for coupling, even if the run is launched on 1 CPU. Indeed the MPI communicator is used to communicate with OASIS. Edit all the usual paths, compilers, libraries in jobcomp, and notably OASIS path PRISM_ROOT_DIR: # set OASIS-MCT (or OASIS3) directories if needed # PRISM_ROOT_DIR=~/oasis/compile_oasis3-mct And compile: ./jobcomp >& compile_coupled.log If the compilation is successfull you should have the CROCO executable croco. Compile the TOY model A script make_toy_compil.sh is provided. Check and eventually edit it (notably the line regarding the environment source ../myenv_mypath.sh, that should be adapt to point towards you environment file where the compilers and libraries are defined). You should also check/edit the Makefile.MACHINE for your machine. cd TOY_IN ln -sf Makefile.YOURMACHINE Makefile ./make_toy_compil.sh If the compilation is successfull you should have the TOY executables toy_wav toy_atm toy_oce 2.17.3.3 Prepare the configuration files for a 3-day run Set up CROCO Edit the croco.in: time_stepping: NTIMES dt[sec] NDTFAST NINFO 72 3600 60 1 You can also change the frequency of outputs: history: LDEFHIS, NWRT, NRPFHIS /filename T24 0 CROCO_FILES/croco_his.nc averages: NTSAVG, NAVG, NRPFAVG /filename 1 24 0 CROCO_FILES/croco_avg.nc And set to True the outputs for waves fields: wave_history_fields: hrm frq action k_xi k_eta eps_b eps_d Erol eps_r 20*T wave_average_fields: hrm frq action k_xi k_eta eps_b eps_d Erol eps_r 20*T wci_history_fields: SUP UST2D VST2D UST VST WST AKB AKW KVF CALP KAPS (continues on next page) 304 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 (continued from previous page) 20*T wci_average_fields: SUP UST2D VST2D UST VST WST AKB AKW KVF CALP KAPS 20*T Set-up the TOY model The toy model can send either fields from a model file (for instance generated by running a model in forced mode previously), or constant or sinusoidal fields. Check the readme in TOY_IN for more informations. In every cases, you need to provide a grid to the toy model, here named grid_wav.nc. Here, the toy model will read and exchange variables specified in the TOYNAMELIST.nam from an input file, here named toy_wav.nc. Get the chosen TOYNAMELIST.nam.wav.ow and rename it: cp TOY_IN/TOYNAMELIST.nam.wav.ow TOYNAMELIST.nam.wav You need to edit all the fields denoted into brackets: <...>, as well as the paths towards the input files in TOYNAMELIST.nam.wav: &NAM_OASIS NB_TIME_STEPS=12, DELTA_T=21600, GRID_FILENAME='grid_wav.nc'/ &NAM_FCT_SEND CTYPE_FCT='FILES', CNAME_FILE='toy_wav.nc', VALUE=1/ &NAM_RECV_FIELDS NB_RECV_FIELDS=3, CRCVFIELDS(1)='TOY__SSH', CRCVFIELDS(2)='TOY_UOCE', CRCVFIELDS(3)='TOY_VOCE'/ &NAM_SEND_FIELDS NB_SEND_FIELDS=3, CSNDFIELDS(1)='TOY_T0M1', CSNDFIELDS(2)='TOY___HS', CSNDFIELDS(3)='TOY__DIR'/ In the current example, the toy model is set to run 12 time steps of 21600s. Also, prepare the toy input files. To do so you can use the script provided in OASIS_SCRIPTS/ create_oasis_toy_files.sh: ./OASIS_SCRIPTS/create_oasis_toy_files.sh TOY_FILES/ww3_20050101_20050131.nc toy_wav. ˓→nc ww3 1,12 You should now have toy_wav.nc and grid_wav.nc files. 2.17.3.4 Prepare OASIS files Edit OASIS namelist, namcouple, which specifies which fields will be coupled, and at which frequency, etc. A basis of namcouple files can be found in the croco/SCRIPTS/SCRIPTS_COUPLING/OASIS_IN directory. Copy the relevant namcouple: cp ~/croco/croco/SCRIPTS/SCRIPTS_COUPLING/OASIS_IN/namcouple.base.ow.toywav namcouple In this namcouple,you have to edit all the fields denoted into brackets <...>. Let’s browse the namcouple file. It has several sections: •A first section with general settings: 2.17. Coupling tutorial 305 Croco Documentation, Release 2.1.2 – the number of fields to exchange (in our case 6: 3 from the ocean to the wave model (SSH, UOCE, VOCE), and 3 from the wave to the ocean model (HS, T0M1, DIR)) – the number and names of model executables: here names must be of 6 characters exactly, so you need to move your model executable names to these 6-character names: mv croco crocox cp TOY_IN/toy_wav toywav – the duration of the run in seconds: you need to change <runtime> to your actual duration (3days * 24h * 3600s): 259200 –the debug level (see detailed explanation in the comments in the namcouple file) •A second section, with the informations on exchanged fields. A typical sub-section for one exchanged field looks like: CROCO_SSH TOY__SSH 1<cpldt>1oce.nc EXPORTED <ocenx> <oceny> <wavnx> <wavny>ocnt toyt LAG=<ocedt> R0R0 SCRIPR DISTWGT LR SCALAR LATLON 1 4 – line 1: field in sending model, field in target model, unused, coupling period, number of transformations (here 1 interpolation), restart file, field status – line 2: nb of pts for sending model grid (without halo) first dim, and second dim, for target grid first dim, and second dim, sending model grid name, target model grid name, lag = time step of sending model – line 3: sending model grid periodical (P) or regional (R), and nb of overlapping points, target model grid periodical (P) or regional (R), and number of overlapping points – line 4: list of transformations performed (here only grid interpolation SCRIPR keyword, see OASIS documentation for more informations) – line 5: parameters for each transformation (here distributed weight interpolation, see OASIS documentation for more informations) You need to edit all the fields denoted into brackets: <...>: <cpldt> -> 21600 the coupling frequency in seconds for each field you will exchange <ocenx> -> 41 the number of points in xi direction for CROCO (see param.h) <oceny> -> 42 the number of points in eta direction for CROCO (see param.h) <wavnx> -> 41 the number of points in x direction for the TOY model (see grid_wav.nc file) <wavny> -> 42 the number of points in y direction for the TOY model (see grid_wav.nc file) <ocedt> -> 3600 the CROCO time step <wavdt> -> 21600 the TOY model time step (see TOYNAMELIST.nam) Then, you need to prepare restart files for the coupler (in addition to model initial/restart files). To do so, two scripts are provided in the Coupling tools to start from calm conditions or previously existing files. Here, we will start from calm conditions. Note that this script uses the nco library, so that you should have it installed/loaded to run the script. First, launch the creation of restart file for OASIS for the toy model: •first argument: grid name •second argument: restart file name •third argument: type of model •fourth argument: list of variables to initialize to 0 306 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 ./OASIS_SCRIPTS/create_oasis_restart_from_calm_conditions.sh grid_wav.nc␣ ˓→wav.nc toy "TOY_T0M1 TOY___HS TOY__DIR" Then, do the same for the restart file for OASIS for CROCO model: ./OASIS_SCRIPTS/create_oasis_restart_from_calm_conditions.sh CROCO_FILES/croco_grd.nc␣ ˓→oce.nc croco "CROCO_SSH CROCO_EOCE CROCO_NOCE" You should now have in your configuration directory wav.nc and oce.nc, which are the OASIS restart files. 2.17.3.5 Run the models You are now ready to run CROCO in coupled mode with the toy model: mpirun -np 2toywav : -np 4crocox Or edit and launch a job to run the coupled models. If the run went well, you should have in your configuration directory the following files: grids.nc # grid file for OASIS (created automatically) areas.nc # areas of cells used by some OASIS interpolations (created automatically) masks.nc # masks file for OASIS (created automatically) rmp_ocnt_to_toyt_DISTWGT.nc rmp_toyt_to_ocnt_DISTWGT.nc rmp_ocnu_to_toyt_DISTWGT.nc rmp_ocnv_to_toyt_DISTWGT.nc # weight files for OASIS interpolation (one for each grid␣ ˓→interpolation) nout.000000 # OASIS log file toywav.timers_0000 # OASIS log file for time statistics crocox.timers_0000 # OASIS log file for time statistics debug.root.01 # OASIS log file for the master processor for model #1 (toy in our case) debug.root.02 # OASIS log file for the master processor for model #2 (CROCO in our␣ ˓→case) debug.notroot.01 # OASIS log file for other processors for model #1 (toy in our case) debug.notroot.02 # OASIS log file for other processors for model #2 (CROCO in our␣ ˓→case) OUTPUT_TOY.txt # log file for the toy croco.log # log file for CROCO (if you have define the LOGFILE cpp-key, otherwise␣ ˓→croco log output is in CPL.o???????) òNote If you have problems running the coupled model, you need to check: •The dimensions of the grids in all grid files (models grid files and OASIS grids and masks files) •The debug.root.0? files •The model log files (e.g. croco.log) You can then check your new CROCO outputs in CROCO_FILES (you can see that you have the additional wave fields outputs (e.g. hrm) and you should see small differences of the surface currents for example if you do a difference of coupled and non-coupled CROCO outputs). If you want then to use actual coupling with an atmospheric or wave model, and run production simulation in coupled mode, follow the next steps of the Coupling tutorial. It uses the full Coupling toolbox provided in croco_tools/Coupling_tools and croco/SCRIPTS/SCRIPTS_COUPLING. It will help you create a dedicated architecture for coupled runs, and it will provide you a set of scripts for running coupled simulation without managing all the files one by one. Basically, the Coupling toolbox will manage: 2.17. Coupling tutorial 307 Croco Documentation, Release 2.1.2 2.17.4.3 Create your configuration To prepare your configuration working directory, you can use the script create_config.bash provided in CROCO sources: cp ~/croco/croco/create_config.bash ~/CONFIGS/. Edit your paths and settings in create_config.bash: ˓→#========================================================================================== # BEGIN USER MODIFICATIONS # Machine you are working on # Known machines: Linux DATARMOR IRENE JEANZAY # --------------------------------------------- MACHINE="Linux" # CROCO parent directory # (where croco_tools directory and croco source directory can be found) # ----------------- CROCO_DIR=~/croco/croco TOOLS_DIR=~/croco/croco_tools (continues on next page) 314 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 (continued from previous page) # Configuration name # ------------------ MY_CONFIG_NAME=BENGUELA_cpl # Home and Work configuration directories # --------------------------------------- MY_CONFIG_HOME=~/CONFIGS MY_CONFIG_WORK=~/CONFIGS # Options of your configuration options=(all-prod-cpl ) Run create_config.bash: ./create_config.bash Go into your configuration directory, open, check and eventually edit paths in myenv_mypath.sh, and source it (you need to be in a bash environment): source myenv_mypath.sh It will set a few useful paths and environment variables. 2.17.4.4 Pre-processing for coupled run 2.17.4.4.1 CROCO preprocessing You can run CROCO pre-processing as usual in the $HOME/CONFIGS/BENGUELA_cpl/PREPRO/CROCO directory. See the usual Pre-processing tutorial. 2.17.4.4.2 WW3 pre-processing 2.17.4.4.2.1 WW3 GRIDGEN Preprocessing tools for WW3 have been developed under Matlab software. They are available in the GRIDGEN matlab package (a tutorial is available here: ftp://ftp.ifremer.fr/ifremer/ww3/COURS/WAVES_SHORT_ COURSE/TUTORIALS/TUTORIAL_GRIDGEN/waves-workshop-exercise-gridgen.pdf). Basic steps for regular grids are summarized here: 1. Define your grid parameters dx= ... # in degrees dy= ... # in degrees lon1d=[...:dx:...]# in degrees lat1d=[...:dy:...]# in degrees [lon,lat]=meshgrid(lon1d,lat1d); 2. Coastline (defined as polygons in coastal bound ....mat) and bathy (e.g., etopo1.nc) files are used. Some threshold values are set up lim_wet=... ;# proportion of cell from which it is considered " wet" cut_off=0;# depth at which cell is considered as "wet" dry_val=999;# value given to "dry" cells 3. Grid can then be generated 2.17. Coupling tutorial 315 Croco Documentation, Release 2.1.2 depth=generate_grid(lon,lat,ref_dir,’etopo1’,’lim_wet,cut_off, dry_val) 4. Definition of boundaries lon_start=min(min(lon))-dx; lon_end=max(max(lon))+dx; lat_start=min(min(lat))-dy; lat_end=max(max(lat))+dy; coord=[lat_start lon_start lat_end lon_end]; [b,n]=compute_boundary(coord,bound,1); 5. Mask generation (use of bathy and coastline) m=ones(size(depth)); m(depth==dry_val)=0; b_split=split_boundary(b,5*max([dx dy])); # splitting to make computation more␣ ˓→efficient lim_wet=0.5; offset=max([dx,dy]); # mask cleaning remove lonely wet cells close to the coastline: m2=clean_mask(lon,lat,m,b_split,lim_wet,offset); cell_limit=-1;# if this value is negative all water bodies except the larger␣ ˓→are considered dry (\ie remove all lakes or closed seas), if positive: has to␣ ˓→be the minimum number of cells to consider a body as water glob=0;# if global or not [m4,mask_map]=remove_lake(m2,cell_limit,glob); 6. To make a grid from another model grid: •read bathymetry and mask from your model file •write the bathymetry thanks to write ww3file function, note that WW3 is expecting negative depth in the ocean write_ww3file([data_dir,’/’,’bottomm2’,’.inp’],depth’.*(-1)); •build the mask for WW3: mask=1 is water, mask=0 is for points which won’t be computed, mask=2 for active boundary points •write the mask file write_ww3file([data_dir,’/’,’mapsta’,’.inp’],mm’); 2.17.4.4.2.2 Alternative Alternatively, you can build the grid input files from a CROCO grid file. A script is provided in Coupling_tools/ WW3:make_ww3_grd_input_files_from_croco_grd.m .Warning Do not put the mask to 0 all around your domain, it will create problems in OASIS interpolations. You can either set 1 for sea points or 2 for boundary points. 2.17.4.4.2.3 Wind, current, and water level forcings Eventually, wind, current, and water level forcing files with a valid time axis have to be prepared (if you need them as forcing for your WW3 run, not requested in full ocean-wave-atmosphere coupled mode). 316 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 A few scripts for preparing ww3 forcing files from CROCO (current and water level, WRF (wind) and CFSR (wind) files already processed through Process_CFSR_files_for_CROCO.sh are provided in croco_tools/ Coupling_tools/WW3: •script_make_CROCO_current_and_level_for_ww3.sh •script_make_WRF_wind_for_ww3.sh •script_make_CFSR_wind_for_ww3.sh WW3 routines are named ww3_ROUTINENAME and take as input file by default: ww3_ROUTINENAME.inp. You have to set parameters in these .inp input files before running. Steps for WW3 pre-processing are ./ww3_grid # To prepare the grid and run (NB: timesteps are defined in ww3_grid.inp␣ ˓→file) ./ww3_prnc # To prepare wind forcing if you want to use one (not mandatory) ./ww3_strt # To prepare initialisation (not mandatory, will take defalut rest state␣ ˓→if not runned) ./ww3_bounc # To prepare spectral boundary conditions (not mandatory, will take␣ ˓→initial state as boundary conditions if not runned) These steps will be performed automatically by the coupling scripts, when you submit the job. òNote Note on mask/mapsta and bathy in WW3: The input map status (MAPSTA) value in the mask file can be : •-2 : excluded boundary points (sea points covered by ice) •-1 : excluded sea points (sea points covered by ice) •0 : excluded points (land) •1 : sea points (ocean) •2 : active boundary points •3 : excluded •7 : ice The final possible values of the output map status MAPSTA are : •-5 : other disabled point •-4 : point masked in the two-way nesting •-3 : dry point covered by ice •-2 : dry point, not covered by ice •-1 : wet point covered by ice •0 : land point •1 : active sea point •2 : active boundary point •8 : excluded sea/ice point •7 : excluded sea point, considered iced •15 : excluded sea point, considered dried: can become wet •31 : excluded sea point, inferred in nesting •63 : excluded sea point, masked in 2-way nesting 2.17. Coupling tutorial 317 Croco Documentation, Release 2.1.2 Coastline limiting depth (m, negative in the ocean) defined in ww3 grid.inp will also affect your MAPSTA: points with depth values above this coastline limit will be transformed to land points and therefore considered as excluded points (never become wet points, even if the water level grows over). In the output of the model, the depth (dpt) is described as : DEPTH = LEV - BATHY, in which the bathy is negative in the sea and positive on land, so the depth will be positive in the sea and a fillvalue on land. When the input water level (LEV) increases, it increases the output depth (DPT) value. The input water level forcing value is stored in WLV output variable, thus it gives the possibility to retrieve the input bathy value at each grid point : BATHY = WLV - DPT. 2.17.4.4.3 WRF preprocessing WRF pre-processing system is WPS. .Warning It should be downloaded in the same version than WRF. Instructions, and scripts are provided in ~/croco/croco_tools/Coupling_tools/WRF_WPS. You can follow the instructions given in readme_wps, and use the provided scripts: run_wps.bash,job.wps.* Note: you will need to have WPS compiled before (see preivous compilation tuto). 2.17.4.4.3.1 Running WPS WRF pre-preocessing with WPS contains 3 steps: •geogrid: defining the horizontal domain and interpolating geographical static data •ungrib: decoding Grib meteorological data from reananlyses (or so) •metgrid: interpolating meteorological data on the model grid To run WPS, you therefore need: •Geographical data Geographical data for WRF are available on WRF users website http://www2.mmm. ucar.edu/wrf/users/download/get_source.html. Geographical data will be available following the link ”here” under WPS download section. You can download the full complete set, but note that topo files are not all in it. Download them individually in addition (e.g. topo_30s). Note that Geographical data file is a VERY LARGE file (49 Go uncompressed). Uncompress them (tar xvjf or tar -zxvf). •Reanalysis data in grib format (from CFSR for example) to build the boundary and initial conditions. For example, CFSR data can be downloaded from: https://rda.ucar.edu/datasets/ds093.0/index.html#!description A dedicated readme for CFSR data download is provided in croco_tools/Coupling_tools/WRF_WPS. You can use g1print.exe or g2print.exe (depending on you grib data format) available in WPS/ungrib/ to check the variables in your data files. Usage is ./g2print.exe YOURDATAFILE •Vtable to read the grib data: exsiting Vtables can be found in WPS source directory under WPS/ungrib/ Variable_Tables, and informations to choose Vtables can be found here: http://www2.mmm.ucar.edu/ wrf/users/download/free_data.html òNote For CFSR, you will need 2 Vtables: one for the fields on pressure levels, one for the fields on surface level. Both Vtables are available in croco_tools/Coupling_tools/WRF_WPS directory Vtable.CFSR_press_pgbh06 Vtable.CFSR_sfc_flxf06 318 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 ungrib therefore needs to be run twice (once for each type). This is done in run_wps.bash (see below). A few scripts have been made to help you run WPS. You can find them in your croco_tools/Coupling_tools/ WRF_WPS directory: •configure.namelist.wps •run_wps.bash •job.wps.* 1. You should find them in YOURCONFIG/PREPRO/WRF_WPS. Edit all the required lines in configure. namelist.wps, and edit all the required paths in run_wps.bash 2. Run WPS directly (or using job.wps.pbs if you need to submit it in batch) ./run_wps.bash configure.namelist.wps NBPROCS >& run_wps.log If WPS is successful, you will obtain in ~/CONFIGS/BENGUELA_cpl/WRF_FILES/WPS_DATA geo_em.d01.nc geo_em.d02.nc met_em.d01.....nc # numerous files where ’...’ are dates met_em.d02.....nc # numerous files where ’...’ are dates 3. Check your metgrid files by looking at some variables with ncview (e.g. LANDMASK, PSFC, PSML, SKINTEMP, TT ...) If some variables are missing, it is probably because you did not process ungrib and metgrid for all your input data. If something appears weird, it may be due to a bad interpolation (for example due to a too coarse land-sea mask in the original data). If so, re-run WPS with an updated METGRID.TBL 2.17.4.4.3.2 Running real.exe After running WPS pre-processing, you need to run real.exe program which actually creates WRF input files for realistic cases from WPS generated files. .Warning You need to use real.exe from uncoupled compilation even for a coupled run A script has been made to help you run real.exe:run_real.bash. You can find it in your ~/CONFIGS/ BENGUELA_cpl/WRF_IN directory or in the croco/SCRIPTS/SCRIPTS_COUPLING/WRF_IN. It also uses: •configure.namelist.real •namelist.input.base.complete 1. Edit all the required lines in configure.namelist.real, and edit all the required paths in run_real. bash 2. Eventually edit namelist.input.base.complete with you choice of parameterization. DO NOT EDIT the stuff placed into brackets: <...>, it will be replaced by run_real.bash with appropriate values. .Warning For coupling with waves and currents, only YSU surface and boundary layer schemes are possible at the moment. Be sure to select these. 3. Run run_real.bash (eventually using a batch job as job.real.pbs): 2.17. Coupling tutorial 319 Croco Documentation, Release 2.1.2 ./run_real.bash configure.namelist.real NBPROCS >& run_real.log If real is successful, you will obtain in ~/CONFIGS/BENGUELA_cpl/WRF_FILES/YYYY wrfinput_d01_DATE wrfbdy_d01_DATE wrflowinp_d01_DATE # if sst_update is set to 1 wrfdda_d01_DATE # if nudging is activated i wrf*_d02_DATE # if you have 2 domains 2.17.4.4.3.3 Additional pre-processing for coupled runs In addition to traditional WRF pre-processing, you will need to: •edit options in namelist.input: –in &physics: isftcflx = 5 if your are coupling with a wave model –in &physics: sst_update = 1 if your are coupling with an ocean model –in &domains: num_ext_model_couple_dom = X : number of domains of the other model you are coupling to WRF ∗edit CPLMASK variable in wrfinput_d0X for all your coupled domains: ·CPLMASK=1 where you want to couple ·CPLMASK=0 when you do no want to couple –you may need to create a WRF grid file for OASIS, if you are using the distributed version of WRF (at the date of 2021-Nov). If you are using the github WRF-CROCO version, you don’t need to create this grid file, it will be created automatically. If necessary, a script is provided in croco/SCRIPTS/ SCRIPTS_COUPLING/SCRIPTS_TOOLBOX/OASIS_SCRIPTS: Edit and run create_oasis_grids_for_wrf.sh Note that the CPLMASK creation may also be performed automatically in the coupling tools. 2.17.4.4.4 OASIS pre-processing In SCRIPTS_TOOLBOX/OASIS_SCRIPTS you have several scripts to help you prepare: •WRF grid files for OASIS: create_oasis_grids_for_wrf.sh •and eventually create oasis restart files from calm or preexisting model outputs: create_oasis_restart_from_calm_conditions.sh create_oasis_restart_from_preexisting_output_files.sh This step is also performed automatically by the coupling tools when launching the run with submitjob.sh. 2.17.4.5 Running in COUPLED mode To run models in coupled mode, you need to have completed the compilation and the preprocessing phases for each model. Then choose the case you desire in the list below: 2.17.4.5.1 CROCO-TOY (wav or atm) myenv_mypath.sh should already have been filled in before the compilation. In TOY_IN, you must have the executable toy_wav. First go to the “Compiling in coupled mode” section otherwise. To prepare the run you need to modify the files myjob.sh and mynamelist.sh. •In myjob.sh , you will have to fill in information about dates, job sequence: 320 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 # Real job duration in sec (converted to MACHINE format in submit job) export TIMEJOB=1800 #------------------------------------------------------------------------------- # Run date settings #------------------------------------------------------------------------------- # Your run can be divided into several jobs (e.g.: 1 year run into 12 jobs of 1␣ ˓→month) # Start date of the first Job export YEAR_BEGIN_JOB=2005 export MONTH_BEGIN_JOB=1 export DAY_BEGIN_JOB=1 # Duration of each Job export JOB_DUR_MTH=1 export JOB_DUR_DAY=0 # How many jobs do you want to launch? export NBJOB=1 # Do we start from a restart? export RESTART_FLAG="FALSE" Along with the number of cpu you will use for each model # nb of CPUs for each model export NP_OCEX=2 export NP_OCEY=2 export NP_TOY=2 •In mynamelist.sh, first specify the run type, and the name of the experiment: # Run type (o/a/w, w.Afrc, oa, 2o1a, owa, owa.full...) # - Will select the models to use reading letters o/w/a/toywav/toyoce/toyatm # - Will select the executables, and some options (see in the following␣ ˓→sections) # - In coupled mode corresponds to the suffix of the OASIS_IN/namcouple.base. ˓→$RUNtype to use export RUNtype=ow.toywav export MOD=`echo $RUNtype | cut -d . -f 1` # Name of the experiment you are about to launch (max 30. CHAR) export CEXPER=BENGUELA_example_${RUNtype} Then, there is a section indicating where the run will be executed and where the outputs and restarts will be stored: #------------------------------------------------------------------------------- # RUN_DIR #------------------------------------------------------------------------------- export EXEDIR_ROOT="$CWORK/rundir/${CEXPER}_execute" export OUTPUTDIR_ROOT="$CWORK/rundir/${CEXPER}_outputs" export RESTDIR_ROOT="$CWORK/rundir/${CEXPER}_restarts" export JOBDIR_ROOT=${CHOME}/jobs_${CEXPER} 2.17. Coupling tutorial 321 Croco Documentation, Release 2.1.2 Then, there are sections for the different components. For the coupler settings: #------------------------------------------------------------------------------- # CPL #------------------------------------------------------------------------------- # Namelist #--------- # Note: namelist example files are provided in OASIS_IN/ # if you want to use a pre-built weight file for grid interpolations, point to # e.g. namcouple.base.oa.smtho2a export namcouplename=namcouple.base.${RUNtype} # Coupling frequency #------------------- export CPL_FREQ=21600 # Restart files for OASIS #------------------------ # If TRUE: create OASIS restart files from pre-existing atm/oce/wav outputs. # If FALSE: create OASIS restart files from calm conditions (need to read at␣ ˓→least the grid for each model) export CPL_restart="FALSE" export oce_rst_file="${OCE_FILES_DIR}/croco_grd.nc" export oce_rst_timeind=-1 # time index (-1 is last) in the file to extract as␣ ˓→restart export atm_rst_file="${ATM_FILES_DIR}/wrfinput_dXX_2005_01_01_00" # the domain␣ ˓→dXX will be automatically replaced export atm_rst_timeind=-1 # time index (-1 is last) in the file to extract as␣ ˓→restart export wav_rst_file="${WAV_FILES_DIR}/ww3.200501.nc" export wav_rst_timeind=-1 # time index (-1 is last) in the file to extract as␣ ˓→restart You should check the coupling frequency, the restart flag and path towards model files to use to create oasis restart files. For CROCO settings, first indicate if you request CROCO compilation: #------------------------------------------------------------------------------- # OCE #------------------------------------------------------------------------------- # Where to find or put the croco execuatble export OCE_EXE_DIR=${CHOME}/CROCO_IN # Online Compilation #------------------- #!!!!!!! IMPORTANT NOTE !!!!!!! # If activated, creates croco executable depending on this namelist. # - In param.h it modifies the grid size, the number of procs in x and y␣ ˓→direction with those given in myjob.sh # - In cppdefs.h it modifies the following options with informations given␣ ˓→below # MPI, OA_COUPLING, OW_COUPLING, MRL_WCI, # XIOS, LOGFILE, MPI_NOLAND, # AGRIF, AGRIF_2WAY, (continues on next page) 322 Chapter 2. Tutorials Croco Documentation, Release 2.1.2 (continued from previous page) # BULK_FLUX, ONLINE, AROME, ARPEGE, ERA_ECMWF # FRC_BRY, CLIMATOLOGY # TIDES, PSOURCE, PSOURCE_NCFILE, PSOURCE_NCFILE_TS # Other changes of parameterizations, numerical schemes, etc should be made "by␣ ˓→hand" in CROCO_IN/cppdefs.h.base #!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! export ONLINE_COMP=1 Then, edit model time steps: # Time steps #----------- export DT_OCE=3600 export NDTFAST=60 Then several options for zooms, wave coupling are provided. They are generally automatically set-up depending on the RUNtype defined at the beginning. Then, edit the options regarding the forcing files: # Forcings #--------- export ini_ext='ini_SODA'# ini extension file (ini_SODA,...) export bdy_ext='bry_SODA'# bry extension file (clm_SODA,bry_SODA,...) # flag for surface forcing should be true except in the case of atm coupling if [[ $MOD =~ .*a.* ]] ; then export surfrc_flag="FALSE" else export surfrc_flag="TRUE" fi export interponline=0 # switch (1=on, 0=off) for online surface interpolation.␣ ˓→Only works with MONTHLY input files! export frc_ext='blk_ERA5'# surface forcing extension(blk_ERA5, frc_ERA5,...).␣ ˓→If interponline=1 precise the type (ERA_ECMWF or AROME, [CFSR by default],␣ ˓→names as cppkey name in croco) export tide_flag="FALSE" # the forcing extension must be blk_??? otherwise tide␣ ˓→forcing overwrites it export river_flag="FALSE" Finally edit CROCO output settings: # Output settings #---------------- #!!! WARNING: when XIOS is activated the following values (for the model) are␣ ˓→not taken into account export oce_his_sec=86400 # history output interval (in number of second) export oce_avg_sec=86400 # average output interval (in number of second) Then go down to the TOY model section, and set the toy options, and model files the toy model should use: #------------------------------------------------------------------------------- # TOY #------------------------------------------------------------------------------- # Where to find the toy executable(s) (continues on next page) 2.17. Coupling tutorial 323 Croco Documentation, Release 2.1.2 (continued from previous page) # Duration of each Job export JOB_DUR_MTH=1 export JOB_DUR_DAY=0 # How many jobs do you want to launch? export NBJOB=1 # Do we start from a restart? export RESTART_FLAG="FALSE" Along with the number of cpu you will use for each model # nb of CPUs for each model export NP_OCEX=2 export NP_OCEY=2 export NP_WAV=14 •In mynamelist.sh, first specify the run type, and the name of the experiment: # Run type (o/a/w, w.Afrc, oa, 2o1a, owa, owa.full...) # - Will select the models to use reading letters o/w/a/toywav/toyoce/toyatm # - Will select the executables, and some options (see in the following␣ ˓→sections) # - In coupled mode corresponds to the suffix of the OASIS_IN/namcouple.base. ˓→$RUNtype to use export RUNtype=ow export MOD=`echo $RUNtype | cut -d . -f 1` # Name of the experiment you are about to launch (max 30. CHAR) export CEXPER=BENGUELA_example_${RUNtype} Then, there is a section indicating where the run will be executed and where the outputs and restarts will be stored: #------------------------------------------------------------------------------- # RUN_DIR #------------------------------------------------------------------------------- export EXEDIR_ROOT="$CWORK/rundir/${CEXPER}_execute" export OUTPUTDIR_ROOT="$CWORK/rundir/${CEXPER}_outputs" export RESTDIR_ROOT="$CWORK/rundir/${CEXPER}_restarts" export JOBDIR_ROOT=${CHOME}/jobs_${CEXPER} Then, there are sections for the different components. For the coupler settings: #------------------------------------------------------------------------------- # CPL #------------------------------------------------------------------------------- # Namelist #--------- # Note: namelist example files are provided in OASIS_IN/ # if you want to use a pre-built weight file for grid interpolations, point to (continues on next page) 330 Chapter 2. Tutorials [Document text truncated for crawler view.]