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

Contents

• Back to the I/O API Home Page
• Availability/Download/Installation
• Tutorial
• Coding Standards used for the I/O API
• Change Log / "What's New" / Research Directions
• Conventions
  • Logical Names
  • Standard environment variables
  • Grids and Coordinates
  • Dates, Times, and Time Steps
  • Calling from Fortran
  • Calling from C
  • File Structure:
    Variables, Layers, and Time Step Sequences
  • Files as Data Sets:
    netCDF and native binary disk files, PnetCDF/MPI distributed files, file-list sequences, volatile, snoop-mode, buffered, and PVM virtual files
• Data Types
• Object Libraries and Executables
• MODULEs and Public INCLUDE Files
• Public I/O Routines
• Coordinate and Grid Related Routines
• Date-Time Manipulation Routines
• Utility Routines
• Related Programs: m3tools; Examples
• Python ioapiTools
• I/O API Troubleshooting
• Requirements Document
• Notices: Copyright, Acknowledgements

• netCDF User's Guide (at NCAR's netCDF home web-site)
• PVM: Parallel Virtual Machine
  A Users' Guide and Tutorial for Networked Parallel Computing (at Oak Ridge's web site)

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 Enhanced^tm. 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@jyarborough.com).

Both the original working prototype and this version are implemented on top of netCDF , ©1993- University Corporation for Atmospheric Research for persistent storage and PVM from Oak Ridge National Laborator for parallel model coupling.

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.

PVM likewise provides an application- and machine-independent interface that permits a heterogeneous collection of computers hooked together by a network to be used as a single system for the support of coupled modeling.

Back to Contents

I/O API Tutorial

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

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 f90 (etc.) to link the ".o" files)

File Structure: Variables, Layers, and Time Steps

Files as Data Sets: NetCDF and native-binary disk files, PnetCDF/MPI distributed-I/O files for CMAQ, LIST: sequences of disk-files, PVM-mailbox Coupling-Mode virtual "files", and memory-resident buffered virtual "files".

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

"Raw netCDF": MODULE MODNCFIO

MPAS: unstructured Voronoi grids and MPAS-format netCDF: MODULE MPASFIO

Object Libraries and Supported Machines/Compilers/Variants

MODULEs and Public INCLUDE Files

MODULE M3UTILIO: parameters, data structures, INTERFACE blocks, and declarations. Replaces use of the (now-deprecated) INCLUDE-files below.
Note on Code Conversion: Since MODULE M3UTILIO INCLUDEs these files, and since it has INTERFACE blocks for virtually all the public I/O API subroutines and functions, you need to do the following to retrofit an "old-style" code to one with USE M3UTILIO:

• Add USE M3UTILIO before any INCLUDE statements or variable-declarations;
• Delete the INCLUDE statements for PARMS.EXT, FDESC3.EXT, and IODECL3.EXT;
• Delete the declarations and EXTERNAL statements for I/O API functions.
• Judging from experience, there is a substantial chance that you will find bad-argument-list bugs in your code...

MODULE MODATTS3: parameters and routines for map-transform, CF, CMAQ, and SMOKE metadata.

MODULE MODGCTP: parameters and routines for map-transform operations and interpolation, using USGS coordinate transform package GCTP.

MODULE MODNCFIO: parameters and function-declarations for netCDF, and for PnetCDF, if PnetCDF/MPI distributed-I/O is enabled.
Can be used to replace INCLUDE-file NETCDF.EXT or netcdf.inc, Also includes new routines for inquiring about, reading, and writing variables from "raw" netCDF files.

MODULE MODMPASFIO: Unstructured-grid description for MPAS domains, related parameters and state variables, MPAS-format-netCDF I/O routines, and various utility routines

FDESC3.EXT: file description data structures : (Deprecated for I/O API-3.0 or later)

IODECL3.EXT: declarations and usage comments for I/O routines : (Deprecated for I/O API-3.0 or later)

PARMS3.EXT: "magic number "tokens and dimensioning parameters : (Deprecated for I/O API-3.0 or later)

