**Description
of major subroutines**

To see how
they are called during program execution, see the call tree in
the AGCM flow chart. Subroutine names and the file names almost
always correspond, i.e., subroutine advect resides in a file named
advect.F; note that this is not the case for the subroutines which
perform the load-balanced fourier filtering. Also note that not
ALL of the subroutines that comprise the model code are described
here, please consult comments in the code itself for those subroutines
not described here.

ADVECT

Computes the horizontal and vertical advection of potential temperature
OR water vapor mixing ratio (depending on where it is called).
The horizontal and vertical finite differencing schemes used here
are given in Arakawa and Lamb (1977). In addition, the total increment
(source/sink) to these variables as determined by the physical
parameterizations (see routines in the directory "column_physics")
is added in this subroutine. The values of the prognostic variables
at the interfaces between layers are computed in the routines
thermo (for potential temperature) and water (for water vapor
mixing ratio).

BAL_LD_STRONG

Performs the N-S communications of data required to load-balance
the 'strong' filtering done via FFTs (see Lou and Farrara (1996)).

BAL_LD_WEAK3

Performs the N-S communications of data required to load-balance
the 'weak' filtering done via FFTs (see Lou and Farrara (1996)).

CONTNUTY

Diagnostically determines the vertical velocity in sigma coordinates
using the differencing scheme of Arakawa and Lamb (1977) and Arakawa
andSuarez (1983). Updates the PBL depth, using mass exchanges
between the PBL and the free atmosphere determined by the physical
parameterizations of turbulent mixing in the PBL and mass flux
out of the PBL by cumulus convection. May also limit mass exchanges
if this is necessary to prevent PBL depth from becoming too large
or small.

DRYCNADJ

Adjusts the values of potential temperature (according to the
algorithm of SAR83) in layers in which the vertical profile of
potential temperature has become absolutely unstable (i.e., potential
temperature decreases with height). Also adjusts values of water
vapor mixing ratio and horizontal

momentum in these layers.

EVENTEMP

Computes the values of the potential temperature at the interfaces
between model layers according to the algorithm of Arakawa and
Suarez (1983).

FFTS_1P

Performs a fourier filtering (in longitude) of the variable passed
to it (see Arakawa (1995)). This subroutine is used only when
the code is run in single processor mode.

FFTS_LB_STRONG

Performs a "strong" fourier filtering (in longitude)
for the three variables requiring this filtering (see Arakawa
(1995)). This subroutine receives input and shares data in common
with the subroutines that do the data re-arrangement required
to load-balance the "strong" filtering and does the

filtering using an FFT routine (RFFTMLT).

FFTS_LB_WEAK3

Performs a "weak" fourier filtering (in longitude) for
the three variables requiring this filtering (see Arakawa (1995)).
This subroutine receives input and shares data in common with
the subroutines that do the data re-arrangement required to load-balance
the "weak" filtering and does the filtering using an
FFT routine (RFFTMLT).

FILTERS_FFT

Driver routine for the standard (non-load balanced) strong or
weak fourier filtering when performed using an FFT routine (RFFTMLT).

FILTERS_LB3

Driver routine for the load-balanced "weak" fourier
filtering when three variables are to be "weak" filtered.
This is the default case; potential temperature, water vapor mixing
ratio and potential vorticity are "weak" filtered.

FILTERS_LB4

Driver routine for both the load-balanced "strong" filtering
and the load-balanced "weak" filtering when four variables
are to be "weak" filtered.

GETFILTR

Sets the values of the coefficients to be used in the filtering
when the convolution method of evaluating the filter is used (see
filter_fft flag).

GPOTENTL

Determines the values of the geopotential at the middle of model
layers using the potential temperature at the interfaces between
model layers (see Arakawa and Suarez (1983)).

HYDRO

Driver routine for the dynamics - one execution of the hydro routine
constitutes an advance of the model prognostic variables by one
timestep.

