setenv <synchfile> <path name> or "NONE"
setenv <infile> <path name>
setenv <outfile> <path name>
setenv GRIDDESC <path name>
setenv SCALEFAC <scaling factor> [1.0]
[m3cple | m3interp] <and respond to the prompts>
where infile, outfile, and the optional
synchfile are the logical
names of the input and output files. GRIDDESC
is needed only if M3CPLE is doing a grid-to-grid
interpolation rather than a copy operation.
NONE except in the
case of coupled (cooperating-process-parallel) modeling systems.
Note that repeated copy-operations may be used to concatenate
multiple files that have the same grid and set of variables:
for example, if FILE1 has hourly data from 2018017:00 through
2018018:00 and FILE2 has hourly data from 2018018:00
through 2018019:00, a M3CPLE using FILE2 as
infile and FILE1 as outfile may be
used to copy the 2018018:01-2018019:00 data from FILE2 to
FILE1. Repeated runs of this sort may be used to construct
month-, year-, or even decade-long files from a (large) set of
single-day files.
Program M3INTERP acts like M3CPLE except that it
uses INTERP3() to extract a
possibly-nonaligned time step sequence from the file, rather than only a
subsequence of time steps found in the file.
Note that for
M3INTERP, almost always the synchfile should be
NONE.
The normal use of M3CPLE with a synchfile is to fit into a system of coupled models exchanging data via the I/O API coupling mode, and extract/interpolate data either from a virtual file to a physical file, or vice versa. Grid-to-grid interpolation is only available for files of type GRDDED3; the copy operation is available for files of type GRDDED3, CUSTOM3, BNDARY3; in any case, all the variables must be of basic data type M3REAL.
For interpolation to be meaningful, the output resolution should be finer than the input resolution, else you should not be using any interpolation, but rather should be using some sort of aggregation algorithm (possibly using a matrix from program MTXBUILD in conjunction with program MTXCPLE).
For I/O API-3.2 or later, versions of M3CPLE for
Oct. 21, 2021, a new re-scaling option was added to this program,
primarily for use with SMOKE gridded emissions data (which uses
non-interpolatable, non-MKS units of the form mass per unit time
per grid-cell, controlled by environment variable
SCALEFAC. By default, the scaling factor is 1.0; however,
for emissions data the scaling factor should be the ratio of the output
cell-area to the input cell-area.
For example with a 12KM input emissions grid and a 4KM output
emissions grid, the scaling factor should be the value of
(4.0/12.0)⊃2), i.e., you should
setenv SCALEFAC 0.111111111
For the I/O API-3.2 or later, all grid-to-grid interpolations involving I/O API supported map projection types are supported. For the I/O API-3.1 or earlier versions of the program, the list of supported coordinate system conversions for interpolation is the following:
"SAME": <input coordinate system type> =
<output coordinate system type>
Before you run the program, you need to assign logical names to the physical file names of both files and to the GRIDDESC file, according to Models-3 conventions, using the operation
"setenv <lname> <pname>"
The program will prompt you for the logical names
you have chosen for the input files, for the output grid, and for
the time step sequence to process. To do a copy operation instead
of a grid-to-grid interpolation, respond SAME to the
prompt for output grid (the default response). The prompts have
default responses indicated in square brackets [LIKE
THIS], which can be accepted by hitting <RETURN>.
The specification of starting date and time, target date and time,
and number of time step records for the run follow Models-3
date and time conventions.
If you want to run this program in batch mode (from a script), the recommended way to develop the script is to run the program once interactively noting the pattern of responses to prompts which generate the particular analysis you want. The pattern of responses then becomes either a command-input file which you may redirect into the program in the script, or may become a "here-document" fed into the execution by the script.
Requires Fortran-90 for compilation. Source code for program
m3cpleis available under the GNU
GPL License, Version 2, and can be downloaded here
from CMAS or here
from GitHub.
See Also:
To: Models-3/EDSS I/O API: The Help Pages