I/O API: Public Routines

Primary I/O 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>

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()

OPEN3: open <file> for <mode / status>, using <file description> to create it, if necessary

READ3: read <timestep> of <layer> of <variable> from <file>

SHUT3: shut down I/O API; flush files to disk

SYNC3: Synchronize <file> with disk: flush output; re-read header from disk.
("Volatile" files auto-synch themselves...)

WRITE3: write <timestep> of <variable> to <file>

XTRACT3: read <window> of <timestep> of <variable> from <file>

Special (Convective-Event, Extra-Metadata) I/O Routines

See also MODULE MODATTS3 with parameters and routines for map-transform, CF, CMAQ, and SMOKE metadata.

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.

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()

GETMTXATT(): get input or output grid description attributes for matrix files and return them as arguments.

SETMTXATT(): set or check input and output grid description attributes from arguments for matrix-files: if file is NEW, set the attributes; else check them.

CHKMTXATT(): check input or output grid description attributes for matrix-files against attributes from the argument list. Return .TRUE. if they match, .FALSE. otherwise.

Utility and Misc I/O Routines (consistency checking, etc.)

FILCHK3: check a file's file type and dimensions for consistency with values supplied by the caller.

GRDCHK3: check a file's map projection, horizontal and vertical grid definition parameters for consistency with values supplied by the caller.

IOPARMS3: return dimensioning parameters from INCLUDE-file PARMS3.EXT to allow consistency checks in model-level code.

READ4D: read <time step sequence > of <layer> of <variable> from <file>

RUNSPEC: Get <time step sequence > for a program run, consistent with, and with defaults from, a specified <file>

WRITE4D: write <time step sequence > of <variable> to <file>

"Raw" netCDF Routines

CREATENC: Create a new "raw netCDF" file.

DESCNCVAR: Return the list of variables, together with their units, types, and dimension-info.

READNCVAR: Read a variable, or a timestep of a variable

WRITENCVAR: Write a variable, or a timestep of a variable

MPAS-format-netCDF Routines

INITMPGRID: module initialization

SHUTMPGRID: module shutdown, flushing and closing all files

OPENMPAS: open existing MPAS-format-netCDF input or output file

CREATEMPAS: create new MPAS-format-netCDF output file

DESCMPAS: read header and return description for MPAS-format file

READMPAS: read variable or time step of variable from MPAS-format input file

WRITEMPAS: write variable or time step of variable to MPAS-format output file

READMPSTEPS: Read MPAS-format ASCII timestep-value list from an MPAS-format file and convert to I/O API conventions

WRITEMPSTEP: Write timestep-value record to an MPAS-format file as MPAS-format ASCII

See also m3tools programs mpasdiff, mpasstat, mpastom3, and mpaswtest

Back to Contents

Coordinate and Grid Related Routines

NOTE: Longitudes are represented in REAL or (preferably) DOUBLE PRECISION within the range [-180,180], as consistent with duly-enacted ISO Standard 6709, treaty obligations since 1878, and several centuries of common usage. Beware that the WMO with its GRIB "standards" violates all of these. When dealing with WMO "longitudes", special-purpose modeling-code hacks will be required.

GTPZ0: driver routine GTPZ0 from US Geological Survey's official GCTP coordinate system manipulation library.

MODULE MODGCTP: I/O API Version 3.2 module with PARAMETERs for GCTP spheroid names and indices, and various routines that use GTPZ0:

M3TOGTPZ

Set up input or output arguments for GTPZ0 according to I/O API conventions

GRID2XY

Compute cell-centers for GRID2 relative to the coordinate system for GRID1

OpenMP-Parallel bilinear interpolation package

GRID2INDX

Compute bilinear interpolation indices and coeffs for grid-to-grid interpolation

PNTS2INDX

Compute bilinear interpolation indices and coeffs for grid-to-scattered-point interpolation

INDXMULT

Use interpolation indices and coeffs for interpolation

XY2XY

Perform coordinate-projection transformations for single points, arrays of points, and grids