MASSFLUX

Computes the second-order (using a centered differencing) mass
fluxes for use in computing the vertical velocity and enstrophy
conserving advection of potential vorticity (see Takano and Wurtele
1982). These two components (zonal and meridional) of the mass
flux are "strong" filtered (by other

routines, see above).

MASSLFX4

Computes fourth-order accurate mass fluxes (Takano and Wurtele
1982) using the filtered second-order accurate fluxes. Fourth
order mass fluxes are used in the horizontal advection of potential
temperature, water vapor and other trace constituents.

MOMENTUM

Updates the zonal and meridional components of the velocity. This
update is performed as four separate additions: 1) the increment
to the velocity components from the physical parameterizations
(i.e., gravity wave drag, cumulus friction); 2) increment due
to vorticity advection (Takano and Wurtele 1982); 3) increment
due to vertical advection of horizontal velocity (Arakawa and
Lamb (1977); 4) increment due to pressure gradient force (Takano
and Wurtele 1982, Suarez etal. (1983)).

OZONE

Prepares for the second-order vertical advection of ozone mixing
ratio by computing values of the mixing ratio at the interfaces
such that the natural log of ozone mixing ratio is conserved (Arakawa
and Lamb (1977)).

PAVERAGE

Computes the values of pressure thickness of the troposphere (between
PBL top and 100 mb) and the PBL depth at the vorticity, u and
v points (Arakawa and Lamb (1981); values of pressure at predicted
at different spatial locations on the Arakawa "C" grid).

PBLFLUX

Modifies the PBL winds to help prevent the PBL depth from becoming
too small by applying a "friction" (Suarez etal. (1983)).

PGRADF

Computes the zonal and meridional gradients of kinetic energy
and pressure, combining them into one variable for the zonal gradient
and one variable for the meridional gradient (Arakawa and Lamb
(1981), Takano and Wurtele 1982). These variables are "strong"
filtered (by other routines, see

above) and used to update the velocities in the "momentum"
subroutine.

POLARQ1

Evaluates the vorticity at the poles via the circulation theorem
(Arakawa and Lamb(1981), Takano and Wurtele 1982). This computation
requires communication, if there is more than one subdomain in
the longitudinal direction. The calculation is completed in the
routine "polarq2" (see below).

POLARQ2

Completes the calculation of vorticity at the poles begun in "polarq1".

PRESSURE

Computes the pressures at the middle of the layers and also at
the interfaces between layers in the sigma coordinate system (
Arakawa and Suarez(1983), Suarez etal. (1983)).

SMAGUCLA

Computes and adds the increment due to the nonlinear horizontal
diffusion of momentum to the velocity components ( Arakawa (1995),
Smagorinsky(1963)).

STRONG

Driver routine for convolution-based high-latitude 'strong' fourier
filtering.

STRONG_FFT

Driver routine for FFT-based high-latitude 'strong' fourier filtering
(with no load balancing).

STRONG_LB_FFT

Driver routine for load-balanced FFT-based high-latitude 'strong'
fourier filtering.

THERMO

Prepares for the second-order vertical advection of potential
temperature by computing values at the interfaces (Arakawa and
Lamb (1977)) between layers. Definition of the value at the interface
between the PBL and the layer above follows Li and Arakawa (1997).

TPFFT_S

Performs the E-W communications of data required to assembly complete
longitude rows of data for the variables to be 'strong' filtered
via FFTs.

TPFFT_W3

Performs the E-W communications of data required to assembly complete
longitude rows of data for the variables to be 'weak' filtered
via FFTs.

VORTEX

Computes the potential vorticity (Arakawa and Lamb (1981), Takano
and Wurtele 1982); the potential vorticity is 'weak' filtered.

WATER

Prepares for the second-order vertical advection of water vapor
mixing ratio by computing values of the mixing ratio at the interfaces
between layers(Arakawa and Lamb (1977)). Definition of the value
at the interface between the PBL and the layer above follows Li
and Arakawa (1997).

