Because of the illconditioned nature of arithmetic relating to coordinate transformations, descriptive parameters are kept in double precision (identifier tokens and dimensioning parameters being of course integers).
Grids and coordinate systems (map projections) are
named entities, for purposes of unambiguous tracking and
database storage. Names are CHARACTER*16
strings
(consistent with the rest of the "name" objects manipulated
within the I/O system). There are finite (and extensible) lists of
names of coordinate systems and of grids currently in use within the
Models3 system. I would not anticipate that we should need more than a
few thousand such grids. So that they are fully selfcontained, both
names and complete descriptions for grids and coordinate systems (as
specified below) are kept in file headers, and stored also in file
description data structures in
FDESC3.EXT
or
fdesc3.h
.
There is a software subsystem for manipulating map projections, grids, and coordinates (see the UserManual section on Coordinate and Grid Related Routines). An implementation of grid parameter access capabilities is given by the DSCGRID() routine, which reads its accompanying ASCII data file GRIDDESC.
A sample GRIDDESC file describing the main computational grids for the SMRAQ regional seasonal modeling effort (part of the Southern Oxidant Study), the OTAG study, all of the standard ROM AQM computational grids, and all of the standard Urban Airshed Model computational grids is available.
Capabilities of this software subsystem include the following:
NOTE: Longitudes are presumed to be in the range
[180,180]
. This is consistent with dulyenacted ISO
Standard 6709, treaty obligations since 1878, and several centuries of
common usage (as well as virtually all of the currently available GIS or
mapping software). Beware that the WMO with its GRIB "standards"
violates all of these. When you deal with WMO "longitudes",
you will have to write specialpurpose modelingcode hacks to transform
longitudevalues into ISO6709 compliant form. Plotting WMOstyle
data against a map will be particularly troublesome; sorry.
The following types of coordinate systems are
supported.
They are identified by the use of
"magic number" token values as the GDTYP3D
in file description data structures such as those found in FDESC3.EXT
. The magic numbers
are specified in PARMS3.EXT
, which gives their
names as LATGRD3, LAMGRD3, MERGRD3, STEGRD3, UTMGRD3, POLGRD3,
TRMGRD3, EQMGRD3, ALBGRD3,
and LEQGRD3
They may be
identified by the corresponding map coordinate identifier, and further
specified by five additional descriptive parameters
PROJ_ALPHA
, PROJ_BETA
,
PROJ_GAMMA
, X_CENT
, and Y_CENT
.
Note that file descriptions contain all of these specifying parameters,
so that the files are selfcontained and do not require additional
griddescription support software systems.
TYPE  ID  PARAMETERS 

LatLon  LATGRD3 = 1

PROJ_ALPHA, PROJ_BETA, PROJ_GAMMA unused.
ISO 6709 compliant: coordinate units are degrees, 90.0 < X ≤ 90.0 and 180.0 < Y ≤ 180.0 GCTP projection 0. Note that Western hemisphere longitudes and Southern Hemisphere latitudes are taken to be negative. Note further that, in violation of treaty obligations and duly enacted international standards, and contrary to basically all the GIS software on the plaanet, the WMO insists upon a different, 0.0 < Y ≤ 360.0 interpretation of latitude for, e.g., GRIB files. This causes substantial difficulty for modelers. 
Lambert Conformal Conic  LAMGRD3 = 2

PROJ_ALPHA ≤ PROJ_BETA are the two latitudes which
determine the projection cone; PROJ_GAMMA is the central
meridian.
(X_CENT,Y_CENT) are the (lon ,lat) coordinates for the center (0,0) of the Cartesian coordinate system. Coordinate units are meters. GCTP projection 4. 
Mercator  MERGRD3 = 3

general Mercator
PROJ_ALPHA and PROJ_BETA are the latitude and longitude of the coordinate origin (within the tangent circle) PROJ_GAMMA is the angle between the cylinder axis and the North polar axis. (X_CENT,Y_CENT) are the (lon ,lat) coordinates for the center (0,0) of the Cartesian coordinate system. Coordinate units are meters. GCTP projection 20. 
Stereographic  STEGRD3 = 4

