PIRCS Archive Format

Format for Transmitting Model Output to PIRCS Archive

Model output should be transmitting to PIRCS in one ASCII file containing control information for reading the output followed by a set of output files in IEEE754 floating point (32 bit) binary. The binary output requires a field ID number, available in Table 1 for the required output and Table 2 for the optional output. A table of representative values (Table 1) is available for guidance when preparing output for the archive. Please adhere carefully to the units assigned each variable in these tables!

ASCII FILE

The ASCII file provides general information to identify the model and gives control data for reading the output. It also has some redundancy with the binary output to help maintain proper identity of the binary files.
The file should be named IDDDDD.CONTROL, where IDDDDD is the 6-character identifier string in line 1 below.
The file should contain at a minimum 8 lines:

Line Information

1 A model ID (character variable; A6 format). This ID should be the prefix to all files sent to the PIRCS archive (see "File naming convention" under BINARY FILES, section 3(a))

2 Start day (3 integers in year, month, day order in I5 format; 4-digit year that includes century, i.e. 1988 not 88)

3 End day (3 integers in year, month, day order in I5 format; 4-digit year)

4 Number of "latitudes" (gridpoints in y-direction of model output grid; 1 integer in I5 format)

5 Number of "longitudes" (gridpoints in x-direction of model output grid; 1 integer in I5 format)

6 Vertical grid identifier (1 integer in I5 format) and type of vertical output grid (e.g., sigma, hybrid sigma-pressure, etc.; character variable, A24 format)
Key for identifier: = 0 - standard pressure levels = 1 - alternative pressure levels = 2 - sigma levels = 3 - other

7 Number of vertical levels (1 integer in I5 format)

8 Byte-order indicator (character variable; A6 format). Enter "BIG..." or "LITTLE" to indicate whether your machine uses "big endian" or "little-endian" byte order for floating-point numbers. Consult your system's 'man' pages or other documentation to find which ordering it uses.

9-12 The file may contain up to 4 additional lines, 80 characters wide, of additional comments.

Line	Information
1	A model ID (character variable; A6 format). This ID should be the prefix to all files sent to the PIRCS archive (see "File naming convention" under BINARY FILES, section 3(a))
2	Start day (3 integers in year, month, day order in I5 format; 4-digit year that includes century, i.e. 1988 not 88)
3	End day (3 integers in year, month, day order in I5 format; 4-digit year)
4	Number of "latitudes" (gridpoints in y-direction of model output grid; 1 integer in I5 format)
5	Number of "longitudes" (gridpoints in x-direction of model output grid; 1 integer in I5 format)
6	Vertical grid identifier (1 integer in I5 format) and type of vertical output grid (e.g., sigma, hybrid sigma-pressure, etc.; character variable, A24 format) Key for identifier: = 0 - standard pressure levels = 1 - alternative pressure levels = 2 - sigma levels = 3 - other
7	Number of vertical levels (1 integer in I5 format)
8	Byte-order indicator (character variable; A6 format). Enter "BIG..." or "LITTLE" to indicate whether your machine uses "big endian" or "little-endian" byte order for floating-point numbers. Consult your system's 'man' pages or other documentation to find which ordering it uses.
9-12	The file may contain up to 4 additional lines, 80 characters wide, of additional comments.

BINARY FILES

1. General structure

Output should be stratified as follows, with "Output field" representing the coarsest division of the output and "Longitude" representing the finest.
Output field	<- coarsest
Date/time
Height
Latitude
Longitude	<- finest
The terms "latitude" and "longitude" are used loosely in this document to refer to the model's Y and X coordinates, respectively, where Y increases approximately from south to north and X increases approximately from west to east. It is not necessarily implied that the data should be interpolated to an actual latitude-longitude grid.

2. Order

Output and related reference fields are to be reported in the order given on the PIRCS web page tables:
Table 1 for the required output and
Table 2 for the optional output.

3. Files

(a) File naming convention: IDDDDD.FIELD.YYYY.MM.DD
where

IDDDDD is the 6 character model ID given in the ASCII file
FIELD is a 6 character field name given at the PIRCS web site
YYYY.MM.DD is the year (4 digits), month and day on which the run ends
An example of a properly constructed file name is: NCPRSM.6HGEOP.1988.07.15
(b) Output should be written as one file per output field (estimated as 2-15 Mb per 60-days for single-level fields, 120 mb per 60-days for three-dimensional fields).
(c) For min/max temperatures, report the times of minimum and times of maximum in separate files from the actual values of minimum or maximum temperatures.

