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.