setenv <infile A> <path name>
setenv <infile B> <path name>
setenv <outfile> <path name>
m3pair [<infile A> <infile B> <reportfile>]
<and respond to the prompts>
where infile A and infile B are the
logical names of the input files,
and outfile is the logical name of the output file
to which the ASCII pairing is printed.
The M3PAIR program constructs an ASCII file of
value-pairs for a pair of variables
from a user-specified pair of GRIDDED
Models-3 files (say "infile A" and
"infile B"). The files must use the same
grid in order for the program to
perform the comparison operations. The comparison takes values
from a user-selected window into the common grid, defined in terms
of column, row, and layer subscript ranges; the default window is
the entire grid.
Note that file B can be the same as file A; this allows you to pair variables O3 and NO2 from the same file, for example, or to pair NO2 between two successive hours or days within that file.
By default, the program finds the common-denominator
time step, and for each common time step, starting at the beginning of
both files, constructs paired output for variable-A and variable-B
for a user-selected window into the (common) grid. In the
most frequently expected application, both files will have the same
timestep, duration, starting date and time, and set of variables;
M3PAIR will then compare two variables, one from each
file, for all time steps. In a more extreme example, if file A is
time-independent with variables V, etc., and file B is time dependent
starting at (1988200,000000) with variable W, etc., then M3PAIR
might compare V from file A with all time steps of W from file B.
Before you run the program, you need to assign logical names to the physical file names of all three files, according to Models-3 conventions, using the operation
"setenv <lname> <pname>"
The program will prompt you for the needed logical names
you have chosen for the input files, and then extensively for the options
to choose; the prompts will have default responses which can be accepted
by hitting <RETURN>. The specification of starting date and time,
and duration for the analysis follow Models-3
date and time conventions.
Note that the set of pairings which can be performed by one execution of M3PAIR is quite complex and context-dependent (being determined by the files being compared). 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 is redirected into the program in the script, or becomes a "here-document" fed into the execution. The following is an excerpt of a script which does the default pairing on the first variable from each of /tmp/myfile.A and /tmp/myfile.B, using the here-document approach:
...
setenv FOO /tmp/myfile.A
setenv BAR /tmp/myfile.B
setenv QUX /tmp/myfile.C
m3pair FOO BAR QUX << !DONE
1
1
!DONE
...
Source code for program m3pairis available
under the GNU GPL License, Version 2,
and can be downloaded here from CMAS or
here from GitHub.
To: Models-3/EDSS I/O API: The Help Pages