List routines by category:
Atmospheric Sciences |
Benchmarking |
Color |
Date/Time |
Doc |
File & I/O |
BPCH Format |
Scientific Data Formats |
GAMAP Examples |
GAMAP Internals |
GAMAP Utilities |
GAMAP Data Manipulation |
GAMAP Models &
Grids |
GAMAP Plotting |
General |
Graphics |
Math & Units |
Plotting |
Regridding |
Strings |
Structures |
Time Series
List routines by alphabetical order:
A |
B |
C |
D |
E |
F |
G |
H |
I |
J |
K |
L |
M |
N |
O |
P |
Q |
R |
S |
T |
U |
V |
W |
X |
Y |
Z
NAME:
CTM_BOXSIZE (function)
PURPOSE:
Computes the size of CTM grid boxes.
CATEGORY
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
result = CTM_BOXSIZE( GRIDINFO [,RADIUS [,KEYWORDS] ] )
INPUTS:
GRIDINFO -> the structure returned by function CTM_GRID,
which contains the following necessary fields:
IMX (int ) -> Maximum I (longitude) dimension
JMX (int ) -> Maximum J (latitude ) dimension
YMID (fltarr) -> Array of latitude centers
RADIUS -> The radius of the earth in km. This may be
passed as an input parameter, or can be specified via
the GEOS_RADIUS, GISS_RADIUS, or FSU_RADIUS keywords.
As default, the GEOS value of 6375.0 km is used.
OUTPUT:
CTM_BOXSIZE returns a 2-D (or 1D) array of CTM surface areas,
or a 3-D array for CTM grid box volumes. The default unit
is square kilometers or cubic kilometers.
KEYWORD PARAMETERS:
/CM2 -> Return ctm surface areas in square centimeters.
[default: km^2].
/M2 -> Return ctm_surface areas in square meters.
[default: km^2].
/CM3 -> Return grid box volumes in cubic centimeters.
[default: km^3].
/M3 -> Return grid box volumes in cubic meters.
[default: km^3].
/VOLUME -> Will cause CTM_BOXSIZE to return grid box volumes
instead of grid box surface areas.
GEOS_RADIUS -> selects GEOS value for earth radius (6375.0 km)
[default]
GISS_RADIUS -> selects GISS value for earth radius (6371.4 km)
FSU_RADIUS -> selects FSU value for earth radius (6371.4 km)
IJ, IL, JL -> determine which area shall be computed [default: IJ]
NOTE: IL computes area of southern boundary
XLEN, YLEN, ZLEN -> Returns length of linear segments
(lat, lon, alt) to calling program. If /CM2 or /CM3 is
specified, then XLEN, YLEN, ZLEN will be in centimeters.
If /M2 or /M3 are specified, then XLEN, YLEN, ZLEN will
be in meters. (Default unit is km).
NO_2D -> return 1D vector instead of 2D array
LATIND -> for IL and JL: return result for given latitude index
[default is equator]. This implies NO_2D. The index must
be provided as FORTRAN index (e.g. 1..72).
SUBROUTINES:
External Subroutines Required:
===============================
CHKSTRU (function) USAGE
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
; (1) Compute surface grid box areas for GISS II model in
; standard resolution (4x5):
Areakm2 = CTM_BOXSIZE( CTM_GRID( CTM_TYPE( 'GISS_II' ), /GISS )
; (2) Compute ctm surface areas in cm2 for GEOS 4x5 grid, return
; a vector with 1 value per latitude :
ModelInfo = CTM_TYPE( 'GEOS1', res=4 )
GridInfo = CTM_GRID( ModelInfo )
AreaCm2 = CTM_BOXSIZE( GridInfo, /GEOS, /cm, /NO_2D )
; (3) Compute ctm grid box volumes in cm3 for GEOS 4x5 grid,
; and return a 3-D array
ModelInfo = CTM_TYPE( 'GEOS1', res=4 )
GridInfo = CTM_GRID( ModelInfo )
VolumeCm3 = CTM_BOXSIZE( GridInfo, /GEOS, /Volume, /cm3 )
MODIFICATION HISTORY:
bmy, 27 Mar 1998: VERSION 1.00 (algorithm from mgs)
mgs, 27 Mar 1998: - added NO_2D keyword
mgs, 07 May 1998: VERSION 1.10
- added IJ, IL, JL, LATIND, XLEN,
YLEN, and ZLEN keywords
- corrected polar box sizes
(now uses gridinfo information)
mgs, 08 May 1998: - corrected latindex, now uses FORTRAN convention
mgs, 24 May 1998: - changed IL so it computes area of
southern boundary
mgs, 17 Nov 1998: - changed keywords GISS and GEOS to .._RADIUS
bmy, 27 Jul 1999: VERSION 1.42
- updated comments
bmy, 27 Jan 2000: VERSION 1.45
- added /CM and /M keywords,
deprecated /CM2 and /M2 keywords.
- now return a 3-D array for grid box volumes
- updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now call USAGE to display doc header
if wrong # of arguments are passed.
- Deleted internal routine USE_CTM_BOXSIZE
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_boxsize.pro)
NAME:
CTM_GRID (function)
PURPOSE:
Set-up of the model grid for various models. While the
horizontal grid information can be computed from a few
basic parameters, the vertical structure is hardwired
for each model seperately. Currently, the following models
are supported: GEOS1, GEOS_STRAT, GEOS-3, GEOS-4, GEOS-5,
GEOS-57, MERRA, GISS_II, GISS_II_PRIME, FSU, FVCCM, and MATCH.
CATEGORY
GAMAP Utilities, GAMAP Models & Grids, Structures
CALLING SEQUENCE:
RESULT = CTM_GRID( MTYPE [, Keywords ] )
INPUTS:
MTYPE --> a MODELINFO structure as returned from function
CTM_TYPE. This structure must contain the following tags:
resolution (a 2 element vector with DI, DJ), halfpolar,
center180, name, nlayers, ptop, psurf, hybrid.)
OUTPUT:
RESULT -> A structure, scalor, or vector variable depending
on the output keywords below.
KEYWORD PARAMETERS:
PSURF -> specify surface pressure in mb. Overrides
value passed in through modelinfo structure.
The following keywords define output options. If none of these
is set, a structure is returned that contains all parameters.
IMX (int ) -> Maximum I (longitude) dimension [alt: NLON]
JMX (int ) -> Maximum J (latitude ) dimension [alt: NLAT]
DI (flt ) -> Delta-I interval between grid box edges
DJ (flt ) -> Delta-J interval between grid box edges
YEDGE (fltarr) -> Array of latitude edges
YMID (fltarr) -> Array of latitude centers
XEDGE (fltarr) -> Array of longitude edges
XMID (fltarr) -> Array of longitude centers
LMX (int) -> Maximum altitude level (layers) [alt: NLAYERS]
SIGMID (fltarr) -> Array of sigma center values
SIGEDGE (fltarr) -> Array of sigma edges
ETAMID (fltarr) -> Array of ETA center values
ETAEDGE (fltarr) -> Array of ETA edge values
PMID (fltarr) -> Array of approx. pressure values for sigma ctrs
PEDGE (fltarr) -> ditto for sigma edges
ZMID (fltarr) -> Array of approx. mean altitudes for sigma ctrs
ZEDGE (fltarr) -> ditto. for sigma edges
AP (fltarr) -> Hybrid-grid "A" parameters
BP (fltarr) -> Hybrid-grid "B" parameters
/NO_VERTICAL --> do not return vertical grid info in structure
In this case the MTYPE structure only needs to contain
resolution, halfpolar and center180. This keyword is ignored if
a specific (vertical) output option is requested.
DELTAZ_m --> For multi-level 'GENERIC' grids, DELTAZ_m specifies
the height of each grid level in meters. DELTAZ_m does not
apply to any of the GEOS, GISS, etc. grid families.
SUBROUTINES:
External Subroutines Required:
===============================
GETSIGMA (function)
GETETA (function)
USSA_ALT (function)
USSA_PRESS (function)
ZMID (function)
REQUIREMENTS:
Best if used with function CTM_TYPE. Also requires functions
GETSIGMA and GETETA for definition of vertical layers.
NOTES:
This routine is not very efficient in that it always computes
all the available information. But since it will not be
called too often and does not handle large amounts of data,
we won't worry about computational efficiency here.
EXAMPLE:
MTYPE = CTM_TYPE( 'GEOS1' )
MGRID = CTM_GRID( MTYPE )
; This will define the following structure (help,mgrid,/stru)
** Structure <10323808>, 17 tags, length=1624, refs=1:
IMX INT 72
JMX INT 46
DI FLOAT 5.00000
DJ FLOAT 4.00000
XEDGE FLOAT Array[73] (-177.500, -172.500, ...)
YEDGE FLOAT Array[47] (-90, -88, -84, ...)
XMID FLOAT Array[72] (-180.0, -175.0, ...)
YMID FLOAT Array[46] (-89, -86, -82, ...)
LMX INT 20
SIGMID FLOAT Array[20] (0.993936, 0.971301, ...)
SIGEDGE FLOAT Array[21] (1.00000, 0.987871, ...)
ETAMID FLOAT Array[20] (all zeroes)
ETAEDGE FLOAT Array[21] (all zeroes)
PMID FLOAT Array[20] (980.082, 957.990, ...)
PEDGE FLOAT Array[21] (986.000, 974.162, ...)
ZEDGE FLOAT Array[21]
ZMID FLOAT Array[20]
AP
; Or, with the use of output keywords:
PRINT, CTM_GRID( CTM_TYPE( 'GISS_II' ), /PMID )
; IDL will print
986.000 935.897 855.733 721.458 551.109
390.781 255.503 150.287 70.1236 10.0000
; A more awkward example (see yourself):
HELP, CTM_GRID( { RESOLUTION : [3.6,3.0], $
HALFPOLAR : 0, $
CENTER180 : 0 }, /NO_VERT), /STRU
MODIFICATION HISTORY:
bmy, 19 Aug 1997: VERSION 1.00
bmy, 24 Sep 1997: VERSION 1.01
mgs, 26 Feb 1998: Version 2.00 - rewritten as a function
mgs, 27 Feb 1998: - added vertical information
mgs, 02 Mar 1998: - better defined interface with CTM_MODEL_TYPE
bmy, 07 Apr 1998: - Renamed
mgs, 24 Apr 1998: - changed structure to named structure
mgs, 04 May 1998: - changed back because of conflicting sizes
mgs, 07 May 1998: - Renamed to CTM_GRID
- x coordinates now start with -182.5 for
center180 grids
bmy, 19 Jun 1998: - now uses USSA_ALT to compute altitudes
from pressure coordinates
- fixed some comments
- added FORWARD_FUNCTION statement
mgs, 30 Jun 1999: - added PSURF keyword
bmy, 27 Jul 1999: GAMAP VERSION 1.42
- now can compute pressure levels and
edges for hybrid sigma-pressure grids
- a few cosmetic changes
bmy, 03 Jan 2000: - more cosmetic changes
bmy, 20 Apr 2000: GAMAP VERSION 1.45
- now returns correct YMID values for FSU grid
bmy, 15 Sep 2000: GAMAP VERSION 1.46
- fixed bug for computing YMID for grids
w/o halfpolar boxes. This also fixes the
previous problem w/ the FSU grid.
bmy, 03 Jul 2001: GAMAP VERSION 1.48
- If MTYPE.NLAYERS = 0, then create a
return structure w/o vertical level info
bmy, 06 Nov 2001: GAMAP VERSION 1.49
- added ETAMID, ETAEDGE keywords
- added ETAMID, ETAEDGE tags to return structure
- now calls GETETA to return ETA coordinates
for hybrid models (such as GEOS-4/fvDAS)
- updated comments
bmy, 18 Oct 2002: GAMAP VERSION 1.52
- deleted obsolete commented-out code
bmy, 04 Nov 2003: GAMAP VERSION 2.01
- Use STRPOS to test for GEOS4 or
GEOS4_30L model names
- Now treat GISS_II_PRIME 23-layer model
as a hybrid grid instead of using the
obsolete "fake" formulation.
bmy, 28 Jun 2006: GAMAP VERSION 2.05
- bug fix for multi-level GENERIC grids
bmy & phs, 16 Aug 2007: GAMAP VERSION 2.10
- now compute mXEDGE, mXMID, mYEDGE, mYMID
as double precision, and cast back to
float, so that we get correct values for
high-res grids like 0.5 x 0.666,
- cosmetic changes
- Special handling for GEOS-5
- Now use USAGE, ROUTINE_NAME() instead of
function USE_CTM_GRID to display options
- Now return IMX, JMX as type LONG
bmy, 03 Aug 2009: GAMAP VERSION 2.13
- Added DELTAZ_m to specify grid size in
meters for multi-level GENERIC grids
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Added MERRA (identical to GEOS-5 grid,
but retains MERRA name for clarity.)
bmy, 28 Nov 2010: GAMAP VERSION 2.15
- Now use modified GETETA routine to
compute the pressure and ETA coords
consistently.
- Now save hybrid-grid parameters Ap and Bp
to the GRIDINFO structure.
bmy, 02 Feb 2012: GAMAP VERSION 2.16
- Add GEOS57 and GEOS57_47L grids, for
GEOS-5.7.x met data. (These are
identical to the GEOS-5 and MERRA grids,
but we will denote them separately).
bmy, 13 Aug 2015: GAMAP VERSION 2.19
- Add MERRA2 and MERRA2_47L grids
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_grid.pro)
NAME:
CTM_INDEX
PURPOSE:
Return index of CTM grid boxes for given coordinates
(or vice versa) and allow user to interactively select
a grid box
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
CTM_INDEX, [,i,j] [,keywords]
INPUTS:
MINFO --> Model type strucure as returned by CTM_TYPE.PRO
or GINFO --> Model grid structure as returned by CTM_GRID.PRO
If neither is given, the user will be prompted for a model
type and the grid will be computed.
I, J --> index pair for which lon, lat coordinates shall
be found if keyword /GET_COORDINATES is set. Also used
to return index values for given lon, lat pairs (this is
the default operation). NOTE: I and J will be in "FORTRAN"
notation (e.g. the starting from 1 and not zero). To index
IDL arrays, be sure to use I-1 and J-1.
KEYWORD PARAMETERS:
CENTER --> a two element vector with (LAT, LON) coordinates
for which the gridbox index shall be returned. Also used
to return center coordinates for a given index pair if
keyword /GET_COORDINATES is set.
EDGE --> a four element vector in the MAP_SET LIMIT format
(LAT0, LON0, LAT1, LON1). If keyword GET_COORDINATES is
not set and no CENTER coordinates are given, I and J will
return two element vectors with I(0) corresponding to LON0
and I(1) corresponding to LON1 etc. In this case, it may
be useful to retrieve WE_INDEX and SN_INDEX for indexing
of CTM data arrays (note that these indices follow the IDL
convention, i.e. starting from 0. To convert them into "true"
CTM indices, add 1).
If CENTER coordinates are provided or /GET_COORDINATES is set
then EDGE returns the grid box edges for the given or calculated
index pair.
WE_INDEX --> integer array for indexing of CTM data arrays. This
keyword is only used when EDGE is a valid 4 element vector,
keyword GET_COORDINATES is not set and no coordinates are
passed in the CENTER keyword. This array is always arranged
in west-east order (e.g. for EDGE=[0.,175.,0.,-175.] it will
return [70, 71, 0] (GEOS1 grid)).
SN_INDEX --> like WE_INDEX but for latitude indexing. Note that
latitude values in EDGE must be arranged in ascending order.
/GET_COORDINATES --> return coordinates to given index rather
than an index pair for given coordinates
/NON_INTERACTIVE --> default action is interactive box picking per
mouse (only need to supply MINFO in this case, but index and
coordinates of last click will be returned in I, J, CENTER
and EDGES repectively). Set this keyword if you want to convert
values to and fro without drawing a map etc.
XSIZE, YSIZE --> window size (default 900x600)
MAPCENTER --> center coordinates for map projection [p0lat, polon ]
COUNTRIES -> draw country boundaries
_EXTRA --> keywords are passed to MAP_SET
(e.g. LIMIT=[lat0,lon0,lat1,lon1])
Careful if you display data!
WINDOW -> window number to plot into. Normally a new window
is opened with the /free option. Use a specific window number
to overlay the map onto existing data plotted with tvimage
(see example).
DATA -> a data array with dimensions matching your model grid
(no error checking on this!) If DATA contains data, the value
at the selected grid box, and a statistic for neighbouring
grid boxes will be displayed together with the corrdinates.
OUTPUTS:
Index of grid box in I, J, coordinates in named variables supplied
with CENTER and EDGE keywords
SUBROUTINES:
REQUIREMENTS:
needs CTM_TYPE for input of MINFO parameter and
CTM_DEFINE_GRID
NOTES:
This routine makes substantial use of recursive calls. Be careful
when changing.
EXAMPLES:
(1)
CTM_INDEX, CTM_TYPE('GEOS1')
; Display world map and have fun.
(2)
CTM_INDEX, CTM_TYPE( 'GEOS1',RESOLUTION=2 ), $
I, J, LIMIT=[ 0.,-180., 90., -30. ]
; Display map of North America and select grid
; boxes for GEOS 2x2.5 grid.
; Indices of last point are returned in I and J.
(3)
CTM_INDEX, CTM_TYPE('GISS_II_PRIME'),$
I, J, CENTER=[ 42., -72.], /NON_INTERACTIVE
print,I,J
; returns grid box index for Harvard Forest in
; GISS CTM II' (21,33) without displaying a map
(4)
CTM_INDEX, CTM_TYPE('GISS_II'), $
I, J, EDGE=[-25.,170.,0.,-100.], $
WE_INDEX=WE, SN_INDEX=SN, /NON_INTERACTIVE
; returns [ 69, 70, 71, 0, 1, ... , 15 ] in WE and
; [ 15, 16, ..., 21 ] in SN. I is [ 70, 16 ], and J
; is [ 16, 22 ]. Note that I, J refer to CTM (= FORTRAN)
; indices, whereas WS and SN are IDL array indices.
(5)
IM = BYTSCL( DATA,MAX=MAX(DATA))
MINFO = CTM_TYPE( 'GENERIC', RES=[360./XDIM,180./YDIM] )
GINFO = CTM_GRID(MINFO)
TVIMAGE, IM, POSITION=P, /KEEP_ASPECT
CTM_INDEX, GINFO, I, J, WINDOW=0, DATA=DATA
; Overlay interactive map onto data displayed with
; TVIMAGE. You should create a generic MODELINFO
; structure in this case. NOTE: replace xdim, ydim
; with the dimensions of your data array!
; This example also demonstrates the use of ginfo vs. minfo.
MODIFICATION HISTORY:
mgs, 04 May 1998: VERSION 1.00
mgs, 07 May 1998: - added MAPCENTER and _EXTRA keywords,
fixed bug with lon index
- actually substantially rewritten
mgs, 08 May 1998: VERSION 1.10
- CENTER and EDGE keywords now MAP_SET compatible
- added WE_INDEX and SN_INDEX keywords
- improved documentation
- bug fix for display of polar grid boxes
mgs, 09 Jun 1998: - added COUNTRIES keyword
mgs, 15 Jun 1998: - bug fix for WE
mgs, 07 Oct 1998: - added interactive selection of model
mgs, 22 Feb 1999: - added DATA, SHELLS and WINDOW keywords
mgs, 23 Feb 1999: - can now use either minfo or ginfo as parameter
bmy, 24 Jan 2001: GAMAP VERSION 1.47
- commented out annoying & useless warning msg
- updated comments
bmy, 12 Mar 2003: GAMAP VERSION 2.02
- updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now pass DEFAULTMODEL from @GAMAP_CMN
common block to SELECT_MODEL
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_index.pro)
NAME:
CTM_MAPGRID
PURPOSE:
Plots CTM grid boxes superposed atop a world map.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
CTM_MAPGRID, GRIDINFO [, Keywords ]
INPUTS:
GRIDINFO -> Output structure returned from CTM_GRID
containing information about the particular
grid being used.
KEYWORD PARAMETERS:
COLOR -> Color index for the map outline, continents, and
title. Default is BLACK (assuming MYCT color table).
G_COLOR -> Color index for the grid lines.
Default is BLACK (assuming MYCT color table).
LIMIT -> Vector containing [ LatMin, LonMin, LatMax, LonMax ].
These define the latitude and longitude ranges for
the map projection. If LIMIT is not supplied,
CTM_MAPGRID will construct LIMIT from the information
supplied in GRIDINFO.
/PS -> If set, will send output to a PostScript file.
_EXTRA=e -> Picks up any extra keywords for OPEN_DEVICE,
MAP_SET, MAP_CONTINENTS, PLOTS, and CLOSE_DEVICE.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=========================================
CHKSTRU (function) CONVERT_LON
OPEN_DEVICE CLOSE_DEVICE
MYCT_DEFAULTS (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
GRIDINFO = CTM_GRID( CTM_TYPE( 'GEOS1', RES=2 ) )
CTM_MAPGRID, GRIDINFO, LIMIT=[ -90, 130, 90, -130 ], /ISOTROPIC
; Plots a world map (pacific region, spanning
; the date line) for the GEOS-1 2 x 2.5 grid
(2)
CTM_MAPGRID, GRIDINFO, LIMIT=[ -90, -182.5, 90, 177.5 ], /ISOTROPIC
; For the same grid as above, plots the entire world
; centered on 0 degrees lat and 0 degrees longitude.
MODIFICATION HISTORY:
bmy, 03 Nov 1999: VERSION 1.00
bmy, 24 Mar 2000: VERSION 1.45
- now prints map labels
- added /NOBORDER to MAP_SET call
bmy, 27 May 2003: GAMAP VERSION 1.53
- now plots continent lines after grid lines
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_mapgrid.pro)
NAME:
CTM_NAMEXT
PURPOSE:
Returns the proper filename extension for CTM model names.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
RESULT = CTM_NAMEXT( MODELINFO )
INPUTS:
MODELINFO -> a MODELINFO structure (output from function
CTM_TYPE) desribing the desired CTM model.
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Returns a string containing the model name
(e.g. 'geos3', 'geos4', 'geos5', 'gcap', 'giss2p',
'generic', etc.).
SUBROUTINES:
External Subroutines Required:
==============================
CHKSTRU (function)
REQUIREMENTS:
None
NOTES:
(1) Add more model names as is necessary.
EXAMPLE:
MODELINFO = CTM_TYPE( 'GEOS_STRAT', RESOLUTION=4 )
PRINT, CTM_NAMEXT( MODELINFO )
geoss
; Returns filename extension for the GEOS-STRAT model
MODIFICATION HISTORY:
bmy, 30 Jun 2000: GAMAP VERSION 1.46
bmy, 02 Jul 2001: GAMAP VERSION 1.48
- added GENERIC as a return option
bmy, 02 Oct 2003: GAMAP VERSION 1.53
- now add GEOS3_30L to the CASE statement
bmy, 16 Oct 2003: - now add GEOS4 to the CASE statement
bmy, 12 Feb 2004: GAMAP VERSION 2.01a
- added GEOS4_30L to the CASE statement
bmy, 05 Aug 2004: GAMAP VERSION 2.02
- added GCAP to the CASE statement
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- added GEOS5, GEOS5_47L to the CASE statement
bmy, 04 Jan 2010: GAMAP VERSION 2.15
- added MERRA, MERRA_47L to the CASE statement
bmy, 09 Feb 2012: GAMAP VERSION 2.16
- added GEOS57, GEOS57_47L to the CASE statement
mps, 06 Nov 2013: - added GEOSFP, GEOSFP_47L to the CASE statement
mps, 28 Oct 2015: - added MERRA2, MERRA2_47L to the CASE statement
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_namext.pro)
NAME:
CTM_RESEXT
PURPOSE:
Returns the proper filename extension for CTM resolution.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
RESULT = CTM_RESEXT( MODELINFO )
INPUTS:
MODELINFO -> a MODELINFO structure (output from function
CTM_TYPE) desribing the desired CTM model.
KEYWORD PARAMETERS:
None
OUTPUTS:
Returns a string containing the model resolution.
(e.g. '05x05', '1x1', '2x25', '4x5', '8x10' etc.)
SUBROUTINES:
External Subroutines Required:
==============================
CHKSTRU (function)
REQUIREMENTS:
None
NOTES:
(1) Add more grid resolutions as is necessary.
EXAMPLE:
MODELINFO = CTM_TYPE( 'GEOS4' )
PRINT, CTM_NAMEXT( MODELINFO )
4x5
; Returns filename extension for the
; 4x5 GEOS-4 model grid
MODIFICATION HISTORY:
bmy, 30 Jun 2000: GAMAP VERSION 1.46
bmy, 08 Aug 2000: - Added string for 0.5 x 0.5
bmy, 08 Feb 2006: GAMAP VERSION 2.04
- Added strings for 1.0 x 1.25 and
0.5 x 0.625
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- added string for 0.5 x 0.667
bmy, 09 Feb 2012: GAMAP VERSION 2.10
- Added string for 0.25 x 0.3125
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_resext.pro)
NAME:
CTM_TYPE (function)
PURPOSE:
return basic parameters for various 3D models used in
the Harvard tropospheric modeling group. This information
should be sufficient for CTM_GRID to compute grid box edge
and center vectors.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids, Structures
CALLING SEQUENCE:
MTYPE = CTM_TYPE( NAME [,FAMILY] [,KEYWORDS] )
INPUTS:
NAME -> a string containing the name of the model
(GISS_II, GISS_II_PRIME (or II_PRIME), GEOS1,
GEOS_STRAT, FSU, MOPITT, or GENERIC (=DUMMY) )
FAMILY -> model family (optional, will otherwise be extracted
from NAME). Possible values: GISS or GEOS or FSU or ''
KEYWORD PARAMETERS:
NLAYERS -> number of vertical model layers. This number must
correspond to the number of layers in the model output
files and is used in conjunction with PTOP to convert
sigma levels into pressure altitudes.
[defaults: GEOS1=20, GEOS_STRAT=26, GISS=FSU=9 ]
NTROP -> number of layers in the troposphere
[defaults: GEOS1=14, GISS=7, FSU=12]
PTOP -> pressure at model top
[default 10 mbar except for GEOS_STRAT=0.1 mbar]
PSURF -> average surface pressure (needed for conversion of
sigma levels to altitudes) [default 984 mbar]
RESOLUTION -> either a 2 element vector with [ DI, DJ ] or
a scalar (DJxDI: 8=8x10, 4=4x5, 2=2x2.5, 1=1x1, 0.5=0.5x0.5)
[default for all models is 4x5]
HALFPOLAR = (1 | 0) -> indicates that polar boxes span
(half | same) latitude as all other boxes (DJ=const.)
[default: 1]
HYBRID = (1 | 0) -> indicates that the model is a
(sigma-pressure hybrid | pure sigma level ) model.
[default: 0]
/PRINT -> prints model parameters on the screen
OUTPUTS:
MTYPE -> A structure with the following tag names will be
returned: NAME, FAMILY, NLAYERS, PTOP, PSURF,
RESOLUTION, HALFPOLAR, CENTER180, FULLCHEM. If input
parameters are not correct, the function returns -1.
SUBROUTINES:
Internal Subroutines:
=====================
YES_NO_VAL (function)
CHECK_RESOLUTION
REQUIREMENTS:
None
NOTES:
If you update this routine by adding additional models, make
sure to update "select_model.pro" and "getsigma.pro" as well.
EXAMPLES:
(1)
MTYPE = CTM_TYPE( 'GEOS1', RESOLUTION=2 )
; defines model parameters for the GEOS1 model
; at 2 x 2.5 degree resolution.
(2)
MTYPE = CTM_TYPE( 'GISS_II' )
MGRID = CTM_GRID( MTYPE )
; Use CTM_TYPE in conjunction with CTM_GRID to return
; the grid structure for the standard GISS_II model.
MODIFICATION HISTORY:
mgs, 02 Mar 1998: VERSION 1.00
bmy, 07 Apr 1998: - Renamed to CTM_TYPE to keep
consistent with other CTM subroutines.
mgs, 24 Apr 1998: - made structure named
mgs, 19 May 1998: - added NTROP tag and keyword
bmy, 19 Jun 1998: - now computes FSU model parameters
- GEOS_STRAT and GEOS-1 troposphere tops
are now computed separately
- added small bug fix for fullchem from mgs
mgs, 14 Aug 1998: - added DUMMY name
mgs, 15 Aug 1998: - added GEOS-1 as variant of GEOS1
bmy, 21 Dec 1998: - changed NLAYERS for GEOS STRAT
mgs, 22 Dec 1998: - small bug fix for GEOS family NTROP
mgs, 22 Feb 1999: - added GENERIC (same as DUMMY) and allow
keyword settings for this name
bmy, 23 Feb 1999: - Implemented FSU grid information
mgs, 16 Mar 1999: VERSION 1.21
- cosmetic changes
- changed function name yesno into yesno_val to
avoid conflicts.
- removed online tag because it's never
used
bmy, 26 Jul 1999: VERSION 1.42
- added HYBRID keyword and tag name
- cosmetic changes
bmy, 15 Sep 1999: VERSION 1.43
- fixed bug for NTROP in GISS-II-PRIME, 9L
bmy, 15 Oct 1999: VERSION 1.44
- now reset model names "GEOS-STRAT" and
"GEOS-2" to "GEOS_STRAT" and "GEOS2"
bmy, 03 Jan 2000: - added GEOS-2 model parameters
- changed NTROP to 16 for GEOS1
- changed NTROP to 22 for GEOS_STRAT
bmy, 16 May 2000: VERSION 1.45
- reset NTROP to 19 for GEOS-STRAT
- now use GEOS-2 47 layer grid
bmy, 01 Aug 2000: VERSION 1.46
- added GEOS-3 48-layer grid
- added internal function CHECKRESOLUTION
- cosmetic changes, updated comments
bmy, 26 Jun 2001: GAMAP VERSION 1.48
- fixed NTROP for GEOS-3 met fields
- for generic grids, return "GENERIC" in
uppercase as model name and family name
bmy, 09 Oct 2001: GAMAP VERSION 1.49
- now accepts modelname "GEOS3_30L", and
returns a structure for 30-layer GEOS-3 grid
bmy, 06 Nov 2001: - now recognizes "GEOS-4" as a modelname
- changed default PSURF from 986 mb to 984 mb
clh & bmy, 18 Oct 2002: GAMAP VERSION 1.52:
- Now supports 7-layer MOPITT grid
bmy, 12 Dec 2003: GAMAP VERSION 2.01
- Now supports "GEOS4_30L" grid
- Set NTROP=18 for GEOS-4 grid
- Now set CENTER180=1 for GISS_II_PRIME
- Now supports 52-layer NCAR-MATCH model
- Cleaned up code and straightened out logic
- Removed SMALLCHEM, HELP keywords
bmy, 18 Feb 2004: GAMAP VERSION 2.01a
- The actual NTROP from the GEOS-4 annual
mean tropopause is 17, not 18
bmy, 17 Jun 2004: GAMAP VERSION 2.02a
- added GCAP model type for the 23L hybrid
GCAP grid (which is the same grid as the
winds for the GISS-II-PRIME)
bmy, 01 Jun 2006: GAMAP VERSION 2.05
- Bug fix: GISS-II model needs CENTER180=0
bmy & phs, 16 Aug 2007: GAMAP VERSION 2.10
- Modified for 47 layer GEOS-5 grid
- Now return NLAYERS, NTROP, HALFPOLAR,
CENTER180, FULLCHEM, HYBRID as type long
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Added MERRA (identical to GEOS-5 grid,
but retains MERRA name for clarity.)
bmy, 28 Nov 2010: GAMAP VERSION 2.15
- Make the default PSURF value 1013.25 hPa,
(i.e. 1 atm) instead of 984hPa.
bmy, 02 Feb 2012: GAMAP VERSION 2.16
- Add GEOS57 and GEOS57_47L grids, for
GEOS-5.7.x met data. (These are
identical to the GEOS-5 and MERRA grids,
but we will denote them separately).
- Added shorthand for 0.25 x 0.3125 resolution
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_type.pro)
NAME:
GETMODELANDGRIDINFO
PURPOSE:
Given a DATAINFO structure, returns the corresponding
MODELINFO and GRIDINFO structures.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids, Structures
CALLING SEQUENCE:
CTM_GETMODELANDGRIDINFO, THISDATAINFO, MODELINFO, GRIDINFO
INPUTS:
THISDATAINFO -> A single of DATAINFO structure which
contains the following fields:
** Structure H3DSTRU, 13 tags, length=72:
ILUN LONG
FILEPOS LONG
CATEGORY STRING
TRACER INT
TRACERNAME STRING
TAU0 DOUBLE
TAU1 DOUBLE
SCALE FLOAT
UNIT STRING
FORMAT STRING
STATUS INT
DIM INT
OFFSET INT
DATA POINTER
KEYWORD PARAMETERS:
LON -> set to a variable that will hold the longitude
centers of the data set. Grid Offsets of data that
do not cover the globe are accounted for.
LAT -> same as LON, but for Latitude centers.
LEVEL -> same as LON, but holds levels indices, starting at 1.
OUTPUTS:
MODELINFO -> Returns to the calling program the model
information structure (see "ctm_type.pro") which
corresponds to THISDATAINFO.
GRIDINFO -> Returns to the calling program the grid
information structure (see "ctm_grid.pro") which
corresponds to THISDATAINFO.
SUBROUTINES:
External Subroutines Required:
==============================
GAMAP_CMN (include file)
CTM_GRID (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
; Read data from "myfile.bpch"
; DATAINFO is an array of structures
CTM_GET_DATA, DATAINFO, FILE='myfile.bpch'
; Loop over all data blocks in the file
FOR D = 0L, N_ELEMENTS( DATAINFO )-1L DO BEGIN
; Pick the DATAINFO structure for the Dth data block
THISDATAINFO = DATAINFO[D].DATA
; Get MODELINFO and GRIDINFO structures for the Dth data block
GETMODELANDGRIDINFO, THISDATAINFO, MODELINFO, GRIDINFO
...
ENDFOR
MODIFICATION HISTORY:
bmy, 24 Apr 2002: GAMAP VERSION 1.50
bmy, 28 Jun 2006: GAMAP VERSION 2.05
- Bug fix for multi-level GENERIC grids
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
phs, 13 May 2008: GAMAP VERSION 2.12
- Added LON and LAT keyword to return data
(not global grid) longitude and latitude centers.
phs, 8 Oct 2008: GAMAP VERSION 2.13
- Added LEVEL keyword to return levels.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/getmodelandgridinfo.pro)
NAME:
GET_GEOS5_PRESS
PURPOSE:
Returns zonal mean pressure edges and pressure centers
for the GEOS-5 grid (47 layers or 72 layers). Because in
GEOS-5 we cannot compute the pressures at grid box edges
and centers, we must read them in from disk.
CATEGORY:
GAMAP Internals, GAMAP Models & Grids
CALLING SEQUENCE:
GET_GEOS5_PRESS, PEDGE, PMID [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
FILENAME -> Specifies the name of the file containing
average pressures on the GEOS-5 grid. If FILENAME
is omitted, then GET_GEOS5_PRESS will use the default
filename: "pedge.geos5.{RESOLUTION}.year".
NLAYERS -> Specifies the number of layers in the GEOS-5
grid. NLAYERS can be either 47 or 72. Default is 47.
RESOLUTION -> Specifies the resolution of the GEOS-5 grid.
Default is 4x5.
PSURF -> If specified, then PEDGE and PMID will be 1-D
vectors, with the surface pressure (i.e. PEDGE[0])
being closest to the passed value of PSURF.
/VERBOSE -> Set this switch to toggle verbose output.
OUTPUTS:
PEDGE -> Array (or vector if PSURF is specified) of pressures
at GEOS-5 grid box edges. The PEDGE values have been
averaged over 12 months and also averaged over longitudes
(i.e. zonal mean).
PMID -> Array (or vector if PSURF is specified) of pressures
at GEOS-5 grid box centers. The pressures have been
averaged over 12 months and also averaged over longitudes
(i.e. zonal mean).
SUBROUTINES:
External Subroutines Required:
===================================
CTM_GET_DATA CTM_TYPE (function)
REQUIREMENTS:
Requires routines from both GAMAP and TOOLS packages.
NOTES:
(1) At present, we only have saved out a file containing
pressure edges from the GEOS-5 47-layer model.
EXAMPLE:
(1)
GET_GEOS5_PRESS, PEDGE, PMID, RES=2
; Returns pressues at grid box edges (PEDGE) and centers
; (PMID) for the GEOS-5 47L model at 2 x 2.5 resolution.
; PEDGE is a 2-D array of size 91x48. PMID is also a
; 2-D array of size 91x47.
(2)
GET_GEOS5_PRESS, PEDGE, PMID, RES=2, PSURF=1000.0
; Returns pressues at grid box edges (PEDGE) and centers
; (PMID) for the GEOS-5 47L model at 2 x 2.5 resolution.
; for the column with the closest surface pressure to
; PSURF=1000 hPa. PEDGE is a 1-D vector w/ 48 elements.
; PMID is also a 1-D vector w/ 47 elements.
MODIFICATION HISTORY:
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
phs, 25 Feb 2008: - check on File_Which output
dbm & ccc, 15 Dec 2009: GAMAP VERSION 2.14
- Make sure PSURF is a scalar
(See /n/home09/ryantosca/IDL/gamap2/internals/get_geos5_press.pro)
NAME:
PLOTSIGMA
PURPOSE:
PLOTSIGMA plots the sigma level extent of various CTM's
(including GISS-II, GISS-II', GEOS-1, GEOS-STRAT, GEOS-2,
and FSU) side by side for comparison. Useful for making
viewgraphs.
CATEGORY:
GAMAP Utilities, GAMAP Models & Grids
CALLING SEQUENCE:
PLOTSIGMA, MODELNAME [, keywords ]
INPUTS:
MODELNAME -> A string (or array of strings) containing the
names of the models to be plotted. Default is [ 'GEOS1' ].
KEYWORD PARAMETERS:
/PLEFT -> Will cause pressure to be plotted (with regular
spacing) along the left Y-axis. Default is to plot
altitude (with regular spacing) along the left Y-axis).
/PS -> Causes output to be sent to the PostScript Device.
SURFP -> The surface pressure in mb used to convert sigma
levels into absolute pressures. Default is 1010.
YRANGE -> Specifies the plotting range [Ymin, Ymax]
along the left Y-axis. Default is [ 0, 32 ] km.
OUTPUTS:
None
SUBROUTINES:
External subroutines required:
--------------------------------------------
CTM_TYPE (function) CTM_GRID (function)
USSA_PRESS (function) USSA_ALT (function)
MYCT_DEFAULTS (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PLOTSIGMA, /PLEFT, $
['GISS_II', 'GEOS1', 'GEOS_STRAT', 'FSU' ], $
YRANGE=[1010, 150], SURFP=1010.0
; plots sigma levels for GISS-II, GEOS-1, GEOS-STRAT,
; and FSU models, with pressure on the left Y-axis,
; assuming a surface pressure of 1010 mb, for the range
; of 1010 mb to 150 mb.
PLOTSIGMA, $
['GISS_II', 'GEOS1', 'GEOS_STRAT', 'FSU' ], $
YRANGE=[0, 16], SURFP=1010.0
; Same as above, but plots with altitude on left Y-axis,
; and for the range 0 km - 16 km.
MODIFICATION HISTORY:
bmy, 15 Aug 1997: VERSION 1.00
bmy, 30 Oct 1997: VERSION 1.01
bmy, 15 Jun 1998: VERSION 1.10
- now uses CTM_TYPE, CTM_GRID
bmy, 17 Jun 1998: GAMAP VERSION 1.20
bmy, 19 Jun 1998: - add array for color indices
- also supports FSU model
bmy, 03 Jan 2000: GAMAP VERSION 1.44
- eliminate call to MYCT and keywords
- cosmetic changes
bmy, 06 Sep 2000: GAMAP VERSION 1.46
- added text string for GEOS-3
bmy, 26 Jun 2001: GAMAP VERSION 1.48
- now pass _EXTRA=e to PLOT command
- added extra error checking
bmy, 23 Jul 2001: - now use MYCT_DEFAULTS() to set up
MYCT color information
bmy, 28 Sep 2002: GAMAP VERSION 1.51
- now gets color information from the
!MYCT system variable
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Modified for GEOS-4 and GEOS-5
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/plotsigma.pro)