MITgcm Documentation - Read the Docs

MITgcm DocumentationRelease 10

Alistair Adcroft Jean-Michel Campin Stephanie DutkiewiczConstantinos Evangelinos David Ferreira Mick FollowsGael Forget Baylor Fox-Kemper Patrick Heimbach Chris HillEd Hill Helen Hill Oliver Jahn Martin Losch John MarshallGuillaume Maze Dimitris Menemenlis and Andrea Molod

Feb 09 2018

Contents

1 Overview 111 Introduction 112 Illustrations of the model in action 4

121 Global atmosphere lsquoHeld-Suarezrsquo benchmark 5122 Ocean gyres 5123 Global ocean circulation 7124 Convection and mixing over topography 9125 Boundary forced internal waves 9126 Parameter sensitivity using the adjoint of MITgcm 11127 Global state estimation of the ocean 11128 Ocean biogeochemical cycles 14129 Simulations of laboratory experiments 14

13 Continuous equations in lsquorrsquo coordinates 15131 Kinematic Boundary conditions 18132 Atmosphere 18133 Ocean 19134 Hydrostatic Quasi-hydrostatic Quasi-nonhydrostatic and Non-hydrostatic forms 20135 Solution strategy 23136 Finding the pressure field 23137 Forcingdissipation 26138 Vector invariant form 27139 Adjoint 27

14 Appendix ATMOSPHERE 27141 Hydrostatic Primitive Equations for the Atmosphere in Pressure Coordinates 27

15 Appendix OCEAN 30151 Equations of Motion for the Ocean 30

16 Appendix OPERATORS 34161 Coordinate systems 34

2 Discretization and Algorithm 3721 Notation 3722 Time-stepping 3823 Pressure method with rigid-lid 3924 Pressure method with implicit linear free-surface 4125 Explicit time-stepping Adams-Bashforth 4226 Implicit time-stepping backward method 42

27 Synchronous time-stepping variables co-located in time 4428 Staggered baroclinic time-stepping 4729 Non-hydrostatic formulation 50210 Variants on the Free Surface 52

2101 Crank-Nicolson barotropic time stepping 532102 Non-linear free-surface 54

211 Spatial discretization of the dynamical equations 592111 The finite volume method finite volumes versus finite difference 592112 C grid staggering of variables 602113 Grid initialization and data 602114 Horizontal grid 602115 Vertical grid 632116 Topography partially filled cells 64

212 Continuity and horizontal pressure gradient term 65213 Hydrostatic balance 65214 Flux-form momentum equations 66

2141 Advection of momentum 672142 Coriolis terms 672143 Curvature metric terms 682144 Non-hydrostatic metric terms 692145 Lateral dissipation 692146 Vertical dissipation 712147 Derivation of discrete energy conservation 722148 Mom Diagnostics 72

215 Vector invariant momentum equations 742151 Relative vorticity 752152 Kinetic energy 752153 Coriolis terms 762154 Shear terms 762155 Gradient of Bernoulli function 772156 Horizontal divergence 772157 Horizontal dissipation 772158 Vertical dissipation 78

216 Tracer equations 782161 Time-stepping of tracers ABII 78

217 Linear advection schemes 802171 Centered second order advection-diffusion 802172 Third order upwind bias advection 812173 Centered fourth order advection 822174 First order upwind advection 82

218 Non-linear advection schemes 832181 Second order flux limiters 832182 Third order direct space time 842183 Third order direct space time with flux limiting 852184 Multi-dimensional advection 86

219 Comparison of advection schemes 86220 Shapiro Filter 94

2201 SHAP Diagnostics 94221 Nonlinear Viscosities for Large Eddy Simulation 95

2211 Eddy Viscosity 952212 Mercator Nondimensional Equations 100

3 Getting Started with MITgcm 10331 Where to find information 103

32 Obtaining the code 103321 Method 1 104322 Method 2 104

33 Updating the code 10434 Model and directory structure 10535 Building the code 106

351 Buildingcompiling the code elsewhere 107352 Using genmake2 107353 Building with MPI 109

36 Running the model 110361 Running with MPI 110362 Output files 111363 Looking at the output 112

37 Customizing the model configuration 113371 Parameters Computational Domain Geometry and Time-Discretization 113372 Parameters Equation of State 114373 Parameters Momentum Equations 115374 Parameters Tracer Equations 116375 Parameters Simulation Controls 117376 Parameters Default Values 118

4 MITgcm Tutorial Example Experiments 12341 Barotropic Gyre MITgcm Example 123

411 Equations Solved 124412 Discrete Numerical Configuration 124413 Code Configuration 125

42 A Rotating Tank in Cylindrical Coordinates 130421 Equations Solved 130422 Discrete Numerical Configuration 130423 Code Configuration 130

5 Contributing to the MITgcm 13751 Bugs and feature requests 13752 Using Git and Github 137

521 Quickstart Guide 138522 Detailed guide for those less familiar with Git and GitHub 138

53 Coding style guide 144531 Automatic testing with Travis-CI 144

54 Contributing to the manual 144541 Section headings 144542 Internal document references 144543 Other embedded links 145544 Symbolic Notation 145545 Figures 145546 Tables 146547 Other text blocks 147548 Other style conventions 147549 Building the manual 148

55 Reviewing pull requests 148

6 Software Architecture 151

7 Automatic Differentiation 153

8 Packages I - Physical Parameterizations 155

81 Overview 155811 Using MITgcm Packages 155

82 Packages Related to Hydrodynamical Kernel 160821 Generic AdvectionDiffusion 160822 Shapiro Filter 161823 FFT Filtering Code 162824 exch2 Extended Cubed Sphere Topology 162825 Gridalt - Alternate Grid Package 169

83 General purpose numerical infrastructure packages 173831 OBCS Open boundary conditions for regional modeling 173832 RBCS Package 180833 PTRACERS Package 182

84 Ocean Packages 185841 GMREDI Gent-McWilliamsRedi SGS Eddy Parameterization 185842 KPP Nonlocal K-Profile Parameterization for Vertical Mixing 192843 GGL90 a TKE vertical mixing scheme 198844 OPPS Ocean Penetrative Plume Scheme 198845 KL10 Vertical Mixing Due to Breaking Internal Waves 198846 BULK_FORCE Bulk Formula Package 201847 EXF The external forcing package 205848 CAL The calendar package 213

85 Atmosphere Packages 217851 Atmospheric Intermediate Physics AIM 217852 Land package 219853 Fizhi High-end Atmospheric Physics 220

86 Sea Ice Packages 258861 THSICE The Thermodynamic Sea Ice Package 258862 SEAICE Package 263

9 Packages II - Diagnostics and IO 279

10 Ocean State Estimation Packages 281101 ECCO model-data comparisons using gridded data sets 281

1011 Generic Cost Function 2821012 Generic Integral Function 2851013 Custom Cost Functions 2851014 Key Routines 2861015 Compile Options 286

102 PROFILES model-data comparisons at observed locations 286103 CTRL Model Parameter Adjustment Capability 288104 SMOOTH Smoothing And Covariance Model 290105 The line search optimisation algorithm 290

1051 General features 2901052 The online vs offline version 2901053 Number of iterations vs number of simulations 291

11 Under Development 297

12 Previous Applications of MITgcm 299

Bibliography 301

CHAPTER 1

Overview

This document provides the reader with the information necessary to carry out numerical experiments using MITgcmIt gives a comprehensive description of the continuous equations on which the model is based the numerical algorithmsthe model employs and a description of the associated program code Along with the hydrodynamical kernel physicaland biogeochemical parameterizations of key atmospheric and oceanic processes are available A number of examplesillustrating the use of the model in both process and general circulation studies of the atmosphere and ocean are alsopresented

11 Introduction

MITgcm has a number of novel aspects

bull it can be used to study both atmospheric and oceanic phenomena one hydrodynamical kernel isused to drive forward both atmospheric and oceanic models - see Figure 11

bull it has a non-hydrostatic capability and so can be used to study both small-scale and large scaleprocesses - see Figure 12

bull finite volume techniques are employed yielding an intuitive discretization and support for the treat-ment of irregular geometries using orthogonal curvilinear grids and shaved cells - see Figure 13

bull tangent linear and adjoint counterparts are automatically maintained along with the forward modelpermitting sensitivity and optimization studies

bull the model is developed to perform efficiently on a wide variety of computational platforms

Key publications reporting on and charting the development of the model are Hill and Marshall (1995) Marshall et al(1997a) Marshall et al (1997b) Adcroft and Marshall (1997) Marshall et al (1998) Adcroft and Marshall (1999)Hill et al (1999) Marotzke et al (1999) Adcroft and Campin (2004) Adcroft et al (2004b) Marshall et al (2004)(an overview on the model formulation can also be found in Adcroft et al (2004c))

MITgcm Documentation Release 10

AtmosphericModel

Dynamical KernelAtmosphericPhysics

OceanPhysics

OceanModel

Figure 11 MITgcm has a single dynamical kernel that can drive forward either oceanic or atmospheric simulations

Figure 12 MITgcm has non-hydrostatic capabilities allowing the model to address a wide range of phenomenon -from convection on the left all the way through to global circulation patterns on the right

2 Chapter 1 Overview

Finite Volume Shaved CellsStream Function Ψ Tracer θ at t=03

Figure 13 Finite volume techniques (bottom panel) are used permitting a treatment of topography that rivals 120590(terrain following) coordinates

11 Introduction 3

Hill C and J Marshall (1995) Application of a Parallel Navier-Stokes Model to Ocean Circulation in Parallel Com-putational Fluid Dynamics In Proceedings of Parallel Computational Fluid Dynamics Implementations and ResultsUsing Parallel Computers 545-552 Elsevier Science BV New York [HM95]

Marshall J C Hill L Perelman and A Adcroft (1997a) Hydrostatic quasi-hydrostatic and nonhydrostatic oceanmodeling J Geophysical Res 102(C3) 5733-5752 [MHPA97]

Marshall J A Adcroft C Hill L Perelman and C Heisey (1997b) A finite-volume incompressible Navier Stokesmodel for studies of the ocean on parallel computers J Geophysical Res 102(C3) 5753-5766 [MAH+97]

Adcroft AJ Hill CN and J Marshall (1997) Representation of topography by shaved cells in a height coordinateocean model Mon Wea Rev 125 2293-2315 [AHM97]

Marshall J Jones H and C Hill (1998) Efficient ocean modeling using non-hydrostatic algorithms Journal ofMarine Systems 18 115-134 [MJH98]

Adcroft A Hill C and J Marshall (1999) A new treatment of the Coriolis terms in C-grid models at both high andlow resolutions Mon Wea Rev 127 1928-1936 [AHM99]

Hill C AdcroftA JamousD and J Marshall (1999) A Strategy for Terascale Climate Modeling In Proceedings ofthe Eighth ECMWF Workshop on the Use of Parallel Processors in Meteorology 406-425 World Scientific PublishingCo UK [HAJM99]

Marotzke J GieringR Zhang KQ StammerD HillC and TLee (1999) Construction of the adjoint MIT oceangeneral circulation model and application to Atlantic heat transport variability J Geophysical Res 104(C12) 29529-29547 [MGZ+99]

A Adcroft and J-M Campin (2004a) Re-scaled height coordinates for accurate representation of free-surface flowsin ocean circulation models Ocean Modelling 7 269ndash284 [AC04]

A Adcroft J-M Campin C Hill and J Marshall (2004b) Implementation of an atmosphere-ocean general circula-tion model on the expanded spherical cube Mon Wea Rev 132 2845ndash2863 [ACHM04]

J Marshall A Adcroft J-M Campin C Hill and A White (2004) Atmosphere-ocean modeling exploiting fluidisomorphisms Mon Wea Rev 132 2882ndash2894 [MAC+04]

A Adcroft C Hill J-M Campin J Marshall and P Heimbach (2004c) Overview of the formulation and numericsof the MITgcm In Proceedings of the ECMWF seminar series on Numerical Methods Recent developments in numer-ical methods for atmosphere and ocean modelling 139ndash149 URL httpmitgcmorgpdfsECMWF2004-Adcroftpdf[AHCampin+04]

We begin by briefly showing some of the results of the model in action to give a feel for the wide range of problemsthat can be addressed using it

12 Illustrations of the model in action

MITgcm has been designed and used to model a wide range of phenomena from convection on the scale of meters inthe ocean to the global pattern of atmospheric winds - see Figure 12 To give a flavor of the kinds of problems themodel has been used to study we briefly describe some of them here A more detailed description of the underlyingformulation numerical algorithm and implementation that lie behind these calculations is given later Indeed manyof the illustrative examples shown below can be easily reproduced simply download the model (the minimum youneed is a PC running Linux together with a FORTRAN77 compiler) and follow the examples described in detail inthe documentation

121 Global atmosphere lsquoHeld-Suarezrsquo benchmark

A novel feature of MITgcm is its ability to simulate using one basic algorithm both atmospheric and oceanographicflows at both small and large scales

Figure 14 shows an instantaneous plot of the 500 mb temperature field obtained using the atmospheric isomorph ofMITgcm run at 28deg resolution on the cubed sphere We see cold air over the pole (blue) and warm air along anequatorial band (red) Fully developed baroclinic eddies spawned in the northern hemisphere storm track are evidentThere are no mountains or land-sea contrast in this calculation but you can easily put them in The model is drivenby relaxation to a radiative-convective equilibrium profile following the description set out in Held and Suarez (1994)[HS94] designed to test atmospheric hydrodynamical cores - there are no mountains or land-sea contrast

Figure 14 Instantaneous plot of the temperature field at 500 mb obtained using the atmospheric isomorph of MITgcm

As described in Adcroft et al (2004) [ACHM04] a lsquocubed spherersquo is used to discretize the globe permitting a uniformgriding and obviated the need to Fourier filter The lsquovector-invariantrsquo form of MITgcm supports any orthogonalcurvilinear grid of which the cubed sphere is just one of many choices

Figure 15 shows the 5-year mean zonally averaged zonal wind from a 20-level configuration of the model It comparesfavorable with more conventional spatial discretization approaches The two plots show the field calculated usingthe cube-sphere grid and the flow calculated using a regular spherical polar latitude-longitude grid Both grids aresupported within the model

122 Ocean gyres

Baroclinic instability is a ubiquitous process in the ocean as well as the atmosphere Ocean eddies play an importantrole in modifying the hydrographic structure and current systems of the oceans Coarse resolution models of theoceans cannot resolve the eddy field and yield rather broad diffusive patterns of ocean currents But if the resolutionof our models is increased until the baroclinic instability process is resolved numerical solutions of a different andmuch more realistic kind can be obtained

12 Illustrations of the model in action 5

Figure 15 Five year mean zonally averaged zonal flow for cube-sphere simulation (top) and latitude-longitudesimulation (bottom) and using Held-Suarez forcing Note the difference in the solutions over the pole mdash the cubedsphere is superior

Figure 16 shows the surface temperature and velocity field obtained from MITgcm run at 16

∘ horizontal resolutionon a lat-lon grid in which the pole has been rotated by 90deg on to the equator (to avoid the converging of meridian innorthern latitudes) 21 vertical levels are used in the vertical with a lsquolopped cellrsquo representation of topography Thedevelopment and propagation of anomalously warm and cold eddies can be clearly seen in the Gulf Stream regionThe transport of warm water northward by the mean flow of the Gulf Stream is also clearly visible

Figure 16 Instantaneous temperature map from a 16

∘ simulation of the North Atlantic The figure shows the temper-ature in the second layer (375 m deep)

123 Global ocean circulation

Figure 17 shows the pattern of ocean currents at the surface of a 4deg global ocean model run with 15 vertical levelsLopped cells are used to represent topography on a regular lat-lon grid extending from 70degN to 70degS The model isdriven using monthly-mean winds with mixed boundary conditions on temperature and salinity at the surface Thetransfer properties of ocean eddies convection and mixing is parameterized in this model

180W 150W 120W 90W 60W 30W 0 30E 60E 90E 120E 150E 180E 90S

90NCurrents at 25 m t=1000 years

Figure 17 Pattern of surface ocean currents from a global integration of the model at 4deg horizontal resolution andwith 15 vertical levels

Figure 18 shows the meridional overturning circulation of the global ocean in Sverdrups

Figure 18 Meridional overturning stream function (in Sverdrups) from a global integration of the model at 4deg hori-zontal resolution and with 15 vertical levels

124 Convection and mixing over topography

Dense plumes generated by localized cooling on the continental shelf of the ocean may be influenced by rotation whenthe deformation radius is smaller than the width of the cooling region Rather than gravity plumes the mechanism formoving dense fluid down the shelf is then through geostrophic eddies The simulation shown in Figure 19 (blue iscold dense fluid red is warmer lighter fluid) employs the non-hydrostatic capability of MITgcm to trigger convectionby surface cooling The cold dense water falls down the slope but is deflected along the slope by rotation It is foundthat entrainment in the vertical plane is reduced when rotational control is strong and replaced by lateral entrainmentdue to the baroclinic instability of the along-slope current

125 Boundary forced internal waves

The unique ability of MITgcm to treat non-hydrostatic dynamics in the presence of complex geometry makes it an idealtool to study internal wave dynamics and mixing in oceanic canyons and ridges driven by large amplitude barotropictidal currents imposed through open boundary conditions

Figure 110 shows the influence of cross-slope topographic variations on internal wave breaking - the cross-slopevelocity is in color the density contoured The internal waves are excited by application of open boundary conditionson the left They propagate to the sloping boundary (represented using MITgcmrsquos finite volume spatial discretization)where they break under non-hydrostatic dynamics

Figure 19 MITgcm run in a non-hydrostatic configuration to study convection over a slope

Figure 110 Simulation of internal waves forced at an open boundary (on the left) impacting a sloping shelf Thealong slope velocity is shown colored contour lines show density surfaces The slope is represented with high-fidelityusing lopped cells

126 Parameter sensitivity using the adjoint of MITgcm

Forward and tangent linear counterparts of MITgcm are supported using an lsquoautomatic adjoint compilerrsquo These canbe used in parameter sensitivity and data assimilation studies

As one example of application of the MITgcm adjoint Figure 111 maps the gradient 120597119869120597ℋ where 119869 is the magnitude

of the overturning stream-function shown in Figure 18 at 60degN and ℋ(120582 120601) is the mean local air-sea heat flux over a100 year period We see that 119869 is sensitive to heat fluxes over the Labrador Sea one of the important sources of deepwater for the thermohaline circulations This calculation also yields sensitivities to all other model parameters

180W 150W 120W 90W 60W 30W 0 30E 60E 90E 120E 150E 180E 90S

90NHeat Flux (Min = minus77 10minus4 Sv Wminus1 m2 Max = 429 10minus4 Sv Wminus1 m2)

minus10 minus5 0 5 10 15 20 25 30 35 40 45 50

10minus4 Sv Wminus1 m2

Sensitivity of the Meridional Overturning minus Ocean

Figure 111 Sensitivity of meridional overturning strength to surface heat flux changes Contours show the magnitudeof the response (in Sv x 10-4 ) that a persistent +1 Wm-2 heat flux anomaly at a given grid point would produce

127 Global state estimation of the ocean

An important application of MITgcm is in state estimation of the global ocean circulation An appropriately definedlsquocost functionrsquo which measures the departure of the model from observations (both remotely sensed and in-situ)over an interval of time is minimized by adjusting lsquocontrol parametersrsquo such as air-sea fluxes the wind field theinitial conditions etc Figure 112 and Figure 113 show the large scale planetary circulation and a Hopf-Muller plot ofEquatorial sea-surface height Both are obtained from assimilation bringing the model in to consistency with altimetricand in-situ observations over the period 1992-1997

Figure 112 Circulation patterns from a multi-year global circulation simulation constrained by Topex altimeter dataand WOCE cruise observations This output is from a higher resolution shorter duration experiment with equatoriallyenhanced grid spacing

Figure 113 Equatorial sea-surface height in unconstrained (left) constrained (middle) simulations and in observations(right)

128 Ocean biogeochemical cycles

MITgcm is being used to study global biogeochemical cycles in the ocean For example one can study the effects ofinterannual changes in meteorological forcing and upper ocean circulation on the fluxes of carbon dioxide and oxygenbetween the ocean and atmosphere Figure 114 shows the annual air-sea flux of oxygen and its relation to densityoutcrops in the southern oceans from a single year of a global interannually varying simulation The simulation is runat 1degx1deg resolution telescoping to 1

∘ x 13

∘ in the tropics (not shown)

268262

268265

MITgcm airminussea O2 flux (molm2yr) with contoured potential density

150 oW

120 oW

0o 30 oE

150o E

minus15 minus10 minus5 0 5 10 15

Figure 114 Annual air-sea flux of oxygen (shaded) plotted along with potential density outcrops of the surface of thesouthern ocean from a global 1degx1deg integration with a telescoping grid (to 1

∘ ) at the equator

129 Simulations of laboratory experiments

Figure 116 shows MITgcm being used to simulate a laboratory experiment (Figure 115) inquiring into the dynamicsof the Antarctic Circumpolar Current (ACC) An initially homogeneous tank of water (1 m in diameter) is driven fromits free surface by a rotating heated disk The combined action of mechanical and thermal forcing creates a lens offluid which becomes baroclinically unstable The stratification and depth of penetration of the lens is arrested by itsinstability in a process analogous to that which sets the stratification of the ACC

Figure 115 A 1 m diameter laboratory experiment simulating the dynamics of the Antarctic Circumpolar Current

13 Continuous equations in lsquorrsquo coordinates

To render atmosphere and ocean models from one dynamical core we exploit lsquoisomorphismsrsquo between equation setsthat govern the evolution of the respective fluids - see Figure 117 One system of hydrodynamical equations is writtendown and encoded The model variables have different interpretations depending on whether the atmosphere or oceanis being studied Thus for example the vertical coordinate lsquo119903rsquo is interpreted as pressure 119901 if we are modeling theatmosphere (right hand side of Figure 117) and height 119911 if we are modeling the ocean (left hand side of Figure 117)

The state of the fluid at any time is characterized by the distribution of velocity v active tracers 120579 and 119878 a lsquogeopoten-tialrsquo 120593 and density 120588 = 120588(120579 119878 119901) which may depend on 120579 119878 and 119901 The equations that govern the evolution of thesefields obtained by applying the laws of classical mechanics and thermodynamics to a Boussinesq Navier-Stokes fluidare written in terms of a generic vertical coordinate 119903 so that the appropriate kinematic boundary conditions can beapplied isomorphically see Figure 118

119863vℎ

119863119905+(

2Ω times v)ℎ

+ nablaℎ120593 = ℱvℎhorizontal momentum (11)

119863

119863119905+ 119896 middot (2Ω times v

)+120597120593

120597119903+ 119887 = ℱ vertical momentum (12)

nablaℎ middot vℎ +120597

120597119903= 0 continuity (13)

119887 = 119887(120579 119878 119903) equation of state (14)

13 Continuous equations in lsquorrsquo coordinates 15

Figure 116 A numerical simulation of the laboratory experiment using MITgcm

Figure 117 Isomorphic equation sets used for atmosphere (right) and ocean (left)

z-p Isomorphism

z = 0 mz = -50 mz = -100 m z = -175 m

z = -275 m

z = -400 m

p = 0 mb

p = 150 mbp = 350 mb

p = 650 mbp = 900 mbp = 1000 mb

Figure 118 Vertical coordinates and kinematic boundary conditions for atmosphere (top) and ocean (bottom)

119863120579

119863119905= 119980120579 potential temperature (15)

119863119878

119863119905= 119980119878 humiditysalinity (16)

119903 is the vertical coordinate

119863

119863119905=

120597

120597119905+ v middot nabla is the total derivative

nabla = nablaℎ + 119896 120597120597119903

is the lsquogradrsquo operator

with nablaℎ operating in the horizontal and 119896 120597120597119903 operating in the vertical where 119896 is a unit vector in the vertical

119905 is time

v = (119906 119907 ) = (vℎ ) is the velocity

120593 is the lsquopressurersquolsquogeopotentialrsquo

Ω is the Earthrsquos rotation

119887 is the lsquobuoyancyrsquo

120579 is potential temperature

119878 is specific humidity in the atmosphere salinity in the ocean

ℱv are forcing and dissipation of v

119980120579 are forcing and dissipation of 120579

The ℱ prime119904 and 119980prime119904 are provided by lsquophysicsrsquo and forcing packages for atmosphere and ocean These are described inlater chapters

131 Kinematic Boundary conditions

1311 Vertical

at fixed and moving 119903 surfaces we set (see Figure 118)

= 0 at 119903 = 119877119891119894119909119890119889(119909 119910) (ocean bottom top of the atmosphere) (17)

=119863119903

119863119905at 119903 = 119877119898119900119907119894119899119892(119909 119910) (ocean surface bottom of the atmosphere) (18)

119877119898119900119907119894119899119892 = 119877119900 + 120578

where 119877119900(119909 119910) is the lsquo119903minusvaluersquo (height or pressure depending on whether we are in the atmosphere or ocean) of thelsquomoving surfacersquo in the resting fluid and 120578 is the departure from 119877119900(119909 119910) in the presence of motion

1312 Horizontal

v middot n = 0 (19)

where n is the normal to a solid boundary

132 Atmosphere

In the atmosphere (see Figure 118) we interpret

119903 = 119901 is the pressure (110)

=119863119901

119863119905= 120596 is the vertical velocity in p coordinates (111)

120593 = 119892 119911 is the geopotential height (112)

119887 =120597Π

120597119901120579 is the buoyancy (113)

120579 = 119879 (119901119888119901

)120581 is potential temperature (114)

119878 = 119902 is the specific humidity (115)

119879 is absolute temperature

119901 is the pressure

119911 is the height of the pressure surface119892 is the acceleration due to gravity

In the above the ideal gas law 119901 = 120588119877119879 has been expressed in terms of the Exner function Π(119901) given by (116) (seealso Section 141)

Π(119901) = 119888119901(119901

119901119888)120581 (116)

where 119901119888 is a reference pressure and 120581 = 119877119888119901 with 119877 the gas constant and 119888119901 the specific heat of air at constantpressure

At the top of the atmosphere (which is lsquofixedrsquo in our 119903 coordinate)

119877119891119894119909119890119889 = 119901119905119900119901 = 0

In a resting atmosphere the elevation of the mountains at the bottom is given by

119877119898119900119907119894119899119892 = 119877119900(119909 119910) = 119901119900(119909 119910)

ie the (hydrostatic) pressure at the top of the mountains in a resting atmosphere

The boundary conditions at top and bottom are given by

120596 = 0 at 119903 = 119877119891119894119909119890119889 (top of the atmosphere) (117)

120596 =119863119901119904119863119905

at 119903 = 119877119898119900119907119894119899119892 (bottom of the atmosphere) (118)

Then the (hydrostatic form of) equations (11)-(16) yields a consistent set of atmospheric equations which for conve-nience are written out in 119901minuscoordinates in Section 141 - see eqs (159)-(163)

133 Ocean

In the ocean we interpret

119903 = 119911 is the height (119)

=119863119911

119863119905= 119908 is the vertical velocity (120)

120593 =119901

120588119888is the pressure (121)

119887(120579 119878 119903) =119892

120588119888(120588(120579 119878 119903) minus 120588119888) is the buoyancy (122)

where 120588119888 is a fixed reference density of water and 119892 is the acceleration due to gravity

In the above

At the bottom of the ocean 119877119891119894119909119890119889(119909 119910) = minus119867(119909 119910)

The surface of the ocean is given by 119877119898119900119907119894119899119892 = 120578

The position of the resting free surface of the ocean is given by 119877119900 = 119885119900 = 0

Boundary conditions are

119908 = 0 at 119903 = 119877119891119894119909119890119889 (ocean bottom) (123)

119908 =119863120578

119863119905at 119903 = 119877119898119900119907119894119899119892 = 120578 (ocean surface) (124)

where 120578 is the elevation of the free surface

Then equations (11)- (16) yield a consistent set of oceanic equations which for convenience are written out in119911minuscoordinates in Section 151 - see eqs (198) to (1103)

134 Hydrostatic Quasi-hydrostatic Quasi-nonhydrostatic and Non-hydrostaticforms

Let us separate 120593 in to surface hydrostatic and non-hydrostatic terms

120593(119909 119910 119903) = 120593119904(119909 119910) + 120593ℎ119910119889(119909 119910 119903) + 120593119899ℎ(119909 119910 119903) (125)

and write (11) in the form

120597vℎ

120597119905+ nablaℎ120593119904 + nablaℎ120593ℎ119910119889 + 120598119899ℎnablaℎ120593119899ℎ = Gℎ

120597120593ℎ119910119889120597119903

= minus119887 (127)

120598119899ℎ120597

120597119905+120597120593119899ℎ120597119903

= 119866 (128)

Here 120598119899ℎ is a non-hydrostatic parameter

The(G 119866

)in (126) and (128) represent advective metric and Coriolis terms in the momentum equations In

spherical coordinates they take the form1 - see Marshall et al (1997a) [MHPA97] for a full discussion

119866119906 = minus vnabla119906 advection

minus119906

119903minus 119906119907 tan120601

119903

metric

minusminus2Ω119907 sin120601+ 2Ω cos120601

Coriolis

+ ℱ119906 forcingdissipation

minus119907

119903minus 1199062 tan120601

119903

metric

minus minus2Ω119906 sin120601 Coriolis+ ℱ119907 forcingdissipation

119866 = minus vnabla advection

minus1199062 + 1199072

119903

metric

+ 2Ω119906 cos120601 Coriolis

+ ℱ forcingdissipation

In the above lsquo119903rsquo is the distance from the center of the earth and lsquo120601 rsquo is latitude (see Figure 120)

Grad and div operators in spherical coordinates are defined in Coordinate systems

1341 Shallow atmosphere approximation

Most models are based on the lsquohydrostatic primitive equationsrsquo (HPErsquos) in which the vertical momentum equation isreduced to a statement of hydrostatic balance and the lsquotraditional approximationrsquo is made in which the Coriolis forceis treated approximately and the shallow atmosphere approximation is made MITgcm need not make the lsquotraditionalapproximationrsquo To be able to support consistent non-hydrostatic forms the shallow atmosphere approximation can berelaxed - when dividing through by 119903 in for example (129) we do not replace 119903 by 119886 the radius of the earth

1342 Hydrostatic and quasi-hydrostatic forms

These are discussed at length in Marshall et al (1997a) [MHPA97]

In the lsquohydrostatic primitive equationsrsquo (HPE) all the underlined terms in Eqs (129) rarr (131) are neglected and lsquo119903rsquois replaced by lsquo119886rsquo the mean radius of the earth Once the pressure is found at one level - eg by inverting a 2-d Ellipticequation for 120593119904 at 119903 = 119877119898119900119907119894119899119892 - the pressure can be computed at all other levels by integration of the hydrostaticrelation eq (127)

In the lsquoquasi-hydrostaticrsquo equations (QH) strict balance between gravity and vertical pressure gradients is not imposedThe 2Ω119906 cos120601 Coriolis term are not neglected and are balanced by a non-hydrostatic contribution to the pressure field

1 In the hydrostatic primitive equations (HPE) all underlined terms in (129) (130) and (131) are omitted the singly-underlined terms areincluded in the quasi-hydrostatic model (QH) The fully non-hydrostatic model (NH) includes all terms

only the terms underlined twice in Eqs (129) rarr (131) are set to zero and simultaneously the shallow atmosphereapproximation is relaxed In QH all the metric terms are retained and the full variation of the radial position of aparticle monitored The QH vertical momentum equation (128) becomes

120597120593119899ℎ120597119903

= 2Ω119906 cos120601

making a small correction to the hydrostatic pressure

QH has good energetic credentials - they are the same as for HPE Importantly however it has the same angularmomentum principle as the full non-hydrostatic model (NH) - see Marshall etal (1997a) [MHPA97] As in HPEonly a 2-d elliptic problem need be solved

1343 Non-hydrostatic and quasi-nonhydrostatic forms

MITgcm presently supports a full non-hydrostatic ocean isomorph but only a quasi-non-hydrostatic atmosphericisomorph

Non-hydrostatic Ocean

In the non-hydrostatic ocean model all terms in equations Eqs (129) rarr (131) are retained A three dimensionalelliptic equation must be solved subject to Neumann boundary conditions (see below) It is important to note thatuse of the full NH does not admit any new lsquofastrsquo waves in to the system - the incompressible condition (13) hasalready filtered out acoustic modes It does however ensure that the gravity waves are treated accurately with anexact dispersion relation The NH set has a complete angular momentum principle and consistent energetics - seeWhite and Bromley (1995) [WB95] Marshall et al (1997a) [MHPA97]

Quasi-nonhydrostatic Atmosphere

In the non-hydrostatic version of our atmospheric model we approximate in the vertical momentum eqs (128) and(130) (but only here) by

=119863119901

119863119905=

119892

119863120593

119863119905(132)

where 119901ℎ119910 is the hydrostatic pressure

1344 Summary of equation sets supported by model

Atmosphere

Hydrostatic and quasi-hydrostatic and quasi non-hydrostatic forms of the compressible non-Boussinesq equations in119901minuscoordinates are supported

Hydrostatic and quasi-hydrostatic

The hydrostatic set is written out in 119901minuscoordinates in Hydrostatic Primitive Equations for the Atmosphere in PressureCoordinates - see eqs (159) to (163)

Quasi-nonhydrostatic

A quasi-nonhydrostatic form is also supported

Hydrostatic and quasi-hydrostatic forms of the incompressible Boussinesq equations in 119911minuscoordinates are supported

Non-hydrostatic

Non-hydrostatic forms of the incompressible Boussinesq equations in 119911minus coordinates are supported - see eqs (198)to (1103)

135 Solution strategy

The method of solution employed in the HPE QH and NH models is summarized in Figure 119 Under all dy-namics a 2-d elliptic equation is first solved to find the surface pressure and the hydrostatic pressure at any levelcomputed from the weight of fluid above Under HPE and QH dynamics the horizontal momentum equations arethen stepped forward and found from continuity Under NH dynamics a 3-d elliptic equation must be solved for thenon-hydrostatic pressure before stepping forward the horizontal momentum equations is found by stepping forwardthe vertical momentum equation

There is no penalty in implementing QH over HPE except of course some complication that goes with the inclusionof cos120601 Coriolis terms and the relaxation of the shallow atmosphere approximation But this leads to negligibleincrease in computation In NH in contrast one additional elliptic equation - a three-dimensional one - must beinverted for 119901119899ℎ However the lsquooverheadrsquo of the NH model is essentially negligible in the hydrostatic limit (see detaileddiscussion in Marshall et al (1997) [MHPA97] resulting in a non-hydrostatic algorithm that in the hydrostatic limitis as computationally economic as the HPEs

136 Finding the pressure field

Unlike the prognostic variables 119906 119907 119908 120579 and 119878 the pressure field must be obtained diagnostically We proceedas before by dividing the total (pressuregeo) potential in to three parts a surface part 120593119904(119909 119910) a hydrostatic part120593ℎ119910119889(119909 119910 119903) and a non-hydrostatic part 120593119899ℎ(119909 119910 119903) as in (125) and writing the momentum equation as in (126)

1361 Hydrostatic pressure

Hydrostatic pressure is obtained by integrating (127) vertically from 119903 = 119877119900 where 120593ℎ119910119889(119903 = 119877119900) = 0 to yieldint 119877119900

119903

120597120593ℎ119910119889120597119903

119889119903 = [120593ℎ119910119889]119877119900

119903 =

int 119877119900

119903

minus119887119889119903

and so

120593ℎ119910119889(119909 119910 119903) =

int 119877119900

119903

119887119889119903 (133)

Figure 119 Basic solution strategy in MITgcm HPE and QH forms diagnose the vertical velocity in NH a prognosticequation for the vertical velocity is integrated

The model can be easily modified to accommodate a loading term (eg atmospheric pressure pushing down on theoceanrsquos surface) by setting

120593ℎ119910119889(119903 = 119877119900) = 119897119900119886119889119894119899119892 (134)

1362 Surface pressure

The surface pressure equation can be obtained by integrating continuity (13) vertically from 119903 = 119877119891119894119909119890119889 to 119903 =119877119898119900119907119894119899119892 int 119877119898119900119907119894119899119892

119877119891119894119909119890119889

(nablaℎ middot vℎ + 120597119903 ) 119889119903 = 0

120597120578

120597119905+ vnabla120578 +

int 119877119898119900119907119894119899119892

119877119891119894119909119890119889

nablaℎ middot vℎ119889119903 = 0

where 120578 = 119877119898119900119907119894119899119892 minus 119877119900 is the free-surface 119903-anomaly in units of 119903 The above can be rearranged to yield usingLeibnitzrsquos theorem

120597120578

120597119905+ nablaℎ middot

int 119877119898119900119907119894119899119892

119877119891119894119909119890119889

vℎ119889119903 = source (135)

where we have incorporated a source term

Whether 120593 is pressure (ocean model 119901120588119888) or geopotential (atmospheric model) in (126) the horizontal gradientterm can be written

nablaℎ120593119904 = nablaℎ (119887119904120578) (136)

where 119887119904 is the buoyancy at the surface

In the hydrostatic limit (120598119899ℎ = 0) equations (126) (135) and (136) can be solved by inverting a 2-d elliptic equationfor 120593119904 as described in Chapter 2 Both lsquofree surfacersquo and lsquorigid lidrsquo approaches are available

1363 Non-hydrostatic pressure

Taking the horizontal divergence of (126) and adding 120597120597119903 of (128) invoking the continuity equation (13) we deduce

nabla23120593119899ℎ = nablaG minus

(nabla2

ℎ120593119904 + nabla2120593ℎ119910119889)

= nablaF (137)

For a given rhs this 3-d elliptic equation must be inverted for 120593119899ℎ subject to appropriate choice of boundary conditionsThis method is usually called The Pressure Method [Harlow and Welch (1965) [HW65] Williams (1969) [Wil69]Potter (1973) [Pot73] In the hydrostatic primitive equations case (HPE) the 3-d problem does not need to be solved

Boundary Conditions

We apply the condition of no normal flow through all solid boundaries - the coasts (in the ocean) and the bottom

v119899 = 0 (138)

where 119899 is a vector of unit length normal to the boundary The kinematic condition (138) is also applied to thevertical velocity at 119903 = 119877119898119900119907119894119899119892 No-slip (119907119879 = 0) or slip (120597119907119879 120597119899 = 0) conditions are employed on the tangentialcomponent of velocity 119907119879 at all solid boundaries depending on the form chosen for the dissipative terms in themomentum equations - see below

Eq (138) implies making use of (126) that

119899nabla120593119899ℎ = 119899F (139)

F = G minus (nablaℎ120593119904 + nabla120593ℎ119910119889)

presenting inhomogeneous Neumann boundary conditions to the Elliptic problem (137) As shown for example byWilliams (1969) [Wil69] one can exploit classical 3D potential theory and by introducing an appropriately chosen120575-function sheet of lsquosource-chargersquo replace the inhomogeneous boundary condition on pressure by a homogeneousone The source term 119903ℎ119904 in (137) is the divergence of the vector F By simultaneously setting 119899F = 0 and119899nabla120593119899ℎ = 0 on the boundary the following self-consistent but simpler homogenized Elliptic problem is obtained

nabla2120593119899ℎ = nabla F13 Continuous equations in lsquorrsquo coordinates 25

where F is a modified F such that F119899 = 0 As is implied by (139) the modified boundary condition becomes

119899nabla120593119899ℎ = 0 (140)

If the flow is lsquoclosersquo to hydrostatic balance then the 3-d inversion converges rapidly because 120593119899ℎ is then only a smallcorrection to the hydrostatic pressure field (see the discussion in Marshall et al (1997ab) [MHPA97] [MAH+97]

The solution 120593119899ℎ to (137) and (139) does not vanish at 119903 = 119877119898119900119907119894119899119892 and so refines the pressure there

137 Forcingdissipation

1371 Forcing

The forcing terms ℱ on the rhs of the equations are provided by lsquophysics packagesrsquo and forcing packages These aredescribed later on

1372 Dissipation

Momentum

Many forms of momentum dissipation are available in the model Laplacian and biharmonic frictions are commonlyused

119863119881 = 119860ℎnabla2ℎ119907 +119860119907

1205972119907

1205971199112+1198604nabla4

ℎ119907 (141)

where 119860ℎ and 119860119907 are (constant) horizontal and vertical viscosity coefficients and 1198604 is the horizontal coefficient forbiharmonic friction These coefficients are the same for all velocity components

Tracers

The mixing terms for the temperature and salinity equations have a similar form to that of momentum except that thediffusion tensor can be non-diagonal and have varying coefficients

119863119879119878 = nabla[119870nabla(119879 119878)] +1198704nabla4ℎ(119879 119878) (142)

where 119870 is the diffusion tensor and the 1198704 horizontal coefficient for biharmonic diffusion In the simplest case wherethe subgrid-scale fluxes of heat and salt are parameterized with constant horizontal and vertical diffusion coefficients119870 reduces to a diagonal matrix with constant coefficients

119870 =

⎛⎝ 119870ℎ 0 00 119870ℎ 00 0 119870119907

⎞⎠ (143)

where 119870ℎ and 119870119907 are the horizontal and vertical diffusion coefficients These coefficients are the same for all tracers(temperature salinity )

138 Vector invariant form

For some purposes it is advantageous to write momentum advection in eq (11) and (12) in the (so-called) lsquovectorinvariantrsquo form

119863v

119863119905=120597v

120597119905+ (nablatimes v) times v + nabla

2(v middot v)

](144)

This permits alternative numerical treatments of the non-linear terms based on their representation as a vorticity fluxBecause gradients of coordinate vectors no longer appear on the rhs of (144) explicit representation of the metricterms in (129) (130) and (131) can be avoided information about the geometry is contained in the areas andlengths of the volumes used to discretize the model

139 Adjoint

Tangent linear and adjoint counterparts of the forward model are described in Section 7

14 Appendix ATMOSPHERE

141 Hydrostatic Primitive Equations for the Atmosphere in Pressure Coordinates

The hydrostatic primitive equations (HPErsquos) in 119901minuscoordinates are

119863vℎ

119863119905+ 119891 ktimes vℎ + nabla119901120593 = ℱ (145)

120597120593

120597119901+ 120572 = 0 (146)

nabla119901 middot vℎ +120597120596

120597119901= 0 (147)

119901120572 = 119877119879 (148)

119888119907119863119879

119863119905+ 119901

119863120572

119863119905= 119980 (149)

where vℎ = (119906 119907 0) is the lsquohorizontalrsquo (on pressure surfaces) component of velocity 119863119863119905 = 120597

120597119905 + vℎ middotnabla119901 +120596 120597120597119901 is the

total derivative 119891 = 2Ω sin120601 is the Coriolis parameter 120593 = 119892119911 is the geopotential 120572 = 1120588 is the specific volume120596 = 119863119901

119863119905 is the vertical velocity in the 119901minuscoordinate Equation (149) is the first law of thermodynamics where internalenergy 119890 = 119888119907119879 119879 is temperature 119876 is the rate of heating per unit mass and 119901119863120572

119863119905 is the work done by the fluid incompressing

It is convenient to cast the heat equation in terms of potential temperature 120579 so that it looks more like a genericconservation law Differentiating (148) we get

119901119863120572

119863119905+ 120572

119863119901

119863119905= 119877

119863119879

119863119905

14 Appendix ATMOSPHERE 27

which when added to the heat equation (149) and using 119888119901 = 119888119907 +119877 gives

119888119901119863119879

119863119905minus 120572

119863119901

119863119905= 119980 (150)

Potential temperature is defined

120579 = 119879 (119901119888119901

)120581 (151)

where 119901119888 is a reference pressure and 120581 = 119877119888119901 For convenience we will make use of the Exner function Π(119901) whichis defined by

Π(119901) = 119888119901(119901

119901119888)120581 (152)

The following relations will be useful and are easily expressed in terms of the Exner function

119888119901119879 = Π120579 120597Π

120597119901=120581Π

119901 120572 =

120581Π120579

119901=120597 Π

120597119901120579

119863Π

119863119905=120597Π

120597119901

119863119901

119863119905

where 119887 = 120597 Π120597119901 120579 is the buoyancy

The heat equation is obtained by noting that

119888119901119863119879

119863119905=119863(Π120579)

119863119905= Π

119863120579

119863119905+ 120579

119863Π

119863119905= Π

119863120579

119863119905+ 120572

119863119901

119863119905

and on substituting into (150) gives

Π119863120579

119863119905= 119980 (153)

which is in conservative form

For convenience in the model we prefer to step forward (153) rather than (149)

1411 Boundary conditions

The upper and lower boundary conditions are

at the top 119901 = 0 120596 =119863119901

119863119905= 0 (154)

at the surface 119901 = 119901119904 120593 = 120593119905119900119901119900 = 119892 119885119905119900119901119900 (155)

In 119901minuscoordinates the upper boundary acts like a solid boundary (120596 = 0 ) in 119911minuscoordinates the lower boundary isanalogous to a free surface (120593 is imposed and 120596 = 0)

1412 Splitting the geopotential

For the purposes of initialization and reducing round-off errors the model deals with perturbations from reference (orlsquostandardrsquo) profiles For example the hydrostatic geopotential associated with the resting atmosphere is not dynami-cally relevant and can therefore be subtracted from the equations The equations written in terms of perturbations areobtained by substituting the following definitions into the previous model equations

120579 = 120579119900 + 120579prime (156)

120572 = 120572119900 + 120572prime (157)

120593 = 120593119900 + 120593prime (158)

The reference state (indicated by subscript lsquoorsquo) corresponds to horizontally homogeneous atmosphere at rest(120579119900 120572119900 120593119900) with surface pressure 119901119900(119909 119910) that satisfies 120593119900(119901119900) = 119892 119885119905119900119901119900 defined

120579119900(119901) = 119891119899(119901)

120572119900(119901) = Π119901120579119900

120593119900(119901) = 120593119905119900119901119900 minusint 119901

1199010

120572119900119889119901

The final form of the HPErsquos in 119901minuscoordinates is then

119863vℎ

119863119905+ 119891 ktimes vℎ + nabla119901120593

prime = ℱ (159)

120597120593prime

120597119901+ 120572prime = 0 (160)

nabla119901 middot vℎ +120597120596

120597119901= 0 (161)

120597Π

120597119901120579prime = 120572prime (162)

119863120579

119863119905=

119980Π

15 Appendix OCEAN

151 Equations of Motion for the Ocean

We review here the method by which the standard (Boussinesq incompressible) HPErsquos for the ocean written in119911minuscoordinates are obtained The non-Boussinesq equations for oceanic motion are

119863vℎ

119863119905+ 119891 ktimes vℎ +

120588nabla119911119901 = ℱ (164)

120598119899ℎ119863119908

119863119905+ 119892 +

120588

120597119901

120597119911= 120598119899ℎℱ119908 (165)

120588

119863120588

119863119905+ nabla119911 middot vℎ +

120597119908

120597119911= 0 (166)

120588 = 120588(120579 119878 119901) (167)

119863120579

119863119905= 119980120579 (168)

119863119878

119863119905= 119980119904 (169)

These equations permit acoustics modes inertia-gravity waves non-hydrostatic motions a geostrophic (Rossby) modeand a thermohaline mode As written they cannot be integrated forward consistently - if we step 120588 forward in (166)the answer will not be consistent with that obtained by stepping (168) and (169) and then using (167) to yield 120588 Itis therefore necessary to manipulate the system as follows Differentiating the EOS (equation of state) gives

119863120588

119863119905=120597120588

120597120579

119878119901

119863120579

119863119905+

120597120588

120597119878

120579119901

119863119878

119863119905+120597120588

120597119901

120579119878

119863119901

119863119905(170)

Note that 120597120588120597119901 = 1

1198882119904is the reciprocal of the sound speed (119888119904) squared Substituting into (166) gives

1205881198882119904

119863119901

119863119905+ nabla119911 middot v + 120597119911119908 asymp 0 (171)

where we have used an approximation sign to indicate that we have assumed adiabatic motion dropping the 119863120579119863119905 and

119863119878119863119905 Replacing (166) with (171) yields a system that can be explicitly integrated forward

119863vℎ

119863119905+ 119891 ktimes vℎ +

120588nabla119911119901 = ℱ (172)

120598119899ℎ119863119908

119863119905+ 119892 +

120588

120597119901

120597119911= 120598119899ℎℱ119908 (173)

1205881198882119904

119863119901

119863119905+ nabla119911 middot vℎ +

120597119908

120597119911= 0 (174)

120588 = 120588(120579 119878 119901) (175)

119863120579

119863119905= 119980120579 (176)

119863119878

119863119905= 119980119904 (177)

1511 Compressible z-coordinate equations

Here we linearize the acoustic modes by replacing 120588 with 120588119900(119911) wherever it appears in a product (ie non-linearterm) - this is the lsquoBoussinesq assumptionrsquo The only term that then retains the full variation in 120588 is the gravitationalacceleration

119863vℎ

119863119905+ 119891 ktimes vℎ +

120588119900nabla119911119901 = ℱ (178)

120598119899ℎ119863119908

119863119905+119892120588

120588119900+

120588119900

120597119901

120597119911= 120598119899ℎℱ119908 (179)

1205881199001198882119904

119863119901

119863119905+ nabla119911 middot vℎ +

120597119908

120597119911= 0 (180)

120588 = 120588(120579 119878 119901) (181)

119863120579

119863119905= 119980120579 (182)

119863119878

119863119905= 119980119904 (183)

These equations still retain acoustic modes But because the ldquocompressiblerdquo terms are linearized the pressure equa-tion (180) can be integrated implicitly with ease (the time-dependent term appears as a Helmholtz term in the non-hydrostatic pressure equation) These are the truly compressible Boussinesq equations Note that the EOS must havethe same pressure dependency as the linearized pressure term ie 120597120588

120597119901

120579119878

= 11198882119904

for consistency

15 Appendix OCEAN 31

1512 lsquoAnelasticrsquo z-coordinate equations

The anelastic approximation filters the acoustic mode by removing the time-dependency in the continuity (nowpressure-) equation (180) This could be done simply by noting that 119863119901

119863119905 asymp minus119892120588119900 119863119911119863119905 = minus119892120588119900119908 but this leads to

an inconsistency between continuity and EOS A better solution is to change the dependency on pressure in the EOSby splitting the pressure into a reference function of height and a perturbation

120588 = 120588(120579 119878 119901119900(119911) + 120598119904119901prime)

Remembering that the term 119863119901119863119905 in continuity comes from differentiating the EOS the continuity equation then be-

comes1

1205881199001198882119904

(119863119901119900119863119905

+ 120598119904119863119901prime

119863119905

)+ nabla119911 middot vℎ +

120597119908

120597119911= 0

If the time- and space-scales of the motions of interest are longer than those of acoustic modes then 119863119901prime

119863119905 ltlt (119863119901119900

119863119905 nablamiddotvℎ) in the continuity equations and 120597120588

120597119901

120579119878

119863119901prime

119863119905 ltlt 120597120588120597119901

120579119878

119863119901119900

119863119905 in the EOS (170) Thus we set 120598119904 = 0 removing

the dependency on 119901prime in the continuity equation and EOS Expanding 119863119901119900(119911)119863119905 = minus119892120588119900119908 then leads to the anelastic

continuity equation

nabla119911 middot vℎ +120597119908

120597119911minus 119892

1198882119904119908 = 0 (184)

A slightly different route leads to the quasi-Boussinesq continuity equation where we use the scaling 120597120588prime

120597119905 +nabla3 middot120588primev ltltnabla3 middot 120588119900v yielding

nabla119911 middot vℎ +1

120588119900

120597 (120588119900119908)

120597119911= 0 (185)

Equations (184) and (185) are in fact the same equation if

120588119900

120597120588119900120597119911

=minus1198921198882119904

Again note that if 120588119900 is evaluated from prescribed 120579119900 and 119878119900 profiles then the EOS dependency on 119901119900 and the term 1198921198882119904

in continuity should be referred to those same profiles The full set of lsquoquasi-Boussinesqrsquo or lsquoanelasticrsquo equations forthe ocean are then

119863vℎ

119863119905+ 119891 ktimes vℎ +

120588119900nabla119911119901 = ℱ (186)

120598119899ℎ119863119908

119863119905+119892120588

120588119900+

120588119900

120597119901

120597119911= 120598119899ℎℱ119908 (187)

120588119900

120597 (120588119900119908)

120597119911= 0 (188)

120588 = 120588(120579 119878 119901119900(119911)) (189)

119863120579

119863119905= 119980120579 (190)

119863119878

119863119905= 119980119904 (191)

1513 Incompressible z-coordinate equations

Here the objective is to drop the depth dependence of 120588119900 and so technically to also remove the dependence of 120588 on119901119900 This would yield the ldquotrulyrdquo incompressible Boussinesq equations

119863vℎ

119863119905+ 119891 ktimes vℎ +

120588119888nabla119911119901 = ℱ (192)

120598119899ℎ119863119908

119863119905+119892120588

120588119888+

120588119888

120597119901

120597119911= 120598119899ℎℱ119908 (193)

nabla119911 middot vℎ +120597119908

120597119911= 0 (194)

120588 = 120588(120579 119878) (195)

119863120579

119863119905= 119980120579 (196)

119863119878

119863119905= 119980119904 (197)

where 120588119888 is a constant reference density of water

1514 Compressible non-divergent equations

The above ldquoincompressiblerdquo equations are incompressible in both the flow and the density In many oceanic appli-cations however it is important to retain compressibility effects in the density To do this we must split the densitythus

120588 = 120588119900 + 120588prime

We then assert that variations with depth of 120588119900 are unimportant while the compressible effects in 120588prime are

120588119900 = 120588119888

120588prime = 120588(120579 119878 119901119900(119911)) minus 120588119900

This then yields what we can call the semi-compressible Boussinesq equations

119863vℎ

119863119905+ 119891 ktimes vℎ +

120588119888nabla119911119901

prime = ℱ (198)

120598119899ℎ119863119908

119863119905+119892120588prime

120588119888+

120588119888

120597119901prime

120597119911= 120598119899ℎℱ119908 (199)

nabla119911 middot vℎ +120597119908

120597119911= 0 (1100)

120588prime = 120588(120579 119878 119901119900(119911)) minus 120588119888 (1101)

119863120579

119863119905= 119980120579 (1102)

119863119878

119863119905= 119980119904 (1103)

Note that the hydrostatic pressure of the resting fluid including that associated with 120588119888 is subtracted out since it hasno effect on the dynamics

Though necessary the assumptions that go into these equations are messy since we essentially assume a differentEOS for the reference density and the perturbation density Nevertheless it is the hydrostatic (120598119899ℎ = 0) form of theseequations that are used throughout the ocean modeling community and referred to as the primitive equations (HPErsquos)

16 Appendix OPERATORS

161 Coordinate systems

1611 Spherical coordinates

In spherical coordinates the velocity components in the zonal meridional and vertical direction respectively are givenby

119906 = 119903 cos120601119863120582

119863119905

119907 = 119903119863120601

119863119905

=119863119903

119863119905

(see Figure 120) Here 120601 is the latitude 120582 the longitude 119903 the radial distance of the particle from the center of theearth Ω is the angular speed of rotation of the Earth and 119863119863119905 is the total derivative

The lsquogradrsquo (nabla) and lsquodivrsquo (nablamiddot) operators are defined by in spherical coordinates

nabla equiv(

119903 cos120601

120597

120597120582

119903

120597

120597120601120597

120597119903

nabla middot 119907 equiv 1

119903 cos120601

120597119906

120597120582+

120597

120597120601(119907 cos120601)

1199032120597(1199032)

120597119903

Figure 120 Spherical polar coordinates longitude 120582 latitude 120593 and 119903 the distance from the center

16 Appendix OPERATORS 35

CHAPTER 2

Discretization and Algorithm

This chapter lays out the numerical schemes that are employed in the core MITgcm algorithm Whenever possiblelinks are made to actual program code in the MITgcm implementation The chapter begins with a discussion of thetemporal discretization used in MITgcm This discussion is followed by sections that describe the spatial discretizationThe schemes employed for momentum terms are described first afterwards the schemes that apply to passive anddynamically active tracers are described

21 Notation

Because of the particularity of the vertical direction in stratified fluid context in this chapter the vector notations aremostly used for the horizontal component the horizontal part of a vector is simply written v (instead of vh or vℎ inchapter 1) and a 3D vector is simply written (instead of v in chapter 1)

The notations we use to describe the discrete formulation of the model are summarized as follows

General notation

∆119909∆119910∆119903 grid spacing in X Y R directions

119860119888 119860119908 119860119904 119860120577 horizontal area of a grid cell surrounding 120579 119906 119907 120577 point

119985119906119985119907119985119908119985120579 Volume of the grid box surrounding 119906 119907 119908 120579 point

119894 119895 119896 current index relative to X Y R directions

Basic operators

120575119894 120575119894Φ = Φ119894+12 minus Φ119894minus12

minus119894 Φ119894

= (Φ119894+12 + Φ119894minus12)2

120575119909 120575119909Φ = 1Δ119909120575119894Φ

nabla = horizontal gradient operator nablaΦ = 120575119909Φ 120575119910Φ

nablamiddot = horizontal divergence operator nabla middot f = 1119964120575119894∆119910 f119909 + 120575119895∆119909 f119910

nabla2= horizontal Laplacian operator nabla2

Φ = nabla middot nablaΦ

22 Time-stepping

The equations of motion integrated by the model involve four prognostic equations for flow 119906 and 119907 temperature120579 and saltmoisture 119878 and three diagnostic equations for vertical flow 119908 densitybuoyancy 120588119887 and pressuregeo-potential 120593ℎ119910119889 In addition the surface pressure or height may by described by either a prognostic or diagnosticequation and if non-hydrostatics terms are included then a diagnostic equation for non-hydrostatic pressure is alsosolved The combination of prognostic and diagnostic equations requires a model algorithm that can march forwardprognostic variables while satisfying constraints imposed by diagnostic equations

Since the model comes in several flavors and formulation it would be confusing to present the model algorithm exactlyas written into code along with all the switches and optional terms Instead we present the algorithm for each of thebasic formulations which are

1 the semi-implicit pressure method for hydrostatic equations with a rigid-lid variables co-located in time andwith Adams-Bashforth time-stepping

2 as 1 but with an implicit linear free-surface

3 as 1 or 2 but with variables staggered in time

4 as 1 or 2 but with non-hydrostatic terms included

5 as 2 or 3 but with non-linear free-surface

In all the above configurations it is also possible to substitute the Adams-Bashforth with an alternative time-steppingscheme for terms evaluated explicitly in time Since the over-arching algorithm is independent of the particular time-stepping scheme chosen we will describe first the over-arching algorithm known as the pressure method with arigid-lid model in Section 23 This algorithm is essentially unchanged apart for some coefficients when the rigidlid assumption is replaced with a linearized implicit free-surface described in Section 24 These two flavors of thepressure-method encompass all formulations of the model as it exists today The integration of explicit in time termsis out-lined in Section 25 and put into the context of the overall algorithm in Section 27 and Section 28 Inclusionof non-hydrostatic terms requires applying the pressure method in three dimensions instead of two and this algorithmmodification is described in Section 29 Finally the free-surface equation may be treated more exactly includingnon-linear terms and this is described in Section 2102

38 Chapter 2 Discretization and Algorithm

23 Pressure method with rigid-lid

The horizontal momentum and continuity equations for the ocean ((198) and (1100)) or for the atmosphere ((145)and (147)) can be summarized by

120597119905119906+ 119892120597119909120578 = 119866119906

120597119905119907 + 119892120597119910120578 = 119866119907

120597119909119906+ 120597119910119907 + 120597119911119908 = 0

where we are adopting the oceanic notation for brevity All terms in the momentum equations except for surfacepressure gradient are encapsulated in the 119866 vector The continuity equation when integrated over the fluid depth 119867 and with the rigid-lidno normal flow boundary conditions applied becomes

120597119909119867119906+ 120597119910119867119907 = 0 (21)

Here 119867119906 =int119867119906119889119911 is the depth integral of 119906 similarly for 119867119907 The rigid-lid approximation sets 119908 = 0 at the lid so

that it does not move but allows a pressure to be exerted on the fluid by the lid The horizontal momentum equationsand vertically integrated continuity equation are be discretized in time and space as follows

119906119899+1 + ∆119905119892120597119909120578119899+1 = 119906119899 + ∆119905119866(119899+12)

119906 (22)

119907119899+1 + ∆119905119892120597119910120578119899+1 = 119907119899 + ∆119905119866(119899+12)

119907 (23)

120597119909119867119906119899+1 + 120597119910119867119907119899+1 = 0 (24)

As written here terms on the LHS all involve time level 119899 + 1 and are referred to as implicit the implicit backwardtime stepping scheme is being used All other terms in the RHS are explicit in time The thermodynamic quantitiesare integrated forward in time in parallel with the flow and will be discussed later For the purposes of describing thepressure method it suffices to say that the hydrostatic pressure gradient is explicit and so can be included in the vector119866

Substituting the two momentum equations into the depth integrated continuity equation eliminates 119906119899+1 and 119907119899+1

yielding an elliptic equation for 120578119899+1 Equations (22) (23) and (24) can then be re-arranged as follows

119906 = 119906119899 + ∆119905119866(119899+12)119906 (25)

119907 = 119907119899 + ∆119905119866(119899+12)119907 (26)

120597119909∆119905119892119867120597119909120578119899+1 + 120597119910∆119905119892119867120597119910120578

119899+1 = 120597119909119867119906 + 120597119910119867 119907 (27)

119906119899+1 = 119906 minus ∆119905119892120597119909120578119899+1 (28)

23 Pressure method with rigid-lid 39

119907119899+1 = 119907 minus ∆119905119892120597119910120578119899+1 (29)

Equations (25) to (29) solved sequentially represent the pressure method algorithm used in the model The essenceof the pressure method lies in the fact that any explicit prediction for the flow would lead to a divergence flow fieldso a pressure field must be found that keeps the flow non-divergent over each step of the integration The particularlocation in time of the pressure field is somewhat ambiguous in Figure 21 we depicted as co-located with the futureflow field (time level 119899+ 1) but it could equally have been drawn as staggered in time with the flow

uvG(n+frac12)

uv n+1

∆2η = ∆ uv

∆(n+1) t∆time

n uv uv

Figure 21 A schematic of the evolution in time of the pressure method algorithm A prediction for the flow variablesat time level 119899 + 1 is made based only on the explicit terms 119866(119899+12) and denoted 119906 119907 Next a pressure field isfound such that 119906119899+1 119907119899+1 will be non-divergent Conceptually the quantities exist at time level 119899+ 1 but they areintermediate and only temporary

The correspondence to the code is as follows

bull the prognostic phase equations (25) and (26) stepping forward 119906119899 and 119907119899 to 119906 and 119907 is coded in timestepF

bull the vertical integration 119867119906 and 119867 119907 divergence and inversion of the elliptic operator in equation (27) iscoded in solve_for_pressureF

bull finally the new flow field at time level 119899+1 given by equations (28) and (29) is calculated in correction_stepF

The calling tree for these routines is as follows

Pressure method calling tree

FORWARD_STEPDYNAMICS

TIMESTEP 119906 119907 (25) (26)SOLVE_FOR_PRESSURE

CALC_DIV_GHAT 119867119906 119867 119907 (27)CG2D 120578119899+1 (27)

MOMENTUM_CORRECTION_STEPCALC_GRAD_PHI_SURF nabla120578119899+1

CORRECTION_STEP 119906119899+1 119907119899+1 (28) (29)

In general the horizontal momentum time-stepping can contain some terms that are treated implicitly in time such asthe vertical viscosity when using the backward time-stepping scheme (implicitViscosity =TRUE) The method usedto solve those implicit terms is provided in Section 26 and modifies equations (22) and (23) to give

119906119899+1 minus ∆119905120597119911119860119907120597119911119906119899+1 + ∆119905119892120597119909120578

119899+1 = 119906119899 + ∆119905119866(119899+12)119906

119907119899+1 minus ∆119905120597119911119860119907120597119911119907119899+1 + ∆119905119892120597119910120578

119899+1 = 119907119899 + ∆119905119866(119899+12)119907

24 Pressure method with implicit linear free-surface

The rigid-lid approximation filters out external gravity waves subsequently modifying the dispersion relation ofbarotropic Rossby waves The discrete form of the elliptic equation has some zero eigenvalues which makes it apotentially tricky or inefficient problem to solve

The rigid-lid approximation can be easily replaced by a linearization of the free-surface equation which can be written

120597119905120578 + 120597119909119867119906+ 120597119910119867119907 = 119875 minus 119864 +119877 (210)

which differs from the depth integrated continuity equation with rigid-lid ((21)) by the time-dependent term andfresh-water source term

Equation (24) in the rigid-lid pressure method is then replaced by the time discretization of (210) which is

120578119899+1 + ∆119905120597119909119867119906119899+1 + ∆119905120597119910119867119907119899+1 = 120578119899 + ∆119905(119875 minus 119864) (211)

where the use of flow at time level 119899+1 makes the method implicit and backward in time This is the preferred schemesince it still filters the fast unresolved wave motions by damping them A centered scheme such as Crank-Nicholson(see Section 2101) would alias the energy of the fast modes onto slower modes of motion

As for the rigid-lid pressure method equations (22) (23) and (211) can be re-arranged as follows

119906 = 119906119899 + ∆119905119866(119899+12)119906 (212)

119907 = 119907119899 + ∆119905119866(119899+12)119907 (213)

120578 = 120598119891119904(120578119899 + ∆119905(119875 minus 119864)) minus ∆119905(120597119909119867119906 + 120597119910119867 119907) (214)

120597119909119892119867120597119909120578119899+1 + 120597119910119892119867120597119910120578

119899+1 minus 120598119891119904120578119899+1

∆1199052= minus 120578

∆1199052(215)

119906119899+1 = 119906 minus ∆119905119892120597119909120578119899+1 (216)

24 Pressure method with implicit linear free-surface 41

119907119899+1 = 119907 minus ∆119905119892120597119910120578119899+1 (217)

Equations (212) to (217) solved sequentially represent the pressure method algorithm with a backward implicitlinearized free surface The method is still formerly a pressure method because in the limit of large ∆119905 the rigid-lid method is recovered However the implicit treatment of the free-surface allows the flow to be divergent and forthe surface pressureelevation to respond on a finite time-scale (as opposed to instantly) To recover the rigid-lidformulation we introduced a switch-like parameter 120598119891119904 (freesurfFac) which selects between the free-surface andrigid-lid 120598119891119904 = 1 allows the free-surface to evolve 120598119891119904 = 0 imposes the rigid-lid The evolution in time and locationof variables is exactly as it was for the rigid-lid model so that Figure 21 is still applicable Similarly the callingsequence given here is as for the pressure-method

25 Explicit time-stepping Adams-Bashforth

In describing the the pressure method above we deferred describing the time discretization of the explicit terms Wehave historically used the quasi-second order Adams-Bashforth method for all explicit terms in both the momentumand tracer equations This is still the default mode of operation but it is now possible to use alternate schemes fortracers (see Section 216) In the previous sections we summarized an explicit scheme as

120591 = 120591119899 + ∆119905119866(119899+12)120591 (218)

where 120591 could be any prognostic variable (119906 119907 120579 or 119878) and 120591 is an explicit estimate of 120591119899+1 and would be exact if notfor implicit-in-time terms The parenthesis about 119899 + 12 indicates that the term is explicit and extrapolated forwardin time and for this we use the quasi-second order Adams-Bashforth method

119866(119899+12)120591 = (32 + 120598119860119861)119866119899

120591 minus (12 + 120598119860119861)119866119899minus1120591 (219)

This is a linear extrapolation forward in time to 119905 = (119899+ 12 + 120598119860119861)∆119905 An extrapolation to the mid-point in time119905 = (119899 + 12)∆119905 corresponding to 120598119860119861 = 0 would be second order accurate but is weakly unstable for oscillatoryterms A small but finite value for 120598119860119861 stabilizes the method Strictly speaking damping terms such as diffusion anddissipation and fixed terms (forcing) do not need to be inside the Adams-Bashforth extrapolation However in thecurrent code it is simpler to include these terms and this can be justified if the flow and forcing evolves smoothlyProblems can and do arise when forcing or motions are high frequency and this corresponds to a reduced stabilitycompared to a simple forward time-stepping of such terms The model offers the possibility to leave terms outsidethe Adams-Bashforth extrapolation by turning off the logical flag forcing_In_AB (parameter file data namelistPARM01 default value = TRUE) and then setting tracForcingOutAB (default=0) momForcingOutAB (default=0)and momDissip_In_AB (parameter file data namelist PARM01 default value = TRUE) respectively for the tracerterms momentum forcing terms and the dissipation terms

A stability analysis for an oscillation equation should be given at this point

A stability analysis for a relaxation equation should be given at this point

26 Implicit time-stepping backward method

Vertical diffusion and viscosity can be treated implicitly in time using the backward method which is an intrinsicscheme Recently the option to treat the vertical advection implicitly has been added but not yet tested therefore thedescription hereafter is limited to diffusion and viscosity For tracers the time discretized equation is

0 02 04 06 08 10

ε = 000

0 02 04 06 08 10

ε = 010 fc= 05025

0 02 04 06 08 10

9ε = 025 fc= 05963

0 05 1minus15

minus1

minus05

1ε = 000 microc= 10000

0 05 1minus15

minus1

minus05

1ε = 010 microc= 09091

0 05 1minus15

minus1

minus05

1ε = 025 microc= 08000

Figure 22 Oscillatory and damping response of quasi-second order Adams-Bashforth scheme for different values ofthe 120598119860119861 parameter (00 01 025 from top to bottom) The analytical solution (in black) the physical mode (in blue)and the numerical mode (in red) are represented with a CFL step of 01 The left column represents the oscillatoryresponse on the complex plane for CFL ranging from 01 up to 09 The right column represents the damping responseamplitude (y-axis) function of the CFL (x-axis)

26 Implicit time-stepping backward method 43

120591119899+1 minus ∆119905120597119903120581119907120597119903120591119899+1 = 120591119899 + ∆119905119866(119899+12)

120591 (220)

where 119866(119899+12)120591 is the remaining explicit terms extrapolated using the Adams-Bashforth method as described above

Equation (220) can be split split into

120591 = 120591119899 + ∆119905119866(119899+12)120591 (221)

120591119899+1 = ℒminus1120591 (120591) (222)

where ℒminus1120591 is the inverse of the operator

ℒ120591 = [1 + ∆119905120597119903120581119907120597119903]

Equation (221) looks exactly as (218) while (222) involves an operator or matrix inversion By re-arranging (220)in this way we have cast the method as an explicit prediction step and an implicit step allowing the latter to be insertedinto the over all algorithm with minimal interference

The calling sequence for stepping forward a tracer variable such as temperature with implicit diffusion is as follows

Adams-Bashforth calling tree

FORWARD_STEPTHERMODYNAMICS

TEMP_INTEGRATEGAD_CALC_RHS 119866119899

120579 = 119866120579(119906 120579119899)

eitherEXTERNAL_FORCING 119866119899

120579 = 119866119899120579 + 119980

ADAMS_BASHFORTH2 119866(119899+12)120579 (219)

orEXTERNAL_FORCING 119866

(119899+12)120579 = 119866

(119899+12)120579 + 119980

TIMESTEP_TRACER 120591 (218)IMPLDIFF 120591 (119899+1) (222)

In order to fit within the pressure method the implicit viscosity must not alter the barotropic flow In other words itcan only redistribute momentum in the vertical The upshot of this is that although vertical viscosity may be backwardimplicit and unconditionally stable no-slip boundary conditions may not be made implicit and are thus cast as a anexplicit drag term

27 Synchronous time-stepping variables co-located in time

The Adams-Bashforth extrapolation of explicit tendencies fits neatly into the pressure method algorithm when all statevariables are co-located in time The algorithm can be represented by the sequential solution of the follow equations

119866119899120579119878 = 119866120579119878(119906119899 120579119899 119878119899) (223)

∆(n+1) t∆(nminus1) t ∆time

Sθ Sθ Sθ

Sθ n+1Lminus1

θS θS θS

θSΦh

Lminus1

uv n+1

nminus1 n Gnminus1 GGn (n+frac12)

nminus1 n uv uv uvuvGnminus1

uv uvG(n+frac12)Gn

Figure 23 A schematic of the explicit Adams-Bashforth and implicit time-stepping phases of the algorithm Allprognostic variables are co-located in time Explicit tendencies are evaluated at time level 119899 as a function of the stateat that time level (dotted arrow) The explicit tendency from the previous time level 119899 minus 1 is used to extrapolatetendencies to 119899 + 12 (dashed arrow) This extrapolated tendency allows variables to be stably integrated forward-in-time to render an estimate ( -variables) at the 119899 + 1 time level (solid arc-arrow) The operator ℒ formed fromimplicit-in-time terms is solved to yield the state variables at time level 119899+ 1

27 Synchronous time-stepping variables co-located in time 45

119866(119899+12)120579119878 = (32 + 120598119860119861)119866119899

120579119878 minus (12 + 120598119860119861)119866119899minus1120579119878

(120579 119878) = (120579119899 119878119899) + ∆119905119866(119899+12)120579119878

(120579119899+1 119878119899+1) = ℒminus1120579119878(120579 119878) (226)

120593119899ℎ119910119889 =

int119887(120579119899 119878119899)119889119903 (227)

G119899v = Gv(v119899 120593119899ℎ119910119889) (228)

G(119899+12)v = (32 + 120598119860119861)G119899

v minus (12 + 120598119860119861)G119899minus1v

v = v119899 + ∆119905G(119899+12)v

v = ℒminus1v (v) (231)

120578 = 120598119891119904 (120578119899 + ∆119905(119875 minus 119864)) minus ∆119905nabla middot119867v (232)

nabla middot 119892119867nabla120578119899+1 minus 120598119891119904120578119899+1

∆1199052= minus 120578

∆1199052(233)

v119899+1 = v minus ∆119905119892nabla120578119899+1 (234)

Figure 23 illustrates the location of variables in time and evolution of the algorithm with time The Adams-Bashforthextrapolation of the tracer tendencies is illustrated by the dashed arrow the prediction at 119899 + 1 is indicated by thesolid arc Inversion of the implicit terms ℒminus1

120579119878 then yields the new tracer fields at 119899 + 1 All these operations arecarried out in subroutine THERMODYNAMICS and subsidiaries which correspond to equations (223) to (226)Similarly illustrated is the Adams-Bashforth extrapolation of accelerations stepping forward and solving of implicitviscosity and surface pressure gradient terms corresponding to equations (228) to (234) These operations are carriedout in subroutines DYNAMICS SOLVE_FOR_PRESSURE and MOMENTUM_CORRECTION_STEP This thenrepresents an entire algorithm for stepping forward the model one time-step The corresponding calling tree for theoverall synchronous algorithm using Adams-Bashforth time-stepping is given below The place where the modelgeometry hFac factors) is updated is added here but is only relevant for the non-linear free-surface algorithm Forcompleteness the external forcing ocean and atmospheric physics have been added although they are mainly optional

Synchronous Adams-Bashforth calling tree

FORWARD_STEPEXTERNAL_FIELDS_LOADDO_ATMOSPHERIC_PHYSDO_OCEANIC_PHYS

THERMODYNAMICSCALC_GT

GAD_CALC_RHS 119866119899120579 = 119866120579(119906 120579119899) (223)

EXTERNAL_FORCING 119866119899120579 = 119866119899

120579 + 119980ADAMS_BASHFORTH2 119866

(119899+12)120579 (224)

TIMESTEP_TRACER 120579 (225)IMPLDIFF 120579(119899+1) (226)

DYNAMICSCALC_PHI_HYD 120593119899ℎ119910119889 (227)MOM_FLUXFORM or MOM_VECINV 119866119899

v (228)TIMESTEP v (229) (230)IMPLDIFF v (231)

UPDATE_R_STAR or UPDATE_SURF_DR (NonLin-FS only)SOLVE_FOR_PRESSURE

CALC_DIV_GHAT 120578 (232)CG2D 120578119899+1 (233)

CORRECTION_STEP 119906119899+1 119907119899+1 (234)TRACERS_CORRECTION_STEP

CYCLE_TRACER 120579119899+1

SHAP_FILT_APPLY_TS or ZONAL_FILT_APPLY_TSCONVECTIVE_ADJUSTMENT

28 Staggered baroclinic time-stepping

For well-stratified problems internal gravity waves may be the limiting process for determining a stable time-step Inthe circumstance it is more efficient to stagger in time the thermodynamic variables with the flow variables Figure24 illustrates the staggering and algorithm The key difference between this and Figure 23 is that the thermodynamicvariables are solved after the dynamics using the recently updated flow field This essentially allows the gravity waveterms to leap-frog in time giving second order accuracy and more stability

The essential change in the staggered algorithm is that the thermodynamics solver is delayed from half a time stepallowing the use of the most recent velocities to compute the advection terms Once the thermodynamics fields areupdated the hydrostatic pressure is computed to step forward the dynamics Note that the pressure gradient must alsobe taken out of the Adams-Bashforth extrapolation Also retaining the integer time-levels 119899 and 119899 + 1 does notgive a user the sense of where variables are located in time Instead we re-write the entire algorithm (223) to (234)annotating the position in time of variables appropriately

120593119899ℎ119910119889 =

int119887(120579119899 119878119899)119889119903 (235)

28 Staggered baroclinic time-stepping 47

Lminus1

Sθ Sθ Sθ

Lminus1

θS θS

SθΦh

∆ (n+frac12) t∆(nminusfrac12) t

(nminus1frac12) t∆

uv uv uvuvG uvGuvG

(n+frac12)

nminusfrac12

nminus1frac12

nminus1

nminus1frac12 nminusfrac12

uv(n+frac12)

nminus1 n

Figure 24 A schematic of the explicit Adams-Bashforth and implicit time-stepping phases of the algorithm but withstaggering in time of thermodynamic variables with the flow Explicit momentum tendencies are evaluated at timelevel 119899 minus 12 as a function of the flow field at that time level 119899 minus 12 The explicit tendency from the previous timelevel 119899 minus 32 is used to extrapolate tendencies to 119899 (dashed arrow) The hydrostatic pressuregeo-potential 120593ℎ119910119889is evaluated directly at time level 119899 (vertical arrows) and used with the extrapolated tendencies to step forward theflow variables from 119899minus 12 to 119899+ 12 (solid arc-arrow) The implicit-in-time operator ℒuv (vertical arrows) is thenapplied to the previous estimation of the the flow field ( -variables) and yields to the two velocity components 119906 119907 attime level 119899 + 12 These are then used to calculate the advection term (dashed arc-arrow) of the thermo-dynamicstendencies at time step 119899 The extrapolated thermodynamics tendency from time level 119899minus 1 and 119899 to 119899+ 12 allowsthermodynamic variables to be stably integrated forward-in-time (solid arc-arrow) up to time level 119899+ 1

G119899minus12v = Gv(v119899minus12) (236)

G(119899)v = (32 + 120598119860119861)G

119899minus12v minus (12 + 120598119860119861)G

119899minus32v

v = v119899minus12 + ∆119905(G

(119899)v minusnabla120593119899ℎ119910119889

)(238)

120578 = 120598119891119904

(120578119899minus12 + ∆119905(119875 minus 119864)119899

)minus ∆119905nabla middot119867v (240)

∆1199052= minus 120578

∆1199052(241)

v119899+12 = v minus ∆119905119892nabla120578119899+12 (242)

119866119899120579119878 = 119866120579119878(119906119899+12 120579119899 119878119899) (243)

119866(119899+12)120579119878 = (32 + 120598119860119861)119866119899

120579119878 minus (12 + 120598119860119861)119866119899minus1120579119878

(120579 119878) = (120579119899 119878119899) + ∆119905119866(119899+12)120579119878

(120579119899+1 119878119899+1) = ℒminus1120579119878(120579 119878) (246)

The corresponding calling tree is given below The staggered algorithm is activated with the run-time flag stagger-TimeStep =TRUE in parameter file data namelist PARM01

Staggered Adams-Bashforth calling tree

DYNAMICSCALC_PHI_HYD 120593119899ℎ119910119889 (235)

MOM_FLUXFORM or MOM_VECINV 119866119899minus12v (236)

TIMESTEP v (237) (238)IMPLDIFF v (239)

CALC_DIV_GHAT 120578 (240)CG2D 120578119899+12 (241)

CORRECTION_STEP 119906119899+12 119907119899+12 (242)THERMODYNAMICS

CALC_GTGAD_CALC_RHS 119866119899

120579 = 119866120579(119906 120579119899) (243)EXTERNAL_FORCING 119866119899

120579 = 119866119899120579 + 119980

ADAMS_BASHFORTH2 119866(119899+12)120579 (244)

TRACERS_CORRECTION_STEPCYCLE_TRACER 120579119899+1

The only difficulty with this approach is apparent in equation (243) and illustrated by the dotted arrow connecting119906 119907119899+12 with 119866119899

120579 The flow used to advect tracers around is not naturally located in time This could be avoided byapplying the Adams-Bashforth extrapolation to the tracer field itself and advecting that around but this approach is notyet available Wersquore not aware of any detrimental effect of this feature The difficulty lies mainly in interpretation ofwhat time-level variables and terms correspond to

29 Non-hydrostatic formulation

The non-hydrostatic formulation re-introduces the full vertical momentum equation and requires the solution of a 3-Delliptic equations for non-hydrostatic pressure perturbation We still integrate vertically for the hydrostatic pressureand solve a 2-D elliptic equation for the surface pressureelevation for this reduces the amount of work needed to solvefor the non-hydrostatic pressure

The momentum equations are discretized in time as follows

∆119905119906119899+1 + 119892120597119909120578

119899+1 + 120597119909120593119899+1119899ℎ =

∆119905119906119899 +119866(119899+12)

119906 (247)

∆119905119907119899+1 + 119892120597119910120578

119899+1 + 120597119910120593119899+1119899ℎ =

∆119905119907119899 +119866(119899+12)

119907 (248)

∆119905119908119899+1 + 120597119903120593

119899+1119899ℎ =

∆119905119908119899 +119866(119899+12)

119908 (249)

which must satisfy the discrete-in-time depth integrated continuity equation (211) and the local continuity equation

120597119909119906119899+1 + 120597119910119907

119899+1 + 120597119903119908119899+1 = 0 (250)

As before the explicit predictions for momentum are consolidated as

119906 = 119906119899 + ∆119905119866(119899+12)119906

119907 = 119907119899 + ∆119905119866(119899+12)119907

119908 = 119908119899 + ∆119905119866(119899+12)119908

but this time we introduce an intermediate step by splitting the tendency of the flow as follows

119906119899+1 = 119906 minus ∆119905120597119909120593119899+1119899ℎ 119906 = 119906 minus ∆119905119892120597119909120578

119899+1

119907119899+1 = 119907 minus ∆119905120597119910120593119899+1119899ℎ 119907 = 119907 minus ∆119905119892120597119910120578

119899+1

Substituting into the depth integrated continuity (equation (211)) gives

120597119909119867120597119909

(119892120578119899+1 + 120593119899+1

119899ℎ

)+ 120597119910119867120597119910

(119892120578119899+1 + 120593119899+1

119899ℎ

)minus 120598119891119904120578

119899+1

∆1199052= minus 120578

∆1199052(251)

which is approximated by equation (215) on the basis that i) 120593119899+1119899ℎ is not yet known and ii) nabla120593119899ℎ ltlt 119892nabla120578 If (215)

is solved accurately then the implication is that 120593119899ℎ asymp 0 so that the non-hydrostatic pressure field does not drivebarotropic motion

The flow must satisfy non-divergence (equation (250)) locally as well as depth integrated and this constraint is usedto form a 3-D elliptic equations for 120593119899+1

119899ℎ

120597119909119909120593119899+1119899ℎ + 120597119910119910120593

119899+1119899ℎ + 120597119903119903120593

119899+1119899ℎ = 120597119909119906

+ 120597119910119907 + 120597119903119908

The entire algorithm can be summarized as the sequential solution of the following equations

119906 = 119906119899 + ∆119905119866(119899+12)119906 (253)

119907 = 119907119899 + ∆119905119866(119899+12)119907 (254)

119908 = 119908119899 + ∆119905119866(119899+12)119908 (255)

120578 = 120598119891119904 (120578119899 + ∆119905(119875 minus 119864)) minus ∆119905(120597119909119867119906 + 120597119910119867 119907) (256)

120597119909119892119867120597119909120578119899+1 + 120597119910119892119867120597119910120578

119899+1 minus 120598119891119904120578119899+1

∆1199052= minus 120578

∆1199052(257)

119906 = 119906 minus ∆119905119892120597119909120578119899+1 (258)

29 Non-hydrostatic formulation 51

119907 = 119907 minus ∆119905119892120597119910120578119899+1 (259)

120597119909119909120593119899+1119899ℎ + 120597119910119910120593

119899+1119899ℎ + 120597119903119903120593

119899+1119899ℎ = 120597119909119906

+ 120597119910119907 + 120597119903119908

119906119899+1 = 119906 minus ∆119905120597119909120593119899+1119899ℎ (261)

119907119899+1 = 119907 minus ∆119905120597119910120593119899+1119899ℎ (262)

120597119903119908119899+1 = minus120597119909119906119899+1 minus 120597119910119907

119899+1 (263)

where the last equation is solved by vertically integrating for 119908119899+1

210 Variants on the Free Surface

We now describe the various formulations of the free-surface that include non-linear forms implicit in time usingCrank-Nicholson explicit and [one day] split-explicit First wersquoll reiterate the underlying algorithm but this time usingthe notation consistent with the more general vertical coordinate 119903 The elliptic equation for free-surface coordinate(units of 119903) corresponding to (211) and assuming no non-hydrostatic effects (120598119899ℎ = 0) is

120598119891119904120578119899+1 minusnablaℎ middot ∆1199052(119877119900 minus119877119891119894119909119890119889)nablaℎ119887119904120578

119899+1 = 120578 (264)

120578 = 120598119891119904 120578119899 minus ∆119905nablaℎ middot

int 119877119900

119877119891119894119909119890119889

v119889119903 + 120598119891119908∆119905(119875 minus 119864)119899 (265)

SR SOLVE_FOR_PRESSURE

119906 gU ( DYNVARSh )119907 gV ( DYNVARSh )120578 cg2d_b ( SOLVE_FOR_PRESSUREh )120578119899+1 etaN ( DYNVARSh )

Once 120578119899+1 has been found substituting into (22) (23) yields v119899+1 if the model is hydrostatic (120598119899ℎ = 0)

v119899+1 = v minus ∆119905nablaℎ119887119904120578119899+1

This is known as the correction step However when the model is non-hydrostatic (120598119899ℎ = 1) we need an additionalstep and an additional equation for 120593prime119899ℎ This is obtained by substituting (247) (248) and (249) into continuity

[nabla2ℎ + 120597119903119903]120593prime119899ℎ

119899+1=

∆119905nablaℎ middot v + 120597119903

v = v minus ∆119905nablaℎ119887119904120578119899+1

Note that 120578119899+1 is also used to update the second RHS term 120597119903 since the vertical velocity at the surface (119904119906119903119891 ) is

evaluated as (120578119899+1 minus 120578119899)∆119905

Finally the horizontal velocities at the new time level are found by

v119899+1 = v minus 120598119899ℎ∆119905nablaℎ120593prime119899ℎ

119899+1 (267)

and the vertical velocity is found by integrating the continuity equation vertically Note that for the convenience ofthe restart procedure the vertical integration of the continuity equation has been moved to the beginning of the timestep (instead of at the end) without any consequence on the solution

SR CORRECTION_STEP

120578119899+1 etaN ( DYNVARSh )120593119899+1119899ℎ phi_nh ( NH_VARSh )119906 gU ( DYNVARSh )119907 gV ( DYNVARSh )119906119899+1 uVel ( DYNVARSh )119907119899+1 vVel ( DYNVARSh )

Regarding the implementation of the surface pressure solver all computation are done within the routineSOLVE_FOR_PRESSURE and its dependent calls The standard method to solve the 2D elliptic problem (264)uses the conjugate gradient method (routine CG2D) the solver matrix and conjugate gradient operator are only func-tion of the discretized domain and are therefore evaluated separately before the time iteration loop within INI_CG2DThe computation of the RHS 120578 is partly done in CALC_DIV_GHAT and in SOLVE_FOR_PRESSURE

The same method is applied for the non hydrostatic part using a conjugate gradient 3D solver (CG3D) that is initializedin INI_CG3D The RHS terms of 2D and 3D problems are computed together at the same point in the code

2101 Crank-Nicolson barotropic time stepping

The full implicit time stepping described previously is unconditionally stable but damps the fast gravity waves result-ing in a loss of potential energy The modification presented now allows one to combine an implicit part (120573 120574) andan explicit part (1 minus 120573 1 minus 120574) for the surface pressure gradient (120573) and for the barotropic flow divergence (120574) Forinstance 120573 = 120574 = 1 is the previous fully implicit scheme 120573 = 120574 = 12 is the non damping (energy conserving)unconditionally stable Crank-Nicolson scheme (120573 120574) = (1 0) or = (0 1) corresponds to the forward - backwardscheme that conserves energy but is only stable for small time steps In the code 120573 120574 are defined as parameters re-spectively implicSurfPress implicDiv2DFlow They are read from the main parameter file data (namelist PARM01)and are set by default to 11

Equations (212) ndash (217) are modified as follows

v119899+1

∆119905+ nablaℎ119887119904[120573120578

119899+1 + (1 minus 120573)120578119899] + 120598119899ℎnablaℎ120593prime119899ℎ

119899+1=

v119899

∆119905+ G

(119899+12)v + nablaℎ120593

primeℎ119910119889

(119899+12)

210 Variants on the Free Surface 53

120598119891119904120578119899+1 minus 120578119899

∆119905+ nablaℎ middot

int 119877119900

119877119891119894119909119890119889

[120574v119899+1 + (1 minus 120574)v119899]119889119903 = 120598119891119908(119875 minus 119864) (268)

We set

v = v119899 + ∆119905G(119899+12)v + (120573 minus 1)∆119905nablaℎ119887119904120578

119899 + ∆119905nablaℎ120593primeℎ119910119889

(119899+12)

120578 = 120598119891119904120578119899 + 120598119891119908∆119905(119875 minus 119864) minus ∆119905nablaℎ middot

int 119877119900

119877119891119894119909119890119889

[120574v + (1 minus 120574)v119899]119889119903

In the hydrostatic case 120598119899ℎ = 0 allowing us to find 120578119899+1 thus

120598119891119904120578119899+1 minusnablaℎ middot 120573120574∆1199052119887119904(119877119900 minus119877119891119894119909119890119889)nablaℎ120578

119899+1 = 120578

and then to compute (CORRECTION_STEP)

v119899+1 = v minus 120573∆119905nablaℎ119887119904120578119899+1

1 The RHS term of equation (268) corresponds the contribution of fresh water flux (P-E) to the free-surfacevariations (120598119891119908 = 1 useRealFreshWaterFlux =TRUE in parameter file data) In order to remain consistentwith the tracer equation specially in the non-linear free-surface formulation this term is also affected by theCrank-Nicolson time stepping The RHS reads 120598119891119908(120574(119875 minus 119864)119899+12 + (1 minus 120574)(119875 minus 119864)119899minus12)

2 The stability criteria with Crank-Nicolson time stepping for the pure linear gravity wave problem in cartesiancoordinates is

bull 120573 + 120574 lt 1 unstable

bull 120573 ge 12 and 120574 ge 12 stable

bull 120573 + 120574 ge 1 stable if 1198882119898119886119909(120573 minus 12)(120574 minus 12) + 1 ge 0 with 119888119898119886119909 = 2∆119905radic119892119867radic

1Δ1199092 + 1

Δ1199102

3 A similar mixed forwardbackward time-stepping is also available for the non-hydrostatic algorithm with afraction 120573119899ℎ (0 lt 120573119899ℎ le 1) of the non-hydrostatic pressure gradient being evaluated at time step 119899 + 1(backward in time) and the remaining part (1 minus 120573119899ℎ) being evaluated at time step 119899 (forward in time) The run-time parameter implicitNHPress corresponding to the implicit fraction 120573119899ℎ of the non-hydrostatic pressure is setby default to the implicit fraction 120573 of surface pressure (implicSurfPress) but can also be specified independently(in main parameter file data namelist PARM01)

2102 Non-linear free-surface

Options have been added to the model that concern the free surface formulation

21021 Pressuregeo-potential and free surface

For the atmosphere since 120593 = 120593119905119900119901119900 minusint 119901

119901119904120572119889119901 subtracting the reference state defined in section Section 1412

120593119900 = 120593119905119900119901119900 minusint 119901

119901119900

120572119900119889119901 with 120593119900(119901119900) = 120593119905119900119901119900

we get

120593prime = 120593minus 120593119900 =

int 119901119904

119901

120572119889119901minusint 119901119900

119901

120572119900119889119901

For the ocean the reference state is simpler since 120588119888 does not dependent on 119911 (119887119900 = 119892) and the surface referenceposition is uniformly 119911 = 0 (119877119900 = 0) and the same subtraction leads to a similar relation For both fluids using theisomorphic notations we can write

120593prime =

int 119903119904119906119903119891

119903

119887 119889119903 minusint 119877119900

119903

119887119900119889119903

and re-write as

120593prime =

int 119903119904119906119903119891

119877119900

119887 119889119903 +

int 119877119900

119903

(119887minus 119887119900)119889119903 (269)

120593prime =

int 119903119904119906119903119891

119877119900

119887119900119889119903 +

int 119903119904119906119903119891

119903

(119887minus 119887119900)119889119903 (270)

In section Section 136 following eq (269) the pressuregeo-potential 120593prime has been separated into surface (120593119904) andhydrostatic anomaly (120593primeℎ119910119889) In this section the split between 120593119904 and 120593primeℎ119910119889 is made according to equation (270) Thisslightly different definition reflects the actual implementation in the code and is valid for both linear and non-linearfree-surface formulation in both r-coordinate and r-coordinate

Because the linear free-surface approximation ignores the tracer content of the fluid parcel between 119877119900 and 119903119904119906119903119891 =119877119900 + 120578 for consistency reasons this part is also neglected in 120593primeℎ119910119889

120593primeℎ119910119889 =

int 119903119904119906119903119891

119903

(119887minus 119887119900)119889119903 ≃int 119877119900

119903

(119887minus 119887119900)119889119903

Note that in this case the two definitions of 120593119904 and 120593primeℎ119910119889 from equations (269) and (270) converge toward the

same (approximated) expressions 120593119904 =int 119903119904119906119903119891

119877119900119887119900119889119903 and 120593primeℎ119910119889 =

int 119877119900

119903119887prime119889119903 On the contrary the unapproximated

formulation (ldquonon-linear free-surfacerdquo see the next section) retains the full expression 120593primeℎ119910119889 =int 119903119904119906119903119891

119903(119887 minus 119887119900)119889119903

This is obtained by selecting nonlinFreeSurf =4 in parameter file data Regarding the surface potential

120593119904 =

int 119877119900+120578

119877119900

119887119900119889119903 = 119887119904120578 with 119887119904 =1

120578

int 119877119900+120578

119877119900

119887119900119889119903

119887119904 ≃ 119887119900(119877119900) is an excellent approximation (better than the usual numerical truncation since generally |120578| is smallerthan the vertical grid increment)

For the ocean 120593119904 = 119892120578 and 119887119904 = 119892 is uniform For the atmosphere however because of topographic effects thereference surface pressure 119877119900 = 119901119900 has large spatial variations that are responsible for significant 119887119904 variations (from08 to 12 [1198983119896119892]) For this reason when uniformLin_PhiSurf =FALSE (parameter file data namelist PARAM01)a non-uniform linear coefficient 119887119904 is used and computed (INI_LINEAR_PHISURF) according to the reference surfacepressure 119901119900 119887119904 = 119887119900(119877119900) = 119888119901120581(119901119900119875

119900119878119871)(120581minus1)120579119903119890119891 (119901119900) with 119875 119900

119878119871 the mean sea-level pressure

21022 Free surface effect on column total thickness (Non-linear free-surface)

The total thickness of the fluid column is 119903119904119906119903119891 minus 119877119891119894119909119890119889 = 120578 + 119877119900 minus 119877119891119894119909119890119889 In most applications the free surfacedisplacements are small compared to the total thickness 120578 ≪ 119867119900 = 119877119900 minus 119877119891119894119909119890119889 In the previous sections and inolder version of the model the linearized free-surface approximation was made assuming 119903119904119906119903119891 minus 119877119891119894119909119890119889 ≃ 119867119900

when computing horizontal transports either in the continuity equation or in tracer and momentum advection termsThis approximation is dropped when using the non-linear free-surface formulation and the total thickness includingthe time varying part 120578 is considered when computing horizontal transports Implications for the barotropic part are

presented hereafter In section Section 21023 consequences for tracer conservation is briefly discussed (more detailscan be found in Campin et al (2004) [CAHM04]) the general time-stepping is presented in section Section 21024with some limitations regarding the vertical resolution in section Section 21025

In the non-linear formulation the continuous form of the model equations remains unchanged except for the 2Dcontinuity equation (211) which is now integrated from 119877119891119894119909119890119889(119909 119910) up to 119903119904119906119903119891 = 119877119900 + 120578

120598119891119904120597119905120578 = |119903=119903119904119906119903119891+ 120598119891119908(119875 minus 119864) = minusnablaℎ middot

int 119877119900+120578

119877119891119894119909119890119889

v119889119903 + 120598119891119908(119875 minus 119864)

Since 120578 has a direct effect on the horizontal velocity (through nablaℎΦ119904119906119903119891 ) this adds a non-linear term to the free surfaceequation Several options for the time discretization of this non-linear part can be considered as detailed below

If the column thickness is evaluated at time step 119899 and with implicit treatment of the surface potential gradientequations (264) and (265) become

120598119891119904120578119899+1 minusnablaℎ middot ∆1199052(120578119899 +119877119900 minus119877119891119894119909119890119889)nablaℎ119887119904120578

119899+1 = 120578

int 119877119900+120578119899

119877119891119894119909119890119889

v119889119903 + 120598119891119908∆119905(119875 minus 119864)119899

This method requires us to update the solver matrix at each time step

Alternatively the non-linear contribution can be evaluated fully explicitly

119899+1 = 120578 + nablaℎ middot ∆1199052(120578119899)nablaℎ119887119904120578119899

This formulation allows one to keep the initial solver matrix unchanged though throughout the integration since thenon-linear free surface only affects the RHS

Finally another option is a ldquolinearizedrdquo formulation where the total column thickness appears only in the integral termof the RHS (265) but not directly in the equation (264)

Those different options (see Table 21) have been tested and show little differences However we recommend the useof the most precise method (nonlinFreeSurf =4) since the computation cost involved in the solver matrix update isnegligible

Table 21 Non-linear free-surface flagsparameter value description

-1 linear free-surface restart from a pickup fileproduced with undef EXACT_CONSERV code

0 Linear free-surfacenonlinFreeSurf 4 Non-linear free-surface

3 same as 4 but neglectingint 119877119900+120578

119877119900119887prime119889119903 in Φprime

ℎ119910119889

2 same as 3 but do not update cg2d solver matrix1 same as 2 but treat momentum as in Linear FS0 do not use 119903 vertical coordinate (= default)

select_rStar 2 use 119903 vertical coordinate1 same as 2 but without the contribution of the

slope of the coordinate in nablaΦ

21023 Tracer conservation with non-linear free-surface

To ensure global tracer conservation (ie the total amount) as well as local conservation the change in the surfacelevel thickness must be consistent with the way the continuity equation is integrated both in the barotropic part (tofind 120578) and baroclinic part (to find 119908 = )

To illustrate this consider the shallow water model with a source of fresh water (P)

120597119905ℎ+ nabla middot ℎv = 119875

where ℎ is the total thickness of the water column To conserve the tracer 120579 we have to discretize

120597119905(ℎ120579) + nabla middot (ℎ120579v) = 119875120579rain

Using the implicit (non-linear) free surface described above (Section 24) we have

ℎ119899+1 = ℎ119899 minus ∆119905nabla middot (ℎ119899 v119899+1) + ∆119905119875

The discretized form of the tracer equation must adopt the same ldquoformrdquo in the computation of tracer fluxes that is thesame value of ℎ as used in the continuity equation

ℎ119899+1 120579119899+1 = ℎ119899 120579119899 minus ∆119905nabla middot (ℎ119899 120579119899 v119899+1) + ∆119905119875120579119903119886119894119899

The use of a 3 time-levels time-stepping scheme such as the Adams-Bashforth make the conservation sightly trickyThe current implementation with the Adams-Bashforth time-stepping provides an exact local conservation and pre-vents any drift in the global tracer content (Campin et al (2004) [CAHM04]) Compared to the linear free-surfacemethod an additional step is required the variation of the water column thickness (from ℎ119899 to ℎ119899+1) is not incorpo-rated directly into the tracer equation Instead the model uses the 119866120579 terms (first step) as in the linear free surfaceformulation (with the ldquosurface correctionrdquo turned ldquoonrdquo see tracer section)

119866119899120579 =

(minusnabla middot (ℎ119899 120579119899 v119899+1) minus 119899+1

119904119906119903119891120579119899)ℎ119899

Then in a second step the thickness variation (expansionreduction) is taken into account

120579119899+1 = 120579119899 + ∆119905ℎ119899

ℎ119899+1

(119866

(119899+12)120579 + 119875 (120579rain minus 120579119899)ℎ119899

)Note that with a simple forward time step (no Adams-Bashforth) these two formulations are equivalent since (ℎ119899+1minusℎ119899)∆119905 = 119875 minusnabla middot (ℎ119899 v119899+1) = 119875 + 119899+1

119904119906119903119891

21024 Time stepping implementation of the non-linear free-surface

The grid cell thickness was hold constant with the linear free-surface with the non-linear free-surface it is nowvarying in time at least at the surface level This implies some modifications of the general algorithm described earlierin sections Section 27 and Section 28

A simplified version of the staggered in time non-linear free-surface algorithm is detailed hereafter and can becompared to the equivalent linear free-surface case (eq (236) to (246)) and can also be easily transposed to thesynchronous time-stepping case Among the simplifications salinity equation implicit operator and detailed ellip-tic equation are omitted Surface forcing is explicitly written as fluxes of temperature fresh water and momentum119876119899+12 119875119899+12 119865119899

v respectively ℎ119899 and 119889ℎ119899 are the column and grid box thickness in r-coordinate

120593119899ℎ119910119889 =

int119887(120579119899 119878119899 119903)119889119903 (271)

G119899minus12v = Gv(119889ℎ119899minus1 v119899minus12) G

(119899)v =

119899minus12v minus 1

119899minus32v

v = v119899minus12 + ∆119905119889ℎ119899minus1

119889ℎ119899

(119899)v + 119865119899

v 119889ℎ119899minus1)minus ∆119905nabla120593119899ℎ119910119889 (273)

minusrarr 119906119901119889119886119905119890 119898119900119889119890119897 119892119890119900119898119890119905119903119910 hFac(119889ℎ119899)

120578119899+12= 120578119899minus12 + ∆119905119875119899+12 minus ∆119905nabla middotint

v119899+12119889ℎ119899

= 120578119899minus12 + ∆119905119875119899+12 minus ∆119905nabla middotint(

v minus 119892∆119905nabla120578119899+12)119889ℎ119899

v119899+12= v minus 119892∆119905nabla120578119899+12 (275)

ℎ119899+1 = ℎ119899 + ∆119905119875119899+12 minus ∆119905nabla middotint

v119899+12119889ℎ119899 (276)

119866119899120579 = 119866120579(119889ℎ119899 119906119899+12 120579119899) 119866

(119899+12)120579 =

2119866119899

120579 minus 1

2119866119899minus1

120579(277)

120579119899+1 = 120579119899 + ∆119905119889ℎ119899

119889ℎ119899+1

(119866

(119899+12)120579 + (119875119899+12(120579rain minus 120579119899) +119876119899+12)119889ℎ119899

)Two steps have been added to linear free-surface algorithm (eq (236) to (246)) Firstly the model ldquogeometryrdquo (herethe hFacCWS) is updated just before entering SOLVE_FOR_PRESSURE using the current 119889ℎ119899 field Secondlythe vertically integrated continuity equation (276) has been added (exactConserv =TRUE in parameter file datanamelist PARM01) just before computing the vertical velocity in subroutine INTEGR_CONTINUITY Although thisequation might appear redundant with (274) the integrated column thickness ℎ119899+1 will be different from 120578119899+12 +119867 in the following cases

bull when Crank-Nicolson time-stepping is used (see Section 2101)

bull when filters are applied to the flow field after (275) and alter the divergence of the flow

bull when the solver does not iterate until convergence for example because a too large residual target was set(cg2dTargetResidual parameter file data namelist PARM02)

In this staggered time-stepping algorithm the momentum tendencies are computed using 119889ℎ119899minus1 geometry factors(272) and then rescaled in subroutine TIMESTEP (273) similarly to tracer tendencies (see Section 21023) Thetracers are stepped forward later using the recently updated flow field v119899+12 and the corresponding model geometry119889ℎ119899 to compute the tendencies (277) then the tendencies are rescaled by 119889ℎ119899119889ℎ119899+1 to derive the new tracers values(120579 119878)119899+1 ((278) in subroutines CALC_GT CALC_GS)

Note that the fresh-water input is added in a consistent way in the continuity equation and in the tracer equation takinginto account the fresh-water temperature 120579rain

Regarding the restart procedure two 2D fields ℎ119899minus1 and (ℎ119899 minus ℎ119899minus1)∆119905 in addition to the standard state variablesand tendencies (120578119899minus12 v119899minus12 120579119899 119878119899 G119899minus32

v 119866119899minus1120579119878 ) are stored in a ldquopickuprdquo file The model restarts reading

this pickup file then updates the model geometry according to ℎ119899minus1 and compute ℎ119899 and the vertical velocity beforestarting the main calling sequence (eq (271) to (278) FORWARD_STEP)

SR INTEGR_CONTINUITY

ℎ119899+1 minus119867119900 etaH ( DYNVARSh )ℎ119899 minus119867119900 etaHnm1 ( SURFACEh )(ℎ119899+1 minus ℎ119899)∆119905 dEtaHdt ( SURFACEh )

21025 Non-linear free-surface and vertical resolution

When the amplitude of the free-surface variations becomes as large as the vertical resolution near the surface thesurface layer thickness can decrease to nearly zero or can even vanish completely This later possibility has not beenimplemented and a minimum relative thickness is imposed (hFacInf parameter file data namelist PARM01) toprevent numerical instabilities caused by very thin surface level

A better alternative to the vanishing level problem relies on a different vertical coordinate 119903 The time variation ofthe total column thickness becomes part of the 119903 coordinate motion as in a 120590119911 120590119901 model but the fixed part relatedto topography is treated as in a height or pressure coordinate model A complete description is given in Adcroft andCampin (2004) [AC04]

The time-stepping implementation of the 119903 coordinate is identical to the non-linear free-surface in 119903 coordinate anddifferences appear only in the spacial discretization

211 Spatial discretization of the dynamical equations

Spatial discretization is carried out using the finite volume method This amounts to a grid-point method (namelysecond-order centered finite difference) in the fluid interior but allows boundaries to intersect a regular grid allowinga more accurate representation of the position of the boundary We treat the horizontal and vertical directions asseparable and differently

2111 The finite volume method finite volumes versus finite difference

The finite volume method is used to discretize the equations in space The expression ldquofinite volumerdquo actually has twomeanings one is the method of embedded or intersecting boundaries (shaved or lopped cells in our terminology) andthe other is non-linear interpolation methods that can deal with non-smooth solutions such as shocks (ie flux limitersfor advection) Both make use of the integral form of the conservation laws to which the weak solution is a solutionon each finite volume of (sub-domain) The weak solution can be constructed out of piece-wise constant elements orbe differentiable The differentiable equations can not be satisfied by piece-wise constant functions

As an example the 1-D constant coefficient advection-diffusion equation

120597119905120579 + 120597119909(119906120579 minus 120581120597119909120579) = 0

can be discretized by integrating over finite sub-domains ie the lengths ∆119909119894

∆119909120597119905120579 + 120575119894(119865 ) = 0

is exact if 120579(119909) is piece-wise constant over the interval ∆119909119894 or more generally if 120579119894 is defined as the average over theinterval ∆119909119894

The flux 119865119894minus12 must be approximated

119865 = 119906120579 minus 120581

∆119909119888120597119894120579

and this is where truncation errors can enter the solution The method for obtaining 120579 is unspecified and a wide rangeof possibilities exist including centered and upwind interpolation polynomial fits based on the the volume averagedefinitions of quantities and non-linear interpolation such as flux-limiters

Choosing simple centered second-order interpolation and differencing recovers the same ODErsquos resulting from finitedifferencing for the interior of a fluid Differences arise at boundaries where a boundary is not positioned on a regularor smoothly varying grid This method is used to represent the topography using lopped cell see Adcroft et al (1997)[AHM97] Subtle difference also appear in more than one dimension away from boundaries This happens becauseeach direction is discretized independently in the finite difference method while the integrating over finite volumeimplicitly treats all directions simultaneously

211 Spatial discretization of the dynamical equations 59

2112 C grid staggering of variables

The basic algorithm employed for stepping forward the momentum equations is based on retaining non-divergence ofthe flow at all times This is most naturally done if the components of flow are staggered in space in the form of anArakawa C grid (Arakawa and Lamb 1977 [AL77])

Figure 25 shows the components of flow (119906119907119908) staggered in space such that the zonal component falls on theinterface between continuity cells in the zonal direction Similarly for the meridional and vertical directions Thecontinuity cell is synonymous with tracer cells (they are one and the same)

Figure 25 Three dimensional staggering of velocity components This facilitates the natural discretization of thecontinuity and tracer equations

2113 Grid initialization and data

Initialization of grid data is controlled by subroutine INI_GRID which in calls INI_VERTICAL_GRID toinitialize the vertical grid and then either of INI_CARTESIAN_GRID INI_SPHERICAL_POLAR_GRID orINI_CURVILINEAR_GRID to initialize the horizontal grid for cartesian spherical-polar or curvilinear coordinatesrespectively

The reciprocals of all grid quantities are pre-calculated and this is done in subroutine INI_MASKS_ETC which iscalled later by subroutine INITIALISE_FIXED

All grid descriptors are global arrays and stored in common blocks in GRIDh and a generally declared as _RS

2114 Horizontal grid

The model domain is decomposed into tiles and within each tile a quasi-regular grid is used A tile is the ba-sic unit of domain decomposition for parallelization but may be used whether parallelized or not see section[secdomain_decomposition] for more details Although the tiles may be patched together in an unstructured manner(ie irregular or non-tessilating pattern) the interior of tiles is a structured grid of quadrilateral cells The horizon-tal coordinate system is orthogonal curvilinear meaning we can not necessarily treat the two horizontal directions asseparable Instead each cell in the horizontal grid is described by the length of itrsquos sides and itrsquos area

The grid information is quite general and describes any of the available coordinates systems cartesian spherical-polar or curvilinear All that is necessary to distinguish between the coordinate systems is to initialize the grid data(descriptors) appropriately

In the following we refer to the orientation of quantities on the computational grid using geographic terminologysuch as points of the compass This is purely for convenience but should not be confused with the actual geographicorientation of model quantities

Figure 26 Staggering of horizontal grid descriptors (lengths and areas) The grid lines indicate the tracer cell bound-aries and are the reference grid for all panels a) The area of a tracer cell 119860119888 is bordered by the lengths ∆119909119892 and ∆119910119892 b) The area of a vorticity cell 119860120577 is bordered by the lengths ∆119909119888 and ∆119910119888 c) The area of a u cell 119860119908 is bordered bythe lengths ∆119909119907 and ∆119910119891 d) The area of a v cell 119860119904 is bordered by the lengths ∆119909119891 and ∆119910119906

Figure 26 (a) shows the tracer cell (synonymous with the continuity cell) The length of the southern edge ∆119909119892 western edge ∆119910119892 and surface area 119860119888 presented in the vertical are stored in arrays dxG dyG and rA The ldquogrdquo suffixindicates that the lengths are along the defining grid boundaries The ldquocrdquo suffix associates the quantity with the cellcenters The quantities are staggered in space and the indexing is such that dxG(ij) is positioned to the south of rA(ij)and dyG(ij) positioned to the west

Figure 26 (b) shows the vorticity cell The length of the southern edge ∆119909119888 western edge ∆119910119888 and surface area 119860120577 presented in the vertical are stored in arrays dxC dyC and rAz The ldquozrdquo suffix indicates that the lengths are measuredbetween the cell centers and the ldquo120577rdquo suffix associates points with the vorticity points The quantities are staggered inspace and the indexing is such that dxC(ij) is positioned to the north of rAz(ij) and dyC(ij) positioned to the east

Figure 26 (c) shows the ldquourdquo or western (w) cell The length of the southern edge ∆119909119907 eastern edge ∆119910119891 and surfacearea 119860119908 presented in the vertical are stored in arrays dxV dyF and rAw The ldquovrdquo suffix indicates that the length ismeasured between the v-points the ldquofrdquo suffix indicates that the length is measured between the (tracer) cell faces andthe ldquowrdquo suffix associates points with the u-points (w stands for west) The quantities are staggered in space and theindexing is such that dxV(ij) is positioned to the south of rAw(ij) and dyF(ij) positioned to the east

Figure 26 (d) shows the ldquovrdquo or southern (s) cell The length of the northern edge ∆119909119891 western edge ∆119910119906 and surfacearea 119860119904 presented in the vertical are stored in arrays dxF dyU and rAs The ldquourdquo suffix indicates that the length ismeasured between the u-points the ldquofrdquo suffix indicates that the length is measured between the (tracer) cell faces and

the ldquosrdquo suffix associates points with the v-points (s stands for south) The quantities are staggered in space and theindexing is such that dxF(ij) is positioned to the north of rAs(ij) and dyU(ij) positioned to the west

SR INI_CARTESIAN_GRID INI_SPHERICAL_POLAR_GRID INI_CURVILINEAR_GRID

119860119888 119860120577 119860119908 119860119904 rA rAz rAw rAs ( GRIDh )∆119909119892∆119910119892 dxG dyG ( GRIDh )∆119909119888∆119910119888 dxC dyC ( GRIDh )∆119909119891 ∆119910119891 dxF dyF ( GRIDh )∆119909119907∆119910119906 dxV dyU ( GRIDh )

21141 Reciprocals of horizontal grid descriptors

Lengths and areas appear in the denominator of expressions as much as in the numerator For efficiency and portabilitywe pre-calculate the reciprocal of the horizontal grid quantities so that in-line divisions can be avoided

For each grid descriptor (array) there is a reciprocal named using the prefix recip_ This doubles the amount ofstorage in GRIDh but they are all only 2-D descriptors

SR INI_MASKS_ETC

119860minus1119888 119860minus1

120577 119860minus1119908 119860minus1

119904 recip_rA recip_rAz recip_rAw recip_rAs ( GRIDh )

∆119909minus1119892 ∆119910minus1

119892 recip_dxG recip_dyG ( GRIDh )∆119909minus1

119888 ∆119910minus1119888 recip_dxC recip_dyC ( GRIDh )

∆119909minus1119891 ∆119910minus1

119891 recip_dxF recip_dyF ( GRIDh )

∆119909minus1119907 ∆119910minus1

119906 recip_dxV recip_dyU ( GRIDh )

21142 Cartesian coordinates

Cartesian coordinates are selected when the logical flag usingCartesianGrid in namelist PARM04 is set to true Thegrid spacing can be set to uniform via scalars dXspacing and dYspacing in namelist PARM04 or to variable resolutionby the vectors DELX and DELY Units are normally meters Non-dimensional coordinates can be used by interpretingthe gravitational constant as the Rayleigh number

21143 Spherical-polar coordinates

Spherical coordinates are selected when the logical flag usingSphericalPolarGrid in namelist PARM04 is set to trueThe grid spacing can be set to uniform via scalars dXspacing and dYspacing in namelist PARM04 or to variableresolution by the vectors DELX and DELY Units of these namelist variables are alway degrees The horizontal griddescriptors are calculated from these namelist variables have units of meters

21144 Curvilinear coordinates

Curvilinear coordinates are selected when the logical flag usingCurvilinearGrid in namelist PARM04 is set to trueThe grid spacing can not be set via the namelist Instead the grid descriptors are read from data files one for eachdescriptor As for other grids the horizontal grid descriptors have units of meters

2115 Vertical grid

Δrc Δrc

a)a) b)

Figure 27 Two versions of the vertical grid a) The cell centered approach where the interface depths are specifiedand the tracer points centered in between the interfaces b) The interface centered approach where tracer levels arespecified and the w-interfaces are centered in between

As for the horizontal grid we use the suffixes ldquocrdquo and ldquofrdquo to indicates faces and centers Figure 27 (a) shows the defaultvertical grid used by the model ∆119903119891 is the difference in 119903 (vertical coordinate) between the faces (ie ∆119903119891 equiv minus120575119896119903where the minus sign appears due to the convention that the surface layer has index 119896 = 1)

The vertical grid is calculated in subroutine INI_VERTICAL_GRID and specified via the vector delR in namelistPARM04 The units of ldquorrdquo are either meters or Pascals depending on the isomorphism being used which in turn isdependent only on the choice of equation of state

There are alternative namelist vectors delZ and delP which dictate whether z- or p- coordinates are to be used but weintend to phase this out since they are redundant

The reciprocals ∆119903minus1119891 and ∆119903minus1

119888 are pre-calculated (also in subroutine INI_VERTICAL_GRID) All vertical griddescriptors are stored in common blocks in GRIDh

The above grid Figure 27 (a) is known as the cell centered approach because the tracer points are at cell centers thecell centers are mid-way between the cell interfaces This discretization is selected when the thickness of the levelsare provided (delR parameter file data namelist PARM04) An alternative the vertex or interface centered approachis shown in Figure 27 (b) Here the interior interfaces are positioned mid-way between the tracer nodes (no longercell centers) This approach is formally more accurate for evaluation of hydrostatic pressure and vertical advection buthistorically the cell centered approach has been used An alternative form of subroutine INI_VERTICAL_GRID isused to select the interface centered approach This form requires to specify119873119903+1 vertical distances delRc (parameter

file data namelist PARM04 eg ideal_2D_oceinputdata) corresponding to surface to center119873119903minus1 center to centerand center to bottom distances

SR INI_VERTICAL_GRID

∆119903119891 ∆119903119888 drF drC ( GRIDh )∆119903minus1

119891 ∆119903minus1119888 recip_drF recip_drC ( GRIDh )

2116 Topography partially filled cells

Adcroft et al (1997) [AHM97] presented two alternatives to the step-wise finite difference representation of topogra-phy The method is known to the engineering community as intersecting boundary method It involves allowing theboundary to intersect a grid of cells thereby modifying the shape of those cells intersected We suggested allowing thetopography to take on a piece-wise linear representation (shaved cells) or a simpler piecewise constant representation(partial step) Both show dramatic improvements in solution compared to the traditional full step representation thepiece-wise linear being the best However the storage requirements are excessive so the simpler piece-wise constantor partial-step method is all that is currently supported

hwΔrf

hcΔrfΔrf

Figure 28 A schematic of the x-r plane showing the location of the non-dimensional fractions ℎ119888 and ℎ119908 Thephysical thickness of a tracer cell is given by ℎ119888(119894 119895 119896)∆119903119891 (119896) and the physical thickness of the open side is given byℎ119908(119894 119895 119896)∆119903119891 (119896)

Figure 28 shows a schematic of the x-r plane indicating how the thickness of a level is determined at tracer and upoints The physical thickness of a tracer cell is given by ℎ119888(119894 119895 119896)∆119903119891 (119896) and the physical thickness of the openside is given by ℎ119908(119894 119895 119896)∆119903119891 (119896) Three 3-D descriptors ℎ119888 ℎ119908 and ℎ119904 are used to describe the geometry hFacChFacW and hFacS respectively These are calculated in subroutine INI_MASKS_ETC along with there reciprocalsrecip_hFacC recip_hFacW and recip_hFacS

The non-dimensional fractions (or h-facs as we call them) are calculated from the model depth array and then processedto avoid tiny volumes The rule is that if a fraction is less than hFacMin then it is rounded to the nearer of 0 or hFacMinor if the physical thickness is less than hFacMinDr then it is similarly rounded The larger of the two methods is usedwhen there is a conflict By setting hFacMinDr equal to or larger than the thinnest nominal layers min (∆119911119891 ) but

setting hFacMin to some small fraction then the model will only lop thick layers but retain stability based on thethinnest unlopped thickness min (∆119911119891 ℎ119865119886119888119872119894119899119863119903)

SR filelinkINI_MASKS_ETC

ℎ119888 ℎ119908 ℎ119904 hFacC hFacW hFacS ( GRIDh )ℎminus1119888 ℎminus1

119908 ℎminus1119904 recip_hFacC recip_hFacW recip_hFacS ( GRIDh )

212 Continuity and horizontal pressure gradient term

The core algorithm is based on the ldquoC gridrdquo discretization of the continuity equation which can be summarized as

120597119905119906+1

∆119909119888120575119894120597Φ

120597119903

119904

120578 +120598119899ℎ∆119909119888

120575119894Φprime119899ℎ = 119866119906 minus 1

∆119909119888120575119894Φ

primeℎ (278)

120597119905119907 +1

∆119910119888120575119895120597Φ

120597119903

119904

120578 +120598119899ℎ∆119910119888

120575119895Φprime119899ℎ = 119866119907 minus

∆119910119888120575119895Φ

primeℎ (279)

120598119899ℎ

(120597119905119908 +

∆119903119888120575119896Φprime

119899ℎ

)= 120598119899ℎ119866119908 + 119887

119896 minus 1

∆119903119888120575119896Φprime

ℎ (280)

120575119894∆119910119892∆119903119891ℎ119908119906+ 120575119895∆119909119892∆119903119891ℎ119904119907 + 120575119896119964119888119908 = 119964119888120575119896(119875 minus 119864)119903=0 (281)

where the continuity equation has been most naturally discretized by staggering the three components of velocity asshown in Figure 25 The grid lengths ∆119909119888 and ∆119910119888 are the lengths between tracer points (cell centers) The gridlengths ∆119909119892 ∆119910119892 are the grid lengths between cell corners ∆119903119891 and ∆119903119888 are the distance (in units of 119903) betweenlevel interfaces (w-level) and level centers (tracer level) The surface area presented in the vertical is denoted 119964119888 Thefactors ℎ119908 and ℎ119904 are non-dimensional fractions (between 0 and 1) that represent the fraction cell depth that is ldquoopenrdquofor fluid flow

The last equation the discrete continuity equation can be summed in the vertical to yield the free-surface equation

119964119888120597119905120578 + 120575119894sum119896

∆119910119892∆119903119891ℎ119908119906+ 120575119895sum119896

∆119909119892∆119903119891ℎ119904119907 = 119964119888(119875 minus 119864)119903=0 (282)

The source term 119875 minus 119864 on the rhs of continuity accounts for the local addition of volume due to excess precipitationand run-off over evaporation and only enters the top-level of the ocean model

213 Hydrostatic balance

The vertical momentum equation has the hydrostatic or quasi-hydrostatic balance on the right hand side This dis-cretization guarantees that the conversion of potential to kinetic energy as derived from the buoyancy equation exactlymatches the form derived from the pressure gradient terms when forming the kinetic energy equation

In the ocean using z-coordinates the hydrostatic balance terms are discretized

212 Continuity and horizontal pressure gradient term 65

120598119899ℎ120597119905119908 + 119892120588prime119896

∆119911120575119896Φprime

ℎ = (283)

In the atmosphere using p-coordinates hydrostatic balance is discretized

120579prime119896

∆Π120575119896Φprime

ℎ = 0 (284)

where ∆Π is the difference in Exner function between the pressure points The non-hydrostatic equations are notavailable in the atmosphere

The difference in approach between ocean and atmosphere occurs because of the direct use of the ideal gas equationin forming the potential energy conversion term 120572120596 Because of the different representation of hydrostatic balancebetween ocean and atmosphere there is no elegant way to represent both systems using an arbitrary coordinate

The integration for hydrostatic pressure is made in the positive 119903 direction (increasing k-index) For the ocean this isfrom the free-surface down and for the atmosphere this is from the ground up

The calculations are made in the subroutine CALC_PHI_HYD Inside this routine one of other of the atmo-sphericoceanic form is selected based on the string variable buoyancyRelation

214 Flux-form momentum equations

The original finite volume model was based on the Eulerian flux form momentum equations This is the default thoughthe vector invariant form is optionally available (and recommended in some cases)

The ldquoGrsquosrdquo (our colloquial name for all terms on rhs) are broken into the various advective Coriolis horizontaldissipation vertical dissipation and metric forces

119866119906 = 119866119886119889119907119906 +119866119888119900119903

119906 +119866ℎminus119889119894119904119904119906 +119866119907minus119889119894119904119904

119906 +119866119898119890119905119903119894119888119906 +119866119899ℎminus119898119890119905119903119894119888

119906 (285)

119866119907 = 119866119886119889119907119907 +119866119888119900119903

119907 +119866ℎminus119889119894119904119904119907 +119866119907minus119889119894119904119904

119907 +119866119898119890119905119903119894119888119907 +119866119899ℎminus119898119890119905119903119894119888

119907 (286)

119866119908 = 119866119886119889119907119908 +119866119888119900119903

119908 +119866ℎminus119889119894119904119904119908 +119866119907minus119889119894119904119904

119908 +119866119898119890119905119903119894119888119908 +119866119899ℎminus119898119890119905119903119894119888

119908 (287)

In the hydrostatic limit 119866119908 = 0 and 120598119899ℎ = 0 reducing the vertical momentum to hydrostatic balance

These terms are calculated in routines called from subroutine MOM_FLUXFORM and collected into the global arraysgU gV and gW

SR MOM_FLUXFORM

119866119906 gU ( DYNVARSh )119866119907 gV ( DYNVARSh )119866119908 gW ( NH_VARSh )

2141 Advection of momentum

The advective operator is second order accurate in space

119964119908∆119903119891ℎ119908119866119886119889119907119906 = 120575119894119880

119894119906119894 + 120575119895119881

119894119906119895 + 120575119896119882

119894119906119896 (288)

119964119904∆119903119891ℎ119904119866119886119889119907119907 = 120575119894119880

119895119907119894 + 120575119895119881

119895119907119895 + 120575119896119882

119895119907119896 (289)

119964119888∆119903119888119866119886119889119907119908 = 120575119894119880

119896119908119894 + 120575119895119881

119896119908119895 + 120575119896119882

119896119908119896 (290)

and because of the flux form does not contribute to the global budget of linear momentum The quantities 119880 119881 and119882 are volume fluxes defined

119880 = ∆119910119892∆119903119891ℎ119908119906 (291)

119881 = ∆119909119892∆119903119891ℎ119904119907 (292)

119882 = 119964119888119908 (293)

The advection of momentum takes the same form as the advection of tracers but by a translated advective flowConsequently the conservation of second moments derived for tracers later applies to 1199062 and 1199072 and 1199082 so thatadvection of momentum correctly conserves kinetic energy

SR MOM_U_ADV_UU MOM_U_ADV_VU MOM_U_ADV_WU

119906119906 119907119906 119908119906 fZon fMer fVerUkp ( local to MOM_FLUXFORMF )

SR MOM_V_ADV_UV MOM_V_ADV_VV MOM_V_ADV_WV

119906119907 119907119907 119908119907 fZon fMer fVerVkp ( local to MOM_FLUXFORMF )

2142 Coriolis terms

The ldquopure C gridrdquo Coriolis terms (ie in absence of C-D scheme) are discretized

119964119908∆119903119891ℎ119908119866119862119900119903119906 = 119891119964119888∆119903119891ℎ119888119907

119895119894minus 120598119899ℎ119891 prime119964119888∆119903119891ℎ119888119908

119896119894

119964119904∆119903119891ℎ119904119866119862119900119903119907 = minus119891119964119888∆119903119891ℎ119888119906

119894119895 (295)

214 Flux-form momentum equations 67

119964119888∆119903119888119866119862119900119903119908 = 120598119899ℎ119891 prime119964119888∆119903119891ℎ119888119906

119894119896 (296)

where the Coriolis parameters 119891 and 119891 prime are defined

119891 = 2Ω sin120601

119891 prime = 2Ω cos120601

where 120601 is geographic latitude when using spherical geometry otherwise the 120573-plane definition is used

119891 = 119891119900 + 120573119910

119891 prime = 0

This discretization globally conserves kinetic energy It should be noted that despite the use of this discretization informer publications all calculations to date have used the following different discretization

119866119862119900119903119906 = 119891119906119907

119895119894 minus 120598119899ℎ119891prime119906119908

119894119896 (297)

119866119862119900119903119907 = minus119891119907119906119894119895 (298)

119866119862119900119903119908 = 120598119899ℎ119891

prime119908119906

119894119896 (299)

where the subscripts on 119891 and 119891 prime indicate evaluation of the Coriolis parameters at the appropriate points in spaceThe above discretization does not conserve anything especially energy but for historical reasons is the default for thecode A flag controls this discretization set run-time logical useEnergyConservingCoriolis to TRUE which otherwisedefaults to FALSE

SR CD_CODE_SCHEME MOM_U_CORIOLIS MOM_V_CORIOLIS

119866119862119900119903119906 119866119862119900119903

119907 cF ( local to MOM_FLUXFORMF )

2143 Curvature metric terms

The most commonly used coordinate system on the sphere is the geographic system (120582 120601) The curvilinear natureof these coordinates on the sphere lead to some ldquometricrdquo terms in the component momentum equations Under thethin-atmosphere and hydrostatic approximations these terms are discretized

119964119908∆119903119891ℎ119908119866119898119890119905119903119894119888119906 =

119906119894

119886tan120601119964119888∆119903119891ℎ119888119907

119895

119894

(2100)

119964119904∆119903119891ℎ119904119866119898119890119905119903119894119888119907 = minus119906

119894

119886tan120601119964119888∆119903119891ℎ119888119906

119894

119895

(2101)

119866119898119890119905119903119894119888119908 = 0 (2102)

where 119886 is the radius of the planet (sphericity is assumed) or the radial distance of the particle (ie a function ofheight) It is easy to see that this discretization satisfies all the properties of the discrete Coriolis terms since the metricfactor 119906

119886 tan120601 can be viewed as a modification of the vertical Coriolis parameter 119891 rarr 119891 + 119906119886 tan120601

However as for the Coriolis terms a non-energy conserving form has exclusively been used to date

119866119898119890119905119903119894119888119906 =

119906119907119894119895

119886tan120601

119866119898119890119905119903119894119888119907 =

119906119894119895119906119894119895

119886tan120601

where tan120601 is evaluated at the 119906 and 119907 points respectively

SR MOM_U_METRIC_SPHERE MOM_V_METRIC_SPHERE

119866119898119890119905119903119894119888119906 119866119898119890119905119903119894119888

119907 mT ( local to MOM_FLUXFORMF )

2144 Non-hydrostatic metric terms

For the non-hydrostatic equations dropping the thin-atmosphere approximation re-introduces metric terms involving119908 which are required to conserve angular momentum

119964119908∆119903119891ℎ119908119866119898119890119905119903119894119888119906 = minus119906

119894119908119896

119886119964119888∆119903119891ℎ119888

119894

(2103)

119964119904∆119903119891ℎ119904119866119898119890119905119903119894119888119907 = minus119907

119895119908119896

119886119964119888∆119903119891ℎ119888

119895

(2104)

119964119888∆119903119888119866119898119890119905119903119894119888119908 =

1199061198942

+ 1199071198952

119886119964119888∆119903119891ℎ119888

119896

(2105)

Because we are always consistent even if consistently wrong we have in the past used a different discretization inthe model which is

119866119898119890119905119903119894119888119906 = minus119906

119886119908119894119896

119866119898119890119905119903119894119888119907 = minus119907

119886119908119895119896

119866119898119890119905119903119894119888119908 =

119886(119906119894119896

2+ 119907119895119896

SR MOM_U_METRIC_NH MOM_V_METRIC_NH

119866119898119890119905119903119894119888119906 119866119898119890119905119903119894119888

2145 Lateral dissipation

Historically we have represented the SGS Reynolds stresses as simply down gradient momentum fluxes ignoringconstraints on the stress tensor such as symmetry

119964119908∆119903119891ℎ119908119866ℎminus119889119894119904119904119906 = 120575119894∆119910119891∆119903119891ℎ11988812059111 + 120575119895∆119909119907∆119903119891ℎ12057712059112 (2106)

119964119904∆119903119891ℎ119904119866ℎminus119889119894119904119904119907 = 120575119894∆119910119906∆119903119891ℎ12057712059121 + 120575119895∆119909119891∆119903119891ℎ11988812059122 (2107)

The lateral viscous stresses are discretized

12059111 = 119860ℎ11988811Δ(120601)1

∆119909119891120575119894119906minus119860411988811Δ2(120601)

∆119909119891120575119894nabla2119906 (2108)

12059112 = 119860ℎ11988812Δ(120601)1

∆119910119906120575119895119906minus119860411988812Δ2(120601)

∆119910119906120575119895nabla2119906 (2109)

12059121 = 119860ℎ11988821Δ(120601)1

∆119909119907120575119894119907 minus119860411988821Δ2(120601)

∆119909119907120575119894nabla2119907 (2110)

12059122 = 119860ℎ11988822Δ(120601)1

∆119910119891120575119895119907 minus119860411988822Δ2(120601)

∆119910119891120575119895nabla2119907 (2111)

where the non-dimensional factors 119888119897119898Δ119899(120601) 119897119898 119899 isin 1 2 define the ldquocosinerdquo scaling with latitude which canbe applied in various ad-hoc ways For instance 11988811Δ = 11988821Δ = (cos120601)32 11988812Δ = 11988822Δ = 1 would represent theanisotropic cosine scaling typically used on the ldquolat-lonrdquo grid for Laplacian viscosity

It should be noted that despite the ad-hoc nature of the scaling some scaling must be done since on a lat-lon grid theconverging meridians make it very unlikely that a stable viscosity parameter exists across the entire model domain

The Laplacian viscosity coefficient 119860ℎ (viscAh) has units of 1198982119904minus1 The bi-harmonic viscosity coefficient 1198604

(viscA4) has units of 1198984119904minus1

SR MOM_U_XVISCFLUX MOM_U_YVISCFLUX

12059111 12059112 vF v4F ( local to MOM_FLUXFORMF )

SR MOM_V_XVISCFLUX MOM_V_YVISCFLUX

Two types of lateral boundary condition exist for the lateral viscous terms no-slip and free-slip

The free-slip condition is most convenient to code since it is equivalent to zero-stress on boundaries Simple maskingof the stress components sets them to zero The fractional open stress is properly handled using the lopped cells

The no-slip condition defines the normal gradient of a tangential flow such that the flow is zero on the boundary Ratherthan modify the stresses by using complicated functions of the masks and ldquoghostrdquo points (see Adcroft and Marshall(1998) [AM98]) we add the boundary stresses as an additional source term in cells next to solid boundaries This hasthe advantage of being able to cope with ldquothin wallsrdquo and also makes the interior stress calculation (code) independentof the boundary conditions The ldquobodyrdquo force takes the form

119866119904119894119889119890minus119889119903119886119892119906 =

∆119911119891(1 minus ℎ120577)

∆119909119907∆119910119906

119895 (119860ℎ11988812Δ(120601)119906minus119860411988812Δ2(120601)nabla2119906

)(2112)

119866119904119894119889119890minus119889119903119886119892119907 =

∆119911119891(1 minus ℎ120577)

∆119910119906∆119909119907

119894 (119860ℎ11988821Δ(120601)119907 minus119860411988821Δ2(120601)nabla2119907

)(2113)

In fact the above discretization is not quite complete because it assumes that the bathymetry at velocity points isdeeper than at neighboring vorticity points eg 1 minus ℎ119908 lt 1 minus ℎ120577

SR MOM_U_SIDEDRAG MOM_V_SIDEDRAG

119866119904119894119889119890minus119889119903119886119892119906 119866119904119894119889119890minus119889119903119886119892

119907 vF ( local to MOM_FLUXFORMF )

2146 Vertical dissipation

Vertical viscosity terms are discretized with only partial adherence to the variable grid lengths introduced by the finitevolume formulation This reduces the formal accuracy of these terms to just first order but only next to boundariesexactly where other terms appear such as linear and quadratic bottom drag

119866119907minus119889119894119904119904119906 =

∆119903119891ℎ11990812057511989612059113 (2114)

119866119907minus119889119894119904119904119907 =

∆119903119891ℎ11990412057511989612059123 (2115)

119866119907minus119889119894119904119904119908 = 120598119899ℎ

∆119903119891ℎ11988912057511989612059133 (2116)

represents the general discrete form of the vertical dissipation terms

In the interior the vertical stresses are discretized

12059113 = 1198601199071

∆119903119888120575119896119906

12059123 = 1198601199071

∆119903119888120575119896119907

12059133 = 1198601199071

∆119903119891120575119896119908

It should be noted that in the non-hydrostatic form the stress tensor is even less consistent than for the hydrostatic (seeWajsowicz (1993) [Waj93]) It is well known how to do this properly (see Griffies and Hallberg (2000) [GH00]) andis on the list of to-dorsquos

SR MOM_U_RVISCFLUX MOM_V_RVISCFLUX

12059113 fVrUp fVrDw ( local to MOM_FLUXFORMF )12059123 fVrUp fVrDw ( local to MOM_FLUXFORMF )

As for the lateral viscous terms the free-slip condition is equivalent to simply setting the stress to zero on boundariesThe no-slip condition is implemented as an additional term acting on top of the interior and free-slip stresses Bottomdrag represents additional friction in addition to that imposed by the no-slip condition at the bottom The drag is castas a stress expressed as a linear or quadratic function of the mean flow in the layer above the topography

120591 119887119900119905119905119900119898minus11988911990311988611989213 =

(2119860119907

∆119903119888+ 119903119887 + 119862119889

radic2119870119864

119894

)119906 (2117)

120591 119887119900119905119905119900119898minus11988911990311988611989223 =

(2119860119907

∆119903119888+ 119903119887 + 119862119889

radic2119870119864

119895

)119907 (2118)

where these terms are only evaluated immediately above topography 119903119887 (bottomDragLinear) has units of 119898119904minus1 and atypical value of the order 00002 119898119904minus1 119862119889 (bottomDragQuadratic) is dimensionless with typical values in the range0001ndash0003

SR MOM_U_BOTTOMDRAG MOM_V_BOTTOMDRAG

120591 119887119900119905119905119900119898minus11988911990311988611989213 ∆119903119891 120591

119887119900119905119905119900119898minus11988911990311988611989223 ∆119903119891 vF ( local to MOM_FLUXFORMF )

2147 Derivation of discrete energy conservation

These discrete equations conserve kinetic plus potential energy using the following definitions

119870119864 =1

(1199062

119894+ 1199072

119895+ 120598119899ℎ1199082

119896)

(2119)

2148 Mom Diagnostics

------------------------------------------------------------------------lt-Name-gt|Levs|lt-parsing code-gt|lt-- Units --gt|lt- Tile (max=80c)------------------------------------------------------------------------VISCAHZ | 15 |SZ MR |m^2s |Harmonic Visc Coefficient (m2s)rarr˓(Zeta Pt)VISCA4Z | 15 |SZ MR |m^4s |Biharmonic Visc Coefficient (m4s)rarr˓(Zeta Pt)VISCAHD | 15 |SM MR |m^2s |Harmonic Viscosity Coefficient (m2s)rarr˓(Div Pt)VISCA4D | 15 |SM MR |m^4s |Biharmonic Viscosity Coefficient (m4rarr˓s) (Div Pt)VAHZMAX | 15 |SZ MR |m^2s |CFL-MAX Harm Visc Coefficient (m2s)rarr˓(Zeta Pt)VA4ZMAX | 15 |SZ MR |m^4s |CFL-MAX Biharm Visc Coefficient (m4rarr˓s) (Zeta Pt)VAHDMAX | 15 |SM MR |m^2s |CFL-MAX Harm Visc Coefficient (m2s)rarr˓(Div Pt)VA4DMAX | 15 |SM MR |m^4s |CFL-MAX Biharm Visc Coefficient (m4rarr˓s) (Div Pt)

(continues on next page)

(continued from previous page)

VAHZMIN | 15 |SZ MR |m^2s |RE-MIN Harm Visc Coefficient (m2s)rarr˓(Zeta Pt)VA4ZMIN | 15 |SZ MR |m^4s |RE-MIN Biharm Visc Coefficient (m4s)rarr˓(Zeta Pt)VAHDMIN | 15 |SM MR |m^2s |RE-MIN Harm Visc Coefficient (m2s)rarr˓(Div Pt)VA4DMIN | 15 |SM MR |m^4s |RE-MIN Biharm Visc Coefficient (m4s)rarr˓(Div Pt)VAHZLTH | 15 |SZ MR |m^2s |Leith Harm Visc Coefficient (m2s)rarr˓(Zeta Pt)VA4ZLTH | 15 |SZ MR |m^4s |Leith Biharm Visc Coefficient (m4s)rarr˓(Zeta Pt)VAHDLTH | 15 |SM MR |m^2s |Leith Harm Visc Coefficient (m2s)rarr˓(Div Pt)VA4DLTH | 15 |SM MR |m^4s |Leith Biharm Visc Coefficient (m4s)rarr˓(Div Pt)VAHZLTHD| 15 |SZ MR |m^2s |LeithD Harm Visc Coefficient (m2s)rarr˓(Zeta Pt)VA4ZLTHD| 15 |SZ MR |m^4s |LeithD Biharm Visc Coefficient (m4s)rarr˓(Zeta Pt)VAHDLTHD| 15 |SM MR |m^2s |LeithD Harm Visc Coefficient (m2s)rarr˓(Div Pt)VA4DLTHD| 15 |SM MR |m^4s |LeithD Biharm Visc Coefficient (m4s)rarr˓(Div Pt)VAHZSMAG| 15 |SZ MR |m^2s |Smagorinsky Harm Visc Coefficient (m2rarr˓s) (Zeta Pt)VA4ZSMAG| 15 |SZ MR |m^4s |Smagorinsky Biharm Visc Coeff (m4s)rarr˓(Zeta Pt)VAHDSMAG| 15 |SM MR |m^2s |Smagorinsky Harm Visc Coefficient (m2rarr˓s) (Div Pt)VA4DSMAG| 15 |SM MR |m^4s |Smagorinsky Biharm Visc Coeff (m4s)rarr˓(Div Pt)momKE | 15 |SM MR |m^2s^2 |Kinetic Energy (in momentum Eq)momHDiv | 15 |SM MR |s^-1 |Horizontal Divergence (in momentum Eqrarr˓)momVort3| 15 |SZ MR |s^-1 |3rd component (vertical) of VorticityStrain | 15 |SZ MR |s^-1 |Horizontal Strain of Horizontalrarr˓VelocitiesTension | 15 |SM MR |s^-1 |Horizontal Tension of Horizontalrarr˓VelocitiesUBotDrag| 15 |UU 129MR |ms^2 |U momentum tendency from Bottom DragVBotDrag| 15 |VV 128MR |ms^2 |V momentum tendency from Bottom DragUSidDrag| 15 |UU 131MR |ms^2 |U momentum tendency from Side DragVSidDrag| 15 |VV 130MR |ms^2 |V momentum tendency from Side DragUm_Diss | 15 |UU 133MR |ms^2 |U momentum tendency from DissipationVm_Diss | 15 |VV 132MR |ms^2 |V momentum tendency from DissipationUm_Advec| 15 |UU 135MR |ms^2 |U momentum tendency from Advectionrarr˓termsVm_Advec| 15 |VV 134MR |ms^2 |V momentum tendency from Advectionrarr˓termsUm_Cori | 15 |UU 137MR |ms^2 |U momentum tendency from Coriolis termVm_Cori | 15 |VV 136MR |ms^2 |V momentum tendency from Coriolis termUm_Ext | 15 |UU 137MR |ms^2 |U momentum tendency from externalrarr˓forcingVm_Ext | 15 |VV 138MR |ms^2 |V momentum tendency from externalrarr˓forcingUm_AdvZ3| 15 |UU 141MR |ms^2 |U momentum tendency from Vorticityrarr˓Advection (continues on next page)

Vm_AdvZ3| 15 |VV 140MR |ms^2 |V momentum tendency from Vorticityrarr˓AdvectionUm_AdvRe| 15 |UU 143MR |ms^2 |U momentum tendency from verticalrarr˓Advection (Explicit part)Vm_AdvRe| 15 |VV 142MR |ms^2 |V momentum tendency from verticalrarr˓Advection (Explicit part)ADVx_Um | 15 |UM 145MR |m^4s^2 |Zonal Advective Flux of Urarr˓momentumADVy_Um | 15 |VZ 144MR |m^4s^2 |Meridional Advective Flux of Urarr˓momentumADVrE_Um| 15 |WU LR |m^4s^2 |Vertical Advective Flux of Urarr˓momentum (Explicit part)ADVx_Vm | 15 |UZ 148MR |m^4s^2 |Zonal Advective Flux of Vrarr˓momentumADVy_Vm | 15 |VM 147MR |m^4s^2 |Meridional Advective Flux of Vrarr˓momentumADVrE_Vm| 15 |WV LR |m^4s^2 |Vertical Advective Flux of Vrarr˓momentum (Explicit part)VISCx_Um| 15 |UM 151MR |m^4s^2 |Zonal Viscous Flux of U momentumVISCy_Um| 15 |VZ 150MR |m^4s^2 |Meridional Viscous Flux of U momentumVISrE_Um| 15 |WU LR |m^4s^2 |Vertical Viscous Flux of U momentumrarr˓(Explicit part)VISrI_Um| 15 |WU LR |m^4s^2 |Vertical Viscous Flux of U momentumrarr˓(Implicit part)VISCx_Vm| 15 |UZ 155MR |m^4s^2 |Zonal Viscous Flux of V momentumVISCy_Vm| 15 |VM 154MR |m^4s^2 |Meridional Viscous Flux of V momentumVISrE_Vm| 15 |WV LR |m^4s^2 |Vertical Viscous Flux of V momentumrarr˓(Explicit part)VISrI_Vm| 15 |WV LR |m^4s^2 |Vertical Viscous Flux of V momentumrarr˓(Implicit part)

215 Vector invariant momentum equations

The finite volume method lends itself to describing the continuity and tracer equations in curvilinear coordinate sys-tems However in curvilinear coordinates many new metric terms appear in the momentum equations (written inLagrangian or flux-form) making generalization far from elegant Fortunately an alternative form of the equationsthe vector invariant equations are exactly that invariant under coordinate transformations so that they can be applieduniformly in any orthogonal curvilinear coordinate system such as spherical coordinates boundary following or theconformal spherical cube system

The non-hydrostatic vector invariant equations read

120597119905 + (2Ω + 120577) and minus 119887119903 + nabla119861 = nabla middot (2120)

which describe motions in any orthogonal curvilinear coordinate system Here 119861 is the Bernoulli function and 120577 =nabla and is the vorticity vector We can take advantage of the elegance of these equations when discretizing them anduse the discrete definitions of the grad curl and divergence operators to satisfy constraints We can also considerthe analogy to forming derived equations such as the vorticity equation and examine how the discretization can beadjusted to give suitable vorticity advection among other things

The underlying algorithm is the same as for the flux form equations All that has changed is the contents of the ldquoGrsquosrdquoFor the time-being only the hydrostatic terms have been coded but we will indicate the points where non-hydrostaticcontributions will enter

119866119906 = 119866119891119907119906 +1198661205773119907

119906 +1198661205772119908119906 +119866120597119909119861

119906 +119866120597119911120591119909

119906 +119866ℎminus119889119894119904119904119894119901119906 +119866119907minus119889119894119904119904119894119901

119906 (2121)

119866119907 = 119866119891119906119907 +1198661205773119906

119907 +1198661205771119908119907 +119866120597119910119861

119907 +119866120597119911120591119910

119907 +119866ℎminus119889119894119904119904119894119901119907 +119866119907minus119889119894119904119904119894119901

119907 (2122)

119866119908 = 119866119891119906119908 +1198661205771119907

119908 +1198661205772119906119908 +119866120597119911119861

119908 +119866ℎminus119889119894119904119904119894119901119908 +119866119907minus119889119894119904119904119894119901

119908 (2123)

SR MOM_VECINV

2151 Relative vorticity

The vertical component of relative vorticity is explicitly calculated and use in the discretization The particular formis crucial for numerical stability alternative definitions break the conservation properties of the discrete equations

Relative vorticity is defined

1205773 =Γ

119860120577=

119964120577(120575119894∆119910119888119907 minus 120575119895∆119909119888119906) (2124)

where 119964120577 is the area of the vorticity cell presented in the vertical and Γ is the circulation about that cell

SR MOM_CALC_RELVORT3

1205773 vort3 ( local to MOM_VECINVF )

2152 Kinetic energy

The kinetic energy denoted 119870119864 is defined

119870119864 =1

2(1199062

119894+ 1199072

119895+ 120598119899ℎ1199082

119896) (2125)

SR MOM_CALC_KE

119870119864 KE ( local to MOM_VECINVF )

215 Vector invariant momentum equations 75

2153 Coriolis terms

The potential enstrophy conserving form of the linear Coriolis terms are written

119866119891119907119906 =

∆119909119888

119891

ℎ120577

119895

∆119909119892ℎ119904119907119895119894

(2126)

119866119891119906119907 = minus 1

∆119910119888

119891

ℎ120577

119894

∆119910119892ℎ119908119906119894119895

(2127)

Here the Coriolis parameter 119891 is defined at vorticity (corner) points

The potential enstrophy conserving form of the non-linear Coriolis terms are written

1198661205773119907119906 =

∆119909119888

1205773ℎ120577

119895

∆119909119892ℎ119904119907119895119894

(2128)

1198661205773119906119907 = minus 1

∆119910119888

1205773ℎ120577

119894

∆119910119892ℎ119908119906119894119895

(2129)

The Coriolis terms can also be evaluated together and expressed in terms of absolute vorticity 119891 + 1205773 The potentialenstrophy conserving form using the absolute vorticity is written

119866119891119907119906 +1198661205773119907

119906 =1

∆119909119888

119891 + 1205773ℎ120577

119895

∆119909119892ℎ119904119907119895119894

(2130)

119866119891119906119907 +1198661205773119906

119907 = minus 1

∆119910119888

119891 + 1205773ℎ120577

119894

∆119910119892ℎ119908119906119894119895

(2131)

The distinction between using absolute vorticity or relative vorticity is useful when constructing higher order advectionschemes monotone advection of relative vorticity behaves differently to monotone advection of absolute vorticityCurrently the choice of relativeabsolute vorticity centeredupwindhigh order advection is available only throughcommented subroutine calls

SR MOM_VI_CORIOLIS MOM_VI_U_CORIOLIS MOM_VI_V_CORIOLIS

119866119891119907119906 1198661205773119907

119906 uCf ( local to MOM_VECINVF )119866119891119906

119907 1198661205773119906119907 vCf ( local to MOM_VECINVF )

2154 Shear terms

The shear terms (1205772119908 and 1205771119908) are are discretized to guarantee that no spurious generation of kinetic energy is possiblethe horizontal gradient of Bernoulli function has to be consistent with the vertical advection of shear

1198661205772119908119906 =

119964119908∆119903119891ℎ119908119964119888119908

119894(120575119896119906minus 120598119899ℎ120575119895119908)

119896

(2132)

1198661205771119908119907 =

119964119904∆119903119891ℎ119904119964119888119908

119894(120575119896119906minus 120598119899ℎ120575119895119908)

119896

(2133)

SR MOM_VI_U_VERTSHEAR MOM_VI_V_VERTSHEAR

1198661205772119908119906 uCf ( local to MOM_VECINVF )

1198661205771119908119907 vCf ( local to MOM_VECINVF )

2155 Gradient of Bernoulli function

119866120597119909119861119906 =

∆119909119888120575119894(120593

prime +119870119864) (2134)

119866120597119910119861119907 =

∆119909119910120575119895(120593

prime +119870119864) (2135)

SR MOM_VI_U_GRAD_KE MOM_VI_V_GRAD_KE

2156 Horizontal divergence

The horizontal divergence a complimentary quantity to relative vorticity is used in parameterizing the Reynoldsstresses and is discretized

119863 =1

119964119888ℎ119888(120575119894∆119910119892ℎ119908119906+ 120575119895∆119909119892ℎ119904119907) (2136)

SR MOM_CALC_KE

119863 hDiv ( local to MOM_VECINVF )

2157 Horizontal dissipation

The following discretization of horizontal dissipation conserves potential vorticity (thickness weighted relative vortic-ity) and divergence and dissipates energy enstrophy and divergence squared

119866ℎminus119889119894119904119904119894119901119906 =

∆119909119888120575119894(119860119863119863 minus1198601198634119863

) minus 1

∆119910119906ℎ119908120575119895ℎ120577(119860120577120577 minus1198601205774120577

) (2137)

119866ℎminus119889119894119904119904119894119901119907 =

∆119909119907ℎ119904120575119894ℎ120577(119860120577120577 minus119860120577120577

∆119910119888120575119895(119860119863119863 minus1198601198634119863

) (2138)

119863 =1

119964119888ℎ119888(120575119894∆119910119892ℎ119908nabla2119906+ 120575119895∆119909119892ℎ119904nabla2119907)

120577 =1

119964120577(120575119894∆119910119888nabla2119907 minus 120575119895∆119909119888nabla2119906)

SR MOM_VI_HDISSIP

119866ℎminus119889119894119904119904119894119901119906 uDissip ( local to MOM_VI_HDISSIPF )

119866ℎminus119889119894119904119904119894119901119907 vDissip ( local to MOM_VI_HDISSIPF )

Currently this is exactly the same code as the flux form equations

119866119907minus119889119894119904119904119906 =

∆119903119891ℎ11990812057511989612059113 (2139)

119866119907minus119889119894119904119904119907 =

∆119903119891ℎ11990412057511989612059123 (2140)

12059113 = 1198601199071

∆119903119888120575119896119906

12059123 = 1198601199071

∆119903119888120575119896119907

12059113 12059123 vrf ( local to MOM_VECINVF )

216 Tracer equations

The basic discretization used for the tracer equations is the second order piece-wise constant finite volume form of theforced advection-diffusion equations There are many alternatives to second order method for advection and alternativeparameterizations for the sub-grid scale processes The Gent-McWilliams eddy parameterization KPP mixing schemeand PV flux parameterization are all dealt with in separate sections The basic discretization of the advection-diffusionpart of the tracer equations and the various advection schemes will be described here

2161 Time-stepping of tracers ABII

The default advection scheme is the centered second order method which requires a second order or quasi-secondorder time-stepping scheme to be stable Historically this has been the quasi-second order Adams-Bashforth method(ABII) and applied to all terms For an arbitrary tracer 120591 the forced advection-diffusion equation reads

120597119905120591 +119866120591119886119889119907 = 119866120591

119889119894119891119891 +119866120591119891119900119903119888 (2141)

where 119866120591119886119889119907 119866120591

119889119894119891119891 and 119866120591119891119900119903119888 are the tendencies due to advection diffusion and forcing respectively namely

119866120591119886119889119907 = 120597119909119906120591 + 120597119910119907120591 + 120597119903119908120591 minus 120591nabla middot v (2142)

119866120591119889119894119891119891 = nabla middotKnabla120591 (2143)

and the forcing can be some arbitrary function of state time and space

The term 120591nabla middot v is required to retain local conservation in conjunction with the linear implicit free-surface It onlyaffects the surface layer since the flow is non-divergent everywhere else This term is therefore referred to as thesurface correction term Global conservation is not possible using the flux-form (as here) and a linearized free-surface(Griffies and Hallberg (2000) [GH00] Campin et al (2004) [CAHM04])

The continuity equation can be recovered by setting 119866119889119894119891119891 = 119866119891119900119903119888 = 0 and 120591 = 1

The driver routine that calls the routines to calculate tendencies are CALC_GT and CALC_GS for temperature andsalt (moisture) respectively These in turn call a generic advection diffusion routine GAD_CALC_RHS that is calledwith the flow field and relevant tracer as arguments and returns the collective tendency due to advection and diffusionForcing is add subsequently in CALC_GT or CALC_GS to the same tendency array

SR GAD_CALC_RHS

120591 tau ( argument )119866(119899) gTracer ( argument )119865119903 fVerT ( argument )

The space and time discretization are treated separately (method of lines) Tendencies are calculated at time levels 119899and 119899minus 1 and extrapolated to 119899+ 12 using the Adams-Bashforth method

119866(119899+12) = (3

2+ 120598)119866(119899) minus (

2+ 120598)119866(119899minus1) (2144)

where 119866(119899) = 119866120591119886119889119907 +119866120591

119889119894119891119891 +119866120591119904119903119888 at time step 119899 The tendency at 119899minus 1 is not re-calculated but rather the tendency

at 119899 is stored in a global array for later re-use

SR ADAMS_BASHFORTH2

119866(119899+12) gTracer ( argument on exit )119866(119899) gTracer ( argument on entry )119866(119899minus1) gTrNm1 ( argument )120598 ABeps ( PARAMSh )

The tracers are stepped forward in time using the extrapolated tendency

120591 (119899+1) = 120591 (119899) + ∆119905119866(119899+12) (2145)

216 Tracer equations 79

SR TIMESTEP_TRACER

120591 (119899+1) gTracer ( argument on exit )120591 (119899) tracer ( argument on entry )119866(119899+12) gTracer ( argument )∆119905 deltaTtracer ( PARAMSh )

Strictly speaking the ABII scheme should be applied only to the advection terms However this scheme is only usedin conjunction with the standard second third and fourth order advection schemes Selection of any other advectionscheme disables Adams-Bashforth for tracers so that explicit diffusion and forcing use the forward method

217 Linear advection schemes

The advection schemes known as centered second order centered fourth order first order upwind and upwind biasedthird order are known as linear advection schemes because the coefficient for interpolation of the advected tracer arelinear and a function only of the flow not the tracer field it self We discuss these first since they are most commonlyused in the field and most familiar

2171 Centered second order advection-diffusion

The basic discretization centered second order is the default It is designed to be consistent with the continuityequation to facilitate conservation properties analogous to the continuum However centered second order advectionis notoriously noisy and must be used in conjunction with some finite amount of diffusion to produce a sensiblesolution

The advection operator is discretized

119964119888∆119903119891ℎ119888119866120591119886119889119907 = 120575119894119865119909 + 120575119895119865119910 + 120575119896119865119903 (2146)

where the area integrated fluxes are given by

119865119909 = 119880120591 119894

119865119910 = 119881 120591 119895

119865119903 = 119882120591119896

The quantities 119880 119881 and 119882 are volume fluxes defined as

119880 = ∆119910119892∆119903119891ℎ119908119906

119881 = ∆119909119892∆119903119891ℎ119904119907

119882 = 119964119888119908

For non-divergent flow this discretization can be shown to conserve the tracer both locally and globally and to globallyconserve tracer variance 1205912 The proof is given in Adcroft (1995) [Adc95] and Adcroft et al (1997) [AHM97]

SR GAD_C2_ADV_X

119865119909 uT ( argument )119880 uTrans ( argument )120591 tracer ( argument )

SR GAD_C2_ADV_Y

119865119910 vT ( argument )119881 vTrans ( argument )120591 tracer ( argument )

SR GAD_C2_ADV_R

119865119903 wT ( argument )119882 rTrans ( argument )120591 tracer ( argument )

2172 Third order upwind bias advection

Upwind biased third order advection offers a relatively good compromise between accuracy and smoothness It is nota ldquopositiverdquo scheme meaning false extrema are permitted but the amplitude of such are significantly reduced over thecentered second order method

The third order upwind fluxes are discretized

119865119909 = 119880120591 minus 1

6120575119894119894120591

119894

2|119880 |120575119894

6120575119894119894120591

119865119910 = 119881 120591 minus 1

6120575119894119894120591

119895

2|119881 |120575119895

6120575119895119895120591

119865119903 = 119882120591 minus 1

6120575119894119894120591

119896

2|119882 |120575119896

6120575119896119896120591

At boundaries 120575120591 is set to zero allowing 120575119899119899 to be evaluated We are currently examine the accuracy of this boundarycondition and the effect on the solution

SR GAD_U3_ADV_X

SR GAD_U3_ADV_Y

SR GAD_U3_ADV_R

119865119903 wT ( argument )119882 rTrans ( argument )

217 Linear advection schemes 81

120591 tracer ( argument )

2173 Centered fourth order advection

Centered fourth order advection is formally the most accurate scheme we have implemented and can be used togreat effect in high resolution simulations where dynamical scales are well resolved However the scheme is noisylike the centered second order method and so must be used with some finite amount of diffusion Bi-harmonic isrecommended since it is more scale selective and less likely to diffuse away the well resolved gradient the fourth orderscheme worked so hard to create

The centered fourth order fluxes are discretized

119865119909 = 119880120591 minus 1

6120575119894119894120591

119894

119865119910 = 119881 120591 minus 1

6120575119894119894120591

119895

119865119903 = 119882120591 minus 1

6120575119894119894120591

119896

As for the third order scheme the best discretization near boundaries is under investigation but currently 120575119894120591 = 0 on aboundary

SR GAD_C4_ADV_X

SR GAD_C4_ADV_Y

SR GAD_C4_ADV_R

2174 First order upwind advection

Although the upwind scheme is the underlying scheme for the robust or non-linear methods given in Section 218 wehavenrsquot actually implemented this method for general use It would be very diffusive and it is unlikely that it couldever produce more useful results than the positive higher order schemes

Upwind bias is introduced into many schemes using the abs function and it allows the first order upwind flux to bewritten

119865119909 = 119880120591 119894 minus 1

2|119880 |120575119894120591

119865119910 = 119881 120591 119895 minus 1

2|119881 |120575119895120591

119865119903 = 119882120591119896 minus 1

2|119882 |120575119896120591

If for some reason the above method is desired the second order flux limiter scheme described in Section 2181reduces to the above scheme if the limiter is set to zero

218 Non-linear advection schemes

Non-linear advection schemes invoke non-linear interpolation and are widely used in computational fluid dynamics(non-linear does not refer to the non-linearity of the advection operator) The flux limited advection schemes belongto the class of finite volume methods which neatly ties into the spatial discretization of the model

When employing the flux limited schemes first order upwind or direct-space-time method the time-stepping isswitched to forward in time

2181 Second order flux limiters

The second order flux limiter method can be cast in several ways but is generally expressed in terms of other fluxapproximations For example in terms of a first order upwind flux and second order Lax-Wendroff flux the limitedflux is given as

119865 = 1198651 + 120595(119903)119865119871119882 (2147)

where 120595(119903) is the limiter function

1198651 = 119906120591 119894 minus 1

2|119906|120575119894120591

is the upwind flux

119865119871119882 = 1198651 +|119906|2

(1 minus 119888)120575119894120591

is the Lax-Wendroff flux and 119888 = 119906Δ119905Δ119909 is the Courant (CFL) number

The limiter function 120595(119903) takes the slope ratio

119903 =120591119894minus1 minus 120591119894minus2

120591119894 minus 120591119894minus1forall 119906 gt 0

119903 =120591119894+1 minus 120591119894120591119894 minus 120591119894minus1

forall 119906 lt 0

as its argument There are many choices of limiter function but we only provide the Superbee limiter (Roe 1995[Roe85])

120595(119903) = max[0min[1 2119903]min[2 119903]]

SR GAD_FLUXLIMIT_ADV_X

218 Non-linear advection schemes 83

SR GAD_FLUXLIMIT_ADV_Y

SR GAD_FLUXLIMIT_ADV_R

2182 Third order direct space time

The direct-space-time method deals with space and time discretization together (other methods that treat space andtime separately are known collectively as the ldquoMethod of Linesrdquo) The Lax-Wendroff scheme falls into this categoryit adds sufficient diffusion to a second order flux that the forward-in-time method is stable The upwind biased thirdorder DST scheme is

119865 = 119906 (120591119894minus1 + 1198890(120591119894 minus 120591119894minus1) + 1198891(120591119894minus1 minus 120591119894minus2)) forall 119906 gt 0

119865 = 119906 (120591119894 minus 1198890(120591119894 minus 120591119894minus1) minus 1198891(120591119894+1 minus 120591119894)) forall 119906 lt 0(2148)

1198891 =1

6(2 minus |119888|)(1 minus |119888|)

1198892 =1

6(1 minus |119888|)(1 + |119888|)

The coefficients 1198890 and 1198891 approach 13 and 16 respectively as the Courant number 119888 vanishes In this limit theconventional third order upwind method is recovered For finite Courant number the deviations from the linear methodare analogous to the diffusion added to centered second order advection in the Lax-Wendroff scheme

The DST3 method described above must be used in a forward-in-time manner and is stable for 0 le |119888| le 1 Althoughthe scheme appears to be forward-in-time it is in fact third order in time and the accuracy increases with the Courantnumber For low Courant number DST3 produces very similar results (indistinguishable in Figure 210) to the linearthird order method but for large Courant number where the linear upwind third order method is unstable the schemeis extremely accurate (Figure 211) with only minor overshoots

SR GAD_DST3_ADV_X

SR GAD_DST3_ADV_Y

SR GAD_DST3_ADV_R

2183 Third order direct space time with flux limiting

The overshoots in the DST3 method can be controlled with a flux limiter The limited flux is written

119865 =1

2(119906+ |119906|)

(120591119894minus1 + 120595(119903+)(120591119894 minus 120591119894minus1)

2(119906minus |119906|)

(120591119894minus1 + 120595(119903minus)(120591119894 minus 120591119894minus1)

)(2149)

119903+ =120591119894minus1 minus 120591119894minus2

120591119894 minus 120591119894minus1

119903minus =120591119894+1 minus 120591119894120591119894 minus 120591119894minus1

and the limiter is the Sweby limiter

120595(119903) = max[0min[min(1 1198890 + 1198891119903]1 minus 119888

119888119903]]

SR GAD_DST3FL_ADV_X

SR GAD_DST3FL_ADV_Y

SR GAD_DST3FL_ADV_R

119865119903 wT ( argument )

119882 rTrans ( argument )120591 tracer ( argument )

2184 Multi-dimensional advection

In many of the aforementioned advection schemes the behavior in multiple dimensions is not necessarily as good asthe one dimensional behavior For instance a shape preserving monotonic scheme in one dimension can have severeshape distortion in two dimensions if the two components of horizontal fluxes are treated independently There is alarge body of literature on the subject dealing with this problem and among the fixes are operator and flux splittingmethods corner flux methods and more We have adopted a variant on the standard splitting methods that allows theflux calculations to be implemented as if in one dimension

120591119899+13 = 120591119899 minus ∆119905

∆119909120575119894119865

119909(120591119899) + 1205911198991

∆119909120575119894119906

)120591119899+23 = 120591119899+13 minus ∆119905

∆119910120575119895119865

119910(120591119899+13) + 1205911198991

∆119910120575119894119907

)120591119899+33 = 120591119899+23 minus ∆119905

∆119903120575119896119865

119909(120591119899+23) + 1205911198991

∆119903120575119894119908

) (2150)

In order to incorporate this method into the general model algorithm we compute the effective tendency rather thanupdate the tracer so that other terms such as diffusion are using the 119899 time-level and not the updated 119899+33 quantities

119866119899+12119886119889119907 =

∆119905(120591119899+33 minus 120591119899)

So that the over all time-stepping looks likes

120591119899+1 = 120591119899 + ∆119905(119866

119899+12119886119889119907 +119866119889119894119891119891 (120591119899) +119866119899

119891119900119903119888119894119899119892

SR GAD_ADVECTION

119866119899+12119886119889119907 gTracer ( argument )

119865119909 119865119910 119865119903 aF ( local )119880 uTrans ( local )119881 vTrans ( local )119882 rTrans ( local )

A schematic of multi-dimension time stepping for the cube sphere configuration is show in Figure 29

219 Comparison of advection schemes

Table 22 shows a summary of the different advection schemes available in MITgcm ldquoABrdquo stands for Adams-Bashforth and ldquoDSTrdquo for direct space time The code corresponds to the number used to select the correspondingadvection scheme in the parameter file (eg tempAdvScheme=3 in file data selects the 3rd order upwind advectionscheme for temperature)

0 20 40 60 80 100 120 140 1600

5 6npass = 1

Calc amp Update X dirCalc amp Update Y dir X dir (Overlap) Y dir (Overlap)

0 20 40 60 80 100 120 140 1600

5 6npass = 2

0 20 40 60 80 100 120 140 1600

5 6npass = 3

Figure 29 Multi-dimensional advection time-stepping with cubed-sphere topology

219 Comparison of advection schemes 87

Table 22 MITgcm Advection Schemesuse

use multi stencilAdvection Scheme Code AB -dim (1-D) comments1st order upwind 1 no yes 3 linear 120591 non-linear vcentered 2nd order 2 yes no 3 linear3rd order upwind 3 yes no 5 linear 120591centered 4th order 4 yes no 5 linear2nd order DST (Lax-Wendroff) 20 no yes 3 linear 120591 non-linear v3rd order DST 30 no yes 5 linear 120591 non-linear v2nd order-moment Prather 80 no yes2nd order flux limiters 77 no yes 5 non-linear3rd order DST flux limiter 33 no yes 5 non-linear2nd order-moment Prather wlimiter 81 no yespiecewise parabolic wldquonullrdquo limiter 40 no yespiecewise parabolic wldquomonordquo limiter 41 no yespiecewise quartic wldquonullrdquo limiter 50 no yespiecewise quartic wldquomonordquo limiter 51 no yespiecewise quartic wldquowenordquo limiter 52 no yes7th order one-step method w 7 no yesmonotonicity preserving limiter

Shown in Figure 210 and Figure 211 is a 1-D comparison of advection schemes Here we advect both a smooth hilland a hill with a more abrupt shock Figure 210 shown the result for a weak flow (low Courant number) whereasFigure 211 shows the result for a stronger flow (high Courant number)

Figure 212 Figure 213 and Figure 214 show solutions to a simple diagonal advection problem using a selection ofschemes for low moderate and high Courant numbers respectively The top row shows the linear schemes integratedwith the Adams-Bashforth method Theses schemes are clearly unstable for the high Courant number and weaklyunstable for the moderate Courant number The presence of false extrema is very apparent for all Courant numbersThe middle row shows solutions obtained with the unlimited but multi-dimensional schemes These solutions alsoexhibit false extrema though the pattern now shows symmetry due to the multi-dimensional scheme Also the schemesare stable at high Courant number where the linear schemes werenrsquot The bottom row (left and middle) shows thelimited schemes and most obvious is the absence of false extrema The accuracy and stability of the unlimited non-linear schemes is retained at high Courant number but at low Courant number the tendency is to lose amplitude insharp peaks due to diffusion The one dimensional tests shown in Figure 210 and Figure 211 show this phenomenon

Finally the bottom left and right panels use the same advection scheme but the right does not use the multi-dimensionalmethod At low Courant number this appears to not matter but for moderate Courant number severe distortion of thefeature is apparent Moreover the stability of the multi-dimensional scheme is determined by the maximum Courantnumber applied of each dimension while the stability of the method of lines is determined by the sum Hence in thehigh Courant number plot the scheme is unstable

With many advection schemes implemented in the code two questions arise ldquoWhich scheme is bestrdquo and ldquoWhy donrsquotyou just offer the best advection schemerdquo Unfortunately no one advection scheme is ldquothe bestrdquo for all particularapplications and for new applications it is often a matter of trial to determine which is most suitable Here are someguidelines but these are not the rule

bull If you have a coarsely resolved model using a positive or upwind biased scheme will introduce significantdiffusion to the solution and using a centered higher order scheme will introduce more noise In this casesimplest may be best

0 01 02 03 04 05 06 07 08 09 1

a) Analytic solutionupwindminus1 DSTminus3 upwindminus3 upwindminus2

0 01 02 03 04 05 06 07 08 09 1

b) Analytic solutionLaxminusWendroff 4minusDST centeredminus2 centeredminus4 4minusFV

0 01 02 03 04 05 06 07 08 09 1

c) Analytic solutionminmod Superbee van Leer (MC) van Leer (alb)

0 01 02 03 04 05 06 07 08 09 1

d) Analytic solution3minusDST Sw micro=1 3minusDST Sw micro(c) 4minusDST Sw micro(c)

Figure 210 Comparison of 1-D advection schemes Courant number is 005 with 60 points and solutions are shownfor T=1 (one complete period) a) Shows the upwind biased schemes first order upwind DST3 third order upwindand second order upwind b) Shows the centered schemes Lax-Wendroff DST4 centered second order centeredfourth order and finite volume fourth order c) Shows the second order flux limiters minmod Superbee MC limiterand the van Leer limiter d) Shows the DST3 method with flux limiters due to Sweby with 120583 = 1 120583 = 119888(1 minus 119888) anda fourth order DST method with Sweby limiter 120583 = 119888(1 minus 119888)

0 01 02 03 04 05 06 07 08 09 1

a) Analytic solutionupwindminus1 DSTminus3

0 01 02 03 04 05 06 07 08 09 1

b) Analytic solutionLaxminusWendroff 4minusDST

0 01 02 03 04 05 06 07 08 09 1

Figure 211 Comparison of 1-D advection schemes Courant number is 089 with 60 points and solutions are shownfor T=1 (one complete period) a) Shows the upwind biased schemes first order upwind and DST3 Third orderupwind and second order upwind are unstable at this Courant number b) Shows the centered schemes Lax-WendroffDST4 Centered second order centered fourth order and finite volume fourth order are unstable at this Courant numberc) Shows the second order flux limiters minmod Superbee MC limiter and the van Leer limiter d) Shows the DST3method with flux limiters due to Sweby with 120583 = 1 120583 = 119888(1 minus 119888) and a fourth order DST method with Swebylimiter 120583 = 119888(1 minus 119888)

02 04 06 08

2nd order centered

02 04 06 08

3rd order upwind

02 04 06 08

4th order centered

02 04 06 08

LaxminusWendroff

02 04 06 08

3minusDST

02 04 06 08

4minusDST

02 04 06 08

Superbee flux limiter

02 04 06 08

3minusDST Sweby micro=micro(c)

02 04 06 08

Superbee (no multiminusdim)

Figure 212 Comparison of advection schemes in two dimensions diagonal advection of a resolved Gaussian featureCourant number is 001 with 30 times 30 points and solutions are shown for T=12 White lines indicate zero crossing(ie the presence of false minima) The left column shows the second order schemes top) centered second order withAdams-Bashforth middle) Lax-Wendroff and bottom) Superbee flux limited The middle column shows the thirdorder schemes top) upwind biased third order with Adams-Bashforth middle) third order direct space-time methodand bottom) the same with flux limiting The top right panel shows the centered fourth order scheme with Adams-Bashforth and right middle panel shows a fourth order variant on the DST method Bottom right panel shows theSuperbee flux limiter (second order) applied independently in each direction (method of lines)

02 04 06 08

2nd order centered

02 04 06 08

3rd order upwind

02 04 06 08

4th order centered

02 04 06 08

LaxminusWendroff

02 04 06 08

3minusDST

02 04 06 08

4minusDST

02 04 06 08

2nd order centered

02 04 06 08

3rd order upwind

02 04 06 08

4th order centered

02 04 06 08

LaxminusWendroff

02 04 06 08

3minusDST

02 04 06 08

4minusDST

02 04 06 08

Figure 214 Comparison of advection schemes in two dimensions diagonal advection of a resolved Gaussian featureCourant number is 047 with 30 times 30 points and solutions are shown for T=12 White lines indicate zero crossingsand initial maximum values (ie the presence of false extrema) The left column shows the second order schemes top)centered second order with Adams-Bashforth middle) Lax-Wendroff and bottom) Superbee flux limited The middlecolumn shows the third order schemes top) upwind biased third order with Adams-Bashforth middle) third orderdirect space-time method and bottom) the same with flux limiting The top right panel shows the centered fourth orderscheme with Adams-Bashforth and right middle panel shows a fourth order variant on the DST method Bottom rightpanel shows the Superbee flux limiter (second order) applied independently in each direction (method of lines)

bull If you have a high resolution model using a higher order scheme will give a more accurate solution but scale-selective diffusion might need to be employed The flux limited methods offer similar accuracy in this regime

bull If your solution has shocks or propagating fronts then a flux limited scheme is almost essential

bull If your time-step is limited by advection the multi-dimensional non-linear schemes have the most stability (upto Courant number 1)

bull If you need to know how much diffusiondissipation has occurred you will have a lot of trouble figuring it outwith a non-linear method

bull The presence of false extrema is non-physical and this alone is the strongest argument for using a positivescheme

220 Shapiro Filter

The Shapiro filter (Shapiro 1970) [Sha70] is a high order horizontal filter that efficiently remove small scale grid noisewithout affecting the physical structures of a field It is applied at the end of the time step on both velocity and tracerfields

Three different space operators are considered here (S1S2 and S4) They differ essentially by the sequence of deriva-tive in both X and Y directions Consequently they show different damping response function specially in the diagonaldirections X+Y and X-Y

Space derivatives can be computed in the real space taking into account the grid spacing Alternatively a purecomputational filter can be defined using pure numerical differences and ignoring grid spacing This later form isstable whatever the grid is and therefore specially useful for highly anisotropic grid such as spherical coordinate gridA damping time-scale parameter 120591119904ℎ119886119901 defines the strength of the filter damping

The three computational filter operators are

S1c [1 minus 12∆119905

120591119904ℎ119886119901(

4120575119894119894)

119899 + (1

4120575119895119895)

119899]

S2c [1 minus ∆119905

120591119904ℎ1198861199011

8(120575119894119894 + 120575119895119895)119899]

S4c [1 minus ∆119905

120591119904ℎ119886119901(1

4120575119894119894)

119899][1 minus ∆119905

120591119904ℎ119886119901(1

4120575119895119895)

119899]

In addition the S2 operator can easily be extended to a physical space filter

S2g [1 minus ∆119905

120591119904ℎ1198861199011198712119904ℎ119886119901

8nabla2119899]

with the Laplacian operator nabla2and a length scale parameter 119871119904ℎ119886119901 The stability of this S2g filter requires 119871119904ℎ119886119901 lt

Min(119866119897119900119887119886119897)(∆119909∆119910)

2201 SHAP Diagnostics

221 Nonlinear Viscosities for Large Eddy Simulation

In Large Eddy Simulations (LES) a turbulent closure needs to be provided that accounts for the effects of subgridscalemotions on the large scale With sufficiently powerful computers we could resolve the entire flow down to themolecular viscosity scales (119871120584 asymp 1cm) Current computation allows perhaps four decades to be resolved so thelargest problem computationally feasible would be about 10m Most oceanographic problems are much larger inscale so some form of LES is required where only the largest scales of motion are resolved and the subgridscaleeffects on the large-scale are parameterized

To formalize this process we can introduce a filter over the subgridscale L 119906120572 rarr 119906120572 and L 119887 rarr 119887 This filterhas some intrinsic length and time scales and we assume that the flow at that scale can be characterized with a singlevelocity scale (119881 ) and vertical buoyancy gradient (1198732) The filtered equations of motion in a local Mercator projectionabout the gridpoint in question (see Appendix for notation and details of approximation) are

119863

119863119905minus 119907 sin 120579

Ro sin 1205790+119872119877119900

120597120587

120597119909= minus

(119863

119863119905minus 119863

119863119905

nabla2

Re(2151)

119863119907

119863119905minus sin 120579

Ro sin 1205790+119872119877119900

120597120587

120597119910= minus

(119863119907

119863119905minus 119863119907

119863119905

nabla2119907

Re(2152)

119863119908

119863119905+

120597120587120597119911 minus 119887

Fr21205822= minus

(119863119908

119863119905minus 119863119908

119863119905

nabla2119908

119863

119863119905+ 119908 = minus

(119863119887

119863119905minus 119863

119863119905

nabla2119887

1205832

(120597

120597119909+120597119907

120597119910

)+120597119908

120597119911= 0 (2153)

Tildes denote multiplication by cos 120579 cos 1205790 to account for converging meridians

The ocean is usually turbulent and an operational definition of turbulence is that the terms in parentheses (the rsquoeddyrsquoterms) on the right of (2151) - (2153)) are of comparable magnitude to the terms on the left-hand side The termsproportional to the inverse of instead are many orders of magnitude smaller than all of the other terms in virtuallyevery oceanic application

2211 Eddy Viscosity

A turbulent closure provides an approximation to the rsquoeddyrsquo terms on the right of the preceding equations The simplestform of LES is just to increase the viscosity and diffusivity until the viscous and diffusive scales are resolved That iswe approximate (2151) - (2153)

(119863

119863119905minus 119863

119863119905

)asymp nabla2

Reℎ+

12059721205971199112

Re119907(2154)

(119863119907

119863119905minus 119863119907

119863119905

)asymp nabla2

ℎ119907

Reℎ+

12059721199071205971199112

Re119907(2155)

221 Nonlinear Viscosities for Large Eddy Simulation 95

(119863119908

119863119905minus 119863119908

119863119905

)asymp nabla2

ℎ119908

Reℎ+

12059721199081205971199112

Re119907(2156)

(119863119887

119863119905minus 119863

119863119905

)asymp nabla2

ℎ119887

Pr Reℎ+

12059721198871205971199112

Pr Re119907

22111 Reynolds-Number Limited Eddy Viscosity

One way of ensuring that the gridscale is sufficiently viscous (ie resolved) is to choose the eddy viscosity 119860ℎ so thatthe gridscale horizontal Reynolds number based on this eddy viscosity Reℎ is O(1) That is if the gridscale is to beviscous then the viscosity should be chosen to make the viscous terms as large as the advective ones Bryan et al(1975) [BMP75] notes that a computational mode is squelched by using Reℎ lt2

MITgcm users can select horizontal eddy viscosities based on Reℎ using two methods 1) The user may estimate thevelocity scale expected from the calculation and grid spacing and set viscAh to satisfy Reℎ lt 2 2) The user mayuse viscAhReMax which ensures that the viscosity is always chosen so that Reℎ lt viscAhReMax This last optionshould be used with caution however since it effectively implies that viscous terms are fixed in magnitude relative toadvective terms While it may be a useful method for specifying a minimum viscosity with little effort tests Bryan etal (1975) [BMP75] have shown that setting viscAhReMax =2 often tends to increase the viscosity substantially overother more rsquophysicalrsquo parameterizations below especially in regions where gradients of velocity are small (and thusturbulence may be weak) so perhaps a more liberal value should be used eg viscAhReMax =10

While it is certainly necessary that viscosity be active at the gridscale the wavelength where dissipation of energy orenstrophy occurs is not necessarily 119871 = 119860ℎ119880 In fact it is by ensuring that either the dissipation of energy in a 3-dturbulent cascade (Smagorinsky) or dissipation of enstrophy in a 2-d turbulent cascade (Leith) is resolved that theseparameterizations derive their physical meaning

22112 Vertical Eddy Viscosities

Vertical eddy viscosities are often chosen in a more subjective way as model stability is not usually as sensitive tovertical viscosity Usually the rsquoobservedrsquo value from finescale measurements is used (eg viscArasymp 1 times 10minus41198982119904)However Smagorinsky (1993) [Sma93] notes that the Smagorinsky parameterization of isotropic turbulence impliesa value of the vertical viscosity as well as the horizontal viscosity (see below)

22113 Smagorinsky Viscosity

Some suggest (see Smagorinsky 1963 [Sma63] Smagorinsky 1993 [Sma93]) choosing a viscosity that depends on theresolved motions Thus the overall viscous operator has a nonlinear dependence on velocity Smagorinsky chose hisform of viscosity by considering Kolmogorovrsquos ideas about the energy spectrum of 3-d isotropic turbulence

Kolmogorov supposed that energy is injected into the flow at large scales (small 119896) and is rsquocascadedrsquo or transferredconservatively by nonlinear processes to smaller and smaller scales until it is dissipated near the viscous scale Bysetting the energy flux through a particular wavenumber 119896 120598 to be a constant in 119896 there is only one combinationof viscosity and energy flux that has the units of length the Kolmogorov wavelength It is 119871120598(120584) prop 120587120598minus1412058434

(the 120587 stems from conversion from wavenumber to wavelength) To ensure that this viscous scale is resolved in anumerical model the gridscale should be decreased until 119871120598(120584) gt 119871 (so-called Direct Numerical Simulation orDNS) Alternatively an eddy viscosity can be used and the corresponding Kolmogorov length can be made larger thanthe gridscale 119871120598(119860ℎ) prop 120587120598minus14119860

34ℎ (for Large Eddy Simulation or LES)

There are two methods of ensuring that the Kolmogorov length is resolved in MITgcm 1) The user can estimatethe flux of energy through spectral space for a given simulation and adjust grid spacing or viscAh to ensure that

119871120598(119860ℎ) gt 119871 2) The user may use the approach of Smagorinsky with viscC2Smag which estimates the energy flux atevery grid point and adjusts the viscosity accordingly

Smagorinsky formed the energy equation from the momentum equations by dotting them with velocity There aresome complications when using the hydrostatic approximation as described by Smagorinsky (1993) [Sma93] Thepositive definite energy dissipation by horizontal viscosity in a hydrostatic flow is 1205841198632 where D is the deformationrate at the viscous scale According to Kolmogorovrsquos theory this should be a good approximation to the energy fluxat any wavenumber 120598 asymp 1205841198632 Kolmogorov and Smagorinsky noted that using an eddy viscosity that exceeds themolecular value 120584 should ensure that the energy flux through viscous scale set by the eddy viscosity is the same asit would have been had we resolved all the way to the true viscous scale That is 120598 asymp 119860ℎ119878119898119886119892119863

2 If we use this

approximation to estimate the Kolmogorov viscous length then

119871120598(119860ℎ119878119898119886119892) prop 120587120598minus1411986034ℎ119878119898119886119892 asymp 120587(119860ℎ119878119898119886119892119863

2)minus14119860

34ℎ119878119898119886119892 = 120587119860

12ℎ119878119898119886119892119863

minus12 (2157)

To make 119871120598(119860ℎ119878119898119886119892) scale with the gridscale then

119860ℎ119878119898119886119892 =

(viscC2Smag

120587

1198712|119863| (2158)

Where the deformation rate appropriate for hydrostatic flows with shallow-water scaling is

|119863| =

radic(120597

120597119909minus 120597119907

120597119910

(120597

120597119910+120597119907

120597119909

(2159)

The coefficient viscC2Smag is what an MITgcm user sets and it replaces the proportionality in the Kolmogorov lengthwith an equality Others (Griffies and Hallberg 2000 [GH00]) suggest values of viscC2Smag from 22 to 4 for oceanicproblems Smagorinsky (1993) [Sma93] shows that values from 02 to 09 have been used in atmospheric modeling

Smagorinsky (1993) [Sma93] shows that a corresponding vertical viscosity should be used

119860119907119878119898119886119892 =

(viscC2Smag

120587

1198672

radic(120597

120597119911

(120597119907

120597119911

(2160)

This vertical viscosity is currently not implemented in MITgcm

22114 Leith Viscosity

Leith (1968 1996) [Lei68] [Lei96] notes that 2-d turbulence is quite different from 3-d In two-dimensional turbu-lence energy cascades to larger scales so there is no concern about resolving the scales of energy dissipation Insteadanother quantity enstrophy (which is the vertical component of vorticity squared) is conserved in 2-d turbulence andit cascades to smaller scales where it is dissipated

Following a similar argument to that above about energy flux the enstrophy flux is estimated to be equal to thepositive-definite gridscale dissipation rate of enstrophy 120578 asymp 119860ℎ119871119890119894119905ℎ|nabla1205963|2 By dimensional analysis the enstrophy-dissipation scale is 119871120578(119860ℎ119871119890119894119905ℎ) prop 120587119860

12ℎ119871119890119894119905ℎ120578

minus16 Thus the Leith-estimated length scale of enstrophy-dissipationand the resulting eddy viscosity are

119871120578(119860ℎ119871119890119894119905ℎ) prop 12058711986012ℎ119871119890119894119905ℎ120578

minus16 = 12058711986013ℎ119871119890119894119905ℎ|nabla1205963|minus13 (2161)

119860ℎ119871119890119894119905ℎ =

(viscC2Leith

120587

1198713|nabla1205963| (2162)

|nabla1205963| equiv

radic[120597

120597119909

(120597119907

120597119909minus 120597

120597119910

[120597

120597119910

(120597119907

120597119909minus 120597

120597119910

)]2(2163)

22115 Modified Leith Viscosity

The argument above for the Leith viscosity parameterization uses concepts from purely 2-dimensional turbulencewhere the horizontal flow field is assumed to be non-divergent However oceanic flows are only quasi-two dimen-sional While the barotropic flow or the flow within isopycnal layers may behave nearly as two-dimensional turbu-lence there is a possibility that these flows will be divergent In a high-resolution numerical model these flows maybe substantially divergent near the grid scale and in fact numerical instabilities exist which are only horizontallydivergent and have little vertical vorticity This causes a difficulty with the Leith viscosity which can only respond tobuildup of vorticity at the grid scale

MITgcm offers two options for dealing with this problem 1) The Smagorinsky viscosity can be used instead ofLeith or in conjunction with Leith ndash a purely divergent flow does cause an increase in Smagorinsky viscosity 2) TheviscC2LeithD parameter can be set This is a damping specifically targeting purely divergent instabilities near thegridscale The combined viscosity has the form

119860ℎ119871119890119894119905ℎ = 1198713

radic(viscC2Leith

120587

|nabla1205963|2 +

(viscC2LeithD

120587

|nablanabla middot ℎ|2 (2164)

|nablanabla middot ℎ| equiv

radic[120597

120597119909

(120597

120597119909+120597119907

120597119910

[120597

120597119910

(120597

120597119909+120597119907

120597119910

)]2(2165)

Whether there is any physical rationale for this correction is unclear but the numerical consequences are good Thedivergence in flows with the grid scale larger or comparable to the Rossby radius is typically much smaller than thevorticity so this adjustment only rarely adjusts the viscosity if viscC2LeithD = viscC2Leith However the rare regionswhere this viscosity acts are often the locations for the largest vales of vertical velocity in the domain Since the CFLcondition on vertical velocity is often what sets the maximum timestep this viscosity may substantially increasethe allowable timestep without severely compromising the verity of the simulation Tests have shown that in somecalculations a timestep three times larger was allowed when viscC2LeithD = viscC2Leith

22116 CourantndashFreidrichsndashLewy Constraint on Viscosity

Whatever viscosities are used in the model the choice is constrained by gridscale and timestep by theCourantndashFreidrichsndashLewy (CFL) constraint on stability

119860ℎ lt1198712

4∆119905

1198604 le 1198714

32∆119905

The viscosities may be automatically limited to be no greater than these values in MITgcm by specifying viscAhGrid-Max lt 1 and viscA4GridMax lt 1 Similarly-scaled minimum values of viscosities are provided by viscAhGridMinand viscA4GridMin which if used should be set to values ≪ 1 119871 is roughly the gridscale (see below)

Following Griffies and Hallberg (2000) [GH00] we note that there is a factor of ∆11990928 difference between theharmonic and biharmonic viscosities Thus whenever a non-dimensional harmonic coefficient is used in the MITgcm(eg viscAhGridMax lt 1) the biharmonic equivalent is scaled so that the same non-dimensional value can be used(eg viscA4GridMax lt 1)

22117 Biharmonic Viscosity

Holland (1978) [Hol78] suggested that eddy viscosities ought to be focused on the dynamics at the grid scale as largermotions would be rsquoresolvedrsquo To enhance the scale selectivity of the viscous operator he suggested a biharmonic eddyviscosity instead of a harmonic (or Laplacian) viscosity

(119863

119863119905minus 119863

119863119905

)asymp minusnabla4

12059721205971199112

Re119907(2166)

(119863119907

119863119905minus 119863119907

119863119905

)asymp minusnabla4

ℎ119907

12059721199071205971199112

Re119907

(119863119908

119863119905minus 119863119908

119863119905

)asymp minusnabla4

ℎ119908

12059721199081205971199112

Re119907

(119863119887

119863119905minus 119863

119863119905

)asymp minusnabla4

ℎ119887

Pr Re4+

12059721198871205971199112

Pr Re119907

Griffies and Hallberg (2000) [GH00] propose that if one scales the biharmonic viscosity by stability considerationsthen the biharmonic viscous terms will be similarly active to harmonic viscous terms at the gridscale of the model butmuch less active on larger scale motions Similarly a biharmonic diffusivity can be used for less diffusive flows

In practice biharmonic viscosity and diffusivity allow a less viscous yet numerically stable simulation than harmonicviscosity and diffusivity However there is no physical rationale for such operators being of leading order and moreboundary conditions must be specified than for the harmonic operators If one considers the approximations of (2154)- (2157) and (2166) - (2167) to be terms in the Taylor series expansions of the eddy terms as functions of the large-scale gradient then one can argue that both harmonic and biharmonic terms would occur in the series and the onlyquestion is the choice of coefficients Using biharmonic viscosity alone implies that one zeros the first non-vanishingterm in the Taylor series which is unsupported by any fluid theory or observation

Nonetheless MITgcm supports a plethora of biharmonic viscosities and diffusivities which are controlled with pa-rameters named similarly to the harmonic viscosities and diffusivities with the substitution h rarr 4 in the MITgcmparameter name MITgcm also supports biharmonic Leith and Smagorinsky viscosities

1198604119878119898119886119892 =

(viscC4Smag

120587

)21198714

8|119863| (2167)

1198604119871119890119894119905ℎ =1198715

radic(viscC4Leith

120587

|nabla1205963|2 +

(viscC4LeithD

120587

|nablanabla middot uℎ|2 (2168)

However it should be noted that unlike the harmonic forms the biharmonic scaling does not easily relate to whetherenergy-dissipation or enstrophy-dissipation scales are resolved If similar arguments are used to estimate these scalesand scale them to the gridscale the resulting biharmonic viscosities should be

1198604119878119898119886119892 =

(viscC4Smag

120587

1198715|nabla2uℎ| (2169)

1198604119871119890119894119905ℎ = 1198716

radic(viscC4Leith

120587

|nabla21205963|2 +

(viscC4LeithD

120587

|nabla2nabla middot uℎ|2 (2170)

Thus the biharmonic scaling suggested by Griffies and Hallberg (2000) [GH00] implies

|119863| prop 119871|nabla2uℎ||nabla1205963| prop 119871|nabla21205963|

It is not at all clear that these assumptions ought to hold Only the Griffies and Hallberg (2000) [GH00] forms arecurrently implemented in MITgcm

22118 Selection of Length Scale

Above the length scale of the grid has been denoted 119871 However in strongly anisotropic grids 119871119909 and 119871119910 will bequite different in some locations In that case the CFL condition suggests that the minimum of 119871119909 and 119871119910 be used Onthe other hand other viscosities which involve whether a particular wavelength is rsquoresolvedrsquo might be better suited touse the maximum of 119871119909 and 119871119910 Currently MITgcm uses useAreaViscLength to select between two options If falsethe geometric mean of 1198712

119909 and 1198712119910 is used for all viscosities which is closer to the minimum and occurs naturally in

the CFL constraint If useAreaViscLength is true then the square root of the area of the grid cell is used

2212 Mercator Nondimensional Equations

The rotating incompressible Boussinesq equations of motion (Gill 1982) [Gil82] on a sphere can be written inMercator projection about a latitude 1205790 and geopotential height 119911 = 119903 minus 1199030 The nondimensional form of theseequations is

Ro119863

119863119905minus 119907 sin 120579

sin 1205790+119872119877119900

120597120587

120597119909+120582Fr2119872119877119900 cos 120579

120583 sin 1205790119908 = minusFr2119872119877119900119908

119903119867+

Rox middot nabla2u

Re(2171)

Ro119863119907

119863119905+ sin 120579

sin 1205790+119872119877119900

120597120587

120597119910= minus120583Ro tan 120579(2 + 1199072)

119903119871minus Fr2119872119877119900119907119908

119903119867+

Roy middot nabla2u

Re(2172)

Fr21205822119863119908

119863119905minus 119887+

120597120587

120597119911minus 120582 cot 1205790

119872119877119900=1205821205832(2 + 1199072)

119872119877119900(119903119871)+

Fr21205822z middot nabla2u

Re(2173)

119863119887

119863119905+ 119908 =

nabla2119887

1205832

(120597

120597119909+120597119907

120597119910

)+120597119908

120597119911= 0 (2174)

120583 equiv cos 1205790cos 120579

=119906

119881 120583 119907 =

119907

119881 120583

1198910 equiv 2Ω sin 1205790119863

119863119905equiv 1205832

(120597

120597119909+ 119907

120597

120597119910

Fr2MRo

Ro119908120597

120597119911

119909 equiv 119903

119871120593 cos 1205790 119910 equiv 119903

119871

int 120579

1205790

cos 1205790 d120579prime

cos 120579prime 119911 equiv 120582

119903 minus 1199030119871

119905 = 119905119871

119881 119887 = 119887

119881 1198910119872119877119900

120582

120587 = 120587119881 1198910119871119872119877119900 119908 = 119908119881Fr2120582119872119877119900

Ro equiv 119881

1198910119871 119872119877119900 equiv max[1Ro]

Fr equiv 119881

119873120582119871 Re equiv 119881 119871

120584 Pr equiv 120584

120581Dimensional variables are denoted by an asterisk where necessary If we filter over a grid scale typical for oceanmodels

1m lt 119871 lt 100km00001 lt 120582 lt 10001ms lt 119881 lt 1 ms1198910 lt 00001 s -1

001 s -1 lt 119873 lt 00001 s -1

these equations are very well approximated by

Ro119863

119863119905minus 119907 sin 120579

sin 1205790+119872119877119900

120597120587

120597119909= minus120582Fr2119872119877119900 cos 120579

120583 sin 1205790119908 +

Ronabla2

Re(2175)

Ro119863119907

119863119905+ sin 120579

sin 1205790+119872119877119900

120597120587

120597119910=

Ronabla2119907

Re(2176)

Fr21205822119863119908

119863119905minus 119887+

120597120587

120597119911=120582 cot 1205790

119872119877119900+

Fr21205822nabla2119908

Re(2177)

119863119887

119863119905+ 119908 =

nabla2119887

Pr Re(2178)

1205832

(120597

120597119909+120597119907

120597119910

)+120597119908

120597119911= 0 (2179)

nabla2 asymp(1205972

1205971199092+

1205972

1205971199102+

1205972

12058221205971199112

)Neglecting the non-frictional terms on the right-hand side is usually called the rsquotraditionalrsquo approximation It is appro-priate with either large aspect ratio or far from the tropics This approximation is used here as it does not affect theform of the eddy stresses which is the main topic The frictional terms are preserved in this approximate form for latercomparison with eddy stresses

CHAPTER 3

Getting Started with MITgcm

This chapter is divided into two main parts The first part which is covered in sections Section 31 through Section36 contains information about how to download build and run the MITgcm The second part covered in Section 4contains a set of step-by-step tutorials for running specific pre-configured atmospheric and oceanic experiments

We believe the best way to familiarize yourself with the model is to run the case study examples provided in theMITgcm repository Information is also provided here on how to customize the code when you are ready to tryimplementing the configuration you have in mind The code and algorithm are described more fully in Section 2 andSection 6 and chapters thereafter

31 Where to find information

There is a web-archived support mailing list for the model that you can email at MITgcm-supportmitgcmorg onceyou have subscribed

To sign up (subscribe) for the mailing list (highly recommended) click here

To browse through the support archive click here

32 Obtaining the code

The MITgcm code and documentation are under continuous development and we generally recommend that onedownloads the latest version of the code You will need to decide if you want to work in a ldquogit-awarerdquo environment(Method 1) or with a one-time ldquostagnantrdquo download (Method 2) We generally recommend method 1 as it is moreflexible and allows your version of the code to be regularly updated as MITgcm developers check in bug fixes and newfeatures However this typically requires at minimum a rudimentary understanding of git in order to make it worthonersquos while

Periodically we release an official checkpoint (or ldquotagrdquo) We recommend one download the latest code unless thereare reasons for obtaining a specific checkpoint (eg duplicating older results collaborating with someone using anolder release etc)

321 Method 1

This section describes how to download git-aware copies of the repository In a terminal window cd to the directorywhere you want your code to reside Type

git clone httpsgithubcomMITgcmMITgcmgit

This will download the latest available code If you now want to revert this code to a specific checkpoint release firstcd into the MITgcm directory you just downloaded then type git checkout checkpointXXX where XXX isthe checkpoint version

Alternatively if you prefer to use ssh keys (say for example you have a firewall which wonrsquot allow a https download)type

git clone gitgithubcomMITgcmMITgcmgit

You will need a GitHub account for this and will have to generate a ssh key though your GitHub account user settings

The fully git-aware download is over several hundred MB which is considerable if one has limited internet downloadspeed In comparison the one-time download zip file (Method 2 below) is order 100MB However one can obtaina truncated yet still git-aware copy of the current code by adding the option --depth=1 to the git clone commandabove all files will be present but it will not include the full git history However the repository can be updated goingforward

322 Method 2

This section describes how to do a one-time download of the MITgcm NOT git-aware In a terminal window cd tothe directory where you want your code to reside To obtain the current code type

wget httpsgithubcomMITgcmMITgcmarchivemasterzip

For specific checkpoint release XXX instead type

wget httpsgithubcomMITgcmMITgcmarchivecheckpointXXXzip

33 Updating the code

There are several different approaches one can use to obtain updates to the MITgcm which is best for you depends abit on how you intend to use the MITgcm and your knowledge of git (andor willingness to learn) Below we outlinethree suggested update pathways

1 Fresh Download of the MITgcm

This approach is the most simple and virtually foolproof Whether you downloaded the code from a static zip file(Method 2) or used the git clone command (Method 1) create a new directory and repeat this procedure to download acurrent copy of the MITgcm Say for example you are starting a new research project this would be a great time to grabthe most recent code repository and keep this new work entirely separate from any past simulations This approachrequires no understanding of git and you are free to make changes to any files in the MIT repo tree (although wegenerally recommend that you avoid doing so instead working in new subdirectories or on separate scratch disks asdescribed in Section 351 for example)

2 Using git pull to update the (unmodified) MITgcm repo tree

If you have downloaded the code through a git clone command (Method 1 above) you can incorporate any changes tothe source code (including any changes to any files in the MITgcm repository new packages or analysis routines etc)

104 Chapter 3 Getting Started with MITgcm

that may have occurred since your original download There is a simple command to bring all code in the repositoryto a lsquocurrent releasersquo state From the MITgcm top directory or any of its subdirectories type

git pull

and all files will be updated to match the current state of the code repository as it exists at GitHub (Note if you planto contribute to the MITgcm and followed the steps to download the code as described in Section 5 you will need totype git pull upstream instead)

This update pathway is ideal if you are in the midst of a project and you want to incorporate new MITgcm featuresinto your executable(s) or take advantage of recently added analysis utilties etc After the git pull any changes inmodel source code and include files will be updated so you can repeat the build procedure (Section 35) and you willinclude all these new features in your new executable

Be forewarned this will only work if you have not modified ANY of the files in the MITgcm repository (adding newfiles is ok also all verification run subdirectories build and run are also ignored by git) If you have modified filesand the git pull fails with errors there is no easy fix other than to learn something about git (continue reading )

3 Fully embracing the power of git

Git offers many tools to help organize and track changes in your work For example one might keep separate projectson different branches and update the code separately (using git pull) on these separate branches You can evenmake changes to code in the MIT repo tree when git then tries to update code from upstream (see Figure 51) itwill notify you about possible conflicts and even merge the code changes together if it can You can also use gitcommit to help you track what you are modifying in your simulations over time If yoursquore planning to submit a pullrequest to include your changes you should read the contributing guide in Section 5 and we suggest you do this modeldevelopment in a separate fresh copy of the code See Section 52 for more information and how to use git effectivelyto manage your workflow

34 Model and directory structure

The ldquonumericalrdquo model is contained within a execution environment support wrapper This wrapper is designed toprovide a general framework for grid-point models MITgcm is a specific numerical model that makes use of thisframework (see chapWrapper for additional detail) Under this structure the model is split into execution environmentsupport code and conventional numerical model code The execution environment support code is held under theeesupp directory The grid point model code is held under the model directory Code execution actually starts inthe eesupp routines and not in the model routines For this reason the top-level MAINF is in the eesuppsrcdirectory In general end-users should not need to worry about the wrapper support code The top-level routine forthe numerical part of the code is in modelsrcTHE_MODEL_MAINF Here is a brief description of the directorystructure of the model under the root tree

bull model this directory contains the main source code Also subdivided into two subdirectories inc (includesfiles) and src (source code)

bull eesupp contains the execution environment source code Also subdivided into two subdirectories inc andsrc

bull pkg contains the source code for the packages Each package corresponds to a subdirectory For examplegmredi contains the code related to the Gent-McWilliamsRedi scheme seaice the code for a dynamicseaice model which can be coupled to the ocean model The packages are described in detail in Section 8]

bull doc contains the MITgcm documentation in reStructured Text (rst) format

bull tools this directory contains various useful tools For example genmake2 is a script written in bash thatshould be used to generate your makefile The subdirectory build_options contains lsquooptfilesrsquo with thecompiler options for many different compilers and machines that can run MITgcm (see Section 3521) This

34 Model and directory structure 105

directory also contains subdirectories adjoint and OAD_support that are used to generate the tangent linearand adjoint model (see details in Section 7)

bull utils this directory contains various utilities The matlab subdirectory contains matlab scripts for readingmodel output directly into matlab The subdirectory python contains similar routines for python scriptscontains C-shell post-processing scripts for joining processor-based and tiled-based model output

bull verification this directory contains the model examples See Section 4

bull jobs contains sample job scripts for running MITgcm

bull lsopt Line search code used for optimization

bull optim Interface between MITgcm and line search code

35 Building the code

To compile the code we use the make program This uses a file (Makefile) that allows us to pre-process source filesspecify compiler and optimization options and also figures out any file dependencies We supply a script (genmake2)described in section Section 352 that automatically creates the Makefile for you You then need to build thedependencies and compile the code

As an example assume that you want to build and run experiment verificationexp2 Letrsquos build the code inverificationexp2build

cd verificationexp2build

First build the Makefile

toolsgenmake2 -mods code

The -mods command line option tells genmake2 to override model source code with any files in the directorycode This and additional genmake2 command line options are described more fully in Section 3522

On many systems the genmake2 program will be able to automatically recognize the hardware find compilers andother tools within the userrsquos path (ldquoecho $PATHrdquo) and then choose an appropriate set of options from the files(ldquooptfilesrdquo) contained in the toolsbuild_options directory Under some circumstances a user may have tocreate a new optfile in order to specify the exact combination of compiler compiler flags libraries and other optionsnecessary to build a particular configuration of MITgcm In such cases it is generally helpful to peruse the existingoptfiles and mimic their syntax See Section 3521

The MITgcm developers are willing to provide help writing or modifing optfiles And we encourage users to ask forassistance or post new optfiles (particularly ones for new machines or architectures) through the GitHub issue trackeror email the MITgcm-supportmitgcmorg list

To specify an optfile to genmake2 the command line syntax is

toolsgenmake2 -mods code -of pathtooptfile

Once a Makefile has been generated we create the dependencies with the command

make depend

This modifies the Makefile by attaching a (usually long) list of files upon which other files depend The purposeof this is to reduce re-compilation if and when you start to modify the code The make depend command alsocreates links from the model source to this directory except for links to those files in the specified -mods directoryIMPORTANT NOTE Editing the source code files in the build directory will not edit a local copy (since these arejust links) but will edit the original files in modelsrc (or modelinc) or in the specified -mods directory While

the latter might be what you intend editing the master copy in modelsrc is usually NOT what was intended andmay cause grief somewhere down the road Rather if you need to add to the list of modified source code files place acopy of the file(s) to edit in the -mods directory make the edits to these -mods directory files go back to the builddirectory and type make Clean and then re-build the makefile (these latter steps critical or the makefile will notlink to to this newly edited file)

It is important to note that the make depend stage will occasionally produce warnings or errors if the dependencyparsing tool is unable to find all of the necessary header files (eg netcdfinc) In some cases you may need toobtain help from your system administrator to locate these files

Next one can compile the code using

The make command creates an executable called mitgcmuv Additional make ldquotargetsrdquo are defined within themakefile to aid in the production of adjoint and other versions of MITgcm On computers with multiple processorcores or shared multi-processor (aka SMP) systems the build process can often be sped up appreciably using thecommand

make -j 2

where the ldquo2rdquo can be replaced with a number that corresponds to the number of cores (or discrete CPUs) available

In addition there are several housekeeping make clean options that might be useful

bull make clean removes files that make generates (eg o and f files)

bull make Clean removes files and links generated by make and make depend

bull make CLEAN removes pretty much everything including any executibles and output from genmake2

Now you are ready to run the model General instructions for doing so are given in section Section 36

351 Buildingcompiling the code elsewhere

In the example above (Section 35) we built the executable in the build directory of the experiment Model objectfiles and output data can use up large amounts of disk space so it is often preferable to operate on a large scratch diskHere we show how to configure and compile the code on a scratch disk without having to copy the entire source treeThe only requirement to do so is you have genmake2 in your path or you know the absolute path to genmake2

Assuming the model source is in ~MITgcm then the following commands will build the model in scratchexp2-run1

cd scratchexp2-run1 ~MITgcmtoolsgenmake2 -rootdir ~MITgcm -mods ~MITgcmverificationexp2code make depend make

Note the use of the command line option -rootdir to tell genmake2 where to find the MITgcm directory tree Ingeneral one can compile the code in any given directory by following this procedure

352 Using genmake2

This section describes further details and capabilities of genmake2 (located in the tools directory) the MITgcmtool used to generate a Makefile genmake2 is a shell script written to work with all ldquoshrdquondashcompatible shells includingbash v1 bash v2 and Bourne (like many unix tools there is a help option that is invoked thru genmake -h)genmake2 parses information from the following sources

35 Building the code 107

bull a genmake_local file if one is found in the current directory

bull command-line options

bull an ldquooptions filerdquo as specified by the command-line option -of pathtofilename

bull a packagesconf file (if one is found) with the specific list of packages to compile The search path for filepackagesconf is first the current directory and then each of the -mods directories in the given order (seehere)

3521 Optfiles in toolsbuild_options directory

The purpose of the optfiles is to provide all the compilation options for particular ldquoplatformsrdquo (where ldquoplatformrdquoroughly means the combination of the hardware and the compiler) and code configurations Given the combi-nations of possible compilers and library dependencies (eg MPI and NetCDF) there may be numerous optfilesavailable for a single machine The naming scheme for the majority of the optfiles shipped with the code isOS_HARDWARE_COMPILER where

OS is the name of the operating system (generally the lower-case output of a linux terminal uname command)

HARDWARE is a string that describes the CPU type and corresponds to output from a uname -m command Somecommon CPU types

amd64 is for x86_64 systems (most common including AMD and Intel 64-bit CPUs)

ia64 is for Intel IA64 systems (eg Itanium Itanium2)

ppc is for (old) Mac PowerPC systems

COMPILER is the compiler name (generally the name of the FORTRAN executable)

In many cases the default optfiles are sufficient and will result in usable Makefiles However for some machines orcode configurations new optfiles must be written To create a new optfile it is generally best to start with one of thedefaults and modify it to suit your needs Like genmake2 the optfiles are all written using a simple shndashcompatiblesyntax While nearly all variables used within genmake2 may be specified in the optfiles the critical ones that shouldbe defined are

FC the FORTRAN compiler (executable) to use

DEFINES the command-line DEFINE options passed to the compiler

CPP the C pre-processor to use

NOOPTFLAGS options flags for special files that should not be optimized

For example the optfile for a typical Red Hat Linux machine (amd64 architecture) using the GCC (g77) compiler is

FC=g77DEFINES=-D_BYTESWAPIO -DWORDLENGTH=4CPP=cpp -traditional -PNOOPTFLAGS=-O0 For IEEE use the -ffloat-store optionif test x$IEEE = x then

FFLAGS=-Wimplicit -Wunused -WuninitializedFOPTIM=-O3 -malign-double -funroll-loops

elseFFLAGS=-Wimplicit -Wunused -ffloat-storeFOPTIM=-O0 -malign-double

If you write an optfile for an unrepresented machine or compiler you are strongly encouraged to submit the optfileto the MITgcm project for inclusion Please submit the file through the GitHub issue tracker or email the MITgcm-supportmitgcmorg list

3522 Command-line options

In addition to the optfiles genmake2 supports a number of helpful command-line options A complete list of theseoptions can be obtained by

genmake2 -h

The most important command-line options are

-optfile pathtofile specifies the optfile that should be used for a particular build

If no optfile is specified (either through the command line or the MITGCM_OPTFILE environment variable)genmake2 will try to make a reasonable guess from the list provided in toolsbuild_options Themethod used for making this guess is to first determine the combination of operating system and hardware (egldquolinux_amd64rdquo) and then find a working FORTRAN compiler within the userrsquos path When these three itemshave been identified genmake2 will try to find an optfile that has a matching name

-mods rsquodir1 dir2 dir3 rsquo specifies a list of directories containing ldquomodificationsrdquo These directoriescontain files with names that may (or may not) exist in the main MITgcm source tree but will be overridden byany identically-named sources within the -mods directories

The order of precedence for this ldquoname-hidingrdquo is as follows

bull ldquomodsrdquo directories (in the order given)

bull Packages either explicitly specified or provided by default (in the order given)

bull Packages included due to package dependencies (in the order that that package dependencies are parsed)

bull The ldquostandard dirsrdquo (which may have been specified by the ldquo-standarddirsrdquo option)

-oad generates a makefile for a OpenAD build

-adof pathtofile specifies the ldquoadjointrdquo or automatic differentiation options file to be used The file isanalogous to the optfile defined above but it specifies information for the AD build process

The default file is located in toolsadjoint_optionsadjoint_default and it defines theldquoTAFrdquo and ldquoTAMCrdquo compilers An alternate version is also available at toolsadjoint_optionsadjoint_staf that selects the newer ldquoSTAFrdquo compiler As with any compilers it is helpful to have theirdirectories listed in your $PATH environment variable

-mpi enables certain MPI features (using CPP define) within the code and is necessary for MPI builds (seeSection 353)

-omp enables OPENMP code and compiler flag OMPFLAG

-ieee use IEEE numerics (requires support in optfile)

-make pathtogmake due to the poor handling of soft-links and other bugs common with the make versionsprovided by commercial Unix vendors GNU make (sometimes called gmake) may be preferred This optionprovides a means for specifying the make executable to be used

353 Building with MPI

Building MITgcm to use MPI libraries can be complicated due to the variety of different MPI implementations avail-able their dependencies or interactions with different compilers and their often ad-hoc locations within file systems

For these reasons its generally a good idea to start by finding and reading the documentation for your machine(s) andif necessary seeking help from your local systems administrator

The steps for building MITgcm with MPI support are

1 Determine the locations of your MPI-enabled compiler andor MPI libraries and put them into an optionsfile as described in Section 3521 One can start with one of the examples in toolsbuild_options such aslinux_amd64_gfortran or linux_amd64_ifort+impi and then edit it to suit the machine at handYou may need help from your user guide or local systems administrator to determine the exact location of theMPI libraries If libraries are not installed MPI implementations and related tools are available including

bull Open MPI

bull MVAPICH2

bull MPICH

bull Intel MPI

2 Build the code with the genmake2 -mpi option (see Section 3522) using commands such as

toolsgenmake2 -mods=code -mpi -of=YOUR_OPTFILE make depend make

36 Running the model

If compilation finished successfully (Section 35) then an executable called mitgcmuv will now exist in the local(build) directory

To run the model as a single process (ie not in parallel) simply type (assuming you are still in the build directory)

cd run ln -s input cp buildmitgcmuv mitgcmuv

Here we are making a link to all the support data files needed by the MITgcm for this experiment and then copyingthe executable from the the build directory The in the last step is a safe-guard to make sure you use the localexecutable in case you have others that might exist in your $PATH The above command will spew out many lines oftext output to your screen This output contains details such as parameter values as well as diagnostics such as meankinetic energy largest CFL number etc It is worth keeping this text output with the binary output so we normallyre-direct the stdout stream as follows

mitgcmuv gt outputtxt

In the event that the model encounters an error and stops it is very helpful to include the last few line of this outputtxt file along with the (stderr) error message within any bug reports

For the example experiments in verification an example of the output is kept in resultsoutputtxt forcomparison You can compare your outputtxt with the corresponding one for that experiment to check that yourset-up indeed works Congratulations

361 Running with MPI

Run the code with the appropriate MPI ldquorunrdquo or ldquoexecrdquo program provided with your particular implementation of MPITypical MPI packages such as Open MPI will use something like

mpirun -np 4 mitgcmuv

Sightly more complicated scripts may be needed for many machines since execution of the code may be controlledby both the MPI library and a job scheduling and queueing system such as SLURM PBS LoadLeveler or any of anumber of similar tools See your local cluster documentation or system administrator for the specific syntax requiredto run on your computing facility

362 Output files

The model produces various output files and when using mnc (ie NetCDF) sometimes even directories Dependingupon the IO package(s) selected at compile time (either mdsio or mnc or both as determined by codepackagesconf) and the run-time flags set (in inputdatapkg) the following output may appear More complete infor-mation describing output files and model diagnostics is described in chap_diagnosticsio

3621 MDSIO output files

The ldquotraditionalrdquo output files are generated by the mdsio package (link to section_mdsio)The mdsio model data arewritten according to a ldquometadatardquo file format Each variable is associated with two files with suffix names dataand meta The data file contains the data written in binary form (big endian by default) The meta file is aldquoheaderrdquo file that contains information about the size and the structure of the data file This way of organizing theoutput is particularly useful when running multi-processors calculations

At a minimum the instantaneous ldquostaterdquo of the model is written out which is made of the following files

bull U00000nIter - zonal component of velocity field (ms and positive eastward)

bull V00000nIter - meridional component of velocity field (ms and positive northward)

bull W00000nIter - vertical component of velocity field (ocean ms and positive upward atmosphere Pas andpositive towards increasing pressure ie downward)

bull T00000nIter - potential temperature (ocean ∘C atmosphere ∘K)

bull S00000nIter - ocean salinity (psu) atmosphere water vapor (gkg)

bull Eta00000nIter - ocean surface elevation (m) atmosphere surface pressure anomaly (Pa)

The chain 00000nIter consists of ten figures that specify the iteration number at which the output is written outFor example U0000000300 is the zonal velocity at iteration 300

In addition a ldquopickuprdquo or ldquocheckpointrdquo file called

bull pickup00000nIter

is written out This file represents the state of the model in a condensed form and is used for restarting the integration(at the specific iteration number) Some additional packages and parameterizations also produce separate pickup fileseg

bull pickup_cd00000nIter if the C-D scheme is used (see link to description)

bull pickup_seaice00000nIter if the seaice package is turned on (see link to description)

bull pickup_ptracers00000nIter if passive tracers are included in the simulation (see link to description)

Rolling checkpoint files are the same as the pickup files but are named differently Their name contain the chainckptA or ckptB instead of 00000nIter They can be used to restart the model but are overwritten every othertime they are output to save disk space during long integrations

36 Running the model 111

3622 MNC output files

The MNC package (link to section_mnc) is a set of routines written to read write and append NetCDF files Unlike themdsio output the mncndashgenerated output is usually placed within a subdirectory with a name such as mnc_output_(by default NetCDF tries to append rather than overwrite existing files so a unique output directory is helpful foreach separate run)

The MNC output files are all in the ldquoself-describingrdquo NetCDF format and can thus be browsed andor plotted usingtools such as

bull ncdump is a utility which is typically included with every NetCDF install and converts the NetCDF binariesinto formatted ASCII text files

bull ncview is a very convenient and quick way to plot NetCDF data and it runs on most platforms Panoply is asimilar alternative

bull Matlab GrADS IDL and other common post-processing environments provide built-in NetCDF interfaces

363 Looking at the output

3631 MATLAB

MDSIO output

The repository includes a few Matlab utilities to read output files written in the mdsio format The Matlab scriptsare located in the directory utilsmatlab under the root tree The script rdmdsm reads the data Look at thecomments inside the script to see how to use it

Some examples of reading and visualizing some output in Matlab

matlabgtgt H=rdmds(Depth)gtgt contourf(H)colorbargtgt title(Depth of fluid as used by model)

gtgt eta=rdmds(Eta10)gtgt imagesc(eta)axis ijcolorbargtgt title(Surface height at iter=10)

gtgt eta=rdmds(Eta[010100])gtgt for n=111 imagesc(eta(n))axis ijcolorbarpause(5)end

NetCDF

Similar scripts for netCDF output (rdmncm) are available and they are described in Section [secpkgmnc]

3632 Python

MDSIO output

The repository includes Python scripts for reading the mdsio format under utilspython The following exampleshows how to load in some data

pythonimport mds

Eta = mdsrdmds(Eta itrs=10)

The docstring for mdsrdmds contains much more detail about using this function and the options that it takes

NetCDF output

The NetCDF output is currently produced with one file per processor This means the individual tiles need to bestitched together to create a single NetCDF file that spans the model domain The script gluemncbigpy in theutilspython folder can do this efficiently from the command line

The following example shows how to use the xarray package to read the resulting NetCDF file into python

pythonimport xarray as xr

Eta = xropen_dataset(Etanc)

37 Customizing the model configuration

When you are ready to run the model in the configuration you want the easiest thing is to use and adapt the setupof the case studies experiment (described in Section 4) that is the closest to your configuration Then the amount ofsetup will be minimized In this section we focus on the setup relative to the ldquonumerical modelrdquo part of the code (thesetup relative to the ldquoexecution environmentrdquo part is covered in the software architecturewrapper section) and on thevariables and parameters that you are likely to change

In what follows the parameters are grouped into categories related to the computational domain the equations solvedin the model and the simulation controls

371 Parameters Computational Domain Geometry and Time-Discretization

Dimensions

The number of points in the x y and r directions are represented by the variables sNx sNy and Nr respec-tively which are declared and set in the file SIZEh (Again this assumes a mono-processor calculationFor multiprocessor calculations see the section on parallel implementation)

Three different grids are available cartesian spherical polar and curvilinear (which includes the cubedsphere) The grid is set through the logical variables usingCartesianGrid usingSphericalPolarGrid andusingCurvilinearGrid In the case of spherical and curvilinear grids the southern boundary is definedthrough the variable ygOrigin which corresponds to the latitude of the southern most cell face (in degrees)The resolution along the x and y directions is controlled by the 1D arrays delx and dely (in meters in thecase of a cartesian grid in degrees otherwise) The vertical grid spacing is set through the 1D array delzfor the ocean (in meters) or delp for the atmosphere (in Pa) The variable Ro_SeaLevel represents thestandard position of sea level in ldquorrdquo coordinate This is typically set to 0 m for the ocean (default value)and 105 Pa for the atmosphere For the atmosphere also set the logical variable groundAtK1 to TRUEwhich puts the first level (k=1) at the lower boundary (ground)

37 Customizing the model configuration 113

For the cartesian grid case the Coriolis parameter 119891 is set through the variables f0 and beta which cor-respond to the reference Coriolis parameter (in sndash1) and 120597119891

120597119910 (in mndash1sndash1) respectively If beta is set to anonzero value f0 is the value of 119891 at the southern edge of the domain

Topography - Full and Partial Cells

The domain bathymetry is read from a file that contains a 2D (xy) map of depths (in m) for the oceanor pressures (in Pa) for the atmosphere The file name is represented by the variable bathyFile The fileis assumed to contain binary numbers giving the depth (pressure) of the model at each grid cell orderedwith the x coordinate varying fastest The points are ordered from low coordinate to high coordinatefor both axes The model code applies without modification to enclosed periodic and double periodicdomains Periodicity is assumed by default and is suppressed by setting the depths to 0 m for the cells atthe limits of the computational domain (note not sure this is the case for the atmosphere) The precisionwith which to read the binary data is controlled by the integer variable readBinaryPrec which can takethe value 32 (single precision) or 64 (double precision) See the matlab program gendatam in theinput directories of verification for several tutorial examples (eg gendatam in the barotropicgyre tutorial) to see how the bathymetry files are generated for the case study experiments

To use the partial cell capability the variable hFacMin needs to be set to a value between 0 and 1 (it is setto 1 by default) corresponding to the minimum fractional size of the cell For example if the bottom cellis 500 m thick and hFacMin is set to 01 the actual thickness of the cell (ie used in the code) can covera range of discrete values 50 m apart from 50 m to 500 m depending on the value of the bottom depth (inbathyFile) at this point

Note that the bottom depths (or pressures) need not coincide with the models levels as deduced from delzor delp The model will interpolate the numbers in bathyFile so that they match the levels obtained fromdelz or delp and hFacMin

(Note the atmospheric case is a bit more complicated than what is written here To come soon )

Time-Discretization

The time steps are set through the real variables deltaTMom and deltaTtracer (in s) which represent thetime step for the momentum and tracer equations respectively For synchronous integrations simplyset the two variables to the same value (or you can prescribe one time step only through the variabledeltaT) The Adams-Bashforth stabilizing parameter is set through the variable abEps (dimensionless)The stagger baroclinic time stepping can be activated by setting the logical variable staggerTimeStep toTRUE

372 Parameters Equation of State

First because the model equations are written in terms of perturbations a reference thermodynamic state needs to bespecified This is done through the 1D arrays tRef and sRef tRef specifies the reference potential temperature profile(in oC for the ocean and K for the atmosphere) starting from the level k=1 Similarly sRef specifies the referencesalinity profile (in ppt) for the ocean or the reference specific humidity profile (in gkg) for the atmosphere

The form of the equation of state is controlled by the character variables buoyancyRelation and eosType buoyan-cyRelation is set to OCEANIC by default and needs to be set to ATMOSPHERIC for atmosphere simulations In thiscase eosType must be set to IDEALGAS For the ocean two forms of the equation of state are available linear (seteosType to LINEAR) and a polynomial approximation to the full nonlinear equation ( set eosType to POLYNOMIAL)In the linear case you need to specify the thermal and haline expansion coefficients represented by the variables tAl-pha (in Kndash1) and sBeta (in pptndash1) For the nonlinear case you need to generate a file of polynomial coefficients calledPOLY3COEFFS To do this use the program utilsknudsen2knudsen2f under the model tree (a Makefile is availablein the same directory and you will need to edit the number and the values of the vertical levels in knudsen2f so thatthey match those of your configuration)

There there are also higher polynomials for the equation of state

rsquoUNESCOrsquo The UNESCO equation of state formula of Fofonoff and Millard (1983) [FRM83] This equation ofstate assumes in-situ temperature which is not a model variable its use is therefore discouraged and it is onlylisted for completeness

rsquoJMD95Zrsquo A modified UNESCO formula by Jackett and McDougall (1995) [JM95] which uses the model variablepotential temperature as input The rsquoZrsquo indicates that this equation of state uses a horizontally and temporallyconstant pressure 1199010 = minus1198921205880119911

rsquoJMD95Prsquo A modified UNESCO formula by Jackett and McDougall (1995) [JM95] which uses the model variablepotential temperature as input The rsquoPrsquo indicates that this equation of state uses the actual hydrostatic pressureof the last time step Lagging the pressure in this way requires an additional pickup file for restarts

rsquoMDJWFrsquo The new more accurate and less expensive equation of state by McDougall et al (1983) [MJWF03] Italso requires lagging the pressure and therefore an additional pickup file for restarts

For none of these options an reference profile of temperature or salinity is required

373 Parameters Momentum Equations

In this section we only focus for now on the parameters that you are likely to change ie the ones relative to forcingand dissipation for example The details relevant to the vector-invariant form of the equations and the various advectionschemes are not covered for the moment We assume that you use the standard form of the momentum equations (iethe flux-form) with the default advection scheme Also there are a few logical variables that allow you to turn onoffvarious terms in the momentum equation These variables are called momViscosity momAdvection momForcinguseCoriolis momPressureForcing momStepping and metricTerms and are assumed to be set to TRUE here Lookat the file PARAMSh for a precise definition of these variables

Initialization

The initial horizontal velocity components can be specified from binary files uVelInitFile and vVelInitFileThese files should contain 3D data ordered in an (xyr) fashion with k=1 as the first vertical level (surfacelevel) If no file names are provided the velocity is initialized to zero The initial vertical velocityis always derived from the horizontal velocity using the continuity equation even in the case of non-hydrostatic simulation (see eg verificationtutorial_deep_convectioninput)

In the case of a restart (from the end of a previous simulation) the velocity field is read from a pickup file(see section on simulation control parameters) and the initial velocity files are ignored

Forcing

This section only applies to the ocean You need to generate wind-stress data into two files zonalWindFileand meridWindFile corresponding to the zonal and meridional components of the wind stress respectively(if you want the stress to be along the direction of only one of the model horizontal axes you only need togenerate one file) The format of the files is similar to the bathymetry file The zonal (meridional) stressdata are assumed to be in Pa and located at U-points (V-points) As for the bathymetry the precisionwith which to read the binary data is controlled by the variable readBinaryPrec See the matlab programgendatam in the input directories of verification for several tutorial example (eg gendatamin the barotropic gyre tutorial) to see how simple analytical wind forcing data are generated for the casestudy experiments

There is also the possibility of prescribing time-dependent periodic forcing To do this concatenate thesuccessive time records into a single file (for each stress component) ordered in a (xyt) fashion and setthe following variables periodicExternalForcing to TRUE externForcingPeriod to the period (in s)of which the forcing varies (typically 1 month) and externForcingCycle to the repeat time (in s) of theforcing (typically 1 year note externForcingCycle must be a multiple of externForcingPeriod) With thesevariables set up the model will interpolate the forcing linearly at each iteration

Dissipation

The lateral eddy viscosity coefficient is specified through the variable viscAh (in m2sndash1) The verticaleddy viscosity coefficient is specified through the variable viscAz (in m2sndash1) for the ocean and viscAp (inPa2sndash1) for the atmosphere The vertical diffusive fluxes can be computed implicitly by setting the logicalvariable implicitViscosity to TRUE In addition biharmonic mixing can be added as well through thevariable viscA4 (in m4sndash1) On a spherical polar grid you might also need to set the variable cosPowerwhich is set to 0 by default and which represents the power of cosine of latitude to multiply viscositySlip or no-slip conditions at lateral and bottom boundaries are specified through the logical variablesno_slip_sides and no_slip_bottom If set to FALSE free-slip boundary conditions are applied If no-slip boundary conditions are applied at the bottom a bottom drag can be applied as well Two formsare available linear (set the variable bottomDragLinear in ms) and quadratic (set the variable bottom-DragQuadratic dimensionless)

The Fourier and Shapiro filters are described elsewhere

C-D Scheme

If you run at a sufficiently coarse resolution you will need the C-D scheme for the computation of theCoriolis terms The variable tauCD which represents the C-D scheme coupling timescale (in s) needs tobe set

Calculation of PressureGeopotential

First to run a non-hydrostatic ocean simulation set the logical variable nonHydrostatic to TRUE Thepressure field is then inverted through a 3D elliptic equation (Note this capability is not available forthe atmosphere yet) By default a hydrostatic simulation is assumed and a 2D elliptic equation is used toinvert the pressure field The parameters controlling the behavior of the elliptic solvers are the variablescg2dMaxIters and cg2dTargetResidual for the 2D case and cg3dMaxIters and cg3dTargetResidual for the3D case You probably wonrsquot need to alter the default values (are we sure of this)

For the calculation of the surface pressure (for the ocean) or surface geopotential (for the atmosphere)you need to set the logical variables rigidLid and implicitFreeSurface (set one to TRUE and the otherto FALSE depending on how you want to deal with the ocean upper or atmosphere lower boundary)

374 Parameters Tracer Equations

This section covers the tracer equations ie the potential temperature equation and the salinity (for the ocean) orspecific humidity (for the atmosphere) equation As for the momentum equations we only describe for now theparameters that you are likely to change The logical variables tempDiffusion tempAdvection tempForcing andtempStepping allow you to turn onoff terms in the temperature equation (same thing for salinity or specific humiditywith variables saltDiffusion saltAdvection etc) These variables are all assumed here to be set to TRUE Look atfile PARAMSh for a precise definition

Initialization

The initial tracer data can be contained in the binary files hydrogThetaFile and hydrogSaltFile These filesshould contain 3D data ordered in an (xyr) fashion with k=1 as the first vertical level If no file names areprovided the tracers are then initialized with the values of tRef and sRef mentioned above In this casethe initial tracer data are uniform in x and y for each depth level

Forcing

This part is more relevant for the ocean the procedure for the atmosphere not being completely stabilizedat the moment

A combination of fluxes data and relaxation terms can be used for driving the tracer equations For poten-tial temperature heat flux data (in Wm2) can be stored in the 2D binary file surfQfile Alternatively or inaddition the forcing can be specified through a relaxation term The SST data to which the model surfacetemperatures are restored to are supposed to be stored in the 2D binary file thetaClimFile The corre-sponding relaxation time scale coefficient is set through the variable tauThetaClimRelax (in s) The same

procedure applies for salinity with the variable names EmPmRfile saltClimFile and tauSaltClimRelaxfor freshwater flux (in ms) and surface salinity (in ppt) data files and relaxation time scale coefficient (ins) respectively Also for salinity if the CPP key USE_NATURAL_BCS is turned on natural boundaryconditions are applied ie when computing the surface salinity tendency the freshwater flux is multipliedby the model surface salinity instead of a constant salinity value

As for the other input files the precision with which to read the data is controlled by the variable read-BinaryPrec Time-dependent periodic forcing can be applied as well following the same procedure usedfor the wind forcing data (see above)

Dissipation

Lateral eddy diffusivities for temperature and salinityspecific humidity are specified through the variablesdiffKhT and diffKhS (in m2s) Vertical eddy diffusivities are specified through the variables diffKzT anddiffKzS (in m2s) for the ocean and diffKpT and diffKpS (in Pa2s) for the atmosphere The verticaldiffusive fluxes can be computed implicitly by setting the logical variable implicitDiffusion to TRUEIn addition biharmonic diffusivities can be specified as well through the coefficients diffK4T and diffK4S(in m4s) Note that the cosine power scaling (specified through cosPower see above) is applied to thetracer diffusivities (Laplacian and biharmonic) as well The Gent and McWilliams parameterization foroceanic tracers is described in the package section Finally note that tracers can be also subject to Fourierand Shapiro filtering (see the corresponding section on these filters)

Ocean convection

Two options are available to parameterize ocean convection To use the first option a convective adjust-ment scheme you need to set the variable cadjFreq which represents the frequency (in s) with whichthe adjustment algorithm is called to a non-zero value (note if cadjFreq set to a negative value by theuser the model will set it to the tracer time step) The second option is to parameterize convection withimplicit vertical diffusion To do this set the logical variable implicitDiffusion to TRUE and the realvariable ivdc_kappa to a value (in m2s) you wish the tracer vertical diffusivities to have when mixingtracers vertically due to static instabilities Note that cadjFreq and ivdc_kappa cannot both have non-zerovalue

375 Parameters Simulation Controls

The model rdquoclockrdquo is defined by the variable deltaTClock (in s) which determines the IO frequencies and is used intagging output Typically you will set it to the tracer time step for accelerated runs (otherwise it is simply set to thedefault time step deltaT) Frequency of checkpointing and dumping of the model state are referenced to this clock (seebelow)

Run Duration

The beginning of a simulation is set by specifying a start time (in s) through the real variable startTime orby specifying an initial iteration number through the integer variable nIter0 If these variables are set tononzero values the model will look for a rdquopickuprdquo file pickup0000nIter0 to restart the integrationThe end of a simulation is set through the real variable endTime (in s) Alternatively you can specifyinstead the number of time steps to execute through the integer variable nTimeSteps

Frequency of Output

Real variables defining frequencies (in s) with which output files are written on disk need to be set updumpFreq controls the frequency with which the instantaneous state of the model is saved chkPtFreqand pchkPtFreq control the output frequency of rolling and permanent checkpoint files respectively Inaddition time-averaged fields can be written out by setting the variable taveFreq (in s) The precision withwhich to write the binary data is controlled by the integer variable writeBinaryPrec (set it to 32 or 64)

376 Parameters Default Values

The CPP keys relative to the ldquonumerical modelrdquo part of the code are all defined and set in the file CPP_OPTIONSh inthe directory modelinc or in one of the code directories of the case study experiments under verification The modelparameters are defined and declared in the file PARAMSh and their default values are set in the routine set_defaultsFThe default values can be modified in the namelist file data which needs to be located in the directory where youwill run the model The parameters are initialized in the routine ini_parmsF Look at this routine to see in what partof the namelist the parameters are located Here is a complete list of the model parameters related to the main model(namelist parameters for the packages are located in the package descriptions) their meaning and their default values

Name Value Description

buoyancyRelation OCEANIC buoyancy relationfluidIsAir F fluid major constituent is airfluidIsWater T fluid major constituent is waterusingPCoords F use pressure coordinatesusingZCoords T use z-coordinatestRef 20E+01 at k=top reference temperature profile ( oC or K )sRef 30E+01 at k=top reference salinity profile ( psu )viscAh 00E+00 lateral eddy viscosity ( m2s )viscAhMax 10E+21 maximum lateral eddy viscosity ( m2s )viscAhGrid 00E+00 grid dependent lateral eddy viscosity ( non-dim )useFullLeith F use full form of Leith viscosity onoff flaguseStrainTensionVisc F use StrainTension form of viscous operator onoff flaguseAreaViscLength F use area for visc length instead of geom meanviscC2leith 00E+00 Leith harmonic visc factor (on grad(vort)non-dim)viscC2leithD 00E+00 Leith harmonic viscosity factor (on grad(div)non-dim)viscC2smag 00E+00 Smagorinsky harmonic viscosity factor (non-dim)viscA4 00E+00 lateral biharmonic viscosity ( m4s )viscA4Max 10E+21 maximum biharmonic viscosity ( m4s )viscA4Grid 00E+00 grid dependent biharmonic viscosity ( non-dim )viscC4leith 00E+00 Leith biharmonic viscosity factor (on grad(vort) non-dim)viscC4leithD 00E+00 Leith biharmonic viscosity factor (on grad(div) non-dim)viscC4Smag 00E+00 Smagorinsky biharmonic viscosity factor (non-dim)no_slip_sides T viscous BCs no-slip sidessideDragFactor 20E+00 side-drag scaling factor (non-dim)viscAr 00E+00 vertical eddy viscosity ( units of r2s )no_slip_bottom T viscous BCs no-slip bottombottomDragLinear 00E+00 linear bottom-drag coefficient ( ms )bottomDragQuadratic 00E+00 quadratic bottom-drag coeff ( 1 )diffKhT 00E+00 Laplacian diffusion of heat laterally ( m2s )diffK4T 00E+00 biharmonic diffusion of heat laterally ( m4s )diffKhS 00E+00 Laplacian diffusion of salt laterally ( m2s )diffK4S 00E+00 biharmonic diffusion of salt laterally ( m4s )diffKrNrT 00E+00 at k=top vertical profile of vertical diffusion of temp ( m2s )diffKrNrS 00E+00 at k=top vertical profile of vertical diffusion of salt ( m2s )diffKrBL79surf 00E+00 surface diffusion for Bryan and Lewis 1979 ( m2s )diffKrBL79deep 00E+00 deep diffusion for Bryan and Lewis 1979 ( m2s )diffKrBL79scl 20E+02 depth scale for Bryan and Lewis 1979 ( m )diffKrBL79Ho -20E+03 turning depth for Bryan and Lewis 1979 ( m )eosType LINEAR equation of state

Continued on next page

Table 31 ndash continued from previous pagetAlpha 20E-04 linear EOS thermal expansion coefficient ( 1oC )

sBeta 74E-04 linear EOS haline contraction coef ( 1psu )rhonil 9998E+02 reference density ( kgm3 )rhoConst 9998E+02 reference density ( kgm3 )rhoConstFresh 9998E+02 reference density ( kgm3 )gravity 981E+00 gravitational acceleration ( ms2 )gBaro 981E+00 barotropic gravity ( ms2 )rotationPeriod 86164E+04 rotation period ( s )omega 2120587rotationPeriod angular velocity ( rads )f0 10E-04 reference coriolis parameter ( 1s )beta 10E-11 beta ( mndash1sndash1 )freeSurfFac 10E+00 implicit free surface factorimplicitFreeSurface T implicit free surface onoff flagrigidLid F rigid lid onoff flagimplicSurfPress 10E+00 surface pressure implicit factor (0-1)implicDiv2Dflow 10E+00 barotropic flow div implicit factor (0-1)exactConserv F exact volume conservation onoff flaguniformLin_PhiSurf T use uniform Bo_surf onoff flagnonlinFreeSurf 0 non-linear free surf options (-10123)hFacInf 20E-01 lower threshold for hFac (nonlinFreeSurf only)hFacSup 20E+00 upper threshold for hFac (nonlinFreeSurf only)select_rStar 0 ruseRealFreshWaterFlux F real freshwater flux onoff flagconvertFW2Salt 35E+01 convert FW flux to salt flux (-1=use local S)use3Dsolver F use 3-D pressure solver onoff flagnonHydrostatic F non-hydrostatic onoff flagnh_Am2 10E+00 non-hydrostatic terms scaling factorquasiHydrostatic F quasi-hydrostatic onoff flagmomStepping T momentum equation onoff flagvectorInvariantMomentum F vector-invariant momentum onoffmomAdvection T momentum advection onoff flagmomViscosity T momentum viscosity onoff flagmomImplVertAdv F momentum implicit vert advection onoffimplicitViscosity F implicit viscosity onoff flagmetricTerms F metric terms onoff flaguseNHMTerms F non-hydrostatic metric terms onoffuseCoriolis T Coriolis onoff flaguseCDscheme F CD scheme onoff flaguseJamartWetPoints F Coriolis wetpoints method flaguseJamartMomAdv F VI non-linear terms Jamart flag

SadournyCoriolis F Sadourny Coriolis discretization flagupwindVorticity F upwind bias vorticity flag

Table 33 ndash continued from previous pageuseAbsVorticity F work with fhighOrderVorticity F high order interp of vort flagupwindShear F upwind vertical shear advection flagselectKEscheme 0 kinetic energy scheme selectormomForcing T momentum forcing onoff flagmomPressureForcing T momentum pressure term onoff flagimplicitIntGravWave F implicit internal gravity wave flagstaggerTimeStep F stagger time stepping onoff flagmultiDimAdvection T enabledisable multi-dim advectionuseMultiDimAdvec F multi-dim advection isis-not usedimplicitDiffusion F implicit diffusion onoff flagtempStepping T temperature equation onoff flagtempAdvection T temperature advection onoff flagtempImplVertAdv F temp implicit vert advection onofftempForcing T temperature forcing onoff flagsaltStepping T salinity equation onoff flagsaltAdvection T salinity advection onoff flagsaltImplVertAdv F salinity implicit vert advection onoffsaltForcing T salinity forcing onoff flagreadBinaryPrec 32 precision used for reading binary fileswriteBinaryPrec 32 precision used for writing binary filesglobalFiles F write ldquoglobalrdquo (=not per tile) filesuseSingleCpuIO F only master MPI process does IOdebugMode F debug Mode onoff flagdebLevA 1 1st level of debuggingdebLevB 2 2nd level of debuggingdebugLevel 1 select debugging levelcg2dMaxIters 150 upper limit on 2d con grad iterationscg2dChkResFreq 1 2d con grad convergence test frequencycg2dTargetResidual 10E-07 2d con grad target residualcg2dTargetResWunit -10E+00 cg2d target residual [W units]cg2dPreCondFreq 1 freq for updating cg2d pre-conditionernIter0 0 run starting timestep numbernTimeSteps 0 number of timestepsdeltatTmom 60E+01 momentum equation timestep ( s )deltaTfreesurf 60E+01 freeSurface equation timestep ( s )dTtracerLev 60E+01 at k=top tracer equation timestep ( s )deltaTClock 60E+01 model clock timestep ( s )

cAdjFreq 00E+00 convective adjustment interval ( s )momForcingOutAB 0 =1 take momentum forcing out of Adams-BashforthtracForcingOutAB 0 =1 take TSpTr forcing out of Adams-BashforthmomDissip_In_AB T put dissipation tendency in Adams-BashforthdoAB_onGtGs T apply AB on tendencies (rather than on TS)abEps 10E-02 Adams-Bashforth-2 stabilizing weightbaseTime 00E+00 model base time ( s )startTime 00E+00 run start time ( s )

Table 34 ndash continued from previous pageendTime 00E+00 integration ending time ( s )pChkPtFreq 00E+00 permanent restartcheckpoint file interval ( s )chkPtFreq 00E+00 rolling restartcheckpoint file interval ( s )pickup_write_mdsio T model IO flagpickup_read_mdsio T model IO flagpickup_write_immed F model IO flagdumpFreq 00E+00 model state write out interval ( s )dumpInitAndLast T write out initial and last iteration model statesnapshot_mdsio | T | model IO flagmonitorFreq 60E+01 monitor output interval ( s )monitor_stdio | T | model IO flagexternForcingPeriod 00E+00 forcing period (s)externForcingCycle 00E+00 period of the cycle (s)tauThetaClimRelax 00E+00 relaxation time scale (s)tauSaltClimRelax 00E+00 relaxation time scale (s)latBandClimRelax 3703701E+05 maximum latitude where relaxation appliedusingCartesianGrid T Cartesian coordinates flag ( true false )usingSphericalPolarGrid F spherical coordinates flag ( true false )usingCylindricalGrid F spherical coordinates flag ( true false )Ro_SeaLevel 00E+00 r(1) ( units of r )rkSign -10E+00 index orientation relative to vertical coordinatehoriVertRatio 10E+00 ratio on units horizontal - verticaldrC 50E+03 at k=1 center cell separation along Z axis ( units of r )drF 10E+04 at k=top cell face separation along Z axis ( units of r )delX 1234567E+05 at i=east U-point spacing ( m - cartesian degrees - spherical )delY 1234567E+05 at j=1 V-point spacing ( m - cartesian degrees - spherical )ygOrigin 00E+00 South edge Y-axis origin (cartesian m spherical deg)xgOrigin 00E+00 West edge X-axis origin (cartesian m spherical deg)rSphere 637E+06 Radius ( ignored - cartesian m - spherical )xcoord 6172835E+04 at i=1 P-point X coord ( m - cartesian degrees - spherical )ycoord 6172835E+04 at j=1 P-point Y coord ( m - cartesian degrees - spherical )rcoord -50E+03 at k=1 P-point r coordinate ( units of r )rF 00E+00 at k=1 W-interface r coordinate ( units of r )dBdrRef 00E+00 at k=top vertical gradient of reference buoyancy [ (msr)2 ]

dxF 1234567E+05 at k=top dxF(11) ( m - cartesian degrees - spherical )dyF 1234567E+05 at i=east dyF(11) ( m - cartesian degrees - spherical )dxG 1234567E+05 at i=east dxG(11) ( m - cartesian degrees - spherical )dyG 1234567E+05 at i=east dyG(11) ( m - cartesian degrees - spherical )dxC 1234567E+05 at i=east dxC(11) ( m - cartesian degrees - spherical )dyC 1234567E+05 at i=east dyC(11) ( m - cartesian degrees - spherical )dxV 1234567E+05 at i=east dxV(11) ( m - cartesian degrees - spherical )dyU 1234567E+05 at i=east dyU(11) ( m - cartesian degrees - spherical )rA 1524155E+10 at i=east rA(11) ( m - cartesian degrees - spherical )rAw 1524155E+10 at k=top rAw(11) ( m - cartesian degrees - spherical )rAs 1524155E+10 at k=top rAs(11) ( m - cartesian degrees - spherical )

tempAdvScheme 2 temp horiz advection scheme selectortempVertAdvScheme 2 temp vert advection scheme selectortempMultiDimAdvec F use multi-dim advection method for temptempAdamsBashforth T use Adams-Bashforth time-stepping for tempsaltAdvScheme 2 salinity horiz advection scheme selectorsaltVertAdvScheme 2 salinity vert advection scheme selectorsaltMultiDimAdvec F use multi-dim advection method for saltsaltAdamsBashforth T use Adams-Bashforth time-stepping for salt

CHAPTER 4

MITgcm Tutorial Example Experiments

The full MITgcm distribution comes with a set of pre-configured numerical experiments Some of these exampleexperiments are tests of individual parts of the model code but many are fully fledged numerical simulations Fulltutorials exist for a few of the examples and are documented in sections Section 41 - Section 42 The other examplesfollow the same general structure as the tutorial examples However they only include brief instructions in textfile README The examples are located in subdirectories under the directory verification Each example is brieflydescribed below

41 Barotropic Gyre MITgcm Example

(in directory verificationtutorial_barotropic_gyre)

This example experiment demonstrates using the MITgcm to simulate a Barotropic wind-forced ocean gyre circu-lation The experiment is a numerical rendition of the gyre circulation problem similar to the problems describedanalytically by Stommel in 1966 [Sto48] and numerically in Holland et al [HL75]

In this experiment the model is configured to represent a rectangular enclosed box of fluid 1200 times 1200 km in lateralextent The fluid is 5 km deep and is forced by a constant in time zonal wind stress 120591119909 that varies sinusoidally inthe lsquonorth-southrsquo direction Topologically the grid is Cartesian and the coriolis parameter 119891 is defined according to amid-latitude beta-plane equation

119891(119910) = 1198910 + 120573119910 (41)

where 119910 is the distance along the lsquonorth-southrsquo axis of the simulated domain For this experiment 1198910 is set to 10minus4119904minus1

in (41) and 120573 = 10minus11119904minus1119898minus1

The sinusoidal wind-stress variations are defined according to

120591119909(119910) = 1205910 sin(120587119910

119871119910) (42)

where 119871119910 is the lateral domain extent (1200~km) and 1205910 is set to 01119873119898minus2

Figure 41 summarizes the configuration simulated

Ly=1200km

Lx=1200km

=01=0 xτxτ

minusminusminus

minusminus

yLff β+= 0

Figure 41 Schematic of simulation domain and wind-stress forcing function for barotropic gyre numerical experi-ment The domain is enclosed by solid walls at 119909 = 0 1200 km and at 119910 = 0 1200 km

411 Equations Solved

The model is configured in hydrostatic form The implicit free surface form of the pressure equation described in[MHPA97] is employed A horizontal Laplacian operator nabla2

ℎ provides viscous dissipation The wind-stress momen-tum input is added to the momentum equation for the lsquozonal flowrsquo 119906 Other terms in the model are explicitly switchedoff for this experiment configuration (see section Section 413 ) yielding an active set of equations solved in thisconfiguration as follows

119863119906

119863119905minus 119891119907 + 119892

120597120578

120597119909minus119860ℎnabla2

ℎ119906 =120591119909

1205880∆119911

119863119907

119863119905+ 119891119906+ 119892

120597120578

120597119910minus119860ℎnabla2

ℎ119907 =0

120597120578

120597119905+ nablaℎ middot =0

where 119906 and 119907 and the 119909 and 119910 components of the flow vector

412 Discrete Numerical Configuration

The domain is discretised with a uniform grid spacing in the horizontal set to ∆119909 = ∆119910 = 20 km so that there aresixty grid cells in the 119909 and 119910 directions Vertically the model is configured with a single layer with depth ∆119911 of 5000m

4121 Numerical Stability Criteria

The Laplacian dissipation coefficient 119860ℎ is set to 400119898119904minus1 This value is chosen to yield a Munk layer width[Adc95]

124 Chapter 4 MITgcm Tutorial Example Experiments

119872119908 = 120587(119860ℎ

120573)

13 (44)

of asymp 100km This is greater than the model resolution ∆119909 ensuring that the frictional boundary layer is well resolved

The model is stepped forward with a time step 120575119905 = 1200 secs With this time step the stability parameter to thehorizontal Laplacian friction [Adc95]

119878119897 = 4119860ℎ120575119905

∆1199092(45)

evaluates to 0012 which is well below the 03 upper limit for stability

The numerical stability for inertial oscillations [Adc95]

119878119894 = 11989121205751199052 (46)

The advective CFL [Adc95] for an extreme maximum horizontal flow speed of || = 2119898119904minus1

119878119886 =||120575119905∆119909

evaluates to 012 This is approaching the stability limit of 05 and limits 120575119905 to 1200 s

413 Code Configuration

The model configuration for this experiment resides under the directory verificationtutorial_barotropic_gyre

The experiment files

bull inputdata

bull inputdatapkg

bull inputeedata

bull inputwindxsin_y

bull inputtopogbox

bull codeCPP_EEOPTIONSh

bull codeCPP_OPTIONSh

bull codeSIZEh

contain the code customizations and parameter settings for this experiments Below we describe the customizations tothese files associated with this experiment

41 Barotropic Gyre MITgcm Example 125

4131 File inputdata

This file reproduced completely below specifies the main parameters for the experiment The parameters that aresignificant for this configuration are

bull Line 7

ndash viscAh=4E2

ndash this line sets the Laplacian friction coefficient to 4001198982119904minus1

bull Line 10

ndash beta=1E-11

ndash this line sets 120573 (the gradient of the coriolis parameter 119891 ) to 10minus11119904minus1119898minus1

bull Lines 15 and 16

ndash rigidLid=FALSE

ndash implicitFreeSurface=TRUE

ndash these lines suppress the rigid lid formulation of the surface pressure inverter and activate the implicit freesurface form of the pressure inverter

bull Line 27

ndash startTime=0

ndash this line indicates that the experiment should start from 119905 = 0 and implicitly suppresses searching forcheckpoint files associated with restarting an numerical integration from a previously saved state

bull Line 29

ndash endTime=12000

ndash this line indicates that the experiment should start finish at 119905 = 12000119904 A restart file will be written at thistime that will enable the simulation to be continued from this point

bull Line 30

ndash deltaTmom=1200

ndash This line sets the momentum equation timestep to 1200119904

bull Line 39

ndash usingCartesianGrid=TRUE

ndash This line requests that the simulation be performed in a Cartesian coordinate system

bull Line 41

ndash delX=6020E3

ndash This line sets the horizontal grid spacing between each x-coordinate line in the discrete grid The syntaxindicates that the discrete grid should be comprise of $60$ grid lines each separated by 20 times 103119898 (20km)

bull Line 42

ndash delY=6020E3

ndash This line sets the horizontal grid spacing between each y-coordinate line in the discrete grid to 20times 103119898(20 km)

bull Line 43

ndash delZ=5000

ndash This line sets the vertical grid spacing between each z-coordinate line in the discrete grid to 5000m (5 km)

bull Line 46

ndash bathyFile=rsquotopogboxrsquo

ndash This line specifies the name of the file from which the domain bathymetry is read This file is a two-dimensional (119909 119910) map of depths This file is assumed to contain 64-bit binary numbers giving the depthof the model at each grid cell ordered with the x coordinate varying fastest The points are ordered fromlow coordinate to high coordinate for both axes The units and orientation of the depths in this file are thesame as used in the MITgcm code In this experiment a depth of 0 m indicates a solid wall and a depth of-5000 m indicates open ocean The matlab program inputgendatam shows an example of how to generatea bathymetry file

bull Line 49

ndash zonalWindFile=rsquowindxsin_yrsquo

ndash This line specifies the name of the file from which the x-direction surface wind stress is read This file isalso a two-dimensional (119909 119910) map and is enumerated and formatted in the same manner as the bathymetryfile The matlab program inputgendatam includes example code to generate a valid zonalWindFile file

other lines in the file inputdata are standard values that are described in the MITgcm Getting Started and MITgcmParameters notes

Listing 41 verificationtutorial_barotropic_gyreinputdata

1 Model parameters2 Continuous equation parameters3 ampPARM014 tRef=205 sRef=106 viscAz=1E-27 viscAh=4E28 diffKhT=4E29 diffKzT=1E-2

10 beta=1E-1111 tAlpha=2E-412 sBeta =013 gravity=98114 gBaro=98115 rigidLid=FALSE16 implicitFreeSurface=TRUE17 eosType=LINEAR18 readBinaryPrec=6419 amp20

21 Elliptic solver parameters22 ampPARM0223 cg2dMaxIters=100024 cg2dTargetResidual=1E-725 amp26

27 Time stepping parameters28 ampPARM0329 startTime=030 endTime=31104000031 endTime=120000

32 deltaTmom=1200033 deltaTtracer=1200034 abEps=0135 pChkptFreq=2592000036 chkptFreq=120000037 dumpFreq=2592000038 monitorSelect=239 monitorFreq=140 amp41

42 Gridding parameters43 ampPARM0444 usingCartesianGrid=TRUE45 usingSphericalPolarGrid=FALSE46 delX=6020E347 delY=6020E348 delZ=500049 amp50

51 Input datasets52 ampPARM0553 bathyFile=topogbox54 hydrogThetaFile=55 hydrogSaltFile=56 zonalWindFile=windxsin_y57 meridWindFile=58 amp

4132 File inputdatapkg

This file uses standard default values and does not contain customizations for this experiment

4133 File inputeedata

4134 File inputwindxsin_y

The inputwindxsin_y file specifies a two-dimensional (119909 119910) map of wind stress 120591119909 values The units used are119873119898minus2Although 120591119909 is only a function of 119910 in this experiment this file must still define a complete two-dimensional map inorder to be compatible with the standard code for loading forcing fields in MITgcm The included matlab programinputgendatam gives a complete code for creating the inputwindxsin_y file

4135 File inputtopogbox

The inputtopogbox file specifies a two-dimensional (119909 119910) map of depth values For this experiment values are either0 m or minus119889119890119897119885 m corresponding respectively to a wall or to deep ocean The file contains a raw binary stream of datathat is enumerated in the same way as standard MITgcm two-dimensional horizontal arrays The included matlabprogram inputgendatam gives a completecode for creating the inputtopogbox file

4136 File codeSIZEh

Two lines are customized in this file for the current experiment

bull Line 39

ndash sNx=60

ndash this line sets the lateral domain extent in grid points for the axis aligned with the x-coordinate

bull Line 40

ndash sNy=60

ndash this line sets the lateral domain extent in grid points for the axis aligned with the y-coordinate

Listing 42 verificationtutorial_barotropic_gyrecodeSIZEh

1 C2 C ==========================================================3 C | SIZEh Declare size of underlying computational grid |4 C |==========================================================|5 C | The design here support a three-dimensional model grid |6 C | with indices IJ and K The three-dimensional domain |7 C | is comprised of nPxnSx blocks of size sNx along one axis|8 C | nPynSy blocks of size sNy along another axis and one |9 C | block of size Nz along the final axis |

10 C | Blocks have overlap regions of size OLx and OLy along the|11 C | dimensions that are subdivided |12 C ==========================================================13 C Voodoo numbers controlling data layout14 C sNx - No X points in sub-grid15 C sNy - No Y points in sub-grid16 C OLx - Overlap extent in X17 C OLy - Overlat extent in Y18 C nSx - No sub-grids in X19 C nSy - No sub-grids in Y20 C nPx - No of processes to use in X21 C nPy - No of processes to use in Y22 C Nx - No points in X for the total domain23 C Ny - No points in Y for the total domain24 C Nr - No points in R for full process domain25 INTEGER sNx26 INTEGER sNy27 INTEGER OLx28 INTEGER OLy29 INTEGER nSx30 INTEGER nSy31 INTEGER nPx32 INTEGER nPy33 INTEGER Nx34 INTEGER Ny35 INTEGER Nr36 PARAMETER (37 amp sNx = 3038 amp sNy = 3039 amp OLx = 240 amp OLy = 241 amp nSx = 242 amp nSy = 2

43 amp nPx = 144 amp nPy = 145 amp Nx = sNxnSxnPx46 amp Ny = sNynSynPy47 amp Nr = 1)48

49 C MAX_OLX - Set to the maximum overlap region size of any array50 C MAX_OLY that will be exchanged Controls the sizing of exch51 C routine buufers52 INTEGER MAX_OLX53 INTEGER MAX_OLY54 PARAMETER ( MAX_OLX = OLx55 amp MAX_OLY = OLy )56

4137 File codeCPP_OPTIONSh

4138 File codeCPP_EEOPTIONSh

42 A Rotating Tank in Cylindrical Coordinates

(in directory verificationrotating_tank)

This example configuration demonstrates using the MITgcm to simulate a laboratory demonstration using a differen-tially heated rotating annulus of water The simulation is configured for a laboratory scale on a 3∘ times 1cm cyclindricalgrid with twenty-nine vertical levels of 05cm each This is a typical laboratory setup for illustration principles ofGFD as well as for a laboratory data assimilation project

example illustration from GFD lab here

The domain is discretised with a uniform cylindrical grid spacing in the horizontal set to ∆119886 = 1lsquo 119888119898119886119899119889 119898119886119905ℎ Delta phi=3^circlsquo so that there are 120 grid cells in the azimuthal direction and thirty-one grid cells inthe radial representing a tank 62cm in diameter The bathymetry file sets the depth=0 in the nine lowest radial rowsto represent the central of the annulus Vertically the model is configured with twenty-nine layers of uniform 05cmthickness

something about heat flux

The model configuration for this experiment resides under the directory verificationrotatingi_tankThe experiment files

bull inputdata

bull inputdatapkg

bull inputeedata

bull inputbathyPolbin

bull inputthetaPolbin

bull codeSIZEh

4231 File inputdata

bull Lines 9-10

ndash viscAh=50E-6

ndash viscAz=50E-6

These lines set the Laplacian friction coefficient in the horizontal and vertical respectively Note that they are severalorders of magnitude smaller than the other examples due to the small scale of this example

bull Lines 13-16

ndash diffKhT=25E-6

ndash diffKzT=25E-6

ndash diffKhS=10E-6

ndash diffKzS=10E-6

These lines set horizontal and vertical diffusion coefficients for temperature and salinity Similarly to the frictioncoefficients the values are a couple of orders of magnitude less than most configurations

bull Line 17 f0=05 this line sets the coriolis term and represents a tank spinning at about 24 rpm

ndash rigidLid=TRUE

ndash implicitFreeSurface=FALSE

These lines activate the rigid lid formulation of the surface pressure inverter and suppress the implicit free surfaceform of the pressure inverter

bull Line 40

ndash nIter=0

This line indicates that the experiment should start from $t=0$ and implicitly suppresses searching for checkpoint filesassociated with restarting an numerical integration from a previously saved state Instead the file thetaPolbin will beloaded to initialized the temperature fields as indicated below and other variables will be initialized to their defaults

bull Line 43

42 A Rotating Tank in Cylindrical Coordinates 131

ndash deltaT=01

This line sets the integration timestep to $01s$ This is an unsually small value among the examples due to the smallphysical scale of the experiment Using the ensemble Kalman filter to produce input fields can necessitate even shortertimesteps

bull Line 56

ndash usingCylindricalGrid=TRUE

This line requests that the simulation be performed in a cylindrical coordinate system

bull Line 57

ndash dXspacing=3

This line sets the azimuthal grid spacing between each $x$-coordinate line in the discrete grid The syntax indicatesthat the discrete grid should be comprised of $120$ grid lines each separated by $3^circ$

bull Line 58

ndash dYspacing=001

This line sets the radial cylindrical grid spacing between each 119886-coordinate line in the discrete grid to 1119888119898

bull Line 59

ndash delZ=290005

This line sets the vertical grid spacing between each of 29 z-coordinate lines in the discrete grid to $0005m$($5$~mm)

bull Line 64

ndash bathyFile=rsquobathyPolbinrsquo

This line specifies the name of the file from which the domain lsquobathymetryrsquo (tank depth) is read This file is a two-dimensional (119886 120593) map of depths This file is assumed to contain 64-bit binary numbers giving the depth of the modelat each grid cell ordered with the $phi$ coordinate varying fastest The points are ordered from low coordinate tohigh coordinate for both axes The units and orientation of the depths in this file are the same as used in the MITgcmcode In this experiment a depth of $0m$ indicates an area outside of the tank and a depth f minus0145119898 indicates thetank itself

bull Line 65

ndash hydrogThetaFile=rsquothetaPolbinrsquo

This line specifies the name of the file from which the initial values of temperature are read This file is a three-dimensional (119909 119910 119911) map and is enumerated and formatted in the same manner as the bathymetry file

ndash tCylIn = 0

ndash tCylOut = 20

These line specify the temperatures in degrees Celsius of the interior and exterior walls of the tank ndash typically taken tobe icewater on the inside and room temperature on the outside

Other lines in the file inputdata are standard values that are described in the MITgcm Getting Started and MITgcmParameters notes

Listing 43 verificationrotating_tankinputdata

1 ====================2 | Model parameters |3 ====================4 5 Continuous equation parameters6 ampPARM017 tRef=292008 sRef=293509 viscAh=50E-6

10 viscAz=50E-611 no_slip_sides=FALSE12 no_slip_bottom=FALSE13 diffKhT=25E-614 diffKzT=25E-615 diffKhS=10E-616 diffKzS=10E-617 f0=0518 eosType=LINEAR19 sBeta =020 gravity=98121 rhoConst=1000022 rhoNil=1000023 heatCapacity_Cp=3900024 rigidLid=TRUE25 implicitFreeSurface=FALSE26 nonHydrostatic=TRUE27 readBinaryPrec=3228 amp29

30 Elliptic solver parameters31 ampPARM0232 cg2dMaxIters=100033 cg2dTargetResidual=1E-734 cg3dMaxIters=1035 cg3dTargetResidual=1E-936 amp37

38 Time stepping parameters39 ampPARM0340 nIter0=041 nTimeSteps=2042 nTimeSteps=3600000043 deltaT=0144 abEps=0145 pChkptFreq=2046 chkptFreq=2047 dumpFreq=2048 monitorSelect=249 monitorFreq=0150 amp51

52 Gridding parameters53 ampPARM0454 usingCylindricalGrid=TRUE55 dXspacing=356 dYspacing=001

57 delZ=29000558 ygOrigin=00759 amp60

61 Input datasets62 ampPARM0563 hydrogThetaFile=thetaPolRbin64 bathyFile=bathyPolRbin65 tCylIn = 066 tCylOut = 2067 amp

4234 File inputthetaPolbin

The it inputthetaPolbin file specifies a three-dimensional ($xyz$) map of initial values of $theta$ in degreesCelsius This particular experiment is set to random values x around 20C to provide initial perturbations

4235 File inputbathyPolbin

The it inputbathyPolbin file specifies a two-dimensional ($xy$) map of depth values For this experiment valuesare either $0m$ or bf -delZm corresponding respectively to outside or inside of the tank The file contains a rawbinary stream of data that is enumerated in the same way as standard MITgcm two-dimensional horizontal arrays

4236 File codeSIZEh

bull Line 39 - sNx=120

this line sets the lateral domain extent in grid points for the axis aligned with the x-coordinate

bull Line 40 - sNy=31

this line sets the lateral domain extent in grid points for the axis aligned with the y-coordinate

Listing 44 verificationrotating_tankcodeSIZEh

1 C2 C ==========================================================3 C | SIZEh Declare size of underlying computational grid |4 C |==========================================================|5 C | The design here support a three-dimensional model grid |6 C | with indices IJ and K The three-dimensional domain |7 C | is comprised of nPxnSx blocks of size sNx along one axis|

8 C | nPynSy blocks of size sNy along another axis and one |9 C | block of size Nz along the final axis |

10 C | Blocks have overlap regions of size OLx and OLy along the|11 C | dimensions that are subdivided |12 C ==========================================================13 C Voodoo numbers controlling data layout14 C sNx - No X points in sub-grid15 C sNy - No Y points in sub-grid16 C OLx - Overlap extent in X17 C OLy - Overlat extent in Y18 C nSx - No sub-grids in X19 C nSy - No sub-grids in Y20 C nPx - No of processes to use in X21 C nPy - No of processes to use in Y22 C Nx - No points in X for the total domain23 C Ny - No points in Y for the total domain24 C Nr - No points in Z for full process domain25 INTEGER sNx26 INTEGER sNy27 INTEGER OLx28 INTEGER OLy29 INTEGER nSx30 INTEGER nSy31 INTEGER nPx32 INTEGER nPy33 INTEGER Nx34 INTEGER Ny35 INTEGER Nr36 PARAMETER (37 amp sNx = 3038 amp sNy = 2339 amp OLx = 340 amp OLy = 341 amp nSx = 442 amp nSy = 143 amp nPx = 144 amp nPy = 145 amp Nx = sNxnSxnPx46 amp Ny = sNynSynPy47 amp Nr = 29)48

CHAPTER 5

Contributing to the MITgcm

The MITgcm is an open source project that relies on the participation of its users and we welcome contributions Thischapter sets out how you can contribute to the MITgcm

51 Bugs and feature requests

If you think yoursquove found a bug the first thing to check that yoursquore using the latest version of the model If the bugis still in the latest version then think about how you might fix it and file a ticket in the GitHub issue tracker Pleaseinclude as much detail as possible At a minimum your ticket should include

bull what the bug does

bull the location of the bug file name and line number(s) and

bull any suggestions you have for how it might be fixed

To request a new feature or guidance on how to implement it yourself please open a ticket with the following details

bull a clear explanation of what the feature will do and

bull a summary of the equations to be solved

52 Using Git and Github

To contribute to the source code of the model you will need to fork the repository and place a pull request on GitHubThe two following sections describe this process in different levels of detail If you are unfamiliar with git you maywish to skip the quickstart guide and use the detailed instructions All contributions to the source code are expectedto conform with the Coding style guide Contributions to the manual should follow the same procedure and conformwith Section 54

521 Quickstart Guide

1 Fork the project on GitHub (using the fork button)

2 Create a local clone (we strongly suggest keeping a separate repository for development work)

git clone httpsgithubcomuser_nameMITgcmgit

3 Move into your local clone directory (cd MITgcm) and and set up a remote that points to the original

git remote add upstream httpsgithubcomMITgcmMITgcmgit

4 Make a new branch from upstreammaster (name it something appropriate here we call the new featurebranch newfeature) and make edits on this branch

git fetch upstream git checkout -b newfeature upstreammaster

5 When edits are done do all git addrsquos and git commitrsquos In the commit message make a succinct (lt70 char)summary of your changes If you need more space to describe your changes you can leave a blank line and type alonger description or break your commit into multiple smaller commits Reference any outstanding issues addressedusing the syntax ISSUE_NUMBER

6 Push the edited branch to the origin remote (ie your fork) on GitHub

git push -u origin newfeature

7 On GitHub go to your fork and hit the pull request (PR) button and wait for the MITgcm head developers to reviewyour proposed changes In general the MITgcm code reviewers try to respond to a new PR within a week A responsemay accept the changes or may request edits and changes Occasionally the review team will reject changes that arenot sufficiently aligned with and do not fit with the code structure The review team is always happy to discuss theirdecisions but wants to avoid people investing extensive effort in code that has a fundamental design flaw The currentreview team is Jean-Michel Campin Ed Doddridge Chris Hill and Oliver Jahn

If you want to update your code branch before submitting a PR (or any point in development) follow the recipe belowIt will ensure that your GitHub repo stays up to date with the main repository Note again that your edits should alwaysbe to a development branch (here newfeature) not the master branch

git checkout master git pull upstream master git push origin master git checkout newfeature git merge master

If you prefer you can rebase rather than merge in the final step above just be careful regarding your rebase syntax

522 Detailed guide for those less familiar with Git and GitHub

What is Git Git is a version control software tool used to help coordinate work among the many MITgcm modelcontributors Version control is a management system to track changes in code over time not only facilitating ongoingchanges to code but also as a means to check differences andor obtain code from any past time in the project historyWithout such a tool keeping track of bug fixes and new features submitted by the global network of MITgcm contrib-utors would be virtually impossible If you are familiar with the older form of version control used by the MITgcm(CVS) there are many similarities but we now take advantage of the modern capabilities offered by Git

Git itself is open source linux software (typically included with any new linux installation check with your sys-adminif it seems to be missing) that is necessary for tracking changes in files etc through your local computerrsquos terminal

138 Chapter 5 Contributing to the MITgcm

session All Git-related terminal commands are of the form git ltargumentsgt Important functions includesyncing or updating your code library adding files to a collection of files with edits and commands to ldquofinalizerdquo thesechanges for sending back to the MITgcm maintainers There are numerous other Git command-line tools to help alongthe way (see man pages via man git)

The most common git commands are

bull git clone download (clone) a repository to your local machine

bull git status obtain information about the local git repository

bull git diff highlight differences between the current version of a file and the version from the most recentcommit

bull git add stage a file or changes to a file so that they are ready for git commit

bull git commit create a commit A commit is a snapshot of the repository with an associated message thatdescribes the changes

What is GitHub then GitHub is a website that has three major purposes 1) Code Viewer through your browser youcan view all source code and all changes to such over time 2) ldquoPull Requestsrdquo facilitates the process whereby codedevelopers submit changes to the primary MITgcm maintainers 3) the ldquoCloudrdquo GitHub functions as a cloud serverto store different copies of the code The utility of 1 is fairly obvious For 2 and 3 without GitHub one mightenvision making a big tarball of edited files and emailing the maintainers for inclusion in the main repository InsteadGitHub effectively does something like this for you in a much more elegant way Note unlike using (linux terminalcommand) git GitHub commands are NOT typed in a terminal but are typically invoked by hitting a button on theweb interface or clicking on a webpage link etc To contribute edits to MITgcm you need to obtain a github accountItrsquos free do this first if you donrsquot have one already

Before you start working with git make sure you identify yourself From your terminal type

git config --global useremail your_emailexampleedu git config --global username lsquoJohn Doersquo

(note the required quotes around your name) You should also personalize your profile associated with your GitHubaccount

There are many online tutorials to using Git and GitHub (see for example httpsakrabatcomthe-beginners-guide-to-contributing-to-a-github-project ) here we are just communicating the basics neces-sary to submit code changes to the MITgcm Spending some time learning the more advanced features of Git willlikely pay off in the long run and not just for MITgcm contributions as you are likely to encounter it in all sorts ofdifferent projects

To better understand this process Figure 51 shows a conceptual map of the Git setup Note three copies of the codethe main MITgcm repository sourcecode ldquoupstreamrdquo (ie owned by the MITgcm maintainers) in the GitHub clouda copy of the repository ldquooriginrdquo owned by you also residing in the GitHub cloud and a local copy on your personalcomputer or compute cluster (where you intend to compile and run) The Git and GitHub commands to create thissetup are explained more fully below

One other aspect of Git that requires some explanation to the uninitiated your local linux copy of the code repositorycan contain different ldquobranchesrdquo each branch being a different copy of the code repository (this can occur in all git-aware directories) When you switch branches basic unix commands such as ls or cat will show a different set offiles specific to current branch In other words Git interacts with your local file system so that edits or newly createdfiles only appear in the current branch ie such changes do not appear in any other branches So if you swore youmade some changes to a particular file and now it appears those changes have vanished first check which branch youare on (git status is a useful command here) all is probably not lost

A detailed explanation of steps for contributing MITgcm repository edits

52 Using Git and Github 139

MITgcmlocal copylocal computer

git clonegit pull git push

git pull upstream

git clone

MITgcmmain repo

MITgcmyour repo

forkldquooriginrdquoldquoupstreamrdquo

pull request

GitHub cloud

Figure 51 A conceptual map of the GitHub setup Git terminal commands are shown in red GitHub commands areshown in green

1 On GitHub create a local copy of the repository in your GitHub cloud user space from the main repository(httpsgithubcomMITgcmMITgcm) hit the Fork button As mentioned your GitHub copy ldquooriginrdquo is necessary tostreamline the collaborative development process ndash you need to create a place for your edits in the GitHub cloud fordevelopers to peruse

2 Download the code onto your local computer using the git clone command Even if you previously downloadedthe code through a ldquogit-awarerdquo method (ie a git clone command see Section 321) we STRONGLY SUGGESTyou download a fresh repository to a separate disk location for your development work (keeping your research workseparate) Type

git clone httpsgithubcomyour_github_user_nameMITgcmgit

from your terminal (technically here you are copying the forked ldquooriginrdquo version from the cloud not the ldquoupstreamrdquoversion but these will be identical at this point)

3 Move into the local clone directory on your computer

cd MITgcm

We need to set up a remote that points to the main repository

This means that we now have two ldquoremotesrdquo of the project A remote is just a pointer to a repository not on yourcomputer ie in the GitHub cloud one pointing to your GitHub user space (ldquooriginrdquo) and this new remote pointingto the original (ldquoupstreamrdquo) You can read and write into your ldquooriginrdquo version (since it belongs to you in the cloud)but not into the ldquoupstreamrdquo version This command just sets up this remote which is needed in step 4 ndash no actual filemanipulation is done at this point If in doubt the command git remote -v will list what remotes have been setup

4 Next make a new branch

You will make edits on this new branch to keep these new edits completely separate from all files on the master branchThe first command git fetch upstreammakes sure your new branch is the latest code from the main repositoryas such you can redo step 4 at any time to start additional separate development projects (on a separate new branch)Note that this second command above not only creates this new branch which we name newfeature from theupstreammaster branch it also switches you onto this newly created branch Naming the branch somethingmore descriptive than lsquonewfeaturersquo is helpful

5 Doing stuff This usually comes in one of three flavors

i) cosmetic changes formatting documentation etcii) fixing bug(s) or any change to the code which results in different numerical output oriii) adding a feature or new package

To do this you should

bull edit the relevant file(s) andor create new files Refer to Coding style guide for details on expected documentationstandards and code style requirements Of course changes should be thoroughly tested to ensure they compileand run successfully

bull type git add ltFILENAME1gt ltFILENAME2gt to stage the file(s) ready for a commit command (noteboth existing and brand new files need to be added) ldquoStagerdquo effectively means to notify Git of the the list of files

you plan to ldquocommitrdquo for changes into the version tracking system Note you can change other files and NOThave them sent to model developers only staged files will be sent You can repeat this git add commandas many times as you like and it will continue to augment the list of files git diff and git status areuseful commands to see what you have done so far

bull use git commit to commit the files This is the first step in bundling a collection of files together to be sentoff to the MITgcm maintainers When you enter this command an editor window will pop up On the top linetype a succinct (lt70 character) summary of what these changes accomplished If your commit is non-trivial andadditional explanation is required leave a blank line and then type a longer description of why the action in thiscommit was appropriate etc It is good practice to link with known issues using the syntax ISSUE_NUMBERin either the summary line or detailed comment Note that all the changes do not have to be handled in a singlecommit (ie you can git add some files do a commit than continue anew by adding different files do anothercommit etc) the git commit command itself does not (yet) submit anything to maintainers

bull if you are fixing a more involved bug or adding a new feature such that many changes are required it ispreferable to break your contribution into multiple commits (each documented separately) rather than submittingone massive commit each commit should encompass a single conceptual change to the code base regardless ofhow many files it touches This will allow the MITgcm maintainers to more easily understand your proposedchanges and will expedite the review process

bull if you make any change to the code however small ie flavor ii or iii above we expect you to add your changesto the top of doctag-index (starting at line 4) which is a running history of all development of the MITgcmAgain be concise describing your changes in one or several lines of text We will not accept code changeswithout this edit

When your changes are tested and documented continue on to step 6 but read all of step 6 and 7 before proceedingyou might want to do an optional ldquobring my development branch up to daterdquo sequence of steps before step 6

6 Now we ldquopushrdquo our modified branch with committed changes onto the origin remote in the GitHub cloud Thiseffectively updates your GitHub cloud copy of the MITgcm repo to reflect the wonderful changes you are contributing

Some time might elapse during step 5 as you make and test your edits during which continuing development occursin the main MITgcm repository In contrast with some models that opt for static major releases the MITgcm is ina constant state of improvement and development It is very possible that some of your edits occur to files that havealso been modified by others in fact it is very likely doctag-index will have been updated in the main repo if even aweek has elapsed Your local clone however will not know anything about any changes that may have occurred to theMITgcm repo in the cloud which may cause an issue in step 7 below when one of three things will occur

bull the files you have modified in your development have NOT been modified in the main repo during this elapsedtime thus git will have no conflicts in trying to update (ie merge) your changes into the main repo

bull during the elapsed time the files you have modified have also been editedupdated in the main repo but youedited different places in these files than those edits to the main repo such that git is smart enough to be able tomerge these edits without conflict

bull during the elapsed time the files you have modified have also been editedupdated in the main repo but git isnot smart enough to know how to deal with this conflict (it will notify you of this problem during step 7)

One option is to NOT attempt to bring your development code branch up to date instead simply proceed with steps6 and 7 and let the maintainers assess and resolve any conflict(s) should such occur (there is a checkbox lsquoAllowedits by maintainersrsquo that is checked by default when you do step 7) If very little time elapsed during step 5 suchconflict is less likely (exception would be to doctag-index which the maintainers can easily resolve) However if step5 takes on the order of months we do suggest you follow this recipe below to update the code and merge yourselfAndor during the development process you might have reasons to bring the latest changes in the main repo into yourdevelopment branch and thus might opt to follow these same steps

Development branch code update recipe

This first command switches you from your development branch to the master branch The second command abovewill synchronize your local master branch with the main MITgcm repository master branch (ie ldquopullrdquo any newchanges that might have occurred in the upstream repository into your local clone) Note you should not have madeany changes to your clonersquos master branch in other words prior to the pull master should be a stagnant copy ofthe code from the day you performed step 1 above The git push command does the opposite of pull so in thethird step you are synchronizing your GitHub cloud copy (ldquooriginrdquo) master branch to your local clonersquos master branch(which you just updated) Then switch back to your development branch via the second git checkout commandFinally the last command will merge any changes into your development branch If conflicts occur that git cannotresolve git will provide you a list of the problematic file names and in these files areas of conflict will be demarcatedYou will need to edit these files at these problem spots (while removing gitrsquos demarcation text) then do a git addFILENAME for each of these files followed by a final git commit to finish off the merger

Some additional git diff commands to help sort out file changes in case you want to assess the scope of devel-opment changes are as follows git diff master upstreammaster will show you all differences betweenyour local master branch and the main MITgcm repo ie so you can peruse what parallel MITgcm changes haveoccurred while you were doing your development (this assumes you have not yet updated your clonersquos master branch)You can check for differences on individual files via git diff master upstreammaster ltFILENAMEgtIf you want to see all differences in files you have modified during your development the command is git diffmaster Similarly to see a combined list of both your changes and those occurring to the main repo git diffupstreammaster

Aside comment if you are familiar with git you might realize there is an alternate way to merge using the ldquorebaserdquosyntax If you know what you are doing feel free to use this command instead of our suggested merge commandabove

7 Finally create a ldquopull requestrdquo (aka ldquoPRrdquo in other words you are requesting that the maintainers pull yourchanges into the main code repository) In GitHub go to the fork of the project that you made (httpsgithubcomyour_github_user_nameMITgcmgit) There is a button for ldquoCompare and Pullrdquo in your newly created branch Clickthe button Now you can add a final succinct summary description of what yoursquove done in your commit(s) and flagup any issues The maintainers will now be notified and be able to peruse your changes In general the maintainerswill try to respond to a new PR within a week While the PR remains open you can go back to step 5 and makeadditional edits git adds git commits and then redo step 6 such changes will be added to the PR (and maintainersre-notified) no need to redo step 7

Your pull request remains open until either the maintainers fully accept and merge your code changes into the mainrepository or decide to reject your changes (occasionally the review team will reject changes that are not sufficientlyaligned with and do not fit with the code structure) But much more likely than the latter you will instead be askedto respond to feedback modify your code changes in some way andor clean up your code to better satisfy our stylerequirements etc and the pull request will remain open instead of outright rejection The review team is alwayshappy to discuss their decisions but wants to avoid people investing extensive effort in code that has a fundamentaldesign flaw

It is possible for other users (besides the maintainers) to examine or even download your pull request see Reviewingpull requests

The current review team is Jean-Michel Campin Ed Doddridge Chris Hill and Oliver Jahn

53 Coding style guide

Detailed instructions or link to be added

531 Automatic testing with Travis-CI

The MITgcm uses the continuous integration service Travis-CI to test code before it is accepted into the repositoryWhen you submit a pull request your contributions will be automatically tested However it is a good idea to testbefore submitting a pull request so that you have time to fix any issues that are identified To do this you will need toactivate Travis-CI for your fork of the repository

54 Contributing to the manual

Whether you are simply correcting typos or describing undocumented packages we welcome all contributions to themanual The following information will help you make sure that your contribution is consistent with the style of theMITgcm documentation (We know that not all of the current documentation follows these guidelines - wersquore workingon it)

The manual is written in rst format which is short for ReStructuredText directives rst offers many wonderful featuresit automatically does much of the formatting for you it is reasonably well documented on the web (eg primersavailable here and here) it can accept raw latex syntax and track equation labelling for you in addition to numerousother useful features On the down side however it can be very fussy about formatting requiring exact spacing andindenting and seemingly innocuous things such as blank spaces at ends of lines can wreak havoc We suggest lookingat the existing rst files in the manual to see exactly how something is formatted along with the syntax guidelinesspecified in this section prior to writing and formatting your own manual text

The manual can be viewed either of two ways interactively (ie web-based) as hosted by read-the-docs (httpsreadthedocsorg) requiring an html format build or downloaded as a pdf file When you have completed yourdocumentation edits you should double check both versions are to your satisfaction particularly noting that figuresizing and placement may be render differently in the pdf build

541 Section headings

bull Chapter headings - these are the main headings with integer numbers - underlined with

bull section headings - headings with number format XY - underlined with ====

bull Subsection headings - headings with number format XYZ - underlined with ---

bull Subsubsection headings - headings with number format XYZA - underlined with +++

bull Paragraph headings - headings with no numbers - underlined with

NB all underlinings should be the same length as the heading If they are too short an error will be produced

542 Internal document references

rst allows internal referencing of figures tables section headings and equations ie clickable links that bring thereader to the respective figure etc in the manual To be referenced a unique label is required To reference figurestables or section headings by number the rst (inline) directive is numref`LABELNAME` For example thissyntax would write out Figure XX on a line (assuming LABELNAME referred to a figure) and when clicked

would relocate your position in the manual to figure XX Section headings can also be referenced so that the name iswritten out instead of the section number instead using this directive ref`LABELNAME`

Equation references have a slightly different inline syntax eq`LABELNAME` will produce a clickable equationnumber reference surrounded by parentheses

For instructions how to assign a label to tables and figures see below To label a section heading labels go above thesection heading they refer to with the format _LABELNAME Note the necessary leading underscore You canalso place a clickable link to any spot in the text (eg mid-section) using this same syntax to make the label andusing the syntax ref`some_text_to_clickon ltLABELNAMEgt` for the link

543 Other embedded links

Hyperlinks to reference a (clickable) URL simply enter the full URL If you want to have a different clickable textlink instead of displaying the full URL the syntax is `clickable_text ltURLgt`_ (the lsquoltrsquo and lsquogtrsquo are literalcharacters and note the trailing underscore)

File references to create a link to pull up MITgcm code (or any file in the repo) in a code browser window the syntaxis filelink`pathfilename` If you want to have a different text link to click on (eg say you didnrsquot wantto display the full path) the syntax is filelink`clickable_text ltpathfilenamegt` (again the lsquoltlsquoand lsquogtrsquo are literal characters) The top directory here is httpsgithubcomMITgcmMITgcm so if for example youwanted to pop open the file dynamicsF from the main model source directory you would specify modelsrcdynamicsF in place of pathfilename

Variable references to create a link to bring up a webpage displaying all MITgcm repo referencesto a particular variable name (for this purpose we are using the LXR Cross Referencer) the syntax isvarlink`name_of_variable`

544 Symbolic Notation

Inline math is done with math`LATEX_HERE`

Separate equations which will be typeset on their own lines are produced with

mathLATEX_HERElabel EQN_LABEL_HERE

Labelled separate equations are assigned an equation number which may be referenced elsewhere in the document(see Section 542) Omitting the label above will still produce an equation on its own line except without anequation label Note that using latex formatting beginaligned endaligned across multiple lines ofequations will not work in conjunction with unique equation labels for each separate line (any embedded formatting ampcharacters will cause errors too) Latex alignment will work however if you assign a single label for the multiple linesof equations

Discuss conversion of tex files

545 Figures

The syntax to insert a figure is as follows

figure pathnamefilenamewidth 80align center

54 Contributing to the manual 145

alt text description of figure herename myfigure

The figure caption goes here as a single line of text

figure The figure file is located in subdirectory pathname above in practice we have located figure files insubdirectories figs off each manual chapter subdirectory The wild-card is used here so that different file formatscan be used in the build process For vector graphic images save a pdf for the pdf build plus a svg file for the htmlbuild For bitmapped images gif png or jpeg formats can be used for both builds no wild-card necessary (seehere for more info on compatible formats)

width used to scale the size of the figure here specified as 80 scaling factor (check sizing in both the pdf andhtml builds as you may need to adjust the figure size within the pdf file independently)

align can be right center or left

name use this name when you refer to the figure in the text ie numref`myfigure`

Note the indentation and line spacing employed above

546 Tables

There are two syntaxes for tables in reStructuredText Grid tables are more flexible but cumbersome to create Simpletables are easy to create but limited (no row spans etc) The raw rst syntax is shown first then the output

Grid Table Example

+------------+------------+-----------+| Header 1 | Header 2 | Header 3 |+============+============+===========+| body row 1 | column 2 | column 3 |+------------+------------+-----------+| body row 2 | Cells may span columns|+------------+------------+-----------+| body row 3 | Cells may | - Cells |+------------+ span rows | - contain || body row 4 | | - blocks |+------------+------------+-----------+

Header 1 Header 2 Header 3body row 1 column 2 column 3body row 2 Cells may span columnsbody row 3 Cells may span rows bull Cells

bull containbull blocksbody row 4

Simple Table Example

===== ===== ======Inputs Output

------------ ------A B A or B

===== ===== ======False False FalseTrue False True

False True TrueTrue True True===== ===== ======

Inputs OutputA B A or BFalse False FalseTrue False TrueFalse True TrueTrue True True

Note that the spacing of your tables in your rst file(s) will not match the generated output rather when you buildthe final output the rst builder (Sphinx) will determine how wide the columns need to be and space them appropriately

547 Other text blocks

To set several lines apart in an whitespace box eg useful for showing lines in from a terminal session rst uses toset off a lsquoliteral blockrsquo For example

unix_command_foo unix_command_fum

(note the would not appear in the output html) A splashier way to outline a block including a box label is toemploy what is termed in rst as an lsquoadmonition blockrsquo In the manual these are used to show calling trees and fordescribing subroutine inputs and outputs An example of a subroutine inputoutput block is as follows

This is an admonition block showing subroutine inout syntax

admonition SUBROUTINE_NAMEclass note

| 1199071198861199031 VAR1 ( WHERE_VAR1_DEFINEDh)| 1199071198861199032 VAR1 ( WHERE_VAR2_DEFINEDh )| 1199071198861199033 VAR1 ( WHERE_VAR3_DEFINEDh )

An example of a subroutine inout admonition box in the documentation is here

An example of a calling tree in the documentation is here

548 Other style conventions

Units should be typeset in normal text with a space between a numeric value and the unit and exponents added withthe sup command

98 ms sup`2`

will produce 98 ms2 If the exponent is negative use two dashes -- to make the minus sign sufficiently long Thebackslash removes the space between the unit and the exponent

Alternatively latex math directives (see above) may also be used to display units using the text syntax todisplay non-italic characters

bull double quotes for inline literal computer command variables syntax etc

bull discuss how to break up sections into smaller files

bull discuss | lines

549 Building the manual

Once yoursquove made your changes to the manual you should build it locally to verify that it works as expected To dothis you will need a working python installation with the following modules installed (use pip install MODULEin the terminal)

bull sphinx

bull sphinxcontrib-bibtex

bull sphinx_rtd_theme

Then run make html in the docs directory

55 Reviewing pull requests

The only people with write access to the main repository are a small number of core MITgcm developers They arethe people that will eventually merge your pull requests However before your PR gets merged it will undergo theautomated testing on Travis-CI and it will be assessed by the MITgcm community

Everyone can review and comment on pull requests Even if you are not one of the core developers you can stillcomment on a pull request

To test pull requests locally you should download the pull request branch You can do this either by cloning the branchfrom the pull request

git clone -b BRANCHNAME httpsgithubcomUSERNAMEMITgcmgit

where USERNAME is replaced by the username of the person proposing the pull request and BRANCHNAME is thebranch from the pull request

Alternatively you can add the repository of the user proposing the pull request as a remote to your existing localrepository Move directories in to your local repository and then

git remote add USERNAME httpsgithubcomUSERNAMEMITgcmgit

where USERNAME is replaced by the user name of the person who has made the pull request Then download thebranch from the pull request

git fetch USERNAME

and switch to the desired branch

git checkout --track USERNAMEfoo

You now have a local copy of the code from the pull request and can run tests locally If you have write access to themain repository you can push fixes or changes directly to the pull request

None of these steps apart from pushing fixes back to the pull request require write access to either the main repositoryor the repository of the person proposing the pull request This means that anyone can review pull requests Howeverunless you are one of the core developers you wonrsquot be able to directly push changes You will instead have to make acomment describing any problems you find

CHAPTER 6

Software Architecture

152 Chapter 6 Software Architecture

CHAPTER 7

Automatic Differentiation

154 Chapter 7 Automatic Differentiation

CHAPTER 8

Packages I - Physical Parameterizations

In this chapter and in the following chapter the MITgcm lsquopackagesrsquo are described While you can carry out manyexperiments with MITgcm by starting from case studies in section refsecmodelExamples configuring a brand newexperiment or making major changes to an experimental configuration requires some knowledge of the packages thatmake up the full MITgcm code Packages are used in MITgcm to help organize and layer various code building blocksthat are assembled and selected to perform a specific experiment Each of the specific experiments described in sectionrefsecmodelExamples uses a particular combination of packages

Figure 81 shows the full set of packages that are available As shown in the figure packages are classified into differentgroupings that layer on top of each other The top layer packages are generally specialized to specific simulation typesIn this layer there are packages that deal with biogeochemical processes ocean interior and boundary layer processesatmospheric processes sea-ice coupled simulations and state estimation Below this layer are a set of general purposenumerical and computational packages The general purpose numerical packages provide code for kernel numericalalgorithms that apply to many different simulation types Similarly the general purpose computational packagesimplement non-numerical algorithms that provide parallelism IO and time-keeping functions that are used in manydifferent scenarios

The following sections describe the packages shown in Figure 81 Section refsecpkgusing describes the generalprocedure for using any package in MITgcm Following that sections refsecpkggad-refsecpkgmonitor layoutthe algorithms implemented in specific packages and describe how to use the individual packages A brief synopsisof the function of each package is given in table reftabpackage_summary_tab Organizationally package code isassigned a separate subdirectory in the MITgcm code distribution (within the source code directory textttpkg) Thename of this subdirectory is used as the package name in table reftabpackage_summary_tab

81 Overview

811 Using MITgcm Packages

The set of packages that will be used within a partiucular model can be configured using a combination of bothldquocompilendashtimerdquo and ldquorunndashtimerdquo options Compilendashtime options are those used to select which packages will be

Figure 81 Hierarchy of code layers that are assembled to make up an MITgcm simulation Conceptually (and interms of code organization) MITgcm consists of several layers At the base is a layer of core software that providesa basic numerical and computational foundation for MITgcm simulations This layer is shown marked FoundationCode at the bottom of the figure and corresponds to code in the italicised subdirectories on the figure This layeris not organized into packages All code above the foundation layer is organized as packages Much of the codein MITgcm is contained in packages which serve as a useful way of organizing and layering the different levels offunctionality that make up the full MITgcm software distribution The figure shows the different packages in MITgcmas boxes containing bold face upper case names Directly above the foundation layer are two layers of general purposeinfrastructure software that consist of computational and numerical packages These general purpose packages can beapplied to both online and offline simulations and are used in many different physical simulation types Above theselayers are more specialized packages

156 Chapter 8 Packages I - Physical Parameterizations

ldquocompiled inrdquo or implemented within the program Packages excluded at compile time are completely absent from theexecutable program(s) and thus cannot be later activated by any set of subsequent runndashtime options

8111 Package InclusionExclusion

There are numerous ways that one can specify compilendashtime package inclusion or exclusion and they are all imple-mented by the genmake2 program which was previously described in Section [secbuildingCode] The options areas follows

1 Setting the genamake2 options -enable PKG andor -disable PKG specifies inclusion or exclusionThis method is intended as a convenient way to perform a single (perhaps for a quick test) compilation

2 By creating a text file with the name packagesconf in either the local build directory or the -mods=DIRdirectory one can specify a list of packages (one package per line with rsquorsquo as the comment character) to beincluded Since the packagesconf file can be saved this is the preferred method for setting and recording(for future reference) the package configuration

3 For convenience a list of ldquostandardrdquo package groups is contained in the pkgpkg_groups file By selectingone of the package group names in the packagesconf file one automatically obtains all packages in thatgroup

4 By default (that is if a packagesconf file is not found) the genmake2 program will use the packagegroup default ldquodefault_pkg_listrdquo as defined in pkgpkg_groups file

5 To help prevent users from creating unusable package groups the genmake2 program will parse the contentsof the pkgpkg_depend file to determine

bull whether any two requested packages cannot be simultaneously included (eg seaice and thsice are mutuallyexclusive)

bull whether additional packages must be included in order to satisfy package dependencies (eg rw dependsupon functionality within the mdsio package) and

bull whether the set of all requested packages is compatible with the dependencies (and producing an error ifthey arenrsquot)

Thus as a result of the dependencies additional packages may be added to those originally requested

8112 Package Activation

For runndashtime package control MITgcm uses flags set through a datapkg file While some packages (eg debugmnc exch2) may have their own usage conventions most follow a simple flag naming convention of the form

usePackageName=TRUE

where the usePackageName variable can activate or disable the package at runtime As mentioned previouslypackages must be included in order to be activated Generally such mistakes will be detected and reported as errorsby the code However users should still be aware of the dependency

8113 Package Coding Standards

The following sections describe how to modify andor create new MITgcm packages

81 Overview 157

Packages are Not Libraries

To a beginner the MITgcm packages may resemble libraries as used in myriad software projects While futureversions are likely to implement packages as libraries (perhaps using FORTRAN9095 syntax) the current packages(FORTRAN77) are not based upon any concept of libraries

File Inclusion Rules

Instead packages should be viewed only as directories containing ldquosets of source filesrdquo that are built using somesimple mechanisms provided by genmake2 Conceptually the build process adds files as they are found and proceedsaccording to the following rules

1 genmake2 locates a ldquocorerdquo or main set of source files (the -standarddirs option sets these locations andthe default value contains the directories eesupp and model)

2 genmake2 then finds additional source files by inspecting the contents of each of the package directories

(a) As the new files are found they are added to a list of source files

(b) If there is a file name ldquocollisionrdquo (that is if one of the files in a package has the same name as one of thefiles previously encountered) then the file within the newer (more recently visited) package will superseed(or ldquohiderdquo) any previous file(s) with the same name

(c) Packages are visited (and thus files discovered) in the order that the packages are enabled withingenmake2 Thus the files in PackB may superseed the files in PackA if PackA is enabled beforePackB Thus package ordering can be significant For this reason genmake2 honors the order in whichpackages are specified

These rules were adopted since they provide a relatively simple means for rapidly including (or ldquohidingrdquo) existing fileswith modified versions

Conditional Compilation and PACKAGES_CONFIGh

Given that packages are simply groups of files that may be added or removed to form a whole one may wonderhow linking (that is FORTRAN symbol resolution) is handled This is the second way that genmake2 supportsthe concept of packages Basically genmake2 creates a Makefile that in turn is able to create a file calledPACKAGES_CONFIGh that contains a set of C pre-processor (or ldquoCPPrdquo) directives such as

undef ALLOW_KPPundef ALLOW_LANDdefine ALLOW_GENERIC_ADVDIFFdefine ALLOW_MDSIO

These CPP symbols are then used throughout the code to conditionally isolate variable definitions function calls orany other code that depends upon the presence or absence of any particular package

An example illustrating the use of these defines is

ifdef ALLOW_GMREDIIF (useGMRedi) CALL GMREDI_CALC_DIFF(

I bibjiMiniMaxjMinjMaxKI maskUpO KappaRTKappaRS

I myThid)endif

which is included from the file and shows how both the compilendashtime ALLOW_GMREDI flag and the runndashtimeuseGMRedi are nested

There are some benefits to using the technique described here The first is that code snippets or subroutines associatedwith packages can be placed or called from almost anywhere else within the code The second benefit is related tomemory footprint and performance Since unused code can be removed there is no performance penalty due to unnec-essary memory allocation unused function calls or extra run-time IF () conditions The major problems withthis approach are the potentially difficult-to-read and difficult-to-debug code caused by an overuse of CPP statementsSo while it can be done developers should exerecise some discipline and avoid unnecesarily ldquosmearingrdquo their packageimplementation details across numerous files

Package Startup or Boot Sequence

Calls to package routines within the core code timestepping loop can vary However all packages should follow arequired ldquobootrdquo sequence outlined here

1 SR PACKAGES_BOOT()

CALL OPEN_COPY_DATA_FILE( datapkg PACKAGES_BOOT )

2 SR PACKAGES_READPARMS()

ifdef ALLOW_$PKGif ( use$Pkg )

amp CALL $PKG_READPARMS( retCode )endif

3 SR PACKAGES_INIT_FIXED()

amp CALL $PKG_INIT_FIXED( retCode )endif

4 SR PACKAGES_CHECK()

amp CALL $PKG_CHECK( retCode )else

if ( use$Pkg )amp CALL PACKAGES_CHECK_ERROR($PKG)

5 SR PACKAGES_INIT_VARIABLES()

amp CALL $PKG_INIT_VARIA( )endif

81 Overview 159

6 SR DO_THE_MODEL_IO

amp CALL $PKG_OUTPUT( )endif

7 SR PACKAGES_WRITE_PICKUP()

amp CALL $PKG_WRITE_PICKUP( )endif

Adding a package to PARAMSh and packages_boot()

An MITgcm package directory contains all the code needed for that package apart from one variable for each packageThis variable is the use$Pkg flag This flag which is of type logical must be declared in the shared header filePARAMSh in the PARM_PACKAGES block This convention is used to support a single runtime control file datapkgwhich is read by the startup routine packages_boot() and that sets a flag controlling the runtime use of a package Thisroutine needs to be able to read the flags for packages that were not built at compile time Therefore when adding a newpackage in addition to creating the per-package directory in the pkg subdirectory a developer should add a use$Pkg flag to PARAMSh and a use$Pkg entry to the packages_boot() PACKAGES namelist The only other packagespecific code that should appear outside the individual package directory are calls to the specific package API

82 Packages Related to Hydrodynamical Kernel

821 Generic AdvectionDiffusion

The generic_advdiff package contains high-level subroutines to solve the advection-diffusion equation of any tracereither active (potential temperature salinity or water vapor) or passive (see pkgptracers) (see also sections[sectracersubequations] to [sectracersubadvectionschemes])

8211 Introduction

Package ldquogeneric_advdiffrdquo provides a common set of routines for calculating advectivediffusive fluxes for tracers(cell centered quantities on a C-grid)

Many different advection schemes are available the standard centered second order centered fourth order and upwindbiased third order schemes are known as linear methods and require some stable time-stepping method such as Adams-Bashforth Alternatives such as flux-limited schemes are stable in the forward sense and are best combined with themulti-dimensional method provided in gad_advection

8212 Key subroutines parameters and files

There are two high-level routines

bull GAD_CALC_RHS calculates all fluxes at time level ldquonrdquo and is used for the standard linear schemes This mustbe used in conjuction with AdamsndashBashforth time stepping Diffusive and parameterized fluxes are alwayscalculated here

bull GAD_ADVECTION calculates just the advective fluxes using the non-linear schemes and can not be used inconjuction with AdamsndashBashforth time stepping

8213 GAD Diagnostics

8214 Experiments and tutorials that use GAD

bull Offline tutorial in tutorial_offline verification directory described in section [seceg-offline]

bull Baroclinic gyre experiment in tutorial_baroclinic_gyre verification directory described in section [seceg-fourlayer]

bull Tracer Sensitivity tutorial in tutorial_tracer_adjsens verification directory described in section [seceg-simple-tracer-adjoint]

822 Shapiro Filter

(in directory pkgshap_filt)

Implementation of filter is described in section [secshapiro-filter]

8222 Experiments and tutorials that use shap filter

bull Held Suarez tutorial in tutorial_held_suarez_cs verification directory described in section [seceg-hs]

82 Packages Related to Hydrodynamical Kernel 161

bull other Held Suarez verification experiments (hs94128x64x5 hs941x64x5 hs94cs-32x32x5)

bull AIM verification experiments (aim5l_cs aim5l_Equatorial_Channel aim5l_LatLon)

bull fizhi verification experiments (fizhi-cs-32x32x40 fizhi-cs-aqualev20 fizhi-gridalt-hs)

823 FFT Filtering Code

(in directory pkgzonal_filt)

8232 Experiments and tutorials that use zonal filter

bull Held Suarez verification experiment (hs94128x64x5)

bull AIM verification experiment (aim5l_LatLon)

824 exch2 Extended Cubed Sphere Topology

8241 Introduction

The exch2 package extends the original cubed sphere topology configuration to allow more flexible domain decom-position and parallelization Cube faces (also called subdomains) may be divided into any number of tiles that divideevenly into the grid point dimensions of the subdomain Furthermore the tiles can run on separate processors indi-vidually or in groups which provides for manual compile-time load balancing across a relatively arbitrary number ofprocessors

The exchange parameters are declared in pkgexch2W2_EXCH2_TOPOLOGYh and assigned in pkgexch2w2_e2setupF The validity of the cube topology depends on the SIZEh file as detailed below Thedefault files provided in the release configure a cubed sphere topology of six tiles one per subdomain each with 32times 32 grid points with all tiles running on a single processor Both files are generated by Matlab scripts in utilsexch2matlab-topology-generator see Section refsectopogen for details on creating alternate topolo-gies Pregenerated examples of these files with alternate topologies are provided under utilsexch2code-modsalong with the appropriate SIZEh file for single-processor execution

8242 Invoking exch2

To use exch2 with the cubed sphere the following conditions must be met

bull The exch2 package is included when genmake2 is run The easiest way to do this is to add the line codeexch2to the packagesconf file ndash see Section refsecbuildingCode sectiontitleBuilding the code for generaldetails

bull An example of W2_EXCH2_TOPOLOGYh and w2_e2setupF must reside in a directory containingfiles symbolically linked by the genmake2 script The safest place to put these is the directory indicated in the-mods=DIR command line modifier (typically code) or the build directory The default versions of thesefiles reside in pkgexch2 and are linked automatically if no other versions exist elsewhere in the build pathbut they should be left untouched to avoid breaking configurations other than the one you intend to modify

bull Files containing grid parameters named tile00$n$mitgrid where n=(16) (one per subdomain) mustbe in the working directory when the MITgcm executable is run These files are provided in the exampleexperiments for cubed sphere configurations with 32 times 32 cube sides ndash please contact MITgcm support if youwant to generate files for other configurations

bull As always when compiling MITgcm the file SIZEh must be placed where genmake2 will find it In par-ticular for exch2 the domain decomposition specified in SIZEh must correspond with the particular config-urationrsquos topology specified in W2_EXCH2_TOPOLOGYh and w2_e2setupF Domain decompositionissues particular to exch2 are addressed in Section refsectopogen sectiontitleGenerating Topology Filesfor exch2 and refsecexch2mpi sectiontitleexch2 SIZEh and Multiprocessing a more general back-ground on the subject relevant to MITgcm is presented in Section refsecspecifying_a_decomposition sec-tiontitleSpecifying a decomposition

At the time of this writing the following examples use exch2 and may be used for guidance

bull verificationadjust_nlfscs-32x32x1

bull verificationadjustmentcs-32x32x1

bull verificationaim5l_cs

bull verificationglobal_oceancs32x15

bull verificationhs94cs-32x32x5

8243 Generating Topology Files for exch2

Alternate cubed sphere topologies may be created using the Matlab scriptsin utilsexch2matlab-topology-generator Running the m-fileutils-exch2-matlab-topology-generator_driverm from the Matlab prompt (there are no pa-rameters to pass) generates exch2 topology files W2_EXCH2_TOPOLOGYh and w2_e2setupF in theworking directory and displays a figure of the topology via Matlab ndash figures reffig6tile reffig18tile andreffig48tile are examples of the generated diagrams The other m-files in the directory are subroutines called fromdriverm and should not be run lsquorsquobarerdquo except for development purposes

The parameters that determine the dimensions and topology of the generated configuration are nr nb ng tnx andtny and all are assigned early in the script

The first three determine the height and width of the subdomains and hence the size of the overall domain Eachone determines the number of grid points and therefore the resolution along the subdomain sides in a lsquorsquogreat circlerdquoaround each the three spatial axes of the cube At the time of this writing MITgcm requires these three parameters tobe equal but they provide for future releases to accomodate different resolutions around the axes to allow subdomainswith differing resolutions

The parameters tnx and tny determine the width and height of the tiles into which the subdomains are decomposedand must evenly divide the integer assigned to nr nb and ng The result is a rectangular tiling of the subdomainFigure 82 shows one possible topology for a twenty-four-tile cube and Figure 84 shows one for six tiles

Tiles can be selected from the topology to be omitted from being allocated memory and processors This tuningis useful in ocean modeling for omitting tiles that fall entirely on land The tiles omitted are specified in the fileblanklisttxt by their tile number in the topology separated by a newline

8244 exch2 SIZEh and Multiprocessing

Once the topology configuration files are created each Fortran PARAMETER in SIZEh must be configured to matchSection refsecspecifying_a_decomposition sectiontitleSpecifying a decomposition provides a general descriptionof domain decomposition within MITgcm and its relation to fileSIZEh The current section specifies constraintsthat the exch2 package imposes and describes how to enable parallel execution with MPI

As in the general case the parameters varlinksNxsNx and varlinksNysNy define the size of the individualtiles and so must be assigned the same respective values as codetnx and codetny in filedriverm

0 20 40 60 80 100 120 1400

t1f5n f6nt2f6n

t3f5n t4 f2w

t5f5n t6 f2w

f3wt8f3w f2w

t9f1e f6et10f6e

t11f1e t12 f4s

t13f1e t14 f4s

t15f1e

f3st16f3s f4s

t17f1n f2nt18f2n

t19f1n t20 f4w

t21f1n t22 f4w

t23f1n

f5wt24f5w f4w

t25f3e f2et26f2e

t27f3e t28 f6s

t29f3e t30 f6s

t31f3e

f5st32f5s f6s

t33f3n f4nt34f4n

t35f3n t36 f6w

t37f3n t38 f6w

t39f3n

f1wt40f1w f6w

t41f5e f4et42f4e

t43f5e t44 f2s

t45f5e t46 f2s

t47f5e

f1st48f1s f2s

Figure 82 Plot of a cubed sphere topology with a 32 times 192 domain divided into six 32 times 32 subdomains each ofwhich is divided into eight tiles of width tnx=16 and height tny=8 for a total of forty-eight tiles The colored bordersof the subdomains represent the parameters nr (red) ng (green) and nb (blue) This tiling is used in the exampleverificationadjustmentcs-32x32x1 with the option (blanklisttxt) to remove the land-only 4 tiles (11121314) whichare filled in red on the plot

0 100 200 300 400 500 600 7000

t2f5n f2w

t3f5n f2w

t6f1e f4s

t7f1e f4s

f3t9f1n

f4w f4t10f3e

f5t14f3n

f6w f6t18f5e

Figure 83 Plot of a non-square cubed sphere topology with 6 subdomains of different size (nr=90ng=360nb=90)divided into one to four tiles each (tnx=90 tny=90) resulting in a total of 18 tiles

0 20 40 60 80 100 120 1400

f1 t1f5n

f2w f2 t2f1e

f3 t3f1n

f4w f4 t4f3e

f5 t5f3n

f6w f6 t6f5e

Figure 84 Plot of a cubed sphere topology with a 32 times 192 domain divided into six 32 times 32 subdomains with onetile each (tnx=32 tny=32) This is the default configuration

The halo width parameters varlinkOLxOLx and varlinkOLyOLy have no special bearing on exch2 and maybe assigned as in the general case The same holds for varlinkNrNr the number of vertical levels in the model

The parameters varlinknSxnSx varlinknSynSy varlinknPxnPx and varlinknPynPy relate to thenumber of tiles and how they are distributed on processors When using exch2 the tiles are stored in the $x$ dimensionand so codevarlinknSynSy=1 in all cases Since the tiles as configured by exch2 cannot be split up accrossprocessors without regenerating the topology codevarlinknPynPy=1 as well

The number of tiles MITgcm allocates and how they are distributed between processors depends on var-linknPxnPx and varlinknSxnSx varlinknSxnSx is the number of tiles per processor and var-linknPxnPx is the number of processors The total number of tiles in the topology minus those listed infileblanklisttxt must equal codenSxnPx Note that in order to obtain maximum usage from a given numberof processors in some cases this restriction might entail sharing a processor with a tile that would otherwise be ex-cluded because it is topographically outside of the domain and therefore in fileblanklisttxt For example supposeyou have five processors and a domain decomposition of thirty-six tiles that allows you to exclude seven tiles Toevenly distribute the remaining twenty-nine tiles among five processors you would have to run one lsquorsquodummyrdquo tile tomake an even six tiles per processor Such dummy tiles are emphnot listed in fileblanklisttxt

The following is an example of fileSIZEh for the six-tile configuration illustrated in figure reffig6tile running onone processor

PARAMETER (amp sNx = 32amp sNy = 32amp OLx = 2amp OLy = 2amp nSx = 6amp nSy = 1amp nPx = 1

amp nPy = 1amp Nx = sNxnSxnPxamp Ny = sNynSynPyamp Nr = 5)

The following is an example for the forty-eight-tile topology in figure reffig48tile running on six processors

PARAMETER (amp sNx = 16amp sNy = 8amp OLx = 2amp OLy = 2amp nSx = 8amp nSy = 1amp nPx = 6amp nPy = 1amp Nx = sNxnSxnPxamp Ny = sNynSynPyamp Nr = 5)

8245 Key Variables

The descriptions of the variables are divided up into scalars one-dimensional arrays indexed to the tile number andtwo and three-dimensional arrays indexed to tile number and neighboring tile This division reflects the functionalityof these variables The scalars are common to every part of the topology the tile-indexed arrays to individual tilesand the arrays indexed by tile and neighbor to relationships between tiles and their neighbors

Scalars

The number of tiles in a particular topology is set with the parameter codeNTILES and the maximum number ofneighbors of any tiles by codeMAX_NEIGHBOURS These parameters are used for defining the size of the variousone and two dimensional arrays that store tile parameters indexed to the tile number and are assigned in the filesgenerated by filedriverm

The scalar parameters varlinkexch2_domain_nxtexch2_domain_nxt and var-linkexch2_domain_nytexch2_domain_nyt express the number of tiles in the $x$ and $y$ global in-dices For example the default setup of six tiles (Fig reffig6tile) has codeexch2_domain_nxt=6 andcodeexch2_domain_nyt=1 A topology of forty-eight tiles eight per subdomain (as in figure reffig48tile) willhave codeexch2_domain_nxt=12 and codeexch2_domain_nyt=4 Note that these parameters express the tilelayout in order to allow global data files that are tile-layout-neutral They have no bearing on the internal storage ofthe arrays The tiles are stored internally in a range from codevarlinkbibi=(1NTILES) in the $x$ axis and the$y$ axis variable varlinkbjbj is assumed to equal code1 throughout the package

Arrays indexed to tile number

The following arrays are of length codeNTILES and are indexed to the tile number which is indicated in thediagrams with the notation textsft$n$ The indices are omitted in the descriptions

The arrays varlinkexch2_tnxexch2_tnx and varlinkexch2_tnyexch2_tny express the $x$ and $y$ dimensionsof each tile At present for each tile textttexch2_tnx=sNx and textttexch2_tny=sNy as assigned in fileSIZEhand described in Section refsecexch2mpi sectiontitleexch2 SIZEh and Multiprocessing Future releases ofMITgcm may allow varying tile sizes

The arrays varlinkexch2_tbasexexch2_tbasex and varlinkexch2_tbaseyexch2_tbasey determine the tilesrsquoCartesian origin within a subdomain and locate the edges of different tiles relative to each other As an examplein the default six-tile topology (Fig reffig6tile) each index in these arrays is set to code0 since a tile occupies itsentire subdomain The twenty-four-tile case discussed above will have values of code0 or code16 depending on

the quadrant of the tile within the subdomain The elements of the arrays varlinkexch2_txglobaloexch2_txglobaloand varlinkexch2_txglobaloexch2_txglobalo are similar to varlinkexch2_tbasexexch2_tbasex and var-linkexch2_tbaseyexch2_tbasey but locate the tile edges within the global address space similar to that usedby global output and input files

The array varlinkexch2_myFaceexch2_myFace contains the number of the subdomain of each tile in a rangecode(16) in the case of the standard cube topology and indicated by textbftextsff$n$ in figures reffig6tileand reffig48tile varlinkexch2_nNeighboursexch2_nNeighbours contains a count of the neighboring tiles eachtile has and sets the bounds for looping over neighboring tiles varlinkexch2_tProcexch2_tProc holds the processrank of each tile and is used in interprocess communication

The arrays varlinkexch2_isWedgeexch2_isWedge varlinkexch2_isEedgeexch2_isEedge var-linkexch2_isSedgeexch2_isSedge and varlinkexch2_isNedgeexch2_isNedge are set to code1 if theindexed tile lies on the edge of its subdomain code0 if not The values are used within the topology generator todetermine the orientation of neighboring tiles and to indicate whether a tile lies on the corner of a subdomain Thelatter case requires special exchange and numerical handling for the singularities at the eight corners of the cube

Arrays Indexed to Tile Number and Neighbor

The following arrays have vectors of length codeMAX_NEIGHBOURS and codeNTILES and describe the ori-entations between the the tiles

The array codeexch2_neighbourId(aT) holds the tile number codeTn for each of the tile number codeTrsquosneighboring tiles codea The neighbor tiles are indexed code(1exch2_nNeighbours(T)) in the order right to lefton the north then south edges and then top to bottom on the east then west edges

The codeexch2_opposingSend_record(aT) array holds the index codeb of the element intextttexch2_neighbourId(bTn) that holds the tile number codeT given codeTn=exch2_neighborId(aT)In other words

exch2_neighbourId( exch2_opposingSend_record(aT)exch2_neighbourId(aT) ) = T

This provides a back-reference from the neighbor tiles

The arrays varlinkexch2_piexch2_pi and varlinkexch2_pjexch2_pj specify the transformations of indices inexchanges between the neighboring tiles These transformations are necessary in exchanges between subdomainsbecause a horizontal dimension in one subdomain may map to other horizonal dimension in an adjacent subdomainand may also have its indexing reversed This swapping arises from the lsquorsquofoldingrdquo of two-dimensional arrays into athree-dimensional cube

The dimensions of codeexch2_pi(tNT) and codeexch2_pj(tNT) are the neighbor ID codeN and the tile num-ber codeT as explained above plus a vector of length code2 containing transformation factors codet The firstelement of the transformation vector holds the factor to multiply the index in the same dimension and the secondelement holds the the same for the orthogonal dimension To clarify codeexch2_pi(1NT) holds the mapping of the$x$ axis index of tile codeT to the $x$ axis of tile codeTrsquos neighbor codeN and codeexch2_pi(2NT) holdsthe mapping of codeTrsquos $x$ index to the neighbor codeNrsquos $y$ index

One of the two elements of codeexch2_pi or codeexch2_pj for a given tile codeT and neighbor codeN willbe code0 reflecting the fact that the two axes are orthogonal The other element will be code1 or code-1depending on whether the axes are indexed in the same or opposite directions For example the transform vector ofthe arrays for all tile neighbors on the same subdomain will be code(10) since all tiles on the same subdomain areoriented identically An axis that corresponds to the orthogonal dimension with the same index direction in a particulartile-neighbor orientation will have code(01) Those with the opposite index direction will have code(0-1) in orderto reverse the ordering

The arrays varlinkexch2_oiexch2_oi varlinkexch2_ojexch2_oj varlinkexch2_oi_fexch2_oi_f and var-linkexch2_oj_fexch2_oj_f are indexed to tile number and neighbor and specify the relative offset within the

subdomain of the array index of a variable going from a neighboring tile codeN to a local tile codeT ConsidercodeT=1 in the six-tile topology (Fig reffig6tile) where

exch2_oi(11)=33exch2_oi(21)=0exch2_oi(31)=32exch2_oi(41)=-32

The simplest case is codeexch2_oi(21) the southern neighbor which is codeTn=6 The axes of codeT andcodeTn have the same orientation and their $x$ axes have the same origin and so an exchange between the tworequires no changes to the $x$ index For the western neighbor (codeTn=5) codecode_oi(31)=32 since thecodex=0 vector on codeT corresponds to the codey=32 vector on codeTn The eastern edge of codeTshows the reverse case (codeexch2_oi(41)=-32)) where codex=32 on codeT exchanges with codex=0 oncodeTn=2

The most interesting case where codeexch2_oi(11)=33 and codeTn=3 involves a reversal of indices As in everycase the offset codeexch2_oi is added to the original $x$ index of codeT multiplied by the transformation factorcodeexch2_pi(tNT) Here codeexch2_pi(111)=0 since the $x$ axis of codeT is orthogonal to the $x$ axis ofcodeTn codeexch2_pi(211)=-1 since the $x$ axis of codeT corresponds to the $y$ axis of codeTn but theindex is reversed The result is that the index of the northern edge of codeT which runs code(132) is transformedto code(-1-32) codeexch2_oi(11) is then added to this range to get back code(321) ndash the index of the $y$axis of codeTn relative to codeT This transformation may seem overly convoluted for the six-tile case but it isnecessary to provide a general solution for various topologies

Finally varlinkexch2_itlo_cexch2_itlo_c varlinkexch2_ithi_cexch2_ithi_c var-linkexch2_jtlo_cexch2_jtlo_c and varlinkexch2_jthi_cexch2_jthi_c hold the location and index bounds ofthe edge segment of the neighbor tile codeNrsquos subdomain that gets exchanged with the local tile codeT To takethe example of tile codeT=2 in the forty-eight-tile topology (Fig reffig48tile)

exch2_itlo_c(42)=17exch2_ithi_c(42)=17exch2_jtlo_c(42)=0exch2_jthi_c(42)=33

Here codeN=4 indicating the western neighbor which is codeTn=1 codeTn resides on the same subdomainas codeT so the tiles have the same orientation and the same $x$ and $y$ axes The $x$ axis is orthogonal tothe western edge and the tile is 16 points wide so codeexch2_itlo_c and codeexch2_ithi_c indicate the columnbeyond codeTnrsquos eastern edge in that tilersquos halo region Since the border of the tiles extends through the entire heightof the subdomain the $y$ axis bounds codeexch2_jtlo_c to codeexch2_jthi_c cover the height of code(132)plus 1 in either direction to cover part of the halo

For the north edge of the same tile codeT=2 where codeN=1 and the neighbor tile is codeTn=5

codeTrsquos northern edge is parallel to the $x$ axis but since codeTnrsquos $y$ axis corresponds to codeTrsquos $x$axis codeTrsquos northern edge exchanges with codeTnrsquos western edge The western edge of the tiles correspondsto the lower bound of the $x$ axis so codeexch2_itlo_c and codeexch2_ithi_c are code0 in the western haloregion of codeTn The range of codeexch2_jtlo_c and codeexch2_jthi_c correspond to the width of codeTrsquosnorthern edge expanded by one into the halo

8246 Key Routines

Most of the subroutines particular to exch2 handle the exchanges themselves and are of the same format as thosedescribed in refseccube_sphere_communication sectiontitleCube sphere communication Like the original rou-tines they are written as templates which the local Makefile converts from codeRX into codeRL and codeRSforms

The interfaces with the core model subroutines are codeEXCH_UV_XY_RX codeEXCH_UV_XYZ_RXand codeEXCH_XY_RX They override the standard exchange routines when codegenmake2 is runwith codeexch2 option They in turn call the local exch2 subroutines codeEXCH2_UV_XY_RX andcodeEXCH2_UV_XYZ_RX for two and three-dimensional vector quantities and codeEXCH2_XY_RX andcodeEXCH2_XYZ_RX for two and three-dimensional scalar quantities These subroutines set the dimensions ofthe area to be exchanged call codeEXCH2_RX1_CUBE for scalars and codeEXCH2_RX2_CUBE for vectorsand then handle the singularities at the cube corners

The separate scalar and vector forms of codeEXCH2_RX1_CUBE and codeEXCH2_RX2_CUBE reflect that thevector-handling subroutine needs to pass both the $u$ and $v$ components of the physical vectors This swappingarises from the topological folding discussed above where the $x$ and $y$ axes get swapped in some cases and is notan issue with the scalar case These subroutines call codeEXCH2_SEND_RX1 and codeEXCH2_SEND_RX2which do most of the work using the variables discussed above

8247 Experiments and tutorials that use exch2

bull Held Suarez tutorial in tutorial_held_suarez_cs verification directory described in section refseceg-hs

825 Gridalt - Alternate Grid Package

8251 Introduction

The gridalt package [Mol09] is designed to allow different components of MITgcm to be run using horizontal andorvertical grids which are different from the main model grid The gridalt routines handle the definition of the allthe various alternative grid(s) and the mappings between them and the MITgcm grid The implementation of thegridalt package which allows the high end atmospheric physics (fizhi) to be run on a high resolution and quasi terrain-following vertical grid is documented here The package has also (with some user modifications) been used for othercalculations within the GCM

The rationale for implementing the atmospheric physics on a high resolution vertical grid involves the fact that theMITgcm 119901 (or any pressure-type) coordinate cannot maintain the vertical resolution near the surface as the bottomtopography rises above sea level The vertical length scales near the ground are small and can vary on small time scalesand the vertical grid must be adequate to resolve them Many studies with both regional and global atmospheric modelshave demonstrated the improvements in the simulations when the vertical resolution near the surface is increased ()Some of the benefit of increased resolution near the surface is realized by employing the higher resolution for thecomputation of the forcing due to turbulent and convective processes in the atmosphere

The parameterizations of atmospheric subgrid scale processes are all essentially one-dimensional in nature and thecomputation of the terms in the equations of motion due to these processes can be performed for the air column overone grid point at a time The vertical grid on which these computations take place can therefore be entirely independantof the grid on which the equations of motion are integrated and the rsquotendencyrsquo terms can be interpolated to the verticalgrid on which the equations of motion are integrated A modified 119901 coordinate which adjusts to the local terrainand adds additional levels between the lower levels of the existing 119901 grid (and perhaps between the levels near thetropopause as well) is implemented The vertical discretization is different for each grid point although it consist ofthe same number of levels Additional rsquospongersquo levels aloft are added when needed The levels of the physics grid areconstrained to fit exactly into the existing 119901 grid simplifying the mapping between the two vertical coordinates Thisis illustrated as follows

Figure 85 Vertical discretization for MITgcm (dark grey lines) and for the atmospheric physics (light grey lines) Inthis implementation all MITgcm level interfaces must coincide with atmospheric physics level interfaces

The algorithm presented here retains the state variables on the high resolution rsquophysicsrsquo grid as well as on the coarserresolution rsquodynamicslsquo grid and ensures that the two estimates of the state rsquoagreersquo on the coarse resolution grid Itwould have been possible to implement a technique in which the tendencies due to atmospheric physics are computedon the high resolution grid and the state variables are retained at low resolution only This however for the case of theturbulence parameterization would mean that the turbulent kinetic energy source terms and all the turbulence termsthat are written in terms of gradients of the mean flow cannot really be computed making use of the fine structure inthe vertical

8252 Equations on Both Grids

In addition to computing the physical forcing terms of the momentum thermodynamic and humidity equations on themodified (higher resolution) grid the higher resolution structure of the atmosphere (the boundary layer) is retainedbetween physics calculations This neccessitates a second set of evolution equations for the atmospheric state variableson the modified grid If the equation for the evolution of 119880 on 119901 can be expressed as

120597119880

120597119905

119905119900119905119886119897119901

=120597119880

120597119905

119889119910119899119886119898119894119888119904

119901+120597119880

120597119905

119901ℎ119910119904119894119888119904119901

where the physics forcing terms on 119901 have been mapped from the modified grid then an additional equation to governthe evolution of 119880 (for example) on the modified grid is written

120597119880

120597119905

119905119900119905119886119897119901119898

=120597119880

120597119905

119889119910119899119886119898119894119888119904

119901119898+120597119880

120597119905

119901ℎ119910119904119894119888119904119901119898

+ 120574(119880 |119901 minus 119880 |119901119898)

where 119901119898 refers to the modified higher resolution grid and the dynamics forcing terms have been mapped from 119901

space The last term on the RHS is a relaxation term meant to constrain the state variables on the modified vertical

grid to lsquotrackrsquo the state variables on the 119901 grid on some time scale governed by 120574 In the present implementation120574 = 1 requiring an immediate agreement between the two rsquostatesrsquo

8253 Time stepping Sequence

If we write 119879119901ℎ119910119904 as the temperature (or any other state variable) on the high resolution physics grid and 119879119889119910119899 as thetemperature on the coarse vertical resolution dynamics grid then

1 Compute the tendency due to physics processes

2 Advance the physics state 119879119899+1119901ℎ119910119904(119897) = 119879119899

119901ℎ119910119904(119897) + 120575119879119901ℎ119910119904

3 Interpolate the physics tendency to the dynamics grid and advance the dynamics state by physics and dynamicstendencies 119879119899+1

119889119910119899(119871) = 119879119899119889119910119899(119871) + 120575119879119889119910119899(119871) + [120575119879119901ℎ119910119904(119897)](119871)

4 Interpolate the dynamics tendency to the physics grid and update the physics grid due to dynamics tendencies119879119899+1

119901ℎ119910119904(119897) = 119879119899+1119901ℎ119910119904(119897) + 120575119879119889119910119899(119871)(119897)

5 Apply correction term to physics state to account for divergence from dynamics state 119879119899+1119901ℎ119910119904(119897) =

119879119899+1119901ℎ119910119904(119897) + 120574119879119889119910119899(119871) minus [119879119901ℎ119910119904(119897)](119871)(119897) Where 120574 = 1 here

8254 Interpolation

In order to minimize the correction terms for the state variables on the alternative higher resolution grid the verticalinterpolation scheme must be constructed so that a dynamics-to-physics interpolation can be exactly reversed with aphysics-to-dynamics mapping The simple scheme employed to achieve this is

Coarse to fineFor all physics layers l in dynamics layer L 119879119901ℎ119910119904(119897) = 119879119889119910119899(119871) = 119879119889119910119899(119871)

Fine to coarseFor all physics layers l in dynamics layer L 119879119889119910119899(119871) = [119879119901ℎ119910119904(119897)] =int119879119901ℎ119910119904119889119901

Where is defined as the dynamics-to-physics operator and [] is the physics-to-dynamics operator 119879 stands for anystate variable and the subscripts 119901ℎ119910119904 and 119889119910119899 stand for variables on the physics and dynamics grids respectively

One of the central elements of the gridalt package is the routine which is called from subroutine gridalt_initialise todefine the grid to be used for the high end physics calculations Routine make_phys_grid passes back the parameterswhich define the grid ultimately stored in the common block gridalt_mapping

subroutine make_phys_grid(drFhfacCim1im2jm1jm2Nr NsxNsyi1i2j1j2bibjNrphysLbotdpphysnumlevphysnlperdyn)

cc Purpose Define the grid that the will be used to run the high-endc atmospheric physicscc Algorithm Fit additional levels of some (~) known thickness inc between existing levels of the grid used for the dynamicscc Need Information about the dynamics grid vertical spacingcc Input drF - delta r (p) edge-to-edgec hfacC - fraction of grid box above topography

c im1 im2 - beginning and ending i - dimensionsc jm1 jm2 - beginning and ending j - dimensionsc Nr - number of levels in dynamics gridc NsxNsy - number of processes in x and y directionc i1 i2 - beginning and ending i - index to fillc j1 j2 - beginning and ending j - index to fillc bi bj - x-dir and y-dir index of processc Nrphys - number of levels in physics gridcc Output dpphys - delta r (p) edge-to-edge of physics gridc numlevphys - number of levels used in the physicsc nlperdyn - physics level number atop each dynamics layercc NOTES 1) Pressure levs are built up from bottom using p0 ps and dpc p(ijk)=p(ijk-1) + dp(k)ps(ij)p0(ij)c 2) Output dps are aligned to fit EXACTLY between existingc levels of the dynamics vertical gridc 3) IMPORTANT This routine assumes the levels are numberedc from the bottom up ie level 1 is the surfacec IT WILL NOT WORK OTHERWISEc 4) This routine does NOT work for surface pressures lessc (ie above in the atmosphere) than about 350 mbc

In the case of the grid used to compute the atmospheric physical forcing (fizhi package) the locations of the gridpoints move in time with the MITgcm 119901 coordinate and subroutine gridalt_update is called during the run to updatethe locations of the grid points

subroutine gridalt_update(myThid)cc Purpose Update the pressure thicknesses of the layers of thec alternative vertical grid (used now for atmospheric physics)cc Calculate dpphys - new delta r (p) edge-to-edge of physics gridc using dpphys0 (initial value) and rstarfacCc

The gridalt package also supplies utility routines which perform the mappings from one grid to the other Theseroutines are called from the code which computes the fields on the alternative (fizhi) grid

subroutine dyn2phys(qdynpedynim1im2jm1jm2lmdynNsxNsy idim1idim2jdim1jdim2bibjwindphypephyLbotlmphynlperdyn flgqphy)

CC PurposeC To interpolate an arbitrary quantity from the dynamics eta (pstar)C grid to the higher resolution physics gridC AlgorithmC Routine works one layer (edge to edge pressure) at a timeC Dynamics -gt Physics retains the dynamics layer mean valueC weights the field either with the profile of the physics gridC wind speed (for U and V fields) or uniformly (T and Q)CC InputC qdyn [imjmlmdyn] Arbitrary Quantity on Input GridC pedyn [imjmlmdyn+1] Pressures at bottom edges of input levels

C im12 Limits for Longitude Dimension of InputC jm12 Limits for Latitude Dimension of InputC lmdyn Vertical Dimension of InputC Nsx Number of processes in x-directionC Nsy Number of processes in y-directionC idim12 Beginning and ending i-values to calculateC jdim12 Beginning and ending j-values to calculateC bi Index of process number in x-directionC bj Index of process number in x-directionC windphy [imjmlmphy] Magnitude of the wind on the output levelsC pephy [imjmlmphy+1] Pressures at bottom edges of output levelsC lmphy Vertical Dimension of OutputC nlperdyn [imjmlmdyn] Highest Physics level in each dynamics levelC flg Flag to indicate field type (0 for T or Q 1 for U or V)CC OutputC qphy [imjmlmphy] Quantity at output grid (physics grid)CC NotesC 1) This algorithm assumes that the output (physics) grid levelsC fit exactly into the input (dynamics) grid levelsC

And similarly gridalt contains subroutine phys2dyn

8256 Gridalt Diagnostics

8257 Dos and donts

8258 Gridalt Reference

8259 Experiments and tutorials that use gridalt

bull Fizhi experiment in fizhi-cs-32x32x10 verification directory

83 General purpose numerical infrastructure packages

831 OBCS Open boundary conditions for regional modeling

Authors Alistair Adcroft Patrick Heimbach Samar Katiwala Martin Losch

83 General purpose numerical infrastructure packages 173

8311 Introduction

The OBCS-package is fundamental to regional ocean modelling with the MITgcm but there are so many details tobe considered in regional ocean modelling that this package cannot accomodate all imaginable and possible optionsTherefore for a regional simulation with very particular details it is recommended to familiarize oneself not only withthe compile- and runtime-options of this package but also with the code itself In many cases it will be necessary toadapt the obcs-code (in particular codeSR OBCS_CALC) to the application in question in these cases the obcs-package (together with the rbcs-package section refsecpkgrbcs) is a very useful infrastructure for implementingspecial regional models

8312 OBCS configuration and compiling

As with all MITgcm packages OBCS can be turned on or off at compile time

bull using the packagesconf file by adding obcs to it

bull or using genmake2 adding -enable=obcs or -disable=obcs switches

bull Required packages and CPP options

ndash Two alternatives are available for prescribing open boundary values which differ in the way how OBrsquos aretreated in time

A simple time-management (eg constant in time or cyclic with fixed fequency) is provided throughSR obcs_external_fields_load

More sophisticated lsquoreal-timersquo (ie calendar time) management is available throughobcs_prescribe_read

ndash The latter case requires packages cal and exf to be enabled

(see also Section refsecbuildingCode)

Parts of the OBCS code can be enabled or disabled at compile time via CPP preprocessor flags These options are setin OBCS_OPTIONSh Table 81 summarizes these options

Table 81 OBCS CPP optionsCPP option DescriptionALLOW_OBCS_NORTH enable Northern OBALLOW_OBCS_SOUTH enable Southern OBALLOW_OBCS_EAST enable Eastern OBALLOW_OBCS_WEST enable Western OB

ALLOW_OBCS_PRESCRIBE enable code for prescribing OBrsquosALLOW_OBCS_SPONGE enable sponge layer codeALLOW_OBCS_BALANCE enable code for balancing transports through OBrsquosALLOW_ORLANSKI enable Orlanski radiation conditions at OBrsquosALLOW_OBCS_STEVENS enable Stevens (1990) boundary conditions at OBrsquos

(currently only implemented for eastern andwestern boundaries and NOT for ptracers)

8313 Run-time parameters

Run-time parameters are set in files datapkg dataobcs and dataexf if real-timeprescription is requested (ie package code`exf enabled) These parameter files are read

in SR packages_readparmsF obcs_readparmsF and exf_readparmsF respectively Run-time pa-rameters may be broken into 3 categories

1 switching onoff the package at runtime

2 OBCS package flags and parameters

3 additional timing flags in dataexf if selected

Enabling the package

The OBCS package is switched on at runtime by setting useOBCS = TRUE in datapkg

Package flags and parameters

Table 82 summarizes the runtime flags that are set in dataobcs and their default values

Table 82 pkg OBCS run-time parametersFlagparameter default Descriptionbasic flags amp parameters (OBCS_PARM01)OB_Jnorth 0 Nx-vector of J-indices (wrt Ny) of Northern OB at each I-position (wrt Nx)OB_Jsouth 0 Nx-vector of J-indices (wrt Ny) of Southern OB at each I-position (wrt Nx)OB_Ieast 0 Ny-vector of I-indices (wrt Nx) of Eastern OB at each J-position (wrt Ny)OB_Iwest 0 Ny-vector of I-indices (wrt Nx) of Western OB at each J-position (wrt Ny)useOBCSprescribe FALSEuseOBCSsponge FALSEuseOBCSbalance codeFALSEOBCS_balanceFacNSEW 1 factor(s) determining the details of the balaning codeuseOrlanskiNorthSouthEastWest FALSE turn on Orlanski boundary conditions for individual boundaryuseStevensNorthSouthEastWest FALSE turn on Stevens boundary conditions for individual boundaryOBXyFile file name of OB field

X N(orth) S(outh) E(ast) W(est)y t(emperature) s(salinity) u(-velocity) v(-velocity)w(-velocity) eta (sea surface height)a (sea ice area) h (sea ice thickness) sn (snow thickness) sl (sea ice salinity)

Orlanski parameters (OBCS_PARM02)cvelTimeScale 2000 sec averaging period for phase speedCMAX 045 ms maximum allowable phase speed-CFL for AB-IICFIX 08 ms fixed boundary phase speeduseFixedCEast FALSEuseFixedCWest FALSE

Sponge-layer parameters (OBCS_PARM03)spongeThickness 0 sponge layer thickness (in grid points)Urelaxobcsinner 0 sec relaxation time scale at the innermost sponge layer point of a meridional OBVrelaxobcsinner 0 sec relaxation time scale at the innermost sponge layer point of a zonal OBUrelaxobcsbound 0 sec relaxation time scale at the outermost sponge layer point of a meridional OBVrelaxobcsbound 0 sec relaxation time scale at the outermost sponge layer point of a zonal OB

Stevens parameters (OBCS_PARM04)Continued on next page

Table 82 ndash continued from previous pageTSrelaxStevens 0 sec relaxation time scale for temperaturesalinityuseStevensPhaseVel codeTRUEuseStevensAdvection codeTRUE

8314 Defining open boundary positions

There are four open boundaries (OBs) a Northern Southern Eastern and Western All OB locations are specifiedby their absolute meridional (NorthernSouthern) or zonal (EasternWestern) indices Thus for each zonal position119894 = 1 119873119909 a meridional index 119895 specifies the NorthernSouthern OB position and for each meridional position 119895 =1 119873119910 a zonal index 119894 specifies the EasternWestern OB position For NorthernSouthern OB this defines an 119873119909-dimensional ldquorowrdquo array OB_Jnorth(Nx) OB_Jsouth(Nx) and an 119873119910-dimenisonal ldquocolumnrdquo array OB_Ieast(Ny) OB_Iwest(Ny) Positions determined in this way allows NorthernSouthern OBs to be at variable 119895 (or 119910) positionsand EasternWestern OBs at variable 119894 (or 119909) positions Here indices refer to tracer points on the C-grid A zero (0)element in OB_I OB_J means there is no corresponding OB in that columnrow For a NorthernSouthern OBthe OB V point is to the SouthNorth For an EasternWestern OB the OB U point is to the WestEast For example

OB_Jnorth(3)=34 means that T(334) is a an OB point U(334) is a an OB point V(334) is a an OBpoint OB_Jsouth(3)=1 means that T(31) is a an OB point U(31) is a an OB point V(32) is a an OBpoint OB_Ieast(10)=69 means that T(6910) is a an OB point U(6910) is a an OB point V(6910) is aan OB point OB_Iwest(10)=1 means that T(110) is a an OB point U(210) is a an OB point V(110) isa an OB point

For convenience negative values for JnorthIeast refer to points relative to the NorthernEastern edges of themodel eg OB_Jnorth(3) = minus1 means that the point (3 Ny) is a northern OB

Simple examples For a model grid with mathlsquo N_xtimes N_y = 120times144lsquo horizontal grid points with fouropen boundaries along the four egdes of the domain the simplest way of specifying the boundary points in is

OB_Ieast = 144-1 or OB_Ieast = 144120

OB_Iwest = 1441OB_Jnorth = 120-1

or OB_Jnorth = 120144OB_Jsouth = 1201

If only the first 50 grid points of the southern boundary are boundary points

OB_Jsouth(150) = 501

8315 Equations and key routines

OBCS_READPARMS

Set OB positions through arrays OB_Jnorth(Nx) OB_Jsouth(Nx) OB_Ieast(Ny) OB_Iwest(Ny) and runtime flags(see Table [tabpkgobcsruntimesubf lags])

OBCS_CALC

Top-level routine for filling values to be applied at OB for 119879 119878 119880 119881 120578 into corresponding ldquoslicerdquo arrays (119909 119911) (119910 119911)for each OB OB[NSEW][tsuv] eg for salinity array at Southern OB array name is OBSt Values filled areeither

bull constant vertical 119879 119878 profiles as specified in file data (tRef(Nr) sRef(Nr)) with zero velocities 119880 119881

bull 119879 119878 119880 119881 values determined via Orlanski radiation conditions (see below)

bull prescribed time-constant or time-varying fields (see below)

bull use prescribed boundary fields to compute Stevens boundary conditions

ORLANSKI

Orlanski radiation conditions [Orl76] examples can be found in verificationdome and verificationtutorial_plume_on_slope

(refseceg-gravityplume)

OBCS_PRESCRIBE_READ

When useOBCSprescribe = TRUE the model tries to read temperature salinity u- and v-velocities from filesspecified in the runtime parameters OB[NSEW][tsuv]File These files are the usual IEEE big-endianfiles with dimensions of a section along an open boundary

bull For NorthSouth boundary files the dimensions are (119873119909 times 119873119903 times time levels) for EastWest boundary files thedimensions are (119873119910 times119873119903 times time levels)

bull If a non-linear free surface is used (refsecnonlinear-freesurface) additional files OB[NSEW]etaFilefor the sea surface height $eta$ with dimension (119873119909119910 times time levels) may be specified

bull If non-hydrostatic dynamics are used (refsecnon-hydrostatic) additional files OB[NSEW]wFile for thevertical velocity $w$ with dimensions (119873119909119910 times119873119903 times time levels) can be specified

bull If useSEAICE=TRUE then additional files OB[NSEW][ahslsnuicevice] for sea ice areathickness (HEFF) seaice salinity snow and ice velocities (119873119909119910 times time levels) can be specified

As in SR external_fields_load or the exf-package the code reads two time levels for each variableegOBNu0 and OBNu1 and interpolates linearly between these time levels to obtain the value OBNu at the currentmodel time (step) When the exf-package is used the time levels are controlled for each boundary separately in thesame way as the exf-fields in dataexf namelist EXF_NML_OBCS The runtime flags follow the above namingconventions eg for the western boundary the corresponding flags are OBCWstartdate12 and OBCWperiodSea-ice boundary values are controlled separately with siobWstartdate12 and siobWperiod When theexf-package is not used the time levels are controlled by the runtime flags externForcingPeriod andexternForcingCycle in data see verificationexp4 for an example

OBCS_CALC_STEVENS

(THE IMPLEMENTATION OF THESE BOUNDARY CONDITIONS IS NOT COMPLETE PASSIVE TRACERSSEA ICE AND NON-LINEAR FREE SURFACE ARE NOT SUPPORTED PROPERLY)

The boundary conditions following [Ste90] require the vertically averaged normal velocity (originally specified asa stream function along the open boundary) 119900119887 and the tracer fields 120594119900119887 (note passive tracers are currently notimplemented and the code stops when package codeptracers is used together with this option) Currently the codevertically averages the normal velocity as specified in codeOB[EW]u or codeOB[NS]v From these prescribedvalues the code computes the boundary values for the next timestep 119899 + 1 as follows (as an example we use thenotation for an eastern or western boundary)

bull 119906119899+1(119910 119911) = 119900119887(119910)+(119906prime)119899(119910 119911) where (119906prime)119899 is the deviation from the vertically averaged velocity at timestep119899 on the boundary (119906prime)119899 is computed in the previous time step 119899 from the intermediate velocity 119906 prior to the

correction step (see section [sectimesubstepping] eg eq([equstar-backward-free-surface])) (This velocityis not available at the beginning of the next time step 119899+1 when SR OBCS_CALCOBCS_CALC_STEVENSare called therefore it needs to be saved in SR DYNAMICS by calling SR OBCS_SAVE_UV_N and alsostored in a separate restart files pickup_stevens[NSEW]$iterationdata)

bull If 119906119899+1 is directed into the model domain the boudary value for tracer 120594 is restored to the prescribed values

120594119899+1 = 120594119899 +∆119905

120591120594(120594119900119887 minus 120594119899)

where 120591120594 is the relaxation time scale TSrelaxStevens The new 120594119899+1 is then subject to the advection by119906119899+1

bull If 119906119899+1 is directed out of the model domain the tracer 120594119899+1 on the boundary at timestep 119899+1 is estimated fromadvection out of the domain with 119906119899+1 + 119888 where 119888 is a phase velocity estimated as 1

2120597120594120597119905

120597120594120597119909 The numerical

scheme is (as an example for an eastern boundary)

120594119899+1119894119887119895119896

= 120594119899119894119887119895119896

+ ∆119905(119906119899+1 + 119888)119894119887119895119896120594119899119894119887119895119896

minus 120594119899119894119887minus1119895119896

∆119909119862119894119887119895 if 119906119899+1

119894119887119895119896gt 0

where 119894119887 is the boundary index For test purposes the phase velocity contribution or the entire advection can beturned off by setting the corresponding parameters useStevensPhaseVel and useStevensAdvectionto FALSE

See [Ste90] for details With this boundary condition specifying the exact net transport across the open boundary issimple so that balancing the flow with (SR~OBCS_BALANCE_FLOW see next paragraph) is usually not necessary

OBCS_BALANCE_FLOW

When turned on (ALLOW_OBCS_BALANCE defined in OBCS_OPTIONSh and useOBCSbalance=truein dataobcsOBCS_PARM01) this routine balances the net flow across the open boundaries By default the netflow across the boundaries is computed and all normal velocities on boundaries are adjusted to obtain zero net inflow

This behavior can be controlled with the runtime flags OBCS_balanceFacNSEW The values of these flagsdetermine how the net inflow is redistributed as small correction velocities between the individual sections A value-1 balances an individual boundary values gt 0 determine the relative size of the correction For example the values

OBCS_balanceFacE = 1 OBCS_balanceFacW = -1 OBCS_balanceFacN = 2OBCS_balanceFacS = 0

make the model

bull correct Western OBWu by substracting a uniform velocity to ensure zero net transport through the Western openboundary

bull correct Eastern and Northern normal flow with the Northern velocity correction two times larger than the Easterncorrection but not the Southern normal flow to ensure that the total inflow through East Northern and Southernopen boundary is balanced

The old method of balancing the net flow for all sections individually can be recovered by setting all flags to -1 Thenthe normal velocities across each of the four boundaries are modified separately so that the net volume transport acrosseach boundary is zero For example for the western boundary at 119894 = 119894119887 the modified velocity is

119906(119910 119911) minusint

western boundary119906 119889119910 119889119911 asymp 119874119861119873119906(119895 119896) minus

sum119895119896

119874119861119873119906(119895 119896)ℎ119908(119894119887 119895 119896)∆119910119866(119894119887 119895)∆119911(119896)

This also ensures a net total inflow of zero through all boundaries but this combination of flags is not useful if you wantto simulate say a sector of the Southern Ocean with a strong ACC entering through the western and leaving throughthe eastern boundary because the value of lsquorsquo-1rdquo for these flags will make sure that the strong inflow is removedClearly gobal balancing with OBCS_balanceFacEWNS ge 0 is the preferred method

OBCS_APPLY_

OBCS_SPONGE

The sponge layer code (turned on with ALLOW_OBCS_SPONGE and useOBCSsponge) adds a relaxation termto the right-hand-side of the momentum and tracer equations The variables are relaxed towards the boundary valueswith a relaxation time scale that increases linearly with distance from the boundary

119866(sponge)120594 = minus120594minus [(119871minus 120575119871)120594119861119862 + 120575119871120594]119871

[(119871minus 120575119871)120591119887 + 120575119871120591119894]119871= minus120594minus [(1 minus 119897)120594119861119862 + 119897120594]

[(1 minus 119897)120591119887 + 119897120591119894]

where 120594 is the model variable (UVTS) in the interior 120594119861119862 the boundary value 119871 the thickness of thesponge layer (runtime parameter spongeThickness in number of grid points) 120575119871 isin [0 119871] ( 120575119871119871 = 119897 isin[0 1]) the distance from the boundary (also in grid points) and 120591119887 (runtime parameters Urelaxobcsboundand Vrelaxobcsbound) and 120591119894 (runtime parameters Urelaxobcsinner and Vrelaxobcsinner) therelaxation time scales on the boundary and at the interior termination of the sponge layer The pa-rameters Urelaxobcsboundinner`set the relaxation time scales for the Eastern andWestern boundaries code`Vrelaxobcsboundinner for the Northern and Southern boundaries

OBrsquos with nonlinear free surface

8316 Flow chart

C CALLING SEQUENCEc

8317 OBCS diagnostics

Diagnostics output is available via the diagnostics package (see Section [secpkgdiagnostics]) Available output fieldsare summarized in Table [tabpkgobcsdiagnostics]

[tabpkgobcsdiagnostics]

------------------------------------------------------lt-Name-gt|Levs|grid|lt-- Units --gt|lt- Tile (max=80c)

------------------------------------------------------

8318 Reference experiments

In the directory verifcation the following experiments use obcs

bull exp4 box with 4 open boundaries simulating flow over a Gaussian bump based on also tests Stevens-boundary conditions

bull dome based on the project ldquoDynamics of Overflow Mixing and Entrainmentrdquo (httpwwwrsmasmiamiedupersonaltamayDOMEdomehtml) uses Orlanski-BCs

bull internal_wave uses a heavily modified SR~OBCS_CALC

bull codeseaice_obcslsquo simple example who to use the sea-ice related code based on lab_sea

bull tutorial_plume_on_slope uses Orlanski-BCs see also section [seceg-gravityplume]

8319 References

83110 Experiments and tutorials that use obcs

bull tutorial_plume_on_slope (section~refseceg-gravityplume)

832 RBCS Package

8321 Introduction

A package which provides the flexibility to relax fields (temperature salinity ptracers) in any 3-D location so couldbe used as a sponge layer or as a ldquosourcerdquo anywhere in the domain

For a tracer (119879 ) at every grid point the tendency is modified so that

119889119879

119889119905=119889119879

119889119905minus 119872119903119887119888

120591119879(119879 minus 119879119903119887119888)

where 119872119903119887119888 is a 3-D mask (no time dependence) with values between 0 and 1 Where 119872119903119887119888 is 1 relaxing timescale is1120591119879 Where it is 0 there is no relaxing The value relaxed to is a 3-D (potentially varying in time) field given by 119879119903119887119888

A seperate mask can be used for TS and ptracers and each of these can be relaxed or not and can have its own timescale120591119879 These are set in datarbcs (see below)

8322 Key subroutines and parameters

The only compile-time parameter you are likely to have to change is in RBCSh the number of masks PARAME-TER(maskLEN = 3 ) see below

The runtime parameters are set in datarbcs

Set in RBCS_PARM01 - rbcsForcingPeriod time interval between forcing fields (in seconds) zero means constant-in-time forcing - rbcsForcingCycle repeat cycle of forcing fields (in seconds) zero means non-cyclic forcing -rbcsForcingOffset time offset of forcing fields (in seconds default 0) this is relative to time averages starting at 119905 =0 ie the first forcing recordfile is placed at rbcsForcingOffset + rbcsForcingPeriod2 see below for examples- rbcsSingleTimeFiles true or false (default false) if true forcing fields are given 1 file per rbcsForcingPeriod -deltaTrbcs time step used to compute the iteration numbers for rbcsSingleTimeFiles=T - rbcsIter0 shift in iterationnumbers used to label files if rbcsSingleTimeFiles=T (default 0 see below for examples) - useRBCtemp true or false(default false) - useRBCsalt true or false (default false) - useRBCptracers true or false (default false) must be usingptracers to set true - tauRelaxT timescale in seconds of relaxing in temperature (120591119879 in equation above) Where mask is1 relax rate will be 1tauRelaxT Default is 1 - tauRelaxS same for salinity - relaxMaskFile(irbc) filename of 3-Dfile with mask (119872119903119887119888 in equation above Need a file for each irbc 1=temperature 2=salinity 3=ptracer01 4=ptracer02etc If the mask numbers end (see maskLEN) are less than the number tracers then relaxMaskFile(maskLEN) is usedfor all remaining ptracers - relaxTFile name of file where temperatures that need to be relaxed to (119879119903119887119888 in equationabove) are stored The file must contain 3-D records to match the model domain If rbcsSingleTimeFiles=F it musthave one record for each forcing period If T there must be a separate file for each period and a 10-digit iterationnumber is appended to the file name (see Table [tabpkgrbcstiming] and examples below) - relaxSFile same forsalinity

Set in RBCS_PARM02 for each of the ptracers (iTrc) - useRBCptrnum(iTrc) true or false (default is false) -tauRelaxPTR(iTrc) relax timescale - relaxPtracerFile(iTrc) file with relax fields

8323 Timing of relaxation forcing fields

For constant-in-time relaxation set rbcsForcingPeriod=0 For time-varying relaxation Table [tabpkgrbcstiming]illustrates the relation between model time and forcing fields (either records in one big file or for rbcsSingleTime-Files=T individual files labeled with an iteration number) With rbcsSingleTimeFiles=T this is the same as in theoffline package except that the forcing offset is in seconds

Table 83 Timing of RBCS relaxation fieldsrbcsSingleTimeFiles = T F119888 = 0 119888 = 0 119888 = 0

model time file number file number record1199050 minus 1199012 1198940 1198940 + 119888∆119905rbcs 1198881199011199050 + 1199012 1198940 + 119901∆119905rbcs 1198940 + 119901∆119905rbcs 11199050 + 119901+ 1199012 1198940 + 2119901∆119905rbcs 1198940 + 2119901∆119905rbcs 2 1199050 + 119888minus 1199012 1198940 + 119888∆119905rbcs 119888119901

119901 = rbcsForcingPeriod

119888 = rbcsForcingCycle

1199050 = rbcsForcingOffset

1198940 = rbcsIter0

∆119905rbcs = deltaTrbcs

8324 Example 1 forcing with time averages starting at 119905 = 0

Cyclic data in a single file

Set rbcsSingleTimeFiles=F and rbcsForcingOffset=0 and the model will start by interpolating the last and first recordsof rbcs data placed at minus1199012 and 1199012 resp as appropriate for fields averaged over the time intervals [minus119901 0] and [0 119901]

Non-cyclic data multiple files

Set rbcsForcingCycle=0 and rbcsSingleTimeFiles=T With rbcsForcingOffset=0 rbcsIter0=0 and deltaTr-bcs=rbcsForcingPeriod the model would then start by interpolating data from files relaxFile0000000000data andrelaxFile0000000001data again placed at minus1199012 and 1199012

8325 Example 2 forcing with snapshots starting at 119905 = 0

Set rbcsSingleTimeFiles=F and rbcsForcingOffset=minus1199012 and the model will start forcing with the first record at119905 = 0

Set rbcsForcingCycle=0 and rbcsSingleTimeFiles=T In this case it is more natural to set rbcsForcingOffset=+1199012With rbcsIter0=0 and deltaTrbcs=rbcsForcingPeriod the model would then start with data from files re-laxFile0000000000data at 119905 = 0 It would then proceed to interpolate between this file and files re-laxFile0000000001data at 119905 = rbcsForcingPeriod

8326 Dorsquos and Donrsquots

8327 Reference Material

8328 Experiments and tutorials that use rbcs

In the directory the following experiments use rbcs

bull exp4 box with 4 open boundaries simulating flow over a Gaussian bump based on [AHM97]

833 PTRACERS Package

8331 Introduction

This is a lsquorsquopassiverdquo tracer package Passive here means that the tracers donrsquot affect the density of the water (as opposedto temperature and salinity) so no not actively affect the physics of the ocean Tracers are initialized advected diffusedand various outputs are taken care of in this package For methods to add additional sources and sinks of tracers usethe pkggchem (section [secpkggchem])

Can use up tp 3843 tracers But can not use pkgdiagnostics with more than about 90 tracers UseutilsmatlabioLb2numm and num2ioLbm to find correspondence between tracer number and tracer designation inthe code for more than 99 tracers (since tracers only have two digit designations)

8332 Equations

The only code you should have to modify is PTRACERS_SIZEh where you need to set in the number of tracers tobe used in the experiment PTRACERS_num

Run time parameters set in dataptracers

bull PTRACERS_Iter0 which is the integer timestep when the tracer experiment is initialized If nIter0 = PTRAC-ERS_Iter0 then the tracers are initialized to zero or from initial files If nIter0 gt PTRACERS_Iter0 then tracers(and previous timestep tendency terms) are read in from a the ptracers pickup file Note that tracers of zeros willbe carried around if nIter0 lt PTRACERS_Iter0

bull PTRACERS_numInUse number of tracers to be used in the run (needs to be lt= PTRACERS_num set inPTRACERS_SIZEh)

bull PTRACERS_dumpFreq defaults to dumpFreq (set in data)

bull PTRACERS_taveFreq defaults to taveFreq (set in data)

bull PTRACERS_monitorFreq defaults to monitorFreq (set in data)

bull PTRACERS_timeave_mnc needs useMNC timeave_mnc default to false

bull PTRACERS_snapshot_mnc needs useMNC snapshot_mnc default to false

bull PTRACERS_monitor_mnc needs useMNC monitor_mnc default to false

bull PTRACERS_pickup_write_mnc needs useMNC pickup_write_mnc default to false

bull PTRACERS_pickup_read_mnc needs useMNC pickup_read_mnc default to false

bull PTRACERS_useRecords defaults to false If true will write all tracers in a single file otherwise each tracerin a seperate file

The following can be set for each tracer (tracer number iTrc)

bull PTRACERS_advScheme(iTrc) will default to saltAdvScheme (set in data) For other options see Table[tabadvectionShemessubsummary]

bull PTRACERS_ImplVertAdv(iTrc) implicit vertical advection flag default to FALSE

bull PTRACERS_diffKh(iTrc) horizontal Laplacian Diffusivity dafaults to diffKhS (set in data)

bull PTRACERS_diffK4(iTrc) Biharmonic Diffusivity defaults to diffK4S (set in data)

bull PTRACERS_diffKr(iTrc) vertical diffusion defaults to un-set

bull PTRACERS_diffKrNr(kiTrc) level specific vertical diffusion defaults to diffKrNrS Will be set to PTRAC-ERS_diffKr if this is set

bull PTRACERS_ref(kiTrc) reference tracer value for each level k defaults to 0 Currently only used for dilu-tionconcentration of tracers at surface if PTRACERS_EvPrRn(iTrc) is set and convertFW2Salt (set in data) isset to something other than -1 (note default is convertFW2Salt=35)

bull PTRACERS_EvPrRn(iTrc) tracer concentration in freshwater Needed for calculation of dilu-tionconcentration in surface layer due to freshwater additionevaporation Defaults to un-set in which caseno dilutionconcentration occurs

bull PTRACERS_useGMRedi(iTrc) apply GM or not Defaults to useGMREdi

bull PTRACERS_useKPP(iTrc) apply KPP or not Defaults to useKPP

bull PTRACERS_initialFile(iTrc) file with initial tracer concentration Will be used if PTRACERS_Iter0 = nIter0Default is no name in which case tracer is initialised as zero If PTRACERS_Iter0 lt nIter0 then tracer con-centration will come from pickup_ptracer

bull PTRACERS_names(iTrc) tracer name Needed for netcdf Defaults to nothing

bull PTRACERS_long_names(iTrc) optional name in long form of tracer

bull PTRACERS_units(iTrc) optional units of tracer

8334 PTRACERS Diagnostics

Note that these will only work for 90 or less tracers (some problems with the numberingdesignation over this number)

84 Ocean Packages

841 GMREDI Gent-McWilliamsRedi SGS Eddy Parameterization

There are two parts to the RediGM parameterization of geostrophic eddies The first the Redi scheme [Red82] aimsto mix tracer properties along isentropes (neutral surfaces) by means of a diffusion operator oriented along the localisentropic surface The second part GM [GM90][GWMM95] adiabatically re-arranges tracers through an advectiveflux where the advecting flow is a function of slope of the isentropic surfaces

The first GCM implementation of the Redi scheme was by [Cox87] in the GFDL ocean circulation model Theoriginal approach failed to distinguish between isopycnals and surfaces of locally referenced potential density (nowcalled neutral surfaces) which are proper isentropes for the ocean As will be discussed later it also appears that the

84 Ocean Packages 185

Cox implementation is susceptible to a computational mode Due to this mode the Cox scheme requires a backgroundlateral diffusion to be present to conserve the integrity of the model fields

The GM parameterization was then added to the GFDL code in the form of a non-divergent bolus velocity The methoddefines two stream-functions expressed in terms of the isoneutral slopes subject to the boundary condition of zero valueon upper and lower boundaries The horizontal bolus velocities are then the vertical derivative of these functions Herein lies a problem highlighted by [GGP+98] the bolus velocities involve multiple derivatives on the potential densityfield which can consequently give rise to noise Griffies et al point out that the GM bolus fluxes can be identicallywritten as a skew flux which involves fewer differential operators Further combining the skew flux formulation andRedi scheme substantial cancellations take place to the point that the horizontal fluxes are unmodified from the lateraldiffusion parameterization

8411 Redi scheme Isopycnal diffusion

The Redi scheme diffuses tracers along isopycnals and introduces a term in the tendency (rhs) of such a tracer (here120591 ) of the form

nabla middot 120581120588KRedinabla120591

where 120581120588 is the along isopycnal diffusivity and KRedi is a rank 2 tensor that projects the gradient of 120591 onto theisopycnal surface The unapproximated projection tensor is

KRedi =1

1 + |S|2

⎛⎝ 1 + 1198782119910 minus119878119909119878119910 119878119909

minus119878119909119878119910 1 + 1198782119909 119878119910

119878119909 119878119910 |119878|2

⎞⎠Here 119878119909 = minus120597119909120590120597119911120590 and 119878119910 = minus120597119910120590120597119911120590 are the components of the isoneutral slope

The first point to note is that a typical slope in the ocean interior is small say of the order 10minus4 A maximum slopemight be of order 10minus2 and only exceeds such in unstratified regions where the slope is ill defined It is therefore jus-tifiable and customary to make the small slope approximation |119878| ltlt 1 The Redi projection tensor then becomes

KRedi =

⎛⎝ 1 0 119878119909

0 1 119878119910

119878119909 119878119910 |119878|2

⎞⎠

8412 GM parameterization

The GM parameterization aims to represent the ldquoadvectiverdquo or ldquotransportrdquo effect of geostrophic eddies by means of aldquobolusrdquo velocity u⋆ The divergence of this advective flux is added to the tracer tendency equation (on the rhs)

minusnabla middot 120591u⋆

The bolus velocity u⋆ is defined as the rotational of a streamfunction F⋆=(119865 ⋆119909 119865

⋆119910 0)

u⋆ = nablatimes F⋆ =

⎛⎝ minus120597119911119865 ⋆119910

+120597119911119865⋆119909

120597119909119865⋆119910 minus 120597119910119865

⋆119909

⎞⎠

and thus is automatically non-divergent In the GM parameterization the streamfunction is specified in terms of theisoneutral slopes 119878119909 and 119878119910

119865 ⋆119909 = minus120581119866119872119878119910

119865 ⋆119910 = 120581119866119872119878119909

with boundary conditions 119865 ⋆119909 = 119865 ⋆

119910 = 0 on upper and lower boundaries In the end the bolus transport in the GMparameterization is given by

u⋆ =

⎛⎝ 119906⋆

119907⋆

119908⋆

⎞⎠ =

⎛⎝ minus120597119911(120581119866119872119878119909)minus120597119911(120581119866119872119878119910)

120597119909(120581119866119872119878119909) + 120597119910(120581119866119872119878119910)

⎞⎠This is the form of the GM parameterization as applied by Donabasaglu 1997 in MOM versions 1 and 2

Note that in the MITgcm the variables containing the GM bolus streamfunction are(119866119872_119875119904119894119883119866119872_119875119904119894119884

(120581119866119872119878119909

120581119866119872119878119910

(119865 ⋆119910

minus119865 ⋆119909

8413 Griffies Skew Flux

[Gri98] notes that the discretisation of bolus velocities involves multiple layers of differencing and interpolation thatpotentially lead to noisy fields and computational modes He pointed out that the bolus flux can be re-written in termsof a non-divergent flux and a skew-flux

u⋆120591 =

⎛⎝ minus120597119911(120581119866119872119878119909)120591minus120597119911(120581119866119872119878119910)120591

(120597119909120581119866119872119878119909 + 120597119910120581119866119872119878119910)120591

⎞⎠=

⎛⎝ minus120597119911(120581119866119872119878119909120591)minus120597119911(120581119866119872119878119910120591)

120597119909(120581119866119872119878119909120591) + 120597119910(120581119866119872119878119910120591)

⎞⎠+

⎛⎝ 120581119866119872119878119909120597119911120591120581119866119872119878119910120597119911120591

minus120581119866119872119878119909120597119909120591 minus 120581119866119872119878119910120597119910120591

⎞⎠The first vector is non-divergent and thus has no effect on the tracer field and can be dropped The remaining flux canbe written

u⋆120591 = minus120581GMKGMnabla120591

⎛⎝ 0 0 minus119878119909

0 0 minus119878119910

119878119909 119878119910 0

⎞⎠is an anti-symmetric tensor

This formulation of the GM parameterization involves fewer derivatives than the original and also involves only termsthat already appear in the Redi mixing scheme Indeed a somewhat fortunate cancellation becomes apparent when weuse the GM parameterization in conjunction with the Redi isoneutral mixing scheme

120581120588KRedinabla120591 minus u⋆120591 = (120581120588KRedi + 120581GMKGM)nabla120591

In the instance that 120581119866119872 = 120581120588 then

120581120588KRedi + 120581GMKGM = 120581120588

⎛⎝ 1 0 00 1 0

2119878119909 2119878119910 |119878|2

⎞⎠which differs from the variable Laplacian diffusion tensor by only two non-zero elements in the 119911-row

Subroutine

SR GMREDI_CALC_TENSOR (pkggmredigmredi_calc_tensorF)

120590119909 SlopeX (argument on entry)

120590119910 SlopeY (argument on entry)

120590119911 SlopeY (argument)

119878119909 SlopeX (argument on exit)

119878119910 SlopeY (argument on exit)

8414 Variable 120581119866119872

[VMHS97] suggest making the eddy coefficient 120581119866119872 a function of the Eady growth rate |119891 |radic119877119894 The formula

involves a non-dimensional constant 120572 and a length-scale 119871

120581119866119872 = 1205721198712 |119891 |radic119877119894

119911

where the Eady growth rate has been depth averaged (indicated by the over-line) A local Richardson number isdefined 119877119894 = 1198732(120597119906120597119911)2 which when combined with thermal wind gives

119877119894=

(120597119906120597119911 )2

1198732=

( 119892119891120588119900

|nabla120590|)2

1198732=

1198724

|119891 |21198732

where 1198722 is defined 1198722 = 119892120588119900|nabla120590| Substituting into the formula for 120581119866119872 gives

120581119866119872 = 12057211987121198722

119873

119911

= 12057211987121198722

1198732119873

119911

= 1205721198712|119878|119873119911

8415 Tapering and stability

Experience with the GFDL model showed that the GM scheme has to be matched to the convective parameterizationThis was originally expressed in connection with the introduction of the KPP boundary layer scheme [LMD94] but infact as subsequent experience with the MIT model has found is necessary for any convective parameterization

Subroutine

SR GMREDI_SLOPE_LIMIT (pkggmredigmredi_slope_limitF)

120590119909 119904119909 SlopeX (argument)

120590119910 119904119910 SlopeY (argument)

120590119911 dSigmadRReal (argument)

119911120590 dRdSigmaLtd (argument)

8416 Slope clipping

Deep convection sites and the mixed layer are indicated by homogenized unstable or nearly unstable stratification Theslopes in such regions can be either infinite very large with a sign reversal or simply very large From a numerical pointof view large slopes lead to large variations in the tensor elements (implying large bolus flow) and can be numerically

10minus4 10minus3 10minus2 10minus10

Slope |S|

r fn f(

DM95 1+tanh[ (Scminus|S|)Sd ] 2GKW91 (Smax|S|)2

Figure 86 Taper functions used in GKW91 and DM95

minus002 minus0015 minus001 minus0005 0 0005 001 0015 002minus001

minus0008

minus0006

minus0004

minus0002

Slope S

S = f(

DM95 1+tanh[ (Scminus|S|)Sd ] 2 SGKW91 (Smax|S|)2 S Cox Slope Clipping

Figure 87 Effective slope as a function of lsquotruersquo slope using Cox slope clipping GKW91 limiting and DM95 limiting

unstable This was first recognized by [Cox87] who implemented ldquoslope clippingrdquo in the isopycnal mixing tensorHere the slope magnitude is simply restricted by an upper limit

|nabla120590| =radic1205902119909 + 1205902

119910

119878119897119894119898 = minus |nabla120590|119878119898119886119909

where 119878119898119886119909 is a parameter

120590⋆119911 = min(120590119911 119878119897119894119898)

[119904119909 119904119910] = minus [120590119909 120590119910]

120590⋆119911

Notice that this algorithm assumes stable stratification through the ldquominrdquo function In the case where the fluid is wellstratified (120590119911 lt 119878119897119894119898) then the slopes evaluate to

[119904119909 119904119910] = minus [120590119909 120590119910]

120590119911

while in the limited regions (120590119911 gt 119878119897119894119898) the slopes become

[119904119909 119904119910] =[120590119909 120590119910]

|nabla120590|119878119898119886119909

so that the slope magnitude is limitedradic1199042119909 + 1199042119910 = 119878119898119886119909

The slope clipping scheme is activated in the model by setting GM_taper_scheme = rsquoclippingrsquo in datagmredi

Even using slope clipping it is normally the case that the vertical diffusion term (with coefficient 120581120588K33 = 1205811205881198782119898119886119909)

is large and must be time-stepped using an implicit procedure (see section on discretisation and code later) Fig [fig-mixedlayer] shows the mixed layer depth resulting from a) using the GM scheme with clipping and b) no GM scheme(horizontal diffusion) The classic result of dramatically reduced mixed layers is evident Indeed the deep convectionsites to just one or two points each and are much shallower than we might prefer This it turns out is due to theover zealous re-stratification due to the bolus transport parameterization Limiting the slopes also breaks the adiabaticnature of the GMRedi parameterization re-introducing diabatic fluxes in regions where the limiting is in effect

8417 Tapering Gerdes Koberle and Willebrand Clim Dyn 1991

The tapering scheme used in [GKW91] addressed two issues with the clipping method the introduction of largevertical fluxes in addition to convective adjustment fluxes is avoided by tapering the GMRedi slopes back to zero inlow-stratification regions the adjustment of slopes is replaced by a tapering of the entire GMRedi tensor This meansthe direction of fluxes is unaffected as the amplitude is scaled

The scheme inserts a tapering function 1198911(119878) in front of the GMRedi tensor

1198911(119878) = min

(119878119898119886119909

|119878|

where 119878119898119886119909 is the maximum slope you want allowed Where the slopes |119878| lt 119878119898119886119909 then 1198911(119878) = 1 and the tensoris un-tapered but where |119878| ge 119878119898119886119909 then 1198911(119878) scales down the tensor so that the effective vertical diffusivity term1205811198911(119878)|119878|2 = 1205811198782

119898119886119909

The GKW91 tapering scheme is activated in the model by setting GM_taper_scheme = rsquogkw91rsquo in datagmredi

8418 Tapering Danabasoglu and McWilliams J Clim 1995

The tapering scheme used by followed a similar procedure but used a different tapering function 1198911(119878)

1198911(119878) =1

(1 + tanh

[119878119888 minus |119878|119878119889

where 119878119888 = 0004 is a cut-off slope and 119878119889 = 0001 is a scale over which the slopes are smoothly tapered Function-ally the operates in the same way as the GKW91 scheme but has a substantially lower cut-off turning off the GMRediSGS parameterization for weaker slopes

The DM95 tapering scheme is activated in the model by setting GM_taper_scheme = rsquodm95rsquo in datagmredi

8419 Tapering Large Danabasoglu and Doney JPO 1997

The tapering used in [LDDM97] is based on the DM95 tapering scheme but also tapers the scheme with an additionalfunction of height 1198912(119911) so that the GMRedi SGS fluxes are reduced near the surface

1198912(119911) =1

(1 + sin(120587

119911

119863minus 120587

where119863 = 119871120588|119878| is a depth-scale and 119871120588 = 119888119891 with 119888 = 2 m smath^-1 This tapering with height was introducedto fix some spurious interaction with the mixed-layer KPP parameterization

The LDD97 tapering scheme is activated in the model by setting GM_taper_scheme = rsquoldd97rsquo in datagmredi

84110 Package Reference

------------------------------------------------------------------------lt-Name-gt|Levs|lt-parsing code-gt|lt-- Units --gt|lt- Tile (max=80c)------------------------------------------------------------------------GM_VisbK| 1 |SM P M1 |m^2s |Mixing coefficient from Visbeck etalrarr˓parameterizationGM_Kux | 15 |UU P 177MR |m^2s |K_11 element (Upoint Xdir) of GM-rarr˓Redi tensorGM_Kvy | 15 |VV P 176MR |m^2s |K_22 element (Vpoint Ydir) of GM-rarr˓Redi tensorGM_Kuz | 15 |UU 179MR |m^2s |K_13 element (Upoint Zdir) of GM-rarr˓Redi tensorGM_Kvz | 15 |VV 178MR |m^2s |K_23 element (Vpoint Zdir) of GM-rarr˓Redi tensorGM_Kwx | 15 |UM 181LR |m^2s |K_31 element (Wpoint Xdir) of GM-rarr˓Redi tensorGM_Kwy | 15 |VM 180LR |m^2s |K_32 element (Wpoint Ydir) of GM-rarr˓Redi tensorGM_Kwz | 15 |WM P LR |m^2s |K_33 element (Wpoint Zdir) of GM-rarr˓Redi tensorGM_PsiX | 15 |UU 184LR |m^2s |GM Bolus transport stream-function rarr˓X componentGM_PsiY | 15 |VV 183LR |m^2s |GM Bolus transport stream-function rarr˓Y componentGM_KuzTz| 15 |UU 186MR |degCm^3s |Redi Off-diagonal Tempetature flux Xrarr˓componentGM_KvzTz| 15 |VV 185MR |degCm^3s |Redi Off-diagonal Tempetature flux Yrarr˓component

84111 Experiments and tutorials that use gmredi

bull Global Ocean tutorial in tutorial_global_oce_latlon verification directory described in section [seceg-global]

bull Front Relax experiment in front_relax verification directory

bull Ideal 2D Ocean experiment in ideal_2D_oce verification directory

842 KPP Nonlocal K-Profile Parameterization for Vertical Mixing

Authors Dimitris Menemenlis and Patrick Heimbach

8421 Introduction

The nonlocal K-Profile Parameterization (KPP) scheme of [LMD94] unifies the treatment of a variety of unresolvedprocesses involved in vertical mixing To consider it as one mixing scheme is in the view of the authors somewhatmisleading since it consists of several entities to deal with distinct mixing processes in the oceanrsquos surface boundarylayer and the interior

1 mixing in the interior is goverened by shear instability (modeled as function of the local gradient Richardsonnumber) internal wave activity (assumed constant) and double-diffusion (not implemented here)

2 a boundary layer depth ℎ or hbl is determined at each grid point based on a critical value of turbulent processesparameterized by a bulk Richardson number

3 mixing is strongly enhanced in the boundary layer under the stabilizing or destabilizing influence of surfaceforcing (buoyancy and momentum) enabling boundary layer properties to penetrate well into the thermoclinemixing is represented through a polynomial profile whose coefficients are determined subject to several con-traints

4 the boundary-layer profile is made to agree with similarity theory of turbulence and is matched in the asymptoticsense (function and derivative agree at the boundary) to the interior thus fixing the polynomial coefficientsmatching allows for some fraction of the boundary layer mixing to affect the interior and vice versa

5 a ldquonon-localrdquo term 120574 or ghat which is independent of the vertical property gradient further enhances mixingwhere the water column is unstable

The scheme has been extensively compared to observations (see eg [LDDM97]) and is now common in many oceanmodels

The current code originates in the NCAR NCOM 1-D code and was kindly provided by Bill Large and Jan MorzelIt has been adapted first to the MITgcm vector code and subsequently to the current parallel code Adjustment weremainly in conjunction with WRAPPER requirements (domain decomposition and threading capability) to enableautomatic differentiation of tangent linear and adjoint code via TAMC

The following sections will describe the KPP package configuration and compiling ([secpkgkppcomp])the settings and choices of runtime parameters ([secpkgkppruntime]) more detailed description of equa-tions to which these parameters relate ([secpkgkppequations]) and key subroutines where they are used([secpkgkppflowchart]) and diagnostics output of KPP-derived diffusivities viscosities and boundary-layermixed-layer depths ([secpkgkppdiagnostics])

8422 KPP configuration and compiling

As with all MITgcm packages KPP can be turned on or off at compile time

bull using the packagesconf file by adding kpp to it

bull or using genmake2 adding -enable=kpp or -disable=kpp switches

bull Required packages and CPP options No additional packages are required but the MITgcm kernel flag enablingthe penetration of shortwave radiation below the surface layer needs to be set in CPP_OPTIONSh as followsdefine SHORTWAVE_HEATING

(see Section [secbuildingCode])

Parts of the KPP code can be enabled or disabled at compile time via CPP preprocessor flags These options are set inKPP_OPTIONSh Table Table 84 summarizes them

Table 84 CPP flags for KPPCPP option Description_KPP_RLFRUGAL_KPPKPP_SMOOTH_SHSQKPP_SMOOTH_DVSQKPP_SMOOTH_DENSKPP_SMOOTH_VISCKPP_SMOOTH_DIFFKPP_ESTIMATE_UREFINCLUDE_DIAGNOSTICS_INTERFACE_CODEKPP_GHATEXCLUDE_KPP_SHEAR_MIX

Run-time parameters are set in files datapkg and datakpp which are read in kpp_readparmsF Run-timeparameters may be broken into 3 categories (i) switching onoff the package at runtime (ii) required MITgcm flags(iii) package flags and parameters

The KPP package is switched on at runtime by setting useKPP = TRUE in datapkg

Required MITgcm flags

The following flagsparameters of the MITgcm dynamical kernel need to be set in conjunction with KPP

implicitViscosity = TRUE enable implicit vertical viscosityimplicitDiffusion = TRUE enable implicit vertical diffusion

Table 85 summarizes the runtime flags that are set in datapkg and their default values

Table 85 Runtime flags for KPPFlagparameter default DescriptionIO related parameterskpp_freq deltaTClock Recomputation frequency for KPP

fieldskpp_dumpFreq dumpFreq Dump frequency of KPP field snap-

shotskpp_taveFreq taveFreq Averaging and dump frequency of

KPP fieldsKPPmixingMaps FALSE include KPP diagnostic maps in

STDOUTContinued on next page

Table 85 ndash continued from previous pageFlagparameter default DescriptionKPPwriteState FALSE write KPP state to fileKPP_ghatUseTotalDiffus FALSE if T compute non-local term us-

ingtotal vertical diffusivityif F use KPP vertical diffusivity

General KPP parametersminKPPhbl delRc(1) Minimum boundary layer depthepsilon 01 nondimensional extent of the sur-

face layervonk 04 von Karman constantdB_dz 52E-5 sndash2 maximum dBdz in mixed layer

hMixconcs 9896concv 18Boundary layer parameters (SR bldepth)Ricr 03 critical bulk Richardson numbercekman 07 coefficient for Ekman depthcmonob 10 coefficient for Monin-Obukhov

depthconcv 18 ratio of interior to entrainment depth

buoyancy frequencyhbf 10 fraction of depth to which absorbed

solar radiation contributes to surfacebuoyancy forcing

Vtc non-dim coeff for velocity scale ofturbulant velocity shear ( = functionof concvconcsepsilonvonkRicr)

Boundary layer mixing parameters (SR blmix)cstar

10proportionality coefficient for non-local transport

cg non-dimensional coefficient forcounter-gradient term ( = functionof cstarvonkconcsepsilon)

Interior mixing parameters (SR Ri_iwmix)Riinfty 07 gradient Richardson number limit

for shear instabilityBVDQcon -02E-4 sndash2 Brunt-Vaumlisalauml squareddifm0 0005 m2 sndash1 viscosity max due to shear instabil-

itydifs0 0005 m2s tracer diffusivity max due to shear

instabilitydift0 0005 m2s heat diffusivity max due to shear

instabilitydifmcon 01 viscosity due to convective instabil-

itydifscon 01 tracer diffusivity due to convective

instabilitydiftcon 01 heat diffusivity due to convective in-

stabilityContinued on next page

Table 85 ndash continued from previous pageFlagparameter default DescriptionRrho0 not used limit for double diffusive density ra-

tiodsfmax not used maximum diffusivity in case of salt

fingering

We restrict ourselves to writing out only the essential equations that relate to main processes and parameters mentionedabove We closely follow the notation of [LMD94]

KPP_CALC

Top-level routine

KPP_MIX

Intermediate-level routine

BLMIX Mixing in the boundary layer

The vertical fluxes 119908119909 of momentum and tracer properties 119883 is composed of a gradient-flux term (proportional to thevertical property divergence 120597119911119883) and a ldquononlocalrdquo term 120574119909 that enhances the gradient-flux mixing coefficient 119870119909

119908119909(119889) = minus119870119909

(120597119883

120597119911minus 120574119909

)bull Boundary layer mixing profile It is expressed as the product of the boundary layer depth ℎ a depth-dependent

turbulent velocity scale 119908119909(120590) and a non-dimensional shape function 119866(120590)

119870119909(120590) = ℎ119908119909(120590)119866(120590)

with dimensionless vertical coordinate 120590 = 119889ℎ For details of mathlsquo w_x(sigma)lsquo and 119866(120590) we refer to

bull Nonlocal mixing term The nonlocal transport term 120574 is nonzero only for tracers in unstable (convective) forcingconditions Thus depending on the stability parameter 120577 = 119889119871 (with depth 119889 Monin-Obukhov length scale 119871)it has the following form

120574119909 = 0 120577 ge 0

120574119898 = 0

120574119904 = 1198621199041199081199040

119908119904(120590)ℎ

120574120579 = 1198621199041199081205790+119908120579119877119908119904(120590)ℎ

⎫⎪⎪⎪⎪⎪⎬⎪⎪⎪⎪⎪⎭120577 lt 0

In practice the routine peforms the following tasks

1 compute velocity scales at hbl

2 find the interior viscosities and derivatives at hbl

3 compute turbulent velocity scales on the interfaces

4 compute the dimensionless shape functions at the interfaces

5 compute boundary layer diffusivities at the interfaces

6 compute nonlocal transport term

7 find diffusivities at kbl-1 grid level

RI_IWMIX Mixing in the interior

Compute interior viscosity and diffusivity coefficients due to

bull shear instability (dependent on a local gradient Richardson number)

bull to background internal wave activity and

bull to static instability (local Richardson number lt 0)

TO BE CONTINUED

BLDEPTH Boundary layer depth calculation

The oceanic planetary boundary layer depth hbl is determined as the shallowest depth where the bulk Richardsonnumber is equal to the critical value Ricr

Bulk Richardson numbers are evaluated by computing velocity and buoyancy differences between values at zgrid(kl)lt 0 and surface reference values In this configuration the reference values are equal to the values in the surface layerWhen using a very fine vertical grid these values should be computed as the vertical average of velocity and buoyancyfrom the surface down to epsilonzgrid(kl)

When the bulk Richardson number at k exceeds Ricr hbl is linearly interpolated between grid levels zgrid(k) andzgrid(k-1)

The water column and the surface forcing are diagnosed for stableustable forcing conditions and where hbl is relativeto grid points (caseA) so that conditional branches can be avoided in later subroutines

TO BE CONTINUED

KPP_CALC_DIFF_T_S KPP_CALC_VISC

Add contribution to net diffusivityviscosity from KPP diffusivityviscosity

TO BE CONTINUED

KPP_TRANSPORT_T_S_PTR

Add non local KPP transport term (ghat) to diffusive temperaturesalinitypassive tracer flux The nonlocal transportterm is nonzero only for scalars in unstable (convective) forcing conditions

TO BE CONTINUED

Implicit time integration

TO BE CONTINUED

Penetration of shortwave radiation

TO BE CONTINUED

8425 Flow chart

8426 KPP diagnostics

Diagnostics output is available via the diagnostics package (see Section [secpkgdiagnostics]) Available output fieldsare summarized here

------------------------------------------------------KPPviscA| 23 |SM |m^2s |KPP vertical eddy viscosity coefficientKPPdiffS| 23 |SM |m^2s |Vertical diffusion coefficient for salt amp tracersKPPdiffT| 23 |SM |m^2s |Vertical diffusion coefficient for heatKPPghat | 23 |SM |sm^2 |Nonlocal transport coefficientKPPhbl | 1 |SM |m |KPP boundary layer depth bulk Ri criterionKPPmld | 1 |SM |m |Mixed layer depth dT=8degC density criterionKPPfrac | 1 |SM | |Short-wave flux fraction penetrating mixing layer

lab_sea

natl_box

8428 References

8429 Experiments and tutorials that use kpp

bull Labrador Sea experiment in lab_sea verification directory

843 GGL90 a TKE vertical mixing scheme

(in directory pkgggl90 )

see [GGL90]

8432 Experiments and tutorials that use GGL90

bull Vertical mixing verification experiment (vermixinputggl90)

844 OPPS Ocean Penetrative Plume Scheme

(in directory pkgopps )

See [PR97]

8442 Experiments and tutorials that use OPPS

bull Vertical mixing verification experiment (vermixinputopps)

845 KL10 Vertical Mixing Due to Breaking Internal Waves

(in directory pkgkl10 )

Authors Jody M Klymak

8451 Introduction

The [KL10] parameterization for breaking internal waves is meant to represent mixing in the ocean ldquointeriorrdquo due toconvective instability Many mixing schemes in the presence of unstable stratification simply turn on an arbitrarilylarge diffusivity and viscosity in the overturning region This assumes the fluid completely mixes which is proba-bly not a terrible assumption but it also makes estimating the turbulence dissipation rate in the overturning regionmeaningless

The KL10 scheme overcomes this limitation by estimating the viscosity and diffusivity from a combination of theOzmidov relation and the Osborn relation assuming a turbulent Prandtl number of one The Ozmidov relation saysthat outer scale of turbulence in an overturn will scale with the strength of the turbulence 120598 and the stratification 119873 as

1198712119874 asymp 120598119873minus3 (81)

The Osborn relation relates the strength of the dissipation to the vertical diffusivity as

119870119907 = Γ120598119873minus2

where Γ asymp 02 is the mixing ratio of buoyancy flux to thermal dissipation due to the turbulence Combining the twogives us

119870119907 asymp Γ1198712119874119873

The ocean turbulence community often approximates the Ozmidov scale by the root-mean-square of the Thorpe dis-placement 120575119911 in an overturn [Tho77] The Thorpe displacement is the distance one would have to move a water parcelfor the water column to be stable and is readily measured in a measured profile by sorting the profile and trackinghow far each parcel moves during the sorting procedure This method gives an imperfect estimate of the turbulencebut it has been found to agree on average over a large range of overturns [WG94][SG94][Mou96]

The algorithm coded here is a slight simplification of the usual Thorpe method for estimating turbulence in overturningregions Usually overturns are identified and 119873 is averaged over the overturn Here instead we estimate

119870119907(119911) asymp Γ1205752119911 119873119904(119911)

where 119873119904(119911) is the local sorted stratification This saves complexity in the code and adds a slight inaccuracy but wedonrsquot believe is biased

We assume a turbulent Prandtl number of 1 so 119860119907 = 119870119907

We also calculate and output a turbulent dissipation from this scheme We do not simply evaluate the overturns for 120598using ([eqpkgkl10Lo]) Instead we compute the vertical shear terms that the viscosity is acting on

120598119907 = 119860119907

((120597119906

120597119911

(120597119907

120597119911

There are straightforward caveats to this approach covered in [KL10]

bull If your resolution is too low to resolve the breaking internal waves you wonrsquot have any turbulence

bull If the model resolution is too high the estimates of 120598119907 will start to be exaggerated particularly if the run innon-hydrostatic That is because there will be significant shear at small scales that represents the turbulencebeing parameterized in the scheme At very high resolutions direct numerical simulation or more sophisticatedlarge-eddy schemes should be used

bull We find that grid cells of approximately 10 to 1 aspect ratio are a good rule of thumb for achieving goodresults are usual oceanic scales For a site like the Hawaiian Ridge and Luzon Strait this means 10-m verticalresolusion and approximately 100-m horizontal The 10-m resolution can be relaxed if the stratification dropsand we often WKB-stretch the grid spacing with depth

bull The dissipation estimate is useful for pinpoiting the location of turbulence but again is grid size dependent tosome extent and should be treated with a grain of salt It will also not include any numerical dissipation suchas you may find with higher order advection schemes

8452 KL10 configuration and compiling

As with all MITgcm packages KL10 can be turned on or off at compile time

bull using the packagesconf file by adding kl10 to it

bull or using genmake2 adding -enable=kl10 or -disable=kl10 switches

bull Required packages and CPP options No additional packages are required

KL10 has no compile-time options (KL10_OPTIONSh is empty)

Run-time parameters are set in files datapkg and datakl10 which are read in kl10_readparmsF Run-time parameters may be broken into 3 categories (i) switching onoff the package at runtime (ii) required MITgcmflags (iii) package flags and parameters

The KL10 package is switched on at runtime by setting useKL10 = TRUE in datapkg

The following flagsparameters of the MITgcm dynamical kernel need to be set in conjunction with KL10

Table 86 summarizes the runtime flags that are set in datakl10 and their default values

Table 86 KL10 runtime parametersFlagparameter default DescriptionKLviscMax 300 m2 sndash1 Maximum viscosity the scheme will ever give (useful for stability)KLdumpFreq dumpFreq Dump frequency of KL10 field snapshotsKLtaveFreq taveFreq Averaging and dump frequency of KL10 fieldsKLwriteState FALSE write KL10 state to file

KL10_CALC

Top-level routine Calculates viscosity and diffusivity on the grid cell centers Note that the runtime parametersviscAz and diffKzT act as minimum viscosity and diffusivities So if there are no overturns (or they are weak)then these will be returned

KL10_CALC_VISC

Calculates viscosity on the W and S grid faces for U and V respectively

KL10_CALC_DIFF

Calculates the added diffusion from KL10

8455 KL10 diagnostics

------------------------------------------------------KLviscAr| Nr |SM |m^2s |KL10 vertical eddy viscosity coefficientKLdiffKr| Nr |SM |m^2s |Vertical diffusion coefficient for saltrarr˓temperature amp tracersKLeps | Nr |SM |m^3s^3 |Turbulence dissipation estimate

8456 References

Klymak and Legg 2010 Oc Modell

8457 Experiments and tutorials that use KL10

bull Modified Internal Wave experiment in internal_wave verification directory

846 BULK_FORCE Bulk Formula Package

author Stephanie Dutkiewicz

Instead of forcing the model with heat and fresh water flux data this package calculates these fluxes using the changingsea surface temperature We need to read in some atmospheric data air temperature air humidity down shortwaveradiation down longwave radiation precipitation wind speed The current setup also reads in wind stress butthis can be changed so that the stresses are calculated from the wind speed

The current setup requires that there is the thermodynamic-seaice package (pkgthsice also refered below as seaice) isalso used It would be useful though to have it also setup to run with some very simple parametrization of the sea ice

The heat and fresh water fluxes are calculated in bulkf_forcingF called from forward_stepF These fluxes are usedover open water fluxes over seaice are recalculated in the sea-ice package Before the call to bulkf_forcingF we callbulkf_fields_loadF to find the current atmospheric conditions The only other changes to the model code come fromthe initializing and writing diagnostics of these fluxes

8461 subroutine BULKF_FIELDS_LOAD

Here we find the atmospheric data needed for the bulk formula calculations These are read in at periodic intervals andvalues are interpolated to the current time The data file names come from datablk The values that can be read inare air temperature air humidity precipitation down solar radiation down long wave radiation zonal and meridionalwind speeds total wind speed net heat flux net freshwater forcing cloud cover snow fall zonal and meridional windstresses and SST and SSS used for relaxation terms Not all these files are necessary or used For instance cloud coverand snow fall are not used in the current bulk formula calculation If total wind speed is not supplied wind speed iscalculate from the zonal and meridional components If wind stresses are not read in then the stresses are calculatedfrom the wind speed Net heat flux and net freshwater can be read in and used over open ocean instead of the bulk

formula calculations (but over seaice the bulkf formula is always used) This is ldquohardwiredrdquo into bulkf_forcing and theldquochrdquo in the variable names suggests that this is ldquocheatingrdquo SST and SSS need to be read in if there is any relaxationused

8462 subroutine BULKF_FORCING

In bulkf_forcingF we calculate heat and fresh water fluxes (and wind stress if necessary) for each grid cell Firstwe determine if the grid cell is open water or seaice and this information is carried by iceornot There is a provisionhere for a different designation if there is snow cover (but currently this does not make any difference) We then callbulkf_formula_lanlF which provides values for up long wave radiation latent and sensible heat fluxes the derivativeof these three with respect to surface temperature wind stress evaporation Net long wave radiation is calculated fromthe combination of the down long wave read in and the up long wave calculated

We then find the albedo of the surface - with a call to sfc_albedo if there is sea-ice (see the seaice package forinformation on the subroutine) If the grid cell is open ocean the albedo is set as 01 Note that this is a parameter thatcan be used to tune the results The net short wave radiation is then the down shortwave radiation minus the amountreflected

If the wind stress needed to be calculated in bulkf_formula_lanlF it was calculated to grid cell center points so inbulkf_forcingF we regrid to u and v points We let the model know if it has read in stresses or calculated stresses bythe switch readwindstress which is can be set in datablk and defaults to TRUE

We then calculate Qnet and EmPmR that will be used as the fluxes over the open ocean There is a provision forusing runoff If we are ldquocheatingrdquo and using observed fluxes over the open ocean then there is a provision here to useread in Qnet and EmPmR

The final call is to calculate averages of the terms found in this subroutine

8463 subroutine BULKF_FORMULA_LANL

This is the main program of the package where the heat fluxes and freshwater fluxes over ice and open water arecalculated Note that this subroutine is also called from the seaice package during the iterations to find the ice surfacetemperature

Latent heat (119871) used in this subroutine depends on the state of the surface vaporization for open water fusion andvaporization for ice surfaces Air temperature is converted from Celsius to Kelvin If there is no wind speed (119906119904)given then the wind speed is calculated from the zonal and meridional components

We calculate the virtual temperature

119879119900 = 119879119886119894119903(1 + 120574119902119886119894119903)

where 119879119886119894119903 is the air temperature at ℎ119879 119902119886119894119903 is humidity at ℎ119902 and 120574 is a constant

The saturated vapor pressure is calculate (QQ ref)

119902119904119886119905 =119886

119901119900119890119871(119887minus 119888

119879119904119903119891)

where 119886 119887 119888 are constants 119879119904119903119891 is surface temperature and 119901119900 is the surface pressure

The two values crucial for the bulk formula calculations are the difference between air at sea surface and sea surfacetemperature

∆119879 = 119879119886119894119903 minus 119879119904119903119891 + 120572ℎ119879

where 120572 is adiabatic lapse rate and ℎ119879 is the height where the air temperature was taken and the difference betweenthe air humidity and the saturated humidity

∆119902 = 119902119886119894119903 minus 119902119904119886119905

We then calculate the turbulent exchange coefficients following Bryan et al (1996) and the numerical scheme of Hunkeand Lipscombe (1998) We estimate initial values for the exchange coefficients 119888119906 119888119879 and 119888119902 as

120581

119897119899(119911119903119890119891119911119903119900119906)

where 120581 is the Von Karman constant 119911119903119890119891 is a reference height and 119911119903119900119906 is a roughness length scale which could be afunction of type of surface but is here set as a constant Turbulent scales are

119906 = 119888119906119906119904

119879 = 119888119879 ∆119879

119902 = 119888119902∆119902

We find the ldquointegrated flux profilerdquo for momentum and stability if there are stable QQ conditions (Υ gt 0)

120595119898 = 120595119904 = minus5Υ

and for unstable QQ conditions (Υ lt 0)

120595119898 = 2119897119899(05(1 + 120594)) + 119897119899(05(1 + 1205942)) minus 2 tanminus1 120594+ 1205872

120595119904 = 2119897119899(05(1 + 1205942))

Υ =1205811198921199111199031198901198911199062

(119879

119879119900+

119902

1120574 + 119902119886)

and 120594 = (1 minus 16Υ)12

The coefficients are updated through 5 iterations as

119888119906 =119888119906

1 + 119888119906(120582minus 120595119898)120581

119888119879 =119888119879

1 + 119888119879 (120582minus 120595119904)120581

119888119902 = 119888prime119879

where 120582 = 119897119899(ℎ119879 119911119903119890119891 )

We can then find the bulk formula heat fluxes

Sensible heat flux

119876119904 = 120588119886119894119903119888119901119886119894119903119906119904119888119906119888119879 ∆119879

Latent heat flux

119876119897 = 120588119886119894119903119871119906119904119888119906119888119902∆119902

Up long wave radiation

119876119906119901119897119908 = 120598120590119879 4

119904119903119891

where 120598 is emissivity (which can be different for open ocean ice and snow) 120590 is Stefan-Boltzman constant

We calculate the derivatives of the three above functions with respect to surface temperature

119889119876119904

119889119879= 120588119886119894119903119888119901119886119894119903

119906119904119888119906119888119879

119889119876119897

119889119879=

1205881198861198941199031198712119906119904119888119906119888119902119888

119879 2119904119903119891

119889119876119906119901]119897119908

119889119879= 41205981205901199053119904119903119891

And total derivative 119889119876119900

119889119879 = 119889119876119904

119889119879 + 119889119876119897

119889119879 +119889119876119906119901

119897119908

119889119879

If we do not read in the wind stress it is calculated here

8464 Initializing subroutines

bulkf_initF Set bulkf variables to zero

bulkf_readparmsF Reads datablk

8465 Diagnostic subroutines

bulkf_aveF Keeps track of means of the bulkf variables

bulkf_diagsF Finds averages and writes out diagnostics

8466 Common Blocks

BULKFh BULKF Variables data file names and logicals readwindstress and readsurface

BULKF_DIAGSh matrices for diagnostics averages of fields from bulkf_diagsF

BULKF_ICE_CONSTANTSh all the parameters needed by the ice model and in the bulkf formula calculations

8467 Input file DATAICE

We read in the file names of atmospheric data used in the bulk formula calculations Here we can also set the logicalsreadwindstress if we read in the wind stress rather than calculate it from the wind speed and readsurface to read inthe surface temperature and salinity if these will be used as part of a relaxing term

8468 Important Notes

1 heat fluxes have different signs in the ocean and ice models

2 StartIceModel must be changed in dataice 1 (if starting from no ice) 0 (if using pickupic file)

8469 References

Bryan FO BG Kauffman WG Large PR Gent 1996 The NCAR CSM flux coupler Technical note TN-425+STRNCAR

Hunke EC and WH Lipscomb circa 2001 CICE the Los Alamos Sea Ice Model Documentation and SoftwareUserrsquos Manual LACC-98-16v2 (note this documentation is no longer available as CICE has progressed to a verydifferent version 3)

84610 Experiments and tutorials that use bulk_force

bull Global ocean experiment in global_oceancs32x15 verification directory input from inputthsice directory

847 EXF The external forcing package

Authors Patrick Heimbach and Dimitris Menemenlis

8471 Introduction

The external forcing package in conjunction with the calendar package (cal) enables the handling of real-time (orldquomodel-timerdquo) forcing fields of differing temporal forcing patterns It comprises climatological restoring and re-laxation Bulk formulae are implemented to convert atmospheric fields to surface fluxes An interpolation routineprovides on-the-fly interpolation of forcing fields an arbitrary grid onto the model grid

CPP options enable or disable different aspects of the package (Section [secpkgexfconfig]) Runtime options flagsfilenames and field-related datestimes are set in dataexf (Section [secpkgexfruntime]) A description of keysubroutines is given in Section [secpkgexfsubroutines] Input fields units and sign conventions are summarized inSection [secpkgexffieldssubunits] and available diagnostics output is listed in Section [secpkgexfdiagnostics]

8472 EXF configuration compiling amp running

Compile-time options

As with all MITgcm packages EXF can be turned on or off at compile time

bull using the packagesconf file by adding exf to it

bull or using genmake2 adding -enable=exf or -disable=exf switches

bull required packages and CPP options EXF requires the calendar package cal to be enabled no additional CPPoptions are required

Parts of the EXF code can be enabled or disabled at compile time via CPP preprocessor flags These options are set ineither EXF_OPTIONSh or in ECCO_CPPOPTIONSh Table 87 summarizes these options

Table 87 EXF CPP optionsCPP option DescriptionEXF_VERBOSE verbose mode (recommended only for testing)ALLOW_ATM_TEMP compute heatfreshwater fluxes from atmos state inputALLOW_ATM_WIND compute wind stress from wind speed inputALLOW_BULKFORMULAE is used if ALLOW_ATM_TEMP or ALLOW_ATM_WIND is enabledEXF_READ_EVAP read evaporation instead of computing itALLOW_RUNOFF read time-constant riverglacier run-off fieldALLOW_DOWNWARD_RADIATION compute net from downward or downward from net radiationUSE_EXF_INTERPOLATION enable on-the-fly bilinear or bicubic interpolation of input fieldsused in conjunction with relaxation to prescribed (climatological) fieldsALLOW_CLIMSST_RELAXATION relaxation to 2-D SST climatologyALLOW_CLIMSSS_RELAXATION relaxation to 2-D SSS climatologythese are set outside of EXF in CPP_OPTIONShSHORTWAVE_HEATING enable shortwave radiationATMOSPHERIC_LOADING enable surface pressure forcing

Run-time parameters are set in files datapkg and dataexf which is read in exf_readparmsF Run-timeparameters may be broken into 3 categories (i) switching onoff the package at runtime (ii) general flags and param-eters and (iii) attributes for each forcing and climatological field

A package is switched onoff at runtime by setting (eg for EXF) useEXF = TRUE in datapkg

General flags and parameters

Table 88 EXF runtime optionsFlagparameter default DescriptionuseExfCheckRange TRUE check range of input fields and stop if out of rangeuseExfYearlyFields FALSE append current year postfix of form _YYYY on filenametwoDigitYear FALSE instead of appending _YYYY append YYrepeatPeriod 00 gt 0 cycle through all input fields at the same period (in seconds)

= 0 use period assigned to each fieldexf_offset_atemp 00 set to 27316 to convert from deg Kelvin (assumed input) to Celsiuswindstressmax 20 max allowed wind stress N mndash2

exf_albedo 01 surface albedo used to compute downward vs net radiative fluxesclimtempfreeze -19 ocean_emissivity longwave ocean-surface emissivityice_emissivity longwave seaice emissivitysnow_emissivity longwave snow emissivityexf_iceCd 163E-3 drag coefficient over sea-iceexf_iceCe 163E-3 evaporation transfer coeff over sea-iceexf_iceCh 163E-3 sensible heat transfer coeff over sea-iceexf_scal_BulkCdn 10 overall scaling of neutral drag coeff

Table 88 ndash continued from previous pageFlagparameter default DescriptionuseStabilityFct_overIce FALSE compute turbulent transfer coeff over sea-icereadStressOnAgrid FALSE read wind-streess located on model-grid A-grid pointreadStressOnCgrid FALSE read wind-streess located on model-grid C-grid pointuseRelativeWind FALSE subtract [UV]VEL or [UVICE from UV]WIND before computing [UV]STRESSzref 100 reference heighthu 100 height of mean windht 20 height of mean temperature and rel humidityumin 05 minimum absolute wind speed for computing Cdatmrho 12 mean atmospheric density [kgm^3]atmcp 10050 mean atmospheric specific heat [JkgK]cdrag_[n] n = 123 parameters for drag coeff functioncstanton_[n] n = 12 parameters for Stanton number functioncdalton parameter for Dalton number functionflamb 25000000 latent heat of evaporation [Jkg]flami 3340000 latent heat of melting of pure ice [Jkg]zolmin -1000 minimum stability parametercvapor_fac 6403800cvapor_exp 51074cvapor_fac_ice 116378000cvapor_fac_ice 58978humid_fac 0606 parameter for virtual temperature calculationgamma_blk 0010 adiabatic lapse ratesaltsat 0980 reduction of saturation vapor pressure over salt-waterpsim_fac 50exf_monFreq monitorFreq output frequency [s]exf_iprec 32 precision of input fields (32-bit or 64-bit)exf_yftype lsquoRLrsquo precision of arrays (lsquoRLrsquo vs lsquoRSrsquo)

Field attributes

All EXF fields are listed in Section [secpkgexffieldssubunits] Each field has a number of attributes which can becustomized They are summarized in Table [tabpkgexfruntimesubattributes] To obtain an attribute for a specificfield eg uwind prepend the field name to the listed attribute eg for attribute period this yields uwindperiod

field amp attribute minusrarr parametereg uwind amp period minusrarr uwindperiod

Table 89 EXF runtime attributes Note there is one exception for thedefault of atempconst = celsius2K = 27316

attribute Default Descriptionfield file lsquo lsquo filename if left empty no file will be read const will be used

insteadfield const 00 constant that will be used if no file is readfield startdate1 00 format YYYYMMDD start year (YYYY) month (MM) day (YY)

of field to determine record numberfield startdate2 00 format HHMMSS start hour (HH) minute (MM) second(SS)

of field to determine record numberfield period 00 interval in seconds between two recordsexf_inscal_field optional rescaling of input fields to comply with EXF unitsexf_outscal_field optional rescaling of EXF fields when mapped onto MITgcm fieldsused in conjunction with EXF_USE_INTERPOLATIONfield _lon0 xgOrigin+delX

2starting longitude of input

field _lon_inc delX increment in longitude of inputfield _lat0 ygOrigin+delY

2starting latitude of input

field _lat_inc delY increment in latitude of inputfield _nlon Nx number of grid points in longitude of inputfield _nlat Ny number of grid points in longitude of input

Example configuration

The following block is taken from the dataexf file of the verification experiment global_with_exf Itdefines attributes for the heat flux variable hflux

hfluxfile = ncep_qnetbinhfluxstartdate1 = 19920101hfluxstartdate2 = 000000hfluxperiod = 25920000hflux_lon0 = 2hflux_lon_inc = 4hflux_lat0 = -78hflux_lat_inc = 394hflux_nlon = 90hflux_nlat = 40

EXF will read a file of name rsquoncep_qnetbinrsquo Its first record represents January 1st 1992 at 0000 UTC Next recordis 2592000 seconds (or 30 days) later Note that the first record read and used by the EXF package corresponds tothe value rsquostartDate1rsquo set in datacal Therefore if you want to start the EXF forcing from later in the rsquoncep_qnetbinrsquofile it suffices to specify startDate1 in datacal as a date later than 19920101 (for example startDate1 = 19940101for starting January 1st 1994) For this to work rsquoncep_qnetbinrsquo must have at least 2 years of data because in thisconfiguration EXF will read 2 years into the file to find the 1994 starting value Interpolation on-the-fly is used (inthe present case trivially on the same grid but included nevertheless for illustration) and input field grid startingcoordinates and increments are supplied as well

8474 EXF bulk formulae

TBD (cross-ref to parameter list table)

8475 EXF input fields and units

The following list is taken from the header file EXF_FIELDSh It comprises all EXF input fields

Output fields which EXF provides to the MITgcm are fields fu fv Qnet Qsw EmPmR and pload They are definedin FFIELDSh

c----------------------------------------------------------------------c |c field Descriptionc |c----------------------------------------------------------------------c ustress Zonal surface wind stress in Nm^2c | gt 0 for increase in uVel which is west toc | east for cartesian and spherical polar gridsc | Typical range -05 lt ustress lt 05c | Southwest C-grid U pointc | Input fieldc----------------------------------------------------------------------c vstress Meridional surface wind stress in Nm^2c | gt 0 for increase in vVel which is south toc | north for cartesian and spherical polar gridsc | Typical range -05 lt vstress lt 05c | Southwest C-grid V pointc | Input fieldc----------------------------------------------------------------------c hs sensible heat flux into ocean in Wm^2c | gt 0 for increase in theta (ocean warming)c----------------------------------------------------------------------c hl latent heat flux into ocean in Wm^2c | gt 0 for increase in theta (ocean warming)c----------------------------------------------------------------------c hflux Net upward surface heat flux in Wm^2c | (including shortwave)c | hflux = latent + sensible + lwflux + swfluxc | gt 0 for decrease in theta (ocean cooling)c | Typical range -250 lt hflux lt 600c | Southwest C-grid tracer pointc | Input fieldc----------------------------------------------------------------------c sflux Net upward freshwater flux in msc | sflux = evap - precip - runoffc | gt 0 for increase in salt (ocean salinity)c | Typical range -1e-7 lt sflux lt 1e-7c | Southwest C-grid tracer pointc | Input fieldc----------------------------------------------------------------------c swflux Net upward shortwave radiation in Wm^2c | swflux = - ( swdown - ice and snow absorption - reflected )c | gt 0 for decrease in theta (ocean cooling)c | Typical range -350 lt swflux lt 0c | Southwest C-grid tracer pointc | Input fieldc----------------------------------------------------------------------c uwind Surface (10-m) zonal wind velocity in msc | gt 0 for increase in uVel which is west toc | east for cartesian and spherical polar gridsc | Typical range -10 lt uwind lt 10

c | Southwest C-grid U pointc | Input or inputoutput fieldc----------------------------------------------------------------------c vwind Surface (10-m) meridional wind velocity in msc | gt 0 for increase in vVel which is south toc | north for cartesian and spherical polar gridsc | Typical range -10 lt vwind lt 10c | Southwest C-grid V pointc | Input or inputoutput fieldc----------------------------------------------------------------------c wspeed Surface (10-m) wind speed in msc | gt= 0 sqrt(u^2+v^2)c | Typical range 0 lt wspeed lt 10c | Input or inputoutput fieldc----------------------------------------------------------------------c atemp Surface (2-m) air temperature in deg Kc | Typical range 200 lt atemp lt 300c | Southwest C-grid tracer pointc | Input or inputoutput fieldc----------------------------------------------------------------------c aqh Surface (2m) specific humidity in kgkgc | Typical range 0 lt aqh lt 002c | Southwest C-grid tracer pointc | Input or inputoutput fieldc----------------------------------------------------------------------c lwflux Net upward longwave radiation in Wm^2c | lwflux = - ( lwdown - ice and snow absorption - emitted )c | gt 0 for decrease in theta (ocean cooling)c | Typical range -20 lt lwflux lt 170c | Southwest C-grid tracer pointc | Input fieldc----------------------------------------------------------------------c evap Evaporation in msc | gt 0 for increase in salt (ocean salinity)c | Typical range 0 lt evap lt 25e-7c | Southwest C-grid tracer pointc | Input inputoutput or output fieldc----------------------------------------------------------------------c precip Precipitation in msc | gt 0 for decrease in salt (ocean salinity)c | Typical range 0 lt precip lt 5e-7c | Southwest C-grid tracer pointc | Input or inputoutput fieldc----------------------------------------------------------------------c snowprecip snow in msc | gt 0 for decrease in salt (ocean salinity)c | Typical range 0 lt precip lt 5e-7c | Input or inputoutput fieldc----------------------------------------------------------------------c runoff River and glacier runoff in msc | gt 0 for decrease in salt (ocean salinity)c | Typical range 0 lt runoff lt c | Southwest C-grid tracer pointc | Input or inputoutput fieldc | WATCH OUT Default exf_inscal_runoff c | in exf_readparmsF is not 10 c----------------------------------------------------------------------

c swdown Downward shortwave radiation in Wm^2c | gt 0 for increase in theta (ocean warming)c | Typical range 0 lt swdown lt 450c | Southwest C-grid tracer pointc | Inputoutput fieldc----------------------------------------------------------------------c lwdown Downward longwave radiation in Wm^2c | gt 0 for increase in theta (ocean warming)c | Typical range 50 lt lwdown lt 450c | Southwest C-grid tracer pointc | Inputoutput fieldc----------------------------------------------------------------------c apressure Atmospheric pressure field in Nm^2c | gt 0 for c | Typical range lt apressure lt c | Southwest C-grid tracer pointc | Input fieldc----------------------------------------------------------------------

8476 Key subroutines

Top-level routine exf_getforcingF

c | oc |c |-- lt hflux is sum of sensible latent longwave rad gtc |-- lt sflux is sum of evap minus precip minus runoff gtc |c |-- exf_getsurfacefluxesc | If forcing and control is flux then thec | control vector anomalies are read here via ctrl_get_genc | (hflux sflux ustress vstress)c |c |-- lt update tile edges here gtc |c |-- exf_check_rangec | | Check whether read fields are within assumed rangec | | (may capture mismatches in units)c | oc |c |-- lt add shortwave to hflux for diagnostics gtc |c |-- exf_diagnostics_fillc | | Do EXF-related diagnostics output herec | oc |c |-- exf_mapfieldsc | | Forcing fields from exf package are mapped ontoc | | mitgcm forcing arraysc | | Mapping enables a runtime rescaling of fieldsc | oC o

Radiation calculation exf_radiationF

Wind speed and stress calculation exf_windF

Bulk formula exf_bulkformulaeF

Generic IO exf_set_genF

Interpolation exf_interpF

Header routines

8477 EXF diagnostics

Diagnostics output is available via the diagnostics package (see Section [secpkgdiagnostics]) Available output fieldsare summarized below

---------+----+----+----------------+-----------------lt-Name-gt|Levs|grid|lt-- Units --gt|lt- Tile (max=80c)

---------+----+----+----------------+-----------------EXFhs | 1 | SM | Wm^2 | Sensible heat flux into ocean gt0 increasesrarr˓thetaEXFhl | 1 | SM | Wm^2 | Latent heat flux into ocean gt0 increases thetaEXFlwnet| 1 | SM | Wm^2 | Net upward longwave radiation gt0 decreasesrarr˓thetaEXFswnet| 1 | SM | Wm^2 | Net upward shortwave radiation gt0 decreasesrarr˓theta

EXFlwdn | 1 | SM | Wm^2 | Downward longwave radiation gt0 increases thetaEXFswdn | 1 | SM | Wm^2 | Downward shortwave radiation gt0 increases thetaEXFqnet | 1 | SM | Wm^2 | Net upward heat flux (turb+rad) gt0 decreasesrarr˓thetaEXFtaux | 1 | SU | Nm^2 | zonal surface wind stress gt0 increases uVelEXFtauy | 1 | SV | Nm^2 | meridional surface wind stress gt0 increasesrarr˓vVelEXFuwind| 1 | SM | ms | zonal 10-m wind speed gt0 increases uVelEXFvwind| 1 | SM | ms | meridional 10-m wind speed gt0 increases uVelEXFwspee| 1 | SM | ms | 10-m wind speed modulus ( gt= 0 )EXFatemp| 1 | SM | degK | surface (2-m) air temperatureEXFaqh | 1 | SM | kgkg | surface (2-m) specific humidityEXFevap | 1 | SM | ms | evaporation gt 0 increases salinityEXFpreci| 1 | SM | ms | evaporation gt 0 decreases salinityEXFsnow | 1 | SM | ms | snow precipitation gt 0 decreases salinityEXFempmr| 1 | SM | ms | net upward freshwater flux gt 0 increasesrarr˓salinityEXFpress| 1 | SM | Nm^2 | atmospheric pressure field

8478 References

8479 Experiments and tutorials that use exf

bull Global Ocean experiment in global_with_exf verification directory

848 CAL The calendar package

Authors Christian Eckert and Patrick Heimbach

This calendar tool was originally intended to enable the use of absolute dates (Gregorian Calendar dates) in MITgcmThere is however a fair number of routines that can be used independently of the main MITgcm executable Aftersome minor modifications the whole package can be used either as a stand-alone calendar or in connection with anydynamical model that needs calendar dates Some straightforward extensions are still pending eg the availability ofthe Julian Calendar to be able to resolve fractions of a second and to have a timestep that is longer than one day

8481 Basic assumptions for the calendar tool

It is assumed that the SMALLEST TIME INTERVAL to be resolved is ONE SECOND

Further assumptions are that there is an INTEGER NUMBER OF MODEL STEPS EACH DAY and that AT LEASTONE STEP EACH DAY is made

Not each individual routine depends on these assumptions there are only a few places where they enter

8482 Format of calendar dates

In this calendar tool a complete date specification is defined as the following integer array

c integer date(4)cc ( yyyymmdd hhmmss leap_year dayofweek )cc date(1) = yyyymmdd lt-- Year-Month-Dayc date(2) = hhmmss lt-- Hours-Minutes-Secondsc date(3) = leap_year lt-- Leap YearNo Leap Yearc date(4) = dayofweek lt-- Day of the Weekcc leap_year is either equal to 1 (normal year)c or equal to 2 (leap year)cc dayofweek has a range of 1 to 7

In case the Gregorian Calendar is used the first day of the week is Friday since day of the Gregorian Calendar wasFriday 15 Oct 1582 As a date array this date would be specified as

c refdate(1) = 15821015c refdate(2) = 0c refdate(3) = 1c refdate(4) = 1

8483 Calendar dates and time intervals

Subtracting calendar dates yields time intervals Time intervals have the following format

c integer datediff(4)cc datediff(1) = Daysc datediff(2) = hhmmssc datediff(3) = 0c datediff(4) = -1

Such time intervals can be added to or can be subtracted from calendar dates Time intervals can be added to and besubtracted from each other

8484 Using the calendar together with MITgcm

Each routine has as an argument the thread number that it is belonging to even if this number is not used in the routineitself

In order to include the calendar tool into the MITgcm setup the MITgcm subroutine ldquoinitialiseFrdquo or the routineldquoinitilise_fixedFrdquo depending on the MITgcm release has to be modified in the following way

c ifdef ALLOW_CALENDARc C-- Initialise the calendar packagec ifdef USE_CAL_NENDITERc CALL cal_Init(c I startTimec I endTimec I deltaTclockc I nIter0c I nEndIterc I nTimeStepsc I myThid

c amp )c elsec CALL cal_Init(c I startTimec I endTimec I deltaTclockc I nIter0c I nTimeStepsc I myThidc amp )c endifc _BARRIERc endif

It is useful to have the CPP flag ALLOW_CALENDAR in order to switch from the usual MITgcm setup to the onethat includes the calendar tool The CPP flag USE_CAL_NENDITER has been introduced in order to enable the useof the calendar for MITgcm releases earlier than checkpoint 25 which do not have the global variable nEndIter

8485 The individual calendars

Simple model calendar

This calendar can be used by defining

c TheCalendar=model

in the calendarrsquos data file ldquodatacalrdquo

In this case a year is assumed to have 360 days The model year is divided into 12 months with 30 days each

Gregorian Calendar

c TheCalendar=gregorian

8486 Short routine description

c o cal_Init - Initialise the calendar This is the interfacec to MITgcmcc o cal_Set - Sets the calendar according to the userc specificationscc o cal_GetDate - Given the models current timestep or thec models current time return the correspondingc calendar datecc o cal_FullDate - Complete a date specification (leap year andc day of the week)cc o cal_IsLeap - Determine whether a given year is a leap yearc

c o cal_TimePassed - Determine the time passed between two datescc o cal_AddTime - Add a time interval either to a time intervalc or to a datecc o cal_TimeInterval - Given a time interval return the correspondingc date arraycc o cal_SubDates - Determine the time interval between two datesc or between two time intervalscc o cal_ConvDate - Decompose a date array or a time intervalc array into its componentscc o cal_CopyDate - Copy a date array or a time interval array toc another arraycc o cal_CompDates - Compare two calendar dates or time intervalscc o cal_ToSeconds - Given a time interval array return the numberc of secondscc o cal_WeekDay - Return the weekday as a string given thec calendar datecc o cal_NumInts - Return the number of time intervals between twoc given datescc o cal_StepsPerDay - Given an iteration number or the currentc integration time return the number of timec steps to integrate in the current calendar daycc o cal_DaysPerMonth - Given an iteration number or the currentc integration time return the number of daysc to integrate in this calendar monthcc o cal_MonthsPerYear - Given an iteration number or the currentc integration time return the number of monthsc to integrate in the current calendar yearcc o cal_StepsForDay - Given the integration day return the numberc of steps to be integrated the first stepc and the last step in the day specified Thec first and the last step refer to the totalc number of steps (1 cal_IntSteps)cc o cal_DaysForMonth - Given the integration month return the numberc of days to be integrated the first dayc and the last day in the month specified Thec first and the last day refer to the totalc number of steps (1 cal_IntDays)cc o cal_MonthsForYear - Given the integration year return the numberc of months to be integrated the first monthc and the last month in the year specified Thec first and the last step refer to the totalc number of steps (1 cal_IntMonths)

cc o cal_Intsteps - Return the number of calendar years that arec affected by the current integrationcc o cal_IntDays - Return the number of calendar days that arec affected by the current integrationcc o cal_IntMonths - Return the number of calendar months that arec affected by the current integrationcc o cal_IntYears - Return the number of calendar years that arec affected by the current integrationcc o cal_nStepDay - Return the number of time steps that can bec performed during one calendar daycc o cal_CheckDate - Do some simple checks on a date array or on ac time interval arraycc o cal_PrintError - Print error messages according to the flagsc raised by the calendar routinescc o cal_PrintDate - Print a date array in some format suitable forc MITgcms protocol outputcc o cal_TimeStamp - Given the time and the iteration number returnc the date and print all the above numberscc o cal_Summary - List all the setttings of the calendar tool

8487 Experiments and tutorials that use cal

bull Global ocean experiment in global_with_exf verification directory

85 Atmosphere Packages

851 Atmospheric Intermediate Physics AIM

Note The folowing document below describes the aim_v23 package that is based on the version v23 of the SPEEDYcode ()

8512 AIM Diagnostics

85 Atmosphere Packages 217

DIABQ | 5 |SM ML |gkgs |SpecHumid Tendency (Mass-Weighted)rarr˓from Diabatic ProcessesRADSW | 5 |SM ML |Ks |Temperature Tendency due to Shortwaverarr˓Radiation (TT_RSW)RADLW | 5 |SM ML |Ks |Temperature Tendency due to Longwaverarr˓Radiation (TT_RLW)DTCONV | 5 |SM MR |Ks |Temperature Tendency due torarr˓Convection (TT_CNV)TURBT | 5 |SM ML |Ks |Temperature Tendency due torarr˓Turbulence in PBL (TT_PBL)DTLS | 5 |SM ML |Ks |Temperature Tendency due to Large-rarr˓scale condens (TT_LSC)DQCONV | 5 |SM MR |gkgs |Spec Humidity Tendency due torarr˓Convection (QT_CNV)TURBQ | 5 |SM ML |gkgs |Spec Humidity Tendency due torarr˓Turbulence in PBL (QT_PBL)DQLS | 5 |SM ML |gkgs |Spec Humidity Tendency due to Large-rarr˓Scale Condens (QT_LSC)TSR | 1 |SM P U1 |Wm^2 |Top-of-atm net Shortwave Radiationrarr˓(+=dw)OLR | 1 |SM P U1 |Wm^2 |Outgoing Longwave Radiation (+=up)RADSWG | 1 |SM P L1 |Wm^2 |Net Shortwave Radiation at the Groundrarr˓(+=dw)RADLWG | 1 |SM L1 |Wm^2 |Net Longwave Radiation at the Groundrarr˓(+=up)HFLUX | 1 |SM L1 |Wm^2 |Sensible Heat Flux (+=up)EVAP | 1 |SM L1 |gm^2s |Surface Evaporation (gm2s)PRECON | 1 |SM P L1 |gm^2s |Convective Precipitation (gm2s)PRECLS | 1 |SM M1 |gm^2s |Large Scale Precipitation (gm2s)CLDFRC | 1 |SM P M1 |0-1 |Total Cloud Fraction (0-1)CLDPRS | 1 |SM PC167M1 |0-1 |Cloud Top Pressure (normalized)CLDMAS | 5 |SM P LL |kgm^2s |Cloud-base Mass Flux (kgm^2s)DRAG | 5 |SM P LL |kgm^2s |Surface Drag Coefficient (kgm^2s)WINDS | 1 |SM P L1 |ms |Surface Wind Speed (ms)TS | 1 |SM L1 |K |near Surface Air Temperature (K)QS | 1 |SM P L1 |gkg |near Surface Specific Humidity (gkg)ENPREC | 1 |SM M1 |Wm^2 |Energy flux associated with preciprarr˓(snow rain Temp)ALBVISDF| 1 |SM P L1 |0-1 |Surface Albedo (Visible band) (0-1)DWNLWG | 1 |SM P L1 |Wm^2 |Downward Component of Longwave Fluxrarr˓at the Ground (+=dw)SWCLR | 5 |SM ML |Ks |Clear Sky Temp Tendency due torarr˓Shortwave RadiationLWCLR | 5 |SM ML |Ks |Clear Sky Temp Tendency due torarr˓Longwave RadiationTSRCLR | 1 |SM P U1 |Wm^2 |Clear Sky Top-of-atm net Shortwaverarr˓Radiation (+=dw)OLRCLR | 1 |SM P U1 |Wm^2 |Clear Sky Outgoing Longwaverarr˓Radiation (+=up)SWGCLR | 1 |SM P L1 |Wm^2 |Clear Sky Net Shortwave Radiation atrarr˓the Ground (+=dw)LWGCLR | 1 |SM L1 |Wm^2 |Clear Sky Net Longwave Radiation atrarr˓the Ground (+=up)UFLUX | 1 |UM 184L1 |Nm^2 |Zonal Wind Surface Stress (Nm^2)VFLUX | 1 |VM 183L1 |Nm^2 |Meridional Wind Surface Stress (Nm^rarr˓2)DTSIMPL | 1 |SM P L1 |K |Surf Temp Change after 1 implicitrarr˓time step (continues on next page)

8513 Experiments and tutorials that use aim

bull Global atmosphere experiment in aim5l_cs verification directory

852 Land package

8521 Introduction

This package provides a simple land model based on Rong Zhang [e-mailrozgfdlnoaagov] 2 layers model (seedocumentation below)

It is primarily implemented for AIM (_v23) atmospheric physics but could be adapted to work with a different atmo-spheric physics Two subroutines (aim_aim2landF aim_land2aimF in pkgaim_v23) are used as interface with AIMphysics

Number of layers is a parameter (land_nLev in LAND_SIZEh) and can be changed

Note on Land Model date June 1999 author Rong Zhang

8522 Equations and Key Parameters

This is a simple 2-layer land model The top layer depth 1199111 = 01119898 the second layer depth 1199112 = 4119898

Let 1198791198921 1198791198922 be the temperature of each layer 11988211198822 be the soil moisture of each layer The field capacity 1198911 1198912 arethe maximum water amount in each layer so 119882119894 is the ratio of available water to field capacity 119891119894 = 120574119911119894 120574 = 024 isthe field capapcity per meter soil so 1198911 = 0024119898 1198912 = 096119898

The land temperature is determined by total surface downward heat flux 119865

119911111986211198891198791198921119889119905

= 119865 minus 1205821198791198921 minus 1198791198922

(1199111 + 1199112)2

119911211986221198891198791198922119889119905

= 1205821198791198921 minus 1198791198922

(1199111 + 1199112)2

here 1198621 1198622 are the heat capacity of each layer 120582lsquo119894119904119905ℎ119890119905ℎ119890119903119898119886119897119888119900119899119889119906119888119905119894119907119894119905119910 119898119886119905ℎ lambda =042Wm^-1K^-1lsquo

1198621 = 1198621199081198821120574 + 119862119904

1198622 = 1198621199081198822120574 + 119862119904

119862119908 119862119904 are the heat capacity of water and dry soil respectively 119862119908 = 42 times 106119869119898minus3119870minus1 119862119904 = 113 times106119869119898minus3119870minus1

The soil moisture is determined by precipitation 119875 (119898119904)surface evaporation 119864(119898119904) and runoff 119877(119898119904)

1198891198821

119889119905=119875 minus 119864 minus119877

1198911+1198822 minus1198821

120591

120591 = 2 119889119886119910119904 is the time constant for diffusion of moisture between layers

1198891198822

119889119905=11989111198912

1198821 minus1198822

120591

In the code 119877 = 0 gives better result 11988211198822 are set to be within [0 1] If 1198821 is greater than 1 then let 1205751198821 =1198821 minus 11198821 = 1 and 1198822 = 1198822 + 1199011205751198821

11989111198912

ie the runoff of top layer is put into second layer 119901 = 05 is the fractionof top layer runoff that is put into second layer

The time step is 1 hour it takes several years to reach equalibrium offline

8523 Land diagnostics

------------------------------------------------------------------------lt-Name-gt|Levs|lt-parsing code-gt|lt-- Units --gt|lt- Tile (max=80c)------------------------------------------------------------------------GrdSurfT| 1 |SM Lg |degC |Surface Temperature over landGrdTemp | 2 |SM MG |degC |Ground Temperature at each levelGrdEnth | 2 |SM MG |Jm3 |Ground Enthalpy at each levelGrdWater| 2 |SM P MG |0-1 |Ground Water (vs Field Capacity)rarr˓Fraction at each levelLdSnowH | 1 |SM P Lg |m |Snow Thickness over landLdSnwAge| 1 |SM P Lg |s |Snow Age over landRUNOFF | 1 |SM L1 |ms |Run-Off per surface unitEnRunOff| 1 |SM L1 |Wm^2 |Energy flux associated with run-OfflandHFlx| 1 |SM Lg |Wm^2 |net surface downward Heat flux overrarr˓landlandPmE | 1 |SM Lg |kgm^2s |Precipitation minus Evaporation overrarr˓landldEnFxPr| 1 |SM Lg |Wm^2 |Energy flux (over land) associatedrarr˓with Precip (snowrain)

8524 References

Hansen J et al Efficient three-dimensional global models for climate studies models I and II Monthly WeatherReview vol111 no4 pp 609-62 1983

8525 Experiments and tutorials that use land

853 Fizhi High-end Atmospheric Physics

8531 Introduction

The fizhi (high-end atmospheric physics) package includes a collection of state-of-the-art physical parameterizationsfor atmospheric radiation cumulus convection atmospheric boundary layer turbulence and land surface processesThe collection of atmospheric physics parameterizations were originally used together as part of the GEOS-3 (God-dard Earth Observing System-3) GCM developed at the NASAGoddard Global Modelling and Assimilation Office(GMAO)

8532 Equations

Moist Convective Processes

Sub-grid and Large-scale Convection

Sub-grid scale cumulus convection is parameterized using the Relaxed Arakawa Schubert (RAS) scheme of [MS92]which is a linearized Arakawa Schubert type scheme RAS predicts the mass flux from an ensemble of clouds Eachsubensemble is identified by its entrainment rate and level of neutral bouyancy which are determined by the grid-scaleproperties

The thermodynamic variables that are used in RAS to describe the grid scale vertical profile are the dry static energy119904 = 119888119901119879 + 119892119911 and the moist static energy ℎ = 119888119901119879 + 119892119911 + 119871119902 The conceptual model behind RAS depicts eachsubensemble as a rising plume cloud entraining mass from the environment during ascent and detraining all cloud airat the level of neutral buoyancy RAS assumes that the normalized cloud mass flux 120578 normalized by the cloud basemass flux is a linear function of height expressed as

120597120578(119911)

120597119911= 120582 119900119903

120597120578(119875120581)

120597119875120581= minus119888119901

119892120579120582

where we have used the hydrostatic equation written in the form

120597119911

120597119875120581= minus119888119901

119892120579

The entrainment parameter 120582 characterizes a particular subensemble based on its detrainment level and is obtainedby assuming that the level of detrainment is the level of neutral buoyancy ie the level at which the moist static energyof the cloud ℎ119888 is equal to the saturation moist static energy of the environment ℎ Following [MS92] 120582 may bewritten as

120582 =ℎ119861 minus ℎ119863

119888119901119892

int 119875119861

119875119863120579(ℎ119863 minus ℎ)119889119875120581

where the subscript 119861 refers to cloud base and the subscript 119863 refers to the detrainment level

The convective instability is measured in terms of the cloud work function 119860 defined as the rate of change of cumuluskinetic energy The cloud work function is related to the buoyancy or the difference between the moist static energyin the cloud and in the environment

119860 =

int 119875119861

119875119863

120578

1 + 120574

[ℎ119888 minus ℎ

119875120581

]119889119875120581

where 120574 is 119871119888119901

120597119902

120597119879 obtained from the Claussius Clapeyron equation and the subscript 119888 refers to the value inside thecloud

To determine the cloud base mass flux the rate of change of 119860 in time due to dissipation by the clouds is assumed toapproximately balance the rate of change of 119860 due to the generation by the large scale This is the quasi-equilibriumassumption and results in an expression for 119898119861

119898119861 =minus 119889119860

119889119905

119897119904

119870

where 119870 is the cloud kernel defined as the rate of change of the cloud work function per unit cloud base mass fluxand is currently obtained by analytically differentiating the expression for 119860 in time The rate of change of 119860 due tothe generation by the large scale can be written as the difference between the current 119860(119905 + ∆119905) and its equillibratedvalue after the previous convective time step 119860(119905) divided by the time step 119860(119905) is approximated as some critical119860119888119903119894119905 computed by Lord (1982) from 119894119899119904119894119905119906 observations

The predicted convective mass fluxes are used to solve grid-scale temperature and moisture budget equations to de-termine the impact of convection on the large scale fields of temperature (through latent heating and compensatingsubsidence) and moisture (through precipitation and detrainment)

120597120579

120597119905

119888

= 120572119898119861

119888119901119875120581120578120597119904

120597119901

120597119902

120597119905

119888

= 120572119898119861

119871120578(120597ℎ

120597119901minus 120597119904

120597119901)

where 120579 = 119879119875120581 119875 = (1199011199010) and 120572 is the relaxation parameter

As an approximation to a full interaction between the different allowable subensembles many clouds are simulatedfrequently each modifying the large scale environment some fraction 120572 of the total adjustment The parameterizationthereby ldquorelaxesrdquo the large scale environment towards equillibrium

In addition to the RAS cumulus convection scheme the fizhi package employs a Kessler-type scheme for the re-evaporation of falling rain [SM88] which correspondingly adjusts the temperature assuming ℎ is conserved RAS inits current formulation assumes that all cloud water is deposited into the detrainment level as rain All of the rain isavailable for re-evaporation which begins in the level below detrainment The scheme accounts for some microphysicssuch as the rainfall intensity the drop size distribution as well as the temperature pressure and relative humidity ofthe surrounding air The fraction of the moisture deficit in any model layer into which the rain may re-evaporate iscontrolled by a free parameter which allows for a relatively efficient re-evaporation of liquid precipitate and largerrainout for frozen precipitation

Due to the increased vertical resolution near the surface the lowest model layers are averaged to provide a 50 mb thicksub-cloud layer for RAS Each time RAS is invoked (every ten simulated minutes) a number of randomly chosensubensembles are checked for the possibility of convection from just above cloud base to 10 mb

Supersaturation or large-scale precipitation is initiated in the fizhi package whenever the relative humidity in any grid-box exceeds a critical value currently 100 The large-scale precipitation re-evaporates during descent to partiallysaturate lower layers in a process identical to the re-evaporation of convective rain

Cloud Formation

Convective and large-scale cloud fractons which are used for cloud-radiative interactions are determined diagnosticallyas part of the cumulus and large-scale parameterizations Convective cloud fractions produced by RAS are proportionalto the detrained liquid water amount given by

119865119877119860119878 = min

[119897119877119860119878

119897119888 10

]where 119897119888 is an assigned critical value equal to 125 gkg A memory is associated with convective clouds defined by

119865119899119877119860119878 = min

[119865119877119860119878 + (1 minus ∆119905119877119860119878

120591)119865119899minus1

119877119860119878 10

]where 119865119877119860119878 is the instantanious cloud fraction and 119865119899minus1

119877119860119878 is the cloud fraction from the previous RAS timestep Thememory coefficient is computed using a RAS cloud timescale 120591 equal to 1 hour RAS cloud fractions are clearedwhen they fall below 5

Large-scale cloudiness is defined following Slingo and Ritter (1985) as a function of relative humidity

119865119871119878 = min

[(119877119867 minus119877119867119888

1 minus119877119867119888

]where

RHc amp = amp 1-s(1-s)(2-+2 s)r s amp = amp ppsurf r amp = amp ( ) RHmin amp = amp 075 amp = amp 0573285

These cloud fractions are suppressed however in regions where the convective sub-cloud layer is conditionally unsta-ble The functional form of 119877119867119888 is shown in Figure 88

Figure 88 Critical Relative Humidity for Clouds

The total cloud fraction in a grid box is determined by the larger of the two cloud fractions

119865119862119871119863 = max [119865119877119860119878 119865119871119878 ]

Finally cloud fractions are time-averaged between calls to the radiation packages

Radiation

The parameterization of radiative heating in the fizhi package includes effects from both shortwave and longwaveprocesses Radiative fluxes are calculated at each model edge-level in both up and down directions The heatingratescooling rates are then obtained from the vertical divergence of the net radiative fluxes

The net flux is

119865 = 119865 uarr minus 119865 darr

where 119865 is the net flux 119865 uarr is the upward flux and 119865 darr is the downward flux

The heating rate due to the divergence of the radiative flux is given by

120597120588119888119901119879

120597119905= minus120597119865

120597119911

120597119879

120597119905=

119892

119888119901120587

120597119865

120597120590

where 119892 is the accelation due to gravity and 119888119901 is the heat capacity of air at constant pressure

The time tendency for Longwave Radiation is updated every 3 hours The time tendency for Shortwave Radiation isupdated once every three hours assuming a normalized incident solar radiation and subsequently modified at everymodel time step by the true incident radiation The solar constant value used in the package is equal to 1365 1198821198982

and a1198621198742 mixing ratio of 330 ppm For the ozone mixing ratio monthly mean zonally averaged climatological valuesspecified as a function of latitude and height [RSG87] are linearly interpolated to the current time

Shortwave Radiation

The shortwave radiation package used in the package computes solar radiative heating due to the absoption by wa-ter vapor ozone carbon dioxide oxygen clouds and aerosols and due to the scattering by clouds aerosols andgases The shortwave radiative processes are described by [Cho90][Cho92] This shortwave package uses the Delta-Eddington approximation to compute the bulk scattering properties of a single layer following King and Harshvardhan(JAS 1986) The transmittance and reflectance of diffuse radiation follow the procedures of Sagan and Pollock (JGR1967) and [LH74]

Highly accurate heating rate calculations are obtained through the use of an optimal grouping strategy of spectralbands By grouping the UV and visible regions as indicated in Table 810 the Rayleigh scattering and the ozoneabsorption of solar radiation can be accurately computed in the ultraviolet region and the photosynthetically activeradiation (PAR) region The computation of solar flux in the infrared region is performed with a broadband param-eterization using the spectrum regions shown in Table 811 The solar radiation algorithm used in the fizhi packagecan be applied not only for climate studies but also for studies on the photolysis in the upper atmosphere and thephotosynthesis in the biosphere

Table 810 UV and Visible Spectral Regions used in shortwave radiationpackage

UV and Visible Spectral RegionsRegion Band Wavelength (micron)UV-C

1175 - 225

2225 - 245

260 - 280

3245 - 260

280 - 295

5295 - 310

6310 - 320

320 - 400

400 - 700

Table 811 Infrared Spectral Regions used in shortwave radiation pack-age

Infrared Spectral RegionsBand Wavenumber (cmndash1) Wavelength (micron)1 1000-4400 227-1002 4400-8200 122-2273 8200-14300 070-122

Within the shortwave radiation package both ice and liquid cloud particles are allowed to co-exist in any of the modellayers Two sets of cloud parameters are used one for ice paticles and the other for liquid particles Cloud parametersare defined as the cloud optical thickness and the effective cloud particle size In the fizhi package the effective radiusfor water droplets is given as 10 microns while 65 microns is used for ice particles The absorption due to aerosols iscurrently set to zero

To simplify calculations in a cloudy atmosphere clouds are grouped into low (119901 gt 700 mb) middle (700 mb ge 119901 gt400 mb) and high (119901 lt 400 mb) cloud regions Within each of the three regions clouds are assumed maximallyoverlapped and the cloud cover of the group is the maximum cloud cover of all the layers in the group The opticalthickness of a given layer is then scaled for both the direct (as a function of the solar zenith angle) and diffuse beamradiation so that the grouped layer reflectance is the same as the original reflectance The solar flux is computedfor each of eight cloud realizations possible within this lowmiddlehigh classification and appropriately averaged toproduce the net solar flux

Longwave Radiation

The longwave radiation package used in the fizhi package is thoroughly described by As described in that documentIR fluxes are computed due to absorption by water vapor carbon dioxide and ozone The spectral bands together withtheir absorbers and parameterization methods configured for the fizhi package are shown in Table 812

Table 812 IR Spectral Bands Absorbers and Parameterization Method(from [CS94])

IR Spectral BandsBand Spectral Range (cmndash1) Absorber Method1 0-340 H2O line T2 340-540 H2O line T3a 540-620 H2O line K3b 620-720 H2O continuum S3b 720-800 CO2 T4 800-980 H2O line K

H2O continuum SH2O line K

5 980-1100 H2O continuum SO3 T

6 1100-1380 H2O line KH2O continuum S

7 1380-1900 H2O line T8 1900-3000 H2O line KK 119896-distribution method with linear pressure scalingT Table look-up with temperature and pressure scalingS One-parameter temperature scaling

The longwave radiation package accurately computes cooling rates for the middle and lower atmosphere from 001 mbto the surface Errors are lt 04 C dayminus1 in cooling rates and lt 1 in fluxes From Chou and Suarez it is estimatedthat the total effect of neglecting all minor absorption bands and the effects of minor infrared absorbers such as nitrousoxide (Nmath_2O) methane (CHmath_4) and the chlorofluorocarbons (CFCs) is an underestimate of asymp 5 Wm2

in the downward flux at the surface and an overestimate of asymp 3 Wm2 in the upward flux at the top of the atmosphere

Similar to the procedure used in the shortwave radiation package clouds are grouped into three regions catagorized aslowmiddlehigh The net clear line-of-site probability (119875 ) between any two levels 1199011 and 1199012 (1199012 gt 1199011) assumingrandomly overlapped cloud groups is simply the product of the probabilities within each group

119875119899119890119905 = 119875119897119900119908 times 119875119898119894119889 times 119875ℎ119894

Since all clouds within a group are assumed maximally overlapped the clear line-of-site probability within a group isgiven by

119875119892119903119900119906119901 = 1 minus 119865119898119886119909

where 119865119898119886119909 is the maximum cloud fraction encountered between 1199011 and 1199012 within that group For groups andorlevels outside the range of 1199011 and 1199012 a clear line-of-site probability equal to 1 is assigned

Cloud-Radiation Interaction

The cloud fractions and diagnosed cloud liquid water produced by moist processes within the fizhi package are usedin the radiation packages to produce cloud-radiative forcing The cloud optical thickness associated with large-scale

cloudiness is made proportional to the diagnosed large-scale liquid water ℓ detrained due to super-saturation Twovalues are used corresponding to cloud ice particles and water droplets The range of optical thickness for these cloudsis given as

00002 le 120591119894119888119890(119898119887minus1) le 0002 for 0 le ℓ le 2 mgkg

002 le 120591ℎ2119900(119898119887minus1) le 02 for 0 le ℓ le 10 mgkg

The partitioning 120572 between ice particles and water droplets is achieved through a linear scaling in temperature

0 le 120572 le 1 for 23315 le 119879 le 25315

The resulting optical depth associated with large-scale cloudiness is given as

120591119871119878 = 120572120591ℎ2119900 + (1 minus 120572)120591119894119888119890

The optical thickness associated with sub-grid scale convective clouds produced by RAS is given as

120591119877119860119878 = 016 119898119887minus1

The total optical depth in a given model layer is computed as a weighted average between the large-scale and sub-gridscale optical depths normalized by the total cloud fraction in the layer

120591 =

(119865119877119860119878 120591119877119860119878 + 119865119871119878 120591119871119878

119865119877119860119878 + 119865119871119878

)∆119901

where 119865119877119860119878 and 119865119871119878 are the time-averaged cloud fractions associated with RAS and large-scale processes describedin Section [secfizhiclouds] The optical thickness for the longwave radiative feedback is assumed to be 75 of thesevalues

The entire Moist Convective Processes Module is called with a frequency of 10 minutes The cloud fraction valuesare time-averaged over the period between Radiation calls (every 3 hours) Therefore in a time-averaged sense bothconvective and large-scale cloudiness can exist in a given grid-box

Turbulence

Turbulence is parameterized in the fizhi package to account for its contribution to the vertical exchange of heatmoisture and momentum The turbulence scheme is invoked every 30 minutes and employs a backward-implicititerative time scheme with an internal time step of 5 minutes The tendencies of atmospheric state variables due toturbulent diffusion are calculated using the diffusion equations

120597119906

120597119905 119905119906119903119887=

120597

120597119911(minus119906prime119908prime) =

120597

120597119911(119870119898

120597119906

120597119911)

120597119907

120597119905 119905119906119903119887=

120597

120597119911(119870119898

120597119907

120597119911)

120597119879

120597119905= 119875120581 120597120579

120597119905 119905119906119903119887= 119875120581 120597

120597119911(minus119908prime120579prime) = 119875120581 120597

120597119911(119870ℎ

120597120579119907120597119911

120597119902

120597119905 119905119906119903119887=

120597

120597119911(119870ℎ

120597119902

120597119911)

Within the atmosphere the time evolution of second turbulent moments is explicitly modeled by representing the thirdmoments in terms of the first and second moments This approach is known as a second-order closure modelingTo simplify and streamline the computation of the second moments the level 25 assumption of Mellor and Yamada(1974) and [Yam77] is employed in which only the turbulent kinetic energy (TKE)

21199022 = 119906prime2 + 119907prime2 + 119908prime2

is solved prognostically and the other second moments are solved diagnostically The prognostic equation for TKEallows the scheme to simulate some of the transient and diffusive effects in the turbulence The TKE budget equationis solved numerically using an implicit backward computation of the terms linear in 1199022 and is written

119889

119889119905(1

21199022) minus 120597

120597119911(5

31205821119902

120597

120597119911(1

21199022)) = minus119906prime119908prime 120597119880

120597119911minus 119907prime119908prime 120597119881

120597119911+

119892

Θ0119908prime120579119907

prime minus 1199023

where 119902 is the turbulent velocity 119906prime 119907prime 119908prime and 120579prime are the fluctuating parts of the velocity components and potentialtemperature 119880 and 119881 are the mean velocity components Θ0

minus1 is the coefficient of thermal expansion and 1205821 andΛ1 are constant multiples of the master length scale ℓ which is designed to be a characteristic measure of the verticalstructure of the turbulent layers

The first term on the left-hand side represents the time rate of change of TKE and the second term is a representationof the triple correlation or turbulent transport term The first three terms on the right-hand side represent the sourcesof TKE due to shear and bouyancy and the last term on the right hand side is the dissipation of TKE

In the level 25 approach the vertical fluxes of the scalars 120579119907 and 119902 and the wind components 119906 and 119907 are expressed interms of the diffusion coefficients 119870ℎ and 119870119898 respectively In the statisically realizable level 25 turbulence schemeof [HL88] these diffusion coefficients are expressed as

119870ℎ =

119902 ℓ 119878119867(119866119872 119866119867) for decaying turbulence1199022

119902119890ℓ 119878119867(119866119872119890

119866119867119890) for growing turbulence

119870119898 =

119902 ℓ 119878119872 (119866119872 119866119867) for decaying turbulence1199022

119902119890ℓ 119878119872 (119866119872119890

where the subscript 119890 refers to the value under conditions of local equillibrium (obtained from the Level 20 Model) ℓis the master length scale related to the vertical structure of the atmosphere and 119878119872 and 119878119867 are functions of 119866119867 and119866119872 the dimensionless buoyancy and wind shear parameters respectively Both 119866119867 and 119866119872 and their equilibriumvalues 119866119867119890 and 119866119872119890 are functions of the Richardson number

119892120579119907

120597120579119907120597119911

(120597119906120597119911 )2 + (120597119907

120597119911 )2=

119888119901120597120579119907120597119911

120597119875120581

120597119911

(120597119906120597119911 )2 + (120597119907

120597119911 )2

Negative values indicate unstable buoyancy and shear small positive values (lt 02) indicate dominantly unstableshear and large positive values indicate dominantly stable stratification

Turbulent eddy diffusion coefficients of momentum heat and moisture in the surface layer which corresponds tothe lowest GCM level (see mdash missing table mdash) are calculated using stability-dependant functions based on Monin-Obukhov theory

119870119898(119904119906119903119891119886119888119890) = 119862119906 times 119906 = 119862119863119882119904

119870ℎ(119904119906119903119891119886119888119890) = 119862119905 times 119906 = 119862119867119882119904

where 119906 = 119862119906119882119904 is the surface friction velocity 119862119863 is termed the surface drag coefficient 119862119867 the heat transfercoefficient and 119882119904 is the magnitude of the surface layer wind

119862119906 is the dimensionless exchange coefficient for momentum from the surface layer similarity functions

119862119906 =119906119882119904

=119896

120595119898

where k is the Von Karman constant and 120595119898 is the surface layer non-dimensional wind shear given by

120595119898 =

int 120577

1205770

120593119898120577119889120577

Here 120577 is the non-dimensional stability parameter and 120593119898 is the similarity function of 120577 which expresses the stabilitydependance of the momentum gradient The functional form of 120593119898 is specified differently for stable and unstablelayers

119862119905 is the dimensionless exchange coefficient for heat and moisture from the surface layer similarity functions

119862119905 = minus (119908prime120579prime)

119906∆120579= minus (119908prime119902prime)

119906∆119902=

119896

(120595ℎ + 120595119892)

where 120595ℎ is the surface layer non-dimensional temperature gradient given by

120595ℎ =

int 120577

1205770

120593ℎ120577119889120577

Here 120593ℎ is the similarity function of 120577 which expresses the stability dependance of the temperature and moisturegradients and is specified differently for stable and unstable layers according to [HS95]

120595119892 is the non-dimensional temperature or moisture gradient in the viscous sublayer which is the mosstly laminarregion between the surface and the tops of the roughness elements in which temperature and moisture gradients canbe quite large Based on [YK74]

120595119892 =055(11987511990323 minus 02)

12058412(ℎ0119906 minus ℎ0119903119890119891119906119903119890119891

where Pr is the Prandtl number for air 120584 is the molecular viscosity 1199110 is the surface roughness length and the subscriptref refers to a reference value ℎ0 = 301199110 with a maximum value over land of 001

The surface roughness length over oceans is is a function of the surface-stress velocity

1199110 = 11988811199063 + 1198882119906

2 + 1198883119906 + 1198884 +

1198885119906

where the constants are chosen to interpolate between the reciprocal relation of [Kon75] for weak winds and thepiecewise linear relation of [LP81] for moderate to large winds Roughness lengths over land are specified from theclimatology of [DS89]

For an unstable surface layer the stability functions chosen to interpolate between the condition of small values of 120573and the convective limit are the KEYPS function [Pan73] for momentum and its generalization for heat and moisture

1205931198984 minus 18120577120593119898

3 = 1 120593ℎ2 minus 18120577120593ℎ

The function for heat and moisture assures non-vanishing heat and moisture fluxes as the wind speed approaches zero

For a stable surface layer the stability functions are the observationally based functions of [Cla70] slightly modifiedfor the momemtum flux

120593119898 =1 + 51205771

1 + 0007941205771(1 + 51205771) 120593ℎ =

1 + 512057711 + 000794120577(1 + 51205771)

The moisture flux also depends on a specified evapotranspiration coefficient set to unity over oceans and dependanton the climatological ground wetness over land

Once all the diffusion coefficients are calculated the diffusion equations are solved numerically using an implicitbackward operator

Atmospheric Boundary Layer

The depth of the atmospheric boundary layer (ABL) is diagnosed by the parameterization as the level at which theturbulent kinetic energy is reduced to a tenth of its maximum near surface value The vertical structure of the ABL isexplicitly resolved by the lowest few (3-8) model layers

Surface Energy Budget

The ground temperature equation is solved as part of the turbulence package using a backward implicit time differenc-ing scheme

119862119892120597119879119892120597119905

= 119877119904119908 minus119877119897119908 +119876119894119888119890 minus119867 minus 119871119864

where 119877119904119908 is the net surface downward shortwave radiative flux and 119877119897119908 is the net surface upward longwave radiativeflux

119867 is the upward sensible heat flux given by

119867 = 119875120581120588119888119901119862119867119882119904(120579119904119906119903119891119886119888119890 minus 120579119873119871119860119884 ) 119908ℎ119890119903119890 119862119867 = 119862119906119862119905

where 120588 = the atmospheric density at the surface 119888119901 is the specific heat of air at constant pressure and 120579 represents thepotential temperature of the surface and of the lowest 120590-level respectively

The upward latent heat flux 119871119864 is given by

119871119864 = 120588120573119871119862119867119882119904(119902119904119906119903119891119886119888119890 minus 119902119873119871119860119884 ) 119908ℎ119890119903119890 119862119867 = 119862119906119862119905

where 120573 is the fraction of the potential evapotranspiration actually evaporated L is the latent heat of evaporation and119902119904119906119903119891119886119888119890 and 119902119873119871119860119884 are the specific humidity of the surface and of the lowest 120590-level respectively

The heat conduction through sea ice 119876119894119888119890 is given by

119876119894119888119890 =119862119905119894

119867119894(119879119894 minus 119879119892)

where 119862119905119894 is the thermal conductivity of ice 119867119894 is the ice thickness assumed to be 3 119898 where sea ice is present 119879119894 is273 degrees Kelvin and 119879119892 is the surface temperature of the ice

119862119892 is the total heat capacity of the ground obtained by solving a heat diffusion equation for the penetration of thediurnal cycle into the ground () and is given by

119862119892 =

radic120582119862119904

2120596=

radic(0386 + 0536119882 + 015119882 2)2 times 10minus3

2120587

Here the thermal conductivity 120582 is equal to 2times 10minus3 119897119910119904119890119888

119888119898119870 the angular velocity of the earth 120596 is written as 86400

119904119890119888119889119886119910 divided by 2120587 119903119886119889119894119886119899119904119889119886119910 and the expression for 119862119904 the heat capacity per unit volume at the surface is afunction of the ground wetness 119882

Land Surface Processes

Surface Type

The fizhi package surface Types are designated using the Koster-Suarez [KS91][KS92] Land Surface Model (LSM)mosaic philosophy which allows multiple ldquotilesrdquo or multiple surface types in any one grid cell The Koster-SuarezLSM surface type classifications are shown in Table 813 The surface types and the percent of the grid cell occupied

by any surface type were derived from the surface classification of [DT94] and information about the location ofpermanent ice was obtained from the classifications of [DS89] The surface type map for a 1∘ grid is shown in Figure89 The determination of the land or sea category of surface type was made from NCARrsquos 10 minute by 10 minuteNavy topography dataset which includes information about the percentage of water-cover at any point The data wereaveraged to the modelrsquos grid resolutions and any grid-box whose averaged water percentage was ge 60 was definedas a water point The Land-Water designation was further modified subjectively to ensure sufficient representationfrom small but isolated land and water regions

Table 813 Surface Type DesignationType Vegetation Designation1 Broadleaf Evergreen Trees2 Broadleaf Deciduous Trees3 Needleleaf Trees4 Ground Cover5 Broadleaf Shrubs6 Dwarf Trees (Tundra)7 Bare Soil8 Desert (Bright)9 Glacier10 Desert (Dark)100 Ocean

Surface Roughness

The surface roughness length over oceans is computed iteratively with the wind stress by the surface layer parameter-ization [HS95] It employs an interpolation between the functions of [LP81] for high winds and of [Kon75] for weakwinds

Albedo

The surface albedo computation described in employs the ldquotwo streamrdquo approximation used in Sellersrsquo (1987) SimpleBiosphere (SiB) Model which distinguishes between the direct and diffuse albedos in the visible and in the near infra-red spectral ranges The albedos are functions of the observed leaf area index (a description of the relative orientationof the leaves to the sun) the greenness fraction the vegetation type and the solar zenith angle Modifications are madeto account for the presence of snow and its depth relative to the height of the vegetation elements

Gravity Wave Drag

The fizhi package employs the gravity wave drag scheme of [ZSL95] This scheme is a modified version of Vernekaret al (1992) which was based on Alpert et al (1988) and Helfand et al (1987) In this version the gravity wavestress at the surface is based on that derived by Pierrehumbert (1986) and is given by

|119904119891119888| =1205881198803

119873ℓ

(119865 2119903

1 + 119865 2119903

where 119865119903 = 119873ℎ119880 is the Froude number 119873 is the Brunt - Vaumlisaumllauml frequency 119880 is the surface wind speed ℎ is thestandard deviation of the sub-grid scale orography and ℓ is the wavelength of the monochromatic gravity wave in thedirection of the low-level wind A modification introduced by Zhou et al allows for the momentum flux to escapethrough the top of the model although this effect is small for the current 70-level model The subgrid scale standarddeviation is defined by ℎ and is not allowed to exceed 400 m

Figure 89 Surface type combinations

The effects of using this scheme within a GCM are shown in [TS96] Experiments using the gravity wave dragparameterization yielded significant and beneficial impacts on both the time-mean flow and the transient statistics ofthe a GCM climatology and have eliminated most of the worst dynamically driven biases in the a GCM simulationAn examination of the angular momentum budget during climate runs indicates that the resulting gravity wave torqueis similar to the data-driven torque produced by a data assimilation which was performed without gravity wave dragIt was shown that the inclusion of gravity wave drag results in large changes in both the mean flow and in eddyfluxes The result is a more accurate simulation of surface stress (through a reduction in the surface wind strength)of mountain torque (through a redistribution of mean sea-level pressure) and of momentum convergence (through areduction in the flux of westerly momentum by transient flow eddies)

Boundary Conditions and other Input Data

Required fields which are not explicitly predicted or diagnosed during model execution must either be prescribedinternally or obtained from external data sets In the fizhi package these fields include sea surface temperature sea iceestent surface geopotential variance vegetation index and the radiation-related background levels of ozone carbondioxide and stratospheric moisture

Boundary condition data sets are available at the modelrsquos resolutions for either climatological or yearly varying con-ditions Any frequency of boundary condition data can be used in the fizhi package however the current selection ofdata is summarized in Table 814 The time mean values are interpolated during each model timestep to the currenttime

Table 814 Boundary conditions and other input data used in the fizhipackage Also noted are the current years and frequencies available

Fizhi Input DatasetsSea Ice Extent monthly 1979-current climatologySea Ice Extent weekly 1982-current climatologySea Surface Temperature monthly 1979-current climatologySea Surface Temperature weekly 1982-current climatologyZonally Averaged Upper-Level Moisture monthly climatologyZonally Averaged Ozone Concentration monthly climatology

Topography and Topography Variance

Surface geopotential heights are provided from an averaging of the Navy 10 minute by 10 minute dataset supplied bythe National Center for Atmospheric Research (NCAR) to the modelrsquos grid resolution The original topography is firstrotated to the proper grid-orientation which is being run and then averages the data to the model resolution

The standard deviation of the subgrid-scale topography is computed by interpolating the 10 minute data to the modelrsquosresolution and re-interpolating back to the 10 minute by 10 minute resolution The sub-grid scale variance is con-structed based on this smoothed dataset

Upper Level Moisture

The fizhi package uses climatological water vapor data above 100 mb from the Stratospheric Aerosol and Gas Ex-periment (SAGE) as input into the modelrsquos radiation packages The SAGE data is archived as monthly zonal meansat 5∘ latitudinal resolution The data is interpolated to the modelrsquos grid location and current time and blended withthe GCMrsquos moisture data Below 300 mb the modelrsquos moisture data is used Above 100 mb the SAGE data is usedBetween 100 and 300 mb a linear interpolation (in pressure) is performed using the data from SAGE and the GCM

8533 Fizhi Diagnostics

Fizhi Diagnostic Menu [secpkgfizhidiagnostics]

NAME UNITS LEVELS DESCRIPTIONUFLUX N mndash2 1 Surface U-Wind Stress on the atmosphereVFLUX N mndash2 1 Surface V-Wind Stress on the atmosphereHFLUX W mndash2 1 Surface Flux of Sensible HeatEFLUX W mndash2 1 Surface Flux of Latent HeatQICE W mndash2 1 Heat Conduction through Sea-IceRADLWG W mndash2 1 Net upward LW flux at the groundRADSWG W mndash2 1 Net downward SW flux at the groundRI dimensionless Nrphys Richardson NumberCT dimensionless 1 Surface Drag coefficient for T and QCU dimensionless 1 Surface Drag coefficient for U and VET m2 sndash1 Nrphys Diffusivity coefficient for T and QEU m2 sndash1 Nrphys Diffusivity coefficient for U and VTURBU m sndash1 dayndash1 Nrphys U-Momentum Changes due to TurbulenceTURBV m sndash1 dayndash1 Nrphys V-Momentum Changes due to TurbulenceTURBT deg dayndash1 Nrphys Temperature Changes due to TurbulenceTURBQ gkgday Nrphys Specific Humidity Changes due to TurbulenceMOISTT deg dayndash1 Nrphys Temperature Changes due to Moist ProcessesMOISTQ gkgday Nrphys Specific Humidity Changes due to Moist ProcessesRADLW deg dayndash1 Nrphys Net Longwave heating rate for each levelRADSW deg dayndash1 Nrphys Net Shortwave heating rate for each levelPREACC mmday 1 Total PrecipitationPRECON mmday 1 Convective PrecipitationTUFLUX N mndash2 Nrphys Turbulent Flux of U-MomentumTVFLUX N mndash2 Nrphys Turbulent Flux of V-MomentumTTFLUX W mndash2 Nrphys Turbulent Flux of Sensible Heat

NAME UNITS LEV-ELS

DESCRIPTION

TQFLUX W mndash2 Nrphys Turbulent Flux of Latent HeatCN dimension-

less1 Neutral Drag Coefficient

WINDS m sndash1 1 Surface Wind SpeedDTSRF deg 1 AirSurface virtual temperature differenceTG deg 1 Ground temperatureTS deg 1 Surface air temperature (Adiabatic from lowest model layer)DTG deg 1 Ground temperature adjustmentQG g kgndash1 1 Ground specific humidityQS g kgndash1 1 Saturation surface specific humidityTGRLW deg 1 Instantaneous ground temperature used as input to the Longwave radiation

subroutineST4 W mndash2 1 Upward Longwave flux at the ground (120590119879 4)OLR W mndash2 1 Net upward Longwave flux at the top of the modelOLRCLR W mndash2 1 Net upward clearsky Longwave flux at the top of the modelLWGCLR W mndash2 1 Net upward clearsky Longwave flux at the groundLWCLR deg dayndash1 Nrphys Net clearsky Longwave heating rate for each levelTLW deg Nrphys Instantaneous temperature used as input to the Longwave radiation sub-

routineSHLW g gndash1 Nrphys Instantaneous specific humidity used as input to the Longwave radiation

subroutineOZLW g gndash1 Nrphys Instantaneous ozone used as input to the Longwave radiation subroutineCLMOLW 0 minus 1 Nrphys Maximum overlap cloud fraction used in the Longwave radiation subrou-

tineCLDTOT 0 minus 1 Nrphys Total cloud fraction used in the Longwave and Shortwave radiation sub-

routinesLWG-DOWN

W mndash2 1 Downwelling Longwave radiation at the ground

GWDT deg dayndash1 Nrphys Temperature tendency due to Gravity Wave DragRADSWT W mndash2 1 Incident Shortwave radiation at the top of the atmosphereTAUCLD per 100 mb Nrphys Counted Cloud Optical Depth (non-dimensional) per 100 mbTAU-CLDC

Number Nrphys Cloud Optical Depth Counter

NAME UNITS LEVELS DescriptionCLDLOW 0-1 Nrphys Low-Level ( 1000-700 hPa) Cloud Fraction (0-1)EVAP mmday 1 Surface evaporationDPDT hPaday 1 Surface Pressure time-tendencyUAVE msec Nrphys Average U-WindVAVE msec Nrphys Average V-WindTAVE deg Nrphys Average TemperatureQAVE gkg Nrphys Average Specific HumidityOMEGA hPaday Nrphys Vertical VelocityDUDT msecday Nrphys Total U-Wind tendencyDVDT msecday Nrphys Total V-Wind tendencyDTDT degday Nrphys Total Temperature tendencyDQDT gkgday Nrphys Total Specific Humidity tendencyVORT 10^-4sec Nrphys Relative VorticityDTLS degday Nrphys Temperature tendency due to Stratiform Cloud FormationDQLS gkgday Nrphys Specific Humidity tendency due to Stratiform Cloud FormationUSTAR msec 1 Surface USTAR windZ0 m 1 Surface roughnessFRQTRB 0-1 Nrphys-1 Frequency of TurbulencePBL mb 1 Planetary Boundary Layer depthSWCLR degday Nrphys Net clearsky Shortwave heating rate for each levelOSR W mndash2 1 Net downward Shortwave flux at the top of the modelOSRCLR W mndash2 1 Net downward clearsky Shortwave flux at the top of the modelCLDMAS kg m^2 Nrphys Convective cloud mass fluxUAVE msec Nrphys Time-averaged 119906-Wind

NAME UNITS LEVELS DESCRIPTIONVAVE msec Nrphys Time-averaged 119907-WindTAVE deg Nrphys Time-averaged TemperaturelsquoQAVE gg Nrphys Time-averaged Specific HumidityRFT degday Nrphys Temperature tendency due Rayleigh FrictionPS mb 1 Surface PressureQQAVE (msec)2 Nrphys Time-averaged Turbulent Kinetic EnergySWGCLR W mndash2 1 Net downward clearsky Shortwave flux at the groundPAVE mb 1 Time-averaged Surface PressureDIABU msecday Nrphys Total Diabatic forcing on 119906-WindDIABV msecday Nrphys Total Diabatic forcing on 119907-WindDIABT degday Nrphys Total Diabatic forcing on TemperatureDIABQ gkgday Nrphys Total Diabatic forcing on Specific HumidityRFU msecday Nrphys U-Wind tendency due to Rayleigh FrictionRFV msecday Nrphys V-Wind tendency due to Rayleigh FrictionGWDU msecday Nrphys U-Wind tendency due to Gravity Wave DragGWDU msecday Nrphys V-Wind tendency due to Gravity Wave DragGWDUS N mndash2 1 U-Wind Gravity Wave Drag Stress at SurfaceGWDVS N mndash2 1 V-Wind Gravity Wave Drag Stress at SurfaceGWDUT N mndash2 1 U-Wind Gravity Wave Drag Stress at TopGWDVT N mndash2 1 V-Wind Gravity Wave Drag Stress at TopLZRAD mgkg Nrphys Estimated Cloud Liquid Water used in Radiation

NAME UNITS LEVELS DESCRIPTIONSLP mb 1 Time-averaged Sea-level PressureCLDFRC 0-1 1 Total Cloud FractionTPW gm cmndash2 1 Precipitable waterU2M msec 1 U-Wind at 2 metersV2M msec 1 V-Wind at 2 metersT2M deg 1 Temperature at 2 metersQ2M gkg 1 Specific Humidity at 2 metersU10M msec 1 U-Wind at 10 metersV10M msec 1 V-Wind at 10 metersT10M deg 1 Temperature at 10 metersQ10M gkg 1 Specific Humidity at 10 metersDTRAIN kg mndash2 Nrphys Detrainment Cloud Mass FluxQFILL gkgday Nrphys Filling of negative specific humidityDTCONV degsec Nr Temp Change due to ConvectionDQCONV gkgsec Nr Specific Humidity Change due to ConvectionRELHUM percent Nr Relative HumidityPRECLS gm^2sec 1 Large Scale PrecipitationENPREC Jg 1 Energy of Precipitation (snow rain Temp)

8534 Fizhi Diagnostic Description

In this section we list and describe the diagnostic quantities available within the GCM The diagnostics are listed inthe order that they appear in the Diagnostic Menu Section [secpkgfizhidiagnostics] In all cases each diagnostic ascurrently archived on the output datasets is time-averaged over its diagnostic output frequency

DIAGNOSTIC =1

119879119879119874119879

119905=119879119879119874119879sum119905=1

119889119894119886119892(119905)

where 119879119879119874119879 = NQDIAGΔ119905 NQDIAG is the output frequency of the diagnostic and ∆119905 is the timestep over which

the diagnostic is updated

Surface Zonal Wind Stress on the Atmosphere (1198731198901199081199051199001198991198982)

The zonal wind stress is the turbulent flux of zonal momentum from the surface

UFLUX = minus120588119862119863119882119904119906 119908ℎ119890119903119890 119862119863 = 1198622119906

where 120588 = the atmospheric density at the surface 119862119863 is the surface drag coefficient 119862119906 is the dimensionless surfaceexchange coefficient for momentum (see diagnostic number 10) 119882119904 is the magnitude of the surface layer wind and 119906is the zonal wind in the lowest model layer

Surface Meridional Wind Stress on the Atmosphere (1198731198901199081199051199001198991198982)

The meridional wind stress is the turbulent flux of meridional momentum from the surface

VFLUX = minus120588119862119863119882119904119907 119908ℎ119890119903119890 119862119863 = 1198622119906

where 120588 = the atmospheric density at the surface 119862119863 is the surface drag coefficient 119862119906 is the dimensionless surfaceexchange coefficient for momentum (see diagnostic number 10) 119882119904 is the magnitude of the surface layer wind and 119907is the meridional wind in the lowest model layer

Surface Flux of Sensible Heat (W mndash2)

The turbulent flux of sensible heat from the surface to the atmosphere is a function of the gradient of virtual potentialtemperature and the eddy exchange coefficient

HFLUX = 119875120581120588119888119901119862119867119882119904(120579119904119906119903119891119886119888119890 minus 120579119873119903119901ℎ119910119904) 119908ℎ119890119903119890 119862119867 = 119862119906119862119905

where 120588 = the atmospheric density at the surface 119888119901 is the specific heat of air 119862119867 is the dimensionless surfaceheat transfer coefficient 119882119904 is the magnitude of the surface layer wind 119862119906 is the dimensionless surface exchangecoefficient for momentum (see diagnostic number 10) 119862119905 is the dimensionless surface exchange coefficient for heatand moisture (see diagnostic number 9) and 120579 is the potential temperature at the surface and at the bottom model level

Surface Flux of Latent Heat (1198821198861199051199051199041198982)

The turbulent flux of latent heat from the surface to the atmosphere is a function of the gradient of moisture thepotential evapotranspiration fraction and the eddy exchange coefficient

EFLUX = 120588120573119871119862119867119882119904(119902119904119906119903119891119886119888119890 minus 119902119873119903119901ℎ119910119904) 119908ℎ119890119903119890 119862119867 = 119862119906119862119905

where 120588 = the atmospheric density at the surface 120573 is the fraction of the potential evapotranspiration actually evapo-rated L is the latent heat of evaporation 119862119867 is the dimensionless surface heat transfer coefficient119882119904 is the magnitudeof the surface layer wind 119862119906 is the dimensionless surface exchange coefficient for momentum (see diagnostic num-ber 10) 119862119905 is the dimensionless surface exchange coefficient for heat and moisture (see diagnostic number 9) and119902119904119906119903119891119886119888119890 and 119902119873119903119901ℎ119910119904 are the specific humidity at the surface and at the bottom model level respectively

Heat Conduction Through Sea Ice (1198821198861199051199051199041198982)

Over sea ice there is an additional source of energy at the surface due to the heat conduction from the relatively warmocean through the sea ice The heat conduction through sea ice represents an additional energy source term for theground temperature equation

QICE =119862119905119894

119867119894(119879119894 minus 119879119892)

where 119862119905119894 is the thermal conductivity of ice 119867119894 is the ice thickness assumed to be 3 119898 where sea ice is present 119879119894 is273 degrees Kelvin and 119879119892 is the temperature of the sea ice

NOTE QICE is not available through model version 53 but is available in subsequent versions

Net upward Longwave Flux at the surface (1198821198861199051199051199041198982)

RADLWG = 119865119873119890119905119871119882119873119903119901ℎ119910119904+1

= 119865 uarr119871119882119873119903119901ℎ119910119904+1 minus 119865 darr

119871119882119873119903119901ℎ119910119904+1

where Nrphys+1 indicates the lowest model edge-level or 119901 = 119901119904119906119903119891 119865 uarr119871119882 is the upward Longwave flux and 119865 darr

119871119882 isthe downward Longwave flux

Net downard shortwave Flux at the surface (1198821198861199051199051199041198982)

RADSWG = 119865119873119890119905119878119882119873119903119901ℎ119910119904+1

= 119865 darr119878119882119873119903119901ℎ119910119904+1 minus 119865 uarr

119878119882119873119903119901ℎ119910119904+1

where Nrphys+1 indicates the lowest model edge-level or 119901 = 119901119904119906119903119891 119865 darr119878119882 is the downward Shortwave flux and 119865 uarr

119878119882

is the upward Shortwave flux

Richardson number (119889119894119898119890119899119904119894119900119899119897119890119904119904)

The non-dimensional stability indicator is the ratio of the buoyancy to the shear

119892120579119907

120597120579119907120597119911

(120597119906120597119911 )2 + (120597119907

120597119911 )2=

119888119901120597120579119907120597119911

120597119875120581

120597119911

(120597119906120597119911 )2 + (120597119907

120597119911 )2

where we used the hydrostatic equation

120597Φ

120597119875120581= 119888119901120579119907

Negative values indicate unstable buoyancy AND shear small positive values (lt 04) indicate dominantly unstableshear and large positive values indicate dominantly stable stratification

CT - Surface Exchange Coefficient for Temperature and Moisture (dimensionless)

The surface exchange coefficient is obtained from the similarity functions for the stability dependant flux profilerelationships

CT = minus (119908prime120579prime)

119906∆119902=

119896

(120595ℎ + 120595119892)

where 120595ℎ is the surface layer non-dimensional temperature change and 120595119892 is the viscous sublayer non-dimensionaltemperature or moisture change

120595ℎ =

int 120577

1205770

120593ℎ120577119889120577 119886119899119889 120595119892 =

055(11987511990323 minus 02)

12058412(ℎ0119906 minus ℎ0119903119890119891119906119903119890119891

and ℎ0 = 301199110 with a maximum value over land of 001

120593ℎ is the similarity function of 120577 which expresses the stability dependance of the temperature and moisture gra-dients specified differently for stable and unstable layers according to k is the Von Karman constant 120577 is thenon-dimensional stability parameter Pr is the Prandtl number for air 120584 is the molecular viscosity 1199110 is the surfaceroughness length 119906 is the surface stress velocity (see diagnostic number 67) and the subscript ref refers to a referencevalue

CU - Surface Exchange Coefficient for Momentum (dimensionless)

CU =119906119882119904

=119896

120595119898

where 120595119898 is the surface layer non-dimensional wind shear

120595119898 =

int 120577

1205770

120593119898120577119889120577

120593119898 is the similarity function of 120577 which expresses the stability dependance of the temperature and moisture gradi-ents specified differently for stable and unstable layers according to k is the Von Karman constant 120577 is the non-dimensional stability parameter 119906 is the surface stress velocity (see diagnostic number 67) and 119882119904 is the magnitudeof the surface layer wind

ET - Diffusivity Coefficient for Temperature and Moisture (m^2sec)

In the level 25 version of the Mellor-Yamada (1974) hierarchy the turbulent heat or moisture flux for the atmosphereabove the surface layer can be expressed as a turbulent diffusion coefficient 119870ℎ times the negative of the gradient ofpotential temperature or moisture In the [HL88] adaptation of this closure 119870ℎ takes the form

ET = 119870ℎ = minus (119908prime120579prime119907)120597120579119907120597119911

119902119890ℓ 119878119867(119866119872119890

where 119902 is the turbulent velocity orradic

2 119905119906119903119887119906119897119890119899119905 119896119894119899119890119905119894119888 119890119899119890119903119892119910 119902119890 is the turbulence velocity derived from themore simple level 20 model which describes equilibrium turbulence ℓ is the master length scale related to the layerdepth 119878119867 is a function of 119866119867 and 119866119872 the dimensionless buoyancy and wind shear parameters respectively or afunction of 119866119867119890 and 119866119872119890 the equilibrium dimensionless buoyancy and wind shear parameters Both 119866119867 and 119866119872 and their equilibrium values 119866119867119890 and 119866119872119890 are functions of the Richardson number

For the detailed equations and derivations of the modified level 25 closure scheme see [HL88]

In the surface layer ET is the exchange coefficient for heat and moisture in units of 119898119904119890119888 given by

ETNrphys = 119862119905 119906 = 119862119867119882119904

where 119862119905 is the dimensionless exchange coefficient for heat and moisture from the surface layer similarity functions(see diagnostic number 9) 119906 is the surface friction velocity (see diagnostic number 67) 119862119867 is the heat transfercoefficient and 119882119904 is the magnitude of the surface layer wind

EU - Diffusivity Coefficient for Momentum (m^2sec)

In the level 25 version of the Mellor-Yamada (1974) hierarchy the turbulent heat momentum flux for the atmosphereabove the surface layer can be expressed as a turbulent diffusion coefficient 119870119898 times the negative of the gradient ofthe u-wind In the [HL88] adaptation of this closure 119870119898 takes the form

EU = 119870119898 = minus (119906prime119908prime)120597119880120597119911

119902119890ℓ 119878119872 (119866119872119890 119866119867119890) for growing turbulence

In the surface layer EU is the exchange coefficient for momentum in units of 119898119904119890119888 given by

EUNrphys = 119862119906 119906 = 119862119863119882119904

where 119862119906 is the dimensionless exchange coefficient for momentum from the surface layer similarity functions (seediagnostic number 10) 119906 is the surface friction velocity (see diagnostic number 67)119862119863 is the surface drag coefficientand 119882119904 is the magnitude of the surface layer wind

TURBU - Zonal U-Momentum changes due to Turbulence (msecday)

The tendency of U-Momentum due to turbulence is written

TURBU =120597119906

120597119905 119905119906119903119887=

120597

120597119911(119870119898

120597119906

120597119911)

The Helfand and Labraga level 25 scheme models the turbulent flux of u-momentum in terms of119870119898 and the equationhas the form of a diffusion equation

TURBV - Meridional V-Momentum changes due to Turbulence (msecday)

The tendency of V-Momentum due to turbulence is written

TURBV =120597119907

120597119905 119905119906119903119887=

120597

120597119911(119870119898

120597119907

120597119911)

The Helfand and Labraga level 25 scheme models the turbulent flux of v-momentum in terms of119870119898 and the equationhas the form of a diffusion equation

TURBT - Temperature changes due to Turbulence (degday)

The tendency of temperature due to turbulence is written

TURBT =120597119879

120597119905= 119875120581 120597120579

120597119905 119905119906119903119887= 119875120581 120597

120597119911(119870ℎ

120597120579119907120597119911

The Helfand and Labraga level 25 scheme models the turbulent flux of temperature in terms of 119870ℎ and the equationhas the form of a diffusion equation

TURBQ - Specific Humidity changes due to Turbulence (gkgday)

The tendency of specific humidity due to turbulence is written

TURBQ =120597119902

120597119905 119905119906119903119887=

120597

120597119911(119870ℎ

120597119902

120597119911)

MOISTT - Temperature Changes Due to Moist Processes (degday)

MOISTT =120597119879

120597119905

119888

+120597119879

120597119905

119897119904

where120597119879

120597119905

119888

= 119877sum119894

(120572119898119861

119888119901Γ119904

)119894

119886119899119889120597119879

120597119905

119897119904

=119871

119888119901(119902 minus 119902)

119886119899119889

Γ119904 = 119892120578120597119904

120597119901

The subscript 119888 refers to convective processes while the subscript 119897119904 refers to large scale precipitation processes orsupersaturation rain The summation refers to contributions from each cloud type called by RAS The dry static energyis given as 119904 the convective cloud base mass flux is given as 119898119861 and the cloud entrainment is given as 120578 which areexplicitly defined in Section 8532 the description of the convective parameterization The fractional adjustment orrelaxation parameter for each cloud type is given as 120572 while 119877 is the rain re-evaporation adjustment

MOISTQ - Specific Humidity Changes Due to Moist Processes (gkgday)

MOISTQ =120597119902

120597119905

119888

+120597119902

120597119905

119897119904

where120597119902

120597119905

119888

= 119877sum119894

(120572119898119861

119871(Γℎ minus Γ119904)

)119894

119886119899119889120597119902

120597119905

119897119904

= (119902 minus 119902)

Γ119904 = 119892120578120597119904

120597119901119886119899119889 Γℎ = 119892120578

120597ℎ

120597119901

The subscript 119888 refers to convective processes while the subscript 119897119904 refers to large scale precipitation processesor supersaturation rain The summation refers to contributions from each cloud type called by RAS The dry staticenergy is given as 119904 the moist static energy is given as ℎ the convective cloud base mass flux is given as 119898119861 andthe cloud entrainment is given as 120578 which are explicitly defined in Section 8532 the description of the convectiveparameterization The fractional adjustment or relaxation parameter for each cloud type is given as 120572 while 119877 is therain re-evaporation adjustment

RADLW - Heating Rate due to Longwave Radiation (degday)

The net longwave heating rate is calculated as the vertical divergence of the net terrestrial radiative fluxes Both theclear-sky and cloudy-sky longwave fluxes are computed within the longwave routine The subroutine calculates theclear-sky flux 119865 119888119897119890119886119903119904119896119910

119871119882 first For a given cloud fraction the clear line-of-sight probability 119862(119901 119901prime) is computed fromthe current level pressure 119901 to the model top pressure 119901prime = 119901119905119900119901 and the model surface pressure 119901prime = 119901119904119906119903119891 for theupward and downward radiative fluxes (see Section [secfizhiradcloud]) The cloudy-sky flux is then obtained as

119865119871119882 = 119862(119901 119901prime) middot 119865 119888119897119890119886119903119904119896119910119871119882

Finally the net longwave heating rate is calculated as the vertical divergence of the net terrestrial radiative fluxes

120597120588119888119901119879

120597119905= minus 120597

120597119911119865119873119864119879119871119882

RADLW =119892

119888119901120587

120597

120597120590119865119873119864119879119871119882

where 119892 is the accelation due to gravity 119888119901 is the heat capacity of air at constant pressure and

119865119873119864119879119871119882 = 119865 uarr

119871119882 minus 119865 darr119871119882

RADSW - Heating Rate due to Shortwave Radiation (degday)

The net Shortwave heating rate is calculated as the vertical divergence of the net solar radiative fluxes The clear-skyand cloudy-sky shortwave fluxes are calculated separately For the clear-sky case the shortwave fluxes and heatingrates are computed with both CLMO (maximum overlap cloud fraction) and CLRO (random overlap cloud fraction)set to zero (see Section [secfizhiradcloud]) The shortwave routine is then called a second time for the cloudy-skycase with the true time-averaged cloud fractions CLMO and CLRO being used In all cases a normalized incidentshortwave flux is used as input at the top of the atmosphere

The heating rate due to Shortwave Radiation under cloudy skies is defined as

120597120588119888119901119879

120597119905= minus 120597

120597119911119865 (119888119897119900119906119889119910)119873119864119879

119878119882 middot RADSWT

RADSW =119892

119888119901120587

120597

120597120590119865 (119888119897119900119906119889119910)119873119864119879

where 119892 is the accelation due to gravity 119888119901 is the heat capacity of air at constant pressure RADSWT is the true incidentshortwave radiation at the top of the atmosphere (See Diagnostic 48) and

119865 (119888119897119900119906119889119910)119873119890119905119878119882 = 119865 (119888119897119900119906119889119910)uarr119878119882 minus 119865 (119888119897119900119906119889119910)darr119878119882

PREACC - Total (Large-scale + Convective) Accumulated Precipition (mmday)

For a change in specific humidity due to moist processes ∆119902119898119900119894119904119905 the vertical integral or total precipitable amount isgiven by

PREACC =

int 119905119900119901

119904119906119903119891

120588∆119902119898119900119894119904119905119889119911 = minusint 119905119900119901

119904119906119903119891

∆119902119898119900119894119904119905119889119901

119892=

119892

∆119902119898119900119894119904119905119889119901

A precipitation rate is defined as the vertically integrated moisture adjustment per Moist Processes time step scaled to119898119898119889119886119910

PRECON - Convective Precipition (mmday)

For a change in specific humidity due to sub-grid scale cumulus convective processes ∆119902119888119906119898 the vertical integral ortotal precipitable amount is given by

PRECON =

int 119905119900119901

119904119906119903119891

120588∆119902119888119906119898119889119911 = minusint 119905119900119901

119904119906119903119891

∆119902119888119906119898119889119901

119892=

119892

∆119902119888119906119898119889119901

TUFLUX - Turbulent Flux of U-Momentum (Newtonm^2)

The turbulent flux of u-momentum is calculated for 119889119894119886119892119899119900119904119905119894119888 119901119906119903119901119900119904119890119904 119900119899119897119910 from the eddy coefficient for mo-mentum

TUFLUX = 120588(119906prime119908prime) = 120588(minus119870119898120597119880

120597119911)

where 120588 is the air density and 119870119898 is the eddy coefficient

TVFLUX - Turbulent Flux of V-Momentum (Newtonm^2)

The turbulent flux of v-momentum is calculated for 119889119894119886119892119899119900119904119905119894119888 119901119906119903119901119900119904119890119904 119900119899119897119910 from the eddy coefficient for mo-mentum

TVFLUX = 120588(119907prime119908prime) = 120588(minus119870119898120597119881

120597119911)

TTFLUX - Turbulent Flux of Sensible Heat (Wattsm^2)

The turbulent flux of sensible heat is calculated for 119889119894119886119892119899119900119904119905119894119888 119901119906119903119901119900119904119890119904 119900119899119897119910 from the eddy coefficient for heatand moisture

TTFLUX = 119888119901120588119875120581(119908prime120579prime) = 119888119901120588119875

120581(minus119870ℎ120597120579119907120597119911

where 120588 is the air density and 119870ℎ is the eddy coefficient

TQFLUX - Turbulent Flux of Latent Heat (Wattsm^2)

The turbulent flux of latent heat is calculated for 119889119894119886119892119899119900119904119905119894119888 119901119906119903119901119900119904119890119904 119900119899119897119910 from the eddy coefficient for heat andmoisture

TQFLUX = 119871120588(119908prime119902prime) = 119871120588(minus119870ℎ120597119902

120597119911)

CN - Neutral Drag Coefficient (dimensionless)

The drag coefficient for momentum obtained by assuming a neutrally stable surface layer

CN =119896

ln( ℎ1199110

where 119896 is the Von Karman constant ℎ is the height of the surface layer and 1199110 is the surface roughness

NOTE CN is not available through model version 53 but is available in subsequent versions

WINDS - Surface Wind Speed (metersec)

The surface wind speed is calculated for the last internal turbulence time step

WINDS =radic1199062119873119903119901ℎ119910119904 + 1199072119873119903119901ℎ119910119904

where the subscript 119873119903119901ℎ119910119904 refers to the lowest model level

The airsurface virtual temperature difference measures the stability of the surface layer

DTSRF = (120579119907119873119903119901ℎ119910119904+1 minus 120579119907119873119903119901ℎ119910119904)119875120581119904119906119903119891

120579119907119873119903119901ℎ119910119904+1 =119879119892

119875120581119904119906119903119891

(1 + 609119902119873119903119901ℎ119910119904+1) 119886119899119889 119902119873119903119901ℎ119910119904+1 = 119902119873119903119901ℎ119910119904 + 120573(119902(119879119892 119875119904) minus 119902119873119903119901ℎ119910119904)

120573 is the surface potential evapotranspiration coefficient (120573 = 1 over oceans) 119902(119879119892 119875119904) is the saturation specifichumidity at the ground temperature and surface pressure level 119873119903119901ℎ119910119904 refers to the lowest model level and level119873119903119901ℎ119910119904+ 1 refers to the surface

TG - Ground Temperature (deg K)

TG 119894119904 119900119887119905119886119894119899119890119889 119891119903119900119898 119862119892120597119879119892120597119905

where 119877119904119908 is the net surface downward shortwave radiative flux 119877119897119908 is the net surface upward longwave radiativeflux 119876119894119888119890 is the heat conduction through sea ice 119867 is the upward sensible heat flux 119871119864 is the upward latent heat fluxand 119862119892 is the total heat capacity of the ground 119862119892 is obtained by solving a heat diffusion equation for the penetrationof the diurnal cycle into the ground () and is given by

119862119892 =

radic120582119862119904

2120596=

radic(0386 + 0536119882 + 015119882 2)211990910minus3

2120587

Here the thermal conductivity 120582 is equal to 211990910minus3 119897119910119904119890119888

TS - Surface Temperature (deg K)

The surface temperature estimate is made by assuming that the modelrsquos lowest layer is well-mixed and therefore that120579 is constant in that layer The surface temperature is therefore

TS = 120579119873119903119901ℎ119910119904119875120581119904119906119903119891

DTG - Surface Temperature Adjustment (deg K)

The change in surface temperature from one turbulence time step to the next solved using the Ground TemperatureEquation (see diagnostic number 30) is calculated

DTG = 119879119892119899 minus 119879119892

119899minus1

where superscript 119899 refers to the new updated time level and the superscript 119899minus 1 refers to the value at the previousturbulence time level

QG - Ground Specific Humidity (gkg)

The ground specific humidity is obtained by interpolating between the specific humidity at the lowest model leveland the specific humidity of a saturated ground The interpolation is performed using the potential evapotranspirationfunction

QG = 119902119873119903119901ℎ119910119904+1 = 119902119873119903119901ℎ119910119904 + 120573(119902(119879119892 119875119904) minus 119902119873119903119901ℎ119910119904)

where 120573 is the surface potential evapotranspiration coefficient (120573 = 1 over oceans) and 119902(119879119892 119875119904) is the saturationspecific humidity at the ground temperature and surface pressure

QS - Saturation Surface Specific Humidity (gkg)

The surface saturation specific humidity is the saturation specific humidity at the ground temprature and surfacepressure

QS = 119902(119879119892 119875119904)

TGRLW - Instantaneous ground temperature used as input to the Longwave radiation subroutine(deg)

TGRLW = 119879119892(120582 120593 119899)

where 119879119892 is the model ground temperature at the current time step 119899

ST4 - Upward Longwave flux at the surface (Wattsm^2)

ST4 = 120590119879 4

where 120590 is the Stefan-Boltzmann constant and T is the temperature

OLR - Net upward Longwave flux at 119901 = 119901119905119900119901 (Wattsm^2)

OLR = 119865119873119864119879119871119882119905119900119901

where top indicates the top of the first model layer In the GCM 119901119905119900119901 = 00 mb

OLRCLR - Net upward clearsky Longwave flux at 119901 = 119901119905119900119901 (Wattsm^2)

OLRCLR = 119865 (119888119897119890119886119903119904119896119910)119873119864119879119871119882119905119900119901

LWGCLR - Net upward clearsky Longwave flux at the surface (Wattsm^2)

LWGCLR = 119865 (119888119897119890119886119903119904119896119910)119873119890119905119871119882119873119903119901ℎ119910119904+1

= 119865 (119888119897119890119886119903119904119896119910)uarr119871119882119873119903119901ℎ119910119904+1 minus 119865 (119888119897119890119886119903119904119896119910)darr119871119882119873119903119901ℎ119910119904+1

where Nrphys+1 indicates the lowest model edge-level or 119901 = 119901119904119906119903119891 119865 (119888119897119890119886119903119904119896119910)uarr119871119882 is the upward clearskyLongwave flux and the 119865 (119888119897119890119886119903119904119896119910)darr119871119882 is the downward clearsky Longwave flux

LWCLR - Heating Rate due to Clearsky Longwave Radiation (degday)

119865119871119882 = 119862(119901 119901prime) middot 119865 119888119897119890119886119903119904119896119910119871119882

Thus LWCLR is defined as the net longwave heating rate due to the vertical divergence of the clear-sky longwaveradiative flux

120597120588119888119901119879

120597119905 119888119897119890119886119903119904119896119910= minus 120597

120597119911119865 (119888119897119890119886119903119904119896119910)119873119864119879

119871119882

LWCLR =119892

119888119901120587

120597

120597120590119865 (119888119897119890119886119903119904119896119910)119873119864119879

119871119882

119865 (119888119897119890119886119903119904119896119910)119873119890119905119871119882 = 119865 (119888119897119890119886119903119904119896119910)uarr119871119882 minus 119865 (119888119897119890119886119903119904119896119910)darr119871119882

TLW - Instantaneous temperature used as input to the Longwave radiation subroutine (deg)

TLW = 119879 (120582 120593 119897119890119907119890119897 119899)

where 119879 is the model temperature at the current time step 119899

SHLW - Instantaneous specific humidity used as input to the Longwave radiation subroutine (kgkg)

SHLW = 119902(120582 120593 119897119890119907119890119897 119899)

where 119902 is the model specific humidity at the current time step 119899

OZLW - Instantaneous ozone used as input to the Longwave radiation subroutine (kgkg)

OZLW = OZ(120582 120593 119897119890119907119890119897 119899)

where OZ is the interpolated ozone data set from the climatological monthly mean zonally averaged ozone data set

CLMOLW - Maximum Overlap cloud fraction used in LW Radiation (0-1)

CLMOLW is the time-averaged maximum overlap cloud fraction that has been filled by the RelaxedArakawaSchubert Convection scheme and will be used in the Longwave Radiation algorithm These are convec-tive clouds whose radiative characteristics are assumed to be correlated in the vertical For a complete description ofcloudradiative interactions see Section [secfizhiradcloud]

CLMOLW = 119862119871119872119874119877119860119878119871119882 (120582 120593 119897119890119907119890119897)

CLDTOT - Total cloud fraction used in LW and SW Radiation (0-1)

CLDTOT is the time-averaged total cloud fraction that has been filled by the Relaxed ArakawaSchubert and Large-scale Convection schemes and will be used in the Longwave and Shortwave Radiation packages For a completedescription of cloudradiative interactions see Section [secfizhiradcloud]

CLDTOT = 119865119877119860119878 + 119865119871119878

where 119865119877119860119878 is the time-averaged cloud fraction due to sub-grid scale convection and 119865119871119878 is the time-averaged cloudfraction due to precipitating and non-precipitating large-scale moist processes

CLMOSW - Maximum Overlap cloud fraction used in SW Radiation (0-1)

CLMOSW is the time-averaged maximum overlap cloud fraction that has been filled by the RelaxedArakawaSchubert Convection scheme and will be used in the Shortwave Radiation algorithm These are convec-tive clouds whose radiative characteristics are assumed to be correlated in the vertical For a complete description ofcloudradiative interactions see Section [secfizhiradcloud]

CLMOSW = 119862119871119872119874119877119860119878119878119882 (120582 120593 119897119890119907119890119897)

CLROSW - Random Overlap cloud fraction used in SW Radiation (0-1)

CLROSW is the time-averaged random overlap cloud fraction that has been filled by the Relaxed ArakawaSchubertand Large-scale Convection schemes and will be used in the Shortwave Radiation algorithm These are convectiveand large-scale clouds whose radiative characteristics are not assumed to be correlated in the vertical For a completedescription of cloudradiative interactions see Section [secfizhiradcloud]

CLROSW = 119862119871119877119874119877119860119878119871119886119903119892119890119878119888119886119897119890119878119882 (120582 120593 119897119890119907119890119897)

RADSWT - Incident Shortwave radiation at the top of the atmosphere (Wattsm^2)

RADSWT =1198780

1198772119886

middot 119888119900119904120593119911

where 1198780 is the extra-terrestial solar contant 119877119886 is the earth-sun distance in Astronomical Units and 119888119900119904120593119911 is thecosine of the zenith angle It should be noted that RADSWT as well as OSR and OSRCLR are calculated at the topof the atmosphere (p=0 mb) However the OLR and OLRCLR diagnostics are currently calculated at 119901 = 119901119905119900119901 (00mb for the GCM)

EVAP - Surface Evaporation (mmday)

The surface evaporation is a function of the gradient of moisture the potential evapotranspiration fraction and the eddyexchange coefficient

EVAP = 120588120573119870ℎ(119902119904119906119903119891119886119888119890 minus 119902119873119903119901ℎ119910119904)

where 120588 = the atmospheric density at the surface 120573 is the fraction of the potential evapotranspiration actually evapo-rated (120573 = 1 over oceans) 119870ℎ is the turbulent eddy exchange coefficient for heat and moisture at the surface in119898119904119890119888and 119902119904119906119903119891119886119888119890 and 119902119873119903119901ℎ119910119904 are the specific humidity at the surface (see diagnostic number 34) and at the bottom modellevel respectively

DUDT - Total Zonal U-Wind Tendency (msecday)

DUDT is the total time-tendency of the Zonal U-Wind due to Hydrodynamic Diabatic and Analysis forcing

DUDT =120597119906

120597119905 119863119910119899119886119898119894119888119904+120597119906

120597119905119872119900119894119904119905+120597119906

120597119905 119879119906119903119887119906119897119890119899119888119890+120597119906

120597119905 119860119899119886119897119910119904119894119904

DVDT - Total Zonal V-Wind Tendency (msecday)

DVDT is the total time-tendency of the Meridional V-Wind due to Hydrodynamic Diabatic and Analysis forcing

DVDT =120597119907

120597119905 119863119910119899119886119898119894119888119904+120597119907

120597119905119872119900119894119904119905+120597119907

120597119905 119879119906119903119887119906119897119890119899119888119890+120597119907

120597119905 119860119899119886119897119910119904119894119904

DTDT - Total Temperature Tendency (degday)

DTDT is the total time-tendency of Temperature due to Hydrodynamic Diabatic and Analysis forcing

DTDT =120597119879

120597119905 119863119910119899119886119898119894119888119904+120597119879

120597119905 119872119900119894119904119905119875119903119900119888119890119904119904119890119904+120597119879

120597119905 119878ℎ119900119903119905119908119886119907119890119877119886119889119894119886119905119894119900119899

+120597119879

120597119905 119871119900119899119892119908119886119907119890119877119886119889119894119886119905119894119900119899+120597119879

120597119905 119879119906119903119887119906119897119890119899119888119890+120597119879

120597119905 119860119899119886119897119910119904119894119904

DQDT - Total Specific Humidity Tendency (gkgday)

DQDT is the total time-tendency of Specific Humidity due to Hydrodynamic Diabatic and Analysis forcing

DQDT =120597119902

120597119905119863119910119899119886119898119894119888119904+120597119902

120597119905119872119900119894119904119905119875119903119900119888119890119904119904119890119904+120597119902

120597119905 119879119906119903119887119906119897119890119899119888119890+120597119902

120597119905119860119899119886119897119910119904119894119904

USTAR - Surface-Stress Velocity (msec)

The surface stress velocity or the friction velocity is the wind speed at the surface layer top impeded by the surfacedrag

USTAR = 119862119906119882119904 119908ℎ119890119903119890 119862119906 =119896

120595119898

119862119906 is the non-dimensional surface drag coefficient (see diagnostic number 10) and 119882119904 is the surface wind speed (seediagnostic number 28)

Z0 - Surface Roughness Length (m)

Over the land surface the surface roughness length is interpolated to the local time from the monthly mean data of Over the ocean the roughness length is a function of the surface-stress velocity 119906

Z0 = 11988811199063 + 1198882119906

2 + 1198883119906 + 1198884 + 1198885119906

where the constants are chosen to interpolate between the reciprocal relation of for weak winds and the piecewiselinear relation of for moderate to large winds

FRQTRB - Frequency of Turbulence (0-1)

The fraction of time when turbulence is present is defined as the fraction of time when the turbulent kinetic energyexceeds some minimum value defined here to be 0005 11989821199041198901198882 When this criterion is met a counter is incrementedThe fraction over the averaging interval is reported

PBL - Planetary Boundary Layer Depth (mb)

The depth of the PBL is defined by the turbulence parameterization to be the depth at which the turbulent kineticenergy reduces to ten percent of its surface value

PBL = 119875119875119861119871 minus 119875119904119906119903119891119886119888119890

where 119875119875119861119871 is the pressure in 119898119887 at which the turbulent kinetic energy reaches one tenth of its surface value and 119875119904

is the surface pressure

SWCLR - Clear sky Heating Rate due to Shortwave Radiation (degday)

The heating rate due to Shortwave Radiation under clear skies is defined as

120597120588119888119901119879

120597119905= minus 120597

120597119911119865 (119888119897119890119886119903)119873119864119879

SWCLR =119892

119888119901

120597

120597119901119865 (119888119897119890119886119903)119873119864119879

119865 (119888119897119890119886119903)119873119890119905119878119882 = 119865 (119888119897119890119886119903)uarr119878119882 minus 119865 (119888119897119890119886119903)darr119878119882

OSR - Net upward Shortwave flux at the top of the model (Wattsm^2)

OSR = 119865119873119864119879119878119882119905119900119901

where top indicates the top of the first model layer used in the shortwave radiation routine In the GCM 119901119878119882119905119900119901= 0

OSRCLR - Net upward clearsky Shortwave flux at the top of the model (Wattsm^2)

OSRCLR = 119865 (119888119897119890119886119903119904119896119910)119873119864119879119878119882119905119900119901

CLDMAS - Convective Cloud Mass Flux (kgm^2)

The amount of cloud mass moved per RAS timestep from all convective clouds is written

CLDMAS = 120578119898119861

where 120578 is the entrainment normalized by the cloud base mass flux and 119898119861 is the cloud base mass flux 119898119861 and 120578are defined explicitly in Section 8532 the description of the convective parameterization

UAVE - Time-Averaged Zonal U-Wind (msec)

The diagnostic UAVE is simply the time-averaged Zonal U-Wind over the NUAVE output frequency This is contrastedto the instantaneous Zonal U-Wind which is archived on the Prognostic Output data stream

UAVE = 119906(120582 120593 119897119890119907119890119897 119905)

Note UAVE is computed and stored on the staggered C-grid

VAVE - Time-Averaged Meridional V-Wind (msec)

The diagnostic VAVE is simply the time-averaged Meridional V-Wind over the NVAVE output frequency This iscontrasted to the instantaneous Meridional V-Wind which is archived on the Prognostic Output data stream

VAVE = 119907(120582 120593 119897119890119907119890119897 119905)

Note VAVE is computed and stored on the staggered C-grid

TAVE - Time-Averaged Temperature (Kelvin)

The diagnostic TAVE is simply the time-averaged Temperature over the NTAVE output frequency This is contrastedto the instantaneous Temperature which is archived on the Prognostic Output data stream

TAVE = 119879 (120582 120593 119897119890119907119890119897 119905)

QAVE - Time-Averaged Specific Humidity (gkg)

The diagnostic QAVE is simply the time-averaged Specific Humidity over the NQAVE output frequency This iscontrasted to the instantaneous Specific Humidity which is archived on the Prognostic Output data stream

QAVE = 119902(120582 120593 119897119890119907119890119897 119905)

PAVE - Time-Averaged Surface Pressure - PTOP (mb)

The diagnostic PAVE is simply the time-averaged Surface Pressure - PTOP over the NPAVE output frequency Thisis contrasted to the instantaneous Surface Pressure - PTOP which is archived on the Prognostic Output data stream

PAVE = 120587(120582 120593 119897119890119907119890119897 119905)

= 119901119904(120582 120593 119897119890119907119890119897 119905) minus 119901119879

QQAVE - Time-Averaged Turbulent Kinetic Energy (msec)^2

The diagnostic QQAVE is simply the time-averaged prognostic Turbulent Kinetic Energy produced by the GCMTurbulence parameterization over the NQQAVE output frequency This is contrasted to the instantaneous TurbulentKinetic Energy which is archived on the Prognostic Output data stream

QQAVE = 119902119902(120582 120593 119897119890119907119890119897 119905)

Note QQAVE is computed and stored at the ldquomass-pointrdquo locations on the staggered C-grid

SWGCLR - Net downward clearsky Shortwave flux at the surface (Wattsm^2)

SWGCLR = 119865 (119888119897119890119886119903119904119896119910)119873119890119905119878119882119873119903119901ℎ119910119904+1

= 119865 (119888119897119890119886119903119904119896119910)darr119878119882119873119903119901ℎ119910119904+1 minus 119865 (119888119897119890119886119903119904119896119910)uarr119878119882119873119903119901ℎ119910119904+1

where Nrphys+1 indicates the lowest model edge-level or 119901 = 119901119904119906119903119891 119865 (119888119897119890119886119903119904119896119910)119878119882 darr is the downward clearskyShortwave flux and 119865 (119888119897119890119886119903119904119896119910)uarr119878119882 is the upward clearsky Shortwave flux

DIABU - Total Diabatic Zonal U-Wind Tendency (msecday)

DIABU is the total time-tendency of the Zonal U-Wind due to Diabatic processes and the Analysis forcing

DIABU =120597119906

120597119905119872119900119894119904119905+120597119906

120597119905 119879119906119903119887119906119897119890119899119888119890+120597119906

120597119905 119860119899119886119897119910119904119894119904

DIABV - Total Diabatic Meridional V-Wind Tendency (msecday)

DIABV is the total time-tendency of the Meridional V-Wind due to Diabatic processes and the Analysis forcing

DIABV =120597119907

120597119905119872119900119894119904119905+120597119907

120597119905 119879119906119903119887119906119897119890119899119888119890+120597119907

120597119905 119860119899119886119897119910119904119894119904

DIABT Total Diabatic Temperature Tendency (degday)

DIABT is the total time-tendency of Temperature due to Diabatic processes and the Analysis forcing

DIABT =120597119879

120597119905 119872119900119894119904119905119875119903119900119888119890119904119904119890119904+120597119879

120597119905 119878ℎ119900119903119905119908119886119907119890119877119886119889119894119886119905119894119900119899

+120597119879

120597119905 119871119900119899119892119908119886119907119890119877119886119889119894119886119905119894119900119899+120597119879

120597119905 119879119906119903119887119906119897119890119899119888119890+120597119879

120597119905 119860119899119886119897119910119904119894119904

If we define the time-tendency of Temperature due to Diabatic processes as

120597119879

120597119905 119863119894119886119887119886119905119894119888=

120597119879

120597119905 119872119900119894119904119905119875119903119900119888119890119904119904119890119904+120597119879

120597119905 119878ℎ119900119903119905119908119886119907119890119877119886119889119894119886119905119894119900119899

+120597119879

120597119905 119871119900119899119892119908119886119907119890119877119886119889119894119886119905119894119900119899+120597119879

120597119905 119879119906119903119887119906119897119890119899119888119890

then since there are no surface pressure changes due to Diabatic processes we may write

120597119879

120597119905 119863119894119886119887119886119905119894119888=119901120581

120587

120597120587120579

120597119905 119863119894119886119887119886119905119894119888

where 120579 = 119879119901120581 Thus DIABT may be written as

DIABT =119901120581

120587

(120597120587120579

120597119905 119863119894119886119887119886119905119894119888+120597120587120579

120597119905 119860119899119886119897119910119904119894119904

DIABQ - Total Diabatic Specific Humidity Tendency (gkgday)

DIABQ is the total time-tendency of Specific Humidity due to Diabatic processes and the Analysis forcing

DIABQ =120597119902

120597119905119872119900119894119904119905119875119903119900119888119890119904119904119890119904+120597119902

120597119905 119879119906119903119887119906119897119890119899119888119890+120597119902

120597119905119860119899119886119897119910119904119894119904

If we define the time-tendency of Specific Humidity due to Diabatic processes as

120597119902

120597119905119863119894119886119887119886119905119894119888=120597119902

120597119905119872119900119894119904119905119875119903119900119888119890119904119904119890119904+120597119902

120597119905 119879119906119903119887119906119897119890119899119888119890

120597119902

120597119905119863119894119886119887119886119905119894119888=

120587

120597120587119902

120597119905 119863119894119886119887119886119905119894119888

119879ℎ119906119904 119863119868119860119861119876 119898119886119910119887119890119908119903119894119905119905119890119899119886119904

DIABQ =1

120587

(120597120587119902

120597119905 119863119894119886119887119886119905119894119888+120597120587119902

120597119905 119860119899119886119897119910119904119894119904

VINTUQ - Vertically Integrated Moisture Flux (msec gkg)

The vertically integrated moisture flux due to the zonal u-wind is obtained by integrating 119906119902 over the depth of theatmosphere at each model timestep and dividing by the total mass of the column

VINTUQ =

int 119905119900119901

119904119906119903119891119906119902120588119889119911int 119905119900119901

119904119906119903119891120588119889119911

Using 120588120575119911 = minus 120575119901119892 = minus 1

119892 120575119901 we have

VINTUQ =

119906119902119889119901

VINTVQ - Vertically Integrated Moisture Flux (msec gkg)

The vertically integrated moisture flux due to the meridional v-wind is obtained by integrating 119907119902 over the depth of theatmosphere at each model timestep and dividing by the total mass of the column

VINTVQ =

int 119905119900119901

119904119906119903119891119907119902120588119889119911int 119905119900119901

119904119906119903119891120588119889119911

119892 120575119901 we have

VINTVQ =

119907119902119889119901

VINTUT - Vertically Integrated Heat Flux (msec deg)

The vertically integrated heat flux due to the zonal u-wind is obtained by integrating 119906119879 over the depth of the atmo-sphere at each model timestep and dividing by the total mass of the column

VINTUT =

int 119905119900119901

119904119906119903119891119906119879120588119889119911int 119905119900119901

119904119906119903119891120588119889119911

VINTUT =

119906119879119889119901

VINTVT - Vertically Integrated Heat Flux (msec deg)

The vertically integrated heat flux due to the meridional v-wind is obtained by integrating 119907119879 over the depth of theatmosphere at each model timestep and dividing by the total mass of the column

VINTVT =

int 119905119900119901

119904119906119903119891119907119879120588119889119911int 119905119900119901

119904119906119903119891120588119889119911

Using 120588120575119911 = minus 120575119901119892 we have

VINTVT =

119907119879119889119901

CLDFRC - Total 2-Dimensional Cloud Fracton (0-1)

If we define the time-averaged random and maximum overlapped cloudiness as CLRO and CLMO respectively thenthe probability of clear sky associated with random overlapped clouds at any level is (1-CLRO) while the probabilityof clear sky associated with maximum overlapped clouds at any level is (1-CLMO) The total clear sky probabilityis given by (1-CLRO)(1-CLMO) thus the total cloud fraction at each level may be obtained by 1-(1-CLRO)(1-CLMO)

At any given level we may define the clear line-of-site probability by appropriately accounting for the maximumand random overlap cloudiness The clear line-of-site probability is defined to be equal to the product of the clearline-of-site probabilities associated with random and maximum overlap cloudiness The clear line-of-site probability119862(119901 119901prime) associated with maximum overlap clouds from the current pressure 119901 to the model top pressure 119901prime = 119901119905119900119901or the model surface pressure 119901prime = 119901119904119906119903119891 is simply 10 minus the largest maximum overlap cloud value along theline-of-site ie

1 minus119872119860119883119901prime

119901 (119862119871119872119874119901)

Thus even in the time-averaged sense it is assumed that the maximum overlap clouds are correlated in the verticalThe clear line-of-site probability associated with random overlap clouds is defined to be the product of the clear skyprobabilities at each level along the line-of-site ie

119901primeprod119901

(1 minus 119862119871119877119874119901)

The total cloud fraction at a given level associated with a line- of-site calculation is given by

1 minus(

1 minus119872119860119883119901prime

119901 [119862119871119872119874119901]) 119901primeprod

119901

(1 minus 119862119871119877119874119901)

The 2-dimensional net cloud fraction as seen from the top of the atmosphere is given by

CLDFRC = 1 minus(

1 minus119872119860119883119873119903119901ℎ119910119904119897=1198971

[119862119871119872119874119897])119873119903119901ℎ119910119904prod

119897=1198971

(1 minus 119862119871119877119874119897)

For a complete description of cloudradiative interactions see Section [secfizhiradcloud]

QINT - Total Precipitable Water (gmcm^2)

The Total Precipitable Water is defined as the vertical integral of the specific humidity given by

QINT =

int 119905119900119901

119904119906119903119891

120588119902119889119911

=120587

119892

119902119889119901

where we have used the hydrostatic relation 120588120575119911 = minus 120575119901119892

U2M Zonal U-Wind at 2 Meter Depth (msec)

The u-wind at the 2-meter depth is determined from the similarity theory

U2M =1199061198961205951198982119898

119906119904119897119882119904

=1205951198982119898

120595119898119904119897

119906119904119897

where 120595119898(2119898) is the non-dimensional wind shear at two meters and the subscript 119904119897 refers to the height of the top ofthe surface layer If the roughness height is above two meters U2M is undefined

V2M - Meridional V-Wind at 2 Meter Depth (msec)

The v-wind at the 2-meter depth is a determined from the similarity theory

V2M =1199061198961205951198982119898

119907119904119897119882119904

=1205951198982119898

120595119898119904119897

119907119904119897

where 120595119898(2119898) is the non-dimensional wind shear at two meters and the subscript 119904119897 refers to the height of the top ofthe surface layer If the roughness height is above two meters V2M is undefined

T2M - Temperature at 2 Meter Depth (deg K)

The temperature at the 2-meter depth is a determined from the similarity theory

T2M = 119875120581(120579119896

(120595ℎ2119898 + 120595119892) + 120579119904119906119903119891 ) = 119875120581(120579119904119906119903119891 +120595ℎ2119898 + 120595119892

120595ℎ119904119897+ 120595119892

(120579119904119897 minus 120579119904119906119903119891 ))

119906

where 120595ℎ(2119898) is the non-dimensional temperature gradient at two meters 120595119892 is the non-dimensional temperaturegradient in the viscous sublayer and the subscript 119904119897 refers to the height of the top of the surface layer If the roughnessheight is above two meters T2M is undefined

Q2M - Specific Humidity at 2 Meter Depth (gkg)

The specific humidity at the 2-meter depth is determined from the similarity theory

Q2M = 119875120581 (

119902119896(120595ℎ2119898

+ 120595119892) + 119902119904119906119903119891 ) = 119875120581(119902119904119906119903119891 +120595ℎ2119898

+ 120595119892

120595ℎ119904119897+ 120595119892

(119902119904119897 minus 119902119904119906119903119891 ))

119906

where 120595ℎ(2119898) is the non-dimensional temperature gradient at two meters 120595119892 is the non-dimensional temperaturegradient in the viscous sublayer and the subscript 119904119897 refers to the height of the top of the surface layer If the roughnessheight is above two meters Q2M is undefined

U10M - Zonal U-Wind at 10 Meter Depth (msec)

The u-wind at the 10-meter depth is an interpolation between the surface wind and the model lowest level wind usingthe ratio of the non-dimensional wind shear at the two levels

U10M =11990611989612059511989810119898

119906119904119897119882119904

=12059511989810119898

120595119898119904119897

119906119904119897

where 120595119898(10119898) is the non-dimensional wind shear at ten meters and the subscript 119904119897 refers to the height of the topof the surface layer

The v-wind at the 10-meter depth is an interpolation between the surface wind and the model lowest level wind usingthe ratio of the non-dimensional wind shear at the two levels

V10M =11990611989612059511989810119898

119907119904119897119882119904

=12059511989810119898

120595119898119904119897

119907119904119897

The temperature at the 10-meter depth is an interpolation between the surface potential temperature and the modellowest level potential temperature using the ratio of the non-dimensional temperature gradient at the two levels

T10M = 119875120581(120579119896

(120595ℎ10119898 + 120595119892) + 120579119904119906119903119891 ) = 119875120581(120579119904119906119903119891 +120595ℎ10119898

+ 120595119892

120595ℎ119904119897+ 120595119892

(120579119904119897 minus 120579119904119906119903119891 ))

119906

where 120595ℎ(10119898) is the non-dimensional temperature gradient at two meters 120595119892 is the non-dimensional temperaturegradient in the viscous sublayer and the subscript 119904119897 refers to the height of the top of the surface layer

The specific humidity at the 10-meter depth is an interpolation between the surface specific humidity and the modellowest level specific humidity using the ratio of the non-dimensional temperature gradient at the two levels

Q10M = 119875120581(119902119896

(120595ℎ10119898 + 120595119892) + 119902119904119906119903119891 ) = 119875120581(119902119904119906119903119891 +120595ℎ10119898

+ 120595119892

120595ℎ119904119897+ 120595119892

(119902119904119897 minus 119902119904119906119903119891 ))

119906

DTRAIN - Cloud Detrainment Mass Flux (kgm^2)

The amount of cloud mass moved per RAS timestep at the cloud detrainment level is written

DTRAIN = 120578119903119863119898119861

where 119903119863 is the detrainment level 119898119861 is the cloud base mass flux and 120578 is the entrainment defined in Section 8532

QFILL - Filling of negative Specific Humidity (gkgday)

Due to computational errors associated with the numerical scheme used for the advection of moisture negative valuesof specific humidity may be generated The specific humidity is checked for negative values after every dynamicstimestep If negative values have been produced a filling algorithm is invoked which redistributes moisture frombelow Diagnostic QFILL is equal to the net filling needed to eliminate negative specific humidity scaled to a per-dayrate

QFILL = 119902119899+1119891119894119899119886119897 minus 119902119899+1

119894119899119894119905119894119886119897

119902119899+1 = (120587119902)119899+1120587119899+1

8536 Dos and donrsquots

8537 Fizhi Reference

8538 Experiments and tutorials that use fizhi

bull Global atmosphere experiment with realistic SST and topography in fizhi-cs-32x32x10 verification directory

bull Global atmosphere aqua planet experiment in fizhi-cs-aqualev20 verification directory

86 Sea Ice Packages

861 THSICE The Thermodynamic Sea Ice Package

Important note This document has been written by Stephanie Dutkiewicz and describes an earlier implementationof the sea-ice package This needs to be updated to reflect the recent changes (JMC)

This thermodynamic ice model is based on the 3-layer model by Winton (2000) and the energy-conserving LANLCICE model (Bitz and Lipscomb 1999) The model considers two equally thick ice layers the upper layer has avariable specific heat resulting from brine pockets the lower layer has a fixed heat capacity A zero heat capacity snowlayer lies above the ice Heat fluxes at the top and bottom surfaces are used to calculate the change in ice and snowlayer thickness Grid cells of the ocean model are either fully covered in ice or are open water There is a provision toparametrize ice fraction (and leads) in this package Modifications are discussed in small font following the subroutinedescriptions

8611 Key parameters and Routines

The ice model is called from thermodynamicsF subroutine ice_forcingF is called in place of external_forcing_surfF

In ice_forcingF we calculate the freezing potential of the ocean model surface layer of water

frzmlt = (119879119891 minus 119878119878119879 )119888119904119908120588119904119908∆119911

∆119905

where 119888119904119908 is seawater heat capacity 120588119904119908 is the seawater density ∆119911 is the ocean model upper layer thickness and ∆119905is the model (tracer) timestep The freezing temperature 119879119891 = 120583119878 is a function of the salinity

1 Provided there is no ice present and frzmlt is less than 0 the surface tendencies of wind heat and freshwaterare calculated as usual (ie as in external_forcing_surfF)

2 If there is ice present in the grid cell we call the main ice model routine ice_thermF (see below) Output fromthis routine gives net heat and freshwater flux affecting the top of the ocean

Subroutine ice_forcingF uses these values to find the sea surface tendencies in grid cells When there is ice presentthe surface stress tendencies are set to zero the ice model is purely thermodynamic and the effect of ice motion on thesea-surface is not examined

Relaxation of surface 119879 and 119878 is only allowed equatorward of relaxlat (see DATAICE below) and no relaxation isallowed under the ice at any latitude

(Note that there is provision for allowing grid cells to have both open water and seaice if compact is between 0 and1)

subroutine ICE_FREEZE

This routine is called from thermodynamicsF after the new temperature calculation calc_gtF but before calc_gsFIn ice_freezeF any ocean upper layer grid cell with no ice cover but with temperature below freezing 119879119891 = 120583119878has ice initialized We calculate frzmlt from all the grid cells in the water column that have a temperature less thanfreezing In this routine any water below the surface that is below freezing is set to 119879119891 A call to ice_startF is madeif frzmlt gt 0 and salinity tendancy is updated for brine release

(There is a provision for fractional ice In the case where the grid cell has less ice coverage than icemaskmax weallow ice_startF to be called)

subroutine ICE_START

The energy available from freezing the sea surface is brought into this routine as esurp The enthalpy of the 2 layersof any new ice is calculated as

1199021 = minus119888119894 119879119891 + 119871119894

1199022 = minus119888119891119879119898119897119905 + 119888119894(119879119898119897119905 minus 119879119891) + 119871119894(1 minus 119879119898119897119905

119879119891)

where 119888119891 is specific heat of liquid fresh water 119888119894 is the specific heat of fresh ice 119871119894 is latent heat of freezing 120588119894 isdensity of ice and 119879119898119897119905 is melting temperature of ice with salinity of 1 The height of a new layer of ice is

ℎ119894119899119890119908 =esurp∆119905

1199021198940119886119907

where 1199021198940119886119907 = minus120588119894

2 (1199021 + 1199022)

The surface skin temperature 119879119904 and ice temperatures 1198791 1198792 and the sea surface temperature are set at 119879119891

(There is provision for fractional ice new ice is formed over open water the first freezing in the cell must have aheight of himin0 this determines the ice fraction compact If there is already ice in the grid cell the new ice musthave the same height and the new ice fraction is

119894119891 = (1 minus 119894119891 )ℎ119894119899119890119908ℎ119894

where 119894119891 is ice fraction from previous timestep and ℎ119894 is current ice height Snow is redistributed over the new icefraction The ice fraction is not allowed to become larger than iceMaskmax and if the ice height is above hihig thenfreezing energy comes from the full grid cell ice growth does not occur under orginal ice due to freezing water)

subroutine ICE_THERM

The main subroutine of this package is ice_thermF where the ice temperatures are calculated and the changes in iceand snow thicknesses are determined Output provides the net heat and fresh water fluxes that force the top layer ofthe ocean model

If the current ice height is less than himin then the ice layer is set to zero and the ocean model upper layer temperatureis allowed to drop lower than its freezing temperature and atmospheric fluxes are allowed to effect the grid cell If theice height is greater than himin we proceed with the ice model calculation

We follow the procedure of Winton (1999) ndash see equations 3 to 21 ndash to calculate the surface and internal ice tem-peratures The surface temperature is found from the balance of the flux at the surface 119865119904 the shortwave heat fluxabsorbed by the ice fswint and the upward conduction of heat through the snow andor ice 119865119906 We linearize 119865119904

about the surface temperature 119879119904 at the previous timestep (whereˆindicates the value at the previous timestep)

119865119904(119879119904) = 119865119904(119879119904) +120597119865119904(119879119904)

120597119879119904(119879119904 minus 119879119904)

119865119904 = 119865119904119890119899119904119894119887119897119890 + 119865119897119886119905119890119899119905 + 119865 119889119900119908119899119897119900119899119892119908119886119907119890 + 119865119906119901

119897119900119899119892119908119886119907119890 + (1 minus 120572)119865119904ℎ119900119903119905119908119886119907119890

119889119865119904

119889119879=119889119865119904119890119899119904119894119887119897119890

119889119879+119889119865119897119886119905119890119899119905

119889119879+119889119865119906119901

119897119900119899119892119908119886119907119890

119889119879

86 Sea Ice Packages 259

119865119904 and 119889119865119904

119889119879 are currently calculated from the BULKF package described separately but could also be provided byan atmospheric model The surface albedo is calculated from the ice height andor surface temperature (see belowsrf_albedoF) and the shortwave flux absorbed in the ice is

fswint = (1 minus 119890120581119894ℎ119894)(1 minus 120572)119865119904ℎ119900119903119905119908119886119907119890

where 120581119894 is bulk extinction coefficient

The conductive flux to the surface is

119865119906 = 11987012(1198791 minus 119879119904)

where 11987012 is the effective conductive coupling of the snow-ice layer between the surface and the mid-point of theupper layer of ice mathlsquo K_12=frac4 K_i K_sK_s h_i + 4 K_i h_s mathlsquoK_i and 119870119904 are constant thermalconductivities of seaice and snow

From the above equations we can develop a system of equations to find the skin surface temperature 119879119904 and the twoice layer temperatures (see Winton 1999 for details) We solve these equations iteratively until the change in 119879119904is small When the surface temperature is greater then the melting temperature of the surface the temperatures arerecalculated setting 119879119904 to 0 The enthalpy of the ice layers are calculated in order to keep track of the energy in theice model Enthalpy is defined here as the energy required to melt a unit mass of seaice with temperature 119879 For theupper layer (1) with brine pockets and the lower fresh layer (2)

1199021 = minus119888119891119879119891 + 119888119894(119879119891 minus 119879 ) + 119871119894(1 minus 119879119891119879

1199022 = minus119888119894119879 + 119871119894

where 119888119891 is specific heat of liquid fresh water 119888119894 is the specific heat of fresh ice and 119871119894 is latent heat of melting freshice

From the new ice temperatures we can calculate the energy flux at the surface available for melting (if 119879119904=0) and theenergy at the ocean-ice interface for either melting or freezing

119864119905119900119901 = (119865119904 minus11987012(119879119904 minus 1198791))∆119905

119864119887119900119905 = (4119870119894(1198792 minus 119879119891 )

ℎ119894minus 119865119887)∆119905

where 119865119887 is the heat flux at the ice bottom due to the sea surface temperature variations from freezing If 119879119904119904119905 is abovefreezing 119865119887 = 119888119904119908120588119904119908120574(119879119904119904119905 minus 119879119891 )119906 120574 is the heat transfer coefficient and 119906 = 119876119876 is frictional velocity betweenice and water If 119879119904119904119905 is below freezing 119865119887 = (119879119891 minus 119879119904119904119905)119888119891120588119891∆119911∆119905 and set 119879119904119904119905 to 119879119891 We also include the energyfrom lower layers that drop below freezing and set those layers to 119879119891

If 119864119905119900119901 gt 0 we melt snow from the surface if all the snow is melted and there is energy left we melt the ice If theice is all gone and there is still energy left we apply the left over energy to heating the ocean model upper layer (SeeWinton 1999 equations 27-29) Similarly if 119864119887119900119905 gt 0 we melt ice from the bottom If all the ice is melted the snowis melted (with energy from the ocean model upper layer if necessary) If 119864119887119900119905 lt 0 we grow ice at the bottom

∆ℎ119894 =minus119864119887119900119905

(119902119887119900119905120588119894)

where 119902119887119900119905 = minus119888119894119879119891 +119871119894 is the enthalpy of the new ice The enthalpy of the second ice layer 1199022 needs to be modified

1199022 =ℎ11989421199022 + ∆ℎ119894119902119887119900119905

ℎ1198942 + ∆ℎ119894

If there is a ice layer and the overlying air temperature is below 0119900C then any precipitation 119875 joins the snow layer

∆ℎ119904 = minus119875 120588119891120588119904

∆119905

120588119891 and 120588119904 are the fresh water and snow densities Any evaporation similarly removes snow or ice from the surfaceWe also calculate the snow age here in case it is needed for the surface albedo calculation (see srf_albedoF below)

For practical reasons we limit the ice growth to hilim and snow is limited to hslim We converts any ice andorsnow above these limits back to water maintaining the salt balance Note however that heat is not conserved in thisconversion sea surface temperatures below the ice are not recalculated

If the snowice interface is below the waterline snow is converted to ice (see Winton 1999 equations 35 and 36) Thesubroutine new_layers_wintonF described below repartitions the ice into equal thickness layers while conservingenergy

The subroutine ice_thermF now calculates the heat and fresh water fluxes affecting the ocean model surface layerThe heat flux

119902119899119890119905 = fswocnminus 119865119887 minusesurp

∆119905is composed of the shortwave flux that has passed through the ice layer and is absorbed by the water fswocn= 119876119876 theocean flux to the ice 119865119887 and the surplus energy left over from the melting esurp The fresh water flux is determinedfrom the amount of fresh water and salt in the icesnow system before and after the timestep

(There is a provision for fractional ice If ice height is above hihig then all energy from freezing at sea surface is usedonly in the open water aparts of the cell (ie 119865119887 will only have the conduction term) The melt energy is partitioned byfrac_energy between melting ice height and ice extent However once ice height drops below himon0 then all energymelts ice extent)

subroutine SFC_ALBEDO

The routine ice_thermF calls this routine to determine the surface albedo There are two calculations provided here

1 from LANL CICE model

120572 = 119891119904120572119904 + (1 minus 119891119904)(120572119894119898119894119899+ (120572119894119898119886119909

minus 120572119894119898119894119899)(1 minus 119890minusℎ119894ℎ120572))

where 119891119904 is 1 if there is snow 0 if not the snow albedo 120572119904 has two values depending on whether 119879119904 lt 0 or not120572119894119898119894119899

and 120572119894119898119886119909are ice albedos for thin melting ice and thick bare ice respectively and ℎ120572 is a scale height

2 From GISS model (Hansen et al 1983)

120572 = 120572119894119890minusℎ119904ℎ119886 + 120572119904(1 minus 119890minusℎ119904ℎ119886)

where 120572119894 is a constant albedo for bare ice ℎ119886 is a scale height and 120572119904 is a variable snow albedo

120572119904 = 1205721 + 1205722119890minus120582119886119886119904

where 1205721 is a constant 1205722 depends on 119879119904 119886119904 is the snow age and 120582119886 is a scale frequency The snow age iscalculated in ice_thermF and is given in equation 41 in Hansen et al (1983)

subroutine NEW_LAYERS_WINTON

The subroutine new_layers_wintonF repartitions the ice into equal thickness layers while conserving energy We passto this subroutine the ice layer enthalpies after meltinggrowth and the new height of the ice layers The ending layerheight should be half the sum of the new ice heights from ice_thermF The enthalpies of the ice layers are adjustedaccordingly to maintain total energy in the ice model If layer 2 height is greater than layer 1 height then layer 2 givesice to layer 1 and

1199021 = 11989111199021 + (1 minus 1198911)1199022

where 1198911 is the fraction of the new to old upper layer heights 1198791 will therefore also have changed Similarly for whenice layer height 2 is less than layer 1 height except here we need to to be careful that the new 1198792 does not fall belowthe melting temperature

Initializing subroutines

ice_initF Set ice variables to zero or reads in pickup information from pickupic (which was written out in check-pointF)

ice_readparmsF Reads dataice

Diagnostic subroutines

ice_aveF Keeps track of means of the ice variables

ice_diagsF Finds averages and writes out diagnostics

Common Blocks

ICEh Ice Varibles also relaxlat and startIceModel

ICE_DIAGSh matrices for diagnostics averages of fields from ice_diagsF

BULKF_ICE_CONSTANTSh (in BULKF package) all the parameters need by the ice model

Input file DATAICE

Here we need to set StartIceModel which is 1 if the model starts from no ice and 0 if there is a pickup file with theice matrices (pickupic) which is read in ice_initF and written out in checkpointF The parameter relaxlat defines thelatitude poleward of which there is no relaxing of surface 119879 or 119878 to observations This avoids the relaxation forcingthe ice model at these high latitudes

(Note hicemin is set to 0 here If the provision for allowing grid cells to have both open water and seaice is everimplemented this would be greater than 0)

8613 THSICE Diagnostics

SI_Qice1| 1 |SM C198M1 |Jkg |Sea-Ice enthalpy 1srt layer (massrarr˓weighted)SI_Qice2| 1 |SM C198M1 |Jkg |Sea-Ice enthalpy 2nd layer (massrarr˓weighted)SIalbedo| 1 |SM PC197M1 |0-1 |Sea-Ice Albedo [0-1] (area weightedrarr˓average)SIsnwAge| 1 |SM P M1 |s |snow age over Sea-IceSIsnwPrc| 1 |SM C197M1 |kgm^2s |snow precip (+=dw) over Sea-Icerarr˓(area weighted)SIflxAtm| 1 |SM M1 |Wm^2 |net heat flux from the Atmosphererarr˓(+=dw)SIfrwAtm| 1 |SM M1 |kgm^2s |fresh-water flux to the Atmosphererarr˓(+=up)SIflx2oc| 1 |SM M1 |Wm^2 |heat flux out of the ocean (+=up)SIfrw2oc| 1 |SM M1 |ms |fresh-water flux out of the oceanrarr˓(+=up)SIsaltFx| 1 |SM M1 |psukgm^2 |salt flux out of the ocean (+=up)SItOcMxL| 1 |SM M1 |degC |ocean mixed layer temperatureSIsOcMxL| 1 |SM P M1 |psu |ocean mixed layer salinity

8614 References

Bitz CM and WH Lipscombe 1999 An Energy-Conserving Thermodynamic Model of Sea Ice Journal of Geo-physical Research 104 15669 ndash 15677

Hansen J G Russell D Rind P Stone A Lacis S Lebedeff R Ruedy and LTravis 1983 Efficient Three-Dimensional Global Models for Climate Studies Models I and II Monthly Weather Review 111 609 ndash 662

Winton M 2000 A reformulated Three-layer Sea Ice Model Journal of Atmospheric and Ocean Technology 17525 ndash 531

8615 Experiments and tutorials that use thsice

bull Global atmosphere experiment in aim5l_cs verification directory input from inputthsice directory

862 SEAICE Package

Authors Martin Losch Dimitris Menemenlis An Nguyen Jean-Michel Campin Patrick Heimbach Chris Hill andJinlun Zhang

8621 Introduction

Package ldquoseaicerdquo provides a dynamic and thermodynamic interactive sea-ice model

CPP options enable or disable different aspects of the package (Section Section 8622) Run-Time options flagsfilenames and field-related datestimes are set in dataseaice (Section Section 8622) A description of key sub-routines is given in Section Section 8623 Input fields units and sign conventions are summarized in Section[secpkgseaicefieldssubunits] and available diagnostics output is listed in Section [secpkgseaicediagnostics]

8622 SEAICE configuration compiling amp running

As with all MITgcm packages SEAICE can be turned on or off at compile time

bull using the packagesconf file by adding seaice to it

bull or using genmake2 adding -enable=seaice or -disable=seaice switches

bull required packages and CPP options SEAICE requires the external forcing package exf to be enabled noadditional CPP options are required

Parts of the SEAICE code can be enabled or disabled at compile time via CPP preprocessor flags These options areset in SEAICE_OPTIONSh Table 815 summarizes the most important ones For more options see the defaultpkgseaiceSEAICE_OPTIONSh

Table 815 Some of the most relevant CPP preporocessor flags in theseaice-package

CPP option DescriptionSEAICE_DEBUG Enhance STDOUT for debuggingSEAICE_ALLOW_DYNAMICS sea-ice dynamics codeSEAICE_CGRID LSR solver on C-grid (rather than original B-grid)SEAICE_ALLOW_EVP enable use of EVP rheology solverSEAICE_ALLOW_JFNK enable use of JFNK rheology solverSEAICE_EXTERNAL_FLUXES use EXF-computed fluxes as starting pointSEAICE_ZETA_SMOOTHREG use differentialable regularization for viscositiesSEAICE_VARIABLE_FREEZING_POINTenable linear dependence of the freezing point on salinity (by default unde-

fined)ALLOW_SEAICE_FLOODING enable snow to ice conversion for submerged sea-iceSEAICE_VARIABLE_SALINITY enable sea-ice with variable salinity (by default undefined)SEAICE_SITRACER enable sea-ice tracer package (by default undefined)SEAICE_BICE_STRESS B-grid only for backward compatiblity turn on ice-stress on oceanEXPLICIT_SSH_SLOPE B-grid only for backward compatiblity use ETAN for tilt computations rather

than geostrophic velocities

Run-time parameters

Run-time parameters (see Table 816) are set in files datapkg (read in packages_readparmsF) and dataseaice (readin seaice_readparmsF)

A package is switched onoff at run-time by setting (eg for SEAICE useSEAICE = TRUE in datapkg)

Table 816 lists most run-time parameters

Table 816 Run-time parameters and default valuesName Default value DescriptionSEAICEwriteState T write sea ice state to fileSEAICEuseDYNAMICS T use dynamicsSEAICEuseJFNK F use the JFNK-solverSEAICEuseTEM F use truncated ellipse methodSEAICEuseStrImpCpl F use strength implicit coupling in LSRJFNKSEAICEuseMetricTerms T use metric terms in dynamicsSEAICEuseEVPpickup T use EVP pickupsSEAICEuseFluxForm F use flux form for 2nd central difference advection schemeSEAICErestoreUnderIce F enable restoring to climatology under iceuseHB87stressCoupling F turn on ice-ocean stress coupling followingusePW79thermodynamics T flag to turn off zero-layer-thermodynamics for testingSEAICEadvHeffAreaSnowSalt T flag to turn off advection of scalar state variablesSEAICEuseFlooding T use flood-freeze algorithmSEAICE_no_slip F switch between free-slip and no-slip boundary conditionsSEAICE_deltaTtherm dTracerLev(1) thermodynamic timestepSEAICE_deltaTdyn dTracerLev(1) dynamic timestepSEAICE_deltaTevp 0 EVP sub-cycling time step values gt 0 turn on EVPSEAICEuseEVPstar F use modified EVP instead of EVPSEAICEuseEVPrev F use yet another variation on EVPSEAICEnEVPstarSteps UNSET number of modified EVP iterationSEAICE_evpAlpha UNSET EVP parameterSEAICE_evpBeta UNSET EVP parameterSEAICEaEVPcoeff UNSET aEVP parameterSEAICEaEVPcStar 4 aEVP parameter [KDL16]SEAICEaEVPalphaMin 5 aEVP parameter [KDL16]SEAICE_elasticParm 1

3 EVP paramter 1198640

SEAICE_evpTauRelax ∆119905119864119881 119875 relaxation time scale 119879 for EVP wavesSEAICEnonLinIterMax 10 maximum number of JFNK-Newton iterations (non-linear)SEAICElinearIterMax 10 maximum number of JFNK-Krylov iterations (linear)SEAICE_JFNK_lsIter (off) start line search after ldquolsIterrdquo Newton iterationsSEAICEnonLinTol 10E-05 non-linear tolerance parameter for JFNK solverJFNKgamma_lin_minmax 010099 tolerance parameters for linear JFNK solverJFNKres_tFac UNSET tolerance parameter for FGMRES residualSEAICE_JFNKepsilon 10E-06 step size for the FD-Jacobian-times-vectorSEAICE_dumpFreq dumpFreq dump frequencySEAICE_taveFreq taveFreq time-averaging frequencySEAICE_dump_mdsio T write snap-shot using MDSIOSEAICE_tave_mdsio T write TimeAverage using MDSIOSEAICE_dump_mnc F write snap-shot using MNCSEAICE_tave_mnc F write TimeAverage using MNCSEAICE_initialHEFF 000000E+00 initial sea-ice thicknessSEAICE_drag 200000E-03 air-ice drag coefficientOCEAN_drag 100000E-03 air-ocean drag coefficientSEAICE_waterDrag 550000E+00 water-ice dragSEAICE_dryIceAlb 750000E-01 winter albedoSEAICE_wetIceAlb 660000E-01 summer albedoSEAICE_drySnowAlb 840000E-01 dry snow albedoSEAICE_wetSnowAlb 700000E-01 wet snow albedoSEAICE_waterAlbedo 100000E-01 water albedo

Table 816 ndash continued from previous pageSEAICE_strength 275000E+04 sea-ice strength 119875

SEAICE_cStar 200000E+00 sea-ice strength paramter 119862

SEAICE_rhoAir 13 (or value) density of air (kgmmath^3)SEAICE_cpAir 1004 (or value) specific heat of air (JkgK)SEAICE_lhEvap 2500000 (or val ue) latent heat of evaporationSEAICE_lhFusion 334000 (or value ) latent heat of fusionSEAICE_lhSublim 2834000 latent heat of sublimationSEAICE_dalton 175E-03 sensible heat transfer coefficientSEAICE_iceConduct 216560E+00 sea-ice conductivitySEAICE_snowConduct 310000E-01 snow conductivitySEAICE_emissivity 550000E-08 Stefan-BoltzmanSEAICE_snowThick 150000E-01 cutoff snow thicknessSEAICE_shortwave 300000E-01 penetration shortwave radiationSEAICE_freeze -196000E+00 freezing temp of sea waterSEAICE_saltFrac 00 salinity newly formed ice (fraction of ocean surface salinity)SEAICE_frazilFrac 00 Fraction of surface level negative heat content anomalies (relative to the local freezing poinSEAICEstressFactor 100000E+00 scaling factor for ice-ocean stressHeffAreaHsnowFileHsalt UNSET initial fields for variables HEFFAREAHSNOWHSALTLSR_ERROR 100000E-04 sets accuracy of LSR solverDIFF1 00 parameter used in advectFHO 500000E-01 demarcation ice thickness (AKA lead closing paramter ℎ0)MAX_HEFF 100000E+01 maximum ice thicknessMIN_ATEMP -500000E+01 minimum air temperatureMIN_LWDOWN 600000E+01 minimum downward longwaveMAX_TICE 300000E+01 maximum ice temperatureMIN_TICE -500000E+01 minimum ice temperatureIMAX_TICE 10 iterations for ice heat budgetSEAICE_EPS 100000E-10 reduce derivative singularitiesSEAICE_area_reg 100000E-5 minimum concentration to regularize ice thicknessSEAICE_hice_reg 005 m minimum ice thickness for regularizationSEAICE_multDim 1 number of ice categories for thermodynamicsSEAICE_useMultDimSnow F use SEAICE_multDim snow categories

Input fields and units

bull HeffFile Initial sea ice thickness averaged over grid cell in meters initializes variable HEFF

bull AreaFile Initial fractional sea ice cover range [0 1] initializes variable AREA

bull HsnowFile Initial snow thickness on sea ice averaged over grid cell in meters initializes variable HSNOW

bull HsaltFile Initial salinity of sea ice averaged over grid cell in gm2 initializes variable HSALT

8623 Description

[TO BE CONTINUEDMODIFIED]

The MITgcm sea ice model (MITgcmsim) is based on a variant of the viscous-plastic (VP) dynamic-thermodynamicsea ice model [ZH97] first introduced by [Hib79][Hib80] In order to adapt this model to the requirements of coupledice-ocean state estimation many important aspects of the original code have been modified and improved [LMC+10]

bull the code has been rewritten for an Arakawa C-grid both B- and C-grid variants are available the C-grid codeallows for no-slip and free-slip lateral boundary conditions

bull three different solution methods for solving the nonlinear momentum equations have been adopted LSOR[ZH97] EVP [HD97] JFNK [LTSedlacek+10][LFLV14]

bull ice-ocean stress can be formulated as in [HB87] or as in [CMF08]

bull ice variables are advected by sophisticated conservative advection schemes with flux limiting

bull growth and melt parameterizations have been refined and extended in order to allow for more stable automaticdifferentiation of the code

The sea ice model is tightly coupled to the ocean compontent of the MITgcm Heat fresh water fluxes and surfacestresses are computed from the atmospheric state and ndash by default ndash modified by the ice model at every time step

The ice dynamics models that are most widely used for large-scale climate studies are the viscous-plastic (VP) model[Hib79] the cavitating fluid (CF) model [FWDH92] and the elastic-viscous-plastic (EVP) model [HD97] Comparedto the VP model the CF model does not allow ice shear in calculating ice motion stress and deformation EVP modelsapproximate VP by adding an elastic term to the equations for easier adaptation to parallel computers Because of itshigher accuracy in plastic solution and relatively simpler formulation compared to the EVP model we decided to usethe VP model as the default dynamic component of our ice model To do this we extended the line successive overrelaxation (LSOR) method of [ZH97] for use in a parallel configuration An EVP model and a free-drift implemtationcan be selected with runtime flags

Compatibility with ice-thermodynamics thsice package

Note that by default the seaice-package includes the orginial so-called zero-layer thermodynamics following witha snow cover as in The zero-layer thermodynamic model assumes that ice does not store heat and therefore tendsto exaggerate the seasonal variability in ice thickness This exaggeration can be significantly reduced by using rsquos []three-layer thermodynamic model that permits heat storage in ice Recently the three-layer thermodynamic model hasbeen reformulated by The reformulation improves model physics by representing the brine content of the upper icewith a variable heat capacity It also improves model numerics and consumes less computer time and memory

The Winton sea-ice thermodynamics have been ported to the MIT GCM they currently reside under pkgseaiceThe package thsice is described in section [secpkgthsice] it is fully compatible with the packages seaice andexf When turned on together with seaice the zero-layer thermodynamics are replaced by the Winton thermody-namics In order to use the seaice-package with the thermodynamics of thsice compile both packages and turnboth package on in datapkg see an example in global_oceancs32x15inputicedyn Note that oncethsice is turned on the variables and diagnostics associated to the default thermodynamics are meaningless andthe diagnostics of thsice have to be used instead

Surface forcing

The sea ice model requires the following input fields 10-m winds 2-m air temperature and specific humidity down-ward longwave and shortwave radiations precipitation evaporation and river and glacier runoff The sea ice modelalso requires surface temperature from the ocean model and the top level horizontal velocity Output fields are surfacewind stress evaporation minus precipitation minus runoff net surface heat flux and net shortwave flux The sea-icemodel is global in ice-free regions bulk formulae are used to estimate oceanic forcing from the atmospheric fields

Dynamics

The momentum equation of the sea-ice model is

119898119863u

119863119905= minus119898119891ktimes u + 120591119886119894119903 + 120591119900119888119890119886119899 minus119898nabla120593(0) + F (82)

where 119898 = 119898119894 + 119898119904 is the ice and snow mass per unit area u = 119906i + 119907j is the ice velocity vector i j and k areunit vectors in the 119909 119910 and 119911 directions respectively 119891 is the Coriolis parameter 120591119886119894119903 and 120591119900119888119890119886119899 are the wind-iceand ocean-ice stresses respectively 119892 is the gravity accelation nabla120593(0) is the gradient (or tilt) of the sea surface height120593(0) = 119892120578 + 1199011198861205880 + 1198981198921205880 is the sea surface height potential in response to ocean dynamics (119892120578) to atmosphericpressure loading (1199011198861205880 where 1205880 is a reference density) and a term due to snow and ice loading and F = nablamiddot120590 is thedivergence of the internal ice stress tensor 120590119894119895 Advection of sea-ice momentum is neglected The wind and ice-oceanstress terms are given by

120591119886119894119903 =120588119886119894119903119862119886119894119903|U119886119894119903 minus u|119877119886119894119903(U119886119894119903 minus u)

120591119900119888119890119886119899 =120588119900119888119890119886119899119862119900119888119890119886119899|U119900119888119890119886119899 minus u|119877119900119888119890119886119899(U119900119888119890119886119899 minus u)

where U119886119894119903119900119888119890119886119899 are the surface winds of the atmosphere and surface currents of the ocean respectively 119862119886119894119903119900119888119890119886119899

are air and ocean drag coefficients 120588119886119894119903119900119888119890119886119899 are reference densities and 119877119886119894119903119900119888119890119886119899 are rotation matrices that act onthe windcurrent vectors

Viscous-Plastic (VP) Rheology

For an isotropic system the stress tensor 120590119894119895 (119894 119895 = 1 2) can be related to the ice strain rate and strength by a nonlinearviscous-plastic (VP) constitutive law

120590119894119895 = 2120578(119894119895 119875 )119894119895 + [120577(119894119895 119875 ) minus 120578(119894119895 119875 )] 119896119896120575119894119895 minus119875

2120575119894119895 (83)

The ice strain rate is given by

119894119895 =1

(120597119906119894120597119909119895

+120597119906119895120597119909119894

The maximum ice pressure 119875max a measure of ice strength depends on both thickness ℎ and compactness (concen-tration) 119888

119875max = 119875 119888 ℎ expminus119862 middot (1 minus 119888) (84)

with the constants 119875 (run-time parameter SEAICE_strength) and 119862 = 20 The nonlinear bulk and shearviscosities 120578 and 120577 are functions of ice strain rate invariants and ice strength such that the principal components of thestress lie on an elliptical yield curve with the ratio of major to minor axis 119890 equal to 2 they are given by

120577 = min

(119875max

2 max(∆∆min) 120577max

)120578 =

120577

1198902

with the abbreviation

∆ =[(211 + 222

)(1 + 119890minus2) + 4119890minus2212 + 21122(1 minus 119890minus2)

The bulk viscosities are bounded above by imposing both a minimum ∆min (for numerical reasons run-time parameterSEAICE_EPS with a default value of 10minus10 sminus1) and a maximum 120577max = 119875max∆

where ∆ = (5 times 10122 times104) sminus1 (There is also the option of bounding 120577 from below by setting run-time parameter SEAICE_zetaMingt 0but this is generally not recommended) For stress tensor computation the replacement pressure 119875 = 2 ∆120577 is used sothat the stress state always lies on the elliptic yield curve by definition

Defining the CPP-flag SEAICE_ZETA_SMOOTHREG in SEAICE_OPTIONSh before compiling replaces themethod for bounding 120577 by a smooth (differentiable) expression

120577 = 120577max tanh

(119875

2 min(∆∆min) 120577max

119875

2∆ tanh

min(∆∆min)

) (85)

where ∆min = 10minus20 sminus1 is chosen to avoid divisions by zero

LSR and JFNK solver

In the matrix notation the discretized momentum equations can be written as

A(x)x = b(x) (86)

The solution vector x consists of the two velocity components 119906 and 119907 that contain the velocity variables at all gridpoints and at one time level The standard (and default) method for solving Eq (86) in the sea ice component of theMITgcm as in many sea ice models is an iterative Picard solver in the 119896-th iteration a linearized form A(x119896minus1)x119896 =b(x119896minus1) is solved (in the case of the MITgcm it is a Line Successive (over) Relaxation (LSR) algorithm ) Picardsolvers converge slowly but generally the iteration is terminated after only a few non-linear steps and the calculationcontinues with the next time level This method is the default method in the MITgcm The number of non-lineariteration steps or pseudo-time steps can be controlled by the runtime parameter SEAICEnonLinIterMax (defaultis 2)

In order to overcome the poor convergence of the Picard-solver introduced a Jacobian-free Newton-Krylov solver forthe sea ice momentum equations This solver is also implemented in the MITgcm The Newton method transformsminimizing the residual F(x) = A(x)xminusb(x) to finding the roots of a multivariate Taylor expansion of the residualF around the previous (119896 minus 1) estimate x119896minus1

F(x119896minus1 + 120575x119896) = F(x119896minus1) + Fprime(x119896minus1) 120575x119896 (87)

with the Jacobian J equiv Fprime The root F(x119896minus1 + 120575x119896) = 0 is found by solving

J(x119896minus1) 120575x119896 = minusF(x119896minus1) (88)

for 120575x119896 The next (119896-th) estimate is given by x119896 = x119896minus1+119886 120575x119896 In order to avoid overshoots the factor 119886 is iterativelyreduced in a line search (119886 = 1 12

18 ) until F(x119896) lt F(x119896minus1) where middot =

intmiddot 1198891199092 is the 1198712-norm In

practice the line search is stopped at 119886 = 18 The line search starts after SEAICE_JFNK_lsIter non-linear Newton

iterations (off by default)

Forming the Jacobian J explicitly is often avoided as ldquotoo error prone and time consumingrdquo Instead Krylov methodsonly require the action of J on an arbitrary vector w and hence allow a matrix free algorithm for solving Eq (88)The action of J can be approximated by a first-order Taylor series expansion

J(x119896minus1)w asymp F(x119896minus1 + 120598w) minus F(x119896minus1)

120598(89)

or computed exactly with the help of automatic differentiation (AD) tools SEAICE_JFNKepsilon sets the stepsize 120598

We use the Flexible Generalized Minimum RESidual method with right-hand side preconditioning to solve Eq (88)iteratively starting from a first guess of 120575x119896

0 = 0 For the preconditioning matrix P we choose a simplified form ofthe system matrix A(x119896minus1) where x119896minus1 is the estimate of the previous Newton step 119896 minus 1 The transformed equation(88) becomes

J(x119896minus1)Pminus1120575z = minusF(x119896minus1) with 120575z = P120575x119896 (810)

The Krylov method iteratively improves the approximate solution to Eq (810) in subspace (r0 JPminus1r0 (JPminus1)2r0 (JPminus1)119898r0) with increasing 119898 r0 = minusF(x119896minus1) minus J(x119896minus1) 120575x119896

0 is the initial residual of Eq (88) r0 =minusF(x119896minus1) with the first guess 120575x119896

0 = 0 We allow a Krylov-subspace of dimension 119898 = 50 and we do not userestarts The preconditioning operation involves applying Pminus1 to the basis vectors v0v1v2 v119898 of the Krylovsubspace This operation is approximated by solving the linear system Pw = v119894 Because P asymp A(x119896minus1) we canuse the LSR-algorithm already implemented in the Picard solver Each preconditioning operation uses a fixed numberof 10 LSR-iterations avoiding any termination criterion More details and results can be found in

To use the JFNK-solver set SEAICEuseJNFK = TRUE in the namelist file dataseaiceSEAICE_ALLOW_JFNK needs to be defined in SEAICE_OPTIONSh and we recommend using a smoothregularization of 120577 by defining SEAICE_ZETA_SMOOTHREG (see above) for better convergence The non-linear Newton iteration is terminated when the 1198712-norm of the residual is reduced by 120574nl (runtime parameterSEAICEnonLinTol = 1E-4 will already lead to expensive simulations) with respect to the initial normF(x119896) lt 120574nlF(x0) Within a non-linear iteration the linear FGMRES solver is terminated when the residual issmaller than 120574119896F(x119896minus1) where 120574119896 is determined by

120574119896 =

1205740 for F(x119896minus1) ge 119903

max(120574min

F(x119896minus1)F(x119896minus2)

)for F(x119896minus1) lt 119903

so that the linear tolerance parameter 120574119896 decreases with the non-linear Newton step as the non-linear solution is ap-proached This inexact Newton method is generally more robust and computationally more efficient than exact meth-ods Typical parameter choices are 1205740 = JFNKgamma_lin_max = 099 120574min = JFNKgamma_lin_min = 01 and119903 = JFNKres_tFac timesF(x0) with JFNKres_tFac = 05 We recommend a maximum number of non-linear it-erations SEAICEnewtonIterMax = 100 and a maximum number of Krylov iterations SEAICEkrylovIterMax= 50 because the Krylov subspace has a fixed dimension of 50

Setting SEAICEuseStrImpCpl = TRUE turns on ldquostrength implicit couplingrdquo [HJL04] in the LSR-solverand in the LSR-preconditioner for the JFNK-solver In this mode the different contributions of the stress divergenceterms are re-ordered in order to increase the diagonal dominance of the system matrix Unfortunately the convergencerate of the LSR solver is increased only slightly while the JFNK-convergence appears to be unaffected

Elastic-Viscous-Plastic (EVP) Dynamics

[HD97] introduced an elastic contribution to the strain rate in order to regularize (83) in such a way that the resultingelastic-viscous-plastic (EVP) and VP models are identical at steady state

119864

120597120590119894119895120597119905

2120578120590119894119895 +

120578 minus 120577

4120577120578120590119896119896120575119894119895 +

119875

4120577120575119894119895 = 119894119895 (812)

The EVP-model uses an explicit time stepping scheme with a short timestep According to the recommen-dation of [HD97] the EVP-model should be stepped forward in time 120 times (SEAICE_deltaTevp =SEAICIE_deltaTdyn120) within the physical ocean model time step (although this parameter is under debate)to allow for elastic waves to disappear Because the scheme does not require a matrix inversion it is fast in spite ofthe small internal timestep and simple to implement on parallel computers For completeness we repeat the equa-tions for the components of the stress tensor 1205901 = 12059011 + 12059022 1205902 = 12059011 minus 12059022 and 12059012 Introducing the divergence119863119863 = 11 + 22 and the horizontal tension and shearing strain rates 119863119879 = 11 minus 22 and 119863119878 = 212 respectivelyand using the above abbreviations the equations (812) can be written as

1205971205901120597119905

+12059012119879

+119875

2119879=

119875

2119879∆119863119863 (813)

1205971205902120597119905

+1205902119890

2119879=

119875

2119879∆119863119879 (814)

12059712059012120597119905

+12059012119890

2119879=

119875

4119879∆119863119878 (815)

Here the elastic parameter 119864 is redefined in terms of a damping timescale 119879 for elastic waves

119864 =120577

119879

119879 = 1198640∆119905 with the tunable parameter 1198640 lt 1 and the external (long) timestep ∆119905 1198640 = 13 is the default value in the

code and close to what and recommend

To use the EVP solver make sure that both SEAICE_CGRID and SEAICE_ALLOW_EVP are defined inSEAICE_OPTIONSh (default) The solver is turned on by setting the sub-cycling time step SEAICE_deltaTevpto a value larger than zero The choice of this time step is under debate [HD97] recommend order(120) time stepsfor the EVP solver within one model time step ∆119905 (deltaTmom) One can also choose order(120) time steps withinthe forcing time scale but then we recommend adjusting the damping time scale 119879 accordingly by setting eitherSEAICE_elasticPlarm (1198640) so that 1198640∆119905 = forcing time scale or directly SEAICE_evpTauRelax (119879 ) tothe forcing time scale (NOTE with the improved EVP variants of the next section the above recommendations areobsolete Use mEVP or aEVP instead)

More stable variants of Elastic-Viscous-Plastic Dynamics EVP mEVP and aEVP

The genuine EVP schemes appears to give noisy solu tions [Hun01][LKT+12][BFLM13] This has lead to a modifiedEVP or EVP [LKT+12][BFLM13][KDL15] here we refer to these variants by modified EVP (mEVP) and adaptiveEVP (aEVP) [KDL16] The main idea is to modify the ldquonaturalrdquo time-discretization of the momentum equations

119898119863u

119863119905asymp 119898

u119901+1 minus u119899

∆119905+ 120573u

119901+1 minus u119901

∆119905EVP

where 119899 is the previous time step index and 119901 is the previous sub-cycling index The extra ldquointertialrdquo term 119898 (u119901+1 minusu119899)∆119905) allows the definition of a residual |u119901+1 minus u119901| that as u119901+1 rarr u119899+1 converges to 0 In this way EVPcan be re-interpreted as a pure iterative solver where the sub-cycling has no association with time-relation (through∆119905EVP) Using the terminology of the evolution equations of stress 120590119894119895 and momentum u can be written as

120590119901+1119894119895 = 120590119901

119894119895 +1

120572

(120590119894119895(u

119901) minus 120590119901119894119895

) (817)

u119901+1 = u119901 +1

120573

(∆119905

119898nabla middot 120590119901+1 +

∆119905

119898R119901 + u119899 minus u119901

) (818)

R contains all terms in the momentum equations except for the rheology terms and the time derivative 120572 and120573 are free parameters (SEAICE_evpAlpha SEAICE_evpBeta) that replace the time stepping parametersSEAICE_deltaTevp (∆119879EVP) SEAICE_elasticParm (1198640) or SEAICE_evpTauRelax (119879 ) 120572 and 120573 deter-mine the speed of convergence and the stability Usually it makes sense to use 120572 = 120573 and SEAICEnEVPstarSteps≫ (120572 120573) [KDL15] Currently there is no termination criterion and the number of mEVP iterations is fixed toSEAICEnEVPstarSteps

In order to use mEVP in the MITgcm set SEAICEuseEVPstar = TRUE in dataseaice IfSEAICEuseEVPrev =TRUE the actual form of equations ([eqevpstarsigma]) and ([eqevpstarmom]) isused with fewer implicit terms and the factor of 1198902 dropped in the stress equations ([eqevpstresstensor2]) and([eqevpstresstensor12]) Although this modifies the original EVP-equations it turns out to improve convergence[BFLM13]

Another variant is the aEVP scheme [KDL16] where the value of 120572 is set dynamically based on the stability criterion

120572 = 120573 = max

(119888120587

radic119888120577

119860119888

∆119905

max(119898 10minus4 kg) 120572min

)(819)

with the grid cell area 119860119888 and the ice and snow mass 119898 This choice sacrifices speed of convergence for sta-bility with the result that aEVP converges quickly to VP where 120572 can be small and more slowly in areas wherethe equations are stiff In practice aEVP leads to an overall better convergence than mEVP [KDL16] To useaEVP in the MITgcm set SEAICEaEVPcoeff = 119888 this also sets the default values of SEAICEaEVPcStar(119888 = 4) and SEAICEaEVPalphaMin (120572min = 5) Good convergence has been obtained with setting these val-ues [KDL16] SEAICEaEVPcoeff = 05 SEAICEnEVPstarSteps = 500 SEAICEuseEVPstar =TRUE SEAICEuseEVPrev = TRUE

Note that probably because of the C-grid staggering of velocities and stresses mEVP may not converge as successfullyas in [KDL15] and that convergence at very high resolution (order 5km) has not been studied yet

Truncated ellipse method (TEM) for yield curve

In the so-called truncated ellipse method the shear viscosity 120578 is capped to suppress any tensile stress

120578 = min

(120577

1198902

1198752 minus 120577(11 + 22)radic

max(∆2min (11 minus 22)2 + 4212)

) (820)

To enable this method set define SEAICE_ALLOW_TEM in SEAICE_OPTIONSh and turn it on withSEAICEuseTEM in dataseaice

Ice-Ocean stress

Moving sea ice exerts a stress on the ocean which is the opposite of the stress 120591119900119888119890119886119899 in Eq (82) This stess is applieddirectly to the surface layer of the ocean model An alternative ocean stress formulation is given by [HB87] Rather

than applying 120591119900119888119890119886119899 directly the stress is derived from integrating over the ice thickness to the bottom of the oceanicsurface layer In the resulting equation for the combined ocean-ice momentum the interfacial stress cancels and thetotal stress appears as the sum of windstress and divergence of internal ice stresses 120575(119911)(120591119886119894119903 + F)1205880 see alse Eq 2of [HB87] The disadvantage of this formulation is that now the velocity in the surface layer of the ocean that is usedto advect tracers is really an average over the ocean surface velocity and the ice velocity leading to an inconsistency asthe ice temperature and salinity are different from the oceanic variables To turn on the stress formulation of [HB87]set useHB87StressCoupling=TRUE in dataseaice

Finite-volume discretization of the stress tensor divergence

On an Arakawa C grid ice thickness and concentration and thus ice strength 119875 and bulk and shear viscosities 120577 and120578 are naturally defined a C-points in the center of the grid cell Discretization requires only averaging of 120577 and 120578 tovorticity or Z-points (or 120577-points but here we use Z in order avoid confusion with the bulk viscosity) at the bottom leftcorner of the cell to give 120577

119885and 120578119885 In the following the superscripts indicate location at Z or C points distance across

the cell (F) along the cell edge (G) between 119906-points (U) 119907-points (V) and C-points (C) The control volumes of the119906- and 119907-equations in the grid cell at indices (119894 119895) are 119860119908

119894119895 and 119860119904119894119895 respectively With these definitions (which follow

the model code documentation except that 120577-points have been renamed to Z-points) the strain rates are discretized as

11 = 12059711199061 + 11989621199062

=gt (12059811)119862119894119895 =119906119894+1119895 minus 119906119894119895

∆119909119865119894119895+ 1198961198622119894119895

119907119894119895+1 + 1199071198941198952

22 = 12059721199062 + 11989611199061

=gt (12059822)119862119894119895 =119907119894119895+1 minus 119907119894119895

∆119910119865119894119895+ 1198961198621119894119895

119906119894+1119895 + 1199061198941198952

12 = 21 =1

(12059711199062 + 12059721199061 minus 11989611199062 minus 11989621199061

)=gt (12059812)119885119894119895 =

(119907119894119895 minus 119907119894minus1119895

∆119909119881119894119895+119906119894119895 minus 119906119894119895minus1

∆119910119880119894119895

minus 1198961198851119894119895119907119894119895 + 119907119894minus1119895

2minus 1198961198852119894119895

119906119894119895 + 119906119894119895minus1

so that the diagonal terms of the strain rate tensor are naturally defined at C-points and the symmetric off-diagonal termat Z-points No-slip boundary conditions (119906119894119895minus1 +119906119894119895 = 0 and 119907119894minus1119895 +119907119894119895 = 0 across boundaries) are implementedvia ldquoghost-pointsrdquo for free slip boundary conditions (12059812)119885 = 0 on boundaries

For a spherical polar grid the coefficients of the metric terms are 1198961 = 0 and 1198962 = minus tan120593119886 with the sphericalradius 119886 and the latitude 120593 ∆1199091 = ∆119909 = 119886 cos120593∆120582 and ∆1199092 = ∆119910 = 119886∆120593 For a general orthogonal curvilineargrid 1198961 and 1198962 can be approximated by finite differences of the cell widths

1198961198621119894119895 =1

∆119910119865119894119895

∆119910119866119894+1119895 minus ∆119910119866119894119895∆119909119865119894119895

1198961198622119894119895 =1

∆119909119865119894119895

∆119909119866119894119895+1 minus ∆119909119866119894119895∆119910119865119894119895

1198961198851119894119895 =1

∆119910119880119894119895

∆119910119862119894119895 minus ∆119910119862119894minus1119895

∆119909119881119894119895

1198961198852119894119895 =1

∆119909119881119894119895

∆119909119862119894119895 minus ∆119909119862119894119895minus1

∆119910119880119894119895

The stress tensor is given by the constitutive viscous-plastic relation 120590120572120573 = 2120578120572120573 + [(120577 minus 120578)120574120574 minus 1198752]120575120572120573 Thestress tensor divergence (nabla120590)120572 = 120597120573120590120573120572 is discretized in finite volumes This conveniently avoids dealing with

further metric terms as these are ldquohiddenrdquo in the differential cell widths For the 119906-equation (120572 = 1) we have

(nabla120590)1 1

119860119908119894119895

intcell

(120597112059011 + 120597212059021) 1198891199091 1198891199092

119860119908119894119895

int 1199092+Δ1199092

1199092

120590111198891199092

1199091+Δ1199091

1199091

int 1199091+Δ1199091

1199091

120590211198891199091

1199092+Δ1199092

1199092

asymp 1

119860119908119894119895

∆119909212059011

1199091+Δ1199091

1199091

+∆119909112059021

1199092+Δ1199092

1199092

119860119908119894119895

(∆119909212059011)119862119894119895 minus (∆119909212059011)119862119894minus1119895

+ (∆119909112059021)119885119894119895+1 minus (∆119909112059021)119885119894119895

(∆119909212059011)119862119894119895 = ∆119910119865119894119895(120577 + 120578)119862119894119895119906119894+1119895 minus 119906119894119895

∆119909119865119894119895

+ ∆119910119865119894119895(120577 + 120578)1198621198941198951198961198622119894119895

119907119894119895+1 + 1199071198941198952

+ ∆119910119865119894119895(120577 minus 120578)119862119894119895119907119894119895+1 minus 119907119894119895

∆119910119865119894119895

+ ∆119910119865119894119895(120577 minus 120578)1198621198941198951198961198621119894119895

119906119894+1119895 + 1199061198941198952

minus ∆119910119865119894119895119875

(∆119909112059021)119885119894119895 = ∆119909119881119894119895120578119885119894119895

119906119894119895 minus 119906119894119895minus1

∆119910119880119894119895

+ ∆119909119881119894119895120578119885119894119895

119907119894119895 minus 119907119894minus1119895

∆119909119881119894119895

minus ∆119909119881119894119895120578119885119894119895119896

1198852119894119895

119906119894119895 + 119906119894119895minus1

minus ∆119909119881119894119895120578119885119894119895119896

1198851119894119895

119907119894119895 + 119907119894minus1119895

Similarly we have for the 119907-equation (120572 = 2)

(nabla120590)2 1

119860119904119894119895

intcell

(120597112059012 + 120597212059022) 1198891199091 1198891199092

119860119904119894119895

int 1199092+Δ1199092

1199092

120590121198891199092

1199091+Δ1199091

1199091

int 1199091+Δ1199091

1199091

120590221198891199091

1199092+Δ1199092

1199092

asymp 1

119860119904119894119895

∆119909212059012

1199091+Δ1199091

1199091

+∆119909112059022

1199092+Δ1199092

1199092

119860119904119894119895

(∆119909212059012)119885119894+1119895 minus (∆119909212059012)119885119894119895

+ (∆119909112059022)119862119894119895 minus (∆119909112059022)119862119894119895minus1

(∆119909112059012)119885119894119895 = ∆119910119880119894119895120578119885119894119895

119906119894119895 minus 119906119894119895minus1

∆119910119880119894119895

+ ∆119910119880119894119895120578119885119894119895

119907119894119895 minus 119907119894minus1119895

∆119909119881119894119895

minus ∆119910119880119894119895120578119885119894119895119896

1198852119894119895

119906119894119895 + 119906119894119895minus1

minus ∆119910119880119894119895120578119885119894119895119896

1198851119894119895

119907119894119895 + 119907119894minus1119895

(∆119909212059022)119862119894119895 = ∆119909119865119894119895(120577 minus 120578)119862119894119895119906119894+1119895 minus 119906119894119895

∆119909119865119894119895

+ ∆119909119865119894119895(120577 minus 120578)1198621198941198951198961198622119894119895

119907119894119895+1 + 1199071198941198952

+ ∆119909119865119894119895(120577 + 120578)119862119894119895119907119894119895+1 minus 119907119894119895

∆119910119865119894119895

+ ∆119909119865119894119895(120577 + 120578)1198621198941198951198961198621119894119895

119906119894+1119895 + 1199061198941198952

minus ∆119909119865119894119895119875

Again no slip boundary conditions are realized via ghost points and 119906119894119895minus1 + 119906119894119895 = 0 and 119907119894minus1119895 + 119907119894119895 = 0 acrossboundaries For free slip boundary conditions the lateral stress is set to zeros In analogy to (12059812)119885 = 0 on boundarieswe set 120590119885

21 = 0 or equivalently 120578119885119894119895 = 0 on boundaries

Thermodynamics

NOTE THIS SECTION IS TERRIBLY OUT OF DATE

In its original formulation the sea ice model uses simple thermodynamics following the appendix of [Sem76] Thisformulation does not allow storage of heat that is the heat capacity of ice is zero Upward conductive heat flux isparameterized assuming a linear temperature profile and together with a constant ice conductivity It is expressed as(119870ℎ)(119879119908 minus 1198790) where 119870 is the ice conductivity ℎ the ice thickness and 119879119908 minus 1198790 the difference between waterand ice surface temperatures This type of model is often refered to as a ldquozero-layerrdquo model The surface heat flux iscomputed in a similar way to that of and

The conductive heat flux depends strongly on the ice thickness ℎ However the ice thickness in the model representsa mean over a potentially very heterogeneous thickness distribution In order to parameterize a sub-grid scale distri-bution for heat flux computations the mean ice thickness ℎ is split into 119873 thickness categories 119867119899 that are equallydistributed between 2ℎ and a minimum imposed ice thickness of 5 cm by 119867119899 = 2119899minus1

7 ℎ for 119899 isin [1 119873 ] The heatfluxes computed for each thickness category is area-averaged to give the total heat flux [Hib84] To use this thick-ness category parameterization set SEAICE_multDim to the number of desired categories in dataseaice (7 isa good guess for anything larger than 7 modify SEAICE_SIZEh) note that this requires different restart files andswitching this flag on in the middle of an integration is not advised In order to include the same distribution for snowset SEAICE_useMultDimSnow = TRUE only then the parameterization of always having a fraction of thinice is efficient and generally thicker ice is produce [CMKL+14]

The atmospheric heat flux is balanced by an oceanic heat flux from below The oceanic flux is proportional to120588 119888119901 (119879119908 minus 119879119891119903) where 120588 and 119888119901 are the density and heat capacity of sea water and 119879119891119903 is the local freezing pointtemperature that is a function of salinity This flux is not assumed to instantaneously melt or create ice but a timescale of three days (run-time parameter SEAICE_gamma_t) is used to relax 119879119908 to the freezing point The parame-terization of lateral and vertical growth of sea ice follows that of [Hib79][Hib80] the so-called lead closing parameterℎ0 (run-time parameter HO) has a default value of 05 meters

On top of the ice there is a layer of snow that modifies the heat flux and the albedo [ZWDHSR98] Snow modifies theeffective conductivity according to

119870

ℎrarr 1

ℎ119904

119870119904+ ℎ

119870

where 119870119904 is the conductivity of snow and ℎ119904 the snow thickness If enough snow accumulates so that its weightsubmerges the ice and the snow is flooded a simple mass conserving parameterization of snowice formation (aflood-freeze algorithm following Archimedesrsquo principle) turns snow into ice until the ice surface is back at 119911 = 0[Lepparanta83] The flood-freeze algorithm is enabled with the CPP-flag SEAICE_ALLOW_FLOODDING and turnedon with run-time parameter SEAICEuseFlooding=TRUE

Advection of thermodynamic variables

Effective ice thickness (ice volume per unit area 119888middotℎ) concentration 119888 and effective snow thickness (119888middotℎ119904) are advectedby ice velocities

120597119883

120597119905= minusnabla middot (u119883) + Γ119883 +119863119883 (821)

where Γ119883 are the thermodynamic source terms and 119863119883 the diffusive terms for quantities 119883 = (119888 middot ℎ) 119888 (119888 middot ℎ119904)From the various advection scheme that are available in the MITgcm we recommend flux-limited schemes to preservesharp gradients and edges that are typical of sea ice distributions and to rule out unphysical over- and undershoots(negative thickness or concentration) These schemes conserve volume and horizontal area and are unconditionallystable so that we can set119863119883 = 0 Run-timeflags SEAICEadvScheme ``(default=2 is the historic2nd-order centered difference scheme) ``DIFF = 119863119883∆119909 (default=0004)

The MITgcm sea ice model provides the option to use the thermodynamics model of [Win00] which in turn is basedon the 3-layer model of [Sem76] and which treats brine content by means of enthalpy conservation the correspondingpackage thsice is described in section [secpkgthsice] This scheme requires additional state variables namelythe enthalpy of the two ice layers (instead of effective ice salinity) to be advected by ice velocities The inter-nal sea ice temperature is inferred from ice enthalpy To avoid unphysical (negative) values for ice thickness andconcentration a positive 2nd-order advection scheme with a SuperBee flux limiter [Roe85] should be used to ad-vect all sea-ice-related quantities of the [Win00] thermodynamic model (runtime flag thSIceAdvScheme=77 andthSIce_diffK =119863119883=0 in dataice defaults are 0) Because of the non-linearity of the advection scheme caremust be taken in advecting these quantities when simply using ice velocity to advect enthalpy the total energy (iethe volume integral of enthalpy) is not conserved Alternatively one can advect the energy content (ie product ofice-volume and enthalpy) but then false enthalpy extrema can occur which then leads to unrealistic ice temperature Inthe currently implemented solution the sea-ice mass flux is used to advect the enthalpy in order to ensure conservationof enthalpy and to prevent false enthalpy extrema

Key subroutines

Top-level routine seaice_modelF

SEAICE diagnostics

Diagnostics output is available via the diagnostics package (see Section [secpkgdiagnostics]) Available output fieldsare summarized in Table [tabpkgseaicediagnostics]

Experiments and tutorials that use seaice

bull seaice_obcs based on lab_sea

bull offline_exf_seaiceinputseaicetd based on lab_sea

bull global_oceancs32x15inputicedyn and global_oceancs32x15inputseaice globalcubed-sphere-experiment with combinations of seaice and thsice

CHAPTER 9

Packages II - Diagnostics and IO

280 Chapter 9 Packages II - Diagnostics and IO

CHAPTER 10

Ocean State Estimation Packages

This chapter describes packages that have been introduced for ocean state estimation purposes and in relation withautomatic differentiation (see Automatic Differentiation)

101 ECCO model-data comparisons using gridded data sets

Author Gael Forget

The functionalities implemented in pkgecco are (1) output time-averaged model fields to compare with griddeddata sets (2) compute normalized model-data distances (ie cost functions) (3) compute averages and transports (ieintegrals) The former is achieved as the model runs forwards in time whereas the others occur after time-integrationhas completed Following [FCH+15] the total cost function is formulated generically as

119973 () =sum119894

120572119894

(119889119879119894 119877

minus1119894 119889119894

)+sum119895

120573119895 119879 (101)

119889119894 = 119979(119894 minus 119894) (102)

119894 = 119982119967ℳ() (103)

= 119980() (104)

= ℛ(prime) (105)

using symbols defined in Table 101 Per Equation (103) model counterparts (119894) to observational data (119894) derivefrom adjustable model parameters () through model dynamics integration (ℳ) diagnostic calculations (119967) andaveraging in space and time (119982) Alternatively 119982 stands for subsampling in space and time in the context of Section102 (PROFILES model-data comparisons at observed locations) Plain model-data misfits (119894minus119894) can be penalizeddirectly in Eq (101) but penalized misfits (119889119894) more generally derive from 119894 minus 119894 through the generic 119979 post-processor (Eq (102)) Eqs (104)-(105) pertain to model control parameter adjustment capabilities described inSection 103 (CTRL Model Parameter Adjustment Capability)

Table 101 Symbol used in formulating generic cost functionssymbol definition vector of nondimensional control variables vector of dimensional control variables120572119894 120573119895 misfit and control cost function multipliers (1 by default)119877119894 data error covariance matrix (119877minus1

119894 are weights)119889119894 a set of model-data differences119894 observational data vector119894 model counterpart to 119894119979 post-processing operator (eg a smoother)ℳ forward model dynamics operator119967 diagnostic computation operator119982 averagingsubsampling operator119980 Pre-processing operatorℛ Pre-conditioning operator

1011 Generic Cost Function

The parameters available for configuring generic cost function terms in dataecco are given in Table 102 andexamples of possible specifications are available in

bull MITgcm_contribverification_otherglobal_oce_cs32inputdataecco

bull MITgcm_contribverification_otherglobal_oce_cs32input_adsensdataecco

bull MITgcm_contribgaelverificationglobal_oce_llc90inputecco_v4dataecco

The gridded observation file name is specified by gencost_datafile Observational time series may be providedas on big file or split into yearly files finishing in lsquo_1992rsquo lsquo_1993rsquo etc The corresponding 119894 physical variable is spec-ified via the gencost_barfile root (see Table 103) A file named as specified by gencost_barfile gets cre-ated where averaged fields are written progressively as the model steps forward in time After the final time step this fileis re-read by cost_genericF to compute the corresponding cost function term If gencost_outputlevel= 1 and gencost_name=lsquofoorsquo then cost_genericF outputs model-data misfit fields (ie 119889119894) to a file namedlsquomisfit_foodatarsquo for offline analysis and visualization

In the current implementation model-data error covariance matrices 119877119894 omit non-diagonal terms Specifying 119877119894 thusboils down to providing uncertainty fields (120590119894 such that 119877119894 = 1205902

119894 ) in a file specified via gencost_errfile Bydefault 120590119894 is assumed to be time-invariant but a 120590119894 time series of the same length as the 119894 time series can be providedusing the variaweight option (Table 104) By default cost functions are quadratic but 119889119879119894 119877

minus1119894 119889119894 can be replaced

with 119877minus12119894 119889119894 using the nosumsq option (Table 104)

In principle any averaging frequency should be possible but only lsquodayrsquo lsquomonthrsquo lsquosteprsquo and lsquoconstrsquo are implementedfor gencost_avgperiod If two different averaging frequencies are needed for a variable used in multiple costfunction terms (eg daily and monthly) then an extension starting with lsquo_rsquo should be added to gencost_barfile(such as lsquo_dayrsquo and lsquo_monrsquo)1 If two cost function terms use the same variable and frequency however then using a

1 ecco_check may be missing a test for conflicting names

282 Chapter 10 Ocean State Estimation Packages

common gencost_barfile saves disk space

Climatologies of 119894 can be formed from the time series of model averages in order to compare with climatologies of119894 by activating the lsquoclimrsquo option via gencost_preproc and setting the corresponding gencost_preproc_iinteger parameter to the number of records (ie a of months days or time steps) per climatological cycle Thegeneric post-processor (119979 in Eq (102)) also allows model-data misfits to be for example smoothed in space bysetting gencost_posproc to lsquosmoothrsquo and specifying the smoother parameters via gencost_posproc_c andgencost_posproc_i (see Table 104) Other options associated with the computation of Eq (101) are summa-rized in Table 104 and further discussed below Multiple gencost_preproc gencost_posproc options maybe specified per cost term

In general the specification of gencost_name is optional has no impact on the end-result and only servesto distinguish between cost function terms amongst the model output (STDOUT0000 STDERR0000 costfunc-tion000 misfitdata) Exceptions listed in Table 106 however activate alternative cost function codes (in place ofcost_genericF) described in Section 1013 In this section and in Table 103 (unlike in other parts of the man-ual) lsquozonalrsquo lsquomeridionalrsquo are to be taken literally and these components are centered (ie not at the staggered modelvelocity points) Preparing gridded velocity data sets for use in cost functions thus boils down to interpolating them toXC YC

Table 102 Run-time parameters used in formulating generic costfunctions and defined via ecco_gencost_nmllsquo namelist in dataeccoAll parameters are vectors of length NGENCOST (the of avail-able cost terms) except for gencost_proc are arrays of sizeNGENPPROCtimesNGENCOST (10 times 20 by default can be changed ineccoh at compile time) In addition the gencost_is3d internalparameter is reset to true on the fly in all 3D cases in Table 103

parameter type functiongencost_name character() Name of cost termgencost_barfile character() File to receive model counterpart 119894 (See Table 103)gencost_datafile character() File containing observational data 119894gencost_avgperiod character(5) Averaging period for 119894 and 119894 (see text)gencost_outputlevel integer Greater than 0 will output misfit fieldsgencost_errfile character() Uncertainty field name (not used in Section 1012)gencost_mask character() Mask file name root (used only in Section 1012)mult_gencost real Multiplier 120572119894 (default 1)gencost_preproc character() Preprocessor namesgencost_preproc_c character() Preprocessor character argumentsgencost_preproc_i integer() Preprocessor integer argumentsgencost_preproc_r real() Preprocessor real argumentsgencost_posproc character() Post-processor namesgencost_posproc_c character() Post-processor character argumentsgencost_posproc_i integer() Post-processor integer argumentsgencost_posproc_r real() Post-processor real argumentsgencost_spmin real Data less than this value will be omittedgencost_spmax real Data greater than this value will be omittedgencost_spzero real Data points equal to this value will be omittedgencost_startdate1 integer Start date of observations (YYYMMDD)gencost_startdate2 integer Start date of observations (HHMMSS)gencost_is3d logical Needs to be true for 3D fieldsgencost_enddate1 integer Not fully implemented (used only in Section 1013)gencost_enddate2 integer Not fully implemented (used only in Section 1013)

101 ECCO model-data comparisons using gridded data sets 283

Table 103 Implemented gencost_barfile options (as of check-point 65z) that can be used via cost_genericF (Section 1011)An extension starting with lsquo_rsquo can be appended at the end of the vari-able name to distinguish between separate cost function terms Notethe lsquom_etarsquo formula depends on the ATMOSPHERIC_LOADING andALLOW_PSBAR_STERIC compile time options and lsquouseRealFreshWa-terFluxrsquo run time parameter

variable name description remarksm_eta sea surface height free surface + ice + global steric correctionm_sst sea surface temperature first level potential temperaturem_sss sea surface salinity first level salinitym_bp bottom pressure phiHydLowm_siarea sea-ice area from pkgseaicem_siheff sea-ice effective thickness from pkgseaicem_sihsnow snow effective thickness from pkgseaicem_theta potential temperature three-dimensionalm_salt salinity three-dimensionalm_UE zonal velocity three-dimensionalm_VN meridional velocity three-dimensionalm_ustress zonal wind stress from pkgexfm_vstress meridional wind stress from pkgexfm_uwind zonal wind from pkgexfm_vwind meridional wind from pkgexfm_atemp atmospheric temperature from pkgexfm_aqh atmospheric specific humidity from pkgexfm_precip precipitation from pkgexfm_swdown downward shortwave from pkgexfm_lwdown downward longwave from pkgexfm_wspeed wind speed from pkgexfm_diffkr verticaldiapycnal diffusivity three-dimensional constantm_kapgm GM diffusivity three-dimensional constantm_kapredi isopycnal diffusivity three-dimensional constantm_geothermalflux geothermal heat flux constantm_bottomdrag bottom drag constant

Table 104 gencost_preproc and gencost_posproc optionsimplemented as of checkpoint 65z Note the distinction betweengencost_preproc and gencost_posproc seems unclear andmay be revisited in the future

name description gencost_preproc_i _r or _cgencost_preprocclim Use climatological misfits integer no of records per climatological cyclemean Use time mean of misfits mdashanom Use anomalies from time mean mdashvariaweight Use time-varying weight 119882119894 mdashnosumsq Use linear misfits mdashfactor Multiply 119894 by a scaling factor real the scaling factorgencost_posprocsmooth Smooth misfits character smoothing scale file

integer smoother of time steps

1012 Generic Integral Function

The functionality described in this section is operated by cost_gencost_boxmeanF It is primarily aimed atobtaining a mechanistic understanding of a chosen physical variable via adjoint sensitivity computations (see Auto-matic Differentiation) as done for example in [MGZ+99][HWP+11][FWL+15] Thus the quadratic term in Eq (101)(119889119879119894 119877

minus1119894 119889119894) is by default replaced with a 119889119894 scalar2 that derives from model fields through a generic integral formula

(Eq (103)) The specification of gencost_barfile again selects the physical variable type Current valid optionsto use cost_gencost_boxmeanF are reported in Table 105 A suffix starting with lsquo_rsquo can again be appendedto gencost_barfile

The integral formula is defined by masks provided via binary files which names are specified via gencost_maskThere are two cases (1) if gencost_mask = lsquofoo_maskrsquo and gencost_barfile is of the lsquom_boxmeanrsquotype then the model will search for horizontal vertical and temporal mask files named foo_maskC foo_maskKand foo_maskT (2) if instead gencost_barfile is of the lsquom_horflux_rsquo type then the model will search forfoo_maskW foo_maskS foo_maskK and foo_maskT

The lsquoCrsquo mask or the lsquoWrsquo lsquoSrsquo masks are expected to be two-dimensional fields The lsquoKrsquo and lsquoTrsquo masks (both optionalall 1 by default) are expected to be one-dimensional vectors The lsquoKrsquo vector length should match Nr The lsquoTrsquo vectorlength should match the of records that the specification of gencost_avgperiod implies but there is no restric-tion on its values In case 1 (lsquom_boxmeanrsquo) the lsquoCrsquo and lsquoKrsquo masks should consists of +1 and 0 values and a volumeaverage will be computed accordingly In case 2 (lsquom_horfluxrsquo) the lsquoWrsquo lsquoSrsquo and lsquoKrsquo masks should consists of +1-1 and 0 values and an integrated horizontal transport (or overturn) will be computed accordingly

Table 105 Implemented gencost_barfile options (as of check-point 65z) that can be used via cost_gencost_boxmeanF (Section1012)

variable name description remarksm_boxmean_theta mean of theta over box specify boxm_boxmean_salt mean of salt over box specify boxm_boxmean_eta mean of SSH over box specify boxm_horflux_vol volume transport through section specify transect

1013 Custom Cost Functions

This section (very much a work in progress ) pertains to the special cases of cost_gencost_bpv4F cost_gencost_seaicev4F cost_gencost_sshv4F cost_gencost_sstv4F andcost_gencost_transpF The cost_gencost_transpF function can be used to compute a transport of vol-ume heat or salt through a specified section (non quadratic cost function) To this end one sets gencost_name =lsquotransprsquo where is an optional suffix starting with lsquo_rsquo and set gencost_barfile to one of m_trVolm_trHeat and m_trSalt

2 The quadratic option in fact does not yet exist in cost_gencost_boxmeanF

Table 106 Pre-defined gencost_name special cases (as of check-point 65z Section 1013)

name description remarkssshv4-mdt sea surface height mean dynamic topography (SSH - geod)sshv4-tp sea surface height Along-Track TopexJason SLA (level 3)sshv4-ers sea surface height Along-Track ERSEnvisat SLA (level 3)sshv4-gfo sea surface height Along-Track GFO class SLA (level 3)sshv4-lsc sea surface height Large-Scale SLA (from the above)sshv4-gmsl sea surface height Global-Mean SLA (from the above)bpv4-grace bottom pressure GRACE maps (level 4)sstv4-amsre sea surface temperature Along-Swath SST (level 3)sstv4-amsre-lsc sea surface temperature Large-Scale SST (from the above)si4-cons sea ice concentration needs sea-ice adjoint (level 4)si4-deconc model sea ice deficiency proxy penalty (from the above)si4-exconc model sea ice excess proxy penalty (from the above)transp_trVol volume transport specify masks (Section 1012)transp_trHeat heat transport specify masks (Section 1012)transp_trSalt salt transport specify masks (Section 1012)

1014 Key Routines

TBA ecco_readparmsF ecco_checkF ecco_summaryF cost_genericFcost_gencost_boxmeanF ecco_toolboxF ecco_physF cost_gencost_customizeF cost_averagesfieldsF

1015 Compile Options

TBA ALLOW_GENCOST_CONTRIBUTION ALLOW_GENCOST3D AL-LOW_PSBAR_STERIC ALLOW_SHALLOW_ALTIMETRY ALLOW_HIGHLAT_ALTIMETRY AL-LOW_PROFILES_CONTRIBUTION ALLOW_ECCO_OLD_FC_PRINT ECCO_CTRL_DEPRECATED packages required for some functionalities smooth profiles ctrl

102 PROFILES model-data comparisons at observed locations

Author Gael Forget

The purpose of pkgprofiles is to allow sampling of MITgcm runs according to a chosen pathway (after a ship or adrifter along altimeter tracks etc) typically leading to easy model-data comparisons Given input files that con-tain positions and dates pkgprofiles will interpolate the model trajectory at the observed location In particularpkgprofiles can be used to do model-data comparison online and formulate a least-squares problem (ECCO applica-tion)

The pkgprofiles namelist is called dataprofiles In the example below it includes two input netcdf file names (AR-GOifremer_r8nc and XBT_v5nc) that should be linked to the run directory and cost function multipliers that onlymatter in the context of automatic differentiation (see Automatic Differentiation) The first index is a file number andthe second index (in mult only) is a variable number By convention the variable number is an integer ranging 1 to6 temperature salinity zonal velocity meridional velocity sea surface height anomaly and passive tracer

The netcdf input file structure is illustrated in the case of XBT_v5nc To create such files one can use the MITprof mat-lab toolbox obtained from httpsgithubcomgaelforgetMITprof At run time each file is scanned to determine which

variables are included these will be interpolated The (final) output file structure is similar but with interpolated modelvalues in prof_T etc and it contains model mask variables (eg prof_Tmask) The very model output consists of onebinary (or netcdf) file per processor The final netcdf output is to be built from those using netcdf_ecco_recomposem(offline)

When the k2 option is used (eg for cubed sphere runs) the input file is to be completed with interpolation gridpoints and coefficients computed offline using netcdf_ecco_GenericgridMainm Typically you would first provide thestandard namelist and files After detecting that interpolation information is missing the model will generate specialgrid files (profilesXCincl1PointOverlap etc) and then stop You then want to run netcdf_ecco_GenericgridMainmusing the special grid files This operation could eventually be inlined

Example dataprofiles

PROFILES cost function ampPROFILES_NMLprofilesfiles(1)= rsquoARGOifremer_r8rsquomult_profiles(11) = 1mult_profiles(12) = 1profilesfiles(2)= rsquoXBT_v5rsquomult_profiles(21) = 1

Example XBT_v5nc

netcdf XBT_v5 dimensionsıPROF = 278026 iDEPTH = 55 lTXT = 30 variablesdouble depth(iDEPTH) depthunits = meters double prof_YYYYMMDD(iPROF) prof_YYYYMMDDmissing_value = -9999 prof_YYYYMMDDlong_name = year (4 digits) month (2 digits) day (2 digits) double prof_HHMMSS(iPROF) prof_HHMMSSmissing_value = -9999 prof_HHMMSSlong_name = hour (2 digits) minute (2 digits) second (2 digits) double prof_lon(iPROF) prof_lonunits = (degree E) prof_lonmissing_value = -9999 double prof_lat(iPROF) prof_latunits = (degree N) prof_latmissing_value = -9999 char prof_descr(iPROF lTXT) prof_descrlong_name = profile description double prof_T(iPROF iDEPTH) prof_Tlong_name = potential temperature prof_Tunits = degree Celsius prof_Tmissing_value = -9999 double prof_Tweight(iPROF iDEPTH) prof_Tweightlong_name = weights prof_Tweightunits = (degree Celsius)-2

102 PROFILES model-data comparisons at observed locations 287

prof_Tweightmissing_value = -9999

103 CTRL Model Parameter Adjustment Capability

Author Gael Forget

The parameters available for configuring generic cost terms in datactrl are given in Table 107

Table 107 Parameters in ctrl_nml_genarr namelist in datactrl The can be replaced by arr2d arr3d or tim2d fortime-invariant two and three dimensional controls and time-varying 2Dcontrols respectively Parameters for genarr2d genarr3d andgentime2d are arrays of length maxCtrlArr2D maxCtrlArr3Dand maxCtrlTim2D respectively with one entry per term in the costfunction

parameter type functionxx_gen_file character() Control Name prefix from Table 108 + suffixxx_gen_weight character() Weights in the form of 120590minus2

119895

xx_gen_bounds real(5) Apply boundsxx_gen_preproc character() Control preprocessor(s) (see Table 109 )xx_gen_preproc_c character() Preprocessor character argumentsxx_gen_preproc_i integer() Preprocessor integer argumentsxx_gen_preproc_r real() Preprocessor real argumentsgenPrecond real Preconditioning factor (= 1 by default)mult_gen real Cost function multiplier 120573119895 (= 1 by default)xx_gentim2d_period real Frequency of adjustments (in seconds)xx_gentim2d_startda te1 integer Adjustment start datexx_gentim2d_startda te2 integer Default model start datexx_gentim2d_cumsum logical Accumulate control adjustmentsxx_gentim2d_glosum logical Global sum of adjustment (output is still 2D)

Table 108 Generic control prefixes implemented as of checkpoint 65zname description

2D time-invariant controls genarr2dxx_etan initial sea surface heightxx_bottomdrag bottom dragxx_geothermal geothermal heat flux

3D time-invariant controls genarr3dxx_theta initial potential temperaturexx_salt initial salinityxx_kapgm GM coefficientxx_kapredi isopycnal diffusivityxx_diffkr diapycnal diffusivity

2D time-varying controls gentim2Dxx_atemp atmospheric temperaturexx_aqh atmospheric specific humidityxx_swdown downward shortwavexx_lwdown downward longwavexx_precip precipitationxx_uwind zonal windxx_vwind meridional windxx_tauu zonal wind stressxx_tauv meridional wind stressxx_gen_precip globally averaged precipitation

Table 109 xx_gend_preproc options implemented as ofcheckpoint 65z Notes 119886 If noscaling is false the control adjust-ment is scaled by one on the square root of the weight before beingadded to the base control variable if noscaling is true the controlis multiplied by the weight in the cost function itself

name description argumentsWC01 Correlation modeling integer operator type (default 1)smooth Smoothing without normalization integer operator type (default 1)docycle Average period replication integer cycle lengthreplicate Alias for docycle (units of xx_gentim2d_period)rmcycle Periodic average subtraction integer cycle lengthvariaweight Use time-varying weight mdashnoscalingmath ^a Do not scale with xx_gen_weight mdashdocumul Sets xx_gentim2d_cumsum mdashdoglomean Sets xx_gentim2d_glosum mdash

The control problem is non-dimensional by default as reflected in the omission of weights in control penalties [(119879119895 119895in (101)] Non-dimensional controls (119895) are scaled to physical units (119895) through multiplication by the respec-tive uncertainty fields (120590119895

) as part of the generic preprocessor 119980 in (104) Besides the scaling of 119895 to physicalunits the preprocessor 119980 can include for example spatial correlation modeling (using an implementation of Weaverand Coutier 2001) by setting xx_gen_preproc = rsquoWC01rsquo Alternatively setting xx_gen_preproc =rsquosmoothrsquo activates the smoothing part of WC01 but omits the normalization Additionally bounds for the controlscan be specified by setting xx_gen_bounds In forward mode adjustments to the 119894th control are clipped so thatthey remain between xx_gen_bounds(i1) and xx_gen_bounds(i4) If xx_gen_bounds(i1)lt xx_gen_bounds(i+11) for 119894 = 1 2 3 then the bounds will ldquoemulate a local minimumrdquo otherwise thebounds have no effect in adjoint mode

103 CTRL Model Parameter Adjustment Capability 289

For the case of time-varying controls the frequency is specified by xx_gentim2d_period The generic con-trol package interprets special values of xx_gentim2d_period in the same way as the exf package a valueof minus12 implies cycling monthly fields while a value of 0 means that the field is steady Time varying weightscan be provided by specifying the preprocessor variaweight in which case the xx_gentim2d_weight filemust contain as many records as the control parameter time series itself (approximately the run length divided byxx_gentim2d_period)

The parameter mult_gen sets the multiplier for the corresponding cost function penalty [120573119895 in (101) 120573119895 = 1by default) The preconditioner ℛ does not directly appear in the estimation problem but only serves to push theoptimization process in a certain direction in control space this operator is specified by genPrecond (= 1 bydefault)

104 SMOOTH Smoothing And Covariance Model

Author Gael Forget

TO BE CONTINUED

105 The line search optimisation algorithm

Author Patrick Heimbach

1051 General features

The line search algorithm is based on a quasi-Newton variable storage method which was implemented by [GL89]

TO BE CONTINUED

1052 The online vs offline version

bull Online versionEvery call to simul refers to an execution of the forward and adjoint model Several iterations of optimizationmay thus be performed within a single run of the main program (lsopt_top) The following cases may occur

ndash cold start only (no optimization)

ndash cold start followed by one or several iterations of optimization

ndash warm start from previous cold start with one or several iterations

ndash warm start from previous warm start with one or several iterations

bull Offline versionEvery call to simul refers to a read procedure which reads the result of a forward and adjoint run Thereforeonly one call to simul is allowed itmax = 0 for cold start itmax = 1 for warm start Also at the end x(i+1)needs to be computed and saved to be available for the offline model and adjoint run

In order to achieve minimum difference between the online and offline code xdiff(i+1) is stored to file at the end of an(offline) iteration but recomputed identically at the beginning of the next iteration

1053 Number of iterations vs number of simulations

- itmax controls the max number of iterations- nfunc controls the max number of simulations within one iteration

10531 Summary

From one iteration to the next the descent direction changes Within one iteration more than one forward and adjointrun may be performed The updated control used as input for these simulations uses the same descent direction butdifferent step sizes

10532 Description

From one iteration to the next the descent direction dd changes using the result for the adjoint vector gg of theprevious iteration In lsline the updated control

xdiff(i 1) = xx(iminus 1) + tact(iminus 1 1) dd(iminus 1)

serves as input for a forward and adjoint model run yielding a new gg(i1) In general the new solutionpasses the 1st and 2nd Wolfe tests so xdiff(i1) represents the solution sought

xx(i) = xdiff(i 1)

If one of the two tests fails an inter- or extrapolation is invoked to determine a new step size tact(i-12) Ifmore than one function call is permitted the new step size is used together with the ldquooldrdquo descent directiondd(i-1) (ie dd is not updated using the new gg(i)) to compute a new

that serves as input in a new forward and adjoint run yielding gg(i2) If now both Wolfe tests aresuccessful the updated solution is given by

xx(i) = xdiff(i 2) = xx(iminus 1) + tact(iminus 1 2) dd(iminus 1)

In order to save memory both the fields dd and xdiff have a double usage

bull- in lsopt_top used as x(i) - x(i-1) for Hessian update- in lsline intermediate result for control update x = x + tactdd

bull- in lsopt_top lsline descent vector dd = -gg and hessupd- in dgscale intermediate result to compute new preconditioner

105 The line search optimisation algorithm 291

10533 The parameter file lsoptpar

bull NUPDATE max no of update pairs (gg(i)-gg(i-1) xx(i)-xx(i-1)) to be stored in OPWARMD to estimateHessian [pair of current iter is stored in (2jmax+2 2jmax+3) jmax must be gt 0 to access these entries]Presently NUPDATE must be gt 0 (ie iteration without reference to previous iterations through OPWARMDhas not been tested)

bull EPSX relative precision on xx bellow which xx should not be improved

bull EPSG relative precision on gg below which optimization is considered successful

bull IPRINT controls verbose (gt=1) or non-verbose output

bull NUMITER max number of iterations of optimisation NUMTER = 0 cold start only no optimization

bull ITER_NUM index of new restart file to be created (not necessarily = NUMITER)

bull NFUNC max no of simulations per iteration (must be gt 0) is used if step size tact is inter-extrapolated inthis case if NFUNC gt 1 a new simulation is performed with same gradient but ldquoimprovedrdquo step size

bull FMIN first guess cost function value (only used as long as first iteration not completed ie for jmax lt= 0)

10534 OPWARMI OPWARMD files

Two files retain values of previous iterations which are used in latest iteration to update Hessian

bull OPWARMI contains index settings and scalar variables

n = nn no of control variablesfc = ff cost value of last iterationisize no of bytes per record in OPWARMDm = nupdate max no of updates for Hessianjmin jmax pointer indices for OPWARMD file (cf below)gnorm0 norm of first (cold start) gradient ggiabsiter total number of iterations with respect to cold start

bull OPWARMD contains vectors (control and gradient)

entry name description1 xx(i) control vector of latest iteration2 gg(i) gradient of latest iteration3 xdiff(i)diag preconditioning vector (1 1) for cold start2jmax+2 gold=g(i)-g(i-1) for last update (jmax)2jmax+3 xdiff=tactd=xx(i)-xx (i-1) for last update (jmax)

Example 1 jmin = 1 jmax = 3 mupd = 5

1 2 3 | 4 5 6 7 8 9 empty empty|___|___|___| | |___|___| |___|___| |___|___| |___|___| |___|___|

0 | 1 2 3

Example 2 jmin = 3 jmax = 7 mupd = 5 ---gt jmax = 2

1 2 3 ||___|___|___| | |___|___| |___|___| |___|___| |___|___| |___|___|

| 6 7 3 4 5

10535 Error handling

lsopt_top||---- check arguments|---- CALL INSTORE| || |---- determine whether OPWARMI available| if no cold start create OPWARMI| if yes warm start read from OPWARMI| create or open OPWARMD||---- check consistency between OPWARMI and model parameters||---- gtgtgt if COLD start ltltlt| | first simulation with fg xx_0 output first ff_0 gg_0| | set first preconditioner value xdiff_0 to 1| | store xx(0) gg(0) xdiff(0) to OPWARMD (first 3 entries)| || gtgtgt else WARM start ltltlt| read xx(i) gg(i) from OPWARMD (first 2 entries)| for first warm start after cold start i=0||||---- if ITMAX gt 0 perform optimization (increment loop index i)| (| )---- save current values of gg(i-1) -gt gold(i-1) ff -gt fold(i-1)| (---- CALL LSUPDXX| ) || ( |---- gtgtgt if jmax=0 ltltlt| ) | | first optimization after cold start| ( | | preconditioner estimated via ff_0 - ff_(first guess)| ) | | dd(i-1) = -gg(i-1)preco| ( | || ) | gtgtgt if jmax gt 0 ltltlt| ( | dd(i-1) = -gg(i-1)| ) | CALL HESSUPD| ( | || ) | |---- dd(i-1) modified via Hessian approx| ( || ) |---- gtgtgt if ltddgggt gt= 0 ltltlt| ( | ifail = 4| ) || ( |---- compute step size tact(i-1)| ) |---- compute update xdiff(i) = xx(i-1) + tact(i-1)dd(i-1)| (| )---- gtgtgt if ifail = 4 ltltlt| ( goto 1000| )| (---- CALL OPTLINE LSLINE| ) |

| )| (---- CALL OPTLINE LSLINE

| ) || ( |---- loop over simulations| ) (| ( )---- CALL SIMUL| ) ( || ( ) |---- input xdiff(i)| ) ( |---- output ff(i) gg(i)| ( ) |---- gtgtgt if ONLINE ltltlt| ) ( runs model and adjoint| ( ) gtgtgt if OFFLINE ltltlt| ) ( reads those values from file| ( )| ) (---- 1st Wolfe test| ( ) ff(i) lt= tactxpara1ltgg(i-1)dd(i-1)gt| ) (| ( )---- 2nd Wolfe test| ) ( ltgg(i)dd(i-1)gt gt= xpara2ltgg(i-1)dd(i-1)gt| ( )| ) (---- gtgtgt if 1st and 2nd Wolfe tests ok ltltlt| ( ) | 320 update xx xx(i) = xdiff(i)| ) ( || ( ) gtgtgt else if 1st Wolfe test not ok ltltlt| ) ( | 500 INTERpolate new tact| ( ) | barrtact lt tact lt (1-barr)tact| ) ( | CALL CUBIC| ( ) || ) ( gtgtgt else if 2nd Wolfe test not ok ltltlt| ( ) 350 EXTRApolate new tact| ) ( (1+barmin)tact lt tact lt 10tact| ( ) CALL CUBIC| ) (| ( )---- gtgtgt if new tact gt tmax ltltlt| ) ( | ifail = 7| ( ) || ) (---- gtgtgt if new tact lt tmin OR tactdd lt machine precision ltltlt| ( ) | ifail = 8| ) ( || ( )---- gtgtgt else ltltlt| ) ( update xdiff for new simulation| ( )| ) if nfunc gt 1 use inter-extrapolated tact and xdiff| ( for new simulation| ) NB new xx is thus not based on new gg but| ( rather on new step size tact| )| (---- store new values xx(i) gg(i) to OPWARMD (first 2 entries)| )---- gtgtgt if ifail = 789 ltltlt| ( goto 1000| )

| )| (---- store new values xx(i) gg(i) to OPWARMD (first 2 entries)| )---- gtgtgt if ifail = 789 ltltlt| ( goto 1000

| )| (---- compute new pointers jmin jmax to include latest values| ) gg(i)-gg(i-1) xx(i)-xx(i-1) to Hessian matrix estimate| (---- store gg(i)-gg(i-1) xx(i)-xx(i-1) to OPWARMD| ) (entries 2jmax+2 2jmax+3)| (| )---- CALL DGSCALE| ( || ) |---- call dostore| ( | || ) | |---- read preconditioner of previous iteration diag(i-1)| ( | from OPWARMD (3rd entry)| ) || ( |---- compute new preconditioner diag(i) based upon diag(i-1)| ) | gg(i)-gg(i-1) xx(i)-xx(i-1)| ( || ) |---- call dostore| ( || ) |---- write new preconditioner diag(i) to OPWARMD (3rd entry)| (|---- end of optimization iteration loop||||---- CALL OUTSTORE| || |---- store gnorm0 ff(i) current pointers jmin jmax iterabs to OPWARMI||---- gtgtgt if OFFLINE version ltltlt| xx(i+1) needs to be computed as input for offline optimization| || |---- CALL LSUPDXX| | || | |---- compute dd(i) tact(i) -gt xdiff(i+1) = x(i) + tact(i)dd(i)| || |---- CALL WRITE_CONTROL| | || | |---- write xdiff(i+1) to special file for offline optim||---- print final information|O

CHAPTER 11

Under Development

298 Chapter 11 Under Development

CHAPTER 12

Previous Applications of MITgcm

300 Chapter 12 Previous Applications of MITgcm

Bibliography

[Adc95] A Adcroft Numerical Algorithms for use in a Dynamical Model of the Ocean PhD thesis Imperial CollegeLondon 1995

[AC04] A Adcroft and J-M Campin Re-scaled height coordinates for accurate representation of free-surface flowsin ocean circulation models Ocean Modelling 7269ndash284 2004 doi101016jocemod200309003

[ACHM04] A Adcroft J-M Campin C Hill and J Marshall Implementation of an atmosphere-ocean generalcirculation model on the expanded spherical cube Mon~Wea~Rev 1322845ndash2863 2004 URL httpmitgcmorgpdfsmwr_2004pdf doi101175MWR28231

[AHCampin+04] A Adcroft C Hill J-M Campinbdquo J Marshall and P Heimbach Overview of the formulationand numerics of the MITgcm In Proceedings of the ECMWF seminar series on Numerical Methods Recentdevelopments in numerical methods for atmosphere and ocean modelling 139ndash149 ECMWF 2004 URL httpmitgcmorgpdfsECMWF2004-Adcroftpdf

[AHM99] A Adcroft C Hill and J Marshall A new treatment of the coriolis terms in c-grid models at bothhigh and low resolutions Mon~Wea~Rev 1271928ndash1936 1999 URL httpmitgcmorgpdfsmwr_1999pdfdoi1011751520-049328199929127lt1928ANTOTCgt20CO2

[AHM97] AJ Adcroft CN Hill and J Marshall Representation of topography by shaved cells in a heightcoordinate ocean model Mon~Wea~Rev 1252293ndash2315 1997 URL httpmitgcmorgpdfsmwr_1997pdfdoi1011751520-049328199729125lt2293ROTBSCgt20CO2

[AM98] AJ Adcroft and D Marshall How slippery are piecewise-constant coastlines in numerical ocean modelsTellus 50(1)95ndash108 1998

[AL77] A Arakawa and V Lamb Computational design of the basic dynamical processes of the ucla general circu-lation model Meth Comput Phys 17174ndash267 1977

[BFLM13] S Bouillon T Fichefet V Legat and G Madec The elastic-viscous-plastic method revisitedOcean Modelling 71(0)2ndash12 2013 Arctic Ocean URL httpdxdoiorg101016jocemod201305013doi101016jocemod201305013

[BMP75] K Bryan S Manabe and RC Pacanowski A global ocean-atmosphere climate model part ii the oceaniccirculation J~Phys~Oceanogr 530ndash46 1975

[CAHM04] J-M Campin A Adcroft C Hill and J Marshall Conservation of properties in a free-surface modelOcean Modelling 6221ndash244 2004

[CMF08] J-M Campin J Marshall and D Ferreira Sea-ice ocean coupling using a rescaled vertical coordinatez$^ast $ Ocean Modelling 24(1ndash2)1ndash14 2008 doi101016jocemod200805005

[CMKL+14] K Castro-Morales F Kauker M Losch S Hendricks K Riemann-Campe and R Gerdes Sensitivityof simulated Arctic sea ice to realistic ice thickness distributions and snow parameterizations J~Geophys~Res119(1)559ndash571 2014 URL httpdxdoiorg1010022013JC009342 doi1010022013JC009342

[Cho90] M-D Chou Parameterizations for the absorption of solar radiation by o$_2$ and co$_2$ with applicationsto climate studies J~Clim 3209ndash217 1990

[Cho92] M-D Chou A solar radiation model for use in climate studies J~Atmos~Sci 49762ndash772 1992

[CS94] M-D Chou and MJ Suarez An efficient thermal infrared radiation parameterization for use in general cir-culation models NASA Technical Memorandum 104606-Vol 3 National Aeronautics and Space AdministrationNASA Goddard Space Flight Center Greenbelt (MD) 20771 USA 1994 httpwwwgmaonasagov

[Cla70] RH Clarke Observational studies in the atmospheric boundary layer Q~J~R~Meteorol~Soc 9691ndash1141970

[Cox87] MD Cox An isopycnal diffusion in a z-coordinate ocean model Ocean modelling 741ndash5 (Unpublishedmanuscript) 1987

[DT94] RS Defries and JRG Townshend Ndvi-derived land cover classification at global scales Intrsquol J Rem Sens153567ndash3586 1994

[DS89] JL Dorman and PJ Sellers A global climatology of albedo roughness length and stomatal resistance foratmospheric general circulation models as represented by the simple biosphere model (sib) J~Appl~Meteor28833ndash855 1989

[FWDH92] GM Flato and III WD Hibler Modeling pack ice as a cavitating fluid J~Phys~Oceanogr 22626ndash6511992

[FRM83] P Fofonoff and Jr R Millard Algorithms for computation of fundamental properties of seawater UNESCOTechnical Papers in Marine Science 44 UNESCO Paris 1983

[FCH+15] G Forget J-M Campin P Heimbach C N Hill R M Ponte and C Wunsch ECCO version 4 anintegrated framework for non-linear inverse modeling and global ocean state estimation Geoscientific ModelDevelopment 8(10)3071ndash3104 2015 URL httpwwwgeosci-model-devnet830712015 doi105194gmd-8-3071-2015

[FWL+15] Ichiro Fukumori Ou Wang William Llovel Ian Fenty and Gael Forget A near-uniform fluctuationof ocean bottom pressure and sea level across the deep ocean basins of the arctic ocean and the nordic seasProgress in Oceanography 134(0)152 ndash 172 2015 URL httpwwwsciencedirectcomsciencearticlepiiS0079661115000245 doihttpdxdoiorg101016jpocean201501013

[GGL90] P Gaspar Y Greacutegoris and J-M Lefevre A simple eddy kinetic energy model for simulations of theoceanic vertical mixing tests at station papa and long-term upper ocean study site J~Geophys~Res 95(C9)16179ndash16193 1990

[GM90] PR Gent and JC McWilliams Isopycnal mixing in ocean circulation models J~Phys~Oceanogr20150ndash155 1990

[GWMM95] PR Gent J Willebrand TJ McDougall and JC McWilliams Parameterizing eddy-induced tracertransports in ocean circulation models J~Phys~Oceanogr 25463ndash474 1995

[GKW91] R Gerdes C Koberle and J Willebrand The influence of numerical advection schemes on the results ofocean general circulation models Clim~Dynamics 5(4)211ndash226 1991 doi101007BF00210006

[GL89] JC Gilbert and C Lemareacutechal Some numerical experiments with variable-storage quasi-newton algorithmsMath Programming 45407ndash435 1989

[Gil82] AE Gill Atmosphere-Ocean Dynamics Academic Press New York 1982

[Gri98] SM Griffies The Gent-McWilliams skew flux J~Phys~Oceanogr 28831ndash841 1998

302 Bibliography

[GGP+98] SM Griffies A Gnanadesikan RC Pacanowski V Larichev JK Dukowicz and RD Smith Isoneutraldiffusion in a z-coordinate ocean model J~Phys~Oceanogr 28805ndash830 1998

[GH00] SM Griffies and RW Hallberg Biharmonic friction with a smagorinsky-like viscosity for use in large-scaleeddy-permitting ocean models Mon~Wea~Rev 128(8)2935ndash2946 2000

[HW65] FH Harlow and JE Welch Numerical calculation of time-dependent viscous incompressible flow of fluidwith free surface Physics of Fluids 82182ndash2189 1965

[HWP+11] Patrick Heimbach Carl Wunsch Rui M Ponte Gael Forget Chris Hill and Jean Utke Timescales andregions of the sensitivity of Atlantic meridional volume and heat transport toward observing system design DeepSea Research Part II Topical Studies in Oceanography 58(17)1858ndash1879 2011

[HS94] IM Held and MJ Suarez A proposal for the intercomparison of the dynamical cores of atmospheric generalcirculation models Bulletin of the American Meteorological Society 75(10)1825ndash1830 1994

[HL88] HM Helfand and JC Labraga Design of a non-singular level 25 second-order closure model for the pre-diction of atmospheric turbulence J~Atmos~Sci 45113ndash132 1988

[HS95] HM Helfand and SD Schubert Climatology of the simulated great plains low-level jet and its contributionto the continental moisture budget of the united states J~Clim 8784ndash806 1995

[Hib79] WD Hibler III A dynamic thermodynamic sea ice model J~Phys~Oceanogr 9815ndash846 1979

[Hib80] WD Hibler III Modeling a variable thickness sea ice cover Mon~Wea~Rev 11943ndash1973 1980

[Hib84] WD Hibler III The role of sea ice dynamics in modeling co$_2$ increases In J E Hansen and T Takahashieditors Climate processes and climate sensitivity volume 29 of Geophysical Monograph pages 238ndash253 AGUWashington DC 1984

[HB87] WD Hibler III and K Bryan A diagnostic ice-ocean model J~Phys~Oceanogr 17(7)987ndash1015 1987

[HAJM99] C Hill A Adcroft D Jamous and John Marshall A strategy for terascale climate modeling In InProceedings of the Eighth ECMWF Workshop on the Use of Parallel Processors in Meteorology 406ndash425 WorldScientific 1999

[HM95] C Hill and J Marshall Application of a parallel navier-stokes model to ocean circulation in parallel com-putational fluid dynamics In N Satofuka A Ecer J Periaux and S Taylor editors Implementations and ResultsUsing Parallel Computers pages 545ndash552 Elsevier Science BV New York 1995

[Hol78] WR Holland The role of mesoscale eddies in the general circulation of the ocean-numerical experimentsusing a wind-driven quasi-geostrophic model J~Phys~Oceanogr 8363ndash392 1978

[HL75] WR Holland and LB Lin On the origin of mesoscale eddies and their contribution to the general circulationof the ocean i a preliminary numerical experiment J~Phys~Oceanogr 5642ndash657 1975

[Hun01] EC Hunke Viscous-plastic sea ice dynamics with the EVP model linearization issues J~Comput~Phys17018ndash38 2001 doi101006jcph20016710

[HD97] EC Hunke and JK Dukowicz An elastic-viscous-plastic model for sea ice dynamics J~Phys~Oceanogr271849ndash1867 1997

[HJL04] JK Hutchings H Jasak and SW Laxon A strength implicit correction scheme for the viscous-plastic seaice model Ocean Modelling 7(1ndash2)111ndash133 2004 doi101016S1463-5003(03)00040-4

[JM95] D R Jackett and T J McDougall Minimal adjustment of hydrographic profiles to achieve static stabilityJ~Atmos~Ocean~Technol 12(4)381ndash389 1995

[KDL15] M Kimmritz S Danilov and M Losch On the convergence of the modified elastic-viscous-plastic methodof solving for sea-ice dynamics J~Comput~Phys 29690ndash100 2015 doi101016jjcp201504051

[KDL16] M Kimmritz S Danilov and M Losch The adaptive EVP method for solving the sea ice momentumequation Ocean Modelling 10159ndash67 2016 doi101016jocemod201603004

Bibliography 303

[KL10] JM Klymak and SM Legg A simple mixing scheme for models that resolve breaking internal waves OceanModelling 33224ndash234 2010 doi101016jocemod201002005

[Kon75] J Kondo Air-sea bulk transfer coefficients in diabatic conditions Bound~Layer~Meteorol 991ndash112 1975

[KS91] RD Koster and MJ Suarez A simplified treatment of sibrsquos land surface albedo parameterization NASATechnical Memorandum 104538 National Aeronautics and Space Administration NASA Goddard Space FlightCenter Greenbelt (MD) 20771 USA 1991 httpwwwgmaonasagov

[KS92] RD Koster and MJ Suarez Modeling the land surface boundary in climate models as a composite of inde-pendent vegetation stands J~Geophys~Res 972697ndash2715 1992

[LH74] AA Lacis and JE Hansen A parameterization for the absorption of solar radiation in the earthrsquos atmosphereJ~Atmos~Sci 31118ndash133 1974

[LDDM97] WG Large G Danabasoglu SC Doney and JC McWilliams Sensitivity to surface forcing and bound-ary layer mixing in a global ocean model annual-mean climatology J~Phys~Oceanogr 27(11)2418ndash24471997

[LMD94] WG Large JC McWilliams and SC Doney Oceanic vertical mixing a review and a model with nonlo-cal boundary layer parameterization Rev~Geophys 32363ndash403 1994

[LP81] WG Large and S Pond Open ocean momentum flux measurements in moderate to strong windsJ~Phys~Oceanogr 11324ndash336 1981

[Lei68] CE Leith Large eddy simulation of complex engineering and geophysical flows Physics of Fluids101409ndash1416 1968

[Lei96] CE Leith Stochastic models of chaotic systems Physica D 98481ndash491 1996

[LKT+12] J-F Lemieux D Knoll B Tremblay DM Holland and M Losch A comparison of the Jacobian-freeNewton-Krylov method and the EVP model for solving the sea ice momentum equation with a viscous-plastic for-mulation a serial algorithm study J~Comput~Phys 231(17)5926ndash5944 2012 doi101016jjcp201205024

[LTSedlacek+10] J-F Lemieux B Tremblay J Sedlaacutecek P Tupper S Thomas D Huard and J-P Auclair Improv-ing the numerical convergence of viscous-plastic sea ice models with the Jacobian-free Newton-Krylov methodJ~Comput~Phys 2292840ndash2852 2010 doi101016jjcp200912011c

[Lepparanta83] M Leppaumlranta A growth model for black ice snow ican and snow thickness in subarctic basinsNordic Hydrology 1459ndash70 1983

[LFLV14] M Losch A Fuchs J-F Lemieux and A Vanselow A parallel Jacobian-free Newton-Krylov solver for acoupled sea ice-ocean model J~Comput~Phys 257(A)901ndash910 2014 doi101016jjcp201309026

[LMC+10] M Losch D Menemenlis J-M Campin P Heimbach and C Hill On the formulation of sea-ice modelsPart 1 effects of different solver implementations and parameterizations Ocean Modelling 33(1ndash2)129ndash1442010 doi101016jocemod200912008

[MGZ+99] J Marotzke R Giering KQ Zhang D Stammer C Hill and T Lee Construction of the adjoint mitocean general circulation model and application to atlantic heat transport variability J~Geophys~Res 104C1229529ndash29547 1999

[MAC+04] J Marshall A Adcroft J-M Campin C Hill and A White Atmosphere-ocean modeling ex-ploiting fluid isomorphisms Mon~Wea~Rev 1322882ndash2894 2004 URL httpmitgcmorgpdfsa_o_isopdfdoi101175MWR28351

[MAH+97] J Marshall A Adcroft C Hill L Perelman and C Heisey A finite-volume incompressible navierstokes model for studies of the ocean on parallel computers J~Geophys~Res 102(C3)5753ndash5766 1997 URLhttpmitgcmorgpdfs96JC02776pdf

[MHPA97] J Marshall C Hill L Perelman and A Adcroft Hydrostatic quasi-hydrostatic and nonhydrostaticocean modeling J~Geophys~Res 102(C3)5733ndash5752 1997 URL httpmitgcmorgpdfs96JC02775pdf

304 Bibliography

[MJH98] J Marshall H Jones and C Hill Efficient ocean modeling using non-hydrostatic algorithms J~Mar~Sys18115ndash134 1998 URL httpmitgcmorgpdfsjournal_of_marine_systems_1998pdf doi101016S0924-796328982900008-6

[MJWF03] T J McDougall D R Jackett D G Wright and R Feistel Accurate and computationally efficientalgorithms for potential temperature and density of seawater J~Atmos~Ocean~Technol 5730ndash741 2003

[Mol09] A Molod Running GCM physics and dynamics on different grids algorithm and tests Tellus 61A381ndash3932009

[MS92] S Moorthi and MJ Suarez Relaxed arakawa schubert a parameterization of moist convection for generalcirculation models Mon~Wea~Rev 120978ndash1002 1992

[Mou96] JN Moum Energy-containing scales of turbulence in the ocean thermocline J~Geophys~Res 101(C3)14095ndash14109 1996

[Orl76] I Orlanski A simple boundary condition for unbounded hyperbolic flows J~Comput~Phys 21251ndash2691976

[PR97] T Paluszkiewicz and RD Romea A one-dimensional model for the parameterization of deep convection inthe ocean Dyn~Atmos~Oceans 2695ndash130 1997

[Pan73] HA Panofsky Tower micrometeorology In D A Haugen editor Workshop on Micrometeorology Ameri-can Meteorological Society 1973

[Pot73] D Potter Computational Physics John Wiley New York 1973

[Red82] MH Redi Oceanic Isopycnal Mixing by Coordinate Rotation J~Phys~Oceanogr 12(10)1154ndash1158 oct1982 doi1011751520-0485(1982)012lt1154OIMBCRgt20CO2

[Roe85] PL Roe Some contributions to the modelling of discontinuous flows In BE Engquist S Osher and RCJSomerville editors Large-Scale Computations in Fluid Mechanics volume 22 of Lectures in Applied Mathemat-ics pages 163ndash193 American Mathematical Society Providence RI 1985

[RSG87] JE Rosenfield MR Schoeberl and MA Geller A computation of the stratospheric diabatic circulationusing an accurate radiative transfer model J~Atmos~Sci 44859ndash876 1987

[SG94] HE Seim and MC Gregg Detailed observations of a naturally occurring shear instability J~Geophys~Res99 (C5)10049ndash10073 1994

[Sem76] AJ Semtner Jr A model for the thermodynamic growth of sea ice in numerical investigations of climateJ~Phys~Oceanogr 6379ndash389 1976

[Sha70] R Shapiro Smoothing filtering and boundary effects Rev~Geophys~Space~Phys 8(2)359ndash387 1970

[Sma63] J Smagorinsky General circulation experiments with the primitive equations i the basic experimentMon~Wea~Rev 91(3)99ndash164 1963

[Sma93] J Smagorinsky Large eddy simulation of complex engineering and geophysical flows In B Galperin andSA Orszag editors Evolution of Physical Oceanography pages 3ndash36 Cambridge University Press 1993

[Ste90] DP Stevens On open boundary conditions for three dimensional primitive equation ocean circulation modelsGeophys Astrophys Fl Dyn 51103ndash133 1990

[Sto48] H Stommel The western intensification of wind-driven ocean currents Trans Am Geophys Union 292061948

[SM88] YC Sud and A Molod The roles of dry convection cloud-radiation feedback processes and the influenceof recent improvements in the parameterization of convection in the gla gcm Mon~Wea~Rev 1162366ndash23871988

[TS96] LL Takacs and MJ Suarez Dynamical aspects of climate simulations using the geos general circulationmodel NASA Technical Memorandum 104606 Volume 10 National Aeronautics and Space AdministrationNASA Goddard Space Flight Center Greenbelt (MD) 20771 USA 1996 httpwwwgmaonasagov

Bibliography 305

[Tho77] SA Thorpe Turbulence and mixing in a scottish loch Phil~Trans~R~Soc~Lond 286125ndash181 1977

[VMHS97] M Visbeck J Marshall T Haine and M Spall Specification of eddy transfer coefficients in coarse-resolution ocean circulation models J~Phys~Oceanogr 27(3)381ndash402 1997

[Waj93] R Wajsowicz A consistent formulation of the anisotropic stress tensor for use in models of the large-scaleocean circulation J~Comput~Phys 105(2)333ndash338 1993

[WG94] JC Wesson and MC Gregg Mixing at camarinal sill in the strait of gibraltar Q~J~R~Meteorol~Soc 99(C5)9847ndash9878 1994

[WB95] AA White and RA Bromley Dynamically consistent quasi-hydrostatic equations for global models witha complete representation of the coriolis force J~Geophys~Res 121399ndash418 1995

[Wil69] GP Williams Numerical integration of the three-dimensional navier stokes equations for incompressibleflow J~Fluid Mech 37727ndash750 1969

[Win00] M Winton A reformulated three-layer sea ice model J~Atmos~Ocean~Technol 17525ndash531 2000

[YK74] AM Yaglom and BA Kader Heat and mass transfer between a rough wall and turbulent fluid flow at highreynolds and peclet numbers J~Fluid Mech 62601ndash623 1974

[Yam77] T Yamada A numerical experiment on pollutant dispersion in a horizontally-homogenious atmosphericboundary layer Atmos Environ 111015ndash1024 1977

[ZH97] J Zhang and WD Hibler III On an efficient numerical method for modeling sea ice dynamicsJ~Geophys~Res 102(C4)8691ndash8702 1997

[ZWDHSR98] J Zhang III WD Hibler M Steele and DA Rothrock Arctic ice-ocean modeling with and withoutclimate restoring J~Phys~Oceanogr 28191ndash217 1998

[ZSL95] J Zhou YC Sud and K-M Lau Impact of orographically induced gravity wave drag in the gla gcmQ~J~R~Meteorol~Soc 122903ndash927 1995

306 Bibliography

Overview

Introduction

Illustrations of the model in action

Global atmosphere lsquoHeld-Suarezrsquo benchmark

Ocean gyres

Global ocean circulation

Convection and mixing over topography

Boundary forced internal waves

Parameter sensitivity using the adjoint of MITgcm

Global state estimation of the ocean

Ocean biogeochemical cycles

Simulations of laboratory experiments

Continuous equations in lsquorrsquo coordinates

Kinematic Boundary conditions

Atmosphere

Ocean

Hydrostatic Quasi-hydrostatic Quasi-nonhydrostatic and Non-hydrostatic forms

Solution strategy

Finding the pressure field

Forcingdissipation

Vector invariant form

Adjoint

Appendix ATMOSPHERE

Hydrostatic Primitive Equations for the Atmosphere in Pressure Coordinates

Appendix OCEAN

Equations of Motion for the Ocean

Appendix OPERATORS

Coordinate systems


Notation

Time-stepping

Pressure method with rigid-lid

Pressure method with implicit linear free-surface

Explicit time-stepping Adams-Bashforth

Implicit time-stepping backward method

Synchronous time-stepping variables co-located in time

Staggered baroclinic time-stepping

Non-hydrostatic formulation

Variants on the Free Surface

Crank-Nicolson barotropic time stepping

Non-linear free-surface

Spatial discretization of the dynamical equations

The finite volume method finite volumes versus finite difference

C grid staggering of variables

Grid initialization and data

Horizontal grid

Vertical grid

Topography partially filled cells

Continuity and horizontal pressure gradient term

Hydrostatic balance

Flux-form momentum equations

Advection of momentum

Coriolis terms

Curvature metric terms

Non-hydrostatic metric terms

Lateral dissipation

Vertical dissipation

Derivation of discrete energy conservation

Mom Diagnostics

Vector invariant momentum equations

Relative vorticity

Kinetic energy

Coriolis terms

Shear terms

Gradient of Bernoulli function

Horizontal divergence

Horizontal dissipation


Tracer equations

Time-stepping of tracers ABII

Linear advection schemes

Centered second order advection-diffusion

Third order upwind bias advection

Centered fourth order advection

First order upwind advection

Non-linear advection schemes

Second order flux limiters

Third order direct space time

Third order direct space time with flux limiting

Multi-dimensional advection

Comparison of advection schemes

Shapiro Filter

SHAP Diagnostics

Nonlinear Viscosities for Large Eddy Simulation

Eddy Viscosity

Mercator Nondimensional Equations


Where to find information

Obtaining the code

Method 1

Method 2

Updating the code

Model and directory structure

Building the code

Buildingcompiling the code elsewhere

Using genmake2

Building with MPI

Running the model

Running with MPI

Output files

Looking at the output

Customizing the model configuration

Parameters Computational Domain Geometry and Time-Discretization

Parameters Equation of State

Parameters Momentum Equations

Parameters Tracer Equations

Parameters Simulation Controls

Parameters Default Values


Barotropic Gyre MITgcm Example

Equations Solved

Discrete Numerical Configuration

Code Configuration

A Rotating Tank in Cylindrical Coordinates

Equations Solved


Code Configuration


Bugs and feature requests

Using Git and Github

Quickstart Guide

Detailed guide for those less familiar with Git and GitHub

Coding style guide

Automatic testing with Travis-CI

Contributing to the manual

Section headings

Internal document references

Other embedded links

Symbolic Notation

Figures

Tables

Other text blocks

Other style conventions

Building the manual

Reviewing pull requests




Overview

Using MITgcm Packages

Packages Related to Hydrodynamical Kernel

Generic AdvectionDiffusion

Shapiro Filter

FFT Filtering Code

exch2 Extended Cubed Sphere Topology

Gridalt - Alternate Grid Package

General purpose numerical infrastructure packages

OBCS Open boundary conditions for regional modeling

RBCS Package

PTRACERS Package

Ocean Packages

GMREDI Gent-McWilliamsRedi SGS Eddy Parameterization

KPP Nonlocal K-Profile Parameterization for Vertical Mixing

GGL90 a TKE vertical mixing scheme

OPPS Ocean Penetrative Plume Scheme

KL10 Vertical Mixing Due to Breaking Internal Waves

BULK_FORCE Bulk Formula Package

EXF The external forcing package

CAL The calendar package

Atmosphere Packages

Atmospheric Intermediate Physics AIM

Land package

Fizhi High-end Atmospheric Physics

Sea Ice Packages

THSICE The Thermodynamic Sea Ice Package

SEAICE Package



ECCO model-data comparisons using gridded data sets

Generic Cost Function

Generic Integral Function

Custom Cost Functions

Key Routines

Compile Options

PROFILES model-data comparisons at observed locations

CTRL Model Parameter Adjustment Capability

SMOOTH Smoothing And Covariance Model

The line search optimisation algorithm

General features

The online vs offline version

Number of iterations vs number of simulations

Under Development


Bibliography