5. Physical Parameterizations - Packages I

In this chapter and in the following chapter, the MITgcm ‘packages’ are described. While you can carry out many experiments with MITgcm by starting from case studies in section ref{sec:modelExamples}, configuring a brand new experiment or making major changes to an experimental configuration requires some knowledge of the packages that make up the full MITgcm code. Packages are used in MITgcm to help organize and layer various code building blocks that are assembled and selected to perform a specific experiment. Each of the specific experiments described in section ref{sec:modelExamples} uses a particular combination of packages.

Figure 5.1 shows the full set of packages that are available. As shown in the figure packages are classified into different groupings that layer on top of each other. The top layer packages are generally specialized to specific simulation types. In this layer there are packages that deal with biogeochemical processes, ocean interior and boundary layer processes, atmospheric processes, sea-ice, coupled simulations and state estimation. Below this layer are a set of general purpose numerical and computational packages. The general purpose numerical packages provide code for kernel numerical alogorithms that apply to many different simulation types. Similarly, the general purpose computational packages implement non-numerical alogorithms that provide parallelism, I/O and time-keeping functions that are used in many different scenarios.

Figure 5.1 Hierarchy of code layers that are assembled to make up an MITgcm simulation. Conceptually (and in terms of code organization) MITgcm consists of several layers. At the base is a layer of core software that provides a basic numerical and computational foundation for MITgcm simulations. This layer is shown marked Foundation Code at the bottom of the figure and corresponds to code in the italicised subdirectories on the figure. This layer is not organized into packages. All code above the foundation layer is organized as packages. Much of the code in MITgcm is contained in packages which serve as a useful way of organizing and layering the different levels of functionality that make up the full MITgcm software distribution. The figure shows the different packages in MITgcm as boxes containing bold face upper case names. Directly above the foundation layer are two layers of general purpose infrastructure software that consist of computational and numerical packages. These general purpose packages can be applied to both online and offline simulations and are used in many different physical simulation types. Above these layers are more specialized packages.

The following sections describe the packages shown in Figure 5.1. Section ref{sec:pkg:using} describes the general procedure for using any package in MITgcm. Following that sections ref{sec:pkg:gad}-ref{sec:pkg:monitor} layout the algorithms implemented in specific packages and describe how to use the individual packages. A brief synopsis of the function of each package is given in table ref{tab:package_summary_tab}. Organizationally package code is assigned a separate subdirectory in the MITgcm code distribution (within the source code directory texttt{pkg}). The name of this subdirectory is used as the package name in table ref{tab:package_summary_tab}.

5.1. Overview

• 5.1.1. Using MITgcm Packages
  • 5.1.1.1. Package Inclusion/Exclusion
  • 5.1.1.2. Package Activation
  • 5.1.1.3. Package Coding Standards
    • Packages are Not Libraries
    • File Inclusion Rules
    • Conditional Compilation and PACKAGES_CONFIG.h
    • Package Startup or Boot Sequence
    • Adding a package to PARAMS.h and packages_boot()

5.2. Packages Related to Hydrodynamical Kernel

• 5.2.1. Generic Advection/Diffusion
  • 5.2.1.1. Introduction
  • 5.2.1.2. Key subroutines, parameters and files
  • 5.2.1.3. GAD Diagnostics
  • 5.2.1.4. Experiments and tutorials that use GAD
• 5.2.2. Shapiro Filter
  • 5.2.2.1. Key subroutines, parameters and files
  • 5.2.2.2. Experiments and tutorials that use shap filter
• 5.2.3. FFT Filtering Code
  • 5.2.3.1. Key subroutines, parameters and files
  • 5.2.3.2. Experiments and tutorials that use zonal filter
• 5.2.4. exch2: Extended Cubed Sphere Topology
  • 5.2.4.1. Introduction
  • 5.2.4.2. Invoking exch2
  • 5.2.4.3. Generating Topology Files for exch2
  • 5.2.4.4. exch2, SIZE.h, and Multiprocessing
  • 5.2.4.5. Key Variables
  • 5.2.4.6. Key Routines
  • 5.2.4.7. Experiments and tutorials that use exch2
