The Library of AMIP Data Transmission Standards

Click here to obtain LATS through the web.

Contents

• Overview
• Basic characteristics
• Usage
• Guidelines for AMIP users
• Sample Subroutines for AMIP Users: monthly and 6hour
• LATS Format and Convention Options: Pros and Cons
• Design Constraints and Resulting Limitation
• Planned Enhancements
• LATS man page
• LATS parameter tables and man page
• Obtaining the LATS distribution, including sample code
• Web resources

Overview

LATS applications output data in either the WMO "GRIdded Binary" (GRIB) format or in the NetCDF format under the COARDS convention. LATS-generated data written according to the GRIB or COARDS conventions is readily accessible by CDAT, GrADS or EzGET.  A variety of other software packages recognize the NetCDF COARDS convention.

However, rather rigid constraints are placed on the structure (e.g., dimension ordering) of data written and thus in its current form LATS is not be considered a general purpose gridded data output system. These constraints are a consequence of the following design criteria:

• Simple to use
• Multi-platform
• Targeted for GCM output (currently limited to rectilinear data)
• Implement and establish conventions for data and metadata
• Use of two well-established and freqently used formats
• Software to be publicly available and free of charge

Basic Features of LATS

• LATS outputs rectilinear, gridded, spatio-temporal data. The fundamental unit of data written with a single function call is a horizontal longitude-latitude slice of a variable. However, derivative structures such as zonal mean-height cross sections (i.e., a sequence of single-longitude, multiple-latitude grids) are supported.
• LATS data written in either GRIB and/or netCDF are machine independent.
• LATS maintains an internal parameter table that prescribes variable names, description, units, datatype, basic structure (e.g., upper air or surface), and compression (GRIB options). These descriptors are inferred from the parameter name only. Thus, most of the metadata needed to write GRIB and/or netCDF data are located in the parameter table to simplify the API.
• An option is provided to override the internal table with an external parameter file. LATS parameter tables are designed to fit specific needs, such as those of AMIP and CMIP.
• More than one LATS file may be open simultaneously for output.
• For a given timepoint, multiple variables and variables at multiple levels may be written in any order.
• Data can only be written in increasing time sequence.
• All data are floating-point or integer. Only FORTRAN REALS (C floats) and INTEGERS (C ints) can be written

• All variables written to a given file must share a common frequency (e.g., hourly, daily, monthly, etc.).
• All fields must be rectilinear gridded data (e.g., Gaussian grid data is acceptable, but "thinned" Gaussian grid data - where the number of longitude grid points is a function of latitude - is not).
• All variables must be declared (including all their dimensions and attributes)  before any numerical data are written to a LATS file.
• All variables for a given time slice must be written before proceeding to the next time slice

Usage

1. Specify an external parameter table file, with lats_parmtab.

2. Define all grid(s), with lats_grid.

3. Define all vertical dimensions (e.g., pressure level) with lats_vert_dim. If a default surface dimension is defined for a variable, it does not have to be redefined with lats_vert_dim. Grids and vertical dimensions may be shared across variables and files. NOTE: At present, only one grid may be defined per GrADS/GRIB file.

4. Create a LATS file, with lats_create.

4a. Optionally set the basetime, with lats_basetime

5. For each variable to be written to the file: Declare the variable with lats_var. (Note: this is required even if the variable has been declared for a different file)

If there is a missing data flag, define it with lats_miss_float or lats_miss_int.

6. For each time-point, in increasing time order: For each horizontal level of each variable: Write the data for this level, time-point, with lats_write.

7. Close the file, with lats_close.

The LATS distribution comes with a sample FORTRAN code and detailed instructions on creating LATS applications. This program is used to verify that LATS is working properly on your system. Furthermore, the distribution is self contained, i.e., all materials needed for creating LATS applications are included, ranging from the libraries and utilities to documentation on setup and application building. Consult the LATS man pages for a detailed description of the LATS programming interface.

Guidelines for AMIP II Users