WEAK

Driver routine for convolution-based high-latitude 'weak' fourier
filtering.

WEAK_FFT

Driver routine for FFT-based high-latitude 'weak' fourier filtering
(with no load balancing).

WEAK_LB_FFT

Driver routine for load-balanced FFT-based high-latitude 'weak'
fourier filtering.

CLOUDS

This routine calculates several quantities characterizing cloudiness
including the fractional heating and moistening increments due to
layer cloud instability in the PBL (Suarez etal. (1983)).
COLUMN

The main driver routine for the calls to the routines that compute
the effects of sub-grid scale processes on the grid-scale. This
routine calls column_ucla, which calls the main physics routines
individually.

COLUMN_UCLA

This routines calls the individual routines that perform the computation
of the effects sub-grid scale physical processes. The order of
calculation of the effects of physical processes is as follows:

1.Determination
of cloudiness and PBL stratus layer cloud instability

2.Cumulus convection

3.Moist convective adjustment

4.Large scale precipitation

5.Shortwave radiation

6.Longwave radiation

7.Planetary boundary layer processes

8.Gravity wave drag

9.Ozone photochemistry (optional)

10.Ground hydrology

CUMULUS1

Driver routine
for the cumulus parameterization (Arakawa and Schubert (1974));
this routine calls the routines that make the computations of
the temperature and moisture increments to the grid-scale variables
from sub-grid scale cumulus convection.

CUMULUS2

Driver routine for completing the calculation of increment to
momentum due to sub-grid scale convective processes (Arakawa and
Schubert (1974), Lord et al. (1982)).

FILL_H2O

Adds water vapor from surrounding grid boxes to grid boxes in
which the water vapor mixing ratio has become negative (fills
from below first). Called prior to calling physical parameterization
routines.

GROUNDT

Driver routine for calculation of the ground temperature over
land and sea-ice points, and snow depth.

GWDRAG

Driver routine for the parameterization of orographic gravity
wave drag (Kim and Arakawa 1995, Kim 1996)). Computes increments
to the momentum.

LONGWAVE_H

Driver routine for the Harshvardhan et al. (1987) parameterization
of heating/cooling due to infrared radiative processes.

LSP

Driver routine for the calculation of changes in temperature and
water vapor mixing ratio due to grid-scale supersaturation/precipitation.
This routine uses inputs which have been modified by the cumulus
convection parameterization and moist adjustment process.

MOISTADJ

Driver routine for computation of changes in temperature and water
vapor mixing ratio due to adjustments of the temperature and moisture
profiles to eliminate conditionally unstable layers (Suarez etal.
(1983)). This routine uses inputs which have been modified by
the cumulus convection

parameterization.

PBL

Driver routine for calculation of the planetary boundary layer
(PBL) processes (Suarez etal. (1983)), including the fluxes at
the atmosphere-ocean/land/sea-ice interface and the changes in
the depth

of the PBL, which is the lowest model layer.

SHORTWAV

Driver routine for the calculation of heating due to absorption
of solar radiation (Katayama (1972)).

ZENITH

This routine calculates the cosine of the solar zenith angle.

CLDSLW_UCLA

Computes the absorption of infrared radiation for cloudy grid
boxes (Harshvardhan et al. (1987)).

CLOUD_UCLA

Determines whether a layer is cloudy (100% or 0%) and computes
the increments in temperature and water vapor mixing ratio due
to instability of stratus clouds in the planetary boundary layer
( Li and Arakawa (1997)).

CRUNCH_UCLA

Computes the interactions among the infrared radiation from the
different model layers (Harshvardhan et al. (1987)). Needed to
produce a net heating/cooling rate due to IR radiation.

CUMLUS_UCLA

First step in the parameterization of cumulus convection, prepares
for the real calculation of heating/moistening done in cup_ucla
(Arakawa and Schubert (1974), Lord et al. (1982)).