• 5.2.5. Gridalt - Alternate Grid Package
  • 5.2.5.1. Introduction
  • 5.2.5.2. Equations on Both Grids
  • 5.2.5.3. Time stepping Sequence
  • 5.2.5.4. Interpolation
  • 5.2.5.5. Key subroutines, parameters and files
  • 5.2.5.6. Gridalt Diagnostics
  • 5.2.5.7. Dos and donts
  • 5.2.5.8. Gridalt Reference
  • 5.2.5.9. Experiments and tutorials that use gridalt

5.3. General purpose numerical infrastructure packages

• 5.3.1. OBCS: Open boundary conditions for regional modeling
  • 5.3.1.1. Introduction
  • 5.3.1.2. OBCS configuration and compiling
  • 5.3.1.3. Run-time parameters
    • Enabling the package
    • Package flags and parameters
  • 5.3.1.4. Defining open boundary positions
  • 5.3.1.5. Equations and key routines
    • OBCS_READPARMS:
    • OBCS_CALC:
    • ORLANSKI:
    • OBCS_PRESCRIBE_READ:
    • OBCS_CALC_STEVENS:
    • OBCS_BALANCE_FLOW:
    • OBCS_APPLY_*:
    • OBCS_SPONGE:
    • OB’s with nonlinear free surface
  • 5.3.1.6. Flow chart
  • 5.3.1.7. OBCS diagnostics
  • 5.3.1.8. Reference experiments
  • 5.3.1.9. References
  • 5.3.1.10. Experiments and tutorials that use obcs
• 5.3.2. RBCS Package
  • 5.3.2.1. Introduction
  • 5.3.2.2. Key subroutines and parameters
  • 5.3.2.3. Timing of relaxation forcing fields
  • 5.3.2.4. Example 1: forcing with time averages starting at \(t=0\)
    • Cyclic data in a single file
    • Non-cyclic data, multiple files
  • 5.3.2.5. Example 2: forcing with snapshots starting at \(t=0\)
    • Cyclic data in a single file
    • Non-cyclic data, multiple files
  • 5.3.2.6. Do’s and Don’ts
  • 5.3.2.7. Reference Material
  • 5.3.2.8. Experiments and tutorials that use rbcs
• 5.3.3. PTRACERS Package
  • 5.3.3.1. Introduction
  • 5.3.3.2. Equations
  • 5.3.3.3. Key subroutines and parameters
  • 5.3.3.4. PTRACERS Diagnostics
  • 5.3.3.5. Do’s and Don’ts
  • 5.3.3.6. Reference Material

5.4. Ocean Packages

• 5.4.1. GMREDI: Gent-McWilliams/Redi SGS Eddy Parameterization
  • 5.4.1.1. Redi scheme: Isopycnal diffusion
  • 5.4.1.2. GM parameterization
  • 5.4.1.3. Griffies Skew Flux
  • 5.4.1.4. Variable \(\kappa_{GM}\)
  • 5.4.1.5. Tapering and stability
  • 5.4.1.6. Slope clipping
  • 5.4.1.7. Tapering: Gerdes, Koberle and Willebrand, Clim. Dyn. 1991
  • 5.4.1.8. Tapering: Danabasoglu and McWilliams, J. Clim. 1995
  • 5.4.1.9. Tapering: Large, Danabasoglu and Doney, JPO 1997
  • 5.4.1.10. Package Reference
  • 5.4.1.11. Experiments and tutorials that use gmredi
• 5.4.2. KPP: Nonlocal K-Profile Parameterization for Vertical Mixing
  • 5.4.2.1. Introduction
  • 5.4.2.2. KPP configuration and compiling
  • 5.4.2.3. Run-time parameters
    • Enabling the package
    • Required MITgcm flags
    • Package flags and parameters
  • 5.4.2.4. Equations and key routines
    • KPP_CALC:
    • KPP_MIX:
    • BLMIX: Mixing in the boundary layer
    • RI_IWMIX: Mixing in the interior
    • BLDEPTH: Boundary layer depth calculation:
    • KPP_CALC_DIFF_T/_S, KPP_CALC_VISC:
    • KPP_TRANSPORT_T/_S/_PTR:
    • Implicit time integration
    • Penetration of shortwave radiation
  • 5.4.2.5. Flow chart
  • 5.4.2.6. KPP diagnostics
  • 5.4.2.7. Reference experiments
  • 5.4.2.8. References
  • 5.4.2.9. Experiments and tutorials that use kpp