SETSPHERE, INITSPHERES, SPHEREDAT

Set up input and output spheroids for MODGCTP operations

INITPROJ, ..., LAMBERT(), ..., ALB2EQM()

(Legacy) single-precision single-point coordinate tranforms

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>

FILCHK3: check a file's file-type and dimensions for consistency with values supplied by the caller.

GRDCHK3: check a file's map projection, horizontal, and vertical grid definition parameters for consistency with values supplied by the caller.

Single-Precision Coordinate Transform Routines:

INITPROJ, LAMBERT, POLSTE, TRMERC, EQMERC, ALBERS

Initialize projection by name

SETPROJ, SETLAM, SETPOL, SETTRM, SETEQM, SETALB

Initialize projection by defining angles

LL2LAM, LL2UTM, LL2POL, LL2TRM, LL2EQM, LL2ALB
LAM2LL, LAM2UTM, LAM2POL, LAM2TRM, LAM2EQM, LAM2ALB
POL2LL, POL2LAM, POL2UTM, POL2TRM, POL2EQM, POL2ALB
TRM2LL, TRM2LAM, TRM2UTM, TRM2POL, TRM2EQM, TRM2ALB
EQM2LL, EQM2LAM, EQM2UTM, EQM2POL, EQM2TRM, EQM2ALB
ALB2LL, ALB2LAM, ALB2UTM, ALB2POL, ALB2TRM, ALB2EQM

Perform single-point coordinate transforms

INITSPHERES(), SETSPHERE(), SPHEREDAT(): select non-default geodetic spheroids for LL2LAM(), etc. (above).

UNGRIDB and UNGRIDI: compute "ungridding"matrices for bilinear interpolation (e.g., with BILIN() or BMATVEC) and for incidence-matrix re-gridding, respectively.

MODULE MPASFIO routines:

SPHEREDIST: compute spherical-Earth distance from (LAT1,LON1) to (LAT2,LON2)

FINDCELL: find subscript for MPAS-grid cell containing the point (ALAT,ALON)

FINDVRTX: find subscript for MPAS-grid vertex closest to the point (ALAT,ALON) (equivalently, for MPAS-grid dual-cell containing the point (ALAT,ALON)

ARC2MPAS: compute 2-D and 3-D weights for arc-segment between points (LAT1,LON1[,HGT1]) and (LAT2,LON2[,HGT2]) (e.g., for SMOKE)

MPINTERP: Interpolate an MPAS-grid variable to a point, set of points, or 2-D grid of points, using barycentric-linear interpolation for REAL variables, or cell-based interpolation for INTEGER variables.

Date-Time Manipulation Routines

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>

LASTTIME: Find ending date & time for a specified time step sequence <SDATE:STIME:TSTEP:NSTEPS>

MMDDYY: construct string "Month DD, YYYY" for <jdate>

NEXTIME: update <jdate-&-time> by <timestep>

RUNSPEC: Get <time step sequence > for a program run, consistent with, and with defaults from, a specified <file>

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.

MPSTR2DT() and MPDT2STR(): convert MPAS-format ASCII date&time to/from I/O API convention JDATE:JTIME
    I/O API-3.2 or later

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.

C/Fortran String Conversion: name2cstr(), fstr2cstr(), and cstr2fstr(): conversion back and forth between Fortran CHARACTER strings and C char * strings.

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)
This should have been a PARAMETER instead of a FUNCTION, but others insisted.

DMATVEC: applies diagonal (sparse) matrix to vector

DSCOORD: get description of <named coordinate system>

DSCGRID: get description of <named grid>

ENVGET(): Fortran-90 generic function for retrieving a CHARACTER string, numeric, or LOGICAL <value of logical name> from the environment, with DEFAULT and possible bounds-checking.
Generic form is I/O API-3.2 or later and subsumes the following older specific forms (which are still available):

