3 Physics Package

3.1 Overview

For completeness, we repeat some of the discussion of physics package interfaces given in the document Physics and Chemistry Interface Design. We use the term ``physics package'' to refer to either a physics or a chemistry package. The specific interfaces to the current CAM physics packages are also described. In the simplest case all that a user must do to be able to run the CAM with a physics package that replaces a standard CAM package is to write ``wrapper'' code that implements the interface specified here. This satisfies requirement PHY04 for swappable physics and chemistry packages.

The generic interface comprises methods to initialize the package, and to run the package (run methods) for a model timestep. The run methods are called from the CAM physics module which is responsible for determining the sequence and the time or process splitting of the individual processes. The interface is designed to be uniform regardless of the nature of the package's internal timestep (forward, backward, time or process split), and to be as flexible as possible, without imposing significant computational or memory overhead.

A physics package will be easy to wrap if it follows the coding standards of [ref]. The basic philosophy behind the package coding standards is that a physics package should only be responsible for doing a calculation on the caller's computational state. The responsibilities of I/O and parallelization are left to the model infrastructure. In the CAM the physics package interface is called below the level where parallelization details are implemented. The I/O services are provided to the physics package via use association of model utilities in the interface module.

3.2 Requirements

The responsibility of each physics package is to perform a calculation on the current model state, and to return a tendency representing how the process changes the state in a single model timestep. Responsibility for updating the model state rests with the CAM physics module. This allows for a consistent method of controlling whether the physical processes are treated in a time or process split manner. All packages must be able to record their net forcing on the output history files. This is necessary for diagnostic purposes. It follows that all packages must calculate a tendency, regardless of whether they use a forward or backward step internally. These requirements, which are enforced by the interface design, can be summarized:

• Physics packages must not change the model state.
• Physics packages must return tendencies for any model state variables that they wish to change.

The following set of requirements are not enforced by the interface, but must instead be enforced by the mathematical formulation and the algorithm design of each physics parameterization.

• All column physics packages are required to conserve the vertical integral of:
  • the mass of each constituent (including sources and sinks)
  • momentum (including boundary forces)
  • total energy (including boundary fluxes)
  • dry static energy (including boundary fluxes and kinetic energy dissipation)

The interface design requires that each column physics package which produces a mass, momentum, or energy tendency must provide any boundary forces or fluxes associated with those tendencies so that the appropriate balance can be checked in the physics module.

3.3 Design

The interface is implemented as a Fortran 90 module. Providing an interface that can be used in the CAM without having to modify CAM source code requires that the interface routines have the same names as the appropriate standard CAM versions. Those names are given in section which describes the specific CAM interfaces.

Fortran 90 template for the interface module:

module cam_pkg_interface
   use precision,     only: r8
   use ppgrid,        only: pcols, pver, ppcnst
   use physics_types, only: physics_state, physics_ptend, physics_buffer
   use surface_types, only: surface_state
   use physconst,     only: ...
   use history,       only: addfld, outfld, physics_decomp
   use constituents,  only: cnst_add, advected, not_advected, cnst_name
   use time_manager,  only: ...
   use pressure,      only: prefm, prefd, prefi
   use phys_grid,     only: get_rlat_all_p, get_rlon_all_p
   use pkg,           only: pkg_init, pkg_run
   :
   implicit none
   private
   save
   :
   public ::        &! Interface methods
      cam_pkg_cnst, &! register package constituents
      cam_pkg_init, &! package initialization
      cam_pkg_run    ! package driver
   :
! Public data for namelist input
   :
! Private package data
   :
contains

   subroutine cam_pkg_cnst()
      :
! Register constituents.
      :
   end subroutine cam_pkg_cnst

   subroutine cam_pkg_init( ... )
      :
! Set up and call pkg_init.
      :
   end subroutine cam_pkg_init

   subroutine cam_pkg_run(lchnk, state, surf, pbuf, ptend)
      implicit none
      integer,             intent(in)  :: lchnk
      type(physics_state), intent(in)  :: state
      type(surface_state), intent(*)   :: surf
      type(physics_buffer),intent(*)   :: pbuf
      type(physics_ptend), intent(out) :: ptend
      :
! Set up and call pkg_run.
      :
   end subroutine cam_pkg_run

end module cam_pkg_interface

The input is a derived type called the PHYSICS_STATE containing $u, v, T, s, p, q$, and $C$ on the physics grid (identified by chuck ID). If the package works on some other variable like $\theta$, the package does the conversion. The output is a derived type, PHYSICS_PTEND containing the net source terms for the prognostic variables expressed as tendencies of $u, v, s, q$, and $C$.

The physics packages work on an arbitrary collection of atmospheric columns indexed from 1 to ncols. It is not assumed that these columns constitute a continguous set of longitudes or that they are all on the same latitude. However, the latitude and longitude coordinates of any given set of columns are available to the package.