1 Atmospheric Driver

The atmospheric driver sets up the initializations of the atmospheric component subpackages. It also reads the namelist option and control information for the simulation and couples the dynamics and physics packages.

1.1 Control Information

The CAM model can be run in stand-alone mode or coupled with other CCSM components. Both initial runs and restart runs are specifiable through the control input. The coupling with the land model, either directly or through the coupler, is a configuration option of the physics package.

Code Template for the Atmospheric Model Driver

use CAM_GComp, only: CAM_init, CAM_run, CAM_final

CAM_init ( cam_import, cam_export, clock )
CAM_run  ( cam_import, cam_export, clock )
CAM_final( cam_import, cam_export, clock )

cam_import and cam_export are ESMF import and export states respectively, and clock is a ESMF clock with a start-time, stop-time, and time-step. The import state are the set of fields that the CAM component needs to run, and, the export state are the list of fields that the CAM component can provide to another component it is linked to.

1.2 Initialization

Initialization of the packages occurs in CAM_INIT which calls DYN_INIT and PHYS_INIT. The initial conditions and boundary conditions of the prognostic variables are handled in DYN_INT while, non-advected tracers and other data required by the physcial parameterizations are initialized in PHYS_INIT. Finally, the information required for the coupling of the physics and dynamics packages and the initialization of the 'communicator' are set. The different phases of the initialization of sub-packages follows a prescribed order. First dimension and control information are processed, then initial conditions are read and boundary data initialized. The following assumptions apply about the order of the initialization phase.

1. The history and the coupling package must pre-initialize to allow all other packages to register in their initialization.
2. The history package allows calls to ADDFLD during physics and dynamics initialization.
3. The coupling package allows calls register each package and to add USES and PROVIDES ports during physics and dynamics package initialization.
4. The dynamics initialization determines model resolution.
5. The CCSM component model coupler and the land surface model are coupled to the physics package directly and not through the CAM driver. In the case of CAM standalone mode with a land model, coupling occurs through a PL_COUPLING module.

CAM Initialization

initialize control
initialize history and dp_coupling for registration of packages and ports
initialize dynamics(initial_conditions, boundary_conditions, restart)
initialize physics(lnd and cpl,non-advected tracers, boundary_conditions)
initialize history
initialize dp_coupling for communicators

1.3 CAM_run

The CAM_run (formerly known as STEPON) method controls the time stepping of the model and calls the physics and dynamics packages and DP_COUPLING. CAM_run enforces a standard interface, by encapsulating state and tendency information in derived types. This design implements Requirement DYN03.

An option of the dynamics is if the dynamics is first or if the physics are first. The time loop in CAM_run reflects this difference. A query method asks the dynamics if it is first or not, and depending on the The time loop continues to iterate until the control finds the simulation to be complete.

time loop :  do while (.not.done)

   if ( dycore_is_first() ) then

      dyn_run(dyn_state, dyn_tend, dyn_buffer, dtime) 

   end if

   d_p_coupling(dyn_state, phys_state)

   phys_run(phys_state, phys_tend, pbuf, dtime) 

   p_d_coupling(phys_tend, dyn_tend) 

   if ( .not. dycore_is_first() ) then

      dyn_run(dyn_state, dyn_tend, dyn_buffer, dtime) 

   end if

   history_write

   restart_write
     
end time loop

Notes

1. The dynamics package for Eulerian Spectral and Semi-Lagrangian Spectral use a process split interface while the Finite Volume Lin-Rood dynamical core uses a time split interface.
2. The p_d_coupling step in the time split interface also updates the dynamics state.

1.3.1 Process and time splitting

The general prediction equation for a generic prognostic variable $\psi$ is

$${\partial \psi \over \partial t} = D + P \;, \eqno(1)$$

where $\psi$ denotes temperature or horizontal velocity components. The dynamical core component is denoted $D$ and the physical parameterizations $P$. We consider two ways to couple $D$ and $P$. The first we denote Process Split and approximate (1) by

$$\psi^{n+1} = \psi^{n-1} + 2\Delta t D(\psi^{n-1}) + 2\Delta t P(\psi^{n-1}) \;. \eqno(2)$$

