MCPL(): Run-Script Control of the Module

This module is principally controlled by environment variables and by ASCII tables found in files under standard logical names, according to EDSS/Models-3 conventions. A template for scripts that set these environment variables is available here. The script must deal with three important points:

Description of the MCPL output grids relative to the grids in the MM5 nested-domain system. For a particular output grid and the MM5 nest domain from which it is extracted, this diagram (also available in PostScript) shows how the output grids are described in terms of specification parameters EM_I0 and EM_J0 for the grid offsets, and EM_NCOLS, EM_NROWS, and EM_NTHIK for output grid dimensioning.
NOTE that
- Air quality modelers tend to think in terms of cell-volume values rather than point-values. The diagram is drawn from that point of view.
- For variables which require decoupling of dot point values (e.g., wind components, or wind speed), the output grid must be strictly smaller than the MM5 grid--it must not contain the first or last horizontal column nor row of the MM5 grid. MCPL will decide on a domain-by-domain basis whether this condition is satisfied,
- If you want to output air quality model grid-boundary data structures, the output grid must be strictly smaller than the MM5 grid, also.
Specification of output file characteristics, particularly which files are produced, which subsets of the set of all possible variables for each file are actually output, and what are the starting date, time, and timestep for each file.
Specification of the output files themselves (i.e., what directory path and what actual file name to use, associated with a standard set of "logical names" which are independent of the particular directory structure and run being executed), and whether the files are "volatile" (i.e., can be analyzed while MM5 is still running or not). This takes the form setenv <standard logical name> <full file name> [-V]
where the optional "-V" indicates that the file is volatile. Note that if you want to analyze the output while MM5 is still running, your script must declare the output files to be volatile.

Environment variables that control these file characteristics are in the form of comma-delimited lists, with one value per output grid, and are set (if you use csh) in the following fashion (where we assume 4 output grids, FOO is an arbitrary integer-list-valued environment variable, and BAR is an arbitrary strign-list-valued environment variable):
setenv FOO '1,2,7,8' setenv BAR 'QUX,ZOP,GAK,MUD'
The list of these environment variables, together with their meanings, is given below.

