GAMAP v2–19 User Guide

Previous | Next | Printable View (no frames)

1. Introduction to GAMAP

1.1 Overview

GAMAP, the Global Atmospheric Model (output) Analysis Package, is a collection of programs which facilitates analysis of CTM (Chemical Transport Model) data. The distribution file contains several source code directories, each of which contains source code routines that have been grouped by functionality.

GAMAP is written in IDL (Interactive Data Language by Exelis Visual Information Solutons, formerly ITT Visualization) and requires IDL version 5.5 or higher. The package provides an easy-to-use text-based interactive interface to fulfill most basic plotting needs for CTM output, including map plots, vertical cross sections, zonal means, etc. Since GAMAP v1–30, animation and multi-panel plots have been supported. But, as the name suggests, GAMAP is more than a simple analysis program: the package provides a collection of high level routines that allows you to analyze atmospheric model output as well.

GAMAP v2–19 read data from the following file formats:

• GISS–II style ASCII output files (a.k.a. "ASCII punch" files)
• GEOS–Chem binary output files (a.k.a. "binary punch" files)
• GEOS–Chem binary meteorological field input files
• HDF4–EOS files (such as are created by NASA/Global Modeling & Assimilation Office)
• netCDF files adhering to the COARDS file convention
• netCDF files created by GAMAP routines and BPCH2COARDS
• netCDF files created by the Global Modeling Initiative (GMI) at NASA/GSFC

GAMAP v2–19 also contains routines which can be used to convert 2D, 3D, or 4D data arrays from other sources into a GAMAP datainfo record so that it can be displayed with the GAMAP plotting routines.

With GAMAP routines CTM_DIFF and CTM_SUM, it is possible to plot differences between or averages of individual data records. Another GAMAP routine, CTM_SUM_EMISSIONS, allows you to compute emission totals in Tg, Gg, or Mg.

NOTE: GAMAP was developed at Harvard University. Its authors are partly funded by government money. Therefore, it is probably OK to offer GAMAP as freeware to users outside of Harvard. However, we urge you to keep the copyright notice with each file and clearly mark changes that you make to any subroutine. We would be extremely happy to hear of any improvements you make (and of errors you find and correct). Please understand that we can give only minimal support beyond this document to external users.

1.2 Summary of new features in GAMAP

Here is a summary of the most important changes in GAMAP since v1–50. For a more detailed list of revisions and documentation, please see Chapter 5: GAMAP Reference.

GAMAP v2–19 (16 Dec 2016)

• Updated the benchmark plotting routines for consistency with GEOS–Chem v11–01
• Added support for MERRA-2 horizontal and vertical grids
• Added PLOT_GPROF routine to plot output obtained with the GNU profiler (gprof)

GAMAP v2–18 (01 May 2015)

• Updated the benchmark plotting routines for consistency with GEOS–Chem v10–01
  • For most emission species, plot anthro + biofuel because these are lumped together by HEMCO
  • Added routines to plot emission maps and emission differences
  • Added updates to plot diagnostic ouptut from the RRTMG and UCX simulations
• Several updates to BPCH2COARDS, which converts bpch files to netCDF format:
  • Improved the handling of 4D data blocks
  • Ensure that longitudes are always monotonically increasing (this is required by the COARDS standard)
  • Define dimensions in this order: time, lev (if needed), lat, lon
  • Add more variable and global attributes for better COARDS compliance

GAMAP v2–17 (24 Jan 2014)

• Updated the benchmark plotting routines for consistency with GEOS–Chem v9–02
• Introduced compatibility with GEOS-FP met data
• Improved the vertical regridding routine REGRID_COLUMN
• Improved netCDF file I/O capability with updated routines:
  • BPCH2COARDS
  • CTM_READ_COARDS
• Improved routine READDATA so that it can:
  • read data from files having up to 200,000 lines
  • read files containing "NaN" values
• Added flexible colorbar scaling in TVMAP and TVPLOT (with the /CBSCALE option)
• Now can read binary punch files larger than 2.4 GB in size

GAMAP v2–15 (11 Feb 2011; Patch 08 Jun 2011)

• More updates for compatibility with MERRA met data
• New function MAKE_PDF converts PostScript to PDF output
• Improvements to routines CTM_GRID, CTM_TYPE, GETETA, BPCH2NC for handling hybrid grids
• Add /NOERASE keyword to TVPLOT to make it operate in the same way as TVMAP
• Plotting codes used to create plots from GEOSChem 1-month benchmark simulations are now part of the GAMAP package
• Routine COLORBAR now contains the UPOS keyword, which allows you to explicity control the placement of the colorbar unit string.
• Modifications to the auto-documentation code used to create the GAMAP reference pages
• New routine CTM_PLOTDIFF4 for creating 4-panel plots
• Other minor fixes

