The BAMS/EDSS/Models-3 I/O API: User Manual
This web page is under construction.
As a matter of fact ALL web pages are under construction
whether they admit it or not.
--Found on the web page of Do Wong Chu
These pages are All Browser Enhancedtm.
There are absolutely no <BLINK>ing text,
unnecessary and ill-considered <TABLE>s nor
<FRAME>s, nor obnoxious <FONT>
COLORs, SIZEs, or FACEs
at this <CENTER>, nor are there in-line
<IMAGE>s that take forever to load.
Please report any problems to the
author Carlie Coats
(carlie.coats@baronams.com).
This hyperdocument describes recent (second and third) versions
of the I/O API. Both the original working prototype and this
version are implemented on top of
netCDF
, (c) 1993 University
Corporation for Atmospheric Research . NetCDF provides an
application- and machine-independent interface to self-describing,
multidimensional scientific data. It supports an abstract view of
scientific data as a collection of named variables and their
attributes, and provides access to data that is faithful to the
abstraction.
Back to Contents
Back to Contents
Back to Contents
Back to Contents
-
Logical Names:
environment variables and "setenv"
-
Standard environment variables:
LOGFILE, SCENFILE, EXECUTION_ID, GRIDDESC, PROMPTFLAG
-
Grids and Coordinate Systems:
both horizontal and vertical
-
Dates and Times and Time-increments:
integers YYYYDDD:HHMMSS
-
Calling from Fortran:
Just do it.
-
Calling from C:
(but use f77 to link the ".o" files)
-
Files:
Variables, Layers, and Time Steps
-
Files:
NetCDF and native-binary disk files, PVM-mailbox
Coupling-Mode virtual "files",
and memory-resident buffered virtual
"files".
Back to Contents
-
DICTIONARY:
file structure repository
-
CUSTOM:
user-defined structure
-
GRIDDED:
2D or 3D gridded data
-
BOUNDARY:
boundary values for 2D or 3D gridded data
-
ID-REFERENCED:
e.g., observations, county-aggregations,...
-
PROFILE:
special type for rawinsonde data
-
GRID-NEST:
nest of 2D or 3D grids of data
-
SPARSE MATRIX:
uses "skyline-transpose" representation
Back to Contents
-
FDESC3:
file description data structures
-
IODECL3:
declarations and usage comments for I/O routines
-
PARMS3:
"magic number "tokens and dimensioning parameters
Back to Contents
-
CHECK3:
is <timestep> available for
<variable> from <file>?
-
CLOSE3:
close and flush <file>
-
DDTVAR3:
compute time derivative of <variable> from
<file>
-
DESC3:
describe <file>
-
FILCHK3:
check a file for consistency with user-supplied
set of file type and dimensions
-
INIT3:
start up I/O API; return log-file unit
-
INTERP3 and INTERPX:
interpolate <variable> from
<file> to <time>,
with windowing to user-selected column, row, and layer
ranges for
INTERPX()
-
IOPARMS3:
return dimensioning parameters from INCLUDE-file
PARMS3.EXT
to allow consistency checks in model-level code.
-
KFINDX:
reads the event index for the indicated cell from the
indicated <KF
event file>.
-
KFOPEN:
open the indicated
<KF event
file> for <mode / status>,
using <file
description> to create it, if necessary.
-
KFREAD:
reads data for the specified variable at the specified
event, along with its grid location, starting date,
starting time, and duration from the indicated
<KF
event file>.
-
KFWRITE:
writes the specified event data for the specified cell,
starting date, starting time, and duration to the specified
<KF
event file>, and return the corresponding
event number.
-
OPEN3:
open <file> for <mode / status>,
using <file
description> to create it, if necessary
-
READ3:
read <timestep> of <layer>
of <variable> from <file>
-
READ4D:
read <time step sequence > of
<layer> of <variable>
from <file>
-
SHUT3:
shut down I/O API; flush files to disk
-
WRITE3:
write <timestep> of
<variable> to <file>
-
WRITE4D:
write <time step sequence > of
<variable> to <file>
-
XTRACT3:
read <window> of <timestep> of
<variable> from <file>
-
FILCHK3:
Check that <file> has the expected
(user-supplied-argument) file-type and dimensions.
-
SYNC3:
Synchronize <file> with disk: flush
output; re-read header from disk.
-
INQATT3:
Inquire the names, types, and sizes of netCDF attributes
for <variable> in <file>.
-
RDATT3 and RDATTC:
Read value of <attribute> of
<variable> in <file>.
Numeric attributes use
RDATT3() and
character-string attributes use RDATTC()
-
WRATT3 and WRATTC:
write value of <attribute> for
<variable> in <file>.
Numeric attributes use
WRATT3() and
character-string attributes use WRATTC()
Back to Contents
See also programs bcwndw,
m3wndw, and
utmtool.
-
BILIN and BMATVEC:
apply 4-band sparse matrix to vector (e.g., for bilinear
interpolation; BMATVEC also does horizontal::vertical
transpose).
-
CBARNES1 and CBARNESN:
Use Barnes analysis to interpolate scattered data to a grid
-
DSCOORD:
get description of <named coordinate system>
-
DSCGRID:
get description of <named grid>
-
GTP0:
driver routine GTPZ0 from US Geological
Survey's official GCTP coordinate system
manipulation library.
-
LAMBERT:
convert among various map projections:
- LAMBERT( CNAME, A, B, C, XC, YV ): Initialize by name
- POLSTE( CNAME, A, B, C, X, Y ): Initialize by name
- TRMERC( CNAME, A, B, C, X, Y ): Initialize by name
- EQMERC( CNAME, A, B, C, X, Y ): Initialize by name
- SETLAM( A, B, C, X, Y ): Initialize by angles
- SETPOL( A, B, C, X, Y ): Initialize by angles
- SETTRM( A, B, C, X, Y ): Initialize by angles
- SETEQM( A, B, C, X, Y ): Initialize by angles
- LAM2LL( X, Y, LON, LAT ): Perform conversion
- LL2LAM( LON, LAT, X, Y ): Perform conversion
- LAM2UTM( X, Y, Z, U, V ): Perform conversion
- UTM2LAM( X, Y, Z, U, V ): Perform conversion
- POL2LL ( X, Y, LON, LAT ): Perform conversion
- LL2POL ( LON, LAT, X, Y ): Perform conversion
- LAM2POL( X, Y, U, V ): Perform conversion
- POL2LAM( X, Y, U, V ): Perform conversion
- POL2UTM( X, Y, Z, U, V ): Perform conversion
- UTM2POL( X, Y, Z, U, V ): Perform conversion
- TRM2LL( X, Y, LON, LAT ): Perform conversion
- LL2TRM( LON, LAT, X, Y ): Perform conversion
- TRM2LAM( X, Y, U, V ): Perform conversion
- LAM2TRM( X, Y, U, V ): Perform conversion
- TRM2UTM( X, Y, Z, U, V ): Perform conversion
- UTM2TRM( X, Y, Z, U, V ): Perform conversion
- TRM2POL( X, Y, U, V ): Perform conversion
- POL2TRM( X, Y, U, V ): Perform conversion
- EQM2LL( X, Y, LON, LAT ): Perform conversion
- LL2EQM( LON, LAT, X, Y ): Perform conversion
- EQM2LAM( X, Y, U, V ): Perform conversion
- LAM2EQM( X, Y, U, V ): Perform conversion
- EQM2UTM( X, Y, Z, U, V ): Perform conversion
- UTM2EQM( X, Y, Z, U, V ): Perform conversion
- EQM2TRM( X, Y, U, V ): Perform conversion
- TRM2EQM( X, Y, U, V ): Perform conversion
- EQM2POL( X, Y, U, V ): Perform conversion
- POL2EQM( X, Y, U, V ): Perform conversion
-
LL2UTM and UTM2LL:
convert between LAT-LON and UTM coordinates
-
SETSPHERE and SPHEREDAT:
select non-default geodetic spheroids for LAMBERT, LL2UT
etc.
-
UNGRIDB:
computes "ungridding"matrices for bilinear
interpolation (e.g., with BILIN
or BMATVEC)
Back to Contents
See also programs DATSHIFT,
gregdate and
juldate for date-related
calculations, and m3tproc and
m3tshift for time-related file
operations.
-
CURRSTEP and CURREC:
find starting date and time, or record-number
respectively, of the timestep containing
<jdate-&-time>
-
DAYMON:
find month and day-of-month for <jdate>
-
DT2STR:
Construct string "HH:MM:SS Month DD, YYYY" for
<jdate-&-time>
-
GETDATE:
Prompt the user for a date; return the result according to
EDSS/Models3 standard
conventions for dates and times
-
GETDTTIME:
get current wall-clock date and time
-
HHMMSS:
construct string "HH:MM:SS" for
<time>
-
ISDSTIME:
TRUE if Daylight Savings Time in effect for
<jdate>
-
JSTEP3:
Compute record number (1,2,...) for
<jdate:jtime> with respect to the
time step sequence <sdate:stime:tstep>,
or (-1) if <jdate:jtime> is not on that
sequence.
-
JULIAN:
find Julian day number (1...365,366) for
<month> <day> <year>
-
MMDDYY:
construct string "Month DD, YYYY" for
<jdate>
-
NEXTIME:
update <jdate-&-time> by
<timestep>
-
SEC2TIME:
get Models-3 time representation for <seconds>
-
SECSDIFF:
find time difference (seconds) between two
<jdate-&-time> pairs
-
TIME2SEC:
get number of seconds for <time>
-
WKDAY:
get day-of-week (1...7) for <jdate>
-
YEAR4:
Return 4-digit year for the given 2-digit year (e.g.,
YEAR4(97)==1997)
-
YR2DAY:
get the year-to-day conversion factor (1/365 or 1/366)
for the given year.
Back to Contents
-
BILIN and BMATVEC:
apply 4-band sparse matrix to vector (e.g., for bilinear
interpolation). For layered data, BMATVEC performs
interpolate-and-transpose, transforming data from
I/O API layer order to (e.g.) SMOKE LAYPOINT
computational order.
-
CBARNES1 and CBARNESN:
Use Barnes analysis to interpolate scattered data to a grid
- CHARACTER*2 FUNCTION CRLF():
returns character string "<CR><LF>"
(DOS/Windows line terminator)
-
DMATVEC:
applies diagonal (sparse) matrix to vector
-
DSCOORD:
get description of <named coordinate system>
-
DSCGRID:
get description of <named grid>
-
ENVDBLE:
get DOUBLE PRECISION <value of logical name>
from the environment
-
ENVINT:
get INTEGER <value of logical name> from
the environment
-
ENVREAL:
get REAL <value of logical name> from
the environment
-
ENVSTR:
get CHARACTER-STRING <value of logical name>
from the environment
-
ENVYN:
get LOGICAL <value of logical name>
from the environment
-
FINDC, FIND1, FIND2, FIND3, FIND4,
FINDR1, FINDR2, FINDR3, FINDR4:
find character-string <key>, INTEGER, or
REAL <key-tuple> in sorted
<key-table> or
<keytuple-table>
-
GCD:
greatest common divisor function
-
GET_ENDIAN:
get host-machine byte order.
-
GETDFILE:
open direct access Fortran file with
<logical name>
and <record length>,
<formatting> and <read-write
status>
-
GETEFILE:
open sequential Fortran file with
<logical name>, <formatting>
and <read-write status>
-
GETDBLE:
prompt user for DOUBLE and get response, with default and
range checking
-
GETMENU:
prompt user for menu choice, etc.
-
GETNUM:
prompt user for INTEGER, etc.
-
GETREAL:
prompt user for REAL, etc.
-
GETSTR:
prompt user for CHARACTER STRING, etc.
-
GETYN:
prompt user for "Yes-No" answer, etc.
-
GRIDOPS:
select and compute various comparison operations
-
INDEX1:
<unsorted-name-table> lookup for
<character-string key>
-
JUNIT:
return a "safe"
<Fortran unit number>
-
LBLANK:
number of leading blanks in <string>
-
LEN2:
number of leading blanks in <string>;
superseded by (more-generic) LBLANK().
-
INTLIST, REALIST, and
STRLIST:
Read in (and count) environment variables that are comma
delimited lists of the indicated type.
-
LOCATC, LOCAT1, LOCAT2, LOCAT3, LOCAT4,
LOCATR1, LOCATR2, LOCATR3, LOCATR4:
find insertion-point for character-string
<key> or INTEGER or
REAL <key-tuple> into sorted
<key-table> or
<keytuple-table>, or -1 if the
key is already present
-
LUSTR:
left-justify and upcase contents of <string>;
-
M3ERR:
<warning or error message>;
with SHUT3() and EXIT(2) if fatal error;
deprecated: superseded by
M3EXIT() and M3WARN()
-
M3EXIT:
<exit message> with
<date and time>,
SHUT3() and EXIT(<status>)
-
M3MESG, M3MSG2,
M3PARAG, M3PROMPT, and
M3FLUSH:
Write 1-line or multi-line <message>
to Fortran-program log; or do prompt-and-response
processing.
-
M3WARN:
<warning message> with
<date and time>
-
NAMEVAL:
get (CHARACTER-STRING) value of
<environment variable> (for Fortran)
-
PCOEF:
coefficients for the polynomial fitting given data
-
PMATVEC:
applies sparse incidence matrix to vector
-
POLY:
degree-<d> polynomial interpolation
-
PROMPTDFILE:
Prompt user for <logical name>
and open the corresponding file for Fortran direct
access with the indicated <read-write
status>, <formatting>, and
<record length>
-
PROMPTFFILE:
Prompt user for <logical name>
and open the corresponding file for Fortran
sequential access with the indicated <read-write
status> and <formatting>
-
PROMPTMFILE:
Prompt user for <logical name>
and open the corresponding I/O API file for
sequential access with the indicated <read-write
status> and <formatting>
-
READSMET:
read 1 hour's data window from surface met file.
-
SETENVVAR:
Subroutine-call equivalent to csh command
setenv name value
-
SMATVEC:
applies sparse matrix to vector
-
SORTC, SORTI1, SORTI2, SORTI3, SORTI4,
SORTR1, SORTR2, SORTR3, SORTR4 :
sort <index table> acording to a
character string key-table, or a
<keytuple-table> of INTEGERs or REALs.
-
SCANINT, STR2INT, and STR2REAL:
Convert a numeric <string> into an INTEGER
or REAL value
-
SYSTEMF():
Fortran wrapper around standard system() C-library
call: execute shell-commands and other programs from within
Fortran code.
-
TRIMLEN:
length of <string>, not counting trailing blanks
-
UNGRIDB:
computes "ungridding"matrices for bilinear
interpolation
-
UPCASE:
make <string> into ALL CAPS
Back to Contents
-
Some Sample Programs using the I/O API:
-
ncdump:
print file as structured ASCII; from NCAR
-
MCPL I/O API output module for MM5:
Generate I/O API output files directly from within
MM5, for analysis, emissions modeling, air quality
modeling, and model coupling.
-
airs2m3:
Import air quality monitor data from an AIRS AMP350-format
ASCII file and put it into an I/O API
"observational data" file.
-
bcwndw:
extract data data from a gridded file to the boundary of
a subgrid window (see m3wndw for extracting
to the window itself)
-
m3cple:
copy to the same grid, or interpolate to another grid
a time sequence of all variables from a source file to
a target file, under the optional control of an
I/O API coupling-mode
"synch file".
-
m3combo:
Compute linear combinations of sets of variables from
an I/O API input file, and write the resulting
variables to an I/O API output file.
-
m3diff:
compute statistics for pairs of variables and for the results
of applying various comparison ("differencing")
operations to those variables in a pair of files.
-
m3edhdr:
edit header attributes/file descriptive parameters
-
m3merge:
Merges selected variables from a set of input files for a
specified time period, and writes them to a single output
file, with optional variable-renaming in the process.
-
m3pair:
build ASCII file of paired values for two variables from
two files, within a user-selected window into the grid,
according to user specifications,
-
m3stat:
compute statistics for variables in a file
-
m3tproc:
compute time period aggregates (e.g., 08:00-16:00
gridded daily maxima) and write them to an output file
-
m3tshift:
copy/time shift data from a file
-
m3wndw:
window data from a gridded file to a subgrid (see
bcwndw for extracting
to the boundary of the subgrdi window)
-
m3xtract:
extract a subset of variables from a file for
<time interval>
-
m3fake:
build a file according to user specifications,
filled with dummy data, or data read in from a
set of user-supplied files.
-
m4filter:
convert first-edition Models-3 files to current version
-
mtxblend:
Use a sparse-matrix file to interpolate/transform data
from an input file to the grid of a "base" file
and to merge it with data from the "base" file.
-
mtxbuild:
Build a sparse-matrix transform file from user-supplied
ASCII coefficient inputs.
-
mtxcalc:
Build a grid-to-grid sparse-matrix transform file using
a sub-sampling algorithm.
-
mtxcple:
Use a sparse-matrix file to interpolate a time sequence of
all variables from a source file to a target file, under
the optional control of an
I/O API coupling-mode
"synch file".
-
presterp:
Interpolate from a 3-D sigma-coordinate file to a
new 3-D pressure-coordinate file, using coefficients
from
PRES_CRO_3D.
-
selmrg2d:
select multiple 2D layer/variable combinations from multiple
gridded input files, and write result to merged 2D gridded
output file
-
vertot:
compute vertical-column totals of variables in a file
-
datshift:
Takes calendar date (form YYYYMMDD) and a number of days D,
and reports the date D days later.
-
gregdate:
compute calendar style date "Month DD, YYYY",
day-of-week (Sunday, Monday, ..., Saturday) and whether
or not daylight savings time is in effect from Julian
date YYYYDDD, or "yesterday",
"today", or "tomorrow".
-
juldate:
compute Julian date YYYYDDD and day-of-week (Sunday,
Monday, ..., Saturday) and whether or not daylight savings
time is in effect from calendar style date
"Month DD, YYYY", or "yesterday",
"today", or "tomorrow".
-
utmtool:
Perform coordinate conversions and grid-related
computations for Lat-Lon, Lambert, and UTM coordinate
systems.
Back to Contents
Back to Contents
Back to Contents
Back to Contents
Back to Contents
Back to Contents
UP: I/O API home page
UP: BAMS Environmental Modeling Center home page
UP: The Environmental Decision Support System Pages
Back to Contents
Send comments to
Carlie J. Coats, Jr.
carlie.coats@baronams.com