4. Horizontal grid

(a) All requested fields should be reported on the same horizontal grid. For models that stagger variables horizontally, output should be interpolated horizontally to a common grid. When interpolation is needed, it is recommended that wind fields be interpolated to the grid used for mass and temperature variables.
(b) When writing two-dimensional (horizontal) fields:

Start in the southwest corner and proceed "eastward" in model's x direction
Increment latitude from south to north, always writing from the latitude's westernmost point toward the easternmost.

(c) When writing three-dimensional fields:

Write output as a sequence of two-dimensional (horizontal) fields.
Start with atmospheric layer closest to surface.
Proceed upward to layer farthest from surface.

5. Vertical grid

(a) All requested three-dimensional fields should be reported at the same levels, without vertical staggering. If the model does stagger variables in the vertical, then all fields should be interpolated to a common vertical grid.
(b) Output from models using a sigma coordinate should be reported on the sigma grid. Sigma levels of the output should be listed in the vertical-coordinate reference file from the surface upward, with sigma values listed as numbers in the range [1,0].
(c) Output from other models also should be presented on the model's vertical grid if there is a straightforward procedure giving the pressure levels corresponding to the model's vertical grid points.
(d) When such a procedure is not available, other models should report output interpolated/extrapolated to the following pressure levels. This is the least desirable option and should be used only as a last resort when it would be effectively impossible to recover the pressure on the model grid. Data are to be interpolated to these 23 pressure levels:

1025 mb, 1000 mb, ... (every 25 mb) ... , 600 mb, 500 mb, 400 mb, 300 mb, 200 mb, 100 mb
If output is reported on this grid, then in the ASCII control file, the grid should be described as the "standard pressure grid".
(e) When writing fields, go from the lowest layer of the model atmosphere toward the top of the model atmosphere.

6. Binary standard

Files should be written as unformatted output in IEEE754 floating point (32 bit) binary.
The IEEE754 format can typically be specified as a compiler option and may be the default format on some systems. If byte ordering can be specified please use "big endian" byte order. Consult your system's "man" pages or other documentation to find any compiler switches that are necessary to specify this format.
For those computing on a 64-bit machine, please note that the IEE754 standard considers 64-bit floating point numbers as double precision. For cross-platform compatibility of the archive, it is imperative that the output be written as 32-bit.

7. Writing to files

(a) General header:
The first record written in an output file is to contain

Output field ID number (not the 6-character form of the ID), as given in the tables for the required and supplementary output (1 floating point number)
Start day (3 floating point numbers in day, month, year order)
End day (3 floating point numbers in day, month, year order)
Number of latitudes (gridpoints in y-direction of model grid; 1 floating point number)
Number of longitudes (gridpoints in x-direction of model grid; 1 floating point number)
Number of vertical levels (1 floating point number)
(These are to be written with a single write statement, i.e., the information above consists of one record)
(b) Individual time-step header:
Before each date/time block of output, write a record containing

Model date (3 floating point numbers in day, month, year order)
Model time (UTC in seconds after 00 UTC; i.e. 1 floating point number in the range 0-86400)

Note that for cumulative fields, such as precipitation, the model time is the ending time of the accumulation period.
(c) For two-dimensional fields, each write record is to contain values for all x-direction gridpoints along one "latitude" (y gridpoint).
(d) Three-dimensional fields are to be written as a sequence of two-dimensional fields ordered from the atmospheric layer closest to the surface to the layer farthest from the surface. Thus, for one atmospheric layer, each write record should contain values for all x-direction gridpoints along one "latitude" (y gridpoint), and the records should be ordered from southernmost latitude to northernmost.

8. The first time to report each field.

(a) For three-hourly mass and temperature fields and all six-hourly fields, the first reporting time is the start of the simulation (00 UTC on starting day).
(b) For three-hourly cumulative fluxes and precipitation, the first reporting time is after the initial 3 hours of simulation (03 UTC on starting day).
(c) For daily values, see Table 1 .
(d) For supplemental ("B-list") output, follow 8(a) for instantaneously sampled fields and 8(b) for cumulative and time-average fields.

Return to Experiment 1 Diagnostics

Return to Workshop II Summary