GAMAP v2–19 User Guide

Previous | Next | Printable View (no frames)

6. GAMAP data formats and data structures

6.1 ASCII "punch" file format

This is the original data format developed by M. Prather (now at UC Irvine) for the old 9-layer Harvard CTM driven by GISS–II meteorology.  This file format is still used by some older versions of the GISS 9 and 23 layer models. This output file is format has largely been supplanted by both the binary punch format and the netCDF format.

The chief advantage of the ASCII "punch" files is that they can be read easily by Fortran, IDL, or S-Plus code running on either big-endian or little-endian machines. Their main disadvantatage is that they only allow for 2 decimal places of precision, which leads to truncation errors in the diagnostic output.

Here is what the top of an ASCII punch file looks like. The first line is the top-of-file header. The next lines is the header for the first level of the first data block, followed by sample data lines in '(12f6.2)' format.

GLOBAL-RUN--4X5+SOM-PFILT--CTM version 1.0 (3/93 Prather)    24 72 46 20  0  0  1985
  IJ-AVG-1  276    2     75960     76680 1.000E-10    72  46   0 

288.86288.86288.90288.90288.92288.96288.96288.98288.99289.00289.01289.01 
289.01289.02289.01289.00289.01289.02289.00289.01289.02289.02289.03289.04

Note that in the ASCII punch file, each level is stored as a 2-D data block. Therefore, the data for the second level will have the category IJ-AVG-2, etc.

6.2 Binary output ("punch") file format (version 2.0)

The binary "punch" file format (v. 2.0) is now the standard data format used by the GEOS-Chem model.  This format was designed to facilitate smooth interaction with GAMAP.  A binary punch file also loads much faster and typically only requires 2/3 as much disk space as the equivalent ASCII punch file.  This section describes the binary punch file format version 2.0.

6.2.1 General header for binary output files

6.2.2 Datablock header for binary output files

First line of datablock header:

Second line of datablock header:

These two header lines are followed by the data block (REAL*4).

NOTE: While "multilevel" diagnostics are stored as individual layers in ASCII files, they are stored as 3D blocks in binary files.  Category names are then e.g. IJ-AVG-$ instead of IJ-AVG-1, IJ-AVG-2, etc

6.3 COARDS-compliant netCDF files

6.3.1 Overview

GAMAP can read data from COARDS-compliant netCDF files. This is a regular netCDF file which adheres to a standard set of dimension and attribute names. In particular:

