Each CMAQ data file has an internal file description that contains the file type, the file start date and time, the file time step, the grid and coordinate descriptions, and a set of descriptions for the set of variables contained within the file (i.e., names, units specifications, and text descriptions). Some of the items in a file description, such as the dates and times for file creation and update, and the name of the program which created the file, are maintained automatically by the system. The remainder of the descriptive information must be provided at the time of file creation.
All files manipulated by the I/O API may have multiple variables and multiple layers. Each file has a time step structure that is shared by all of its variables, as well. There are three kinds of time-step structure supported, as listed in Table 4-1. Within a file, all the variables are data arrays with the same dimensions, number of layers and the same data structure type, although possibly different basic types (e.g., gridded and boundary variables can not be mixed within the same file, but real and integer variables can). The data type structures that are supported are listed in Table 4-2. GRDDED3 and BNDARY3 are the most prevalent file types in a CMAQ simulation.
Table 4.1. Possible Time Step Structures in IO/API Files
| File Type | Description |
|---|---|
| Time-independent | The file's time-step attribute is set to zero. Routines which deal with time-independent files ignore the date and time arguments |
| Time-stepped | The file has a starting date, a starting time, and a positive time step. Read and write requests must be for some positive integer multiple of the time step from the starting date and time. |
| Circular-buffer | This type of file keeps only two “records”, the “even”" part and the “odd” part (useful, for example, for "restart" files where only the last data written in the file are used). The file's description has a starting date, a starting time, and a negative time step (set to the negative of the actual time step). Read and write requests must be for some positive integer multiple of the time step from the starting date and time, and they must reflect a specific time step that is in the file. |
Table 4.2. Possible Data Type Structures in IO/API Files
| File Type | Magic Number | Data Type | Description |
|---|---|---|---|
| CUSTOM3 | -1 | Custom | User-dimensioned array of REAL*4s that these system reads/writes reliably |
| DCTNRY3 | 0 | Dictionary | Data type stores and retrieves parts of an FDESC.EXT file description |
| GRDDED3 | 1 | Gridded | Dimension as REAL*4 ARRAY (NCOLS, NROWS, NLAYS, NVARS) |
| BNDARY3 | 2 | Boundary | Dimension as REAL*4 ARRAY (SIZE, NLAYS, NVARS) |
| IDDATA3 | 3 | ID-reference | Used to store lists of data like pollution monitoring observations |
| PROFIL3 | 4 | Vertical profile | Used to store lists of vertical data, like rawinsonde observations |
| GRNEST3 | 5 | Nested grid | Preliminary and experimental implementation for storing multiple grids, which need not in fact have any particular relationship with each other beyond using the same coordinate system |
| SMATRX3 | 6 | Sparse matrix | Sparse matrix data, which uses a "skyline-transpose" representation for sparse matrices, such as those found in SMOKE |
| KFEVNT3 | -3 | Cloud event | KF-Cloud files use the same file description data structures (from FDESC3.EXT) and defining parameters (from PARMS3.EXT); the usual I/O API DESC3() call may be used to retrieve file descriptions from the headers. KF-Cloud file, on the other hand, have their own specialized opening/creation, lookup/indexing, input, and output operations |
| TSRIES3 | 7 | Hydrology Time Series | A hydrology time series file behaves much like a degenerate gridded file, except that the numbers of rows and columns are usually 1, and that there are additional file attributes found in the include file ATDSC3.EXT |
| PTRFLY3 | 8 | Pointer-flyer | A pointer-flyer observation file behaves much like a degenerate gridded file with NCOLS3D and NROWS3D set to 1, and certain mandatory variables and variable-naming conventions to be used by analysis and visualization software |