CUP_UCLA

Determines the interaction of an ensemble of cumulus clouds (sub-grid
scale) with the large-scale environment (Arakawa and Schubert
(1974)). Outputs increments to the temperature, moisture and wind
fields.

GTHYD_UCLA

Computes the ground temperature and snow depth for non-ocean points.

GWDRAG_UCLA

Computes changes in velocity due to the breaking of sub-grid scale
orographically-generated gravity waves (Kim and Arakawa 1995).

LSP_UCLA

Calculates the temperature and moisture changes due to the condensation
and falling to the ground of precipitation.

LWFLUX_UCLA

Computes (via calls to CRUNCH_UCLA) the upward and downward fluxes
of IR radiation (Harshvardhan et al. (1987)).

LWRAD_UCLA

Driver routine for column calculation of heating/cooling due to
IR radiative exchange (Harshvardhan et al. (1987)).

MOMCUM1

First step in computing the increment to the velocities due to
cumulus convection (Arakawa and Schubert (1974), Lord et al. (1982)).

MOMCUM2

Completes the calculation of the increment to the velocities due
to cumulus convection (Arakawa and Schubert (1974), Lord et al.
(1982)).

MSTADJ_UCLA

Calculates an increment to temperature and water vapor mixing
ratio necessary to restore the convective stability of convectively
unstable layers (Suarez et al. (1983)).

NTRAIN_UCLA

Computes the amount of turbulent entrainment of mass into the
planetary boundary layer (Suarez et al. (1983)).

PBL_UCLA

Calls routines (SFLXES_UCLA, NTRAIN_UCLA) to compute surface fluxes
and the turbulent entrainment of mass into the planetary boundary
layer (Suarez et al. (1983)).

QSAT_UCLA

Computes the saturation water vapor mixing ratio for a given input
temperature via a table lookup.

SFLXES_UCLA

Computes the surface fluxes of heat, water vapor and momentum
using a backward implicit scheme (Suarez et al. (1983)).

SWRAD_UCLA

Computes increment to temperature due to absorption of solar radiation
(Katayama (1972)).

UCLADATA

Many physical constants (Rgas, etc.) are set here; some of these
can be over-ridden by specifying the values in the input file.

VQSAT_UCLA

Same as QSAT_UCLA, except it requires as input a 1-D array of
temperatures.

INTEGRATE_AGCM

Advances the simulated time from t1 to t2 by making calls to "timestep".

TIMESTEP

Advances the simulation by one physics parameterization timestep
(this usually involves approximately 10 hydrodynamics timesteps;
Arakawa and Lamb (1977)).

AGCM_INIT2

Driver for most of the initialization tasks including input, and
the initial call to the physics.

AGCM_BCREAD

Reads model boundary condition file (netcdf format).

AGCM_HISTREAD

Read model initial/restart history file (netcdf format).

AGCM_HISTWRITE

Writes model restart histories (netcdf format).

MAIN

Main routine; everything starts here.

ESMCLOCK

Tells the time and reads the calendar.

BC_FOR_SUBDOMAINS[2,3,4]

Driver routine for the nearest neighbor message-passing. Different
incarnations send the boundary data for different numbers of variables
(i.e.,bc_for_subdomains2 sends the boundary data for two variables
with a single set of messages).

CPPINC

Initializes the MPP environment (i.e., assigns and exchanges processor
id's, etc.) and the message-passing software environment (if necessary).

MES3DEW[2,3,4]

Does the actual nearest neighbor message-passing at the east-west
boundaries of the subdomains (called by bc_for_subdomains[2,3,4].
Different incarnations send the boundary data for different numbers
of variables.

MES3DNS[2,3,4]

Does the actual nearest neighbor message-passing at the north-south
boundaries of the subdomains (called by bc_for_subdomains[2,3,4].
Different incarnations send the boundary data for different numbers
of variables.