• 5.4.3. GGL90: a TKE vertical mixing scheme
  • 5.4.3.1. Key subroutines, parameters and files
  • 5.4.3.2. Experiments and tutorials that use GGL90
• 5.4.4. OPPS: Ocean Penetrative Plume Scheme
  • 5.4.4.1. Key subroutines, parameters and files
  • 5.4.4.2. Experiments and tutorials that use OPPS
• 5.4.5. KL10: Vertical Mixing Due to Breaking Internal Waves
  • 5.4.5.1. Introduction
  • 5.4.5.2. KL10 configuration and compiling
  • 5.4.5.3. Run-time parameters
    • Enabling the package
    • Required MITgcm flags
    • Package flags and parameters
  • 5.4.5.4. Equations and key routines
    • KL10_CALC:
    • KL10_CALC_VISC:
    • KL10_CALC_DIFF:
  • 5.4.5.5. KL10 diagnostics
  • 5.4.5.6. References
  • 5.4.5.7. Experiments and tutorials that use KL10
• 5.4.6. BULK_FORCE: Bulk Formula Package
  • 5.4.6.1. subroutine BULKF_FIELDS_LOAD
  • 5.4.6.2. subroutine BULKF_FORCING
  • 5.4.6.3. subroutine BULKF_FORMULA_LANL
  • 5.4.6.4. Initializing subroutines
  • 5.4.6.5. Diagnostic subroutines
  • 5.4.6.6. Common Blocks
  • 5.4.6.7. Input file DATA.ICE
  • 5.4.6.8. Important Notes
  • 5.4.6.9. References
  • 5.4.6.10. Experiments and tutorials that use bulk_force
• 5.4.7. EXF: The external forcing package
  • 5.4.7.1. Introduction
  • 5.4.7.2. EXF configuration, compiling & running
    • Compile-time options
  • 5.4.7.3. Run-time parameters
    • Enabling the package
    • General flags and parameters
    • Field attributes
    • Example configuration
  • 5.4.7.4. EXF bulk formulae
  • 5.4.7.5. EXF input fields and units
  • 5.4.7.6. Key subroutines
  • 5.4.7.7. EXF diagnostics
  • 5.4.7.8. References
  • 5.4.7.9. Experiments and tutorials that use exf
• 5.4.8. CAL: The calendar package
  • 5.4.8.1. Basic assumptions for the calendar tool
  • 5.4.8.2. Format of calendar dates
  • 5.4.8.3. Calendar dates and time intervals
  • 5.4.8.4. Using the calendar together with MITgcm
  • 5.4.8.5. The individual calendars
  • 5.4.8.6. Short routine description
  • 5.4.8.7. Experiments and tutorials that use cal

5.5. Atmosphere Packages

• 5.5.1. Atmospheric Intermediate Physics: AIM
  • 5.5.1.1. Key subroutines, parameters and files
  • 5.5.1.2. AIM Diagnostics
  • 5.5.1.3. Experiments and tutorials that use aim
• 5.5.2. Land package
  • 5.5.2.1. Introduction
  • 5.5.2.2. Equations and Key Parameters
  • 5.5.2.3. Land diagnostics
  • 5.5.2.4. References
  • 5.5.2.5. Experiments and tutorials that use land