MCPL_SDATE contains a comma-delimited list of the starting Julian dates for all output grids, formatted YYYYDDD, for MCPL() I/O API output files (with default value taken from the current wall-clock century and MM5's input variable MDATE (which is formatted YYMMDDHH); if only one date entry is specified, it is used for all output grids. Note that MM5v2 suffers from the Year-2000 problem (or more generally, a century-problem): it only stores the 2-digit year mod 100 internally). MCPL attempts to fill in the century digits from the current wall clock. With MM5V2, the default behavior leads to errors when the simulation century and the wall-clock century are not the same.

MCPL_STIME contains a comma-delimited list of the the starting times for all output grids, formatted HHMMSS, for MCPL() I/O API output files (with default value determined by MM5's MDATE, which has an hours field only). If only one time entry is specified, it is used for all output grids.

MCPL_TSTEP contains a comma-delimited list of the time steps for all output grids, formatted HHMMSS, for MCPL() I/O API output files (with default value determined by MM5's TAPFRQ). If only one time step entry is specified, it is used for all output grids.

GRIDDESC logical name for the Grid Description File. (Its value is the path-name for this file).

CRDNAM contains the coordinate system name for the coordinate system used by the model, as found in the GRIDDESC file. Needed only if MCPL will create GRIDDESC.

EM_OUTGRIDS contains a list of MM5 domains into which the output grids fit.
These need to be in increasing order, e.g.."1,1,2,2,2,3,3" to denote that the first two output windows are from MM5 domain 1, three more are from MM5 domain 2, and the last two are from MM5 domain 3.
All other list-style environment variables use the same subscripting as EM_OUTGRIDS. There may be more than one output grid per MM5 domain. If this environment variable is not present, MCPL() assumes one output grid per MM5 domain

OUTGNAMES contains a comma-delimited list of root grid-names, used to construct the corresponding grid names in GRIDDESC. Each root name X will generate two GRIDDESC records, for the grids X_CRO and X_DOT, respectively the cross-point and dot-point output grids for that grid. Note that these root names can be at most 12 characters because of the necessity for adding tails _CRO or _DOT for the respective cross-point and dot-point grid names in GRIDDESC.

CRONAMES contains a comma-delimited list of cross-point grid-names, used to construct the corresponding grid names in GRIDDESC. CRONAMES is optional; these names override the names generated from OUTGNAMES (above), if CRONAMES is present

DOTNAMES contains a comma-delimited list of cross-point grid-names, used to construct the corresponding grid names in GRIDDESC. CRONAMES is optional; these names override the names generated from OUTGNAMES (above), if CRONAMES is present

EM_I0 contains a list of MM5-domain (I) row-offsets for the output grids relative to the domain from which they are taken. Offset 0 means that the output grid has the same starting row as its MM5 domain.
Entries in the list should be separated by commas, and the list should be quoted in the setenv statement that defines it.
Needed only if MCPL will create GRIDDESC.

EM_J0 contains a list of MM5-domain (J) column-offsets for the output grids relative to the domain from which they are taken. Offset 0 means that the output grid has the same starting row as its MM5 domain.
Needed only if MCPL will create GRIDDESC. Must have the same format and number of entries as EM_I0.

EM_NROWS contains a list of row dimensions for the output grids.
Needed only if MCPL will create GRIDDESC. Must have the same format and number of entries as EM_I0.

EM_NCOLS contains a list of column dimensions for the output grids.
Needed only if MCPL will create GRIDDESC. Must have the same format and number of entries as EM_I0.

EM_NTHIK contains a list of boundary thickness dimensions for the output grid.
Needed only if MCPL will create GRIDDESC. Must have the same format and number of entries as EM_I0. Needed (but unused) if not creating AQM-style boundary-files.

MCPL_KFTHIK contains a list of maximum number of KF-cloud events per cell.
Needed only if MCPL will create KF cloud-event files. If there are fewer entries in this list than there are output windows - particularly if there is only one entry, will use the last list-entry for all subsequent output windows.

MCPL_PRESF contains a comma-delimited list of the pressure full-levels for the PRES_CRO_3D and PRES_DOT_3D output files, if these are produced. If this variable is not set but the files are being produced, there are 18 default levels with values going from 1025.0E2 down to 175.0E2 Pascals, in intervals of 50.0E2 Pascals (so that the half-levels run 1000.0E2, 950.0E2, ..., 200.0E2 Pascals).

GB2_VARS contains either NONE if no GRID_BDY_2D file is desired, or the logical name for an input file containing an ASCII table of names of output variables requested in this MM5 run for file GRID_BDY_2D, listed one name per line. A master version of this file, which assumes that the user wants to output the entire set of potentially available variables, is available here. You may want to use your browser's "save link as" capability (Shift-MouseButton1 for Netscape®) to save a copy of it.

GB3_VARS file of output variables requested for GRID_BDY_3D, or NONE. Master version available here.

GC2_VARS file of output variables requested for GRID_CRO_2D, or NONE. Master version available here.

GC3_VARS file of output variables requested for GRID_CRO_3D, or NONE. Master version available here.

GB2_VARS file of output variables requested for GRID_DOT_2D, or NONE. Master version available here.

MB2_VARS file of output variables requested for MET_BDY_2D, or NONE. Master version available here.

MB3_VARS file of output variables requested for MET_BDY_3D, or NONE. Master version available here.

MC2_VARS file of output variables requested for MET_CRO_2D, or NONE . Master version available here.

MC3_VARS file of output variables requested for MET_CRO_3D, or NONE. Master version available here.

MD3_VARS file of output variables requested for MET_DOT_3D, or NONE. Master version available here.

PC3_VARS file of output variables requested for PRES_CRO_3D, or NONE. Master version available here.

PD3_VARS file of output variables requested for PRES_DOT_3D, or NONE. Master version available here.

SCENFILE the "scenario description file," which contains an up-to-60-line ASCII text scenario description with 80 characters per line. The contents of this file will be copied into all the output file headers for tracking/auditing purposes.

LOGFILE the log file, to which is written the working log of the current program. If LOGFILE is not available as specified above, the working log defaults to "stdout" (UNIT 6).
The following are the set of standard logical-file-name templates for MCPL's output files. Actual file names take the form <base-file-name>_G<output-grid-number>, where the grid number runs 0,1,2,... through the output grids for MCPL, e.g., for the 2-D cross-point time-independent output file on the first output grid, your script might have:
setenv GRID_CRO_2D_G0 /data/my-name/my-run-date/gc2_g0.ncf -V
(The "-v" indicates that this file is "volatile," i.e., that it may be accessed/analyzed/visualized while the MM5 run is still in progress.
For any file on any grid, you may turn that file off by setenv <logical-name> NONE.

GRID_BDY_2D_G<grid> logical name for output file, or NONE

GRID_BDY_3D_G<grid> logical name for output file, or NONE

GRID_CRO_2D_G<grid> logical name for output file, or NONE

GRID_CRO_3D_G<grid> logical name for output file, or NONE

GRID_DOT_2D_G<grid> logical name for output file, or NONE

MET_BDY_2D_G<grid> logical name for output file, or NONE

MET_BDY_3D_G<grid> logical name for output file, or NONE

MET_CRO_2D_G<grid> logical name for output file, or NONE

MET_CRO_3D_G<grid> logical name for output file, or NONE

MET_DOT_3D_G<grid> logical name for output file, or NONE

PRES_CRO_3D_G<grid> logical name for output file, or NONE

PRES_DOT_3D_G<grid> logical name for output file, or NONE

MET_KF_1D_G<grid> logical name for output file, or NONE

MET_KF_3D_G<grid> logical name for output file, or NONE

Back to MCPL Contents