BENVDBLE(LNAME, ...):  get DOUBLE PRECISION from environment, with bounds-checking (I/O API-3.2 or later)
BENVINT(LNAME, ...):  get INTEGER from environment, with bounds-checking BENVINT8(LNAME, ...):  get INTEGER(8) from environment, with bounds-checking (I/O API-3.2 or later)
BENVREAL(LNAME, ...)get REAL from environment, with bounds-checking (I/O API-3.2 or later)
ENVDBLE(LNAME, ...):  get DOUBLE PRECISION from environment
ENVINT(LNAME, ...):  get INTEGER from environment
ENVINT8(LNAME, ...):  get INTEGER from environment
ENVREAL(LNAME, ...):  get REAL from environment
ENVSTR(LNAME, ...):  get CHARACTER string from environment
ENVYN(LNAME, ...):  get LOGICAL from environment from the environment

FINDC, FINDKEY, 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.

GETDBLE and GETDBLE1: prompt user for DOUBLE and get response, with default and range checking

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>

GETMENU: prompt user for menu choice, etc.

GETNUM and GETNUM1: prompt user for INTEGER, etc.

GETREAL and GETREAL1: prompt user for REAL, etc.

GETSTR: prompt user for CHARACTER STRING, etc.

GETVAL: Fortran-90 generic function for prompting user for a numeric or LOGICAL answer, with DEFAULT and bounds checking.
(I/O API-3.2 or later): GETINT8; Generic form and new GETDBLE1, GETNUM1, GETINT81, GETREAL1 forms that do not have bounds checking.
Subsumes the following older specific forms (which are still available):

GETDBLE and GETDBLE1,
GETMENU,
GETNUM, GETNUM1, GETINT8, GETINT81,
GETREAL and GETREAL1,
GETYN,


GETYN: prompt user for "Yes-No" answer, etc.

GRIDOPS: select and compute various comparison operations

INDEX1 and INDEXINT1: <unsorted-name-table> lookup for <character-string or integer 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().

ENVLIST, INTLIST, REALIST, and STRLIST: Read in (and count) environment variables that are comma delimited lists of the indicated type.

LOCATE(): Fortran-90 generic function to find subscript for insertion of keys K or key-tuples (e.g., <K1,K2,K3>) into sorted <key-table> or <keytuple-table>, or -1 if the key is already present
for I/O API-3.2 or later
Subsumes the following specific forms:

LOCATC:  for CHARACTER keys
LOCAT1, LOCAT2, LOCAT3, LOCAT4:  for INTEGER key-tuples
LOCATL1, LOCATL2, LOCATL3, LOCATL4:  for INTEGER*8 key-tuples
LOCATR1, LOCATR2, LOCATR3, LOCATR4:  for REAL key-tuples

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

PERMUTI Fortran-90 generic routine to permute arrays inplace, according to am <index table> such as that produced by SORTI

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 and SMATVECP: applies sparse matrix to vector

SORTI Fortran-90 generic routine to generate sorted <index table> acording to a CHARACTER-string key-table, or a <keytuple-table> of INTEGERs. INTEGER(8)s, or REALs.using the quicksort algorithm
Generic form is I/O API-3.2 or later and subsumes the following older specific forms (which are still available):

SORTIC SORTIC8, SORTINC4, SORTINC8:  for CHARACTER key-tables, with optional INTEGER*8 result and/or initial-string-segment lengths
SORTI1, SORTI2, SORTI3, SORTI4:  for INTEGER keytuple-tables
SORTL1, SORTL2, SORTL3, SORTL4:  for INTEGER*8 keytuple-tables (I/O API-3.2 or later)
SORTR1, SORTR2, SORTR3, SORTR4:  for REAL keytuple-tables

SCANINT, STR2INT, STR2REAL, and STR2DBLE: Convert a numeric <string> into an INTEGER, REAL, or DOUBLE-PRECISION value, with error-checking.

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
    Deprecated for F90, since it duplicates intrinsic function LEN_TRIM()

UNGRIDB and UNGRIDI: computes "ungridding-matrices" for bilinear interpolation and "incidence-matrices" for source-attribution, etc.
    I/O API-3.2 or later: additional forms with IERR argument detect out-of-grid input locations.

