m3tools Programs M3CPLE and M3INTERP


    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.


The M3CPLE program extracts all variables for a specified time step sequence from one I/O API file, infile, copies them or optionally interpolates them bilinearly to a new grid, and writes them to a different I/O API file, outfile, under the optional control of a synchfile. Any combination of physical or virtual files is supported. The output time step sequence must be a subsequence of the input file's time step sequence.
Note that synchfile should be 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:

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:

Previous: M3COMBO

Next: M3FAKE

Up: Related Programs

To: Models-3/EDSS I/O API: The Help Pages