The second we denote Time Split and approximate (1) by

$$\psi^* = \psi^{n-1} + 2\Delta t D(\psi^{n-1}) \;, \eqno(3)$$

$$\psi^{n+1} = \psi^* + 2\Delta t P(\psi^*) \;. \eqno(4)$$

The distinction is that in the Process Split approximation the calculations of $D$ and $P$ are both based on the same data $\psi^{n-1}$, while in the Time Split approximations $D$ and $P$ are calculated sequentially, each based on data produced by the other. We have employ a three-time-level notation in (2)-(4) to be consistent with the current CAM, in which the spectral transform semi-implicit dynamical core also depends on $\psi^{n}$ and $\psi^{n+1}$. We leave this aspect implied. Similarly, in CAM the parameterizations have a mild dependency on $\psi^{n}$. However, since the numerical characteristics of the parameterizations are like those of diffusive processes, it is more appropriate to approximate them as forward or backward approximations. Any use of $\psi^{n}$ is for linearizing coefficients and can be replaced with $\psi^{n-1}$. Egns. (2)-(4) would also apply to two-time-level approximations with $n$-1 replaced by $n$ and $2 \Delta t$ by $\Delta t$.

The parameterization package can be applied to produce an updated field as indicated in (4). Thus we can write (4) with an operator notation

$$\psi^{n+1} = {\bf P}_{2 \Delta t}\left(\psi^*\right) \;. \eqno(5)$$

The Process Split equation (2) can also be written in operator notation as

$$\psi^{n+1} = {\bf D}_{2 \Delta t}\left(\psi^{n-1}, {{\bf P}... ...t}(\psi^{n-1})-\psi^{n-1}\over 2 \Delta t}\right) \;, \eqno(6)$$

where the first argument denotes the prognostic variable input to the dynamical core and the second denotes the forcing rate from the parameterization package. With this notation the Time Split system (3) and (4) can be written

$$\psi^{n+1} = {\bf P}_{2 \Delta t}\left({\bf D}_{2 \Delta t}\left(\psi^{n-1},0\right)\right) \;. \eqno(7)$$

Or as above with $(n-1)$ replaced by $(n)$ and $2 \Delta t$ by $\Delta t$

$T_{s \rightarrow u}$, transform staggered to unstaggered grid

$T_{u \rightarrow s}$, transform unstaggered to staggered grid

Basic time steps are described below.

Assumptions:

• Tendencies on history file are not necessarily what produced state variables on history files, e.g. to calculate budgets must outfld state after dynamics (or physics for L-R)

• Do not need time-filtered data in history file

• Separate block of code to put initial data on history file

1.3.2 Three-time-level Eulerian spectral transform

Given

$${\bf V}^{n-1},~~T^{n-1},~~q^{n-1}$$

$${\bf V}^{n},~~T^{n},~~q^{n}$$

Calculate parameterization (using $t^{n}$)

$${\bf P}_{2 \Delta t}\left(\psi^{n-1}\right)$$

For process split parameterizations the time should be $t^{n}$. For time split, which is conceptually what is being done to create the state variables for history tape, the time should be $t^{n-2}$. However, since time only enters the radiation, it is ok for the current parameterization suite. However, if radiation went before convection, it must be considered.

outfld state $\left({\bf P}_{2 \Delta t}\left(\psi^{n-1}\right)\right)$ after convection

outfld (parameterization tendencies)

Calculate dynamics

$$\psi^{n+1} = {\bf D}_{2 \Delta t}\left(\psi^{n-1}, {{\bf P}_{2 \Delta t}(\psi^{n-1})-\psi^{n-1}\over 2 \Delta t}\right)$$

time filter ($\psi^{n}$)

outfld (dynamical tendencies)

wshist (if $t^{n-1}$ = desired time)

write restart

1.3.3 Two-time-level semi-Lagrangian spectral transform

Given

$${\bf V}^{n-1}, {\bf V}^{n},~~T^{n},~~q^{n}$$

Calculate parameterization (using $t^{n+{1 \over 2}}$)

$${\bf P}_{\Delta t}\left(\psi^{n}\right)$$

