The Models-3 Input/Output Applications Programming Interface (I/O API) is an environmental software development library which provides an easy-to-learn, easy-to-use interface with the data involved in CMAQ applications (Coats, 2005). The files are self-describing Network Common Data Form (NetCDF) format files in which the file headers have all the dimensioning and descriptive information needed to define the resident data. According to Unidata (2005), NetCDF is an interface for array-oriented data access and a freely-distributed collection of software libraries for several languages that provide implementations of the interface.
The CMAQ data files all have selective direct access which means the modeling system can be more efficient by only reading the necessary parts of the data files. Additionally, I/O API files are portable across computing platforms. This means that the same file can be read, for example, on a Sun workstation, a Red Hat Linux workstation, and on a Mac OS X. A further benefit of the I/O API is that an expansive set of data manipulation utilities and statistical analysis programs are available to help evaluate and post-process the binary CMAQ input/output data files.
The I/O API system is essentially transparent to those CMAQ users employing a preconfigured application of the model. For users planning to modify the code or implement updated modules for research purposes, a few key elements of the I/O API should be understood and are discussed below. This section covers only the barest of necessities in terms of a CMAQ user's interaction with I/O API. For more detailed information about developing new modules for CMAQ using the I/O API code libraries, please refer to Chapter 9.
The I/O API stores and retrieves data using files and virtual files, which have (optionally) multiple time steps of multiple layers of multiple variables. Files are formatted internally so that they are machine and network-independent. This behavior is unlike FORTRAN files, whose internal formats are platform-specific, so that the files do not transfer using the File Transfer Protocol (FTP) or Network File System (NFS)-mount very well. Each I/O API file has an internal description, consisting of the file type, the grid and coordinate descriptions, and a set of descriptions for the file variables (i.e., names, unit specifications, and text descriptions). According to the I/O API format, files and variables are referred to by names, layers by number (from one to the greatest number of layers in the file), and dates and times are stored as integers, using the coding formats: YYYYDAY (commonly called "JDATE") and HHMMSS (commonly called "JTMIE") as defined in equations 4.1a and 4.1b.
| YYYYDAY = (1000 * Year) + Julian Day | (4.1a) |
|
HHMMSS = (10000 * Hour) + (100 * Minute) + Seconds |
(4.1b) |
Rather than forcing the programmer and program-user to deal with hard-coded file names or hard-coded unit numbers, the I/O API utilizes the concept of logical file names. The modelers can define the logical names as properties of a program and then at run-time the logical names can be linked to the actual file name using environment variables. For programming purposes, the only limitations are that file names cannot contain blank spaces and must be at most 16 characters long. When a modeler runs a program that uses the I/O API, environment variables must be used to set the values for the program's logical names. This will be discussed further in terms of CMAQ applications in Chapter 5. The remainder of this section will discuss some of the rudimentary details of programming in an environment using I/O API data files.