• 5.5.3. Fizhi: High-end Atmospheric Physics
  • 5.5.3.1. Introduction
  • 5.5.3.2. Equations
    • Sub-grid and Large-scale Convection
    • Cloud Formation
    • Shortwave Radiation
    • Longwave Radiation
    • Cloud-Radiation Interaction
    • Turbulence
    • Atmospheric Boundary Layer
    • Surface Energy Budget
    • Surface Type
    • Surface Roughness
    • Albedo
    • Gravity Wave Drag
    • Topography and Topography Variance
    • Upper Level Moisture
  • 5.5.3.3. Fizhi Diagnostics
  • 5.5.3.4. Fizhi Diagnostic Description
    • Surface Zonal Wind Stress on the Atmosphere (\(Newton/m^2\))
    • Surface Meridional Wind Stress on the Atmosphere (\(Newton/m^2\))
    • Surface Flux of Sensible Heat (W m^–2)
    • Surface Flux of Latent Heat (\(Watts/m^2\))
    • Heat Conduction Through Sea Ice (\(Watts/m^2\))
    • Net upward Longwave Flux at the surface (\(Watts/m^2\))
    • Net downard shortwave Flux at the surface (\(Watts/m^2\))
    • Richardson number (\(dimensionless\))
    • CT - Surface Exchange Coefficient for Temperature and Moisture (dimensionless)
    • CU - Surface Exchange Coefficient for Momentum (dimensionless)
    • ET - Diffusivity Coefficient for Temperature and Moisture (m^2/sec)
    • EU - Diffusivity Coefficient for Momentum (m^2/sec)
    • TURBU - Zonal U-Momentum changes due to Turbulence (m/sec/day)
    • TURBV - Meridional V-Momentum changes due to Turbulence (m/sec/day)
    • TURBT - Temperature changes due to Turbulence (deg/day)
    • TURBQ - Specific Humidity changes due to Turbulence (g/kg/day)
    • MOISTT - Temperature Changes Due to Moist Processes (deg/day)
    • MOISTQ - Specific Humidity Changes Due to Moist Processes (g/kg/day)
    • RADLW - Heating Rate due to Longwave Radiation (deg/day)
    • RADSW - Heating Rate due to Shortwave Radiation (deg/day)
    • PREACC - Total (Large-scale + Convective) Accumulated Precipition (mm/day)
    • PRECON - Convective Precipition (mm/day)
    • TUFLUX - Turbulent Flux of U-Momentum (Newton/m^2)
    • TVFLUX - Turbulent Flux of V-Momentum (Newton/m^2)
    • TTFLUX - Turbulent Flux of Sensible Heat (Watts/m^2)
    • TQFLUX - Turbulent Flux of Latent Heat (Watts/m^2)
    • CN - Neutral Drag Coefficient (dimensionless)
    • WINDS - Surface Wind Speed (meter/sec)
    • TG - Ground Temperature (deg K)
    • TS - Surface Temperature (deg K)
    • DTG - Surface Temperature Adjustment (deg K)
    • QG - Ground Specific Humidity (g/kg)
    • QS - Saturation Surface Specific Humidity (g/kg)
    • TGRLW - Instantaneous ground temperature used as input to the Longwave radiation subroutine (deg)
    • ST4 - Upward Longwave flux at the surface (Watts/m^2)
    • OLR - Net upward Longwave flux at \(p=p_{top}\) (Watts/m^2)
    • OLRCLR - Net upward clearsky Longwave flux at \(p=p_{top}\) (Watts/m^2)
    • LWGCLR - Net upward clearsky Longwave flux at the surface (Watts/m^2)
    • LWCLR - Heating Rate due to Clearsky Longwave Radiation (deg/day)
    • TLW - Instantaneous temperature used as input to the Longwave radiation subroutine (deg)
    • SHLW - Instantaneous specific humidity used as input to the Longwave radiation subroutine (kg/kg)
    • OZLW - Instantaneous ozone used as input to the Longwave radiation subroutine (kg/kg)
    • CLMOLW - Maximum Overlap cloud fraction used in LW Radiation (0-1)
    • CLDTOT - Total cloud fraction used in LW and SW Radiation (0-1)
    • CLMOSW - Maximum Overlap cloud fraction used in SW Radiation (0-1)
    • CLROSW - Random Overlap cloud fraction used in SW Radiation (0-1)
    • RADSWT - Incident Shortwave radiation at the top of the atmosphere (Watts/m^2)
    • EVAP - Surface Evaporation (mm/day)
    • DUDT - Total Zonal U-Wind Tendency (m/sec/day)
    • DVDT - Total Zonal V-Wind Tendency (m/sec/day)
    • DTDT - Total Temperature Tendency (deg/day)
    • DQDT - Total Specific Humidity Tendency (g/kg/day)
    • USTAR - Surface-Stress Velocity (m/sec)
    • Z0 - Surface Roughness Length (m)
    • FRQTRB - Frequency of Turbulence (0-1)
    • PBL - Planetary Boundary Layer Depth (mb)
    • SWCLR - Clear sky Heating Rate due to Shortwave Radiation (deg/day)
    • OSR - Net upward Shortwave flux at the top of the model (Watts/m^2)
    • OSRCLR - Net upward clearsky Shortwave flux at the top of the model (Watts/m^2)
    • CLDMAS - Convective Cloud Mass Flux (kg/m^2)
    • UAVE - Time-Averaged Zonal U-Wind (m/sec)
    • VAVE - Time-Averaged Meridional V-Wind (m/sec)
    • TAVE - Time-Averaged Temperature (Kelvin)
    • QAVE - Time-Averaged Specific Humidity (g/kg)
    • PAVE - Time-Averaged Surface Pressure - PTOP (mb)
    • QQAVE - Time-Averaged Turbulent Kinetic Energy (m/sec)^2
    • SWGCLR - Net downward clearsky Shortwave flux at the surface (Watts/m^2)
    • DIABU - Total Diabatic Zonal U-Wind Tendency (m/sec/day)
    • DIABV - Total Diabatic Meridional V-Wind Tendency (m/sec/day)
    • DIABT Total Diabatic Temperature Tendency (deg/day)
    • DIABQ - Total Diabatic Specific Humidity Tendency (g/kg/day)
    • VINTUQ - Vertically Integrated Moisture Flux (m/sec g/kg)
    • VINTVQ - Vertically Integrated Moisture Flux (m/sec g/kg)
    • VINTUT - Vertically Integrated Heat Flux (m/sec deg)
    • VINTVT - Vertically Integrated Heat Flux (m/sec deg)
    • CLDFRC - Total 2-Dimensional Cloud Fracton (0-1)
    • QINT - Total Precipitable Water (gm/cm^2)
    • U2M Zonal U-Wind at 2 Meter Depth (m/sec)
    • V2M - Meridional V-Wind at 2 Meter Depth (m/sec)
    • T2M - Temperature at 2 Meter Depth (deg K)
    • Q2M - Specific Humidity at 2 Meter Depth (g/kg)
    • U10M - Zonal U-Wind at 10 Meter Depth (m/sec)
    • V10M - Meridional V-Wind at 10 Meter Depth (m/sec)
    • T10M - Temperature at 10 Meter Depth (deg K)
    • Q10M - Specific Humidity at 10 Meter Depth (g/kg)
    • DTRAIN - Cloud Detrainment Mass Flux (kg/m^2)
    • QFILL - Filling of negative Specific Humidity (g/kg/day)
  • 5.5.3.5. Key subroutines, parameters and files
  • 5.5.3.6. Dos and don’ts
  • 5.5.3.7. Fizhi Reference
  • 5.5.3.8. Experiments and tutorials that use fizhi