• Establish contact with LATS support (lats@pcmdi.llnl.gov) when you begin using LATS.  First process only two simulation years, and send it to the AMIP Project Office (or make it ftp available) so that it can be verified that LATS is working properly.
• Use the most recent version of the AMIP parameter table.  Contact LATS support if you believe any modifications to this table are necessary for your application. Note: the variable names and units for each field are specified in the parameter file.
• Use only the LATS_COARDS or LATS_GRADS_GRIB conventions. Data produced with the GRADS_GRIB convention can be read with VCS, GrADS and EZGET.  netCDF data produced with the COARDS convention can be read with these and many other applications.
• Use the same base time (in the lats_basetime call) for all files.
• The time sequence and sampling frequency should be clearly identified in the file name (e.g., "...jan79_dec79mm", where the "mm' denotes monthly means).

• Please make sure that the time information specified in the LATS_write call is correct.
• All data must be on the same model grid (i.e., staggered grid data should be interpolated).
• For ALL data associated with intervals of time, such as 6-hour accumulations and averages set the valid time in lats_write to the value at the beginning of the interval.
• Grid orientation: monotonically increasing in latitude and longitude, no wrap-around points (e.g., 72 points, 0 to 355 degrees).
• Grid orientation: start at Greenwich meridian and south pole.

LATS Format and Convention Options: Pros and Cons

Convention options:

LATS_PCMDI (netCDF): Permits the use of calendars other than the standard Gregorian calendar. Other than the calendar options, this option is at present consistent with the COARDS conventions. Future releases may provide other extensions beyond the COARDS convention. Files created with this convention may be used with all netCDF utilities, except those that require the COARDS convention (e.g., GrADS). As this is an evolving convention, its use in AMIP II is not supported.

LATS_COARDS (netCDF): Compliant with the COARDS metadata standard . If this convention is chosen, the calendar must be specified to be Gregorian (LATS_STANDARD calendar). Internally, monthly data are represented in units of "days since (basetime)". Climatology data are assumed if year = 2. Fixed fields (e.g., topography) is assigned the year 1.

LATS_GRADS_GRIB: WMO GRIB format (GRIB), plus a GrADS control file and a GRIB map file. Variables must be defined on the same horizontal grid. Supports, all calendar options except Julian and 360-day years.

LATS_GRIB_ONLY: WMO GRIB only. The delta (see LATS man page) may be zero. This convention is the most general, but may not be readily interfaced to VCS and GrADS. Appropriate for straight data transmission with no need for direct data interface.

Data format pros and cons:

netCDF - advantages: There is a wide range of tools available for netCDF data, and it is used extensively in the atmospheric science research community, particularly among universities. The netCDF data model is general and flexible. All quality controlled AMIP data released to diagnostic subprojects will be in netCDF.

netCDF - disadvantages: Requires installation and use of the netCDF libraries. For some platforms, netCDF version 2.4 or greater must be used for performance reasons. At present, LATS does not support the COARDS data compression (offset plus scaling to 16-bit integers) option, but will do so in a future release. Data writing and reading can be much slower than GRIB, particularly for large grids (e.g., 360x180 points).

GRIB - advantages: GRIB is a WMO standard and is widely used at most numerical weather prediction centers (e.g, ECMWF and NCEP). GRIB features flexible compression options on a variable-by-variable basis and the binary format is generally simple. For AMIP II high frequency (6-h) data, GRIB files will be on average 2.5 times smaller than netCDF format, i.e., a space savings of ~60%.

GRIB - disadvantages: GRIB is primarily a physical format with metadata defined for each 2-D grid (i.e., a "GRIB message") only. Thus, GRIB data cannot be organized internally as higher dimensional data sets. The higher dimensional structure achieved in the LATS_GRADS_GRIB convention is though a mapping function not part of the format. For example, all variables in a file must share the same vertical dimension, and multilevel variables must share the same vertical dimension.  Beyond the GrADS interface, there are no standard programming interfaces and a variety of GRIB 'flavors' (LATS uses WMO GRIB Edition 1 and the NCEP tradition) have evolved complicating interface building.

Design Constraints and Resulting Limitations

Although four conventions may seem complex, it is symptomatic of the wide variation in existing data sets as conventions are often specific to an individual. The purpose of a convention is to improve the efficiency of a group and the lack of conventions for AMIP I was very costly to PCMDI as we had to bring the disparate data sets (all 30 model data sets were different) to some common standard. Relative to AMIP I, four conventions will greatly improve the efficiency of PCMDI and our ability to support analysis of the AMIP II results.

While the valid year of a climatology field may have no mean, it is generally required by data interfaces. LATS internally sets a time convention for climatology and fixed fields. Again, there are no obvious standards for describing the valid time of climatology or fields such topography. Thus, we have arbitrarily set the valid year of a data written under the climatology calendars to the year 2 AD and fixed fields to 1 AD.

CDAT, EZGET (a Fortran interface) and GrADS can read both GRADS_GRIB and netCDF (COARDS) LATS-generated data. FERRET, and many other applications  can be used to access the  netCDF (COARDS) LATS-generated data.  EZGET users creating applications that link to both EZGET and LATS may experience problems because of compiler-dependent resolution of externals (functions). The issue is compatibiliity between cdunif and lats routines which is now being corrected at PCMDI.

Planned enhancements

• Predefined quality control values for the AMIP II Standard Model Output.
• Improved treatment for storage of latitude-height (e.g., zonal means) fields.
• Support for a richer set of grid types (zonal fields, thin grids, preprojected grids, etc.).
• Enhanced error trapping
• Port to MS-DOS / Win32 Operating Systems
• Support COARDS compression for netCDF data.

Obtaining LATS

The LATS (latest version) source code for is available, and  has been built on the following platforms:
 

Distribution Name	Machine	uname -a	Latest version available
source code	-	-	LATS 1.5
aix	IBM RS4000	AIX 2 3 000039577000	LATS 1.0
alpha	DEC Alpha	OSF1 V3.2 41.64 alpha	LATS 1.5
c90	CRAY C90	sn4005 8.0.4 u31.20 CRAY C90	LATS 1.3
hpux	HP	HP-UX A.09.01 A 9000/755	LATS 1.3
irix4	SGI	IRIX 4.0.5 06151813 IP12	LATS 1.0
irix5	SGI	IRIX 5.3 11091812 IP22 mips	LATS 1.3
irix6	SGI	IRIX 6.2	LATS 1.5
j90	CRAY J90	sn9550 9.0.2.2 car.6 CRAY J90	LATS 1.5
linux	x86 PC	Linux 2.0.21 #5	LATS 1.0
sol2	SUN	SunOS 5.5.1 Generic_103640-03 sun4d	LATS 1.5
sunos4	SUN	SunOS 4.1.3 1 sun4m	LATS 1.5

If your system does not exactly match, try a version which is close. The libraries will generally work within operating system major versions (e.g., 2 in version 2.5.1 of Solaris (now called 5.5.1) or with an OS at a higher version (e.g., V3.0 LATS will often work in OS V4.0). LATS built on system with a higher version than that of the target system may work, so try the library for your platform.

If you are unable to find a compatible version, then please contact lats support (lats@pcmdi.llnl.gov).
 

Web resources

Last update July 15, 1998. For further information, contact the AMIP Project Office (amip@pcmdi.llnl.gov) or lats@pcmdi.llnl.gov.

LLNL Disclaimers

UCRL-MI-125598