UPCASE and DOWNCASE: make <string> into ALL CAPS or all lower-case.

I/O API Related Programs and Examples

Generally, you may need to run these programs with

    limit stacksize unlimited
    

With the exception of programs designed specifically for manipulating dates and times in scripts (greg2jul, jul2greg, juldiff, julshift, timeshift), these programs are designed for easy interactive use. They begin by displaying a "splash screen" displaying the name, usage, and version for the program, and then prompt the user for the specifications for the program-run. Most of these prompts have default values computed from the metadata in input-file headers; defaults may be accepted by hitting the RETURN key. To develop scripts for them, it is generally best to run them interactively once, recording all the responses you give to the prompts, and then use that information to develop a command-file which redirect into the program within the script.

Some Sample Programs (together with their source codes) using the I/O API

ncdump: print file as structured ASCII; from NCAR

Programs for data-analysis and manipulation

bcwndw: extract data data from a gridded file to the boundary of a subgrid window (see m3wndw below for extracting to the window itself)

dayagg: construct weighted averages from a set of input files and write the result to a seasonal "standard day" (year-zero) output file.

findwndw: Given two gridded files FILE1 and FILE2 find the specifications for the smallest window into the grid of FILE2 that completely covers the grid of FILE1.

gridprobe: build ASCII time series file by interpolating a selected set of (Lat-Lon specified) points for a selected variable from a GRIDDED file.

insertgrid: Aggregate/re-grid values from a high-resolution subdomain-file to "covered" grid cells in a coarse-resolution large-domain file, with map-projection transformation as appropriate.

m3cple and m3interp: 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".
    m3interp also does time-interpolation.

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

m3fake: build a file according to user specifications, filled with dummy data, or with data read in from a set of user-supplied ASCII CSV files.

m3mask: Reads ASCII mask-data, construct a gridded mask from it, and write the result as an M3IO file.

m3mxfind: find analysis-period MAX (e.g., daily-max) for a specified variable from a specified file, and report its date&time to an ASCII output file

m3merge: merge 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,

m3probe: build ASCII time series file for a selected set of (subscript specified) points for a selected variable from a GRIDDED, BOUNDARY, or CUSTOM file.

m3stat: compute statistics for variables in a file

m3totxt: extract selected variables for a specified window and time period into a GRIDDED M3IO file and write to an ASCII report 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

m3tslct: Use ${OUTFILE} from M3MXFIND to read maximum-time sets of variables and write them to an output file (e.g., "gridded daily-max-ozone" file).

m3wndw: window data from a gridded file to a subgrid (see bcwndw above, for extracting to the boundary of the subgrid window)

m3xtract: extract a subset of variables from a file for <time interval>

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 for program mtxcple [etc...] 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 indices and coefficients from PRES_CRO_3D.

presz: Construct an MM5-style reference atmosphere with layer-center and layer-surface altitude and reference pressure, and layer-center reference temperature, for a user specified coordinate system and grid.

selmrg2d: select multiple 2D layer/variable combinations from multiple gridded input files, and write result to merged 2D gridded output file.

vertimeproc: Given a specified time-aggregation duration, e.g., 24 hours, computes vertical-column/time-period totals for each REAL variable in a 3-D tie stepped (emissions, usually) file, and write the output to a 1-layer GRIDDED file.

vertintegral: Compute vertical-column mass-integral for each CMAQ conc-file variable, and write the output to a 1-layer GRIDDED file.

vertot: compute "dumb" vertical-column totals of variables in a 3-D GRIDDED file (does not take layer-thickness nor mass-weighting into account; think of it as a programming-example)

wndwpoints and wndwptdata: Subset the point-sources in SMOKE-I/O API POINTS and point-data files to a specified a grid-window and write the result to SMOKE-I/O API files.

Programs for Data Import/Export

airs2m3: import air quality monitor data from an AIRS AMP350-format ASCII file and put it into an I/O API "observational data" file.

