The BAMS/EDSS/Models-3 I/O API: User Manual

Contents

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

Best Viewed With Any Browser

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

I/O API Tutorial

Back to Contents

Availability/Download of the BAMS EDSS/EPA Models-3 I/O API

Back to Contents

Changes from I/O API Version 1

Back to Contents

Conventions

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

Data Types Supported

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

Object Libraries and Supported Machines

Public INCLUDE FILES

FDESC3: file description data structures
IODECL3: declarations and usage comments for I/O routines
PARMS3: "magic number "tokens and dimensioning parameters
Back to Contents

I/O API: Public Routines

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

Coordinate and Grid Related Routines

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:
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

Date-Time Manipulation Routines

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

Utility Routines

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

I/O API Related Programs and Examples

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

I/O API Troubleshooting

Back to Contents

I/O API Requirements Document

Back to Contents

Notices and Acknowledgements

Back to Contents

netCDF User's Guide (at NCAR)

Back to Contents

PVM: Parallel VirtualMachine (at Oak Ridge)

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