5.6. Sea Ice Packages

• 5.6.1. THSICE: The Thermodynamic Sea Ice Package
  • 5.6.1.1. Key parameters and Routines
    • subroutine ICE_FREEZE
    • subroutine ICE_START
    • subroutine ICE_THERM
    • subroutine SFC_ALBEDO
    • subroutine NEW_LAYERS_WINTON
    • Initializing subroutines
    • Diagnostic subroutines
    • Common Blocks
    • Input file DATA.ICE
  • 5.6.1.2. Important Notes
  • 5.6.1.3. THSICE Diagnostics
  • 5.6.1.4. References
  • 5.6.1.5. Experiments and tutorials that use thsice
• 5.6.2. SEAICE Package
  • 5.6.2.1. Introduction
  • 5.6.2.2. SEAICE configuration, compiling & running
    • Compile-time options
    • Run-time parameters
  • 5.6.2.3. Description
    • Compatibility with ice-thermodynamics thsice package
    • Surface forcing
    • Dynamics
    • Viscous-Plastic (VP) Rheology
    • LSR and JFNK solver
    • Elastic-Viscous-Plastic (EVP) Dynamics
    • More stable variants of Elastic-Viscous-Plastic Dynamics: EVP* , mEVP, and aEVP
    • Truncated ellipse method (TEM) for yield curve
    • Ice-Ocean stress
    • Finite-volume discretization of the stress tensor divergence
    • Thermodynamics
    • Advection of thermodynamic variables
    • Key subroutines
    • SEAICE diagnostics
    • Experiments and tutorials that use seaice