general tangent stereographic
PROJ_ALPHA is the "true latitude", the latitude at which the stereographic plane is secant to the Earth (or 90, if the projection is a North Polar tangent stereographic. PROJ_BETA is the angle of rotation of the Yaxis relative to the Greenwich meridian, i.e., the longitude meridian which becomes the negative Y axis. PROJ_GAMMA is unused. (X_CENT,Y_CENT) are the (lon ,lat) coordinates for the center (0,0) of the Cartesian coordinate system. Coordinate units are meters. GCTP projection 10. 
UTM  UTMGRD3 = 5

special case of Mercator
PROJ_ALPHA is the UTM zone, considered as a DOUBLE. PROJ_BETA and PROJ_GAMMA are unused. (X_CENT,Y_CENT) are the UTM coordinates of the origin for offset UTM coordinates (or are (0,0) for Equatorbased UTM coords). Coordinate units are meters. GCTP projection 1. 
Polar  POLGRD3 = 6

polar secant stereographic
PROJ_ALPHA is 1.0 for North Polar, 1.0 for South Polar. PROJ_BETA is the secant latitude (latitude of true scale), PROJ_GAMMA is the central meridian. (X_CENT,Y_CENT) are the (lon ,lat) coordinates for the center (0,0) of the Cartesian coordinate system. Coordinate units are meters. GCTP projection 6. 
Equatorial Mercator  EQMGRD3 = 7

PROJ_ALPHA is the latitude of true scale.
PROJ_BETA is unused. PROJ_GAMMA is the longitude of the central meridian. (X_CENT,Y_CENT) are the (lon ,lat) coordinates for the center (0,0) of the Cartesian coordinate system. Coordinate units are meters. GCTP projection 5. 
Transverse Mercator  TRMGRD3 = 8

PROJ_ALPHA is the latitude of true scale.
PROJ_BETA is the scale factor at the central meridian; PROJ_GAMMA is the longitude of the central meridian. (X_CENT,Y_CENT) are the (lon ,lat) coordinates for the center (0,0) of the Cartesian coordinate system. Coordinate units are meters. GCTP projection 9. 
Albers EqualArea Conic  ALBGRD3 = 9

PROJ_ALPHA ≤ PROJ_BETA are the two latitudes which
determine the projection cone; PROJ_GAMMA is the central
meridian.
(X_CENT,Y_CENT) are the (lon ,lat) coordinates for the center (0,0) of the Cartesian coordinate system. Coordinate units are meters. GCTP projection 3. 
Lambert Azimuthal EqualArea  LEQGRD3 = 10

PROJ_ALPHA is the central latitude; PROJ_GAMMA is the central
meridian.
(X_CENT,Y_CENT) are the (lon ,lat) coordinates for the center (0,0) of the Cartesian coordinate system. Coordinate units are meters. GCTP projection 11. 
Sinusoidal EqualArea  SINUGRD3 = 10
Added 5/5/2015 to I/O API3.1,3.2. 
PROJ_GAMMA is the central meridian.
(X_CENT,Y_CENT) are the (lon ,lat) coordinates for the center (0,0) of the Cartesian coordinate system. Coordinate units are meters. GCTP projection 16. 
Note that the standard names for UTM coordinate
systems are given in the form UTM_<nn>, where
nn is the number for the UTM zone, as counted from
ZONE 1: 180.0≤LAT≤174.0
. Most of the
Eastern US would use coordinate system UTM_17, for example.
Definitions of regular grids require four descriptive parameters and two dimensioning parameters in addition to the specification of a map projection. Note that while some variables are regarded as being cell based (emissions values, considered as celltotals, for example) and other variables are regarded as being point based (generally at the cellcenters; for example, surface temperature), the I/O API by convention uses cellbased descriptions for its grids:
Definitions of irregular and unstructured grids require a much more
complete setof descriptive parameters (e.g., the coordinates of the
grid origin and lists of cell sizes in both the X and
Y directions) in addition to the two dimensioning parameters
and map projection specifications. I do not know enough to suggest an
efficient characterization of such grids for Models3 at this time,
although irregular grids can certainly be handled by putting the grid
geometry information into its own data file (what you might term a
"grid geometry file". Note that the grid descriptions
supported directly by the I/O API deal only with regular grids at
this time (although it allows for the later provision of irregular or
unstructuredgrid file types).
Note 1 The MPAS EarthSystem model uses
unstructured Voronoicomplex grids (with their dual
DelaunayTriangulation grids) for meteorology, landsurface, ocean, and
atmospheric chemistry modeling. The I/O API provides some high
level I/O and grid utility data structures and routines in
MODULE MODMPASFIO
.
The required data structures are quite complicated :)
Note 2 The I/O API also provides some high level
I/O routines for "raw" netCDF gridded data in
MODULE MODNCFIO
.
Data files (or their generalizations) carry a complete set of parameters for both the map projection and the (regular) grid description as attributes (e.g., within the file headers), so that the files stand alone, independent of external database or software systems. This selfdescription within file should be regarded as the final authority on the file's contents, since it is not subject to corruption or loss in the same way that an external system is. (Of course, this puts the demand on users that they define their files correctly). Where defining parameters are not applicable (e.g., when one is creating an irregulargrid file with an accompanying geometry file, the nonapplicable parameters should be set to the standard "missing" values IMISS3 or BADVAL3 (defined in the PARMS.EXT INCLUDE file. The relationship between the defining parameters and the variables in FDESC.EXT INCLUDE file resident file description data structures is the following:
FDESC3.EXT
and
fdesc3.h
): vertical cordinate type specifier
VGTYP3D in FDESC3.EXT
and in file
headers takes values from a short list of vertical coordinate types
with tokens for the types defined in PARMS3.EXT
, as
follows:
GISLAY3
, and the filedescription should describe the GIS
layers in its FDESC3D
field.
The FDESC3.EXT
attribute NLAYS3D stores the actual number of layers in a
file. Parameter MXLAYS3 = 100 in PARMS3.EXT
is used for
dimensioning an array VGLVS3D(MXLAYS3+1) in
FDESC3.EXT
used to store the vertical coordinate values
for the file (up to the dimensioned maximum, although files may have
an actual number of layers in excess of this). The array section
VGLVS3D(1:NLAYS3D+1) contains valid values; subscripts in
excess of NLAYS3D+1 may well point to garbage. A new file
attribute VGTOP3D is used to store the MODELTOP for
the sigma coordinate types. For sigmaP coordinates, VGTOP3D is
given in Pascals; for sigmaZ, it is in meters.
Diagrams showing the relationship of the grid and its layers to the header attributes VGLVS3D, etc., are available in Postscript, X bitmap, JPEG, and GIF image formats. Note that Layer 1 is the bottom layer in the modeling grid.
VGTYP3D = IMISS is used when there is only one layer, and also when the vertical coordinate values VGLVS3D(MXLAYS3+1) are irrelevant (e.g., if the vertical coordinate value for the levels is spatially or temporally varying, in which case the values should be store as variables either in the same file or in an appropriate verticalgeometry file). In principle, layer K goes from VGLVS3D(K) to VGLVS3D(K+1). VGTOP3D is the "top of the model" parameter used for sigma types of coordinates, where generally the equation for sigma is of the form
sigma = ( X  X_top ) / ( X_bottom X_top ).For other types of coordinate, VGTOP3D is unused, and should be set to BADVAL3.
Note that FOO < AMISS3 is a safe and machine independent test to determine whether FOO has been set to BADVAL3.
Next Section: Dates and Times and Timeincrements
To: Models3/EDSS I/O API: The Help Pages