1. Standard names for dimensions:

   • time (minutes, days, or years from a specified reference time)
   • lev (# of levels in grid)
   • lat (# of latitudes in grid)
   • lon (# of longitudes in grid)

2. Each index array has the same name as its dimension. Therefore, the lon dimension is used to define the lon index array, etc.

3. Also index array values must be listed as monotonically increasing or decreasing.

4. Standard attribute names for each variable stored in the netCDF file. In particular, the most important of these are:

   • long_name: A longer description of the variable and what it represents.
   • units: The units carried by the variable.

5. The time dimension should also have a calendar attribute, which may be:

   • gregorian: Describes a gregorian calendar with leap years (used by GEOS-Chem)
   • noleap: Describes a 365 day calendar w/o leap years.

For more information about the COARDS standards, please see this web page.

6.3.2 Reading COARDS-compliant netCDF files from disk

The main GAMAP program (as well as the lower-level routines like CTM_GET_DATA, CTM_GET_DATABLOCK) can read directly from COARDS-compliant netCDF files. The only limitation (at present) is that information about the tracer (i.e. category and tracer number) category and tracer name must be present in the diaginfo.dat and tracerinfo.dat files.

You can also read any netCDF file directly with helper routine NCDF_READ. This routine will return a structure containing all of the variables and attributes in the netCDF file.

6.3.3 Writing COARDS-compliant netCDF files from disk

GAMAP routine BPCH2COARDS can convert a bpch file to a COARDS-compliant netCDF file. This may be used in conjunction with routine MAKE_MULTI_NC to convert several bpch files in a single session.

6.4 The FILEINFO structure

Contains information about a file that has been accessed in a GAMAP session. For each file read by GAMAP, a corresponding FILEINFO structure is stored in a global common block. The global common block is accessible via the include statement @gamap_cmn.

6.4.1 Structure tag names for FILEINFO

GAMAP uses function CREATE3DFSTRU to create new FILEINFO structure(s).

NOTE: The correspondence between IDL and FORTRAN data types is as follows

• IDL fix = Fortran INTEGER*2
• IDL long = Fortran INTEGER*4
• IDL float = Fortran REAL*4
• IDL double = Fortran REAL*8

6.5 The DATAINFO structure

Contains information about each data record that is in a model file. If a new file is opened, the complete header information is parsed once and the location of the individual data blocks is saved. Therefore, subsequent access is really fast.

6.5.1 Structure tag names for DATAINFO

Use function CREATE3DHSTRU to create new DATAINFO structure(s).

NOTE: The correspondence between IDL and FORTRAN data types is as follows

• IDL fix = Fortran INTEGER*2
• IDL long = Fortran INTEGER*4
• IDL double long = Fortran INTEGER*8
• IDL float = Fortran REAL*4
• IDL double = Fortran REAL*8

6.6 The MODELINFO structure

This structure holds basic information about the model so that a grid can be computed.

6.6.1 General usage

ModelInfo = CTM_Type( modelname [, options] )

6.6.2 Example

ModelInfo = CTM_Type( `GEOS_3', resolution=4 )

6.6.3 Structure tag names for MODELINFO

Most parameters are automatically set to the correct values in function CTM_TYPE, so you only need to provide the model name and resolution.

NOTE: The correspondence between IDL and FORTRAN data types is as follows

• IDL fix = Fortran INTEGER*2
• IDL long = Fortran INTEGER*4
• IDL float = Fortran REAL*4
• IDL double = Fortran REAL*8

6.7 The GRIDINFO structure

This structure holds the actual grid for the data set (both horizontal and vertical).  It is created from the information stored in MODELINFO, but may be frequently re-generated e.g to accomodate for different surface pressures.  The GRIDINFO structure is generated by a call to ctm_grid.pro (see below).

6.7.1 General usage

GridInfo = CTM_Grid( ModelInfo )

6.7.2 Example

ModelInfo = ctm_type( 'GEOS_3', resolution=4 )
 
; To have the GRIDINFO structure contain vertical layers 
GridInfo = ctm_grid( ModelInfo ) 
 
; To suppress vertical layers from the GRIDINFO structure 
GridInfo = ctm_grid( ModelInfo, /No_Vertical )

6.7.3 Structure Tag Names for GRIDINFO

When GRIDINFO contains vertical information (i.e. when the /NO_VERTICAL keyword to CTM_GRID is omitted), then the following fields are added:

The computation of pressures and altitudes may at some point be improved to allow for different surface pressures for individual grid boxes.  However, this can be pretty complicated in terms of averaging.

NOTE: The correspondence between IDL and FORTRAN data types is as follows:

• IDL fix = Fortran INTEGER*2
• IDL long = Fortran INTEGER*4
• IDL float = Fortran REAL*4
• IDL double = Fortran REAL*8

6.8 The TRACERINFO structure

This structure contains information about the various quantities stored in the model output.  Tracers are indexed by number, and the number is usually identical to the tracer number used in the model, but it may be offset by a multiple of a large number (usually 100 or 1000) to distinguish between different diagnostics.

This structure will be returned from procedure ctm_tracerinfo.pro.  The information about all tracers is stored in the file tracerinfo.dat.  This file is only read once, however, it can be reloaded with:

ctm_tracerinfo, /force_reading

You can pass either a tracer name or number to ctm_tracerinfo.pro.

6.8.1 Structure Tag Names for TRACERINFO

NOTE: The correspondence between IDL and FORTRAN data types is as follows:

• IDL fix = Fortran INTEGER*2
• IDL long = Fortran INTEGER*4
• IDL float = Fortran REAL*4
• IDL double = Fortran REAL*8

6.9 The DIAGINFO structure

This structure holds information about the individual diagnostics from all models.  It is be returned from procedure ctm_diaginfo.pro. The information about all diagnostics is stored in the file diaginfo.dat.  This file is only read once, however, it can be reloaded with

ctm_diaginfo, /force_reading

You can pass either a category name or diagnostic number to ctm_tracerinfo.pro. Note, however, that category names are unique, while numbers may be used repeatedly (e.g. 45 for IJ-AVG-$, 43 for CHEM-L=$).