GAMAP v2–14 (09 Aug 2010)

• Updates for reading and plotting MERRA met data
• Now allow polar maps to use pixel plots
• New function FIND_TRACER_INDEX returns the tracer number given the diagnostic category and tracer name
• Minor fixes in several plotting routines (CTM_OVERLAY, CTM_PLOTDIFF)
• Minor fixes in timeseries routines

GAMAP v2–13 (15 Oct 2009)

• User-defined colortable in MYCT
• New routine to retrieve an air number density for GEOS–Chem
• New routine to recursively convert binary punch (bpch) files into netCDF format
• New updates to TVMAP, TVPLOT, and CTM_PLOTDIFF
• Many other minor fixes

GAMAP v2–12 (17 Jul 2008)

• Added several new colortables to MYCT, including all of the ColorBrewer tables. The user may now select a colortable via an interactive dialog box.
• TVMAP may now be used with any of the IDL map projections. Some minor issues from the previous version have now been resolved.
• Various minor updates and fixes in several routines.
• A GAMAP section has been added to the GEOS–Chem wiki site. Some helpful tips and tricks and other examples are posted here.

GAMAP v2–11 (03 Dec 2007)

• New map projections (e.g. Lambert, Mollweide, Continental US, etc.) are now available for all types of plots
• The MYCT drawing colors have been modified so that they are less saturated and look better on the screen
• Routines have been included for reading GEOS–Chem time series output (4D data: lon, lat, alt, time)
• COLORBAR can now draw triangles to denote values beyond the min & max values that are displayed

GAMAP v2–10 (31 Jul 2007)

• Now can read GEOS–5 data
• Now includes several customized color tables
• Now includes expanded on-line documentation
• Now can read 4D data blocks (lon, lat, alt, time)

GAMAP v2–05 (16 Oct 2006)

• New routine: CTM_OVERLAY can be used to overplot data atop an image map
• New routine: FIND_CELLS_BY_COUNTRY can be used to find which grid boxes belong to a given country
• New routine: PLOT_CPD can be used to plot cumulative probability plots
• New routines for time and date: ADD_DATE, DATE2YMD, YMD2DATE
• Updated routine: CTM_EXAMPLES shows how to make certain kinds of plots
• Updated routine: CTM_REGRIDH now regrids from coarse to fine grids in a more correct manner
• Updated routine: QQNORM now uses simpler algorithm
• Updated routine: CTM_GRID now can handle multi-level "GENERIC" grids
• Updated routine: BPCH_SEP now can save out a subset of the globe or a given tracer
• Updated routine: MYCT can now use the red-white-blue "difference" colortable
• Regridding routine CTM_GETWEIGHT updated for 1 x 1.25 grids
• New colortable for differences (negatives=blue, positives=red, zero=white)
• Other minor fixes and improvements

GAMAP v2–04 (08 Feb 2006)

• Bug fix: now can read HDF, HDF–EOS, netCDF files when using dialog box to specify filename
• gamap.pro main routine now trims white space from the input filename
• Now tests properly for GCAP met field files
• Various minor updates to TVMAP, TVPLOT and other routines

GAMAP v2–03 (11 Apr 2005)

• GAMAP can now read COARDS-compliant netCDF files
• New routine CTM_READ_PLANEFLIGHT reads GEOS–CHEM planeflight diagnostic data
• BPCH2COARDS now allows you to convert data from binary punch file to COARDS netCDF format
• BPCH2ASCII, BPCH2HDF, BPCH2NC now allow you to select data blocks by category
• Routine CTM_CLEANUP now also clears all heap variable and pointer memory
• The user may suppress screen output in routines CTM_GET_DATA and CTM_GET_DATABLOCK
• CTM_SUM_EMISSIONS can now report totals in Tg, Gg, or Mg

GAMAP v2–02 (04 Jun 2004)

• Added tickmarks to GAMAP color bar; can now also flag a specific value
• TOOLS routine MFINDFILE now calls the new IDL FILE_SEARCH() routine for IDL 5.5+
• Added OMARGIN and MARGIN keywords to TVMAP and TVPLOT to better specify plot positions
• Bug fix: Now can read all months of data stored within a GMI netCDF file
• Bug fix: Now avoid infinite loop when reading ASCII punch files (e.g. from GISS model)
• Bug fix: GEOS–4 has 17 purely tropospheric levels, not 18.
• Bug fix: When reading HDF–EOS files, if model type is undetermined, it asks user to supply the model type
• Updated comments, removed obsolete features