(same issue as with three-time-level Eulerian above, except time levels are $t^{n+{1 \over 2}}$ and $t^{n-{1 \over 2}}$ here.

outfld state ( ${\bf P}_{\Delta t}\left(\psi^{n}\right)$) after convection

outfld (parameterization tendencies)

Calculate dynamics

$$\psi^{n+1} = {\bf D}_{\Delta t}\left(\psi^{n}, {{\bf P}_{\Delta t}(\psi^{n})-\psi^{n}\over \Delta t} \right)$$

Using ${\bf V}^{n+{1 \over 2}} = {3 \over 2}{\bf V}^{n} -{1 \over 2}{\bf V}^{n-1}$ for trajectory

outfld (dynamical tendencies)

wshist (if $t^n$ = desired time)

write restart

1.3.4 Lin-Rood

Given

$${\bf V}_s^{n},~~T^{n},~~q^{n}$$

Calculate dynamics

$$\psi_s^{*} = {\bf D}_{\Delta t}\left(\psi_s^{n},0\right)$$

outfld (dynamical tendencies)

$${\bf V}^{*} = T_{s \rightarrow u}\left({\bf V}_s^{*}\right)$$

Calculate parameterization (using $t^{n+{1 \over 2}}$)

$$\psi^{n+1} = {\bf P}_{\Delta t}\left(\psi^{*}\right)$$

outfld state $\left({\bf P}_{\Delta t}\left(\psi^{*}\right) {\rm ~~or~~} {\bf V}_s^{*} + \Del... ...\Delta t}\left({\bf V}^{*}\right) - {\bf V}^{*} \over \Delta t}\right) \right)$ after convection

outfld (parameterization tendencies)

$${\bf V}_s^{n+1} = {\bf V}_s^{*} + \Delta tT_{u \rightarrow s... ...\left({\bf V}^{*}\right) - {\bf V}^{*} \over \Delta t}\right)$$

wshist (if $t^{n+1}$ = desired time)

write restart

1.3.5 Lin-Rood (alternative)

Given

$${\bf V}_s^{n},~~T^{n},~~q^{n}$$

$${\bf V}^{n} = T_{s \rightarrow u}\left({\bf V}_s^{n}\right)$$

Calculate parameterization (using $t^{n-{1 \over 2}}$)

$$\psi^{*} = {\bf P}_{\Delta t}\left(\psi^{n}\right)$$

outfld state $\left({\bf P}_{\Delta t}\left(\psi^{n}\right) {\rm ~~or~~} {\bf V}_s^{n} + \Del... ...\Delta t}\left({\bf V}^{n}\right) - {\bf V}^{n} \over \Delta t}\right) \right)$ after convection

outfld (parameterization tendencies)

Calculate dynamics

$$\psi_s^{n+1} = {\bf D}_{\Delta t}\left(\psi_s^{*},0\right)$$

outfld (dynamical tendencies)

wshist (if $t^n$ = desired time)

write restart

Possibly not desirable because analysis based on $\left(\psi^{n}\right)$ not available before dynamics produces $\left(\psi^{n+1}\right)$

1.4 Physics and Dynamics Coupling

The DP_COUPLING interface module supplies routing information, routers and the map between index spaces of decomposed grids. In addition it calls transformation and update routines of the dynamics and physics packages that effect changes of variables, regridding state and tendency fields and updating state for timesplit dynamical cores. This design implements Requirement DYN02, DYN03 and DYN04.

The primary task of DP_COUPLING is to effect the transformation of data structures from the dynamics block decomposition to and from the physics chunk decomposition. Thus it must have access to the DYN_GRID and PHYS_GRID modules. The data transpose or regridding takes into account load balanced maps from the physics package and the assignment of block and chunk sizes from the coupled sizes in order to effect an effecient message passing and data movement method.

DP_COUPLING module also manages the interfaces for external components that specify what a component is, how it is registered and the interface to other functions offered by a framework. The two frameworks we are specifically designing for are the Earth System Modeling Framework (ESMF) and the Common Component Architecture (CCA). Since neither of these are mature at this writing we must leave place holders that will be adapted at a later date. However, the basic outlines are known.