camxtom3: convert CAMx and other UAM-format binary files to GRIDDED I/O API files.

mpastom3: Interpolate a set of variables from an MPAS-format-netCDF file for a specified time step sequence to a grid specified by an I/O API gridded Lat-Lon file, and write the result to a gridded I/O API file.

wrfgriddesc: Create a GRIDDESC file from the header-data in a WRF-format netCDF file.

wrftom3: Convert/extract/window variables from WRF-format netCDF files to GRIDDED I/O API files.

wrfwndw: Window/extract/window variables from WRF-format netCDF files to a new WRF-format netCDF file.

Programs for coordinate-manipulation

latlon: construct GRIDDED and/or BOUNDARY files with REAL variables LAT and LON for the cell-centers.
    For I/O API-3.2 after Dec. 25, 2017, also constructs DOUBLE PRECISION variables LATD and LOND.

projtool: Perform coordinate conversions and grid-related computations for LAT-LON, Lambert Conformal Conic, UTM, Polar Stereographic, General Transverse Mercator, Equatorial Mercator, and Albers Conic Equal Area coordinate systems.
Supersedes utmtool (below).

utmtool:     Deprecated for Version 3.1; deleted for Version 3.2
Perform coordinate conversions and grid-related computations for Lat-Lon, Lambert, and UTM coordinate systems.

wndwdesc: New June 12, 2019 for Version 3.2
Take diagonally-opposing Lat-Lon coordinates for a grid, and compute the col-row bounds for the windowed sub-grid that encloses them, and produces a single-grid GRIDDESC file for the indicated sub-grid.

Programs for date-manipulation

Verbose, prompt based, for interactive use:

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".

For scripting: The following programs are driven by command line arguments and echo a single number to standard output for use in scripting, or if invoked with command line argument --help display a usage-screen. Most of these also accept YESTERDAY, TODAY, TOMORROW as command-line arguments.

datshift: Shift a Gregorian-calendar date YYYYMMDD by a specified number of days and echo the result.

greg2jul: Convert a Gregorian-style date YYYYMMDD to Julian-style YYYYDDD and echo the result.

jul2greg: Convert Julian-style date YYYYDDD to Gregorian-style YYYYMMDD and echo the result.

juldiff: Compute the number of days between two Julian dates and echo the result.

julshift: Shift a Julian date YYYYDDD by a specified number of days and echo the result.

timediff: Compute the number of days between two dates× formatted YYYYDDD.HHMMSS and echo the result.

timeshift: Shift a Julian date&time YYYYDDD.HHMMSS by a specified time step HHMMSS and echo the result.

Programs for MPAS-grid and MPAS-format-netCDF file manipulation
I/O API-3.2 after Oct. 24, 2017 only.

mpasdiff: Compare variables or layer-ranges of variables from one or two MPAS-format-netCDF files using the standard binary grid-comparison operations, and report statistics for the result

mpasstat: Compute statistics for a variable or layer-range of a variable from an MPAS-format-netCDF file.

mpastom3: Interpolate a set of variables from an MPAS-format-netCDF file for a specified time step sequence to a grid specified by an I/O API gridded Lat-Lon file, and write the result to a gridded I/O API file.

mpaswtest: Compute weights for allocating a Lat-Lon specified arc to a 2-D or 3-D MPAS grid.
Demonstration program for MODULE MPASFIO

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.

Python ioapiTools

ioapiTools is a python interface to I/O API data. It allows you to easily import the data into python, have full access to the I/O API metadata, use the full breadth of python's scientific libraries, create plots, and write out your data to new I/O API or netCDF files.

See the ioapiTools on its GitHub site:

https://github.com/CDAT/cdat/tree/master/contrib/ioapiTools

Back to Contents

I/O API Troubleshooting

I/O API Requirements Document

Notices and Acknowledgements

netCDF User's Guide (at NCAR)

PVM: Parallel VirtualMachine (at Oak Ridge)

Back to Contents

Send comments to

$Id: AA.html 259 2024-01-23 19:27:19Z coats $