All GAMAP Routines

All GAMAP Routines

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

Last modified: Tue Apr 4 10:50:19 2017.


List of Routines


Routine Descriptions

ADD_DATA

[Next Routine] [List of Routines]
 NAME:
        ADD_DATA

 PURPOSE:
        Add a variable to a data array and its header, units,
        cfact, and mcode fields.  For use with CHEM1D.

 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        ADD_DATA,data,header,units,cfact,mcode,    $
           newdat,newhead,newunit,newfact,newcode [,keywords]

 INPUTS:
        DATA --> the array containing all the data
        HEADER --> string vector of variable names
        UNITS --> string vector of variable units (maybe undefined)
        CFACT --> float vector of conversion factors (maybe undefined)
        MCODE --> float vector of missing value codes (maybe undefined)
        NEWDATA --> data vector containing new variable
        NEWHEADER --> name of new variable
        NEWUNIT --> physical unit of new variable (may be omitted)
        NEWFACT --> conversion factor of new variable (may be omitted)
        NEWCODE --> missing value code for new variable (may be omitted)

 KEYWORD PARAMETERS:
        /INFO  --> prints number of variables (elements of HEADER)
               after merging the new column with the old array
        /TRANSPOSE --> NEWDAT is being transposed before merging it
               with DATA
        /FIRST --> add variable at first position rather than last

 OUTPUTS:
        DATA, HEADER, UNITS, CFACT, MCODE will contain the extra data

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        suppose DATA is a 3x10 array, and HEADER contains 
        the names A, B, and C. Then 

            ADD_DATA,DATA,HEADER,DUMMY,DUMMY,DUMMY,findgen(10),'COUNT'

        will add the variable COUNT to the dataset and the name to HEADER.

        A more realistic example:
            ADD_DATA,DATA,HEADER,UNITS,CFACT,MCODE, $
                     NEWDAT,'SATURATION_PRESSURE','mbar',1.0,-999.99

 MODIFICATION HISTORY:
        mgs, 05 Nov 1997: VERSION 1.00
            extracted from CREATE_MASTER.PRO, added flexibility for
            optional parameters
        mgs, 06 Nov 1997: - added FIRST keyword
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/add_data.pro)


ADD_DATE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ADD_DATE

 PURPOSE:
        Computes the YYYY/MM/DD date after a number of days in the
        future (or past) have elapsed.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = ADD_DATE( YYYYMMDD, NDAYS )

 INPUTS:
        YYYYMMDD -> Today's date in YYYY/MM/DD format

        NDAYS -> The number of days (either positive or negative)
              to add to YYYYMMDD.  Default is 1.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        DATE2YMD    YMD2DATE (function)
       
 REQUIREMENTS:
        None

 NOTES:
        None
   
 EXAMPLES:
        PRINT, ADD_DATE( 20060101, 100 )
           20060411
             ; Computes the date 100 days after 2006/01/01

        PRINT, ADD_DATE( 20060101, -100 )
           20050923
             ; Computes the date 100 days before 2006/01/01

 MODIFICATION HISTORY:
        bmy, 06 Jun 2006: TOOLS VERSION 2.05
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/date_time/add_date.pro)


ADD_SEPARATOR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ADD_SEPARATOR

 PURPOSE:
        Adds a pathname separator to the last character of
        a file name or path name.

 CATEGORY:
        General

 CALLING SEQUENCE:
        NEWPATH = ADD_SEPARATOR( PATH )

 INPUTS:
        PATH -> Path name to append the separator character
             to.  If Unix, will append a "/" character.  If
             Windows, will append a "/" character.  If 
             Macintosh, will append a ":" character.

 KEYWORD PARAMETERS:
        None    

 OUTPUTS:
        NEWPATH -> Path name with separator appended to
             the last character.

 SUBROUTINES:
        None

 REQUIREMENTS:
        Supports Unix, Windows, and Macintosh platforms.

 NOTES:
        None

 EXAMPLE:
        (1) 
        PATH    = '/scratch/bmy'
        NEWPATH = ADD_SEPARATOR( PATH )
          /scratch/bmy/ 

             ; Adds a separator to the path "/scratch/bmy".

        (2)
        SEP = ADD_SEPARATOR()
        PRINT, SEP
          /

             ; Returns the default separator string
             ; (here we have assumed a Unix environment).
           

 MODIFICATION HISTORY:
        bmy, 03 May 2002: TOOLS VERSION 1.50
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/add_separator.pro)


ADD_TEMPLATE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ADD_TEMPLATE

 PURPOSE:
       Add a near standard IDL template to a given IDL routine file.
   
 CATEGORY:
       Documentation

 CALLING SEQUENCE:
       ADD_TEMPLATE, FILE

 INPUTS:
       FILE -> Input IDL routine file name.   

 KEYWORD PARAMETERS:
       None

 OUTPUTS:
       None

 COMMON BLOCKS:
       None

 NOTES:
       (1) Existing front end, up to the pro or function
           statement, are replaced by the new template.

       (2) Also see routine IDL2HTML, which converts the IDL
           doc header text to HTML format.

 MODIFICATION HISTORY:
       written by:
          R. Sterner, about Sep 1989 at Sac Peak.  The exact date was
               probably lost by this routine itself.
       modified:
          R. Sterner, 13 Dec, 1993 --- dropped spawn to copy files.
          R. Sterner, 11 Mar, 1993 --- handled no help text case.
          M. Schultz, 01 Aug, 1997 --- simplified version without
               analyzing help text
               Also, original file is left intact 
               (i.e. modification date etc.)
               and renamed file.backup if operation successfully.
               OF COURSE the copyright note is changed as well 
          mgs, 09 Oct 1998 : - added Id tag for RCS
          bmy, 19 Jul 1999 : - changed name & email from mgs to bmy
                               for convenience!  :-)
          bmy, 27 Jul 1999 : - put RCS tag as the first line of
                               the standard header
          bmy, 06 Jul 2000 : - extended separator lines a bit
          bmy, 11 Oct 2006 : TOOLS VERSION 2.05
                             - Cosmetic chanes
     bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                             - Now include 2 email addresses
                             - Updated comments, cosmetic changes.
                             - Same conditions apply
           bmy, 22 Apr 2008: GAMAP VERSION 2.12
                             - Updated email addresses

(See /n/home09/ryantosca/IDL/gamap2/doc/add_template.pro)


ADJ_INDEX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ADJ_INDEX

 PURPOSE:
        Adjusts CTM global index arrays for a particular
        data-block dimension from global size to window size.

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        NEWINDEX = ADJ_INDEX( OLDINDEX, N_SUBTRACT, MAXINDEX )

 INPUTS:
        OLDINDEX -> The globally sized CTM index array to be adjusted.

        N_SUBTRACT -> The number to subtract from each element
             of OLDINDEX.  

        MAXINDEX -> The maximum number of elements that OLDINDEX
             can have.  

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        ADJ_INDEX returns the window-sized index array as
        the value of the function.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None.
            
 NOTES:
        Designed for use with GAMAP, but can be used for more
        general purpose applications as well.

 EXAMPLE:
       WE     = [ 69, 70, 71, 0, 1, 2 ]     ; WE straddles the date line
       WE_ADJ = ADJ_INDEX( WE, 69, 72 )   
       print, WE_ADJ
         0       1       2       3       4       5
       NEWDATA = DATA[ WE_ADJ, *, * ]

       ; WE has a possible maximum of 72 elements.  Convert WE
       ; from global size to window size by subtracting 69 
       ; from each element of WE.  Use WE_ADJ to reference
       ; elements of the DATA array.

 MODIFICATION HISTORY:
        bmy, 19 Feb 1999: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/adj_index.pro)


AIRDENS (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        AIRDENS (function)

 PURPOSE:
        Compute air mass density for a given pressure and 
        temperature. If the temperature is not provided, a
        temperature is estimated using the US Standard atmosphere.

 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        idens = AIRDENS(p [,T])

 INPUTS:
        P  -> pressure in hPa (mbar)

        T  -> temperature in K

 KEYWORD PARAMETERS:
        HELP -> print help information

 OUTPUTS:
        The air mass density in molec/cm^3. The result type will 
        match the type and array dimensions of p unless p is a 
        scalar and T an array.

 SUBROUTINES:
        External Subroutines Required:
        ===========================================
        USSA_ALT (function)   USSA_TEMP (function)

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1) 
        PRINT, AIRDENS( 1013.25, 273.15 )
           2.69000e+19
 
             ; Prints air density at std temperature & pressure

        (2)
        P = FINDGEN(5)*100+500
        PRINT,AIRDENS(P,T)     ; T undefined !
           1.44840e+19  1.67414e+19  1.89029e+19  2.10104e+19  2.30998e+19
        PRINT, T
           250.334      259.894      268.538      276.117      282.534

             ; Prints air density w/ undefined temperature
             ; Temperature profile from the US Std atmosphere
             ; will be returned.

        (3)
        PRINT,AIRDENS(800.,T)  ; T from previous calculation
           2.31744e+19  2.23218e+19  2.16033e+19  2.10104e+19  2.05332e+19

             ; Use T from previous example and print
             ; air density at 800 hPa

 MODIFICATION HISTORY:
        mgs, 12 Nov 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/airdens.pro)


ARREX (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ARREX  (function)

 PURPOSE:
        This function extracts a multi-dimensional subset
        of an array. For each dimension the start index,
        end index, and stride can be specified - default values
        are 0 (i.e. first start index), "all" (i.e. last end
        index), and 1 (i.e. every element). A negative stride
        causes reversion of the respective array dimension.

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        Result = ARREX(Array [, Starti [,Endi [, Stride ]]] [,/Reform])

 INPUTS:
        ARRAY -> The parent array from which the extraction shall be made.
            Currently up to 4 dimensions are supported.

        STARTI -> An array with starting indices. Each element of STARTI
            corresponds to one dimension of ARRAY. If STARTI has less
            elements than ARRAY dimensions, the remainder is assumed 0.

        ENDI   -> An array with ending indices. Each element of ENDI
            corresponds to one dimension of ARRAY. If ENDI has less
            elements than ARRAY dimensions, the remainder is set to the
            maximum possible value for that dimension.

        STRIDE -> An array with stride values. A stride of 1 (default)
            signifies extraction of every element, 2 returns every 
            second element for that dimension, etc. Negative values
            cause the respective dimension to be reversed. 
            Each value of STRIDE corresponds to one dimension of ARRAY. 
            If STRIDE has less elements than ARRAY dimensions, the 
            remainder is assumed 1.

 KEYWORD PARAMETERS:
        /REFORM -> Set this keyword to eliminate unnecessary dimensions
            in the result.

 OUTPUTS:
        A subset of the original array. This will have the same 
        dimensionality as ARRAY unless the REFORM keyword is set.

 SUBROUTINES:
        Function arrex_ComputeInd

 REQUIREMENTS:
        None

 NOTES:
        Created after discussion in newsgroup idl-pvwave.

        This version contains some debug output.

 EXAMPLE:
        A = indgen(10,10)
        print,arrex(A,[2,1],-1,[2,4])
        ; yields  12  14  16  18
        ;         52  54  56  58
        ;         92  94  96  98
        print,arrex(A,[10,1],[1,10],[5,5])
        ; yields  19  15
        ;         69  65
        ; note that stride for dimension 1 is adjusted automatically.

 MODIFICATION HISTORY:
        mgs, 20 May 1999: VERSION 1.00
                          - with a lot of input from 
                            L. Gumley, S. Vidar, and others
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/math_units/arrex.pro)


ARROWMAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ARROWMAP

 PURPOSE:
        Plots a vector field atop a world map.

 CATEGORY:
        Plotting

 CALLING SEQUENCE:
        ARROWMAP, U, V, X, Y [, Keywords ]

 INPUTS:
        U, V -> The X and Y components of the two-dimensional vector
             field.  U and V must be two-dimensional arrays.

             The vector at point (i,j) has a magnitude of:             
             
                       ( U(i,j)^2 + V(i,j)^2 )^0.5             
             
             and a direction of:             
             
                       ATAN2( V(i,j), U(i,j) ).             
             
        X, Y -> Longitude (X) and latitude (Y) values corresponding to 
             the U and V arrays.  X must be a vector with a length equal 
             to the 1st dimension of U and V.  Y must be a vector
             with length equal to the 2nd dimension of U and V.

 KEYWORD PARAMETERS:
        UNIT -> String containing the units for the plot legend.
             Default is '' (the null string).

        FORMAT -> Format string for the arrow legend.  Default
             is '(f10.3)'.

        TITLE -> Top title for the map panel.  
             Default is '' (the null string).

        CSFAC -> Character size for the map labels and X, Y titles. 
             Default settings for CSFAC vary according to the number 
             of plots per page and type of plot device.

        TCSFAC -> Character size for the top title.  Default
             settings for TCSFAC vary according to the number 
             of plots per page and type of plot device.

        _EXTRA=e -> Picks up extra keywords (not listed below) for
             ARROW, MAP_SET, MAP_GRID, MAP_CONTINENTS, VELOCITY_FIELD.

    Keywords for MAP_SET:
    =====================
        MPARAM -> A 3 element vector containing values for
             [ P0Lat, P0Lon, Rot ].  Default is [ 0, 0, 0 ].
             Elements not specified are automatically set to zero.

             NOTE: If X contains positive longitudes (i.e. in the 
             range 0-360), then set MPARAM = [0, 180, 0].  This will
             ensure that the map is displayed correctly.

        LIMIT -> A four-element vector which specifies the latitude
             and longitude extent of the map.  The elements of LIMIT
             are arranged thus: [ LatMin, LonMin, LatMax, LonMax ].
             Default is to set LIMIT = [ -90, -180, 90, 180 ] (i.e.
             to include the entire globe). P0Lon will be computed
             to fit into the LIMIT range unless it is explicitely
             requested in MParam.

             If LIMIT is not passed explicitly, then LIMIT will be
             computed from the maximum and minimum values of the 
             X and Y vectors.

        COLOR -> Color index of the map outline and flow vectors.
             Defaults is 1 (MYCT black color).

        /POLAR -> Plot a polar stereographic projection. 
             NOTE: Polar is not yet supported (bmy, 5/26/00)

        POSITION -> A four-element array of normalized coordinates
             that specifies the location of the map.  POSITION has
             the same form as the POSITION keyword on a plot.
             Default is [0.0, 0.15, 1.0, 1.0].

        MARGIN -> specify a margin around the plot in normalized 
            coordinates. This keyword does not change any IDL
            system variables and will thus only become "visible" 
            if you use the POSITION returned by MULTIPANEL in
            subsequent plot commands.  MARGIN can either be one value 
            which will be applied to all four margins, or a 2-element 
            vector which results in equal values for the left and
            right and equal values for the bottom and top margins, 
            or a 4-element vector with [left,bottom,right,top].  The
            default MARGIN setting is [ 0.05, 0.04, 0.03, 0.07 ].

        /ISOTROPIC  -> If set, will produce a map with the same scale
             in the X and Y directions.  Default is not to plot an
             isotropic-scale map. Note, however, that if TVMAP is 
             called from CTM_PLOT, the default is to plot a map that
             keeps the aspect ratio (which is about the same as 
             isotropic).


    Keywords for MAP_CONTINENTS:
    ============================
        /CONTINENTS -> If set, will call MAP_CONTINENTS to plot
             continent outlines or filled boundaries.  Default is 0.

        CCOLOR -> The color index of the continent outline or fill
             region.  Default is 1 (MYCT black color).

        CFILL -> Value passed to FILL_CONTINENTS keyword of MAP_CONTINENTS.
             If CFILL=1 then will fill continents with a solid color
             (as specified in CCOLOR above).  If CFILL=2 then will fill
             continents with hatching.

    Keywords for MAP_GRID:
    ======================
        /GRID -> If set, will call MAP_GRID to plot grid lines and
             labels.  Default is NOT to plot grid lines and labels.

        GCOLOR -> The color index of the grid lines. Default is
             BLACK (see above).

    Keywords for VELOCITY_FIELD:
    ============================
        ACOLOR -> Specifies the color of the arrows.  Default is black.
 
        HSIZE -> The length of the lines used to draw the arrowhead.
             If HSIZE is positive, then the arrow head will be the
             same regardless of the length of each vector.  (Default
             size is !D.X_SIZE / 100).  If HSIZE is negative, then
             the arrowhead will be 1/HSIZEth of the total arrow length.

        THICK -> Thickness factor for the arrows.  Default is 2.0.

        MAXMAG -> Returns to the calling program the magnitude of the
             longest vector. 

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        =====================================
        MULTIPANEL   MYCT_DEFAULTS (function)
        MAP_LABELS   VELOCITY_FIELD

 REQUIREMENTS:
        None

 NOTES:
        (1) The U and V arrays may contain either CTM winds or 
            flux quantities.  However, when plotting fluxes, it is 
            STRONGLY RECOMMENDED that you double-check the units of
            U and V before passing them to ARROWMAP.  Some unit 
            conversion may be required in order to display fluxes
            properly.

        (2) If your map spans the date line, then do the following:

              (a) Make sure that your longitudes are in the range 
                  0 - 360 degrees

              (b) Call ARROWMAP with MPARAM=[0,180,0] in order to 
                  have MAP_SET accept longitudes in the range 0-360.

 EXAMPLE:
        ARROWMAP, U, V, X, Y, $
            /GRID, /CONTINENTS, THICK=3, CFILL=2, GCOLOR=1, UNIT='m/s'

            ; Plots a vector flow pattern over a world map.  Continents 
            ; are filled to a solid red color (assuming a MYCT colortable).  
            ; Arrows have a thickness factor of 3.

 MODIFICATION HISTORY:
        bmy, 26 May 2000: GAMAP VERSION 1.45
        bmy, 24 Jul 2000: GAMAP VERSION 1.46
                          - added X_STEP, Y_STEP, and MAXMAG keywords
                          - now print the longest vector as the arrow
                            legend below the plot.  
                          - added MARGIN keyword for MULTIPANEL 
                          - added ISOTROPIC keyword for MAP_SET
        bmy, 23 Jul 2002: GAMAP VERSION 1.51
                          - now default HSIZE to a device pixel length
                          - added LEGENDLEN keyword
                          - now call VELOCITY_FIELD using new LEGENDLEN,
                            LEGENDNORM, and LEGENDMAG keywords
                          - Now use MYCT_DEFAULTS for default BLACK
                          - added COUNTRIES and COASTS keywords
                          - removed HANGLE keyword -- it's obsolete!
                          - renamed ARRLEN to LEGENDNORM
                          - renamed MAXMAG to LEGENDMAG
        bmy, 28 Sep 2002: - Now reference MYCT colors from the !MYCT
                            system variable
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        phs, 12 Mar 2008: GAMAP VERSION 2.12
                          - add /NOADVANCE keyword to prevent advancing
                            to the next page (in case you want to overplot)

(See /n/home09/ryantosca/IDL/gamap2/plotting/arrowmap.pro)


BARGRAPH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BARGRAPH

 PURPOSE:
        Creates a bar graph from a vector of data points.

 CATEGORY:
        Plotting

 CALLING SEQUENCE:
        BARGRAPH, DATA, BASELINE [,keywords]

 INPUTS
        DATA -> Vector of data points to be plotted as a bargraph.
 
        BASELINE -> Vector of points to be used as a baseline for 
             DATA (i.e., Y(I) = DATA(I) + BASELINE(I) ).  If BASELINE 
             is not specified, its default value will be an array 
             of zeroes.

 KEYWORD PARAMETERS:
        /OVERPLOT -> Set this switch to prevent the current plot
             window from being erased.  This is useful for producing 
             stacked bar plots with successive calls to BARGRAPH.
 
        BARWIDTH -> The width of the bars.  If BARWIDTH is not
            specified, its default value will be 1.0.

        BARCOLOR -> a value or an array containing the colorindex for
            all boxes or each box, respectively. If a single value
            is given, *all* boxes will have this color. If an array 
            is passed that has less elements than there are groups to 
            plot, the remaining colors will be filled with 15 (grey 
            in MYCT standard-scheme).  

        BARLABELS -> A string array of labels to be plotted above each
            bar.  If BARLABELS may be originally set equal to the
            DATA vector, and it will be converted to the string 
            representation of DATA, using the FORMAT statement 
            contained in L_FORMAT.

        BARCHARSIZE -> Character size for BARLABELS.  Default is 1.0.

        COLOR -> Color index for the plot axes and labels.  
            Default is !MYCT.BLACK.

        L_FORMAT -> The FORMAT statement used to convert BARLABELS
            from a numeric array to a string array.

        /NO_LABELS -> Set this switch to suppress printing the labels
            contained in the BARLABELS atop each bar.  This is useful 
            for producing stacked bar plots.

        XLABELS -> A string array containing the labels that will be 
            printed underneath each bar on the X-axis.  

            NOTE: If /HORIZONTAL is set, then these labels will be 
            printed along the Y-axis instead.

            ALSO NOTE: IDL only allows a maximum limit of 60 ticks 
            along any axis.  If XLABELS has more than 58 elements
            (also allowing for null labels at the beginning and end
            of the plot range), then the labels will not be printed.

        YRANGE -> Use this keyword to specify the range of the data 
            values.  If YRANGE is not specified, then YRANGE will be 
            computed based on the maximum value of the DATA array.  
            For stacked plots, it is useful to compute YRANGE in the 
            calling program and pass it to BARGRAPH. 

            NOTE: If HORIZONTAL is set, then the YRANGE settings 
            will apply to the X-axis instead.

        /HORIZONTAL -> Set this switch to plot the bars in the 
            horizontal instead of in the vertical.  NOTE: In this
            case, the YRANGE settings will be applied to the X-axis.
            and the XRANGE and XLABELS settings will be applied to
            the Y-axis.

        YFACTOR -> Use this to add space between the bar and bar label.
            This will multiply DATA + BASELINE by a factor that you
            specify.  Default is 1.01.

        _EXTRA=e -> Passes extra keywords to PLOT and other routines.

 OUTPUTS:
        None

 SUBROUTINES:
        None
        
 REQUIREMENTS:
        None

 NOTES:
        (1) This routine has been modified to be more general and 
            more robust than the original version in the IDL 5.0 
            User's Guide (p. 170).

        (2) IDL 5.x array notation [] is now used.

 EXAMPLES:
        (1)

        BARGRAPH, [1,2,3], BARWIDTH=1.0, BARCOLOR=[10,11,12]
           XLABELS=['Bart', 'Lisa', 'Maggie']

             ; Create a simple bar graph with bars of 3 different 
             ; colors, using a baseline of zero.

        (2)

        DATA   = [2,3.5,6,7,2,1]
        DATA2  = 0.0*DATA + 2

        BARGRAPH, DATA, XLABELS=['A','B','C','D','E','F'],  $
           XSTYLE=1, BARWIDTH=0.8

        BARGRAPH, DATA2, DATA, BARWIDTH=0.8 ,/OVERPLOT, $
           BARCOLOR=2, BARLABELS=DATA+DATA2, L_FORMAT='(F8.2)'             


             ; Use successive calls to BARGRAPH to create a 
             ; "stacked" bar graph with two different data vectors.  
             ; The first vector is used as the baseline for the
             ; second.  The BARLABELS array is created from the actual 
             ; data values.

        (3) 

        BARGRAPH, [1,2,3], BARWIDTH=1.0, BARCOLOR=[10,11,12]
           XLABELS=['Bart', 'Lisa', 'Maggie'], /HORIZONTAL

             ; Same as example (1), but plot bars in the horizontal.

 MODIFICATION HISTORY:
        bmy, 18 Nov 1997: VERSION 1.00
        bmy, 19 Nov 1997: VERSION 1.01
        bmy, 29 Apr 1999: VERSION 1.10
                          - added COLOR keyword
                          - eliminated help screen 
                          - enhanced readability & updated comments
        bmy, 15 Mar 2000: VERSION 1.45
                          - added BARCHARSIZE keyword
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - added HORIZONTAL keyword to plot
                            bars in the horizontal 
                          - Now limits XLABELS array to 58 elements
                            in order to prevent exceeding an IDL
                            plotting limit
        bmy, 15 Dec 2016: GAMAP VERSION 2.19
                          - Now plot top-of-bar labels in the right
                            place when using the /HORIZONTAL option
        bmy, 20 Dec 2017: - Now compute YOffSet dynamically, for more
                            consistent spacing between bars & bar labels

(See /n/home09/ryantosca/IDL/gamap2/plotting/bargraph.pro)


BENCHMARK_1MON

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BENCHMARK_1MON

 PURPOSE:
        Produces maps of tracers and other quantities from two
        GEOS-Chem benchmark simulations (for model validation).

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        BENCHMARK_1MON, INPUTFILE, [, Keywords ]

 INPUTS:
        INPUTFILE -> A file containing default values for version 
             numbers, directories, model names, resolutions, etc.
             Default is "input_bm.1mon"

 KEYWORD PARAMETERS:
        By default, BENCHMARK_1MON will produce the following types
        of output:

          (a) Table of Ox and CO budgets, mean OH conc. and CH3CCL3 lifetime 
          (b) Table of emissions totals
          (c) Frequency distribution histogram
          (d) Vertical profiles of tracer differences along 15S and 42N 
          (e) Maps of tracer concentration @ surface and 500 hPa
          (f) Maps of tracer differences   @ surface and 500 hPa
          (g) Maps of J-value differences  @ surface and 500 hPa
          (h) Maps of tracer ratios        @ surface and 500 hPa

        Each of these types of output can be turned off individually
        with the following keywords:
 
        /NO_AOD_DIFFS -> Do not create difference maps of aerosol optical
             depths.

        /NO_AOD_MAPS -> Do not create concentration plots for aerosol
             optical depths.

        /NO_BUDGET -> Do not create the table of Ox and CO budgets,
             mean OH concentration and CH3CCl3 lifetime.

        /NO_CONC_MAPS -> Do not create the plot the maps of tracer
             concentrations @ sfc and 500 hPa altitude.

        /NO_DIFFS -> Do not create the maps of tracer differences
             at the surface and 500 hPa altitude.

        /NO_EMISSIONS -> Do not create the table of emissions totals. 

        /NO_FREQ_DIST -> Do not create the the frequency distribution
             histogram plot.
        
        /NO_JVALUES -> Do not create the maps of J-value ratios
             at the surface and 500 hPa altitude.

        /NO_JVDIFFS -> Do not create the maps of J-value differences
             at the surface and 500 hPa altitude.

        /NO_JVMAPS -> Do not create the maps of J-values 
             at the surface and 500 hPa altitude.

        /NO_PROFILES -> Do not create the plot of vertical profiles 
             of tracer differences along 15S and 42N.

        /NO_RATIOS -> Do not create the maps of tracer ratios at
             the surface and 500 hPa altitude.

        /NO_STRATDIFF -> Do not create the maps of zonal mean differences
             in the stratosphere (100hPa-0.01hPa)

        /NO_STRATCONC -> Do not create the maps of zonal mean concentrations
             in the stratosphere (100hPa-0.01hPa)

        /NO_ZONALDIFF -> Do not create the maps of zonal mean differences

        /NO_ZONALCONC -> Do not create the maps of zonal tracer concentrations

        /NO_CLOUDDIFF -> Do not create difference plots of cloud optical depth

        /NO_2D_MET -> Do not create difference plots for 2-D met fields

        /NO_3D_MET -> Do not create difference plots for 3-D met fields

        Additional keywords:
        --------------------

        /DEBUG -> Set this switch to print the values of the various
             input variables.  Use this to make sure that all values
             have been created corectly.

        /DYNRANGE -> Set this switch to create additional difference 
             plots, ratio plots, and profile plots using the whole
             dynamic range of the data.

        /NO_FULLCHEM -> Set this switch to only plot the advected 
             tracers and omit full-chemistry quantities such as OH
             and aerosol optical depths.  This is useful if you wish
             to compare output from offline GEOS-Chem simulations
             (e.g. Rn-Pb-Be, CH4).

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        ====================================================
        DynOutFile (function)    GetSfc500Levels (function)  

        External Subroutines Required:
        ====================================================
        CTM_NAMEXT (function)    CTM_TYPE (function) 
        DIFFERENCES              FREQ_DIST         
        FULLCHEM_BUDGET          FULLCHEM_EMISSIONS
        JV_RATIO                 PROFILES
        MAPS                     NYMD2TAU (function)
        RATIOS                   REPLACE_TOKEN
        STRUADDVAR (function)    MCF_LIFETIME (function)

 REQUIREMENTS:
        References routines from the GAMAP package.

 NOTES:
        BENCHMARK_1MON assumes that the following GEOS-Chem
        diagnostic quantities have been archived for the 
        "old" and "new" model versions:

          (a) ND22 ("JV-MAP-$")   (h) ND44 ("DRYD-FLX")
          (b) ND24 ("EW-FLX-$")   (i) ND45 ("IJ-AVG-$")
          (c) ND25 ("NS-FLX-$")   (j) ND65 ("PORL-L=$")
          (d) ND26 ("UP-FLX-$")   (k) ND66 ("DAO-3D-$")
          (e) ND31 ("PEDGE-$" )   (l) ND67 ("DAO-FLDS")
          (f) ND43 ("CHEM-L=$")   (m) ND69 ("DXYP"    )
          (g) ND32 (""NOX-AC-$", "NOX-AN-$", "NOX-BIOB", 
                     "NOX-FERT", "NOX-LI-$", "NOX-SOIL")

 EXAMPLES:
        BENCHMARK_1MON, 'input.1mon'

            ; Produces the full suite of benchmark output plots.

        BENCHMARK_1MON, 'input.1mon', /DYNRANGE

            ; Produces the full suite of benchmark output plots.
            ; Will also produce an additional set of difference and
            ; ratio maps using the full dynamic range of the data.

        BENCHMARK_1MON, 'input.1mon', /DEBUG, /NO_FREQ_DIST

            ; Will produce the standard plots except for the
            ; frequency distribution histogram.  Also will cause
            ; extra information to be echoed to the screen.

 MODIFICATION HISTORY:
        bmy, 09 Nov 2007: VERSION 1.01
                          - based on "benchmark.pro"
        bmy, 10 Jan 2011: VERSION 1.02
                          - Now set proper symbolic links to
                            diaginfo.dat and tracerinfo.dat 
                          - Set 500hPa level for MERRA
                          - Added /NO_PROFILES keyword to suppress
                            printing of vertical profiles
        bmy, 08 Jun 2011: VERSION 1.03
                          - Updated comments
                          - Added /NO_BUDGET, /NO_EMISSIONS, 
                            /NO_PROFILES, /NO_CONC_MAPS, /NO_DIFFS, 
                            /NO_JVALUES, /NO_RATIOS, /NO_FULLCHEM 
                            keywords.
                          - Now pass _EXTRA=e to all routines
                          - Now use FILE_WHICH to locate the 
                            diff_range.1mon file
                          - Now look for diaginfo.dat and 
                            tracerinfo.dat in RUNDIR_2.  Do not
                            use symbolic links anymore.
        bmy, 10 Jun 2011: - Now call EMISSION_RATIOS
        bmy, 23 Jun 2011  - Now call ZONAL_DIFF
        bmy, 18 Jul 2011  - Now pass /PRESSURE keyword to ZONAL_DIFF
                            to create plots w/ pressure on Y-axis
        bmy, 11 May 2012: GAMAP VERSION 2.16
                          - Now do not stop the run if the two model 
                            grids are equivalent.  This allows
                            comparisons between GEOS-5, MERRA,
                            GEOS-5.7 data.  
                          - Return 500hPa level for GEOS-5.7 met
        cdh, 18 Mar 2013: GAMAP VERSION 2.17
                          - Added Zonal concentration plots for !
                            1-month benchmarks
        mps, 16 Sep 2013: - Now create AOD difference plots
                          - Now create AOD map plots
        mps, 18 Nov 2013: - Read in Model_1 and Model_2 as printed in input
                            file. Previously, model names were converted to
                            filename extensions using CTM_NamExt.
                          - Update GetSfc500Levels to accept model names
                          - Rename all instances of GEOS57_47L to GEOSFP_47L
        mps, 02 Dec 2013: - Now create difference plots for 2-D and 3-D
                            met fields
        mps, 03 Dec 2013: - Now create absolute difference plots for J-values
        mps, 21 Apr 2015: - Now create emission maps and emission difference
                            plots
        mps, 11 Sep 2015: - Now create stratospheric benchmark plots showing
                            zonal mean differences and concentrations for
                            100-0.01 hPa
        mps, 04 Mar 2016: - Include MERRA2 in the check for equivalent
                            vertical grids
        mps, 29 Mar 2016: - Add plots for cloud optical depth

(See /n/home09/ryantosca/IDL/gamap2/benchmark/benchmark_1mon.pro)


BINARY (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BINARY (function)

 PURPOSE:
        This function returns the binary representation of a number. 
        Numbers are converted to LONG integers if necessary.

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        RESULT = BINARY( NUMBER ) 

 INPUTS:
        NUMBER -> Number for which its binary representation 
             will be returned.  Number may be any of the numeric
             types (BYTE, INT, LONG, FLOAT, DOUBLE, COMPLEX, etc).

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1)
        PRINT, BINARY( 11B )                                           
           0 0 0 0 1 0 1 1

             ; Binary representation of 11B

        (2) 
        PRINT, FORMAT='(Z9.8,5X,4(1X,8A1))', LONG(!PI,0), BINARY(!PI)
           40490fdb      01000000 01001001 00001111 11011011


             ; If data extraction is used instead of conversion 
             ; Binary representation of pi (little endian IEEE 
             ; representation)


 AUTHOR:
        Kevin Ivory                         Tel: +49 5556 979 434
        Max-Planck-Institut fuer Aeronomie  Fax: +49 5556 979 240
        Max-Planck-Str. 2                   mailto:Kevin.Ivory@linmpi.mpg.de
        D-37191 Katlenburg-Lindau, GERMANY

 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments, cosmetic changes

(See /n/home09/ryantosca/IDL/gamap2/math_units/binary.pro)


BOXPLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BOXPLOT

 PURPOSE:
        Produce a box and whisker plot of a data vector

 CATEGORY:
        Plotting

 CALLING SEQUENCE:
        BOXPLOT,DATA [,keywords]

 INPUTS:
        DATA  --> the data vector

 KEYWORD PARAMETERS:
        GROUP --> array of the same dimension as DATA which contains
             grouping information. One box is plotted for each group.
             If MINGROUP or MAXGROUP are given, boxes and whiskers are
             only plotted for group values within this range.
             GROUP may not contain more than 28 different values.
             Group can also be a string array. In this case MINGROUP
             and MAXGROUP make no sense of course.

        MINGROUP --> the minimum group value for which a box shall be
             plotted

        MAXGROUP --> the maximum group value for which a box shall be
             plotted

        LABEL --> string array containing labels for *different* groups.
             NOTE: The user must take care that one label is passed for
             each group to be plotted. If label is not specified, the
             group values will be used as axis labels

        COLOR --> plotting color for axis (default : 1, i.e. black in MYCT
             color scheme). Will also be used as default for BOXCOLOR.

        BOXCOLOR --> color of the boxes (frames). Default is the COLOR
             value, i.e. 1 if not specified. This color will also be used as
             default for MEDIANCOLOR and MEANCOLOR. If you want boxes that 
             are only filled but have no frame, you must specify BOXCOLOR=-1.
             In this case the default for MEDIANCOLOR and MEANCOLOR will
             be the COLOR value.

        BOXWIDTH --> relative width of boxes (default: 0.8).

        BOXPOSITION --> relative position of box on x axis (default: 0.).
             This parameter can be used together with the OVERPLOT keyword
             to plot multiple groups of boxes in one graph.

        MEDIANCOLOR --> a color value for the median bar
             (default: value of BOXCOLOR)

        MEANSYMBOL --> symbol to be used for mean values. If no symbol
             is given, no mean values will be drawn.

        MEANCOLOR --> color for mean symbols (default: value of BOXCOLOR)

        FILLCOLOR --> a value or an array containing the colorindex for all
             boxes or each box, respectively. If a single value is given,
             *all* boxes will be filled with this color. If an array is 
             passed that has less elements than there are groups to plot, 
             the remaining colors will be filled with 15 (grey in MYCT 
             standard-scheme). If no FILLCOLOR is specified, the boxes will 
             be empty.

        MISSING --> a value that represents missing data. If given, any data
             with a value of missing will be filtered out before plotting.

        PRINTN --> print number of elements on top of each box/whisker

        CHARSIZE --> character size of the PRINTN labels (default: 0.8)

        /OVERPLOT --> do not draw a new coordinate system but overlay new
             data. For 2 sets of data you should use BOXWIDTH=0.4 and
             BOXPOSITION=-0.25 and 0.25, respectively.

        ORIENTATION -> orientation for axis labels (see XYOUTS procedure)

        /IS_PERCENTILE --> data are already processed percentiles. In this
             case data must be an array with dimensions 5,N. The GROUP keyword
             is ignored, and each set of the N percentiles will be treated as
             one group.

        PERCVAL --> float array with 5 elements denoting the percentile
             values (default: 0.05, 0.25, 0.5, 0.75, 0.95)

        Further keywords are passed to the PLOT routine and can be used
        to determine the appearance of the plot (e.g. XTITLE,YTITLE,
        YSTYLE,YRANGE,/YLOG,COLOR,THICK)

 OUTPUTS:

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        PERCENTILES (function)

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1)
        O3   = DATA( WHERE( HEADER EQ 'O3'  ), * )
        ALT  = DATA( WHERE( HEADER EQ 'ALT' ), * )
        IALT = 2.0* FIX( ALT / 2.0 )
        BOXPLOT, O3, GROUP=IALT

             ; Produces a boxplot with ozone percentiles in 
             ; altitude bins of 2 (km).  Axis, box frames and 
             ; labels will be black, boxes are not color filled.

        (2)
        BOXPLOT, O3, GROUP=IALT, FILLC=15, MEANSYM=SYM(1), $
           MEANCOL=2, BOXWIDTH=0.6, YTITLE='O3',           $
           XTITLE='alt. bin', MISSING=-999.99, /PRINTN

             ; Produces boxes that are filled with light grey and 
             ; have a black frame and median line.  A red filled 
             ; circle denotes the mean value, titles are assigned 
             ; to the x and y axis. The number of valid observations 
             ; is printed on top of each box. The boxes are reduced 
             ; in size.

        CO = DATA( WHERE( HEADER EQ 'CO' ), * )
        BOXPLOT, O3, GROUP=IALT, MISSING=-999.99, BOXCOL=4, $
            BOXWIDTH=0.4, BOXPOS=-0.25
        BOXPLOT, CO, GROUP=IALT, MISSING=-999.99, BOXCOL=2, $
            BOXWIDTH=0.4, BOXPOS=+0.25, /OVERPLOT

             ; Produces a plot with blue box frames for ozone 
             ; and red frames for CO data.
            
 MODIFICATION HISTORY:
        mgs, 30 Jul 1997: VERSION 1.00
        mgs, 03 Aug 1997: added template
        mgs, 27 Nov 1997: some revisions and suggested changes by T.Brauers:
             - better color handling (NOTE: meaning of BOXCOLOR has changed)
             - optional overlay of mean value
             - box frames
             - variable boxwidth
             - error fixing lower upper boundaries in log plots
             - bug fix with label keyword
             - added OVERPLOT and BOXPOSITION keywords
        mgs, 22 Jan 1998: added IS_PERCENTILE keyword to allow
               plotting of data that has been processed already
        mgs, 17 Apr 1998: 
             - x-axis handling improved (now uses axis command and xyouts)
             - orientation and medianthick keywords added
        mgs, 21 May 1998:
             - added percval keyword
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/plotting/boxplot.pro)


BPCH2ASCII

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BPCH2ASCII

 PURPOSE:
        Translates data from GAMAP-readable binary punch file v. 2.0 
        format to a simple ASCII file format
       
 CATEGORY:
        File & I/O, BPCH Format

 CALLING SEQUENCE:
        BPCH2ASCII, INFILE, OUTFILE [ , Keywords ]

 INPUTS:
        INFILE -> Name of the binary punch file to read.  If
             INFILE is not passed, the user will be prompted
             to supply a file name via a dialog box.

        OUTFILE -> Name of the ASCII file to be written.  It is
             recommended to insert the tokens %DATE% and %TIME%
             into OUTFILE, since BPCH2ASCII will write a separate
             netCDF file for each time index in the *.bpch file.
             The tokens %DATE% and %TIME% will be overwritten 
             with the current values of YYYYMMDD and HHMMSS.
             Default is "bpch2nc_output.%DATE%.%TIME%.ascii".

 KEYWORD PARAMETERS:
        DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
              array of names which will restrict the data block 
              selection.  If DIAGN is omitted, then all data blocks 
              within INFILE will be saved in ASCII format to OUTFILE.

        /VERBOSE -> If set, then BPCH2ASCII will also echo the
             header lines for each data block to the screen.

        FORMAT -> String containing the numeric format for
             for the data values.  Default is '(7(e13.6,1x))'

 OUTPUTS:
         None

 SUBROUTINES:
         External Subroutines Required:
         =============================================
         CTM_GET_DATA         TAU2YYMMDD    (function)
         GETMODELANDGRIDINFO  REPLACE_TOKEN (function)
         UNDEFINE

 REQUIREMENTS:
         References routines from both GAMAP and TOOLS packages.

 NOTES:
        (1) BPCH2ASCII assumes that all data blocks in the *.bpch file
            file adhere to same grid.  This will be true for output
            files from the GEOS-CHEM model.

        (2) BPCH2ASCII will write a separate ASCII file corresponding
            to each time index in the *.bpch file.  This prevents
            file sizes from getting large, especially if there is
            a lot of diagnostic output in the *.bpch file.

        (3) BPCH2NC will replace the %DATE% token with the 
            current YYYYMMDD value, and will replace the %TIME%
            token with the current HHMMSS value.  Therefore, it
            is recommended to insert these tokens into the string
            passed via OUTFILE.  The tokens %DATE% and %TIME% tokens 
            may be either in uppercase or lowercase.

        (4) The format of the ASCII file is:

               Data block #1 header line
               Data block #1 values (format specified by FORMAT keyword)
               Data block #2 header line
               Data block #2 values (format specified by FORMAT keyword)
                ...

             The header line will contain the units and size of
             each data block.

        (5) The data is written to the ASCII file in column-major 
            order (i.e. the same way as in FORTRAN), so you can read 
            the data into FORTRAN w/ the following code:

                  READ( IUNIT, '(a)' ) HEADER
                  READ( IUNIT, '(1p,7(e13.6,1x))' )
            &       ((DATA(I,J), I=1,IMX), J=1,JMX)

            where IMX and JMX are the dimensions of the data block.       
     

 EXAMPLE:
         BPCH2ASCII, 'myfile.bpch', 'myfile.%DATE%.%TIME%.ascii'
        
             ; Read data from binary punch file 'myfile.bpch'
             ; and writes it to ASCII file 'myfile.bpch.ascii'.


 MODIFICATION HISTORY:
        bmy, 22 May 2002: GAMAP VERSION 1.50
        bmy, 28 May 2002: GAMAP VERSION 1.51
                          - Added FORMAT keyword
        bmy, 03 Jun 2004: GAMAP VERSION 2.02
                          - now pass extra keywords to CTM_GET_DATA
                            via _EXTRA=e keyword
        bmy, 03 Dec 2004: GAMAP VERSION 2.03
                          - add CATEGORY keyword (passed to CTM_GET_DATA)
                            in order to refine data block search
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2ascii.pro)


BPCH2COARDS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BPCH2COARDS

 PURPOSE:
        Reads data from a binary punch file and saves it in a
        COARDS-compliant netCDF (network Common Data Format) file.

        NOTE: COARDS is a formatting standard for netCDF files which
        is widely used in both the atmospheric & climate communities.
        COARDS-compliant netCDF files can be read by GAMAP, GrADS and
        other plotting packages.
        
        See http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html
        for more information about the COARDS standard.

 CATEGORY:
        File & I/O, BPCH Format, Scientific Data Formats

 CALLING SEQUENCE:
        BPCH2COARDS, INFILE, OUTFILE [, Keywords ]

 INPUTS:
        INFILE -> Name of the binary punch file to read.  If INFILE
             is not passed, the user will be prompted to supply a 
             file name via a dialog box.

        OUTFILE -> Name of the netCDF file to be written.  It is
             recommended to insert the tokens %DATE% (or %date%)
             into OUTFILE, since BPCH2COARDS will write a separate
             netCDF file for each unique YYYYMMDD value contained
             within the *.bpch file.  If OUTFILE is not specified,
             BPCH2COARDS will use the default file name 
             "coards.%DATE%.nc".

 KEYWORD PARAMETERS:
        DIAGN -> Array of diagnostic categories from the bpch file
             to save to netCDF format.  If omitted, BPCH2COARDS will 
             save all diagnostic categories.  
 
        /VERBOSE -> If set, will print the name of each tracer
             as it is being written to the netCDF file.  Useful
             for debugging purposes.

        /NC4 -> Write a netCDF4 file instead of netCDF3. Default is
             NetCDF3. NetCDF4 support requires IDL 8.0 or later. 

        COMPRESS -> Integer 0-9 specifies amount of compression in
             netCDF4 files. Default is 2, with very little benefit
             for higher compression.

        /PCOORD -> Use mean pressure as the vertical coordinate rather
             sigma or eta

        /ALTCOORD -> Use mean altitude as the vertical coordinate
             rather than sigma or eta

        /TROPONLY -> Write only tropospheric layers

        /ONEFILE -> Write all data to one netCDF output file.
              Default is one file per calendar day.

        _EXTRA=e -> Picks up additional keywords for NCDF_SET

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ============================================
        CTM_GET_DATA        TAU2YYMMDD    (function)  
        UNDEFINE            REPLACE_TOKEN (function)
        STRREPL (function)  GETMODELANDGRIDINFO
    
 REQUIREMENTS:
        (1) References routines from GAMAP and TOOLS packages.
        (2) You must use a version of IDL containing the NCDF routines.

 NOTES:
        (1) BPCH2COARDS assumes that each data block in the *.bpch
            file is either 2-D (lon-lat) or 3-D (lon-lat-alt). 

        (2) BPCH2COARDS assumes that the number type of each data 
            block in the *.bpch file is REAL*4 (a.k.a. FLOAT). 

        (3) BPCH2COARDS assumes that all data blocks in the *.bpch
            file adhere to same horizontal grid.  This will always
            be true for output files from the GEOS-CHEM model.

        (4) BPCH2COARDS will write a separate COARDS-compliant netCDF
            file corresponding to each unique YYYYMMDD date.  This 
            prevents the files from becoming too large to be read
            with IDL.

        (5) BPCH2COARDS will replace the %DATE% (or %date%) token with
            the current YYYYMMDD value.  Therefore, it is recommended
            to insert this token into the string passed via OUTFILE.

        (6) BPCH2COARDS will write arrays containing the latitudes,
            longitudes to the netCDF file.  For 3-D data blocks,
            the eta or sigma centers will also be written to the
            file.  Time will be written as TAU values (i.e. hours
            since 00:00 GMT on 01-Jan-1985.

        (7) The netCDF library has apparently been updated in 
            IDL 6.0+.  The result is that variable names containing
            characters such as '$', '=', and ':' may now cause an
            error in NCDF_VARDEF.  Therefore, we now pre-screen 
            tracer names with function NCDF_VALID_NAME.
           
 EXAMPLE:
        BPCH2COARDS, 'myfile.bpch', 'myfile.%DATE%.nc'

            ; Will write the contents of "myfile.bpch" to one
            ; or more COARDS-compliant netCDF files adhering
            ; to the filename convention "myfile.YYYYMMDD.nc"

 MODIFICATION HISTORY:
  rjp & bmy, 17 Mar 2005: GAMAP VERSION 2.03
                          - Based on bpch2nc.pro
        bmy, 21 Jul 2005: GAMAP VERSION 2.04
                          - Bug fix: 
        bmy, 13 Jul 2006: GAMAP VERSION 2.05
                          - Remove call to PTR_FREE
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now count GCAP among the GEOS family
                            for the purpose of converting the TAU
                            date to a YYYY/MM/DD date.
        phs, 29 Oct 2009: GAMAP VERSION 2.14
                          - Can process files with 3D data on both
                            centers and edges of the grid boxes.
        bmy, 19 Dec 2011: GAMAP VERSION 2.16
                          - Now handles multiple vertical dimensions
                            in the bpch file properly.
                          - Bug fix: now write vertical levels edges to 
                            the file.
        bmy, 27 Sep 2012: - Bug fix: Now handle data blocks that straddle
                            the date line.
        bmy, 05 Nov 2013: GAMAP VERSION 2.17
                          - Change attributes for better COARDS compliance
        bmy, 12 Feb 2014: GAMAP VERSION 2.18
                          - Add more modifications for 4-D data blocks
                            from bpch files created w/ GC_COMBINE_ND49
        bmy, 03 Mar 2015: - Now define dims in order: time, lev, lon, lat,
                            which is more COARDS compliant.
        cdholmes, 29 Mar 2017 - Add support for NetCDF4 and
                                compression
                              - Add support for pressure and altitude
                                as vertical coordinate
                              - ONEFILE puts all data into a single
                                output file
                              - TROPONLY limits the output to
                                troposphere layers
                              - Singleton "altXXX" dimensions are avoided

(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2coards.pro)


BPCH2GMI

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BPCH2GMI

 PURPOSE:
        Reads data from a binary punch file and saves it in
        netCDF (network Common Data Format) format.  The data
        will be shifted so that the first longitude is 0 degrees
        (i.e. the prime meridian) in order to conform with the
        GMI (Global Model Initiative) model grid definition.

 CATEGORY:
        File & I/O, BPCH Format, Scientific Data Formats

 CALLING SEQUENCE:
        BPCH2GMI, INFILE, OUTFILE [, Keywords ]

 INPUTS:
        INFILE -> Name of the binary punch file to read.  If
             INFILE is not passed, the user will be prompted
             to supply a file name via a dialog box.

        OUTFILE -> Name of the netCDF file to be written.  It is
             recommended to insert the tokens %DATE% and %TIME%
             into OUTFILE, since BPCH2NC will write a separate
             netCDF file for each time index in the *.bpch file.
             The tokens %DATE% and %TIME% will be overwritten 
             with the current values of YYYYMMDD and HHMMSS.
             Default is "bpch2nc_output.%DATE%.%TIME%.nc".

 KEYWORD PARAMETERS:
        DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
             array of names which will restrict the data block 
             selection.  If DIAGN is omitted, then all data blocks 
             within INFILE will be saved in netCDF format to OUTFILE.
 
        /VERBOSE -> If set, will print the names of each tracer
             as it is being written to the netCDF file.

        _EXTRA=e -> Picks up additional keywords for netCDF routines

 OUTPUTS:

 SUBROUTINES:
        Internal Subroutines:
        ============================================
        B2G_Valid_VarName (function)
        B2G_SetNcDim      (function)
        B2G_GetNcDim      (function)

        External Subroutines Required:
        ============================================
        CTM_GET_DATA        TAU2YYMMDD    (function)  
        UNDEFINE            REPLACE_TOKEN (function)
        STRREPL (function)  GETMODELANDGRIDINFO
    
 REQUIREMENTS:
        (1) References routines from GAMAP and TOOLS packages.
        (2) You must use a version of IDL containing the NCDF routines.

 NOTES:
        (1) BPCH2GMI assumes that each data block in the *.bpch file
            is either 2-D (lon-lat) or 3-D (lon-lat-alt). 

        (2) BPCH2GMI assumes that the number type of each data block
            in the *.bpch file is REAL*4 (a.k.a. FLOAT). 

        (3) BPCH2GMI assumes that all data blocks in the *.bpch file
            file adhere to same horizontal grid.  This will always
            be true for output files from the GEOS-CHEM model.

        (4) BPCH2GMI will write a separate NC file corresponding
            to each time index in the *.bpch file.  This prevents
            file sizes from getting large, especially if there is
            a lot of diagnostic output in the *.bpch file.

        (5) BPCH2GMI will replace the %DATE% token with the 
            current YYYYMMDD value, and will replace the %TIME%
            token with the current HHMMSS value.  Therefore, it
            is recommended to insert these tokens into the string
            passed via OUTFILE.  The tokens %DATE% and %TIME% tokens 
            may also be passed in lowercase (e.g,  %date%, %time% ).  

        (6) BPCH2GMI will write arrays containing the latitudes,
            longitudes to the netCDF file.  For 3-D data blocks,
            the sigma centers will also be written to the file.  
            Date and time are stored as global attributes.

        (7) The netCDF library has apparently been updated in 
            IDL 6.0+.  The result is that variable names containing
            characters such as '$', '=', and ':' may now cause an
            error in NCDF_VARDEF.  Therefore, we now pre-screen 
            tracer names with function NCDF_VALID_NAME.
           
 EXAMPLE:
        BPCH2GMI, 'myfile.bpch', 'myfile.%DATE%.%TIME%.nc'

            ; Will write the contents of "myfile.bpch" to one
            ; or more netCDF files "myfile.YYYYMMDD.HHMMSS.nc"

 MODIFICATION HISTORY:
  bmy & phs, 20 Aug 2007: GAMAP VERSION 2.10
                          - Based on BPCH2NC
        bmy, 19 Dec 2007: GAMAP VERSION 2.12
                          - Now save sigma edges & centers or
                            eta edges & centers to the file.
                          - Extra error trap, if there is only one
                            level in the file then set IS_3D=0.
        bmy, 20 Dec 2011: GAMAP VERSION 2.16
                          - Changed default filename to "bpch2

(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2gmi.pro)


BPCH2HDF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BPCH2HDF

 PURPOSE:
        Reads data from a binary punch file and saves it in HDF-SD 
        (Hierarchical Data Format, Scientific Dataset) format.

 CATEGORY:
        File & I/O, BPCH Format, Scientific Data Formats

 CALLING SEQUENCE:
        BPCH2HDF, INFILE, OUTFILE [, Keywords ]

 INPUTS:
        INFILE -> Name of the binary punch file to read.  If
             INFILE is not passed, the user will be prompted
             to supply a file name via a dialog box.

        OUTFILE -> Name of the HDF file to be written.  It is
             recommended to insert the tokens %DATE% and %TIME%
             into OUTFILE, since BPCH2HDF will write a separate
             HDF file for each time index in the *.bpch file.
             The tokens %DATE% and %TIME% will be overwritten 
             with the current values of YYYYMMDD and HHMMSS.
             Default is "bpch2hdf_output.%DATE%.%TIME%.hdf".

 KEYWORD PARAMETERS:
        DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
              array of names which will restrict the data block 
              selection.  If DIAGN is omitted, then all data blocks 
              within INFILE will be saved in HDF format to OUTFILE.

        _EXTRA=e -> Picks up additional keywords for HDF_SETSD

 OUTPUTS:

 SUBROUTINES:
        External Subroutines Required:
        =========================================
        CTM_GET_DATA    TAU2YYMMDD    (function)  
        UNDEFINE        REPLACE_TOKEN (function)
        HDF_SETSD       GETMODELANDGRIDINFO

 REQUIREMENTS:
        (1) References routines from GAMAP and TOOLS packages.
        (2) You must use a version of IDL containing the HDF-SD routines.

 NOTES:
        (1) BPCH2HDF assumes that each data block in the *.bpch file
            is either 2-D (lon-lat) or 3-D (lon-lat-alt).  

        (2) BPCH2HDF assumes that all data blocks in the *.bpch file
            file adhere to same horizontal grid.  This will be true
            for output files from the GEOS-CHEM model.

        (3) BPCH2HDF will write a separate HDF file corresponding
            to each time index in the *.bpch file.  This prevents
            file sizes from getting large, especially if there is
            a lot of diagnostic output in the *.bpch file.

        (4) BPCH2HDF will replace the %DATE% token with the 
            current YYYYMMDD value, and will replace the %TIME%
            token with the current HHMMSS value.  Therefore, it
            is recommended to insert these tokens into the string
            passed via OUTFILE.  These tokens may be in either
            uppercase or lowercase.

        (4) BPCH2HDF will also write arrays containing the latitudes,
            longitudes, sigma coordinates (for 3-D data blocks only!)
            to the HDF file.

        (5) BPCH2HDF will write arrays containing the latitudes,
            longitudes to the netCDF file.  For 3-D data blocks,
            the sigma centers and sigma edges will also be written 
            to the file.

 EXAMPLE:
        BPCH2HDF, 'myfile.bpch', 'myfile.%DATE%.%TIME%.hdf'

            ; Will write the contents of "myfile.bpch" to
            ; one or more HDF files "myfile.YYYYMMDD.HHMMSS.hdf"

 MODIFICATION HISTORY:
        bmy, 22 May 2002: GAMAP VERSION 1.50
        bmy, 22 Oct 2002: GAMAP VERSION 1.52
                          - bug fix: now do not write vertical layer 
                            dim info to HDF file for 2-D grids
        bmy, 22 May 2003: GAMAP VERSION 1.53
                          - Make sure LONGNAME is not a null string
        bmy, 18 Sep 2003: - Call PTR_FREE to free the pointer memory
        bmy, 03 Jun 2004: GAMAP VERSION 2.02
                          - now pass extra keywords to CTM_GET_DATA
                            via _EXTRA=e keyword
        bmy, 03 Sep 2004: GAMAP VERSION 2.03
                          - now defines ETAC and ETAE variables
                            for hybrid grids
        bmy, 03 Dec 2004: GAMAP VERSION 2.03
                          - add DIAGN keyword (passed to CTM_GET_DATA)
                            in order to refine data block search
        bmy, 19 May 2006: GAMAP VERSION 2.05
                          - Now do not free the pointer memory
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now count GCAP among the GEOS family
                            for the purpose of converting the TAU
                            date to a YYYY/MM/DD date.
        bmy, 18 Feb 2009: GAMAP VERSION 2.13
                          - Bug fix: should be N_ELEMENTS( DiagN )
                            instead of N_ELEMENTS( Category ) in the
                            IF statement for CTM_GET_DATA.

(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2hdf.pro)


BPCH2NC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BPCH2NC

 PURPOSE:
        Reads data from a binary punch file and saves it in
        netCDF (network Common Data Format) format.

 CATEGORY:
        File & I/O, BPCH Format, Scientific Data Formats

 CALLING SEQUENCE:
        BPCH2NC, INFILE, OUTFILE [, Keywords ]

 INPUTS:
        INFILE -> Name of the binary punch file to read.  If
             INFILE is not passed, the user will be prompted
             to supply a file name via a dialog box.

        OUTFILE -> Name of the netCDF file to be written.  It is
             recommended to insert the tokens %DATE% and %TIME%
             into OUTFILE, since BPCH2NC will write a separate
             netCDF file for each time index in the *.bpch file.
             The tokens %DATE% and %TIME% will be overwritten 
             with the current values of YYYYMMDD and HHMMSS.
             Default is "bpch2nc_output.%DATE%.%TIME%.nc".

 KEYWORD PARAMETERS:
        DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
              array of names which will restrict the data block 
              selection.  If DIAGN is omitted, then all data blocks 
              within INFILE will be saved in netCDF format to OUTFILE.
 
        /VERBOSE -> If set, will print the names of each tracer
             as it is being written to the netCDF file.

        _EXTRA=e -> Picks up additional keywords for NCDF_SET

 OUTPUTS:

 SUBROUTINES:
        Internal Subroutines:
        ============================================
        B2N_Valid_VarName (function)
        B2N_SetNcDim      (function)
        B2N_GetNcDim      (function)

        External Subroutines Required:
        ============================================
        CTM_GET_DATA        TAU2YYMMDD    (function)  
        UNDEFINE            REPLACE_TOKEN (function)
        STRREPL (function)  GETMODELANDGRIDINFO
    
 REQUIREMENTS:
        (1) References routines from GAMAP and TOOLS packages.
        (2) You must use a version of IDL containing the NCDF routines.

 NOTES:
        (1) BPCH2NC assumes that each data block in the *.bpch file
            is either 2-D (lon-lat) or 3-D (lon-lat-alt). 

        (2) BPCH2NC assumes that the number type of each data block
            in the *.bpch file is REAL*4 (a.k.a. FLOAT). 

        (3) BPCH2NC assumes that all data blocks in the *.bpch file
            file adhere to same horizontal grid.  This will always
            be true for output files from the GEOS-CHEM model.

        (4) BPCH2NC will write a separate NC file corresponding
            to each time index in the *.bpch file.  This prevents
            file sizes from getting large, especially if there is
            a lot of diagnostic output in the *.bpch file.

        (5) BPCH2NC will replace the %DATE% token with the 
            current YYYYMMDD value, and will replace the %TIME%
            token with the current HHMMSS value.  Therefore, it
            is recommended to insert these tokens into the string
            passed via OUTFILE.  The tokens %DATE% and %TIME% tokens 
            may also be passed in lowercase (e.g,  %date%, %time% ).  

        (6) BPCH2NC will write arrays containing the latitudes,
            longitudes to the netCDF file.  

        (7) For pure-sigma grids (e.g. GEOS-1, GEOS-STRAT, GEOS-3),
            BPCH2NC will write the following additional variables to 
            the netCDF file:

            (1) SIGE : Sigma coordinate at level edges
            (2) SIGC : Sigma coordinate at level centers

            The pressure at the bottom edge of level L is given by:

                Pe(L) = Ptop + [ SIGE(L) * ( Psurface - Ptop ) ]

            and the pressure at the vertical center of level L is:

                Pc(L) = Ptop + [ SIGC(L) * ( Psurface - Ptop ) ]

            %%%%% NOTE: This is mostly obsolete, as most met fields
            %%%%% that are used to drive CTM's are now placed onto
            %%%%% hybrid grids.

        (8) For hybrid grids (e.g. GEOS-4, GEOS-5, MERRA), the following
            dditional variables will be written to the netCDF file:

            (1) ETAE : Eta coordinate on level edges
            (2) ETAC : Eta coordinate on level centers
            (3) Ap   : Hybrid grid "A" parameter
            (4) Bp   : Hybrid grid "B" parameter

            The pressure at the bottom edge of level L is given by:
 
                Pe(L) = Ap(L) + ( Bp(L) * Psurface )

            and the pressure at the vertical center of level L is:

                Pc(L) = ( Pe(L) + Pe(L+1) ) * 0.5

            The hybrid ETA coordinates (similar to sigma) at the 
            level edges and centers are, correspondingly:

                ETAE(L) = ( Pe(L) - Ptop ) / ( Psurface - Ptop )
                ETAC(L) = ( Pc(L) - Ptop ) / ( Psurface - Ptop )

            %%%%% NOTE: The ETAe and ETAc values are only approximate
            %%%%% and are computed with a surface pressure of 1013.25
            %%%%% hPa.  For your scientific analysis, you should compute
            %%%%% the pressures at level edges from Ap, Bp, and a 
            %%%%% spatially-varying surface pressure field (e.g. saved
            %%%%% out from GEOS-Chem or another model).
          
        (7) The date and time of the data are stored in the netCDF 
            file as global attributes.

        (8) The netCDF library has apparently been updated in 
            IDL 6.0+.  The result is that variable names containing
            characters such as '$', '=', and ':' may now cause an
            error in NCDF_VARDEF.  Therefore, we now pre-screen 
            tracer names with function NCDF_VALID_NAME.
           
 EXAMPLE:
        BPCH2NC, 'myfile.bpch', 'myfile.%DATE%.%TIME%.nc'

            ; Will write the contents of "myfile.bpch" to one
            ; or more netCDF files "myfile.YYYYMMDD.HHMMSS.nc"

 MODIFICATION HISTORY:
        bmy, 22 May 2002: GAMAP VERSION 1.50
        bmy, 22 Oct 2002: GAMAP VERSION 1.52
                          - bug fix: now do not write vertical layer 
                            dim info to netCDF file for 2-D grids
        bmy, 22 May 2003: GAMAP VERSION 1.53
                          - Bug fix: LONGNAME cannot be a null string
        bmy, 22 Sep 2003: - Now declare all variables first, then save
                            data into them.  This is much more efficient!
                          - Remove reference to NCDF_SET routine
                          - Call PTR_FREE to free the pointer memory
                          - Bug fix: now sort TAU0 values for call to UNIQ
                          - added /VERBOSE keyword
        bmy, 09 Oct 2003: - for IDL 6.0+, use '__' to separate category
                            name from the tracer name
        bmy, 21 Oct 2003: - Now uses function NCDF_Valid_Name to screen 
                            out and replace invalid characters for netCDF 
                            variable names
        bmy, 06 Nov 2003: GAMAP VERSION 2.01
                          - added extra global attributes to facilitate
                            reading netCDF files created by BPCH2NC
                            into GAMAP
        bmy, 29 Mar 2004: GAMAP VERSION 2.02
                          - Now saves ETA centers for hybrid grid
                            instead of sigma centers
        bmy, 17 Mar 2005: GAMAP VERSION 2.03
                          - Bug fix: now prints ETAC properly 
                            when the /VERBOSE keyword is set   
        bmy, 03 Oct 2006: GAMAP VERSION 2.05
                          - Bug fix: now do not call PTR_FREE
                            to free the pointer memory
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now count GCAP among the GEOS family
                            for the purpose of converting the TAU
                            date to a YYYY/MM/DD date.
        bmy, 21 Jan 2008: GAMAP VERSION 2.12
                          - Now save sigma edges & centers or
                            eta edges & centers to the file.
                          - Extra error trap, if there is only one
                            level in the file then set IS_3D=0.
                          - Now error check for duplicate variable names
        bmy, 28 Nov 2008: GAMAP VERSION 2.15
                          - Now save out hybrid-grid Ap and Bp
                            parameters so that users can accurately
                            compute the pressure at level edges and
                            centers.
                          - Updated comments
        bmy, 07 Mar 2012: GAMAP VERSION 2.16
                          - Correct typos in /VERBOSE output

(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2nc.pro)


BPCH2PCH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BPCH2PCH

 PURPOSE:
        Translates data from GAMAP-readable binary punch
        file v. 2.0 format to the ancient ASCII-punch
        file standard.
       
 CATEGORY:
        File & I/O, BPCH Format

 CALLING SEQUENCE:
        BPCH2PCH, FILENAME [, OUTFILENAME [, Keywords ] ]

 INPUTS:
        FILENAME -> Name of the binary punch file from which 
             to read data.  FILENAME may be a file mask, and may
             contain wild card characters (e.g. ~/ctm.bpch.*). If
             FILENAME is omitted or contains a wild card character,
             the user will be prompted to pick a file via a dialog box.

        OUTFILENAME (optional) -> Name of the output ASCII punch
             file.  Default is 'ASCIIfile.pch' 

 KEYWORD PARAMETERS:
        DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
              array of names which will restrict the data block 
              selection.  If DIAGN is omitted, then all data blocks 
              within INFILE will be saved in ASCII punch format
              to OUTFILE.

         /EXTRA_SPACE -> If set, will put an extra space between
             the numbers in the ASCII punch file.  This might 
             be necessary when using MATLAB or S-PLUS to read
             in the ASCII punch file.

 OUTPUTS:
         Writes data to ASCII punch file format

 SUBROUTINES:
         CTM_GET_DATA 

 REQUIREMENTS:
         References routines from both GAMAP and TOOLS packages.

 NOTES:
         Some limitations:
         (1) Works only for global lon-lat diagnostics.           
         (2) The top header line might be inaccurate (but nobody
             really reads that anyway, so forget it for now...)

 EXAMPLE:
         BPCH2PCH, '~/bmy/ctm.bpch', '~/bmy/ctm.pch'
        
             ; Reads data from binary punch file '~/bmy/ctm.bpch'
             ; and writes it to ASCII punch file '~/bmy/ctm.pch'. 


 MODIFICATION HISTORY:
        bmy, 08 Nov 1999: VERSION 1.00
        bmy, 03 Jun 2004: GAMAP VERSION 2.02
                          - now pass extra keywords to CTM_GET_DATA
                            via _EXTRA=e keyword;
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2pch.pro)


BPCH_LINK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BPCH_LINK

 PURPOSE:
        Copies data from several binary punch files into a single
        binary punch file.  Also can trim data down to nested-grid
        resolution if necessary

 CATEGORY:
        File & I/O, BPCH Format

 CALLING SEQUENCE:
        BPCH_LINK, INFILES, OUTFILE [, Keywords ]

 INPUTS:
        INFILES -> A path name or file mask (with wildcards) 
             which indicates the names of the individual files
             to be linked together in a single bpch file.

        OUTFILE -> Name of the bpch file that will contain data
             from the individual bpch files specified by INFILES.

 KEYWORD PARAMETERS:
        /CREATE_NESTED --> If set, then BPCH_LINK will trim data
             to the nested grid resolution as specified by the
             XRANGE and YRANGE keywords.

        XRANGE -> A 2-element vector containing the minimum and
             maximum box center longitudes which define the nested
             model grid. Default is [-180,180].

        YRANGE -> A 2-element vector containing the minimum and
             maximum box center latitudes which define the nested
             model grid. Default is [-90,90].

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        OPEN_FILE      UNDEFINE
        CTM_DIAGINFO

 REQUIREMENTS:
        Requires routines from the GAMAP and TOOLS packages.

 NOTES:
        None

 EXAMPLE:
        BPCH_LINK, 'ctm.bpch.*', 'new.ctm.bpch'

             ; Consolidates data from the 'ctm.bpch.*' files
             ; into a single file named 'new.ctm.bpch'

 MODIFICATION HISTORY:
        bmy, 31 Jan 2003: VERSION 1.00
        bmy, 09 Apr 2003: VERSION 1.01
                          - now can save to nested grid 
        bmy, 15 May 2003: VERSION 1.02
                          - now can pass a list of files via INFILES
        bmy, 20 Nov 2003: GAMAP VERSION 2.01
                          - now gets the spacing between diagnostic
                            offsets from CTM_DIAGINFO
        bmy, 28 May 2004: GAMAP VERSION 2.02
                          - Now use MFINDFILE to get INLIST regardless
                            of the # of elements of INFILES 
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 02 Apr 2008: GAMAP VERSION 2.12
                          - Now read/write bpch as big-endian

(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_link.pro)


BPCH_MONTHLY_MEAN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BPCH_MONTHLY_MEAN

 PURPOSE:
        Creates monthly means from GEOS-Chem output saved at less
        than monthly intervals.  Ideal for working with output of 
        high-resolution model output, especially if your queuing
        system time limits do not permit a 1-month simulation to be
        completed in a single run stage.

 CATEGORY:
        File & I/O, BPCH Format

 CALLING SEQUENCE:
        BPCH_MONTHLY_MEAN, FILES [, Keywords ]

 INPUTS:
        FILES -> A vector containing the pathnames of the files from
             which you would like to create monthly mean output.

 KEYWORD PARAMETERS:
        OUTFILENAME -> Name of the file (bpch format) that will
             contain the monthly mean output.  The default is 
             "bpch_monthly_mean_output.bpch".

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required
        ================================

 REQUIREMENTS:
        Requires other routines from the GAMAP package.

 NOTES:
        Assumes that each of the files passed via the FILES argument
        contains an identical sequence of diagnostic data blocks.
        This will normally be the case for GEOS-Chem simulations that 
        have to be separated into several run stages for the queue
        system.

        Error checking is minimal, we will fix this later.  This
        routine in intended for use with files that are created from
        individual stages of a long GEOS-Chem simulation.  As such,
        we can usually assume that all files will have the same
        sequence of data blocks, and that all data blocks will be on
        the same grid.

 EXAMPLE:
        FILES = [ 'ctm.bpch.2011010100', 'ctm.bpch.2011011500' ]
        BPCH_MONTHLY_MEAN, FILES, OUTFILENAME = 'monthly_mean.bpch'

             ; Creates monthly-mean output from two GEOS-Chem bpch
             ; files that contain 15-day averaged data.

 MODIFICATION HISTORY:
        bmy, 21 Dec 2011: GAMAP VERSION 2.16
                          - Initial version

(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_monthly_mean.pro)


BPCH_SEP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BPCH_SEP

 PURPOSE:
        Separates data from one binary punch file into another binary 
        punch file by time (TAU0), tracer, or location indices.  Useful 
        for making smaller bpch files so that we don't run out of IDL 
        memory when reading/processing them.

 CATEGORY:
        File & I/O, BPCH Format

 CALLING SEQUENCE:p
        BPCH_SEP, INFILE, OUTFILE [, Keywords ]

 INPUTS:
        INFILE -> A path name or file mask (with wildcards) 
             which indicates the names of the individual files
             to be linked together in a single bpch file.

        OUTFILE -> Name of the bpch file that will contain data
             from the individual bpch files specified by INFILES.

 KEYWORD PARAMETERS:
        DIAGN -> Array of diagnostic categories for which to 
             save out to OUTFILE  Default is to save all diagnostic
             categories to OUTFILE.

        TAU0 -> Time index (hours from 1 Jan 1985) denoting the
             data blocks to be saved from INFILE to OUTFILE.  You
             can use NYMD2TAU to compute this from a YYYYMMDD date.

        TRACER -> Tracer number(s) for which to save to OUTFILE.  
             Default is to save all tracers.

        II, JJ, LL -> Longitude, latitude, altitude index arrays used
             to cut down the data block to less than global size. Use
             IDL notation, meaning first element is 0.

        GLOBALCOORDS ->  When the data entries in the bpch file 
             contain only part of the global CTM grid (e.g. ND48,
             ND49, ND50, ND51) this indicates 
             that II, JJ, LL indices should be
             interpreted as global CTM indices, rather than relative
             to the regional subset grid. 

         EXCLUDE -> Reverses the selection criteria, so that the
         designated DIAGN, TAU0, and TRACER are EXCLUDED from the
         output file. Everything else is included. In order to be
         excluded, a datablock must match all specified keywords:
         DIAGN, TAU0, and TRACER. 


 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===============================================
        CTM_DIAGINFO    LITTLE_ENDIAN (function)
        OPEN_FILE       UNDEFINE 

 REQUIREMENTS:
        None

 NOTES:
        (1) Assumes that II, JJ, LL contain consecutive indices in
            longitude, latitude, and altitude, respectively.

        (2) Also assumes that II, JJ, LL are in IDL notation
            (i.e. starting from zero).  This is so that you can
            pass the output from the WHERE command to BPCH_SEP.

 EXAMPLES:
        (1)
        BPCH_SEP, 'ctm.bpch.big', 'ctm.bpch.small', tau0=140256D

             ; Pulls out data blocks for TAU0=140256 (1/1/2001) from
             ; "ctm.bpch.big" and saves them in "ctm.bpch.small"


        (2) 
        INTYPE = CTM_TYPE( 'GEOS4', RES=4 )
        INGRID = CTM_GRID( INTYPE )
  
        INDX = WHERE( INGRID.XMID ge -60 AND INGRID.XMID le 60 )
        INDY = WHERE( INGRID.YMID ge   0 AND INGRID.YMID le 60 )
         
        BPCH_SEP, 'ctm.bpch.big', 'ctm.bpch.small', II=INDX, JJ=INDY

             ; Pulls out all data blocks for the geographical area
             ; from 60W - 60E longitude and 0-60N latitude.

 MODIFICATION HISTORY:
        bmy, 18 Sep 2003: GAMAP VERSION 1.53
        bmy, 20 Nov 2003: GAMAP VERSION 2.01
                          - now gets the spacing between diagnostic
                            offsets from CTM_DIAGINFO
        bmy, 07 Jul 2005: GAMAP VERSION 2.04
                          - minor bug fix; now can save out data
                            blocks for more than one matching TAU0
        phs, 24 Oct 2006: GAMAP VERSION 2.05
                          - Added the II, JJ, LL keywords for
                            selecting a smaller geographical area.  
                            These must be index arrays.
                          - Added the TRACERN keyword
                          - Added SWAP_ENDIAN=LITTLE_ENDIAN() in 
                            the call to OPEN_FILE
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 02 Apr 2008: GAMAP VERSION 2.12
                          - Cosmetic changes
        bmy, 18 Jul 2016: GAMAP VERSION 2.19
                          - Now use the spacing obtained from
                            the diaginfo.dat file
        cdh, 04 Apr 2017: -Add GlobalCoord keyword so that II,JJ,LL keywords
                           work with ND48, ND49, ND50 and ND51 output
                          -Prevent writing data when no matching
                           II,JJ,LL coordinates

(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_sep.pro)


BPCH_TEST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        BPCH_TEST

 PURPOSE:
        Reads header and data block information from binary punch 
        (BPCH for short) files and prints the file pointer locations.

 CATEGORY:
        File & I/O, BPCH Format

 CALLING SEQUENCE:
        BPCH_TEST [, FILENAME, [ Keywords ] ]

 INPUTS:
        FILENAME (optional) -> Name of the binary punch file to read.
             If omitted, a dialog box will prompt the user to make
             a selection.
             
 KEYWORD PARAMETERS:
        /NOPAUSE -> If set, will not pause after displaying information   
             about each data block.  Default is to pause to allow the
             user to examine each data blocks header information.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ------------------------------
        LITTLE_ENDIAN (function)

 REQUIREMENTS:
        References routines from the TOOLS package.

 NOTES:
        BPCH_TEST does not return any data values from the binary
        punch file.  It is meant to be used for debugging purposes.

 EXAMPLES:
        BPCH_TEST, 'my.bpch'  
        BPCH_TEST, FILENAME = 'my.bpch'
               
             ; will print info about each data block in 'my.bpch'

 MODIFICATION HISTORY:
        bmy, 10 Dec 1999: VERSION 1.00
        bmy, 25 May 2000: GAMAP VERSION 1.45
                          - allow user to quit after viewing 
                            each data block header
                          - add FILENAME keyword, so that the filename  
                            can be passed as a parameter or a keyword
        bmy, 21 Jul 2000: GAMAP VERSION 1.46
                          - now print locations of min, max data values
                          - changed FILETYPE to reflect new definitions
                            from CTM_OPEN_FILE 
        bmy, 24 Aug 2004: GAMAP VERSION 2.03
                          - Now recognizes bpch file containing
                            GEOS-CHEM station timeseries data
                          - Updated comments, cosmetic change
        bmy, 05 Feb 2013: GAMAP VERSION 2.17
                          - Now recognize FTI "CTM bin 4D", which is
                            output from gc_combine_nd49.pro etc.

(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_test.pro)


CAT_STRUCT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CAT_STRUCT

 PURPOSE: 
        Concatenate all tags within 2 or more structures. 
        Return one structure with the same tags as each individual 
        structure.

 CATEGORY:
        Structures

 CALLING SEQUENCE:
        RESULT = CAT_STRUCT( STR1, STR2, STR3, STR4, STR5 )

 INPUTS:
        STR1, STR2, STR3, STR4, STR5 -> Structures to concatenate

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The concatenated structure

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        The user can concatenate as many structures as desired by
        adding extra input arguments: st6, st7, st8, etc.

 EXAMPLE:
         a = {Name: 'Larry', Age: 46}
         b = {Name: 'Chuck', Age: 10}
         c = {Name: 'Alice', Age: 35}

         d = cat_struct( a, b, c )
         print, d.Name


 MODIFICATION HISTORY:
        cdh, 08 Jul 2010: GAMAP VERSION 2.15
                          - Initial version

(See /n/home09/ryantosca/IDL/gamap2/structures/cat_struct.pro)


CHKSTRU (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CHKSTRU  (function)

 PURPOSE:
        Check validity of a structure and test if necessary
        fields are contained

 CATEGORY:
        Structures

 CALLING SEQUENCE:
        RESULT = CHKSTRU( STRUCTURE, [ FIELDS, Keywords ] ) 

 INPUTS:
        STRUCTURE -> the structure to be tested.  If STRUCTURE is
             not of type structure, the function will return 0

        FIELDS (optional) -> a string or string array with field 
             names to be contained in STRUCTURE.  CHKSTRU returns 
             1 (true) only if all field names are contained in 
             STRUCTURE.  The entries of FIELDS may be upper or 
             lowercase.

 KEYWORD PARAMETERS:
        INDEX -> a named variable that will contain the indices of
             the required field names in the structure. They can then
             be assessed through structure.(index(i)) . Index will
             contain -1 for all fields entries that are not in the
             structure.

        /VERBOSE -> set this keyword to return an error message 
             in case of an error.

 OUTPUTS:
        RESULT -> Returns 1 if successful, otherwise 0.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1)
        TEST     = { a:1, b:2, c:3 }
        IF CHKSTRU( TEST ) THEN PRINT, 'TEST is a structure!'
          TEST is a structure!

             ; Verify that TEST is a structure rather than
             ; a scalar or an array variable. 

        (2)
        TEST     = { a:1, b:2, c:3 }
        REQUIRED = [ 'a', 'c' ]
        IF CHKSTRU( TEST, REQUIRED ) THEN PRINT, 'Found a and c.'
          Found a and c.

             ; MAKES sure that structure TEST contains
             ; the tag names A and C.

 MODIFICATION HISTORY:
        mgs, 02 Mar 1998: VERSION 1.00
        mgs, 07 Apr 1998: - second parameter (FIELDS) now optional
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated documentation

(See /n/home09/ryantosca/IDL/gamap2/structures/chkstru.pro)


CHOICE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CHOICE

 PURPOSE:
        Allows user to choose interactively from several options.

 CATEGORY:
        General

 CALLING SEQUENCE:
        RESULT = CHOICE( VALUES [,options] )

 INPUTS:
        VALUES  -> a string array containing the selectable options

 KEYWORD PARAMETERS:
        TITLE -> title to be displayed on top of the selection menu

        DEFAULT -> a default selection (to allow user to simply 
             press enter)

        BY_INDEX  -> return selection index rather than value

        /NOABORT -> prevents addition of 'ABORT' to selection

 OUTPUTS:
        CHOICE returns a string containing the selected value or
            the index of the selection if keyword /BY_INDEX is set.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        CHOICE automatically adds 'ABORT' to the list of selections.
        If keyword BY_INDEX is set then ABORT will return -1
        (unless /NOABORT keyword is set)

 EXAMPLE:
        DIRNAMES = [ '~my/dir/','~your/dir/','~any/dir']
        DIR      = CHOICE( DIRNAMES, TITLE='Select Directory' )

        IF (DIR ne 'ABORT') THEN BEGIN
            OPENR, U1, DIR+FILE, /GET_LUN
            READF, U1, DATA
            CLOSE, U1
            FREE_LUN,U1
        ENDIF ELSE PRINT,'ABORTED !'

             ; Allow user to pick a directory and then
             ; read a file from that directory.

 MODIFICATION HISTORY:
        mgs, 26 Sep 1997: VERSION 1.00
        mgs, 17 Nov 1998: - added DEFAULT and NOABORT keywords
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/choice.pro)


CINDEX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:		
        CINDEX

 PURPOSE:	
        This is a program for viewing the current colors in the 
	 colortable with their index numbers overlayed on each color.
        
	 CINDEX Draws a NROW x NCOL set of small rectangles, each of 
        which displays one of the colors in the color table.  It also
        writes the color index number on top of each rectangle.

 CATEGORY:	
        Color

 CALLING SEQUENCE:	
        CINDEX

 INPUTS:	
        None
	
 KEYWORD PARAMETERS:
        NCOL -> Specify the number of columns in the plot. 
             Default is 16.

        NROW -> Specify the number of columns in the plot.  If not 
             specified, then CINDEX will compute the minimum number
             of rows that are needed to display all of the colors,
             given the setting of NCOL.

        TITLE -> Specify the title for the plot window.

        /ALL -> Set this switch to plot all 256 colors on a 16x16 grid.
             Colors that are not defined will be rendered as white.

 OUTPUTS:	
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1)
        MYCT, /WhGrYlRd
        CINDEX
 
             ; Displays the colors of the MYCT color table
             ; WHITE-GREEN-YELLOW-RED (spectral).  The drawing
             ; colors and all 20 colors of this table are shown.

        (2)
        MYCT, /WhGrYlRd
        CINDEX, /ALL
 
             ; Same as above, but plots the colors on a 
             ; 16 x 16 grid.

 MODIFICATION HISTORY:  
        INITIAL REVISION: David Fanning, RSI, May 1995
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Added NCOL, ROW, TITLE, ALL keywords to
                            allow the user to specify these settings
                            instead of having these be hardwired.
        bmy, 21 Apr 2008: GAMAP VERSION 2.12
                          - Now use NAME and INDEX tags from !MYCT 
                            to define the default title string.

(See /n/home09/ryantosca/IDL/gamap2/color/cindex.pro)


CLOSE_DEVICE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CLOSE_DEVICE

 PURPOSE:
        CLOSE_DEVICE closes the PostScript device and spawns
        a print job to the printer specified by the user or
        it can be used to close a graphics window.

 CATEGORY:
        Graphics

 CALLING SEQUENCE:
        CLOSE_DEVICE [,OLD_DEVICE] [, Keywords ]

 INPUTS:
        OLD_DEVICE -> Name of device that shall become the active
             plotting device. If omitted, "X", "WIN" or "MAC" will
             be set depending on !VERSION.OS_FAMILY.  Hence, 
             specification of OLD_DEVICE is only rarely needed.
             This parameter works together with the OLD_DEVICE 
             parameter of OPEN_DEVICE which returns the device name 
             before the postscript device (or a graphics device) is 
             opened.  The OLD_DEVICE parameter can be misused to set 
             the output device to anything! Therefore, it's probably 
             safest to not use it and stick with the operating system 
             dependent default.

 KEYWORD PARAMETERS:
        LABEL -> a string that contains an annotation for a postscript
             plot (usually a user name and/or filename). The current 
             data and time will be appended if TIMESTAMP is set. 
             NOTE: TIMESTAMP will produce an annotation even if LABEL
             is not provided. The annotation is only added to 
             postscript plots and only if the ps file is actually 
             open.

        /TIMESTAMP  -> add date and time to the LABEL on the plot.
             If no LABEL is provided, the username and filename 
             (value of FILENAME will be used or the filename of the 
             current postscript file will be added). The timestamp 
             is only added to postscript plots and only on the last 
             page.

        PRINTER -> Name of the printer queue to send output to.
             Default is 'none', i.e. the postscript file will only 
             be closed and can then be manually printed e.g. using 
             the Unix lpr command.  Direct printing only works in 
             Unix environments.

        WINDOW -> window number to be closed (or -1 if current)

        _EXTRA=e -> any additional keywords to CLOSE_DEVICE will 
             be passed on to STRDATE which is used to format the 
             date and time string.  Possible values are: /SHORT, 
             /SORTABLE, /EUROPEAN.

        LCOLOR -> the color value for the LABEL (default 1).

        LPOSITION -> the position of the LABEL in normalized 
             coordinates (a two-element vector with default 
             [0.98,0.007]).

        LSIZE -> the charcter size of the LABEL (default 0.7).

        LALIGN -> the alignment of the LABEL (default 1).

        FILENAME -> name of the PostScript file.  This is actaully
             obsolete now because the PostScript filename is 
             determined at the time the file is opened (e.g. in
             routine OPEN_DEVICE)

 OUTPUTS:
        If postscript device is active, a *.ps file will be closed 
        and optionally sent to the printer.

 SUBROUTINES:
        External Subroutines Required:
        ================================
        STRDATE (function)

 REQUIREMENTS:
        Requires routines in the 

 NOTES: 
        The WINDOW keyword is only evaluated if the current device 
        supports windows [!D.FLAGS AND 256) GT 0]. If you only want 
        to close a postscript file and don't fuss around with your 
        screen windows then simply don't set this keyword.

 EXAMPLES:
        (1)
        CLOSE_DEVICE

            ; Closes a postscript file (if opened) and resets the 
            ; current plotting device to 'X', 'WIN', or 'MAC' 
            ; depending on the OS_FAMILY.

        (2) 
        CLOSE_DEVICE, PRINTER='hplj4', LABEL='mgs', /TIMESTAMP

            ; If current device name is PS then the postscript 
            ; file will be closed, a user, date and time label will 
            ; be added and the file will be spooled to the printer 
            ; queue 'hplj4'. NOTE: Printing of the file fails if you 
            ; specified FILENAME as a relative path in the OPEN_DEVICE 
            ; command and you changed your working directory while
            ; the device was opened.
  
        (3)
        CLOSE_DEVICE, WIN=-1

            ; If current device name is PS then the postscript file 
            ; will be closed. If the current device is a screen 
            ; device (that supports windows), then the active window
            ;  will be deleted.
 
 MODIFICATION HISTORY:
        bmy, 18 Aug 1997: VERSION 1.00
        bmy, 19 Aug 1997: VERSION 1.01
        mgs, 20 Aug 1997: VERSION 1.02
        mgs, 08 Apr 1998: VERSION 2.00 
                          - automatic filename detection
                          - default device depending on OS_FAMILY
        mgs, 21 May 1998: 
                          - added L.. keywords to control label 
                            and timestamp output
        mgs, 18 Nov 1998:
                          - added output of username as default in timestamp
        bmy, 28 Jul 2000: TOOLS VERSION 1.46
                          - cleaned up a few things
        bmy, 24 May 2007: TOOLS VERSION 2.06
                          - Updated comments
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/graphics/close_device.pro)


CMSET_OP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   CMSET_OP

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov

 PURPOSE:
   Performs an AND, OR, or XOR operation between two sets

 CATEGORY:
   Math & Units

 CALLING SEQUENCE:
   SET      = CMSET_OP(A, OP, B)

 DESCRIPTION:

   SET_OP performs three common operations between two sets.  The
   three supported functions of OP are:

       OP      Meaning
       'AND' - to find the intersection of A and B;
       'OR'  - to find the union of A and B;
       'XOR' - to find the those elements who are members of A or B 
               but not both;

   Sets as defined here are one dimensional arrays composed of
   numeric or string types.  Comparisons of equality between elements
   are done using the IDL EQ operator.

   The complements of either set can be taken as well, by using the
   NOT1 and NOT2 keywords.  For example, it may be desireable to find
   the elements in A but not B, or B but not A (they are different!).
   The following IDL expressions achieve each of those effects:

      SET = CMSET_OP(A, 'AND', /NOT2, B)   ; A but not B
      SET = CMSET_OP(/NOT1, A, 'AND', B)   ; B but not A

   Note the distinction between NOT1 and NOT2.  NOT1 refers to the
   first set (A) and NOT2 refers to the second (B).  Their ordered
   placement in the calling sequence is entirely optional, but the
   above ordering makes the logical meaning explicit.

   NOT1 and NOT2 can only be set for the 'AND' operator, and never
   simultaneously.  This is because the results of an operation with
   'OR' or 'XOR' and any combination of NOTs -- or with 'AND' and
   both NOTs -- formally cannot produce a defined result.

   The implementation depends on the type of operands.  For integer
   types, a fast technique using HISTOGRAM is used.  However, this
   algorithm becomes inefficient when the dynamic range in the data
   is large.  For those cases, and for other data types, a technique
   based on SORT() is used.  Thus the compute time should scale
   roughly as (A+B)*ALOG(A+B) or better, rather than (A*B) for the
   brute force approach.  For large arrays this is a significant
   benefit.

 INPUTS:

   A, B - the two sets to be operated on.  A one dimensional array of
          either numeric or string type.  A and B must be of the same
          type.  Empty sets are permitted, and are either represented
          as an undefined variable, or by setting EMPTY1 or EMPTY2.

   OP - a string, the operation to be performed.  Must be one of
        'AND', 'OR' or 'XOR' (lower or mixed case is permitted).
        Other operations will cause an error message to be produced.

 KEYWORDS

   NOT1, NOT2 - if set and OP is 'AND', then the complement of A (for
                NOT1) or B (for NOT2) will be used in the operation.
                NOT1 and NOT2 cannot be set simultaneously.

   EMPTY1, EMPTY2 - if set, then A (for EMPTY1) or B (for EMPTY2) are
                    assumed to be the empty set.  The actual values
                    passed as A or B are then ignored.

   INDEX - if set, then return a list of indices instead of the array
           values themselves.  The "slower" set operations are always
           performed in this case.

           The indices refer to the *combined* array [A,B].  To
           clarify, in the following call: I = CMSET_OP(..., /INDEX);
           returned values from 0 to NA-1 refer to A[I], and values
           from NA to NA+NB-1 refer to B[I-NA].

   COUNT - upon return, the number of elements in the result set.
           This is only important when the result set is the empty
           set, in which case COUNT is set to zero.

 RETURNS

   The resulting set as a one-dimensional array.  The set may be
   represented by either an array of data values (default), or an
   array of indices (if INDEX is set).  Duplicate elements, if any,
   are removed, and element order may not be preserved.

   The empty set is represented as a return value of -1L, and COUNT
   is set to zero.  Note that the only way to recognize the empty set
   is to examine COUNT.

 SEE ALSO:

   SET_UTILS.PRO by RSI

 MODIFICATION HISTORY:
   Written, CM, 23 Feb 2000
   Added empty set capability, CM, 25 Feb 2000
   Documentation clarification, CM 02 Mar 2000
   Incompatible but more consistent reworking of EMPTY keywords, CM,
     04 Mar 2000
   Minor documentation clarifications, CM, 26 Mar 2000
   Corrected bug in empty_arg special case, CM 06 Apr 2000
   Add INDEX keyword, CM 31 Jul 2000
   Clarify INDEX keyword documentation, CM 06 Sep 2000
   Made INDEX keyword always force SLOW_SET_OP, CM 06 Sep 2000
   Added CMSET_OP_UNIQ, and ability to select FIRST_UNIQUE or
     LAST_UNIQUE values, CM, 18 Sep 2000
   Removed FIRST_UNIQUE and LAST_UNIQUE, and streamlined
     CMSET_OP_UNIQ until problems with SORT can be understood, CM, 20
     Sep 2000 (thanks to Ben Tupper)
   Still trying to get documentation of INDEX and NOT right, CM, 28
     Sep 2000 (no code changes)
   Correct bug for AND case, when input sets A and B each only have
     one unique value, and the values are equal.  CM, 04 Mar 2004
     (thanks to James B. jbattat at cfa dot harvard dot edu)
   Add support for the cases where the input data types are mixed,
      but still compatible; also, attempt to return the same data
      type that was passed in; CM, 05 Feb 2005
   Fix bug in type checking (thanks to "marit"), CM, 10 Dec 2005
   Work around a stupidity in the built-in IDL HISTOGRAM routine,
      which tries to "help" you by restricting the MIN/MAX to the
      range of the input variable (thanks to Will Maddox), CM, 16 Jan 2006

  $Id: cmset_op.pro,v 1.4 2007/11/20 21:55:32 bmy Exp $

(See /n/home09/ryantosca/IDL/gamap2/math_units/cmset_op.pro)


CODE_TREE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CODE_TREE

 PURPOSE:
        This routine produces a tree structure for Fortran programs.
        It will scan a directory for FORTRAN files and gather all
        SUBROUTINE names and CALL statements. FUNCTIONS are not
        parsed.

 CATEGORY:
        General

 CALLING SEQUENCE:
        CODE_TREE [, DEFAULT_PATH, DEFAULT_MAIN ] [ , /FILENAMES ]

 INPUTS:
        DEFAULT_PATH -> the default search path to look for FORTRAN files

        DEFAULT_MAIN -> the default name of the main program file. Note
             that code_tree will not work properly if the main file
             contains subroutine definitions.

 KEYWORD PARAMETERS:
        /FILENAMES -> display the filename where each routine can be
             found together with the routine name.

 OUTPUTS:
        A calling tree is generated on the screen or dumped into a file.

 SUBROUTINES:
        Several

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        CODE_TREE

 MODIFICATION HISTORY:
       99/5/18 Philip Cameron-Smith, Harvard 
         Initial code.
       99/5/21 Philip Cameron-Smith, Harvard 
         Have included some of my utilities to allow easy distribution.
         Added '1' to names to ensure no future conflicts.
       99/5/24 Philip Cameron-Smith, Harvard 
         Now removes tabs and strings.
         Various other improvements.
       99/5/25 Philip Cameron-Smith, Harvard 
         Reversed order of path and filename arguments
         Converted a "print" to a "printf,lun" to stop lines running
         on when printing to a file.
         Improved check for ENTRY before SUBROUTINE.
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/code_tree.pro)


COLORBAR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        COLORBAR

 PURPOSE:
        Draw a colorbar (legend) with labels

 CATEGORY:
        Color

 CALLING SEQUENCE:
        COLORBAR [ , Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        ANNOTATION -> Array with string label values.  If specified,
             ANNOTATION will override the default label values, and 
             will also override the LABEL keyword.

        BOTOUTOFRANGE, TOPOUTOFRANGE -> a color index value for data
             that falls below (or above) the normal plot range. If 
             given, an extra box will be drawn to the left (or right) 
             of the colorbar, and the colorbar will shrink in size.  
             A default label '<' (or '>') will be placed below.  
             NOTE: these options are only available for horizontal 
             colorbars.

        BOR_LABEL, TOR_LABEL -> label values for BOTOUTOFRANGE and 
             TOPOUTOFRANGE that replace the defaults.

        BOTTOM -> First color index to use.  Default is !MYCT.BOTTOM.
             NOTE: In practice you shouldn't have to specify BOTTOM,
             as the value from !MYCT.BOTTOM will reflect the settings
             of the current colortable.

        C_COLORS -> Array of color indices for "discrete" color bars
             e.g. in filled contour plots. You must also use the 
             C_LEVELS keyword, otherwise there will most likely be
             a mismatch between your plot colors and your colorbar 
             colors. COLORBAR normally limits the number of labels
             it prints to 10. Use the SKIP keyword to force a different
             behaviour. If C_COLORS is not undefined it overrides the
             settings from NCOLORS, and BOTTOM.

        C_LEVELS -> Array with label values for "discrete" colorbars.
             Use the LABEL or ANNOTATION keyword for continuous
             colorbars.  C_LEVELS must have the same number of elements 
             as C_COLORS and assigns one label to each color change 
             (LABEL distributes the labels evenly). Use the SKIP
             keyword to skip labels.  As default, COLORBAR limits the 
             number of labels printed to 10.

        AUTOSCALELEVELS -> Set this switch to automatically scale
             labels (specified by C_LEVELS, LABEL, MAX, or MIN) 
             by powers of 10. This reduces the length of each tick label
             and helps prevent overlapping numbers in the colorbar.  

        CHARSIZE -> Specifies the character size for colorbar labels.
             Default is !P.CHARSIZE.

        COLOR -> The drawing color for boxes and labels.  
             Default is !MYCT.BLACK.
 
        DIVISIONS -> Number of labels to put on the colorbar.
             Note that this keyword is overwritten by LABEL.
             The labels will be equally spaced and the /LOG option
             will be honored.

        FLAGVAL -> If set, will place a tick mark with label at a
             user-defined value.  You can use this to denote where
             0 or 1 falls w/in a color range, for example.

        FORMAT -> Output format of the labels.  Default is determined
             according to the range given in min and max.  Label 
             strings will be trimmed, so you can safely specify 
             '(f14.2)' for example.

        LABEL -> Array containing label values (must be numeric).
             Normally, it is easier to generate labels with the 
             DIVISIONS options, but this allows tighter control 
             (e.g. 1,2,5,10,20 labels on logarithmic scales).
             Default (if no DIVISIONS are given): MIN and MAX.
             NOTE: ANNOTATION will 

        /LOG -> Set this switch to invoke logarithmic spacing of 
             labels.  The colors are *always* linearily distributed.

        MAX -> Maximum value to plot.  Default is NCOLORS.

        MIN -> Minimum value to plot.  Default is BOTTOM.

        /NOGAP -> if 0 then there is a gap b/w the triangle or
             rectangle OutOfRange boxes and the bar, else no
             gap. Defalut is to have a gap. If /TRIANGLE and no
             OutOfRange boxes are set then default is No Gap.

        NCOLORS -> Number of colors to use in the colorbar.  Default 
             is !MYCT.NCOLORS.  NOTE: In practice you shouldn't have 
             to specify NCOLORS, as the value from !MYCT.NCOLORS will 
             reflect the settings of the current colortable.

        ORIENTATION -> Specifies the orientation of the colorbar
             labels.  This keyword has the same behavior as the 
             ORIENTATION option in XYOUTS (i.e. ORIENTATION=0 means
             normal "left-right" text, ORIENTATION=-90 means "top-
             bottom" text, etc.)

        POSITION -> A position value or 4-element vector. If POSITION
             contains only one element, it will be centered at the
             bottom or right side of the page and extend over 60% of
             the total plotting area.

        SCIENTIFIC -> If set, will call STRSCI to put the colorbar
             labels in scientific notation format (e.g. in the form
             A x 10^B).  STRSCI will use the format string specified 
             in the FORMAT keyword.

        SKIP -> Print only every Nth discrete label.  The default is 
             computed such that COLORBAR will print no more than 10 
             labels.

        TITLE -> A title string for the colorbar.  (This works similarly 
             to the XTITLE or YTITLE options to the PLOT command.)

        TICKLEN -> A number between 0 and 1 which defines the length
             of the tick marks as a fraction of the size of the plot
             box.  Default is 0.25.

        /TRIANGLE -> to plot triangles at the end of the color bar. If 
             OutOfRange boxes are requested, then the triangles
             replace the rectangle.

        UNIT -> A unit string that will be added to the right of the
             labels.  If /VERTICAL is set, then the unit string will
             be placed at the top of the labels.

        UPOS -> Specifies the position (relative to the size of the 
             colorbar) where the unit string will be placed.  The
             default is 1.15.  To print the unit string closer to the
             end of the colorbar, reduce this value until the desired
             appearance is obtained.

        /VERTICAL -> Set this keyword to produce a vertical colorbar
             (default is horizontal).  Note that out-of-range boxes are
             only implemented for horizontal color bars.  

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ====================================
        STRSCI (function)  TRIANGLE

 REQUIREMENTS:
        Assumes that we are using a MYCT-defined colortable.

 NOTES:
        (1) This routine was designed after David Fanning's colorbar
            routine and adapted to our needs.  Some of the postscript
            handling of DF was removed, positioning is a little easier 
            but maybe a little less flexible; out-of-range boxes have 
            been added.

        (2) The !MYCT system variable contains the properties of the
            current MYCT-defined colortable.  You normally should not
            have to explicity pass BOTTOM or NCOLORS, as these
            keywords will be initialized from the values from !MYCT.

 EXAMPLES:
        COLORBAR, MIN=MIN( DATA, MAX=M ), MAX=M

            ; Draw a horizontal colorbar with all available colors
            ; Default placement is at the bottom of the page.
            ; will be placed at the bottom of the page

        COLORBAR, MIN=0.1, MAX=10, /LOG, UNIT='[ppt]', $
            LABELS=[0.1, 0.5, 1, 5, 10 ], 
            POSITION=[0.3. 0.3, 0.3, 0.3]
 
            ; Draw another colorbar above the first one, 
            ; use logarithmic scale

        COLORBAR, MIN=0.1, MAX=10, /LOG, UNIT='[ppt]', $
            LABELS=[0.1, 0.5, 1, 5, 10 ], 
            POSITION=[0.1, 0.1, 0.1, 0.1], /VERTICAL

            ; Draw vertical colorbar closer to the left edge of 
            ; the plot.  Otherwise options are the same as in the 
            ; previous example.

        COLORBAR, MIN=0, MAX=100, $
            DIVISIONS=5, TOPOUTOFRANGE=!MYCT.WHITE

            ; Draw horizontal colorbar with out-of-range box
            ; (colored white) to the right of the max value.

        COLORBAR, MIN=0, MAX=100, $
            DIVISIONS=5, TOPOUTOFRANGE=!MYCT.WHITE, $
            ANNOTATION=[ '0', '2,500', '5,000', '7,500', '10,000' ]

            ; Same example as above, but this time we use the
            ; ANNOTATION keyword to override the default labels
            ; with string labels.

 MODIFICATION HISTORY:
        mgs, 02 Jun 1998: VERSION 1.00
        mgs, 14 Nov 1998: - changed default format to f14.2 from f6.2
        mgs, 19 Nov 1998: - added cbdefaultformat function to better handle
                            default labeling format.
        mgs, 28 Nov 1998: - default labelling format now exponential for
                            values gt 1.e6
        mgs, 19 May 1999: - unit string placed a little further right
                            in horizontal colorbars.
        mgs, 27 May 1999: - added functionality for discrete colorbars
                            (C_COLORS, C_LEVELS, and SKIP keywords)
        bmy, 02 Jun 1999: - added /SCIENTIFIC keyword
                          - updated comments
        mgs, 03 Jun 1999: - fixed discrete labeling x positions
        bmy, 27 Jul 2000: TOOLS VERSION 1.46
                          - added ORIENTATION keyword so that the user
                            can control the vertical colorbar labels
        bmy, 27 Sep 2002: TOOLS VERSION 1.51
                          - Now use 2 decimal places for exponential
                            default format instead of 3
        bmy, 18 Oct 2002: TOOLS VERSION 1.52
                          - now use _EXTRA=e to pass commands to
                            XYOUTS (i.e. to set label thickness)
        bmy, 26 Nov 2002: - Added ANNOTATION keyword to print
                            string labels instead of numeric labels
        bmy, 26 Nov 2003: TOOLS VERSION 2.01
                          - make sure MINV, MAXV, and DIVISIONS
                            are scalars so as not to generate the
                            color bar labels incorrectly.
        bmy, 21 May 2004: TOOLS VERSION 2.02
                          - If SKIP is passed, make sure that it is
                            never less than 1.
                          - added TICKLEN and FLAGVAL keywords
                          - now add ticks where labels are printed
                          - Cosmetic changes, updated comments
        bmy, 07 Mar 2007: TOOLS VERSION 2.06
                          - Updated documentation and examples
  dbm & bmy, 13 Jun 2007: - Now define default colors for contour plots
                            if C_LEVELS is passed but C_COLORS isn't
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
  cdh & phs, 19 Nov 2007: GAMAP VERSION 2.11
                          - Added out of range boxes options for
                            vertical bar
                          - Added TRIANGLE and NoGAP keyword
                          - Set default for case of /TRIANGLE, but no
                            OutOfRange boxes.
        phs, 21 Apr 2008: GAMAP VERSION 2.12
                          - Bug fix default MAXV should be NCOLORS+BOTTOM
        cdh, 16 Apr 2013: Fill MinV and MaxV values from C_Levels

(See /n/home09/ryantosca/IDL/gamap2/color/colorbar.pro)


COLORBAR_NDIV

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        COLORBAR_NDIV

 PURPOSE:
        Returns the maximum number of colorbar divisions possible
        (up to a user-defined limit) such that tickmarks are placed 
        in between colors.

 CATEGORY:
        Color

 CALLING SEQUENCE:
        Result = COLORBAR_NDIV( NCOLORS [, Keywords ] )

 INPUTS:
        NCOLORS -> (OPTIONAL) Specifies the number of colors 
             in the color table.  Default is !MYCT.NCOLORS.

 KEYWORD PARAMETERS:
        MAXDIV -> Specifies the maximum number of divisions 
             for the colorbar.  Default is 6.

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        DIV = COLORBAR_NDIV( 20, MAXDIV=8 )
        TVMAP, ..., DIVISONS=DIV, ...
             
             ; Computes the number of color bar divisions for
             ; a colortable with 20 colors.  DIV will not exceed
             ; the value of MAXDIV (in this case =8).  The value 
             ; of DIV is then passed to the TVMAP routine (which
             ; in turn passes it to the COLORBAR routine).

 MODIFICATION HISTORY:
        phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/color/colorbar_ndiv.pro)


COMPARE_FLIGHT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        COMPARE_FLIGHT

 PURPOSE:
        Compare observations from aircraft campaigns to 
        high time-resolution CTM output (bpch files).
        This routine reads aircraft data in binary (bdt) format
        and produces an unlabeld plot and returns all the data
        you might ask for. If an aircraft mission extends beyond
        midnight GMT, the program will ask for a second model file
        which should be from the following day.

 CATEGORY:
        GAMAP Utilities, GAMAP Plotting

 CALLING SEQUENCE:
        COMPARE_FLIGHT, keywords

 INPUTS:
        None

 KEYWORD PARAMETERS:
      DATAFILE -> Name of the aircraft data file or file mask

      MODELFILE -> Name of the (first) model output file or file mask

      TRACER -> tracer number in model output (default=71)

      PSURF -> surface pressure for model grid (default=1013, because most
          aircraft data was sampled over oceans)

      FLIGHTDATA -> returns the observational data array as read
          with gte_readbin. Can also be used to pass flight data if you
          set the USE_DATA flag.

      FLIGHTVARS -> returns the variable names of the observational data.
          Must accompany FLIGHTDATA if you use USE_DATA.

      SPECIES -> the name of the observed species to plot (default CH3I).

      MODELDATA -> returns a time series of model data along the flight 
          track and a couple of min/max values:
             MODELDATA[*,0] = model value in corresponding grid box
                      [*,1] = min of neighbouring grid boxes at same level
                      [*,2] = max ...
                      [*,3] = min of neighbouring grid boxes at level below
                      [*,4] = max ...
                      [*,5] = min of neighbouring grid boxes at level above
                      [*,6] = max ...
          Note that the min/max arrays may contain values from the same
          grid boxes at the edges (i.e. there is no level below the first
          one, hence 3,4 will be identical to 1,2).

      TIME -> returns the time vector of the observations and modeldata

      /USE_DATA -> set this flag if you provide the aircraft data in the
          FLIGHTDATA array and the variable names in FLIGHTVARS. The data
          must contain variables named 'LON', 'LAT', 'ALTP' and SPECIES
          (for SPECIES see above). You must also provide a TIME vector
          which specifies UTC seconds.

 OUTPUTS:
      The extracted data is returned in MODELDATA, several other keywords
      return things read or computed in the process.

 SUBROUTINES:
      EXTRACT__FLIGHT : actual workhorse that does the extraction

 REQUIREMENTS:
      chkstru, ctm_get_data (GAMAP), gte_readbin (GTE)

 NOTES:
      Some hardwiring of default directories.

 EXAMPLE:
      simply  COMPARE_FLIGHT,tracer=1  if all you want is a plot
 
      CONVERT_FLIGHT,tracer=1,modeldata=md,time=time
      plot,time,md[*,0],color=1

 MODIFICATION HISTORY:
      mgs, 21 Apr 1999: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/compare_flight.pro)


COMPRESS_DIV_CT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        COMPRESS_DIV_CT

 PURPOSE:
        Compresses a diverging color table with even number of colors 
        into NCOLORS.  If the /MIDCOLORPRESENT keyword is specified,
        COMPRESS_DIV_CT will also place white or yellow spaces in
        the middle of the color table.

 CATEGORY:
	 Color


 CALLING SEQUENCE:
        COMPRESS_DIV_CT, R, G, B [, Keywords ]

 INPUTS:
        R, G, B -> The vectors containing the red, blue, and 
             green color values that define the color table.

 KEYWORD PARAMETERS:
        NCOLORS -> Requested number of colors to be returned.
             If NCOLORS is omitted, then COMPRESS_DIV_CT will
             return without doing anything.

        /MIDCOLORPRESENT -> Set this switch to add 1 or 2 extra
             white or yellow color spaces in the color table.  
            
        /WHITE -> If /MIDCOLORPRESENT is set, this switch will
             cause 1 (if NCOLORS is odd) or 2 (if NCOLORS is even)
             extra white color spaces to be placed
             at the center of the color table.  
            
        /YELLOW -> If /MIDCOLORPRESENT is set, this switch will
             cause 1 (if NCOLORS is odd) or 2 (if NCOLORS is even)
             extra white color spaces to be placed
             at the center of the color table.  ;

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        Designed for use with MYCT.  You shouldn't normally 
        have to call COMPRESS_DIV_CT directly.

 NOTES:
        None

 EXAMPLE:
        LOADCT, 63, FILE=FILE_WHICH( 'gamap_colors.tbl' )
        TVLCT, R, G, B, /Get

             ; Load the ColorBrewer "RdBu" table
             ; and return the color vectors

        COMPRESS_DIV_CT, R, G, B, $
                         NCOLORS=20, /MIDCOLORPRESENT, /WHITE

             ; Compress the color table down to 20 colors and 
             ; insert 2 white spaces at the middle of the table.

 MODIFICATION HISTORY:
        phs, 21 Apr 2008: GAMAP VERSION 2.12

(See /n/home09/ryantosca/IDL/gamap2/color/compress_div_ct.pro)


CONVERT_INDEX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CONVERT_INDEX

 PURPOSE:
        Converts a 1-D array index (such as is returned from 
        WHERE, UNIQ, etc) to the appropriate 1-D, 2-D, or 3-D
        array indices

 CATEGORY:
        General

 CALLING SEQUENCE:
        RESULT = CONVERT_INDEX( Index, Dim )

 INPUTS:
        INDEX -> The 1-D array index to be converted to 
             multi-dimensional indices.  INDEX is returned
             to the calling program unchanged.
 
        DIM -> A vector containing the dimensions of the array
             for which multi-dimensional indices are required.

 KEYWORD PARAMETERS:
        FORTRAN -> Interpret array indices as FORTRAN indices, i.e.
             starting from 1 instead of 0. This applies to INPUT 
             and OUTPUT indices!

 OUTPUTS:
        RESULT -> Returns either a vector index or a vector of 
             multi-dimensional array indices as the value of the 
             function. If INDEX is a 1-dimensional parameter, the 
             result will have n_elements(dim) dimensions. If INDEX 
             is a multidimensional parameter, the result will be 
             a scalar.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        Right now only works for 3-D arrays and smaller.  Will
        eventually do the general case...

 EXAMPLES:
        (1) 
        PRINT, CONVERT_INDEX( [1,1], [2,2] )
           3

        (2)
        PRINT, CONVERT_INDEX( [2,2], [2,2] )
           % CONVERT_INDEX: Index[0] greater than Dim[0]
           % CONVERT_INDEX: Index[1] greater than Dim[1]
           6

        (3)
        PRINT, CONVERT_INDEX( [2,2], [2,2], /FORTRAN )
           4       ; <<<-- shifted by 1 !

        (4)
        PRINT, CONVERT_INDEX( 72, [72,46,20] )
           0  1  0
 
        (5)
        PRINT, CONVERT_INDEX( 72, [72,46,20], /FORTRAN )
           72           1           1
 
 MODIFICATION HISTORY:
        bmy, 07 Oct 1998: VERSION 1.00
        mgs, 07 Oct 1998: VERSION 1.20
               - made result etc LONG arrays
               - allow sany dimensions now
               - added reverse operation if index is multidimensional
               - added FORTRAN keyword 
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/convert_index.pro)


CONVERT_KG_MOLCM2

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CONVERT_KG_MOLCM2 

 PURPOSE:
        Converts the units of a 2-D array from kg to molecules/cm2 
        (or kg/s to molecules/cm2/s).  

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        CONVERT_KG_MOLCM2, DATA, AREACM2, KGPERMOLE

 INPUTS:
        DATA -> 2-D array of data values in units of
             kg or kg s^-1.

        AREACM2 -> 2-D array containing the surface area of each
             gridbox in cm^2

        KGPERMOLE -> The molecular weight of the tracer or
             molecule, in units of kg mole^-1.

 OUTPUTS:
        DATA -> The converted array in molecules cm^-2 s^-1
             is returned in DATA. 

 KEYWORD PARAMETERS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        CTM_SURFACE_AREA must be called to compute the AREACM2 array.
        TRACER_KG_PER_MOLE (or a similar subroutine) must be called
        to compute the KGPERMOLE array.
             
 NOTES:
        None

 EXAMPLE:
        AreaCm2      = CTM_SURFACE_AREA( GridInfo, /cm2, /GEOS )
        KgPerMole    = TRACER_KG_PER_MOLE( /FULLCHEM )
        TracerNumber = 1  ; for NOx  
        CONVERT_KG_MOLCM2, Data, AreaCm2, KgPerMole(TracerNumber)

            ; Will convert the Data array for the GEOS-1 model (using
            ; the molecular weight for NOx) from kg/s to molecules/cm2/s.
             
 MODIFICATION HISTORY:
        bmy, 07 Apr 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/math_units/convert_kg_molcm2.pro)


CONVERT_LON

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CONVERT_LON

 PURPOSE:
        Convert longitudes from -180..180 to 0..360 
        or vice versa.

 CATEGORY:
        General

 CALLING SEQUENCE:
        CONVERT_LON, DATA, NAMES, [, KEywords ] 

 INPUTS:
        DATA -> A data array (lines,vars) or vector containing 
            longitude data. If DATA is a 2D array, the NAMES
            parameter must be given to identify the LONgitude variable.

        NAMES -> A string list of variable names. The longitude data
            must be labeled 'LON', unless specified with the LONNAME
            keyword. The NAMES parameter is not needed, if a data
            vector is passed.

 KEYWORD PARAMETERS:
        PACIFIC -> Convert longitudes from -180..180 to 0..360

        ATLANTIC -> Convert from 0..360 to -180..180

        LONNAME -> Name of the longitude variable if a name other
            than 'LON' is used.

 OUTPUTS:
        The longitude column in the data array will be changed.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1)
        LONDAT = [ -180.,-179.,-0.1,0.1,179.,180.,270.,359.]
        CONVERT_LON, LONDAT, /PACIFIC
        PRINT, LONDAT
           180.000  181.000  359.900  0.100000  
           179.000  180.000  270.000  359.000

             ; Convert longitudes to 0..360

        (2)
        CONVERT_LON,londat,/Atlantic
        PRINT, LONDAT
           180.000  -179.000  -0.100006  0.100000      
           179.000   180.000  -90.0000  -1.00000

             ; Convert back to -180..180

 MODIFICATION HISTORY:
        mgs, 25 Aug 1998: VERSION 1.00
        mgs, 19 May 1999: - now makes sure that longitude range does
                            not exceed -180..180 or 0..360
        mgs, 24 Jun 1999: - bug fix: choked at missing values 
        bmy, 24 May 2007: TOOLS VERSION 2.06
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments
        phs, 19 Nov 2007: GAMAP VERSION 2.11
                          - now accept scalar

(See /n/home09/ryantosca/IDL/gamap2/general/convert_lon.pro)


CONVERT_MOLCM2_KG

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CONVERT_MOLCM2_KG 

 PURPOSE:
        Converts the units of a 2-D or 3-D array from molecules/cm2 
        to kg (or, equivalently, from molecules/cm2/s to kg/s).  

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        CONVERT_MOLCM2_KG, DATA, AREACM2, KGPERMOLE

 INPUTS:
        DATA -> 2-D or 3-D array of data values in units of
             molecules cm^-2 or molecules cm^-2 s^-1.

        AREACM2 -> 2-D array containing the surface area of each
             gridbox in cm^2

        KGPERMOLE -> The molecular weight of the tracer or
             molecule, in units of kg/mole.
 
 OUTPUTS:
        DATA -> The converted array in kg/s is returned in DATA. 
             DATA is returned with the same dimensions as
             it had when it was passed to CONVERT_MOLCM2_KG.

 KEYWORD PARAMETERS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        CTM_SURFACE_AREA must be called to compute the AREACM2 array.
        TRACER_KG_PER_MOLE (or a similar subroutine) must be called
        to compute the KGPERMOLE array.
             
 NOTES:

 EXAMPLE:
        AreaCm2      = CTM_SURFACE_AREA( GridInfo, /cm2, /GEOS )
        KgPerMole    = TRACER_KG_PER_MOLE( /FULLCHEM )
        TracerNumber = 1   ; for NOx
        CONVERT_MOLCM2_KG, Data, AreaCm2, KgPerMole

            Will convert the Data array for the GEOS-1 model (using
            the molecular weight for NOx) from molecules/cm2/s to kg/s.
             

 MODIFICATION HISTORY:
        bmy, 07 Apr 1998: VERSION 1.00
        bmy, 09 Apr 1998: VERSION 1.01 
                          - DATA can now be a 2-D or 3-D array.
                          - KgPerMole can now be an array of the same
                            dimension as the 3rd dimension of Data.
        bmy, 07 Oct 1998: VERSION 1.02
                          - now uses MESSAGE statement
                          - also uses [] instead of () for array
                            indices
        bmy  23 Nov 1998: VERSION 2.00
                          - now uses double precision array NEWDATA
                            to avoid overflow/underflow errors
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/math_units/convert_molcm2_kg.pro)


CONVERT_O3PL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CONVERT_O3PL

 PURPOSE:
        Converts single-tracer Ox rate files from their native
        binary format to binary punch format 

 CATEGORY:
        File & I/O, BPCH Format

 CALLING SEQUENCE:
        CONVERT_O3PL [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INMODELNAME -> A string containing the name of the model
             grid on which the input data resides.  Default is GEOS_STRAT.

        INRESOLUTION -> Specifies the resolution of the model grid
             on which the input data resides.  RESOLUTION can be 
             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 is 2.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        CTM_TYPE          (function)  
        CTM_GRID          (function)
        CTM_MAKE_DATAINFO (function)

 REQUIREMENTS:
        None

 NOTES:
        Input file names are hardwired for now.

 EXAMPLE:
        CONVERT_O3PL, INMODELNAME   ='GEOS1',                $
                      INRESOLUTION  = 4,                     $

             ; Regrids P(O3) and L(O3) data from 
             ; GEOS-1 4 x 5 grid to GISS-II-PRIME 4 x 5 grid.

 MODIFICATION HISTORY:
        bmy, 16 Jul 2002: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 02 Apr 2008: GAMAP VERSION 2.12
                          - Now read input file as big-endian

(See /n/home09/ryantosca/IDL/gamap2/file_io/convert_o3pl.pro)


CONVERT_UNIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CONVERT_UNIT

 PURPOSE:
        Convert data to a different unit. You can either 
        replace a unit by the corresponding standard SI unit or 
        replace a specific unit with another one.

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        CONVERT_UNIT,DATA,UNIT,TOPARAM [,keywords]

 INPUTS:
        DATA -> A data vector, array, or a single value that shall
            be converted to a new unit. 

        UNIT -> A string variable containing the (current) unit of 
            DATA. This will be replaced by the new unit afterwards.
            If omitted, you must give the FROM_UNIT keyword to indicate
            the current unit of DATA.

        TOPARAM -> The unit to convert DATA to. This is equivalent to 
            the keyword TO_UNIT and overwrites it.

 KEYWORD PARAMETERS:
        FROM_UNIT -> An individual unit to search and replace. If not
            given, any unit will be converted to TO_UNIT, as long as
            the current unit belongs to the same category. 

        TO_UNIT -> An individual unit to convert to. If not given, all
            unit that are converted (see FROM_UNIT) will be replaced
            by the standard SI unit of their category.

        For the individual unit and categories see FIND_UNIT 

        RESULT -> returns 1 if conversion was successful, 0 otherwise
            This keyword is mostly for consistency witholder routines.
            It is more convenient to test !ERROR_STATE.CODE for being
            0.

        MINVAL -> minimum valid data value. Only data above this 
            value will be converted (default: -1.E30)

        QUIET -> In case of an error, an error message is displayed,
            and the !ERROR_STATUS system variable is set to reflect the
            error condition (program execution continues). Set the
            QUIET keyword to suppress the error message.

 OUTPUTS:
        DATA will be converted and unit will contain new names.

 SUBROUTINES:
        Uses FIND_UNIT

 REQUIREMENTS:
        None

 NOTES:
        CONVERT_UNIT wil return the value and unit unchanged if
        the unit was not found in the standard list (see FIND_UNIT)
        or the category of the target unit does not match the
        category of the source unit. In these cases, !ERROR_STATE.CODE
        will be set to signal an error condition.

 EXAMPLE:
        ; create some data
        data = findgen(100)
        unit = 'cm'

        ; convert all data to SI unit of same category (m)
        convert_unit,data,unit

        ; test success
        if (!ERROR_STATE.CODE ne 0) then stop

        ; convert temperature in Fahrenheit to 'deg C'
        ; (multiple calls to capture all different spellings)
        ; Data will only be changed if unit is indeed Fahrenheit
        convert_unit,data,unit,from='F',to='deg C'
        convert_unit,data,unit,from='degF',to='deg C'
        convert_unit,data,unit,from='deg F',to='deg C'

        ; (easier way) convert any temperature to 'C'
        ; This will also convert 'K' !
        ; Don't display error message
        convert_unit,data,unit,to='C',/QUIET

        ; convert 'mph' data to SI ('m/s')
        convert_unit,data,unit,from='mph'

        ; explicitely convert 'cm' to 'm'
        convert_unit,data,'cm','m'
        ; equivalent to
        convert_unit,data,from='cm',to='m'

 MODIFICATION HISTORY:
        mgs, 26 Aug 1998: VERSION 1.00
        mgs, 27 Aug 1998: 
            - added RESULT and QUIET keywords
            - improved error handling
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/math_units/convert_unit.pro)


CREATE3DFSTRU

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CREATE3DFSTRU

 PURPOSE:
        Creates an empty GAMAP fileinfo structure or an array
        of such structures. These are used to hold information
        about CTM data files.

 CATEGORY:
        GAMAP Internals, Structures

 CALLING SEQUENCE:
        FILEINFO = CREATE3DHSTRU( [Elements] )

 INPUTS:
        ELEMENTS -> Number of individual structures to
             be contained in the array of structures. Default
             is 1, i.e. return a single structure.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        A fileinfo structure or an array of fileinfo structures.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        See comments in code below for structure field descriptions.

 EXAMPLES:
        FILEINFO = CREATE3DFSTRU()
            ; returns a single structure which will hold
            ; info about CTM punch file data.

        FILEINFO = CREATE3DFSTRU( 20 )
            ; returns an 20 element array of structures 
            ; which will hold info about 20 records from a 
            ; CTM data file

 MODIFICATION HISTORY:
        mgs, 14 Aug 1998: VERSION 1.00
        bmy, 18 May 2007: GAMAP VERSION 2.06
                          - added standard doc header
                          - updated comments, cosmetic changes
 MODIFICATION HISTORY:
        bmy, 19 Feb 1999: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/create3dfstru.pro)


CREATE3DHSTRU

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CREATE3DHSTRU

 PURPOSE:
        Creates an empty GAMAP datainfo structure or an array
        of such structures. These are used to hold information
        about individual data blocks from CTM data files.

 CATEGORY:
        GAMAP Internals, Structures

 CALLING SEQUENCE:
        DATAINFO = CREATE3DHSTRU( [Elements] )

 INPUTS:
        ELEMENTS -> Number of individual structures to be contained 
             in the array of structures. Default is 1, (i.e. return
             a single structure).

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        A datainfo structure or an array of datainfo structures.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        See comments in code below for structure field descriptions.

 EXAMPLES:
        DATAINFO = CREATE3DHSTRU()
            ; returns a single structure which will hold
            ; info about CTM punch file data.

        DATAINFO = CREATE3DHSTRU( 20 )
            ; returns an 20 element array of structures 
            ; which will hold info about 20 records from a 
            ; CTM data file

 MODIFICATION HISTORY:
        mgs, 14 Aug 1998: VERSION 1.00
        mgs, 10 Nov 1998: - changed default filepos to -1L and scale to 1
        bmy, 08 Feb 1999: VERSION 1.10
                          - changed TAU0, TAU1 from longword to double
                          - added OFFSET field for I0, J0, L0
        bmy, 17 Feb 1999: VERSION 1.20
                          - changed OFFSET field to FIRST since we
                            are storing the I, J, L indices of the 
                            first 
        mgs, 16 Mar 1999: - cosmetic changes
        bmy, 03 Jan 2000: VERSION 1.44
                          - updated comments
        bmy, 26 Apr 2000: VERSION 1.45
                          - TRACER now carries a longword variable
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        phs, 02 Dec 2008: GAMAP VERSION 2.13
                          - DIM tag is 32-bit integer (LONG) now
        bmy, 23 Feb 2012: GAMAP VERSION 2.16
                          - Now make FILEPOS a LONG64 variable, in
                            order to read files larger than 2.4 GB
                          - Now make FIRST an array of LONG variables

(See /n/home09/ryantosca/IDL/gamap2/internals/create3dhstru.pro)


CREATE_NESTED

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CREATE_NESTED

 PURPOSE:
        Reads data from a file and trims it down horizontally to a 
        "nested" CTM grid size.  Vertical resolution is not affected.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        CREATE_NESTED [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INFILENAME -> Name of the input file containing data to be 
             trimmed down to "nested" model grid resolution.  If 
             omitted, a dialog box will prompt the user to supply
             a filename.

        OUTFILENAME -> Name of the file that will contain trimmed
             data on the "nested" model grid.  OUTFILENAME will be
             in binary punch resolution.  If omitted, a dialog box 
             will prompt the user to supply a filename.

        XRANGE -> A 2-element vector containing the minimum and
             maximum box center longitudes which define the nested
             model grid. Default is [-180,180].

        YRANGE -> A 2-element vector containing the minimum and
             maximum box center latitudes which define the nested
             model grid. Default is [-180,180].

        /CHINA -> Set this switch to create nested-grid met data
             fil}es for the CHINA region.  Setting this switch will
             override the XRANGE and YRANGE keywords.

        /NAMER -> Set this switch to create nested-grid met data
             files for the NORTH AMERICA region.  Setting this switch 
             will override the XRANGE and YRANGE keywords.

        /EUROPE -> Set this switch to create nested-grid met data
             files for the EUROPE region.  Setting this switch will
             override the XRANGE and YRANGE keywords.
             ### NOTE: Need to define the region as of 10/4/07 ###

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        ================================================
        CN_GETRANGES
 
        External Subroutines Required:
        ================================================
        CTM_CLEANUP         CTM_GET_DATA
        CTM_WRITEBPCH       CTM_MAKE_DATAINFO (function)
        GETMODELANDGRIDINFO   

 REQUIREMENTS:
        None

 NOTES:
        (1) Works for the following types of data blocks:
            (a) 2-D "zonal-mean" (latitude-altitude)
            (b) 2-D "horizontal" (longitude-latitude)
            (c) 3-D "global"     (longitude-latitude-altitude)

 EXAMPLE:
        (1)
        CREATE_NESTED, INFILENAME='global_grid.bpch', $
                       OUTFILENAME='nested_grid.bpch, $
                       XRANGE=[ -150, -30 ],          $
                       YRANGE=[   10,  70 ]

             ; Trims data from "global_grid.bpch" to a nested grid 
             ; from 150W to 30W and 10N to 70N (in this example,
             ; this covers the US and parts of Canada and Mexico).

        (2)
        CREATE_NESTED, INFILENAME='global_grid.bpch', $
                       OUTFILENAME='nested_grid.bpch, /CHINA

             ; Trims data from "global_grid.bpch" to a nested grid 
             ; for the default China nested grid (70-150E and 11S 
             ; to 55 N).  The /CHINA keyword is a convenience to the
             ; user.  It will set XRANGE and YRANGE automatically for
             ; the China nested grid.


 MODIFICATION HISTORY:
        bmy, 10 Jan 2003: VERSION 1.00
        bmy, 25 Sep 2003: VERSION 1.01
                          - now call PTR_FREE to free pointer heap memory
        bmy, 16 Dec 2003: - now add THISFILEINFO in call to CTM_WRITEBPCH
  bmy & phs, 04 Oct 2007: GAMAP VERSION 2.10
                          - Added /CHINA, /NAMER, /EUROPE keywords
                            which may be specified instead of XRANGE
                            and YRANGE.  This is a user convenience.
        phs, 28 Jan 2008: - Bug fix if model name is 'GEOS3_30L'
                          - Free pointers not referenced at exist.
        lhu, 12 Jan 2012: GAMAP VERSION 2.16
                          - Better test for small number equality
                          - Add SEA4CRS nested grid range
        mps, 06 Nov 2013: - Remove SEAC4RS nested grid
                          - Add NAMER grid for GEOS-FP
        mps, 28 Oct 2015: - Add NAMER and CHINA grids for MERRA2

(See /n/home09/ryantosca/IDL/gamap2/regridding/create_nested.pro)


CREATE_NESTED_ASCII

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CREATE_NESTED_ASCII

 PURPOSE:
        Reads data from an ASCII file and trims it to nested-grid
        resolution.  Also renumbers I and J from "global" to "window" 
        coordinates.  Vertical and temporal resolution are not affected.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        CREATE_NESTED_ASCII [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INMODELNAME -> A string containing the name of the model 
             grid on which the input data resides.  Default is 'GEOS3'.

        INRESOLUTION -> Specifies the resolution of the model grid
             on which the input data resides.  INRESOLUTION
             can be 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 is 1.

        INFILENAME -> Name of the input file containing data to be 
             trimmed down to "nested" model grid resolution.  If 
             omitted, a dialog box will prompt the user to supply
             a filename.

        OUTFILENAME -> Name of the file that will contain trimmed
             data on the "nested" model grid.  OUTFILENAME will be
             in binary punch resolution.  If omitted, a dialog box 
             will prompt the user to supply a filename.

        XRANGE -> A 2-element vector containing the minimum and
             maximum box center longitudes which define the nested
             model grid. Default is [-180,180].

        YRANGE -> A 2-element vector containing the minimum and
             maximum box center latitudes which define the nested
             model grid. Default is [-180,180].

        HEADER -> Number of header lines to skip over.

        FORMAT -> String describing the input file format.  
             Default is '(2i3,a)', i.e., two 3-digit integers
             and then an unspecified length character line.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ================================================
        CTM_TYPE (function)   CTM_GRID (function)
        OPEN_FILE

 REQUIREMENTS:
        None

 NOTES:
        (1) Assumes I and J (the lon & lat grid box indices) 
            are the first two items on each line.

        (2) Assumes that the nested-grid does not wrap around
            the date line.  

 EXAMPLE:
        CREATE_NESTED_ASCII, INFILENAME='fert_scale.dat.1x1', $
                             OUTFILENAME='fert_scale.dat,     $
                             XRANGE=[ -140, -40 ],            $
                             YRANGE=[   10,  60 ],            $
                             FORMAT='(2i6,a)

             ; Trims data from "fert_scale.dat.1x1" to a GEOS-3
             ; 1x1 (default values) nested grid from 14OW to 4OW 
             ; and 10N to 60N (in this example, this covers the US 
             ; and parts of Canada and Mexico).

 MODIFICATION HISTORY:
        bmy, 10 Apr 2003: VERSION 1.00
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/create_nested_ascii.pro)


CREATE_NESTED_MET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CREATE_NESTED_MET

 PURPOSE:
        Reads GEOS-Chem binary met data files at global resolution
        and creates new files that have been "cut down" to a 
        particular nested-grid region (e.g. China, North America,
        Europe).  Vertical resolution is not affected.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        CREATE_NESTED_MET [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INFILENAME -> Name of the input file containing data to be 
             trimmed down to "nested" model grid resolution.  If 
             omitted, a dialog box will prompt the user to supply
             a filename.

        OUTFILENAME -> Name of the file that will contain trimmed
             data on the "nested" model grid.  OUTFILENAME will be
             in binary punch resolution.  If omitted, a dialog box 
             will prompt the user to supply a filename.

        /CHINA -> Set this switch to create nested-grid met data
             files for the CHINA region.

        /NAMER -> Set this switch to create nested-grid met data
             files for the NORTH AMERICA region.

        /EUROPE -> Set this switch to create nested-grid met data
             files for the EUROPE region.
             ### NOTE: Need to define the region as of 10/4/07 ###

        /VERBOSE -> Set this switch to print extra informational
             messages to the screen.

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        ================================================
        CNM_GETGRID            CNM_GETCORNERS

        External Subroutines Required:
        ================================================
        CTM_INDEX
        CTM_TYPE  (function)   CTM_GRID (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) Works for the following types of data blocks:
            (a) 2-D "horizontal" (longitude-latitude)
            (b) 3-D "global"     (longitude-latitude-altitude)

 EXAMPLE:
        CREATE_NESTED_MET, INFILENAME='20021031.i6.1x1',      $
                           OUTFILENAME='20021031.i6.1x1.USA', $
                           /NAMER

             ; Trims DAO met data from "20021031.i6.1x1" to a nested 
             ; grid from 150W to 30W and 10N to 70N (in this example,
             ; this covers the US and parts of Canada and Mexico).

 MODIFICATION HISTORY:
        bmy, 18 Jan 2003: VERSION 1.00
                          - adapted from "create_nested.pro"  
        bmy, 25 Sep 2003: VERSION 1.01
                          - also added GEOS-4 met fields
  bmy & phs, 24 Sep 2007: GAMAP VERSION 2.10
                          - Rewritten for compatibility with
                            GAMAP internal routine CTM_READ_GMAO
        bmy, 02 Apr 2008: GAMAP VERSION 2.12
                          - Make sure we create big-endian binary files

(See /n/home09/ryantosca/IDL/gamap2/regridding/create_nested_met.pro)


CREATE_TAGOX_RESTART

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CREATE_TAGOX_RESTART

 PURPOSE:
        Creates an initial tagged-Ox restart file w/ 13 tracers
        (i.e. corresponding to Arlene Fiore's original runs)

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
        CREATE_TAGOX_RESTART

 INPUTS:
        None
        
 KEYWORD PARAMETERS:
        FILENAME -> Name of full-chemistry restart file containing Ox 
             data (stored under tracer #2) to be used in creating a 
             Tagged Ox restart file.

        OUTFILENAME -> Name of the Tagged Ox restart file that will
             be created.  Default is "restart.Ox".

        /ZERO_STRAT -> Set this
         
 OUTPUTS:
        None

 SUBROUTINES:
        External subroutines required:
        ==============================
        CTM_GRID          (function)  
        CTM_MAKE_DATAINFO (function)
        CTM_WRITEBPCH

 REQUIREMENTS:
        None

 NOTES:
        Assumes Ox tracers have an offset of 40.

 EXAMPLE:
        CREATE_TAGOX_RESTART, FILENAME='gctm.trc.20010701', $
                              OUTFILENAME="gctm.trc.20010701.Ox'
             
             ; Reads Ox from a full chemistry restart file and
             ; creates a tagged-Ox restart file for initial spinup.

 MODIFICATION HISTORY:
        bmy, 18 Aug 2003: VERSION 1.01
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/create_tagox_restart.pro)


CREATE_USA_MASK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CREATE_USA_MASK

 PURPOSE:
        This program defines a mask over the USA.  All grid boxes
        that are totally contained w/ in the continental US are
        set equal to 1, with zeroes everywhere else.  Boxes that
        the USA shares w/ another country are set to zero.
         
 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        CREATE_USA_MASK [, Keywords ]

 INPUTS:

 KEYWORD PARAMETERS:
        OUTMODELNAME -> Name of the CTM model grid on which the
             mask is to be created.  Default is "GEOS_4".  NOTE:
             since the mask is only a 2-D quantity, all vertical
             layer information will be ignored.

        OUTRESOLUTION -> Resolution of the CTM model grid on 
             which the mask is to be created.  Default is 2.

        OUTFILENAME -> Name of the output file (BPCH format) which
             will contain the USA mask data.  Default is 
             "usa_mask.geos.{RESOLUTION}"

 OUTPUTS:
        None

 SUBROUTINES:
       External Subroutines Required:
       =====================================================
       CTM_TYPE          (function)   CTM_GRID   (function)
       CTM_MAKE_DATAINFO (function)   CTM_RESEXT (function)
       CTM_WRITEBPCH

 REQUIREMENTS:
        None

 NOTES:
        May not yet work for 4x5.

 EXAMPLE:
        CREATE_USA_MASK, OUTMODELNAME="GEOS4",           $
                       OUTRESOLUTION=4,                $
                       OUTFILENAME='usa_mask.geos.4x5'

             ; Creates a USA mask for the GEOS-4 4x5 grid and
             ; saves it to a bpch file named "us_mask.geos.4x5"

 MODIFICATION HISTORY:
  rch & bmy, 22 Jun 2004: VERSION 1.00
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/create_usa_mask.pro)


CTM_BOXSIZE (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 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)


CTM_CLEANUP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_CLEANUP

 PURPOSE: 
        Free memory blocked by excessive use of the GAMAP package.
        With the /DATA_ONLY option, only the data blocks themselves
        are freed, all header information remains accessible. 
        This speeds up any further analysis.  Also calls HEAP_GC
        to do garbage collection on unused heap variables.

 CATEGORY:
        GAMAP Utilities

 CALLING SEQUENCE:
        CTM_CLEANUP [, /DATA_ONLY, /NO_GC, /NO_FILE_CLOSE ]

 INPUTS:
        none

 KEYWORD PARAMETERS:
        /DATA_ONLY -> Only free heap variables that point to the
             actual data records. Leave all 'info' intact. Default 
             is to remove everything includign the global DATAINFO 
             and FILEINFO structure arrays.  NOTE: Setting this switch
             will not perform garbage collection via routine HEAP_GC.
           
        /NO_GC -> Set this switch to suppress garbage collection of
             heap variables with HEAP_GC.

        /NO_FILE_CLOSE -> Set this switch to suppress closing of
             all open files.

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        CTM_CLEANUP

 MODIFICATION HISTORY:
        mgs, 05 Oct 1998: VERSION 1.00
        mgs, 08 Oct 1998: - fixed DATA_ONLY part so that status is
                            reset to zero and derived data records 
                            are removed
        bmy, 21 Nov 2000: - Updated comments 
        bmy, 04 Oct 2004: GAMAP VERSION 2.03
                          - added /NO_GC keyword
                          - now call HEAP_GC to do garbage collection
                            of heap variables & pointers
        bmy, 23 Mar 2007: GAMAP VERSION 2.06
                          - Now add /NO_FILE_CLOSE keyword so as not
                            to close open files
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - close only files opened with GAMAP
        bmy, 16 May 2011: GAMAP VERSION 2.16
                          - Now make all loop indices long integers

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_cleanup.pro)


CTM_COLUMN_DU

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_COLUMN_DU

 PURPOSE:
        Calculates columns in Dobson Units for a given tracer.

 CATEGORY:
        GAMAP Utilities

 CALLING SEQUENCE:
        RESULT = CTM_COLUMN_DU( DiagN, [ Keywords ] )

 INPUTS:
        DIAGN -> Diagnostic category name (or number) containing the
             tracer data for which columns will be computed.  The
             default is 'IJ-AVG-$' (i.e. v/v mixing ratios).
             
 KEYWORD PARAMETERS:
        FILENAME -> (OPTIONAL) File containing CTM data for which 
             to compute columns.  If omitted, then the user will
             be prompted to select a file via a dialog box.

        TAU0 -> Starting TAU value of the desired data block (will
             be passed to CTM_GET_DATABLOCK).  If omitted, then 
             CTM_COLUMN_DU will read data for the first time in
             the data file.

        TRACER -> Number of tracer for which to compute columns.

        PFILENAME -> Name of the file containing surface pressure
             data (this is necessary in order to compute column
             sums).  If PFILENAME is omitted, then CTM_COLUMN_DU
             will look for surface pressure data in FILENAME.

        PTAU0 -> TAU0 value by which surface pressure data in
             PFILENAME is indexed.  If PTAU0 is omitted, then
             CTM_COLUMN_DU will use TAU0.  

        PTRACER -> Tracer number for the surface pressure data.
             Default is 1.  (For some GISS-CTM punch files, surface
             pressure is saved as tracer #0). 

        TROPFILENAME -> Name of the file containing the annual mean
             tropopause data for the GEOS-Chem model.  If TROPFILENAME
             is supplied, then columns will be computed from the
             surface up to the annual mean tropopause height.
             Otherwise, columns will be computed for the full
             vertical extent of the data.

        /DOUBLE -> If set, will return column sums as double
             precision.  Otherwise, will return column sums as
             single precision.

        MODELINFO -> Returns to the calling program the MODELINFO
             structure (i.e. output from CTM_TYPE) corresponding to 
             the data.

        GRIDINFO -> Returns to the calling program the GRIDINFO 
             structure (i.e. output from CTM_GRID) corresponding
             to the data.

        XMID -> Returns to the calling program the longitude centers
             in degrees for the extracted data block.
 
        YMID -> Returns to the calling program the latitude centers
             in degrees for the extracted data block.

        ZMID -> Returns to the calling program the altitude centers
             in # of levels for the extracted data block.
       
        /DU -> If set, will return column sums in Dobsun units.
	      Otherwise, will return column sums in molec/cm2. (jaf, 8/19/08)

        _EXTRA=e -> Picks up any extra keywords.


 OUTPUTS:
        RESULT -> a 2-D array containing the columns for TRACER
             in Dobson Units (DU).  1 DU = 2.69e16 molec/cm2.

 SUBROUTINES:
        Internal Subroutines:
        =============================================================
        CCD_GetAirMass (function)   CCD_Consistency_Check (function)
    

        External Subroutines Required:
        =============================================================
        CHKSTRU          (function)   CTM_BOXSIZE       (function)
        CTM_EXTRACT      (function)   CTM_GET_DATABLOCK (function)
        EXTRACT_FILENAME (function) 

 REQUIREMENTS:
        References routines in both GAMAP and TOOLS packages.

 NOTES:
        (1) An internal consistency check is now done to make sure
            the tracer data block is of the same model and resolution
            as the surface pressure and annual mean tropopause data blocks.

 EXAMPLE:
        Result = CTM_COLUMN_DU( 'IJ-AVG-$',          $
                                FileName='ctm.bpch'  $
                                Tracer=20,           $
                                Tau0=80304.0,        $
				 /DU )

             ; Returns O3 columns in DU from the file "ctm.bpch", 
             ; for March 1994 (TAU0 = 80304 for GEOS date 3/1/1994).

 MODIFICATION HISTORY:
        bmy, 26 Jul 1999: VERSION 1.00
        bmy, 20 Apr 2000: GAMAP VERSION 1.45
                          - renamed from "rvm_o3col"
                          - removed hardwiring, added comments
                          - added internal subroutine "CCD_Consistency_Check
                          - now can sum up to the annual mean tropopause
                            for GEOS model data blocks
        bmy, 30 Jul 2001: GAMAP VERSION 1.48
                          - bug fix: make sure to extract the same
                            lat/lon region for PS, tropopause heights
                            as we do for tracers
                          - added XMID, YMID, ZMID keywords to return
                            XMID, YMID, ZMID arrays from CTM_GET_DATABLOCK
                            to the calling program
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Rewritten for hybrid grids, and to compute 
                            DU for a data block of less than global size
  jaf & phs, 18 Aug 2008: GAMAP VERSION 2.13
                          - added capability to read surface pressure in 
			     GEOS, which stores surface pressure as a 3-D
                            array called PEDGE-$
			   - added DU keyword so that default unit is
			     molec/cm2, and renamed "DU" output to "Column"

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_column_du.pro)


CTM_CONVERT_UNIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_CONVERT_UNIT 

 PURPOSE:
        Wrapper program for CONVERT_UNIT.PRO

 CATEGORY:
        GAMAP Utilities

 CALLING SEQUENCE:
        CTM_CONVERT_UNIT, Data [,Keywords] 

 INPUTS:
        DATA -> The data array (or value) on which to perform
             the unit conversion.  DATA will be converted.

 KEYWORD PARAMETERS:
        CNUM -> For hydrocarbons, CNUM is the following
             ratio: ( moles C / moles hydrocarbon ).
             CNUM is needed to convert from ppbC to ppbv.

     Keyword Parameters Passed to CONVERT_UNIT:
     ==========================================
        FROM_UNIT -> An individual unit to search and replace. 
             If not given, any unit will be converted to TO_UNIT, 
             as long as the current unit belongs to 
             the same category. 

        TO_UNIT -> An individual unit to convert to. If not given, 
             all units that are converted (see FROM_UNIT) will be 
             replaced by the standard SI unit of their category.

        For the individual unit and categories see FIND_UNIT 

        _EXTRA=e  -> Picks up any extra keywords for CTM_CONVERT_UNIT.

 OUTPUTS:
        RESULT -> Returns 1 if conversion was successful, 0 otherwise.

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        CONVERT_UNIT
        CONVERT_MOLCM2_KG (function)
        CONVERT_KG_MOLCM2 (function)

 REQUIREMENTS:
        None

 NOTES:
        Will first convert ppbC to ppbv

 EXAMPLE:
        CTM_CONVERT_UNIT, Data, From='ppbC', To='ppbv', $
                          CNum=5, Result=Result

             ; converts Isoprene (5 mole C / 1 mole ISOP ) from
             ; parts per billion of Carbon (ppbC) to parts per
             ; parts per billion by volume of ISOP (ppbv).
             ; RESULT = 1 if unit conversion was successful.

 MODIFICATION HISTORY:
        bmy, 29 Sep 1998: VERSION 1.00
        bmy, 07 Oct 1998: VERSION 1.01
                          - Added unit conversion for mol/cm2 -> kg etc.. 
        mgs, 11 Nov 1998: - bug fix if seconds not passed
        bmy, 21 Jun 2002: GAMAP VERSION 1.51
                          - now recognize string "molec/cm2/s"
                          - updated comments, cosmetic changes
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_convert_unit.pro)


CTM_DATAINFO (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_DATAINFO  (function)

 PURPOSE:
        Return information about available categories, tracers or 
        time steps in either a given or the global datainfo structure 
        array.

 CATEGORY:
        GAMAP Utilities, Structures

 CALLING SEQUENCE:
        RESULT = CTM_DATAINFO( [DIAGN] [,DATAINFO] [,keywords] )

 INPUTS:
        DIAGN -> A diagnostic number or category name for which
             information shall be returned on available tracers 
             or time steps. If not given, CTM_DATAINFO returns
             information about all available diagnostics instead.
 
        DATAINFO -> An optional subset of the global DataInfo 
             structure array. If given, the search will be 
             restricted to the data records contained in DATAINFO.

 KEYWORD PARAMETERS:
        /TRACER -> If set, CTM_DATAINFO returns all tracer numbers
             that are available with the given diagnostics. This
             keyword has no effect if no DIAGN is given.

        /TAU0 -> Returns information about all available time steps
             for a given diagnostics. This keyword has no effect if
             either DIAGN is not given or /TRACER is set.
    
        /TAU1 -> Same as TAU0, but for the end of the time step.

        If none of these keywords is set, CTM_DATAINFO returns the
        index values for the DATAINFO structure array that match
        the requested diagnostics.

        STATUS -> restrict search to: 0=unread data, 1=read data.
             Default is 2=no restriction

        /EXPAND -> For multilevel diagnostics, CTM_DATAINFO normally
             returns only the template (with the '$' character). Use
             this keyword to get all individual levels as well.

 OUTPUTS:
        Depending on the keywords and the DIAGN parameter, an array
        with diagmostics numbers, index values, tracer numbers, or 
        time steps is returned. 

 SUBROUTINES:
        External Subroutines Required:
        ====================================
        CTM_SELECT_DATA, CTM_DIAGINFO

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        ; Must read in some data first
        CTM_GET_DATA, 'IJ-AVG-$', TRACER=1, FILE=''

        ; print all tracers that are available for diag IJ-AVG-$
        PRINT, CTM_DATAINFO( 'IJ-AVG-$', /TRACER )

        ; print all time step endings for diagnostics IJ-AVG-$
        PRINT, CTM_DATAINFO( 'IJ-AVG-$', /TAU0 )

        ; print all diagnostics that are available in the file
        ; (or in all files previously read)
        PRINT, CTM_DATAINFO()

        ; print all record indices for diagnostics IJ-AVG_$
        PRINT, CTM_DATAINFO( 'IJ-AVG-$' )

 MODIFICATION HISTORY:
        mgs, 07 Oct 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_datainfo.pro)


CTM_DIAGINFO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_DIAGINFO

 PURPOSE:
        Return information about one or all of the diagnostic 
        used by GEOS-CHEM, GISS, or other CTM's.  

 CATEGORY:
        GAMAP Utilities, Structures

 CALLING SEQUENCE:
        CTM_DIAGINFO, DIAGN, DIAGSTRU [ , Keywords ]

 INPUTS:
        DIAGN -> Diagnostic category name for which to extract the 
             information.  To retrieve information about all CTM
             diagnostic categories use the /ALL_DIAGS keyword.

 KEYWORD PARAMETERS:
        /ALL_DIAGS -> Retrieves information about all diagnostics.

        CATEGORY -> Returns to the calling program the punch
             file category name of the requested diagnostic(s)

        FILENAME -> Name of the diaginfo file (default diaginfo.dat)
             The file will be searched in the current directory first, 
             then in the directory where CTM_DIAGINFO.PRO is located.
             If not found in either location, a standard data block is
             retrieved from this file.

        /FORCE_READING -> Read from the diaginfo file (specified in
             FILENAME) and overwrite the contents of the common block.

        MAXTRACER -> Returns to the calling program the maximum
             number of tracers stored in the requested diagnostic(s).
             NOTE: This is now only necessary for backwards 
             compatibility with the GISS-II ASCII punch files.

        OFFSET -> Returns to the calling program the offset constant 
             that is used to locate tracers in the "tracerinfo.dat"
             file.  OFFSET is needed to locate the proper index from
             the "tracerinfo.dat" file.

        SPACING -> Returns to the calling program the interval
             between diagnostic offsets.

 OUTPUTS:
        DIAGSTRU -> returns a structure or structure array with the 
             following tags:
             Category  : Category name for this diagnostic
             Offset    : Offset factor used in "tracerinfo.dat" file
             Spacing   : Spacing between diagnostic offsets 
             MaxTracer : Max # of tracers stored in this diagnostic

 SUBROUTINES:
        Internal Subroutines:
        =============================================
        CD_Is_MaxTracer (function)

        External Subroutines Required:
        =============================================
        FILE_EXIST   (function)   OPEN_FILE
        ROUTINE_NAME (funciton)   STRBREAK (function)

 REQUIREMENTS:
        Requires routines from the TOOLS package.

 NOTES:
        (1) At first call, the tracer information structure array is
        read from a file.  Thereafter, the information is stored in a 
        common block where it is accessible in subsequent calls.

 EXAMPLES:
        (1)
        CTM_DIAGINFO, 'BIOGSRCE', R
        PRINT, R.CATEGORY, ':', R.MAXTRACER, ':',R.OFFSET
        IDL prints "BIOGSRCE:           0:        4700"
 
             ; Returns a structure containing tags CATEGORY,
             ; MAXTRACER, OFFSET for the "BIOGSRCE" diagnostic.
             ; as listed in the file "diaginfo.dat".

        (2)
        CTM_DIAGINFO, /ALL, CATEGORY=CATEGORY
        PRINT, CATEGORY
        IDL prints "IJ-AVG-$ IJ-24H-$ IJ-INS-$ INST-MAP ..."

             ; Return information about all category names
             ; listed in the file "diaginfo.dat".

 MODIFICATION HISTORY:
        bmy, 19 May 1998: VERSION 1.00
                          - developed from CTM_TRACERINFO.PRO v. 2.0 by
                            Martin Schultz (08 May 1998)
                            see comments to CTM_TRACERINFO.PRO for 
                            modification history of that subroutine
        bmy, 20 May 1998: - removed SCALE and UNIT structure tags & keywords
                          - added OFFSET structure tag & keyword
        bmy, 27 May 1998: - changed "tracers" to "diagnostics" in 
                            print statement.
        mgs, 13 Aug 1998: - now returns only first diagnostics for a
                            given number.  This permits to keep old
                            and new diagnostics in one file and use
                            the old diagnostics by name.
                          - introduced extra search one level above 
                            current dir.
        mgs, 17 Aug 1998: - changed defaults vor void return
                          - diaginfo.dat: MAXTRACER meaning changed!
        bmy, 17 Nov 2003: GAMAP VERSION 2.01
                          - Removed INDEX and TYPE, they're obsolete
                          - Now use new file format for "diaginfo.dat"
                            which allows for 8-digit offset numbers
                          - Added internal function CD_IS_MAXTRACER
                          - No longer read defaults from internal datablock
                          - Added SPACING keyword
                          - Updated comments 
        bmy, 09 Mar 2006: GAMAP VERSION 2.05
                          - Use "./diaginfo.dat" as default in
                            order to facilitate reading in IDL 5.5-
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now use the FILE_WHICH routine to
                            locate the "diaginfo.dat" file
        phs, 17 Jul 2008: GAMAP VERSION 2.12
                          - Bug fix: only use FILE_WHICH if the 
                            FILENAME keyword isn't passed.

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_diaginfo.pro)


CTM_DIFF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_DIFF

 PURPOSE:
        Computes absolute or relative differences between two CTM
        data blocks, and creates a new entry in the global DATAINFO
        structure.

 CATEGORY:
        GAMAP Utilities

 CALLING SEQUENCE:
        CTM_DIFF, DIAGN, [, Keywords ]

 INPUTS:
        DIAGN -> A diagnostic number or category name (see
             (CTM_DIAGINFO). A value of 0 (or an empty string)
             prompts processing of all available diagnostics.
             DIAGN can also be an array of diagnostic numbers or
             category names.

 KEYWORD PARAMETERS:
        FILE -> File name or list of file names containing the data 
             blocks to be differenced.  

        ILUN -> Logical unit number, or list of logical unit numbers
             of the files that contain the data blocks to be differenced.   

        TAU0 -> A time value or list of values to restrict the search.
             Default handling as with ILUN or TRACER. TAU0 superseeds
             /FIRST, /LAST or TAURANGE.

        TRACER -> Tracer ID number, or list of tracer ID numbers.  
             CTM_DIFF will difference the data blocks for diagnostic 
             DIAGN and tracer TRACER.

        /PERCENT -> If set, will compute the percent difference
             between two data blocks as 100 * ( DATA2 - DATA1 ) / DATA1.  
             Default is to compute the absolute difference DATA2 - DATA1.  

        NEWTRACER -> Returns to the calling program the tracer values
             for the data blocks, as read in from disk.

        NEWTAU -> Returns to the calling program the TAU0 values for
             the data blocks, as read in from disk.

        RANGE -> Returns the min & max difference values to the
             calling program.

        /MASK -> If set, the absolute % difference is return, with
             data below either thresholds (see pc_thr and diff_thr)
             set to a negative value, -99 .They are "masked", and can
             be set to a specific color in a plot (see ctm_plotdiff
             usage of the same keyword) or set to NaN for future
             analysis.
             
	 PC_THR, DIFF_THR : the %-Diff and Diff THResholds to mask data if
             /MASK is set.  Default values are 1% and 1e4.

 OUTPUTS:
        CTM_DIFF will append an entry to the global DATAINFO array of
        structures pertaining to the difference between the data
        blocks.

 OUTPUT KEYWORD:
 
        OUTLUN -> set this keyword to a variable name that will hold
             the LUN associated with the newly computed difference
             data.

        SUCCESS -> 0 by default, becomes 1 if MASK is set and all
             data are below the thresholds that define the MASK.


 SUBROUTINES:
        External Subroutines Requrired:
        =========================================================
        CTM_GET_DATA             CTM_MAKE_DATAINFO (function)
        CTM_GRID     (function)  GAMAP_CMN         (include file)
        INV_INDEX    (function)  YESNO             (function)
        CTM_DIAGINFO 

 REQUIREMENTS:
        References routines from GAMAP and TOOLS packages.

        Also, currently will only look at data blocks with the same
        tracer, since differencing two different tracers is not
        always that productive. 

 NOTES:
        (1) If DATA1 corresponds to the "old" data, and DATA2
            corresponds to the "new" data, then CTM_DIFF will 
            compute the following:
         
            Abs. Diff = ( new - old )
            % Diff    = ( new - old ) / old

        (2) The DATAINFO entries created by CTM_DIFF can be read into
            GAMAP with the /NOFILE option.  The ILUN values of these 
            data blocks will be negative, indicating derived data.

        (3) The call to CTM_REGRID probably does not work yet.
             Will get around to fixing that later...

 EXAMPLE:
        (1) Call CTM_DIFF to compute an absolute difference between
            two data blocks from two different punch files, at the
            same TAU0 value, for OH (DIAGN='CHEM-L=$', TRACER=1).
            
            FILE = [ 'ctm.bpch.v4-30', 'ctm.bpch.v4-31' ] 
            CTM_DIFF, 'CHEM-L=$', FILE=FILE, TRACER=1


        (2) Call CTM_DIFF to compute a relative difference between
            two data blocks from the same punch file, at two
            different TAU0 values, for tracer 1 (Radon).

            ILUN = 20
            TAU0 = [ 74472L, 74640L ]

            CTM_DIFF, 'IJ-AVG-$', ILUN=ILUN, TAU0=TAU0, $
                  TRACER=1, /Percent
 
 MODIFICATION HISTORY:
        bmy, 23 Apr 1999: VERSION 1.00
        mgs, 18 May 1999: - some bug fixes in error checks.
                          - regridding still not tested !!
        mgs, 10 Jun 1999: - bug fix for percent diference (indexing)
        bmy, 15 Sep 1999: GAMAP VERSION 1.43
                          - now use the GRIDINFO structure from the
                            global FILEINFO structure, if it exists.
                          - bug fix in call to CTM_GET_DATABLOCK
                          - updated comments
        bmy, 14 Jan 2000: GAMAP VERSION 1.44
                          - now allow comparision of two different
                            tracer numbers (e.g. for comparing two
                            simulations w/ different tracer indices)
                          - added error checking for size of the
                            FILE, ILUN, TAU0, TRACER keywords
                          - deleted obsolete code
        bmy, 26 Jan 2000: GAMAP VERSION 1.45
                          - now allow TAU0, FILE, ILUN, TRACER to have 
                            0 elements w/o generating an error message
        bmy, 15 Nov 2001: GAMAP VERSION 1.49
                          - Now make sure that NEWTRACER is not a 
                            multiple of 100, so that the tracer #
                            will be saved correctly to the global 
                            DATAINFO structure 
        bmy, 22 Apr 2002: GAMAP VERSION 1.50
                          - updated comments
        bmy, 19 Nov 2003: GAMAP VERSION 2.01
                          - Now get spacing between diagnostic
                            offsets from CTM_DIAGINFO
        bmy, 29 Jan 2004: - Added LEV keyword so that you can
                            select just a single level
                          - If we are just comparing a single level,
                            then do not test altitude dimensions
                            of the two data blocks.
        bmy, 16 Feb 2005: GAMAP VERSION 2.03
                          - now pass _EXTRA=e to CTM_GET_DATA 
        phs, 24 Oct 2006: GAMAP VERSION 2.05
                          - replace CTM_REGRID with CTM_REGRIDH
                          - pass _EXTRA=e to CTM_REGRIDH
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - added RANGE keyword for sending min/max
                            difference values to the calling program
        phs, 25 Sep 2009: GAMAP VERSION 2.13
                          - OUTLUN kwrd returns LUN associated with
                            computed difference
                          - /MASK is available to deals with absolute
                            %-age data and masked data below PC_THR
                            and/or DIFF_THR

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_diff.pro)


CTM_DOSELECT_DATA (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_DOSELECT_DATA (function)

 PURPOSE:
        Return indices for data blocks that match specific
        criteria.  This is an internal routine which is called
        by CTM_GET_DATA.  

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        INDEX = CTM_DOSELECT_DATA( DIAGN, USE_DATAINFO [, keywords ] )

 INPUTS:
        CATEGORY -> A string or string array with category names
            to search for. Multilevel categories can be expanded to
            a string array with the EXPAND_CATEGORY function.
            Usually, CTM_DOSELECT_DATA should be called with only
            one "logical" category at the time, i.e. only for
            multilevel diagnostics should it contain more than one
            element. Otherwise, the tracer offset may be wrong.

        USE_DATAINFO -> A valid DataInfo structure. No error checking 
            is performed.

        Both parameters are mandatory.

 KEYWORD PARAMETERS:
        ILUN -> A logical unit value or an array of logical unit
            values. Only records from corresponding files will be 
            returned. If ILUN is an undefined variable, information
            about all previously opened files will be returned,
            and ILUN will contain all logical unit numbers that 
            match the selection criteria.

        TRACER -> A tracer number or an array of tracer numbers to
            restrict the selection of data records. Default is to
            return information about all tracers.
            Tracer numbers less than 100 are automatically expanded
            to include the offset of certain diagnostics (see
            keyword TRCOFFSET and routine CTM_DIAGINFO). If TRACER is
            an undefined variable, all tracers that match the selection 
            criteria are returned.

        TRCOFFSET -> A tracer offset (multiple of 100) that will be
            added to TRACER. The search is performed for both,
            TRACER and TRACER+TRCOFFSET. (for tracer offsets see
            routine CTM_DIAGINFO and file diaginfo.dat)
 
        TAU -> A time value (tau0 !) or an array of time values
            to restrict the selection of data records. Default is to
            return information about all time steps. If TAU is an
            undefined variable, it will return all time steps that
            match the selection criteria.

        STATUS -> Restricts the data selection to
            Data that has not been read  (STATUS = 0)
            Data that has been read      (STATUS = 1)
            All data blocks              (STATUS = 2, default)
            If STATUS is 1, all pointers returned in DATA are tested
            for validity. Status will automatically be restricted 
            to range 0..1

        COUNT -> A named variable that will return the number of
            data blocks found with the given selection criteria

        MISSING -> If no records were found that match the selection 
            criteria, MISSING will return a string array with the 
            items that could not be matched (e.g. ['TRACER','ILUN']).
            If records were found, MISSING returns an empty string.

        SPACING -> Passes to CTM_DOSELECT_DATA the spacing between
            diagnostic offsets listed in "diaginfo.dat".  

 OUTPUTS:
        The function returns an (long) integer array that contains
        index values to all the data blocks that match the selection
        criteria. If no data is found, -1L is returned.

 SUBROUTINES:
        Uses IS_SELECTED function

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        See CTM_SELECT_DATA and CTM_READ_DATA source codes.

 MODIFICATION HISTORY:
        mgs, 19 Aug 1998: VERSION 1.00
        mgs, 07 Oct 1998: - added DEBUG keyword
        mgs, 22 Oct 1998: - now filters ilun, tracer, and tau
                            after finding matching records. This
                            was necessary to find the correct first
                            or last time step in CTM_GET_DATA.
                            Needs some more testing whether there are
                            side effects when TAU0 and ILUN or TRACER
                            are specified.
        mgs, 09 Nov 1998: - improved documentation
                          - default status now 2
                          - uses status field in use_datainfo instead of
                            ptr_valid function
                          - ILUN, TRACER and TAU only overwritten
                            if they are undefined variables
                          - added MISSING keyword
        mgs, 10 Nov 1998: - minor bug fix for status=1
        bmy, 19 Nov 2003: GAMAP VERSION 2.01
                          - added SPACING keyword to pass the
                            diagnostic spacing from CTM_DIAGINFO
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_doselect_data.pro)


CTM_EXAMPLES

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_EXAMPLES

 PURPOSE:
        Quick and dirty demonstration of various CTM_* routines

 CATEGORY:
        GAMAP Examples, GAMAP Utilities

 CALLING SEQUENCE:
        CTM_EXAMPLES

 INPUTS:
        None

 KEYWORD PARAMETERS:
        /PNG -> Set this switch to create PNG files from screen
             shots of examples generated by this program.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===============================================
        OPEN_DEVICE           MULTIPANEL
        CTM_GET_DATA          GETMODELANDGRIDINFO
        TVMAP                 PAUSE
        CTM_PLOT              SCREEN2PNG
        NYMD2TAU (function)   CTM_OVERLAY

 REQUIREMENTS:
        None

 NOTES:
        Updated with the most recent GAMAP routines.

 EXAMPLE:
        CTM_EXAMPLES, /PNG

             ; Show example plots and create screenshot output
             ; as PNG files.

 MODIFICATION HISTORY:
        mgs, 20 Aug 1998: INITIAL VERSION
        mgs, 22 Oct 1998: - adapted for new use of CTM_GET_DATA
                            some more comments
        mgs, 26 Oct 1998: - attached a few more comments about extended 
                            use of ctm_get_data at end
        mgs, 18 Nov 1998: - added call to CTM_MAKE_DATAINFO
        bmy, 06 Oct 2006: GAMAP VERSION 2.05
                          - Updated examples w/ newest GAMAP routines
                          - Added examples w/ CTM_OVERLAY and
                            FIND_CELLS_BY_COUNTRY
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - now uses FILE_WHICH to find ctm.bpch.examples

(See /n/home09/ryantosca/IDL/gamap2/examples/ctm_examples.pro)


CTM_EXTRACT (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_EXTRACT (function)

 PURPOSE:
        Extracts a block of data from a 3-D CTM data cube.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        CTM_EXTRACT, DATA, MODELINFO, GRIDINFO [,Keywords]

 INPUTS:
        DATA -> The data cube from which to extract a region.
             DATA must be 3-dimensional (e.g. lon-lat-alt, or 
             lon-lat-tracer, etc).

 KEYWORD PARAMETERS:
        MODELINFO -> The MODELINFO structure returned from function 
             CTM_TYPE.  

        GRIDINFO -> The GRIDINFO structure returned from function
             CTM_GRID.

        AVERAGE -> Bit flag indicating the dimensions over which to
             average the data:
                1 :  longitudinal
                2 :  latitudinal
                4 :  vertical
             These values can be combined. E.g., to average over 
             longitude and latitude use 3. A bit set in AVERAGE 
             superseeds the corresponding bit in TOTAL (see below).
 
        TOTAL -> Bit flag indicating the dimensions over which
             to sum the data:
                1 :  longitudinal
                2 :  latitudinal
                4 :  vertical
             These values can be combined. E.g., to integrate over
             longitude and latitude use 3. A bit set in AVERAGE
             superseeds the corresponding bit in TOTAL (see above).

        /INDEX -> If set, will interpret LAT, LEV, and LON as index 
             arrays.  If not set, will interpret LAT, LEV, and LON as 
             ranges (i.e. two-element vectors containing min and max values).

        LAT -> An index array of latitudes *OR* a two-element vector 
             specifying the min and max latitudes to be included in
             the extracted data block.  Default is [ -90, 90 ].

        LEV -> An index array of sigma levels *OR* a two-element vector 
             specifying the min and max sigma levels to be included
             in the extracted data block.  Default is [ 1, GRIDINFO.LMX ].

        LON -> An index array of longitudes *OR* a two-element vector 
             specifying the min and max longitudes to be included in
             the extracted data block.  Default is [ -180, 180 ].

        ALTRANGE -> A vector specifying the min and max altitude 
             values (or a scalar specifying a single altitude) to
             be included in the extracted data block.

        PRANGE -> A vector specifying the min and max pressure levels 
             (or a scalar specifying a single pressure level) to be
             included in the extracted data block.

        WE -> Returns to the calling program the index array of longitudes 
             for the extracted data region, ordered from west to east.

        SN -> Returns to the calling program the index array of latitudes
             for the extracted data region, ordered from South to North.
 
        UP -> Returns to the calling program the index array of vertical  
             levels for the extracted data region, ordered from surface
             to top.

        DIM -> A named variable will return the new dimension information 
             of the data block after averaging or totaling.

        _EXTRA=e   -> Picks up extra keywords for CTM_INDEX.

 OUTPUTS:
        X, Y, Z -> Arrays of latitude, longitude, or altitude values 
             corresponding to the the 1st, 2nd, and 3rd dimensions of 
             the DATA array, respectively.

 SUBROUTINES:
        CTM_INDEX 
        DEFAULT_RANGE (function)

 REQUIREMENTS:
        Uses GAMAP package subroutines.

 NOTES:
        (1) CTM_EXTRACT returns the extracted data region as 
        the function value.

        (2) Assumes a 3-D data cube as input, of dimensions (lon, lat,
        alt), or for some diagnostics (lon, lat, "tracer" number).

        (3) In the calling program, CTM_TYPE and CTM_GRID must be 
        called to compute the MODELINFO and GRIDINFO structures,
        which can then be passed to CTM_EXTRACT.

        (4) If any of the LAT, LON, LEV, ALTRANGE, PRANGE keywords are
        explicity specified, then CTM_EXTRACT will return to the
        calling program their original, unmodified values.  If any
        of these are not explicitly specified , then CTM_EXTRACT 
        will return to the calling program default values.  

 EXAMPLE:
        (1)
        MODELINFO  = CTM_TYPE( 'GEOS4', RES=4 )
        GRIDINFO   = CTM_GRID( MODELINFO )
        DATAREGION = CTM_EXTRACT( DATACUBE,                   $
                                  MODELINFO=MODELINFO,        $
                                  GRIDINFO=GRIDINFO           $
                                  LON=[-180,0], LAT=[-30,30], $ 
                                  LEV=[1,10] )

               ; Extracts from a GEOS-4 4x5 data cube a region 
               ; delimited by longitude = [-180, 0], 
               ; latitude = [-30, 30], for levels 1 to 10.

        (2)
        LON = INDGEN( 36 )
        LAT = INDGEN( 16 ) + 15
        LEV = INDGEN( 10 ) 
        MODELINFO  = CTM_TYPE( 'GEOS4' )
        GRIDINFO   = CTM_GRID( MODELINFO )
        DATAREGION = CTM_EXTRACT( DATACUBE,            $
                                  MODELINFO=MODELINFO, $
                                  GRIDINFO=GRIDINFO,   $
                                  /INDEX,  LON=LON,    $
                                  LAT=LAT, LEV=LEV )

               ; Extracts same data region as in Example (1) but 
               ; here passes explicit index arrays instead of ranges.

 MODIFICATION HISTORY:
        bmy, 16 Sep 1998: VERSION 1.00
        bmy, 17 Sep 1998: - now extracts data from data cube one 
                            dimension at a time to avoid errors
        bmy, 18 Sep 1998: VERSION 1.01
                          - INDEX, SN, WE, UP keywords added
                          - LATRANGE, LONRANGE, LEVRANGE renamed
                            to LAT, LON, LEV (since they may now 
                            contain arrays and not just ranges).
        mgs, 21 Sep 1998: - some more error checking
                          - removed MinData and MaxData 
        bmy and mgs, 22 Sep 1998: VERSION 1.02
                          - added AVERAGE and TOTAL keywords
        bmy, 24 Sep 1998: VERSION 1.03
                          - Now returns original values of LAT, LON, 
                            LEV, ALTRANGE, and PRANGE if those keywords
                            are specified.  Otherwise returns
                            defaults.
        MGS, 29 SEP 1998: - Introduced new DEFAULT_RANGE function.
        bmy, 06 Oct 1998: - fixed bug: now S = size( NEWDATA )
        bmy, 08 Oct 1998: VERSION 1.04
                          - MODELINFO and GRIDINFO are now keywords
                          - added X, Y, and Z as parameters
        bmy, 11 Feb 1999: - updated comments
        bmy, 19 Feb 1999: VERSION 1.05
                          - added FIRST keyword so that the values of
                            THISDATAINFO.FIRST can be passed from the
                            calling routine.
                          - now call ADJ_INDEX to adjust the WE,
                            SN, and UP index arrays for data blocks
                            that are less than global size.
                          - added DEBUG keyword
        mgs, 16 Mar 1999: - cosmetic changes
        mgs, 02 Apr 1999: - bug fixes that prevented use with 2D fields
                            (e.g. EPTOMS data)
        mgs, 21 May 1999: - now catches error in multitracer diagnostics
                            when user requests a level beyond LMX.
        qli, 26 May 1999: - "max(newlev) ge" corrected to "gt"
        bmy, 15 Sep 1999: VERSION 1.43
                          - removed bugs that caused data blocks to
                            always have MODELINFO.NTROP vertical
                            layers
        bmy, 04 Dec 2000: GAMAP VERSION 1.47
                          - add code for future bug fix
        bmy, 24 Apr 2001: - bug fix: now can handle longitudes
                            greater than 180 degrees
        bmy, 06 Jun 2001: - bug fix: Test if LON exists before
                            assigning it to NEWLON.
        bmy, 30 Jul 2001: GAMAP VERSION 1.48
                          - bug fix: now extract proper latitude range
                            for data blocks smaller than global size
        bmy, 26 Jun 2002: GAMAP VERSION 1.51
                          - Default value of FIRST is now [1,1,1], 
                            since this has to be in Fortran notation.
                          - also do error checking on FIRST near
                            the beginning of the program.
        bmy, 15 Nov 2002: GAMAP VERSION 1.52
                          - now can handle total/average for MOPITT grid
        bmy, 23 Aug 2004: GAMAP VERSION 2.03
                          - now can handle single-point data blocks
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 19 Nov 2007: GAMAP VERSION 2.11
                          - Updated comments
        bmy, 10 Dec 2007: GAMAP VERSION 2.12
                          - Now pad ALTRANGE and PRANGE to 2 elements
                            if they are passed w/ one element
        bmy, 13 Aug 2009: GAMAP VERSION 2.13
                          - Bug fix: now compute DEF_X_RANGE from the
                            grid edges for computing NEWLON.  Now
                            also works for nested grids.
  phs & bmy, 13 Oct 2009: - Bug fix: now account for ranges that
                            straddle the date line when computing
                            DEF_X_RANGE
        ccc, 21 Oct 2009: - Bug fix when PRange is passed.
        bmy, 20 Mar 2017: GAMAP VERSION 2.19
                          - Now make sure that WE, SN, UP are converted
                            from Fortran to IDL notation properly
                            when /INDEX is specified.

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_extract.pro)


CTM_GETDEFAULTSTRUCTURES

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_GETDEFAULTSTRUCTURES

 PURPOSE:
        Return default values for FileInfo and DataInfo for
        subsequent analysis. The defaults are taken from the
        global common block defined in gamap_cmn.pro

 CATEGORY:
        GAMAP Internals, Structures

 CALLING SEQUENCE:
        CTM_GETDEFAULTSTRUCTURES, FileInfo, DataInfo, result=result

 INPUTS:
        FILEINFO -> A named variable that will contain the global
            FileInfo structure array, i.e. information about all
            files that have been opened.

        DATAINFO -> A named variable that will contain the global
            DataInfo structure array, i.e. information about all
            data records that have been read from the headers of 
            all opened CTM files.

 KEYWORD PARAMETERS:
        RESULT -> returns 1 if assignment was successful, 0 otherwise.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required
        ==============================
        GAMAP_CMN

 REQUIREMENTS:
        Requires routines from the GAMAP package.

 NOTES:
        None

 EXAMPLE:
        CTM_GETDEFAULTSTRUCTURES, $
            FileInfo, DataInfo, result=result

        if (not result) then return

        ; the current state of the global FileInfo and DataInfo 
        ; structures will be copied into FileInfo and DataInfo

 MODIFICATION HISTORY:
        mgs, 20 Aug 1998: VERSION 1.00
        mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_getdefaultstructures.pro)


CTM_GETWEIGHT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_GETWEIGHT

 PURPOSE:
        Computes the "mapping weights" for regridding data from
        a "fine" CTM grid to a CTM grid of equal or coarser 
        horizontal resolution.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        CTM_GETWEIGHT, OLDGRID, NEWGRID, WEIGHT, XX_IND, YY_IND [, Keywords ]

 INPUTS:
        OLDGRID -> GRIDINFO structure (use ctm_grid to create one) 
             which defines the old ("fine") grid.

        NEWGRID -> GRIDINFO structure (use ctm_grid to create one) 
             which defines the new ("coarse") grid.
 

 KEYWORD PARAMETERS:
        WEIGHTFILE (optional) -> Name of the file to which WEIGHT,
             XX_IND, and YY_IND will be written.  If WEIGHTFILE is
             not given, then

        WEIGHTFORMAT (optional) -> Specify the format string used to
             save the mapping weights to WEIGHTFILE.  For high-res grids,
             you may need to specify more than the default 2 decimal 
             precision.  Default value is '(3x,12f6.2)'.

 OUTPUTS:
        WEIGHT -> Array of mapping weights which defines the fraction
             of each "fine" grid box that fits into each "coarse" 
             grid box.

        XX_IND -> Array of "longitude" grid box indices of the "fine" 
             grid boxes that fit into each "coarse" grid box.  

        YY_IND -> Array of "latitude" grid box indices of the "fine" 
             grid boxes that fit into each "coarse" grid box.

 SUBROUTINES:
        External Subroutines Required:
        ================================

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.

 NOTES:
        (1) This routine was adapted from CTM_REGRID.  It is
            sometimes computationally expedient to compute the
            mapping weights once for the entire horizontal grid 
            and save them to a file for future use.
            
        (2) Right now this only works in regridding from a "fine" 
            grid to a grid of equal horiziontal resolution (i.e. with
            shifted grid boxes) or coarser horizontal resolution.

 EXAMPLE:
        OLDTYPE = CTM_TYPE( 'GENERIC', RES=1, HALFPOLAR=0, CENTER180=0 )
        OLDGRID = CTM_GRID( OLDTYPE, /NO_VERTICAL )
        NEWTYPE = CTM_TYPE( 'GEOS4', RES=4 )
        NEWGRID = CTM_GRID( NEWTYPE, /NO_VERTICAL )

        CTM_GETWEIGHT, OLDGRID, NEWGRID, WEIGHT, XX_IND, YY_IND, $
             WEIGHTFILE = 'weights.1x1.to.geos1.4x5']

             ; Precomputes the mapping weights for regridding a
             ; 1 x 1 grid to the GEOS-1 4 x 5 grid, and saves them
             ; to an ASCII file named "weights.1x1.to.geos1.4x5"

 MODIFICATION HISTORY:
        bmy, 11 Aug 2000: VERSION 1.01
                          - adapted from CTM_REGRID
        bmy, 21 Jan 2003: VERSION 1.02
                          - Added fix for GEOS 1 x 1.25 grid
        bmy, 04 May 2006: GAMAP VERSION 2.05
                          - Added fix for GENERIC 2.5 x 2.5 grid
        bmy, 29 Jun 2006: - Added fix for GEOS 1x1 -> GENERIC 1x1 
  bmy & phs, 04 Oct 2007: GAMAP VERSION 2.10
                          - added fix for GENERIC 0.5 x 0.5 grid
                          - general fix for over-the-dateline cases
        bmy, 26 Sep 2008: GAMAP VERSION 2.13
                          - Add WEIGHTFORMAT keyword to specify more
                            decimal places of precision if need be

(See /n/home09/ryantosca/IDL/gamap2/regridding/ctm_getweight.pro)


CTM_GET_DATA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_GET_DATA

 PURPOSE:
        Retrieve specific data records from CTM output files.
        Opening files, parsing header information, and loading
        of data are handled transparently and can be 
        controlled by various keywords. The routine returns a
        subset of the global DATAINFO structure that matches the
        requested category and (optional) tracer and time step(s).

        This routine should be called *whenever* you want to 
        access data and you are not sure that it has been 
        loaded previously. It provides the general user-interface
        for GAMAP (the Global Atmospheric Model output Analysis 
        Package). 

        For the future, a widget interface to this routine is 
        planned.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        CTM_GET_DATA, DATAINFO [,DIAGN] [,keywords]

 INPUTS:
        DIAGN -> A diagnostic number or category name (see
             (CTM_DIAGINFO). A value of 0 (or an empty string)
             prompts processing of all available diagnostics.
             DIAGN can also be an array of diagnostic numbers or
             category names.

 KEYWORD PARAMETERS:
        FILENAME -> (optional) If FILENAME is a fully qualified file path
             the specified file is opened without user interaction.
             If filename is empty or contains wildchards (*,?), a
             pickfile dialog will be displayed.
             If FILENAME is a named variable it will contain the full
             file path upon return so that a subsequent call to
             CTM_GET_DATA with the same FILENAME argument will not prompt
             another file selection dialog.
                If the FILENAME keyword is present, CTM_GET_DATA
             will restrict it's scope to records from the selected
             is file (even if FILENAME contains an empty string, it will 
             restrict the scope of the search!).
                If the file is found in the global FILEINFO structure or
             the USE_FILEINFO structure (i.e. it has been opened 
             previously), then it will not be parsed again; instead the
             data records are returned from memory.
                The data itself is loaded transparently via 
             CTM_RETRIEVE_DATA.

        ILUN -> An optional value or array of logical unit numbers. If
             given, the search is restricted to data from the specified
             files. Default is to use all files (unless the FILENAME
             keyword is present). If an undefined variable
             is passed into ILUN, information about all accessible files
             in the global FILEINFO structure (or USE_FILEINFO) is returned.

        TRACER -> A tracer ID number or a list of those. If given, the
             search is restricted to those tracers. Default is to use all 
             tracers. If an undefined variable is passed into TRACER, 
             and one specific diagnostics is requested with DIAGN,
             information about all accessible tracers in the global
             DATAINFO structure or USE_DATAINFO structure or the
             DATAINFO structure associated with a specific file is returned.

        TAU0 -> A time value or list of values to restrict the search.
             Default handling as with ILUN or TRACER. TAU0 superseeds
             /FIRST, /LAST or TAURANGE.

        TAURANGE -> A 2-element vector containing the first and last tau0
             value to look for. 

        /FIRST, /LAST -> extract first or last time step that is stored for
             the selected diagnostics, ilun, and tracer. Only one can be 
             be active at a time. /LAST superseeds /FIRST.

        INDEX -> A named variable that will contain the indices of the 
             records in USE_DATAINFO that match the selection criteria.
             You can test INDEX[0] ge 0 in order to see if CTM_GET_DATA has
             been successful although it is now recommended to test for
             n_elements(DATAINFO) eq 0. 
                The INDEX keyword is useful if you want to change the
             information contained in the selected DATAINFO structures
             globally.

        USE_FILEINFO -> (optional) If provided, CTM_GET_DATA will 
             restrict its search to only the files that are
             contained in USE_FILEINFO which must be a FILEINFO 
             structure array. Default is to use the global information 
             (see gamap_cmn.pro).
             If an undefined named variable is provided in USE_FILEINFO,
             it will either contain the global FILEINFO structure array 
             or the FILEINFO record of the specified file.
             USE_FILEINFO must contain entries for all logical unit numbers
             that are used in USE_DATAINFO.

        USE_DATAINFO -> (optional) Restrict search to records contained
             in USE_DATAINFO which must be a DATAINFO structure array. 
             If an undefined named variable is provided in USE_DATAINFO,
             it will either contain the global DATAINFO structure array 
             or all DATAINFO records of the specified file.
             See also USE_FILEINFO.

        /INTERNAL_USE -> Set this keyword if you want to prevent a call
             to CTM_OPEN_FILE, but instead abort in case of undefined 
             (global) FILEINFO or DATAINFO structures.

 OUTPUTS:
        DATAINFO -> An array of DATAINFO records that match the selected 
             criteria. You can then simply loop over 
             0..n_elements(DATAINFO)-1 to access all data records and 
             extract the data as *(DATAINFO[i].data).
             DATAINFO will be undefined if no records are found!!
             Always test for  IF (n_elements(DATAINFO) eq 0) ... !
             NOTE: Alternatively you can return the INDEX to the selected
             data records in the global (or USE_) datainfo structure array
             with the INDEX keyword. This may in some cases eliminate the
             need to make a local copy of the selected DATAINFO records. 

 SUBROUTINES:
       pro reopen_all_files,fileinfo
       (needed in order to get free unit numbers)

       pro make_compound_datainfo,DataInfo,category,ilun,tracer,tau0,tau1
       (make compound structure for multilevel or multitracer diagnostics)

       pro update_tracer_datainfo,datainfo,traceroffset
       (enter tracer information into global datainfo structure)

 REQUIREMENTS:
       Several ctm_* routines are used
       Also uses UNDEFINE (by D. Fanning)

 NOTES:
       Please test rigorously. In case of read errors, try using CTM_OPEN_FILE
       with the /PRINT keyword.

       If your model output (ASCII punch file) does not contain the
       dimensional information about each data block, it may cause problems
       for diagnostics that do not contain 72x46 elements.
       It's defintively a good idea to implement this little change *NOW* !

       Outline of this procedure:
       - get all data records that match selection criteria
       - create "compound" datainfo structures for multilevel and
         multitracer diagnostics (those hold 3D data blocks)
       - read data for all selected compound structures unless only
         status information requested

 EXAMPLE:
       See CTM_EXAMPLES
       

 MODIFICATION HISTORY:
        mgs, 20 Aug 1998: VERSION 1.00
        mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
        mgs, 22 Sep 1998: - changed to accomodate usage of 
                            tracer information
        mgs, 22 Oct 1998: - old FILEINFO and DATAINFO parameters now
                            keywords USE_..., new DATAINFO parameter
                            returns selected subset of records.
                          - print statements replaced with message
                          - DEBUG messages improved
                          - catch cancelled file open dialog
        mgs, 26 Oct 1998: - datainfo now undefined at start
                          - allows for multiple categories
                          - ilun, tracer, tau0 keyword variables renamed
                            as sel_... in order to preserve them
        mgs, 04 Nov 1998: - sel_tracer now expanded to include offsets
        mgs, 10 Nov 1998: VERSION 3.0 
                          - major update! Program structure much more
                            straightforward!
        mgs, 12 Nov 1998: - bug fixes for simple diagnostics (line 732)
                            and finding offset tracers (in update_...)
                            replaced tracer by (tracer mod 100) in 3 places
        mgs, 19 Nov 1998: - bug fix with scale factor. Didn't get globally
                            updated because it was linked to unit. Need a
                            more generic global update procedure !
        mgs, 03 Dec 1998: - yet another bug fix in reopen files: needed
                            to test for negative ilun before fstat
        bmy, 21 Jan 1999: - added outer parentheses to the FORMAT
                            descriptor (255(I4,1x)) to avoid errors
        mgs, 17 Feb 1999: - bug fix for simple diagnostics: needed
                            to add dummy value to compound array.
        mgs, 16 Mar 1999: - catch error in tracerinfo.dat (more than one
                            tracer with same number)
                          - error in update_tracer... should have been
                            fixed. Some more debug output added for 
                            testing.
        mgs, 23 mar 1999: - set vertical dimension to -1 for new compound
                            datainfo records
        mgs, 24 May 1999: - updated filetype info
        mgs, 02 Jun 1999: - added retall statement after error
                            message
        bmy, 23 Nov 1999: - added /SMALLCHEM keyword for CTM_TRACERINFO
        bmy, 27 Sep 2001: GAMAP VERSION 1.49
                          - Set F77=1 for filetype 4 (DAO met fields)
                          - Now reference function LITTLE_ENDIAN
                          - Swap endian in OPEN_FILE if reading data
                            on a little-endian machine (e.g. PC) 
        bmy, 19 Nov 2003: GAMAP VERSION 2.01
                          - now test valid diagnostics using 
                            DIAGSTRU[*].CATEGORY and not DIAGSTRU[*].INDEX
                          - removed /SMALLCHEM keyword, it's obsolete
                          - Now recognizes binary files as having
                            FILETYPE values between 100 and 200
                          - Removed /SMALLCHEM flag, it's obsolete
                          - Now uses diagnostic spacing from CTM_DIAGINFO
                            and pass this to UPDATE_TRACER_DIAGINFO
        bmy, 11 Feb 2004: GAMAP VERSION 2.01a
                          - Internal routine MAKE_COMPOUND_DATAINFO
                            now passes SPACING from CTM_DIAGINFO
                            to routine CTM_DOSELECT_DATA
        bmy, 27 Oct 2004: GAMAP VERSION 2.03
                          - added QUIET keyword to suppress printing
                            information about retrieved tracers
        bmy, 06 Feb 2006: GAMAP VERSION 2.04
                          - Bug fix: use DIALOG_PICKFILE to get file name
                            before calling CTM_OPEN_FILE.  This is necessary
                            because the tests for certain file types requires
                            the file name to be known ahead of time.
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - now passes _EXTRA keyword to
                            CTM_OPEN_FILE. This allows to read nested 
                            met (GMAO) files by using /NA or /CHINA
  bmy & phs, 20 Nov 2007: GAMAP VERSION 2.11
                          - If FILENAME is not defined, then the value
                            of the filename selected via dialog box
                            will be passed back to the calling program.

 KNOWN BUGS OR WEAKNESSES:
        - handling of USE_DATAINFO and USE_FILEINFO is not carried 
          through all lower level subroutines, i.e. they may be replaced
          by *pGlobal... in some occasions. Since USE_... should always
          be a subset of *pGlobal..., no serious errors are expected
          from this weakness. 

        - known bug in update_tracer_datainfo, see comment in routine.

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_get_data.pro)


CTM_GET_DATABLOCK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_GET_DATABLOCK

 PURPOSE:
        Extracts a data block from a CTM punch file.
        (Wrapper program for CTM_GET_DATA and CTM_EXTRACT.)

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        SUCCESS = CTM_GET_DATABLOCK(DATA [,DIAGN] [,Keywords])

 INPUTS:
        DIAGN -> A diagnostic number or category name (see
             (CTM_DIAGINFO). This must uniquely identify a
             specific data type.  DIAGN is passed to CTM_GET_DATA


 KEYWORD PARAMETERS:
     Keywords that are passed to CTM_GET_DATA:
     =========================================
        FILENAME   -> Name of the file to open.  FILENAME is passed
                      to CTM_GET_DATA.  CTM_GET_DATA will return
                      the full path name, which is then returned
                      to the calling program.

        USE_FILEINFO -> (optional) If provided, CTM_GET_DATA will 
             restrict its search to only the files that are
             contained in USE_FILEINFO which must be a FILEINFO 
             structure array. Default is to use the global information 
             (see gamap_cmn.pro).
             If an undefined named variable is provided in USE_FILEINFO,
             it will either contain the global FILEINFO structure array 
             or the FILEINFO record of the specified file.
             USE_FILEINFO and USE_DATAINFO must be consistent, and should
             either both be used or omitted. However, it is
             possible to provide the global FILEINFO structure 
             (or nothing) with a local subset of DATAINFO.

        USE_DATAINFO -> (optional) Restrict search to records contained
             in USE_DATAINFO which must be a DATAINFO structure array. 
             If an undefined named variable is provided in USE_DATAINFO,
             it will either contain the global DATAINFO structure array 
             or all DATAINFO records of the specified file.
             See also USE_FILEINFO.

     Keywords that are passed to CTM_EXTRACT:
     ========================================
        AVERAGE -> Bit flag to average over certain dimensions
             (see CTM_EXTRACT)

        TOTAL -> Bit flag to sum over certain dimensions 
             (see CTM_EXTRACT)

        /INDEX -> If set, will interpret LAT, LEV, and LON as index 
             arrays.  If not set, will interpret LAT, LEV, and LON as 
             ranges (i.e. two-element vectors containing min and max values).

        LAT -> An index array of latitudes *OR* a two-element vector 
             specifying the min and max latitudes to be included in
             the extracted data block.  Default is [ -90, 90 ].

        LEV -> An index array of sigma levels *OR* a two-element vector 
             specifying the min and max sigma levels to be included in
             the extracted data block.  Default is [ 1, GRIDINFO.LMX ].

        LON -> An index array of longitudes *OR* a two-element vector 
             specifying the min and max longitudes to be included in
             the extracted data block.  Default is [ -180, 180 ].

        ALTRANGE -> A vector specifying the min and max altitude
             values to be included in the extracted data block.

        PRANGE -> A vector specifying the min and max pressure levels 
             to be included in the extracted data block.

     Other keywords:
     ===============
        XMID, YMID, ZMID -> Arrays of values (e.g. latitude,
             longitude, or altitude) for the 1st, 2nd, and 3rd
             dimensions of the DATA array, respectively.  
             NOTE: These are *NOT* index arrays.

        THISDATAINFO -> Returns the DATAINFO structure for the
             selected data block.

        MODELINFO -> Returns to the calling program the model information 
             structure created by CTM_TYPE.
                      
        GRIDINFO -> Returns to the calling program the grid information  
             structure created by CTM_GRID.

        WE -> Returns to the calling program the index array of longitudes
             for the extracted data region, ordered from west to east.

        SN -> Returns to the calling program the index array of latitudes
             for the extracted data region, ordered from South to North 
 
        UP -> Returns to the calling program the index array of vertical
             levels for the extracted data region, ordered from surface 
             to top.

        PSURF -> Surface pressure to be used for the conversion from
             sigma layers to pressure and altitude.  For defaults 
             see function CTM_TYPE.

       _EXTRA=e -> Picks up any extra keywords for CTM_GET_DATA
              and CTM_EXTRACT.
 
 OUTPUTS:
        SUCCESS -> Returns 1 if successful or 0 otherwise.
 
        DATA -> A 2D or 3D data array

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        CTM_GET_DATA
        CTM_GRID    (function)
        CTM_EXTRACT (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) CTM_GET_DATABLOCK returns the extracted data block as the 
        function value.

        (2) CTM_GET_DATABLOCK is meant to be called whenever you need
        to extract data from a punch file.  If the punch file needs
        to be opened, CTM_GET_DATABLOCK will do that automatically
        (via CTM_GET_DATA).  

 EXAMPLE:
   FILENAME  = '~/amalthea/CTM4/run/ctm.pch'
   LAT       = [  -90,  90 ]
   LON       = [ -180, 180 ]
   LEV       = 1
   SUCCESS   = CTM_GET_DATABLOCK( DATA, 'IJ-AVG-$',                 $
                           XIND=XMID, YIND=YMID, ZIND=ZMID,         $
                           THISDATAINFO=THISDATAINFO,               $
                           TRACER=1,           FILENAME=FILENAME,   $
                           GRIDINFO=GRIDINFO,  MODELINFO=MODELINFO, $
                           LEV=LEV,            LAT=LAT,             $
                           LON=LON,            WE=WE,               $
                           SN=SN,              UP=UP )

   IF ( NOT SUCCESS ) THEN RETURN, 0

            ; gets a data block for the IJ-AVG-$ (ND45) diagnostic,
            ; for the first tracer, at the first timestep, with the 
            ; given latitude, longitude, and sigma level ranges.  
            ; Returns FILEINFO, DATAINFO, THISDATAINFO, WE, SN, UP, 
            ; XMID, YMID, and ZMID to the calling program.

 MODIFICATION HISTORY:
        bmy, 16 Sep 1998: VERSION 1.00
        bmy, 17 Sep 1998: - added FILENAME keyword, so that the file
                            name can be passed back to the calling
                            program. 
        bmy, 18 Sep 1998: VERSION 1.01
                          - now compatible with CTM_EXTRACT v. 1.01
                          - INDEX, SN, WE, UP keywords added
                          - LATRANGE, LONRANGE, LEVRANGE renamed
                            to LAT, LON, LEV (since they may now 
                            contain arrays and not just ranges).
        mgs, 21 Sep 1998: VERSION 1.02
                          - more error checking
                          - added PSurf keywords
                          - frees gridinfo pointer before re-assignment
                          - removed MinData and MaxData
        bmy, 22 Sep 1998: - Now pass AVERAGE and TOTAL keywords to
                            CTM_EXTRACT
        mgs, 22 Sep 1998: - added THISDATAINFO keyword
        bmy, 24 Sep 1998: - added FORWARD_FUNCTION for CTM_GRID
                            and CTM_EXTRACT
        bmy, 08 Oct 1998: VERSION 1.03
                          - FILEINFO and DATAINFO are now keywords
                          - now returns X, Y, and Z as parameters
        bmy, 03 Nov 1998: VERSION 1.04
                          - compatible with new CTM_GET_DATA routine
                          - now pass FILEINFO and DATAINFO structures 
                            via USE_FILEINFO and USE_DATAINFO keywords
        mgs, 10 Nov 1998: - once more adapted to changes in CTM_GET_DATA
                          - now extracts locally used FILEINFO structure
        bmy, 11 Feb 1999: VERSION 1.05
                          - updated comments
        bmy, 19 Feb 1999: - Renamed XIND, YIND, ZIND to XMID, YMID,
                            and ZMID, since these are not index
                            arrays, but the actual longitude,
                            latitude, or altitude values for each
                            dimension of the DATA array.
                          - added DEBUG keyword
                          - eliminate obsolete XARR, YARR, ZARR keywords
                          - added NOPRINT keyword to suppress
                            call to CTM_PRINT_DATAINFO
        mgs, 02 Apr 1999: - replace gridinfo in fileinfo only if new
                            surface pressure is requested. Necessary 
                            for 2D fields (e.g. EPTOMS)
                          - deactivated SMALLCHEM flag
                          - added error checking for FILEINFO
        bmy, 28 Apr 1999: - return THISFILEINFO as a keyword
        mgs, 30 Jun 1999: - Specification of PSURF finally works.
        bmy, 13 Dec 1999: - now use CHKSTRU instead of N_ELEMENTS  
                            to diagnose undefined GRIDINFO structure
        bmy, 04 Dec 2000: GAMAP VERSION 1.47
                          - eliminated obsolete code from 12/31/99
        bmy, 03 Jun 2001: GAMAP VERSION 1.48
                          - bug fix: also create GRIDINFO structure
                            for grids with no vertical layers
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_get_datablock.pro)


CTM_GRID (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 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)


CTM_INDEX

[Previous Routine] [Next Routine] [List of Routines]
 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)


CTM_LABEL (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_LABEL (function)

 PURPOSE:
        Returns strings for several CTM quantities.

 CATEGORY:
        GAMAP Utilities, GAMAP Plotting

 CALLING SEQUENCE:
        RESULT = CTM_LABEL( DATAINFO, MODELINFO [, Keywords ] )

 INPUTS:
        DATAINFO -> Structure returned from CTM_GET_DATA, which
             contains information about one data block
                      
        MODELINFO -> Structure returned from CTM_TYPE, which
             contains information about the particular model 


 KEYWORD PARAMETERS:
        AVERAGE -> Bit flag indicating the dimensions over which
                   to average the data:
                      1 :  longitudinal
                      2 :  latitudinal
                      4 :  vertical
             These values can be combined. E.g., to average over
             longitude and latitude use 3. A bit set in AVERAGE 
             supersedes the corresponding bit in  TOTAL (see below). 

        LAT -> Scalar value or array of latitudes used in the plot.
 
        LON -> Scalar value or array of longitudes used in the plot.
 
        LEV -> Scalar value or array of latitudes used in the plot.

        ALT -> Scalar value or array of altitudes used in the plot.

        PRS -> Scalar value or array of pressures used in the plot.

        TOTAL -> Bit flag indicating the dimensions over which
                 to sum the data:
                      1 :  longitudinal
                      2 :  latitudinal
                      4 :  vertical
             These values can be combined. E.g., to integrate over 
             longitude and latitude use 3. A bit set in AVERAGE 
             supersedes the corresponding bit in TOTAL (see above).


        FORMAT -> Specifies format for converting numeric values into
             string values, for selected fields (such as LAT and LON).
             Default is I14 (strings are trimmed).

        /NO_SPECIAL -> If set, will not place any special superscript
             or subscript characters into the strings returned in
             LABELSTRU.

 OUTPUTS:
        LABELSTRU -> Structure containing the following label fields:
             LAT:        String for latitude(s)     
             LON:        String for longitude(s)
             LEV:        String for vertical level(s)
             ALT:        String for altitude level(s)
             PRS:        String for pressure level(s)
             LATLON:     String that has format "(Lat,Lon)"
             TRACERNAME: String for the tracer name
             SCALE:      String for the tracer's scale factor
             UNIT:       String for the tracer's unit
             TAU0:       String representation of TAU0
             TAU1:       String representation of TAU1
             YMD0:       String representation of (YY)YYMMDD
                           corresponding to TAU0
             YMD1:       String representation of (YY)YYMMDD
                           corresponding to TAU1
             HMS0:       String representation of HHMMSS
                           corresponding to TAU0
             HMS1:       String representation of HHMMSS
                           corresponding to TAU1
             YEAR0:      String for the starting year (e.g. 1994)
             YEAR1:      String for the ending year 
             MONTH0:     String for the starting month name 
                          (e.g. "Jan", "Feb", "Mar", etc..)
             MONTH1:     String for the ending month name
             DAY0:       String for the starting day number (1-31)
             DAY1:       String for the ending day number (1-31)
             DATE:       String for the date (see below)
             MODEL:      String for the model name
             FAMILY      String for the model's family
             RES:        String for the resolution of the model 

 SUBROUTINES:
        External Subroutines Required:
        ==============================================
        CHKSTRU (function)     STRCHEM (function)
        STRSCI  (function)     TAU2YYMMDD (function)
   
 REQUIREMENTS:
        DATAINFO and MODELINFO must be passed to CTM_LABEL.  These
        structures are computed by the GAMAP package subroutines.

 NOTES:
        DATAINFO is created e.g. by CTM_GET_DATA (or CTM_GET_DATABLOCK)
        MODELINFO is created by CTM_TYPE

 EXAMPLE:
        CTM_LABEL, DataInfo, ModelInfo, LabelStru, Lat=10, Lon=48
       
        print, LabelStru.LAT
            'Lat=10!UN!N'       

 MODIFICATION HISTORY:
         bmy, 23 Sep 1998: VERSION 1.00
         bmy, 24 Sep 1998: - now ensure that RES is a scalar string
                           - place TAU2YYMMDD in FORWARD_FUNCTION call
         bmy, 28 Sep 1998: VERSION 1.01
                           - formats for LatStr, LonStr, LevStr
                             changed to be more consistent.
         mgs, 29 Sep 1998: - changed a few comments and fixed bug in 
                             MinLon/MaxLon
         bmy, 03 Nov 1998: - changed NAME to TRACERNAME for
                             the sake of consistency
         bmy, 12 Nov 1998: - added LABELSTRU structure tags: YEAR0,
                             YEAR1, MONTH0, MONTH1, DAY0, DAY1, and DATE
                           - now reports lats as S/N instead of -/+ 
                             and reports lons as W/E instead of -/+
         bmy, 17 Nov 1998: - now use function N_UNIQ to test for
                             the number of unique elements in
                             LAT, LON, LEV, ALT, PRS
                           - Added FORMAT keyword to specify 
                             format for LAT and LON strings
                           - updated comments
         bmy, 15 Jan 1999: - added NO_SPECIAL keyword
         bmy, 17 Feb 1999: - Now add GMT to date string for timeseries
                             animation plots (interval < 1 day)
                           - make sure that HMS0STR and HMS1STR have
                             string lengths of 6 characters
         bmy, 18 Feb 1999: - fix default DATE string for February
         mgs, 16 Mar 1999: - cosmetic changes
                           - removed SUBTRACT_ONE keyword and improved
                             choice of date format
         bmy, 13 Jul 2001: GAMAP VERSION 1.48
                           - Use updated version of STRREPL.PRO from mgs 
         bmy, 07 Nov 2001: GAMAP VERSION 1.49
                           - now use 8-digit YYYYMMDD format for
                             date variables YMD0, YMD1
         bmy, 02 Oct 2002: GAMAP VERSION 1.53
                           - now write GEOS3 instead of GEOS3_30L
         bmy, 05 Nov 2003: GAMAP VERSION 2.01
                           - now write GEOS4 instead of GEOS3_30L
                           - now use the proper time epoch for each
                             model family in call to TAU2YYMMDD
                           - updated comments
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_label.pro)


CTM_LOCATEDIFF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_LOCATEDIFF

 PURPOSE:
        Locates data blocks which differ in two binary
        punch files or GMAO met field files.  

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        CTM_LOCATEDIFF, FILE1, FILE2 [, Keywords ]

 INPUTS:
        FILE1 -> Name of the first file to be tested.  FILE1 may be
             a binary punch file, and ASCII file, or a GMAO met field
             file.

        FILE2 -> Name of the second file to be tested.  FILE2 may be
             a binary punch file, and ASCII file, or a GMAO met field
             file.

 KEYWORD PARAMETERS:
        DIAGN -> A diagnostic category name to restrict the selection
             of data records.

        OUTFILENAME -> Name of the output file which will contain
             the location of differences found between data blocks
             in FILE1 and FILE2.  If OUTFILENAME is not specified,
             then CTM_LOCATEDIFF will print this information to
             the screen.

        /HEADERS_ONLY -> Set this switch to just print the category
             names and tracer numbers where differences occur instead
             of printing all of the data points.

        _EXTRA=e -> Picks up any extra keywords for CTM_GET_DATA.

 OUTPUTS:
        None

 SUBROUTINES:
        External subroutines required:
        ==============================
        CTM_GET_DATA   UNDEFINE
        CTM_DIAGINFO

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS directories.

 NOTES:
        (1) Both FILE1 and FILE2 must contain the same diagnostic 
            categories, listed in the same order.

 EXAMPLE:
        CTM_LOCATEDIFF, 'ctm.bpch.old', 'ctm.bpch.new'

             ; Locates data blocks which differ between ctm.bpch.old
             ; and ctm.bpch.new.  You can investigate these further
             ; with routines CTM_PRINTDIFF and CTM_PLOTDIFF.

 MODIFICATION HISTORY:
        bmy, 24 Feb 2003: VERSION 1.00
        bmy, 19 Nov 2003: GAMAP VERSION 2.01
                          - Now get spacing between diagnostic
                            offsets from CTM_DIAGINFO
        bmy, 27 Feb 2004: GAMAP VERSION 2.02
                          - Rewritten to also print out locations in
                            FORTRAN notation where differences occur
                          - added DIAGN keyword to specify category name
                          - added OUTFILENAME to specify output file
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 01 May 2013: GAMAP VERSION 2.17
                          - Corrected error in EXAMPLE section above

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_locatediff.pro)


CTM_MAKE_DATAINFO (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_MAKE_DATAINFO (function)

 PURPOSE:
        Create a datainfo and fileinfo structure from an
        "external" data set so that it can be used seamlessly
        within the GAMAP package. The dataset can have up to
        four dimensions (however, only the first 3 are currently
        supported). The new datainfo and fileinfo structures 
        will be added to the global structure arrays.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation, Structures

 CALLING SEQUENCE:
        RESULT = CTM_MAKE_DATAINFO( DATA, DATAINFO, FILEINFO  [,Keywords] )

 INPUTS:
        DATA  -> A 1-D, 2-D, or 3-D data array.

 KEYWORD PARAMETERS:
        DIAGN -> A diagnostics name (category) or number that describes
               the data type. If not given, the user will be prompted.
               If DIAGN is a number that is not recognized as valid
               diagnostics by CTM_DIAGINFO, the number will be stored
               as string value. If DIAGN is a string, it does not have 
               to be a valid diagnostics category.

        DIM -> A 4 element vector with the DATA dimensions as
               LON, LAT, LEVEL, TIME. If not given, the dimensions
               of DATA will be entered sequentially. Use this keyword
               to properly identify e.g. a zonal mean data set as
               DIM = [ 0, 46, 20, 0 ] (for the GEOS-1).
               The order and magnitude of the dimensions in DIM must
               agree with the dimensions of the DATA array
               (e.g. if DATA(72,46) then DIM=[46,72,0,0] is not allowed).

        FILENAME-> Name of the file which is specified by the
               FILEINFO structure.  If FILENAME is not specified, 
               then the default FILENAME = "derived data".

        FILETYPE -> A numeric code to identify the file type.  If not
               specified then the default FILETYPE = -1.

        FIRSTBOX -> A 3 element vector containing IFIRST, JFIRST, and
               LFIRST, which are the starting indices for the LON,
               LAT, and LEVEL dimensions.  

        FORMAT -> A format string (for ASCII data) or descriptive
               string (for binary or self-describing data) that is
               saved to the DATAINFO structure.  Default is ''.

        GRIDINFO -> A gridinfo structure describing the grid set-up
               of the data set (see CTM_GRID). If not given, 
               CTM_MAKE_DATAINFO attempts to use the MODELINFO 
               structure to construct GRIDINFO.

        ILUN -> The file unit number that will be used to identify 
               FILEINFO and DATAINFO.  If not passed, then ILUN will
               be negative to denote derived data, and will increment
               negatively for each data block, starting at -1. 

        MODELINFO -> A modelinfo structure containing information
               about the model that generated the data (see CTM_TYPE).
               If not given, the user is prompted for a selection.

        /NO_GLOBAL -> If passed, will prevent the DATAINFO and FILEINFO
               structures from being appended to the global GAMAP
               common blocks.  Useful for saving memory.

        /NO_VERTICAL (passed via _EXTRA) -> set this keyword if you only want
               to create a 2D gridfinfo structure.

        TAU0, TAU1 -> Beginning and end of time interval that is spanned
               by DATA (as TAU value). Default is -1 for both.

        TOPTITLE -> A user defined string that may describe the data set
               in more detail.

        TRACER -> A tracer number or name that identifies the chemical 
               species or physical quantity contained in DATA. If 
               TRACER is an invalid name, it will be set to -1, and the
               string value of TRACER will be used as TRCNAME (see below). 
               If not given, the user will be prompted.

        TRCNAME -> A tracer name. Default is to use the name associated
               with that tracer number in CTM_TRACERINFO.

        SCALE -> A value that is entered in the SCALE field in DATAINFO.
               Default is 1.0.

        UNIT -> A unit string. Default is empty.

 OUTPUTS:
        DATAINFO, FILEINFO -> The datainfo and fileinfo structures
               generated from the "external" data array. These are 
               automatically appended to the global DATAINFO and FILEINFO 
               structures, unless the /NO_GLOBAL keyword is set.

 SUBROUTINES:
        External Subroutines Required:
        =========================================
        CREATE3DHSTRU, CREATE3DFSTRU, TAU2YYMMDD

 REQUIREMENTS:
        None

 NOTES:
        In the current version, no error checking is made whether the
        DATA dimensions agree with the grid information. This is the
        users responsibility. 

 EXAMPLES:
        (1)
        DATA   = DIST(72,46)
        RESULT = CTM_MAKE_DATAINFO( DATA, DATAINFO, FILEINFO )

             ; Create a 2D array and make a DATAINFO structure.
             ; The user will be prompted for model type, 
             ; diagnostics and tracer.
   
        (2)
        RESULT = CTM_MAKE_DATAINFO( DATA, DATAINFO, FILEINFO,        $
            MODEL=CTM_TYPE( 'GEOS1' ), DIAGN='IJ-AVG-$',             $ 
            TRACER=2, TAU0=NYMD2TAU(940901L), TAU1=NYMD2TAU(940930), $
            UNIT='PPBV', DIM=[0,46,20,0],                            $
            TOPTITLE='Zonal mean difference in Ox CLDS/no CLDS')

             ; Add a zonal mean difference data set (already in DATA) 

        (3)
        HELP, DATAINFO, /STRU
           ** Structure H3DSTRU, 13 tags, length=72:
              ILUN            LONG               -15
              FILEPOS         LONG                 0
              CATEGORY        STRING    'ZONE-AVG'
              TRACER          INT              2
              TRACERNAME      STRING    'Ox'
              TAU0            DOUBLE           84720.000
              TAU1            DOUBLE           85416.000
              SCALE           FLOAT           1.00000
              UNIT            STRING    'ppbv'
              FORMAT          STRING    ''
              STATUS          INT              1
              DIM             INT       Array[4]
              OFFSET          INT       Array[3]
              DATA            POINTER   

             ; Display DATAINFO structure

 MODIFICATION HISTORY:
        mgs, 09 Oct 1998: VERSION 1.00
        mgs, 19 Nov 1998: - bug fix. ILUN now always negative!
                          - unit now "required" parameter, i.e.
                            interactively asked for
        bmy, 11 Feb 1999: VERSION 1.01
                          - added OFFSET keyword so that I0, J0, and
                            L0 offsets can be stored in DATAINFO
                          - DATAINFO.TAU0 and DATAINFO.TAU1 are now
                            stored as double precision
                          - updated comments
        mgs, 16 Mar 1999: - cosmetic changes
                          - OFFSET changed into FIRSTBOX
        mgs, 30 Mar 1999: - added _EXTRA keyword for ctm_grid
                            (use for /NO_VERTICAL)
        bmy, 29 Jun 2001: GAMAP VERSION 1.48
                          - bug fix: now pass CTM_TRACERINFO the
                            tracer number plus diagnostic offset
        bmy, 06 Mar 2002: GAMAP VERSION 1.50
                          - now take TRACER mod 100L before 
                            adding the diagnostic offset to it
                            in call to CTM_TRACERINFO
        bmy, 26 Nov 2003: GAMAP VERSION 2.01
                          - added /NO_GLOBAL keyword
                          - rewrote for clarity; updated comments
                          - Now get diagnostic spacing from CTM_DIAGINFO
                          - added ILUN, FILENAME, FILETYPE keywords
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        phs, 30 May 2008: GAMAP VERSION 2.12
                          - Minor fix to restrict FIRSTBOX to 3 elements

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_make_datainfo.pro)


CTM_MAPGRID

[Previous Routine] [Next Routine] [List of Routines]
 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)


CTM_MASS_CHECK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_MASS_CHECK

 PURPOSE:
        Plots the time evolution of % difference of tracer mass and 
        air mass from a CTM simulation.  Used to assess mass
        conservation in CTM transport codes.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        CTM_MASS_CHECK [, Keywords ]

 INPUTS:
        FILENAME -> Name of the CTM output file containing air mass
             and tracer concentrations.  FILENAME can be either an
             ASCII punch file or a BINARY punch file.  If omitted,
             the user will be prompted to supply FILENAME via a 
             dialog box.

 KEYWORD PARAMETERS:
        TRACER -> Number of the tracer that you wish to check for
             mass conservation.

        /PS -> Set this switch to create PostScript plot output.

        OUTFILENAME -> If /PS is set, OUTFILENAME will be the name of
             the PostScript plot output file.  Default is "mass_check.ps".

        _EXTRA=e -> Catches extra keywords for routines OPEN_DEVICE
             and CLOSE_DEVICE.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        CLOSE_DEVICE   CTM_GET_DATA
        MULTIPANEL     OPEN_DEVICE    
        UNDEFINE

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.

 NOTES:
        (1) Assumes that the tracer concentration has been saved
            under the IJ-AVG-$ diagnostic category.  Also assumes 
            that the airmass has been saved under the BXHGHT-$
            diagnostic category.  

 EXAMPLE:
        CTM_MASS_CHECK, 'ctm.bpch.geos4', TRACER=4

            ; Plots the evolution of % difference of both
            ; tracer and air mass for CO from a GEOS-4 simulation.

 MODIFICATION HISTORY:
  bdf & bmy, 26 Jun 2003: GAMAP VERSION 2.03
        bmy, 06 Mar 2007: GAMAP VERSION 2.06
                          - make FILENAME an input rather than
                            a keyword argument.
                          - now pass _EXTRA=e to the PLOT command
                          - Added WINPARAM keyword
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_mass_check.pro)


CTM_NAMEXT

[Previous Routine] [Next Routine] [List of Routines]
 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)


CTM_NOYBUDGET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_NOYBUDGET

 PURPOSE:
        Computes the NOy budget within a given 3-D region.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        CTM_NOYBUDGET [, BATCHFILE [, Keywords ] ]

 INPUTS:
        BATCHFILE (optional) -> Name of the batch file which 
             contains inputs that defines the 3-D region and NOy
             constituents.  If BATCHFILE is omitted, then the user
             will be prompted to supply a file name via a dialog box.

 KEYWORD PARAMETERS:
        LOGFILENAME (optional) -> Name of the log file where output 
             will be sent.  Default is "noy_budget.log".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        --------------------------------------------------------------
        ErrorNOy                       (function)
        TruncateAndWrapForNOy          (function)
        GetNoxEmissionsForNOy          (function)  
        GetHNO3WetDepForNOy            (function)
        GetDryDepositionForNOy         (function)  
        GetNetExportForNOy             (function)
        GetNetChemicalProductionForNOy (function)  
        ReadBatchFileForNOy            (procedure)

        External Subroutines:
        --------------------------------------------------------------
        CTM_Get_Datablock (function)  CTM_BoxSize (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) CTM_NOYBUDGET was developed for use with the GEOS-CTM,
            there might be some adaptation required for use with
            other models.

        (2) Only 5 "families" are considered: 
            Dry Deposition, NOx, PAN, HNO3, R4N2.

        (3) Wrapping around the date line seems to work but you
            should always double-check.

 EXAMPLE:
        CTM_NOYBUDGET, 'box1.dat', LogFileName='box1.log'
           
             ; Computes NOy budgets for the region specified in
             ; the file "box1.dat" and sends output to the 
             ; "box1.log" log file.

 MODIFICATION HISTORY:
        bmy, 28 Jan 2000: VERSION 1.00
                          - adapted original code from Isabelle Bey
        bmy, 25 May 2000: VERSION 1.45
                          - now allow the user to specify diagnostic
                            category names in the batch file
                          - added internal function "TruncateAndWrapForNOy"
                            to wrap arrays around the date line
                          - added internal procedure "ErrorNOy"
                            to do error checking for CTM_GET_DATABLOCK
                          - now can create budgets for more than one
                            diagnostic interval
                          - now allow user not to compute chemical 
                            production data for given families
        acs, 26 May 2000: - bug fixes: now do not stop the run if 
                            data blocks are not found
        bmy, 01 Aug 2000: VERSION 1.46
                          - use abs( Total( X ) ) > 0 when testing if 
                            transport fluxes are all nonzero
        bmy, 24 Jan 2001: GAMAP VERSION 1.47
                          - now no longer require all types of emissions
                            to be nonzero in order to sum them
                          - now no longer require both HNO3 LS and
                            convective wetdep to be zero in order to 
                            sum them
        bmy, 17 Jan 2002: GAMAP VERSION 1.50
                          - now call STRBREAK wrapper routine from
                            the TOOLS subdirectory for backwards
                            compatiblity for string-splitting
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_noybudget.pro)


CTM_OPEN_FILE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_OPEN_FILE

 PURPOSE:
        Open a CTM output (punch) file and reads the complete
        header information from that file. The file may be either
        ASCII or binary type, and is only opened if not already 
        parsed. It is re-opened if it was parsed but closed in the 
        meantime. CTM_OPEN_FILE can also be used to read GEOS-CTM
        restart files. However, since it is not possible to
        point randomly at these data, the complete set of tracers
        in a restart file will be read at once.
        
        While in general files are opened automatically when 
        CTM_GET_DATA is used, there are several circumstances where
        direct use of CTM_OPEN_FILE advantageous:
        * if a read error occurs, use CTM_OPEN_FILE with the /PRINT
          keyword to diagnose the error
        * to compare two model runs, it is simpler to first open
          the two files, then call CTM_GET_DATA without the filename
          keyword. All operations will then be done on both files
          in parallel.

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        CTM_OPEN_FILE, FILENAME, THISFILEINFO, THISDATAINFO

 INPUTS:
        FILENAME -> The name of the file to be opened or a
            file mask. If the file was not found or the file 
            mask contains wild cards, a pickfile dialog is
            opened for interactive selection. The default
            search mask can be set in gamap.defaults (see
            GAMAP_INIT).

 KEYWORD PARAMETERS:
        CANCELLED -> Returns 1 if the CANCEL button was pressed
            during DIALOG PICKFILE filename selection.
 
        _EXTRA keywords are passed to the various routines which
            read the file headers.  

 OUTPUTS:
        THISFILEINFO -> A named variable that will contain a 
            fileinfo structure (see CREATE3DFSTRU).

        THISDATAINFO -> A named variable that will contain an
            array of datainfo structures (see CREATE3DHSTRU)
            associated with this file.

        THISFILEINFO and THISDATAINFO are also appended to the 
        global pointer variables pGlobalFileInfo and pGlobalDataInfo
        (see gamap_cmn.pro and GAMAP_INIT).

 SUBROUTINES:
        Internal Subroutines:
        ============================================================
        Get_Free_Lun  (function)   Test_For_NCDF          (function)
        Test_For_HDF  (function)   Test_For_HDFEOS        (function)
        Test_For_GMAO (function)   Test_For_Binary        (function)
        File_Parse    (function)   File_Opened_Previously (function)
        Handle_Prev_Opened_File

        External Subroutines Required:
        ==============================================================
        GAMAP_CMN          (incl file)  OPEN_FILE
        CTM_READ3DB_HEADER (function )  CTM_READ3DB_HEADER (function)
        CTM_READ_GMAO      (function )  CTM_READ_NCDF      (function) 
        CTM_READ_GMI       (function )  LITTLE_ENDIAN      (function)
        STRRIGHT           (function )

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.

 NOTES:
        (1) In internal function "test_for_dao", add additional met 
        field names as is necessary to the FIELDNAMES array.  The
        first met field name in a file is tested against FIELDNAMES.
        If there is a match, then the file is declared to be a DAO 
        met field file, and it is assigned a file type of 4.

        (2) You must also add additional met field names to routine
        "ctm_read_dao" as is necessary.  The DAO met field files do 
        not carry tracer numbers, so the name of each met field must
        be checked in "ctm_read_dao" before a corresponding DATAINFO
        structure can be assigned.

        (3) If a binary file is the wrong endian, we will get a
        "Corrupted F77 file error" when we try to read data from it.
        We now test for this error in routines TEST_FOR_BINARY and
        TEST_FOR_DAO.  If this error condition occurs, the file is
        re-opened with the /SWAP_ENDIAN command.

 EXAMPLE:
        CTM_OPEN_FILE
        ; queries the user for a filename and stores the analyzed
        ; header information in the global common block
        ; If an ASCII punch file is read, the user is prompted for
        ; a model name

        CTM_OPEN_FILE,'',fileinfo,datainfo
        ; opens a CTM punch file after selection from a pickfile
        ; dialog

        CTM_OPEN_FILE,'~/amalthea/CTM4/run/ctm.pch',fileinfo,datainfo
        ; opens the specified punch file

 MODIFICATION HISTORY:
        mgs, 14 Aug 1998: VERSION 1.00
        mgs, 17 Sep 1998: - file units now starting from 20, so
                            they do not interfere with GET_LUN
        mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
        mgs, 05 Oct 1998: - added function file_parse
                          - can now handle GEOS restart files as well.
        mgs, 10 Nov 1998: - no message after Cancel on Pickfile dialog
        bmy, 20 Jan 1999: - explicitly set binary type to 2 for 
                            GEOS-CTM restart files
                          - accept bey's personal GEOS CTM timeseries label
        mgs, 19 May 1999: - added SWAP_ENDIAN keyword to open_file if
                            binary files are read on PC
        mgs, 24 May 1999: - added support for 'CTM bin 02' files
                            (involved changing filetype numbers)
        bmy, 12 Apr 2000: GAMAP VERSION 1.45
                          - added test for DAO binary met field files
        bmy, 12 Jun 2000: - added CLDFRC to list of recognized DAO fields
        bmy, 28 Jul 2000: GAMAP VERSION 1.46
                          - added GEOS-3 names to list of recognized fields
                          - deleted a couple of field names woe don't use
        bmy, 25 Sep 2000: - added new field: SLP (sea level pressure)
        bmy, 05 Dec 2000: GAMAP VERSION 1.47
                          - added new fields: TKE, RH, KH
        bmy, 07 Mar 2001: - added new fields: CLDTMP, TPW
        bmy, 25 Apr 2001: - added new fields: TAULOW, TAUMID, TAUHI
        bmy, 26 Jul 2001: GAMAP VERSION 1.48
                          - added new field: T2M
        bmy, 15 Aug 2001: - added new field: OPTDEPTH
        bmy, 27 Sep 2001: GAMAP VERSION 1.49
                          - reference LITTLE_ENDIAN in internal
                            subroutine "handle_prev_opened_file"
                          - swap endian if LITTLE_ENDIAN() returns true
                            in internal subroutine "handle_prev_opened_file"
        bmy, 29 Jan 2002: GAMAP VERSION 1.50
                          - added new field: GWET
        bmy, 03 Mar 2003: GAMAP VERSION 1.52:
                          - added new fvDAS fields: CMFDTR, CMFETR,
                            ZMDU, ZMED, ZMEU, ZMMD, ZMMU, HKETA, HKBETA
        bmy, 18 Jun 2003: GAMAP VERSION 1.53
                          - added new fields: EVAP, LAI, PARDF, PARDR
        bmy, 30 Jul 2003: - added new field: TSKIN
  lyj & tdf, 22 Oct 2003: - added SWAP_BINARY keyword to TEST_FOR_BINARY
                          - Call TEST_FOR_BINARY with /SWAP_BINARY
                            as a last-ditch effort if the file type
                            cannot be classified.  This will open the
                            file and swap the endian.
        bmy, 12 Dec 2003: GAMAP VERSION 2.01
                          - Now also test for netCDF file format
                          - Added internal routines TEST_FOR_NETCDF,
                            TEST_FOR_HDF (stub), TEST_FOR_HDFEOS
                          - FILETYPE for ASCII   files range from 0-99
                          - FILETYPE for BINARY  files range from 100-199
                          - FILETYPE for netCDF  files range from 200-299
                          - FILETYPE for HDF-EOS files range from 300-399
                          - Routine TEST_FOR_GMAO now looks for met
                            field tracer names from "tracerinfo.dat",
                            instead of using a hardwired string array
                          - rewritten for clarity; updated comments
                          - Now looks for the GEOS-4 met field ident string
        bmy, 11 Feb 2004: GAMAP VERSION 2.01a
                          - Now prevents infinite loops when testing
                            for file type
        bmy, 24 Aug 2004: GAMAP VERSION 2.03
                          - now recognizes GEOS-CHEM station timeseries
                            file in bpch file format by the FTI string
        bmy, 21 Mar 2005: - Added COARDS-compliant netCDF as FILETYPE=203
        bmy, 24 May 2005: GAMAP VERSION 2.04
                          - Now test properly for GCAP met fields
        bmy, 06 Feb 2006: - Activate file type tests for HDF-EOS4 
                            swath and point file types
                          - Add new function TEST_FOR_HDF5 to test if
                            the file is in HDF5 format
                          - Use the absolute path name internally when
                            testing for HDF5 or HDF-EOS files
        bmy, 31 May 2006: GAMAP VERSION 2.05
                          - Now expand the filename when calling NCDF_OPEN
                          - Skip test for HDF5 for IDL versions
                            earlier than 6.0
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now modified for GEOS-5
                          - Added FILETYPE=106 for files that
                            contain 4-D data blocks
                          - Use FILETYPE=202 for netCDF files
                            created by BPCH2GMI
        phs, 30 Jun 2008: GAMAP VERSION 2.12
                          - warning if too many files are opened
                          - completly rewrite handling of endian swapping
        bmy, 23 Jan 2017: GAMAP VERSION 2.19
                          - Add a better test for netCDF files.  This
                            removes the restriction of the file having
                            to end with *.nc or *.nc4.
               

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_open_file.pro)


CTM_OVERLAY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_OVERLAY

 PURPOSE:
        Calls TVMAP to plot a pixel or contour map and then overplots 
        either an aircraft flight track or individual station data 
        atop it.

 CATEGORY:
        GAMAP Utilities, GAMAP Plotting

 CALLING SEQUENCE:
        CTM_OVERLAY, DATA,   XMID,   YMID, $
                     TRACKD, TRACKX, TRACKY [, Keywords ]

 INPUTS:
        DATA -> Data array (e.g. from CTM_GET_DATA or CTM_GET_DATABLOCK)
             from which a pixel plot or contour plot will be generated.

        XMID -> Vector of longitudes corresponding to DATA.

        YMID -> Vector of latitudes corresponding to DATA

        TRACKD -> Vector of data values corresponding to the aircraft
             flight track or station data points.

        TRACKX -> Vector of longitudes corresponding to the aircraft 
             flight track or station data points.  Should be in the 
             range [-180,180].

        TRACKY -> Vector of longitudes corresponding to the aircraft
             flight track or station data points.  Should be in the 
             range [-90,90].

 KEYWORD PARAMETERS:
        C_COLORS -> Vector to specify the color levels for filled
             contour plots.  If not passed, then C_COLORS will return
             to the calling program the default color level values
             generated internally by TVMAP.
 
        C_LEVELS -> Vector containing contour levels for filled
             contour plots.  Used in conjunction with /FCONTOUR. 

        COLOR -> Color of the map outline.  Passed to TVMAP.

        /FCONTOUR -> Set this switch to generate a filled-contour
             plot instead of a pixel plot.

        /LOG -> Set this switch to use a logarithmic color table.

        MINDATA -> Minimum value of DATA.  If omitted, then MINDATA
             will be automatically set to the minimum value of DATA.

        MAXDATA -> Minimum value of DATA.  If omitted, then MINDATA
             will be automatically set to the minimum value of DATA.

        /OVERPLOT -> Set this keyword to overplot a flight track
             atop a map previously drawn by TVMAP.

        T_COLOR -> (1) If plotting aircraft flight track data, then
             T_COLOR will be used to define the color of the line.
             (2) If plotting symbol data, then T_COLOR will be used to
             describe the color of the border around the symbol.  
             To suppress printing a border around the symbol, use
             any negative value for T_COLOR (e.g. T_COLOR = -1).

        T_LINESTYLE -> IDL linestyle for the aircraft flight track.
             Takes same values as the LINESTYLE graphic keyword
             (see help pages).

        T_SYMBOL -> Argument to the SYM keyword, which will be used
             to define the individual data points if you are plotting
             station data.  Recommended value: 1 (filled circle).

        T_THICK -> Thickness of the aircraft flight track, in pixels.
 
        _EXTRA=e -> Passes extra keywords to TVMAP and OPLOT.

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        ==========================================
        SCALETRACK (function)

        External Subroutines Required:
        =========================================
        MULTIPANEL      MYCT_DEFAULTS (function) 
        TVMAP           RECTANGLE
        SYM (function)

 REQUIREMENTS:
        None

 NOTES:
        You can pass all of the same keywords to CTM_OVERLAY_FLIGHT
        as you do to TVMAP.    

 EXAMPLE:
        (1) Plot flight tracks atop a pixel or contour map
        --------------------------------------------------

        ; Read the data -- in this case, CO concentrations
        SUCCESS = CTM_Get_DataBlock( Data, 'IJ-AVG-$',     $
                                     File='ctm.bpch.1995', $
                                     Tra=4,                $
                                     /First,               $
                                     Lon=[-180, 180],      $
                                     Lat=[-88,   88],      $
                                     Lev=1,                $
                                     XMid=XXmid, Ymid=YYMid )
         
        
        ; Make a "fake" aircraft track
        ; Here we'll use MAP_2POINTS to create a "fake" flight 
        ; track of constant longitude (30 deg E meridian)
        nPts   = 101
        a      = MAP_2POINTS( 30, -90, 30, 90, NPATH=NPTS )
        TrackX = A[0,*]
        TrackY = A[1,*]
        TrackD = FltArr( nPts )                  
               
        ; Plot a pixel map w/ countries, continents, grid lines,
        ; and overlay a red, dashed-line flight track atop it.
        CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
           /Sample,    /Countries,    /Coasts,    /CBar,         $      
           Div=4,      Min_Val=1e-20, /Isotropic, /Grid,         $ 
           Title='Pixel map overlaid /w contour map',            $    
           T_Color=!MYCT.RED, T_Thick=2, T_LineStyle=2
         
        ; Make a second "fake" aircraft track
        ; (of course, if you have a real flight track, use it...)
        TrackX = Replicate( 72, 100 )
        TrackY = Findgen( 100 ) - 50
        TrackD = Fltarr( 100 )
         
        ; Call CTM_OVERLAY again with /OVERPLOT to 
        ; overplot the second flight track
        CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
           T_Color=!MYCT.BLUE, T_Thick=2, T_LineStyle=2, /OVERPLOT


       (2) Draw Boxes for Tagged Tracer regions
       ----------------------------------------

       ; Define (X,Y) coordinates of first tagged tracer region
       TrackX = [ 0, 60, 60,  0, 0 ]
       TrackY = [ 0,  0, 30, 30, 0 ]
       TrackD = [ 0,  0,  0,  0, 0 ]
    
       ; Call CTM_OVERLAY with all TVMAP keywords to
       ; plot the map and to initialize the map dataspace
       CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
          /Sample,    /Countries,    /Coasts,    /CBar,         $      
          Div=4,      Min_Val=1e-20, /Isotropic, /Grid,         $       
          Title='Test pixel map w/ overlay boxes',              $
          T_Thick=3,  T_Color=!MYCT.BLACK,  T_LineStyle=0
    
       ; Define second tagged tracer region
       TrackX = [ 0, 120, 120,   0, 0 ]
       TrackY = [ 0,   0, -30, -30, 0 ]
          
       ; Call CTM_OVERLAY with /OVERPLOT to overplot
       ; atop the previously defined map
       CTM_OverLay, Data, XXMid, YYMid, TrackX, TrackY, $
          /OVERPLOT, T_Thick=3, T_Color=!MYCT.RED, T_LineStyle=0


       (3) Plot individual station data points
       ----------------------------------------

       ; Define "fake" station data for demo
       ; (along the equator between 60W and 60E)
       Ind    = Where( XMid ge -60 AND XMid le 60, N )
       TrackD = Findgen(N) + 20
       TrackY = Fltarr(N)  + 0
       TrackX = Xmid[Ind]

       ; Call CTM_OVERLAY with all TVMAP keywords to
       ; plot the map and to initialize the map dataspace
       CTM_OverLay, Data, XXMid, YYMid, TrackD, TrackX, TrackY, $
          /Sample,    /Countries,    /Coasts,    /CBar,         $      
          Div=4,      Min_Val=1e-20, /Isotropic, /Grid,         $      
          T_Symbol=1, SymSize=2,                                $
          Title='Test pixel map w/ station data',           
         

 MODIFICATION HISTORY:
        bmy, 05 Oct 2006: GAMAP VERSION 2.05
                          - Modified from CTM_OVERLAY_FLIGHT and
                            renamed to CTM_OVERLAY
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
  dbm & bmy, 06 Nov 2007: - Modified to allow filled contour plots
  cdh & bmy, 18 Feb 2009: GAMAP VERSION 2.13
                          - Now pass LOG=LOG to TVMAP call to ensure
                            that TVMAP gets the /LOG keyword OK
  bmy & cph, 14 Jan 2010: GAMAP VERSION 2.14
                          - Remove the call to the PLOT command after
                            TVMAP. This does set up the approropriate
                            coordinates for map projections other
                            than /CYLINDRICAL.
                          - Now use PLOTS to plot symbols or lines
                            rather than OPLOT.
                          - Updated comments
        cdh, 24 Feb 2010: - Added /NOADVANCE keyword
        bmy, 06 Aug 2010: GAMAP VERSION 2.14
                          - Now set default values for C_COLORS
                            for filled contour plots if not specified
   bf & bmy, 18 Oct 2010: - Bug fix submitted by Bonne Ford to allow
                            more than one overlay on the same plot
        bmy, 10 Feb 2016: GAMAP VERSION 2.19
                          - If plotting symbols, suppress symbol borders
                            if T_COLOR is negative (e.g. T_COLOR=-1).
                          - Now require adding /NOADVANCE before each 
                            successive call to CTM_OVERLAY with /OVERPLOT

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_overlay.pro)


CTM_OVERLAY_WIND

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_OVERLAY_WIND

 PURPOSE:
        Calls TVMAP to plot a pixel or contour map and then overplots 
        wind data atop it.
        %%%% NOTE: Still in BETA testing! %%%%

 CATEGORY:
        GAMAP Utilities, GAMAP Plotting

 CALLING SEQUENCE:
        CTM_OVERLAY, DATA, XMID, YMID, U, V, [, Keywords ]

 INPUTS:
        DATA -> Data array (e.g. from CTM_GET_DATA or CTM_GET_DATABLOCK)
             from which a pixel plot or contour plot will be generated.

        XMID -> Vector of longitudes corresponding to DATA.

        YMID -> Vector of latitudes corresponding to DATA

        U -> Array of U-wind values

        V -> Array of V-wind values

 KEYWORD PARAMETERS:
        COLOR -> Color of the map outline.  Passed to TVMAP.

        /LOG -> Set this switch to use a logarithmic color table.

        MINDATA -> Minimum value of DATA.  If omitted, then MINDATA
             will be automatically set to the minimum value of DATA.

        MAXDATA -> Minimum value of DATA.  If omitted, then MINDATA
             will be automatically set to the minimum value of DATA.

        /OVERPLOT -> Set this keyword to overplot the wind
             atop a map previously drawn by TVMAP.
 
        _EXTRA=e -> Passes extra keywords to TVMAP and VELOCITY_FIELD.

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        ==========================================
        SCALETRACK (function)

        External Subroutines Required
        =========================================
        MULTIPANEL      MYCT_DEFAULTS (function) 
        TVMAP           RECTANGLE
        SYM (function)

 REQUIREMENTS:
        Uses routines from both GAMAP and TOOLS packages.

 NOTES:
        You can pass all of the same keywords to CTM_OVERLAY_FLIGHT
        as you do to TVMAP.    

 EXAMPLE:
        (1) Plot flight tracks atop a pixel or contour map
        --------------------------------------------------

        ; Read the data -- in this case, CO concentrations
        SUCCESS = CTM_Get_DataBlock( Data, 'IJ-AVG-$',     $
                                     File='ctm.bpch.1995', $
                                     Tra=4,                $
                                     /First,               $
                                     Lon=[-180, 180],      $
                                     Lat=[-88,   88],      $
                                     Lev=1,                $
                                     XMid=XXmid, Ymid=YYMid )
         

        ; Make a "fake" wind [TO DOCUMENT]
         

 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        phs, 20 Mar 2008: GAMAP VERSION 2.12
                          - cleanup, updated for new TVMAP
                          - now pass Map Position to velocity_field

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_overlay_wind.pro)


CTM_OXBUDGET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_OXBUDGET

 PURPOSE:
        Computes the Ox budget within a given 3-D region.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        CTM_OXBUDGET [, BATCHFILE [, Keywords ] ]

 INPUTS:
        BATCHFILE (optional) -> Name of the batch file which 
             contains inputs that defines the 3-D region and NOy
             constituents.  If BATCHFILE is omitted, then the user
             will be prompted to supply a file name via a dialog box.

 KEYWORD PARAMETERS:
        LOGFILENAME (optional) -> Name of the log file where output 
             will be sent.  Default is "ox_budget.log".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        --------------------------------------------------------------
        ErrorOx                       (function)
        TruncateAndWrapForOx          (function)
        GetHNO3WetDepForOx            (function)             
        GetDryDepositionForOx         (function)  
        GetNetChemicalProductionForOx (function)  
        GetNetExportForOx             (function)
        ReadBatchFileForOx            (procedure)

        External Subroutines Required:
        --------------------------------------------------------------
        CTM_Get_Datablock (function)  CTM_BoxSize (function)

 REQUIREMENTS:
 

 NOTES:
        (1) CTM_OXBUDGET was developed for use with the GEOS-CTM,
            there might be some adaptation required for use with
            other models.  

        (2) Only 2 "families" are considered: Dry Deposition and Ox.

        (3) Wrapping around the date line seems to work but you
            should always double-check.

        (4) Currently, the box of consideration must be less than
            global size in order to m
       
 EXAMPLE:
        CTM_OXBUDGET, 'box1.ox', LogFileName='box1.log'
           
             ; Computes Ox budgets for the region specified in
             ; the file "box1.ox" and sends output to the 
             ; "box1.log" log file.

 MODIFICATION HISTORY:
        bmy, 28 Jan 2000: VERSION 1.00
                          - adapted original code from Isabelle Bey
        bmy, 25 May 2000: GAMAP VERSION 1.45
                          - now allow the user to specify diagnostic
                            category names in the batch file
                          - added internal function "TruncateAndWrapForOx"
                            to wrap arrays around the date line
                          - added internal procedure "ErrorOx"
                            to do error checking for CTM_GET_DATABLOCK
                          - now can create budgets for more than one
                            diagnostic interval  
                          - now allow user not to compute chemical 
                            production data for given families
        acs, 26 May 2000: - bug fixes: now do not stop the run if 
                            data blocks are not found.  
        bmy, 01 Aug 2000: GAMAP VERSION 1.46
                          - use abs( Total( X ) ) > 0 when testing if 
                            transport fluxes are all nonzero
        bmy, 13 Dec 2001: GAMAP VERSION 1.49
                          - Now do not require all transport fluxes
                            to be nonzero in order to compute budgets
                          - now truncate data blocks correctly for
                            E/W and N/S transport fluxes
                          - Now compute the total number of seconds
                            over the entire diagnostic interval
                          - Now divide fluxes by the number of diagnostic
                            time intervals in order to get average fluxes
        bmy, 17 Jan 2002: GAMAP VERSION 1.50
                          - now call STRBREAK wrapper routine from
                            the TOOLS subdirectory for backwards
                            compatiblity for string-splitting;
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 23 Mar 2008: GAMAP VERSION 2.12
        phs, 20 Aug 2008: GAMAP VERSION 2.13
                          - now 3D region can be as small as one box.

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_oxbudget.pro)


CTM_PLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_PLOT

 PURPOSE:
        General plotting tool for CTM data that is stored in the 
        GAMAP datainfo and fileinfo structures. CTM_PLOT can 
        handle everything from 0-D to 3-D and has many different
        plot options, especially for 2-D plots for which it was
        originally designed. E.g. full map support.

 CATEGORY:
        GAMAP Utilities, GAMAP Plotting

 CALLING SEQUENCE:
        CTM_PLOT, [ Diagn [ [ ,Keywords ] ] 

 INPUTS:
        DIAGN -> The diagnostic number (e.g. ND22, ND45, etc or 
             category name (e.g. "JV-MAP", "IJ-AVG") for which to 
             read data from the punch file. 

 KEYWORD PARAMETERS:
    Keyword parameters passed to CTM_GET_DATABLOCK:
    ===============================================
        FILENAME -> Name of the punch file to read data from.  
             FILENAME is passed to CTM_GET_DATABLOCK.  You can also
             use a file mask, in which case FILENAME will return the 
             full filename if it is a named variable. If an empty 
             filename is provided, the default search mask from 
             gamap.defaults (see gamap.cmn) will be used. If no 
             filename is given, ctm_plot will try 
             to find the records from data already loaded.

        TRACER -> Number of tracer to read from the punch file.

        TAU0, /FIRST, /LAST -> time step to be plotted

        LON -> If /INDEX is set, LON denotes the CTM longitude index
             of the box to plot.  Otherwise, LON denotes the actual
             longitude value of that box. (that is at box CENTER, phs
             4/2/08)

        LAT -> If /INDEX is set, LAT denotes the CTM latitude index
             of the box to plot.  Otherwise, LAT denotes the actual
             latitude value of that box. (that is at box CENTER, phs
             4/2/08)

        LEV -> An index array of sigma levels *OR* a two-element
             vector specifying the min and max sigma levels to be 
             included in the plot.  Default is [ 1, GRIDINFO.LMX ].
 
        ALTRANGE -> A vector specifying the min and max altitude
             values to be included in the extracted data block.

        PRANGE -> A vector specifying the min and max pressure 
             levels to be included in the extracted data block.

        /INDEX -> If set, will interpret LAT, LEV, and LON as CTM 
             indices.  If not set, will interpret LAT, LEV, and LON
             as the actual values of latitude, level, and longitude.
             NOTE: If /INDEX is set, then GAMAP cannot create plots
             for longitude ranges that span the date line!!!

        AVERAGE -> If = 0, will not average the data 
                      = 1, will average data longitudinally
                      = 2, will average data latitudinally
                      = 4, will average data vertically
             These are cumulative (e.g. AVERAGE=3 will average over 
             both lat and lon, and AVERAGE=7 will average over lat,
             lon, and vertical levels to produce 1 data point).
                       
        TOTAL -> If = 0, will not total data
                    = 1, will total data longitudinally
                    = 2, will total data latitudinally
                    = 4, will total data vertically
             These are cumulative (e.g. TOTAL=3 will total over both 
             lat and lon, and TOTAL=7 will total over lat, lon, and 
             vertical levels to produce 1 data point).

        USE_FILEINFO -> (optional) If provided, CTM_GET_DATABLOCK will 
             restrict its search to only the files that are
             contained in USE_FILEINFO which must be a FILEINFO 
             structure array. Default is to use the global information 
             (see gamap_cmn.pro).
             If an undefined named variable is provided in USE_FILEINFO,
             it will either contain the global FILEINFO structure array 
             or the FILEINFO record of the specified file.
             USE_FILEINFO and USE_DATAINFO must be consistent, and should
             either both be used or omitted. However, it is
             possible to provide the global FILEINFO structure 
             (or nothing) with a local subset of DATAINFO.

        USE_DATAINFO -> (optional) Restrict search to records contained
             in USE_DATAINFO which must be a DATAINFO structure array. 
             If an undefined named variable is provided in USE_DATAINFO,
             it will either contain the global DATAINFO structure array 
             or all DATAINFO records of the specified file.
             See also USE_FILEINFO.

    Keywords passed to CTM_CONVERT_UNIT:
    ====================================
        UNIT -> Name of the unit that the DATA array will be converted
             to. If not specified, then no unit conversion will be done.

    Keywords passed to TVMAP or TVPLOT:
    ===================================
        NOERASE -> Do not erase previous plot.
 
        POSITION -> A four-element array of normalized coordinates
             that specifies the location of map on the plot. POSITION
             has the same form as the POSITION keyword on a plot. 
             Default is [0.1, 0.05, 0.9, 0.08]. (Passed to TVMAP).

        NCOLORS -> This is the maximum color index that will be used.

        BOTTOM -> The lowest color index of the colors to be loaded
             used in the color map and color bar.

        /NOCBAR -> If set, will not plot the colorbar below the map
             in the position specified by CBPOSITION.  Default is to
             plot a colorbar.

        CBCOLOR -> Color index of the colorbar outline and
             characters.  Defaults to BLACK (from colors_default.pro).

        CBPOSITION -> A four-element array of normalized coordinates
             that specifies the location of the colorbar. BARPOSITION 
             has the same form as the POSITION keyword on a plot. 
             Default is [0.1, 0.05, 0.9, 0.08]. 

        CBUNIT -> Passes the Unit string to COLORBAR, which will be
             plotted to the right of the color bar.  NOTE: For black
             & white contour plots, the string specified by CBUNIT
             will be plotted below the X-axis.  

        CBFORMAT -> format to use in call to colorbar. Default is I12
             if abs(max(data)) < 1e4, else e12.2 (strings get trimmed)

        COLOR  -> Color index of the map outline and title characters.  
             Defaults to BLACK (from colors_default.pro). Also used as
             plot color for 1-D (line) plots.

        MPARAM -> A 3 element vector containing values for
             [ P0Lat, P0Lon, Rot ].  Default is [ 0, 0, 0 ].

        POSITION -> A four-element array of normalized coordinates
             that specifies the location of the map.  POSITION has
             the same form as the POSITION keyword on a plot. 
             Default is [0.1, 0.1, 0.9, 0.9]. 

        TITLE -> The title string that is to be placed atop the
             map window.  

        /NOCONTINENTS -> If set, will suppress adding continent lines
             to the map.  Default is to call MAP_CONTINENTS to plot
             continent outlines or filled boundaries.

        CCOLOR -> The color index of the continent outline or fill 
             region.  Default is BLACK (from colors_default.pro).
 
        CFILL -> Value passed to FILL_CONTINENTS keyword of
             MAP_CONTINENTS.  If CFILL=1 then will fill continents
             with a solid color (as specified in CCOLOR above).  
             If CFILL=2 then will fill continents with hatching.

        /NOGRID -> If set, will suppress printing of grid lines.
             Default is to call MAP_GRID to overlay grid lines.
 
        GCOLOR -> The color index of the grid lines.
             Default is BLACK (from colors_default.pro)

        /NOGLABELS -> Will suppres printing of labels for each grid
             line in TVMAP.PRO.  Default is to print grid labels
             for each grid line.

        /NOISOTROPIC -> Will suppress plotting of an isotropic map
             (i.e. one with the same X and Y scale).  Default is to 
             print an isotropic map.
  
        /CONTOUR -> Will produce a line-contour map instead of the 
             default color-pixel image map.

        /FCONTOUR -> Will produce a filled contour map instead
             of the default color-pixel image map. If you find
             that one or more color bands are not filled properly, 
             try the /CELL_FILL keyword. This is a known IDL precularity.

        C_LEVELS -> Vector containing the contour levels.  If not
             specified, TVMAP will use quasi-logarithmic levels.

        C_COLORS -> Index array of color levels for each line (or
             each fill section) of the contour map.  If not
             specified, TVMAP will select default colors from the 
             colortable.

        C_ANNOTATION -> Vector containing the contour labels.
             Default is to use string representations of C_LEVELS.

        C_FORMAT -> Format string used in converting C_LEVELS to
             the default C_ANNOTATION values.  Default is '(f8.1)'.

        C_LABELS -> Specifies which contour levels should be labeled.
             By default, every other contour level is labeled.  C_LABELS 
             allows you to override this default and explicitly
             specify the levels to label. This parameter is a vector, 
             converted to integer type if necessary.  If the LEVELS 
             keyword is specified, the elements of C_LABELS
             correspond directly to the levels specified, otherwise, 
             they correspond to the default levels chosen by the 
             CONTOUR procedure. Setting an element of the vector to 
             zero causes that contour label to not be labeled.  A
             nonzero value forces labeling. 

             NOTE: If C_LABELS is given as a scalar, then it will be
             expanded to a vector with all elements having the same value.

        /C_LINES -> Will overplot a filled-contour map with contour lines
             and labels instead of plotting a colorbar. This was the old
             default behaviour but has been changed with the advent of
             "discrete" colorbars. The old NOLINES keyword is kept
             for compatibility reasons but doesn't do anything.

        /NOLABELS -> Will suppress printing contour labels on both
             line-contour and filled-contour maps.

        OVERLAYCOLOR -> Color of the solid lines that will be
             overlaid atop a filled contour map.  Default is BLACK.

        /OVERPLOT -> Add an additional line plot to an existing one.
             You should specify LINE=n and/or COLOR=n to distinguish 
             between curves in this case. You can manually add a legend
             with legend.pro after the plot(s) are produced.
             Note that the title string will contain information on 
             your first selection only. Use an explicit TITLE for 
             best results.

        /SAMPLE -> Will cause REBIN (in TVMAP) to use nearest-
             neighbor sampling rather than bilinear interpolation.

        /LOG -> Will create a color-pixel plot with logarithmic
             scaling.  /LOG has no effect on line-contour or
             filled-contour plots, since the default contour levels
             are quasi-logarithmic.

        /POLAR -> Create a polar plot. Note that the longitude range must 
             be -180..180 and the latitude range must extend to one pole
             but not straddle the equator.


    Keywords passed to ISOPLETH_MAP:
    ================================
        ISOPLETH -> Value for which a 3-D isosurface will be computed.
             ISOPLETH_MAP assigns a default value of 35.0.  


    Other Keywords:
    ===============
        USTR -> Unit string to be plotted to the right of the colorbar.  
             If not specified, then CTM_PLOT  will construct a unit 
             string based on the value of TRACERINFO.UNIT.
             NOTE: USTR is a synonym for the keyword CBUNIT, which
             specifies the color bar unit string.

        THISDATAINFO -> Returns to the calling program the THISDATAINFO
             structure obtained by CTM_GET_DATABLOCK.

        LABELSTRU -> Returns to the calling program the structure
             of label information obtained by CTM_LABEL.
 
        YRANGE -> range of y values for color scaling (default:
             scale each plot seperately with data min and max)

        X_FORMAT, Y_FORMAT (optional) -> Specifies the format string
             (e.g. '(f10.3)', '(e14.2)' ) for the X and Y axes, when
             making line plots.  If omitted, CTM_PLOT will call
             GET_DEFAULTFORMAT to compute default format strings. 

        RESULT -> A named variable will contain the data subset that was
             plotted together with the X and/or Y coordinates in a structure.
             For 1D plots, either X or Y are -1. 3D visualization returns
             a structure including the Z coordinate.

        _EXTRA=e -> Picks up extra keywords for CTM_GET_DATABLOCK,
             CTM_LABEL, TVMAP, and TVPLOT.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===========================================================
        CTM_DRAW_CUBE                  CONVERT_LON
        CTM_TRACERINFO                 CTM_CONVERT_UNIT
        TVMAP                          TVPLOT
        CHKSTRU           (function)   MYCT_DEFAULTS     (function)
        CTM_GET_DATABLOCK (function)   CTM_LABEL         (function) 
        REPLACE_TOKEN     (function)   CTM_BOXSIZE       (function)   
        GET_DEFAULTFORMAT (function)   GAMAP_CMN     (include file)   

        
 REQUIREMENTS:
        Also assumes colortable has been loaded with "myct.pro". 

 NOTES:
        (1) Some keywords are saved in local variables with 
        slightly different names (e.g. MCONTOUR for /CONTOUR) 
        to prevent confusion with routine names and/or keywords
        that are picked up by the _EXTRA=e facility.

        (2) Not every possible combination of keywords has been thoroghly 
        tested. *PLEASE* report reproducible errors to mgs@io.harvard.edu!!

        (3) As of 11/17/98, CTM_PLOT can only produce X-Y plots with
        either PRESSURE or ALTITUDE along the left Y-Axis.  The right
        Y-Axis is left disabled (but will fix that later on...) 

        (4) Now define X-axis labels for longitude.  The labels are
        defined correctly for data blocks that span the date line.

 EXAMPLE:
        (0)
        CTM_PLOT
             ; To plot an ozone surface map (default) of a 
             ; user-selected file

        (1)
        FileName = '~/terra/CTM4/run_code/ctm.pch.sep1'
        CTM_PLOT, 22, 1, FileName=FileName, Lev=[1,14], $
           Total=4, /NoErase 

             ; Plots vertically-summed map for tracer 1 of ND22
             ; (J-Values map).  Will erase screen before plotting map.

        (2)
        CTM_PLOT, 'JV-MAP-$', 1, FileName=FileName, Lev=[1,14], $
           Total=4, /NoErase 

             ; Same as above, but uses category name instead of 
             ; diagnostic number.
 

 MODIFICATION HISTORY:
        bmy, 21 Sep 1998: VERSION 1.00
        bmy, 22 Sep 1998: VERSION 1.01
                          - added AVERAGE and TOTAL keywords
        bmy, 22 Sep 1998: VERSION 1.10
                          - Modified for use with new versions of
                            CTM_GET_DATABLOCK, CTM_EXTRACT,
                            CTM_LABEL, REPLACE_TOKEN, and TVMAP
        bmy, 25 Sep 1998: VERSION 1.11
                          - modified for TVMAP v. 2.0
        bmy, 28 Sep 1998: VERSION 2.00
                          - modified for TVMAP v. 2.01
                          - renamed LONSHIFT to LSHIFT
        bmy, 29 Sep 1998: - added ALTRANGE and PRANGE keywords
                            (which had been previously omitted)
        bmy, 30 Sep 1998: VERSION 2.01
                          - added call to CTM_CONVERT_UNIT
                          - added LABELSTRU keyword 
        bmy, 07 Oct 1998  VERSION 2.02
                          - now works with TVMAP 3.0
                          - added /CONTOUR, /FCONTOUR, and 
                            /COLORBAR keywords
                          - removed I/O error handling (that 
                            is already done in CTM_GET_DATABLOCK)
        bmy, 08 Oct 1998: VERSION 2.03
                          - now works with CTM_GET_DATABLOCK v. 1.03
                            and CTM_EXTRACT v. 1.04
                          - added DATA and THISDATAINFO keywords so
                            that an external data block can be
                            passed.
                          - another bug fix for UNITSTR
        bmy, 03 Nov 1998: VERSION 2.04
                          - works with new CTM_GET_DATA, 
                            CTM_GET_DATABLOCK and CTM_LABEL routines
                          - Now pass the FILEINFO and DATAINFO
                            structures via USE_FILEINFO and
                            USE_DATAINFO keywords
                          - removed DATA keyword   
                          - changed %NAME% token to %TRACERNAME%
                          - Now can pass an explicit unit string
                            via the USTR keyword
        mgs, 10 Nov 1998: - adapted for use with new CTM_GET_DATABLOCK
                          - changed keyword Erase to NoErase
                          - defaults set to produce an OX surface map
                            from IJ-AVG-$ diagnostics 
                          - allow for vertical cross section plots
                            (interface to TVPLOT) : ** still needs work! **
                          - changed CBAR to NOCBAR
        bmy, 12 Nov 1998: - TRACER is now a keyword instead of
                            an argument
                          - Changed keyword CONTINENTS to
                            NOCONTINENTS and GRID to NOGRID
                          - added NOISOTROPIC, SAMPLE and
                            keywords
        bmy, 13 Nov 1998: - VERSION 3.00
                          - ***** RENAMED to CTM_PLOT *****
                          - updated documentation header
                          - renamed C_LABELS to C_ANNOTATION to
                            prevent keyword name confusion
                          - added NOLINES, NOLABELS, C_LABELS,
                            and OVERLAYCOLOR keywords for tvmap
                          - now gets default colors from 
                            DEFAULT_COLORS.PRO
                          - Error checking for LIMIT keyword
                            (OK for now...fix this later on...)
        bmy, 16 Nov 1998: - Now use %DATE% instead of %YMD1% for
                            all default plot titles
                          - now enhanced for TVPLOT v. 2.0
                          - now only convert units for a tracer 
                            if the default unit is different from
                            the desired unit!!
        bmy, 17 Nov 1998: - added /PRESSURE keyword to plot pressure
                            instead of altitude on the left Y-axis
        mgs, 17 Nov 1998: - messed around quite a bit, because of 
                            (unfortunate) changes in default_range !@#$!@
                          - added CBFormat keyword
        bmy, 23 Nov 1998: - eliminated %SCALE% token from UNITSTR,
                            to be consistent with the latest
                            upgrade to COLORBAR.PRO. 
                          - now pass SECONDS to CTM_CONVERT_UNIT
        bmy, 13 Jan 1999: - add support for line plots.  Also, if
                            the DATA array is averaged down to a
                            single point, will print the value of
                            that point and exit.
                          - use NEWXTITLE and NEWYTITLE as token-replaced
                            strings for XTITLE and YTITLE
        bmy, 15 Jan 1999: - add support for 3-D visualization plots
                          - added unit string for contour plots
                          - now place CTM_LABEL call after the case
                            statement for PLOTTYPE, so that we can
                            suppress printing of special characters
                            in plot titles.
        bmy, 19 Jan 1999: - improve 0-D output
                          - fixed [XY]Titles for line plots
                          - "unitless" is now a unit string option
                          - now use new default color names from
                            DEFAULT_COLORS.PRO
        bmy, 20 Jan 1999: - Updated comments
        mgs, 22 Jan 1999: - couple bug fixes, some code cleaning
                          - added OverPlot keyword to allow multiple
                            line plots
        bmy, 19 Feb 1999: - now pass DEBUG (from GAMAP_CMN) to 
                            CTM_GET_DATABLOCK via DEBUG keyword
                          - Rename XIND, YIND, ZIND keywords to
                            XMID, YMID, ZMID, in call to CTM_GET_DATABLOCK
        bmy, 23 Feb 1999: - Add XTICKNAME, XTICKS, XTICKV in call to
                            TVPLOT...fix for map regions smaller than 
                            the globe
                          - bug fix.../NOGRID was listed as GRID!!!
                          - added keyword /NOGLABELS, which
                            suppresses grid line labels in MAP_SET 
                          - updated comments
        bmy, 26 Feb 1999: - now calls MAP_LABELS to get latitude labels
                            for X, XZ, Y, YZ plot types.
                          - updated comments
        bmy, 04 Mar 1999: - now pass DEBUG keyword to TVMAP
                          - now use GRIDINFO.XEDGE, GRIDINFO.YEDGE
                            to compute the LIMIT keyword for MAP_SET
        mgs, 18 Mar 1999: - minor cleaning
        mgs, 23 Mar 1999: - added ILun to keyword list to prevent retrieval
                            of two otherwise identical records from two
                            different files
        bmy, 25 Mar 1999: - now line plots use MULTIPANEL
                          - if NPANELS >=2 then place the plot title
                            higher above the window, to allow for 
                            carriage-returned lines
                            for X, Y, Z, XY, XZ, YZ plots
        mgs, 25 Mar 1999: - no unit conversion if not necessary
                          - small fix to allow for 2D fields (e.g. EPTOMS)
        bmy, 14 Apr 1999: - now prints unit string at lower right of
                            XZ or YZ plots, if the colorbar is not
                            plotted
        bmy, 26 Apr 1999: - rename YRANGE to YYRANGE internally, so as
                            to avoid confusion with YRANGE plot keywords   
        mgs, 19 May 1999: - removed a few too explicit keyword settings
                            for 1D plots and fixed OverPlot option.
                            Now stores !X, !Y, and !P from last 1D plot
                            in a local common block.
        mgs, 21 May 1999: - restore !X, !Y, and !P at the end of each
                            1-D plot to allow overplotting of data.
        mgs, 25 May 1999: - needed to mess around with lonrange to get
                            it right.
        mgs & bmy, 26 May 1999: - added POLAR keyword
        bmy, 27 May 1999: - bug fix: CBUnit keyword wasn't honored
                          - neither was NoIsotropic
        mgs, 27 May 1999: - changed default behaviour for filled contours:
                            now plots no lines and colorbar. Keyword
                            NoLines changed to C_Lines.
        mgs, 28 May 1999: - added RESULT keyword to return data as plotted
                          - bug fix with wrapping round data: shouldn't be
                            done for vertical cross sections.
        mgs, 02 Jun 1999: - small bug fix for 0D results.
        mgs, bmy 03 Jun 1999: - removed "Unit:" from output
        bmy, 07 Jul 1999: - added PLOTCSFAC scale factor for multipanel
                            plots
                          - small fixes for line plots
        bmy, 02 Nov 1999: GAMAP VERSION 1.44
                          - return if THISDATAINFO contains
                            information for more than one data block
        bmy, 24 Nov 1999: - now pass _EXTRA=e to CTM_TRACERINFO
                            so that /SMALLCHEM will be passed
        bmy, 13 Dec 1999: - if GRIDINFO is undefined after returning from
                            CTM_GET_DATABLOCK, rebuild it w/ CTM_TYPE
        bmy, 03 Feb 2000: GAMAP VERSION 1.45
                          - NOTE: /INDEX does not work with lon range
                            shifting anymore.  Will fix later.
                          - also make sure LON, LAT have two elements 
                          - added X_FORMAT, Y_FORMAT keywords for line plots
                          - updated comments 
        bmy, 06 Apr 2000: - bug fix: restrict X or Y axis range for line
                            plots using the value passed from YYRANGE.
                          - cosmetic changes, updated comments
        bmy, 23 Jan 2001: GAMAP VERSION 1.47
                          - now call "isopleth_map.pro" to plot a 3-D
                            isosurface.  3-D visualization via
                            routine "ctm_draw_cube.pro" is obsolete.
                          - added ISOPLETH keyword as pass-thru to 
                            ISOPLETH_MAP
        bmy, 23 Jul 2001: GAMAP VERSION 1.48
                          - replaced call to DEFAULT_COLORS with 
                            call to MYCT_DEFAULTS() to specify
                            MYCT color table information
                          - deleted obsolete code from 1998 and 1999
        bmy, 09 Aug 2001: - bug fix: remove reference to BLACK from
                            the old "default_colors.pro"
        bmy, 24 May 2002: GAMAP VERSION 1.50
                          - Now use SI unit hPa instead of mb in axis titles
                          - delete obsolete, commented-out code
        bmy, 28 Sep 2002: GAMAP VERSION 1.51
                          - now get default NCOLORS, BOTTOM, BLACK values
                            from !MYCT system variable instead of from
                            the MYCT_DEFAULTS function
        bmy, 16 Apr 2004: GAMAP VERSION 2.02
                          - Also need to convert the units of YYRANGE
                            accordingly so that /AUTORANGE will work
        bmy, 16 Jun 2004: - Bug fix: if we do unit conversion, do not
                            let the converted value of YRANGE get
                            passed back to the main program
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Modified for GEOS-5 fields that are
                            defined on level edges
        phs, 19 Mar 2008: GAMAP VERSION 2.12
                          - Bug fix for working with new map_labels
        phs, 02 Apr 2008: - Bug fix for XZ and YZ pixel plots

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plot.pro)


CTM_PLOTDIFF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_PLOTDIFF

 PURPOSE:
        Prints a lat-lon map of 2 CTM fields, their absolute difference, 
        and their percent difference.  This is a quick way of ensuring 
        that two model versions are producing identical results.

        The page will contain the following plot panels:

             Panel #1               Panel #2
             Data Block D1          Data Block D2

             Panel #3               Panel #4
             Abs Diff (D2 - D1)     % Diff (D2 - D1)

 CATEGORY:
        GAMAP Utilities, GAMAP Plotting

 CALLING SEQUENCE:
        CTM_PLOTDIFF, DIAGN, FILE1, FILE2 [, Keywords ]

 INPUTS:
        DIAGN -> A diagnostic number or category to restrict
             the record selection (default is: "IJ-AVG-$"). 

        FILE1 -> Name of the first CTM output file.  If FILE1
             is not given, or if it contains wildcard characters
             (e.g. "*"), then the user will be prompted to supply
             a file name via a pickfile dialog box.

        FILE2 ->  Name of the second CTM output file.  If FILE2
             is not given, or if it contains wildcard characters
             (e.g. "*"), then the user will be prompted to supply
             a file name via a pickfile dialog box.

 KEYWORD PARAMETERS:


        LON -> A 2-element vector specifying the longitude range that
             will be used to make the plot.  Default is [-180,180].

        LAT -> A 2-element vector specifying the latitude range that
             will be used to make the plot.  Default is [-88,88].

        LEV -> A scalar or 2-element vector which specifies the
             level(s) that will be used to make the plot.  Default
             is [ 1, 1 ].

        /PS -> Set this switch to print to a PostScript file.
 
        OUTFILENAME -> Name of the PostScript file if the /PS option 
             is set.  Default is "idl.ps".

        TRACER -> Tracer number(s) for which differences will be plotted.  

        TAU0 -> TAU value(s) (hours since 0 GMT 1 Jan 1985) at the start
             of the diagnostic data block to plot.

        DIVISIONS -> Specifies the number of colorbar divisions for 
             the quantity plot (Panels #1 and #2).  Default is 5.
             NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.

        DATARANGE -> Allows you to manually specify the min and max
             values of the data that will appear on the plot (Panels
             # 1 and #2).  The default is to automatically compute
             the overall min and max of both data blocks.

        MIN_VALID -> Specifies the minimum valid data for the plot. 
             Data lower than MIN_VALID will be rendered with color
             !MYCT.WHITE.  For example, MIN_VALID is useful for
             plotting emissions which only occur on land.

        DIFFDIV -> Specifies the number of colorbar divisions for 
             the difference plots (Panels #3 and #4).  Default is 8.
             NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.

        DIFFNCOLORS -> Sets the # of colors used to create the
             difference plots (Panels #3 and #4).  Default is 13.

        DIFFRANGE -> Allows you to manually specify the min and max
             values that will appear on the absolute difference
             plot (Panel #3).  Default is to use the dynamic range of
             the absolute difference data (symmetric around zero).

        /NODEVICE -> set to not call open_device, so you can do it
             from outside

        /NOMULTIPANEL -> set to not call multipanel, so you can do it
             from outside

        PCRANGE -> Allows you to manually specify the min and max
             values that will appear on the percentage difference
             plot (Panel #4).  Default is to use the dynamic range of
             the percentage difference data (symmetric around zero).

        PCDIV -> number of ticks in the %-Diff colorbar

        PCNCOLORS -> number of colors for the %-Diff plot

        T1, T2, DIFFTITLE -> allows you to overwrite the default
             title for the 1st, 2nd and DIff plots.


        _EXTRA=e -> Picks up extra keywords for CTM_DIFF,
             OPEN_DEVICE, and MYCT


   Keywords for the MASK feature:
   ------------------------------
        /MASK -> set to mask with a green color boxes where %-diff
             and/or diff are below some threshold. The absolute value
             of the % is plot.

	 PC_THR, DIFF_THR : the %-Diff and Diff THResholds to mask data in the
             4th plot if /MASK is set. Boxes with %-Diff or/and Diff
             below the THResholds are masked. Default values are 1%
             and 1e4.

        /ZAP -> set to skip all plots if /MASK is set and all boxes
             are masked.


 OUTPUTS:
        none

 SUBROUTINES:
        External Subroutines Required:
        =======================================================
        CHKSTRU     (function)    CLOSE_DEVICE 
        CTM_CLEANUP               COLORBAR_NDIV     (function)
        CTM_DIFF                  CTM_GET_DATABLOCK (function) 
        IS_DEFINED   (function)   EXTRACT_FILENAME  (function) 
        MULTIPANEL                OPEN_DEVICE
        

 REQUIREMENTS:
        None

 NOTES:
        (1) CTM_PLOTDIFF calls CTM_CLEANUP each time to remove
            previously read datablock info from the GAMAP common
            block.

        (2) The default TAU0 value is 0, and is not suitable if your 
            run has no output for 0 GMT 1 Jan 1985! You may have to 
            gather tau0 before running and crashing CTM_PLOTDIFF.

 EXAMPLE:
        FILE1 = 'ctm.bpch.v4-30'
        FILE2 = 'ctm.bpch.v4-31'
        CTM_PLOTDIFF, 'IJ-AVG-$', FILE1, FILE2, TRACER=1

             ; Creates 4-panel plot w/ old data, new data,
             ; new - old (abs diff), and new - old (% diff).

 MODIFICATION HISTORY:
        bmy, 17 Apr 2002: GAMAP VERSION 1.50
        bmy, 17 Jul 2002: GAMAP VERSION 1.51
                          - added TAU0 keyword
        bmy, 16 Dec 2002: GAMAP VERSION 1.52
                          - now can handle 2 different tracer numbers
                          - now can handle 2 different TAU0 values
        bmy, 29 Jan 2004: GAMAP VERSION 2.01
                          - Now pass LEV keyword to CTM_DIFF
                          - Now plot both DATA1 and DATA2 on
                            the same scale for easier comparison
        bmy, 16 Feb 2005: GAMAP VERSION 2.03
                          - Now use /QUIET and /NOPRINT keywords in
                            CTM_GET_DATA and CTM_GET_DATABLOCK to
                            suppress screen output
        phs, 24 Oct 2006: GAMAP VERSION 2.05
                          - Now use YRANGE if it is passed.  
                          - Also use DIFFRANGE (for range of the 
                            abs difference plot) if it is passed.
                          - Now use PCRANGE (for range of the
                            %age difference plot) if it is passed.
        bmy, 15 Nov 2006: GAMAP VERSION 2.06
                          - Now use blue-white-red color table
                            for abs diff and % diff plots
  bmy & phs, 04 Oct 2007: GAMAP VERSION 2.10
                          - Added DIVISIONS keyword (default=5) 
                          - Now make the default DIFFRANGE and
                            PCRANGE symmetric around zero
                          - Added DIFFDIV, DIFFNCOLORS keywords
                          - Also restore original !MYCT structure
                          - restore initial Color Table and !MyCt,
                            and return, when crashes.
                          - Now skip plotting % difference if
                            DATA1 is zero everywhere
                          - Add error trapping with CATCH
        bmy, 16 Jan 2008: GAMAP VERSION 2.12
                          - add _EXTRA=e to calls to CTM_PLOT, in order
                            to pass extra variables to that routine
        phs, 31 Jan 2008: - Add NODEVICE keyword, so device (like PS
                            file) can be open outside this routine,
                            allowing for multiple pages in a PS file
                            for example.
                          - Clipping of percentage difference range
                            is indicated with triangle.
        phs, 25 Feb 2008: - Improved error catcher
        bmy, 05 Nov 2008: GAMAP VERSION 2.13
                          - Renamed YRANGE keyword to DATARANGE in
                            order to avoid confusion with nested grids
        phs, 22 Sep 2009: - more flexible call to MYCT for diff
                            plots, so it can be overwriten from
                            caller
                          - Can select number of colors and divisions
                            for %-diff plot
                          - Can overwrite titles
                          - Can set Multipanel from outside in caller
                          - Can MASK data according to both Diff and
                            %-Diff values, in the 4th plot
        bmy, 29 Jan 2010: GAMAP VERSION 2.14
                          - Minor fix in IF statement to prevent code
                            from dying after call to CTM_DIFF.
                          

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plotdiff.pro)


CTM_PLOTDIFF4

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_PLOTDIFF4

 PURPOSE:
        Prints a lat-lon map of 2 CTM fields, their absolute difference, 
        and their percent difference.  This is a quick way of ensuring 
        that two model versions are producing identical results.

        The page will contain the following plot panels:

             Panel #1               Panel #2
             Data Block D1          Data Block D2

             Panel #3               Panel #4
             Abs Diff (D2 - D1)     % Diff (D2 - D1) / D1

        CTM_PLOTDIFF4 is a lighter version of CTM_PLOTDIFF, and does
        not use CTM_DIFF as an intermediary routine. 

 CATEGORY:
        GAMAP Utilities, GAMAP Plotting

 CALLING SEQUENCE:
        CTM_PLOTDIFF4, DIAGN, FILE2, FILE2 [, Keywords ]

 INPUTS:
        DIAGN -> A diagnostic number or category to restrict
             the record selection (default is: "IJ-AVG-$"). 

        FILE1 -> Name of the first CTM output file.  If FILE1
             is not given, or if it contains wildcard characters
             (e.g. "*"), then the user will be prompted to supply
             a file name via a pickfile dialog box.

        FILE2 ->  Name of the second CTM output file.  If FILE2
             is not given, or if it contains wildcard characters
             (e.g. "*"), then the user will be prompted to supply
             a file name via a pickfile dialog box.

 KEYWORD PARAMETERS:

        LON -> A 2-element vector specifying the longitude range that
             will be used to make the plot.  Default is [-180,180].

        LAT -> A 2-element vector specifying the latitude range that
             will be used to make the plot.  Default is [-88,88].

        LEV -> A scalar or 2-element vector which specifies the
             level(s) that will be used to make the plot.  Default
             is [ 1, 1 ].

        /PS -> Set this switch to print to a PostScript file.
 
        OUTFILENAME -> Name of the PostScript file if the /PS option 
             is set.  Default is "idl.ps".

        TRACER -> A scalar or 2-element vector which specifies the
             tracer number(s) for each data block.  

        TAU0 -> A scalar or 2-element vector which specifies the
             TAU value(s) (hours since 0 GMT 1 Jan 1985) by which
             each data block is timestamped.

        DIVISIONS -> Specifies the number of colorbar divisions for 
             the quantity plot (Panels #1 and #2).  Default is 5.
             NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.

        DATARANGE -> Allows you to manually specify the min and max
             values of the data that will appear on the plot (Panels
             # 1 and #2).  The default is to automatically compute
             the overall min and max of both data blocks.

        MIN_VALID -> Specifies the minimum valid data for the plot. 
             Data lower than MIN_VALID will be rendered with color
             !MYCT.WHITE.  For example, MIN_VALID is useful for
             plotting emissions which only occur on land.

        DIFFDIV -> Specifies the number of colorbar divisions for 
             the difference plots (Panels #3 and #4).  Default is 8.
             NOTE: The optimal # of divisions is !MYCT.NCOLORS/2 +1.

        DIFFNCOLORS -> Sets the # of colors used to create the
             difference plots (Panels #3 and #4).  Default is 13.

        DIFFRANGE -> Allows you to manually specify the min and max
             values that will appear on the absolute difference
             plot (Panel #3).  Default is to use the dynamic range of
             the absolute difference data (symmetric around zero).

        /NODEVICE -> set to not call open_device, so you can do it
             from outside

        /NOMULTIPANEL -> set to not call multipanel, so you can do it
             from outside

        PCRANGE -> Allows you to manually specify the min and max
             values that will appear on the percentage difference
             plot (Panel #4).  Default is to use the dynamic range of
             the percentage difference data (symmetric around zero).

        PCDIV -> number of ticks in the %-Diff colorbar

        PCNCOLORS -> number of colors for the %-Diff plot

        TITLE_1 -> Allows you to override the default plot title for
             the first data block (1st plot panel).

        TITLE_1 -> Allows you to override the default plot title for
             the 2nd data block (2nd plot panel).

        DIFFTITLE -> Allows you to override the default plot title for
             the absolute difference plot (3rd plot panel).

        PCTITLE -> Allows you to override the default plot title for
             the percent difference plot (4th plot panel).

        _EXTRA=e -> Picks up extra keywords for CTM_DIFF,
             OPEN_DEVICE, and MYCT


   Keywords for the MASK feature:
   ------------------------------
        /MASK -> set to mask with a green color boxes where %-diff
             and/or diff are below some threshold. The absolute value
             of the % is plot.

	 PC_THR, DIFF_THR : the %-Diff and Diff THResholds to mask
	      data in the 4th plot (percent difference) if /MASK is
	      set.  Boxes with %-Diff or/and Diff below the THResholds
	      are masked. Default values are 1% and 1e4.

        /ZAP -> set to skip all plots if /MASK is set and all boxes
             are masked.;

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==========================================================
        CHKSTRU          (function)  CLOSE_DEVICE
        COLORBAR_NDIV    (function)  CTM_GET_DATABLOCK (function)
        EXTRACT_FILENAME (function)  MULTIPANEL                
        MYCT                         OPEN_DEVICE               
        TVMAP                        UNDEFINE

 REQUIREMENTS:
        Requires routines from the GAMAP package.

 NOTES:
        (1) When plotting a subset of the globe, CTM_PLOTDIFF4
            properly sets the colorbar ranges for the abs diff
            and percent diff plots.  This was an issue in the
            older CTM_PLOTDIFF.

        (2) Longitude and latitude ranges specified by LON and LAT
            will be applied to both data blocks.  

 EXAMPLE:
         CTM_PLOTDIFF4, 'IJ-AVG-$',                      $
                        'v8-03-02.bpch', 'v9-01-01.bpch, $
                        TRACER=6,      LEVEL=1,          $
                        LON=[-90,-30], LAT=[30,15]
 
             ; Creates a 4-panel difference plot for ISOPRENE
             ; (IJ-AVG-$, tracer #6) at the surface for the Amazon
             ; basin region from data in 2 different model versions.

 MODIFICATION HISTORY:
        bmy, 16 May 2011: VERSION 1.00
        bmy, 13 Jan 2014: GAMAP VERSION 2.17
                          - Bug fix: For 2-D data blocks that lack the  
                            GRIDINFO.ZMID tag name, display the altitude
                            of the data as 0.0 km.

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plotdiff4.pro)


CTM_PLOTRATIO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_PLOTRATIO

 PURPOSE:
        Plots the ratio of two CTM data fields.  This is one way
        to see if two model versions produce identical results.

 CATEGORY:
        GAMAP Utilities, GAMAP Plotting

 CALLING SEQUENCE:
        CTM_PLOTRATIO, DIAGN [, Keywords ]

 INPUTS:
        DIAGN -> A diagnostic number or category to restrict
             the record selection.  Default is "IJ-AVG-$". 

 KEYWORD PARAMETERS:
        FILE1 -> Name of the first CTM output file (containing the
             "old" data).  If FILE1 is not given, or if it contains 
             wildcard characters (e.g. "*"), then the user will be 
             prompted to supply a file name via a pickfile dialog box.

        FILE2 ->  Name of the second CTM output file.  If FILE2
             is not given, or if it contains wildcard characters
             (e.g. "*"), then the user will be prompted to supply
             a file name via a pickfile dialog box.

        LON -> A 2-element vector specifying the longitude range that
             will be used to make the plot.  Default is [-180,180].

        LAT -> A 2-element vector specifying the latitude range that
             will be used to make the plot.  Default is [-88,88].

        LEV -> Vertical level for which to plot data.  Default is 1.

        TITLE -> Title string for the plot.  If not specified, a
             generic title string will be generated.

        TRACER -> Number of the tracer for which differences
             will be plotted.  Default is 1.

        _EXTRA=e -> Picks up extra keywords for CTM_DIFF.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==========================================
        CTM_CLEANUP   CTM_GET_DATABLOCK (function)
        CTM_DIFF      EXTRACT_FILENAME  (function)
        OPEN_DEVICE   CLOSE_DEVICE
        MULTIPANEL

 REQUIREMENTS:
        None

 NOTES:
        (1) The ratio plotted will be DATA2 / DATA1, where DATA2
            is contained in FILE2, and DATA1 is contained in FILE1.

        (2) For places where DATA1 = 0, DATA2 will also be set to 0.
            This avoids division by zero errors.

        (3) CTM_PLOTRATIO calls CTM_CLEANUP each time to remove
            previously read datablock info from the GAMAP common
            block.

 EXAMPLE:
        FILE1 = 'ctm.bpch.v4-30'
        FILE2 = 'ctm.bpch.v4-31'
        CTM_PLOTRATIO, 'IJ-AVG-$', $
             FILE1=FILE1, FILE2=FILE2, TRACER=1, LEV=1

             ; Plots the ratio of NOx data at the surface:
             ;   ctm.bpch.v4-31 / ctm.bpch.v4-30

 MODIFICATION HISTORY:
        bmy, 24 Apr 2002: GAMAP VERSION 1.50
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plotratio.pro)


CTM_PLOT_TIMESERIES

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_PLOT_TIMESERIES

 PURPOSE:
        Plots station timeseries data (e.g. from the GEOS-CHEM
        ND48 diagnostic) contained in binary punch file format.
        %%%% MAY NEED UPDATING %%%%%

 CATEGORY:
        GAMAP Utilities, GAMAP Plotting

 CALLING SEQUENCE:
        CTM_PLOT_TIMESERIES, CATEGORY [ , Keywords ] 

 INPUTS:
        CATEGORY -> The diagnostic number (e.g. ND22, ND45, etc or 
             category name (e.g. "JV-MAP-$", "IJ-AVG-$") for which to 
             read data from the punch file. 

 KEYWORD PARAMETERS:
        BOTTOM -> The lowest color index of the colors to be loaded
             used in the color map and color bar.  The default is
             to use the value in system variable !MYCT.BOTTOM.

        COLOR -> Color of the plot window and/or data.  The default
             is to use the system variable !MYCT.BLACK.

        LABELSTRU -> Returns to the calling program the structure
             of label information obtained by CTM_LABEL.

        LEV -> An index array of sigma levels *OR* a two-element
             vector specifying the min and max sigma levels to be 
             included in the plot.  Default is [ 1, GRIDINFO.LMX ].
 
        OVERPLOT -> Plot data atop the previous plot window, instead
             of erasing the screen and plotting in a new window.

        RESULT -> A named variable will contain the data subset that
             was plotted together with the X and/or Y coordinates in
             a  structure.  

        TITLE -> Top title string for the plot.  If not passed, 
             then a default title string will be printed.

        UNIT -> Name of the unit that the DATA array will be converted
             to. If not specified, then no unit conversion will be done.

        XTITLE -> X-Axis title string for the plot.  If not passed, 
             then a default title string will be printed.

        YTITLE -> Y-Axis title string for the plot.  If not passed, 
             then a default title string will be printed.

        YRANGE -> range of y values for color scaling (default:
             scale each plot seperately with data min and max)

        _EXTRA=e -> Picks up extra keywords for routines called
             by CTM_PLOT_TIMESERIES.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===========================================================
        CTM_GET_DATA              CTM_INDEX           (function)
        CTM_LABEL    (function)   GETMODELANDGRIDINFO (function)
        UNDEFINE                  REPLACE_TOKEN       (function)         

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:

 MODIFICATION HISTORY:
        bmy, 16 Apr 2004: GAMAP VERSION 2.03
                          - Initial version
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_plot_timeseries.pro)


CTM_PRINTDIFF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_PRINTDIFF

 PURPOSE:
        Prints the sum of the differences between two CTM
        output files.  This is a quick way of ensuring that
        two model versions are producing identical results.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        CTM_PRINTDIFF, DIAGN [, Keywords ]

 INPUTS:
        DIAGN -> A diagnostic number or category to restrict
             the record selection (default is: "IJ-AVG-$").        

 KEYWORD PARAMETERS:
        FILE1 -> Name of the first CTM output file (the "old" file).
             If FILE1 is not given, or if it contains wildcard 
             characters (e.g. "*"), then the user will be prompted 
             to supply a file name via a pickfile dialog box.

        FILE2 ->  Name of the second CTM output file (the "new" file).  
             If FILE2 is not given, or if it contains wildcard 
             characters (e.g. "*"), then the user will be prompted 
             to supply a file name via a pickfile dialog box.

        TRACER -> Number of the tracer for which differences
             will be plotted.

        _EXTRA=e -> Picks up other keywords for CTM_GET_DATABLOCK.

 OUTPUTS:
        Prints the quantity:

             DIFF[L] = TOTAL( DATA2[*,*,L] - DATA1[*,*,L] ) 

        for each level L.  If DIFF[L] = 0 for all levels L, then
        FILE1 and FILE2 contain identical data.

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        CTM_CLEANUP
        CTM_GET_DATABLOCK (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) If DATA1 corresponds to the "old" data, and DATA2
            corresponds to the "new" data, then CTM_DIFF will 
            compute the following:
         
            Abs. Diff = ( new - old )

        (2) CTM_PRINTDIFF calls CTM_CLEANUP each time to remove
            previously read datablock info from the GAMAP common
            block.

 EXAMPLE:
        FILE1 = 'ctm.bpch.v4-30'      ; the "old" file
        FILE2 = 'ctm.bpch.v4-31'      ; the "new" file
        CTM_PRINTDIFF, 'IJ-AVG-$', $
             FILE1=FILE1, FILE2=FILE2, TRACER=1

        IDL prints:
             Level:  26 Difference: -2.3841858e-07
             Level:  25 Difference:  0.0000000e+00
             Level:  24 Difference:  0.0000000e+00
             Level:  23 Difference:  0.0000000e+00
             Level:  22 Difference: -1.4901161e-08
             Level:  21 Difference:  0.0000000e+00
             Level:  20 Difference:  0.0000000e+00
             Level:  19 Difference:  0.0000000e+00
             Level:  18 Difference:  0.0000000e+00
             Level:  17 Difference:  0.0000000e+00
             Level:  16 Difference:  0.0000000e+00
             Level:  15 Difference:  0.0000000e+00
             Level:  14 Difference: -7.4505806e-09
             Level:  13 Difference:  0.0000000e+00
             Level:  12 Difference:  0.0000000e+00
             Level:  11 Difference:  0.0000000e+00
             Level:  10 Difference:  0.0000000e+00
             Level:   9 Difference:  0.0000000e+00
             Level:   8 Difference:  0.0000000e+00
             Level:   7 Difference:  0.0000000e+00
             Level:   6 Difference:  0.0000000e+00
             Level:   5 Difference:  0.0000000e+00
             Level:   4 Difference:  0.0000000e+00
             Level:   3 Difference:  0.0000000e+00
             Level:   2 Difference:  0.0000000e+00
             Level:   1 Difference:  0.0000000e+00

             ; Prints the sum of differences at each level 
             ; betweeen two GEOS-STRAT binary punch files 
             ; for NOx (tracer=1).
            
 MODIFICATION HISTORY:
        bmy, 04 Apr 2002: GAMAP VERSION 1.50
        bmy, 22 Apr 2002: - now takes diff of DATA2 - DATA1, in order
                            to be consistent with CTM_PLOTDIFF.
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_printdiff.pro)


CTM_PRINT_DATAINFO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_PRINT_DATAINFO

 PURPOSE:
        Create and print a formatted list of DATAINFO records.
        This procedure can be used for direct printing, but it
        can also return a string array of the formatted output 
        e.g. for use in a widget list.

 CATEGORY:
        GAMAP Internals, GAMAP Data Manipulation

 CALLING SEQUENCE:
        CTM_PRINT_DATAINFO,DATAINFO [,keywords]

 INPUTS:
        DATAINFO -> One or more DATAINFO records, e.g. the result 
             from CTM_GET_DATA.

 KEYWORD PARAMETERS:
        FIELDS -> (*** not yet implemented ***) A list of fields
             (structure tag names) to be printed. Default is
             CATEGORY, ILUN, TRACERNAME, TRACERNUMBER, 
             UNIT, TAU0, STATUS, DIMENSIONS
             FIELDS can also include tags from the (global) FILEINFO
             structure (e.g. FILENAME).

        OUTPUT -> A named variable that will contain a string array
             with the formatted output including the title line but 
             without the seperating lines. The title is not included
             if keyword /NOTITLE is set.

        /NOPRINT -> Don't print, only return formatted strings

        /NOTITLE -> Do not generate title line (will neither be printed
             nor included in OUTPUT.

 OUTPUTS:
        None

 SUBROUTINES:
        External subroutines required:  
        ------------------------------
        GAMAP_CMN  (include file)
        TAU2YYMMDD (function)

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.

 NOTES:
        For GISS, FSU family of models, TAU0 = 0 occurs on date 1/1/1980.
        For GEOS      family of models, TAU0 = 0 occurs on date 1/1/1985.
        Therefore, the model family must be obtained from the global
        FILEINFO structure in order to display the YYMMDD
        corresponding to TAU0.
 
 EXAMPLE:
        CTM_GET_DATA,DataInfo,File='',tracer=2
        CTM_PRINT_DATAINFO,DataInfo
        ; *or*
        CTM_PRINT_DATAINFO,DataInfo,Output=r,/NOPRINT

 MODIFICATION HISTORY:
        mgs, 10 Nov 1998: VERSION 1.00
        bmy, 11 Feb 1999: VERSION 1.01
                          - adjust format for double-precision TAU0
        mgs, 16 Mar 1999: - added tracer number and removed STATUS
                          - made cosmetic changes
        mgs, 23 Mar 1999: - print dimension as NA if not yet available
        bmy, 27 Apr 1999: - widen tracer number field to 6 chars
        mgs, 22 Jun 1999: - widen unit field to 12 chars and add DATE field
        bmy, 27 Jul 1999: VERSION 1.42
                          - GISS/FSU YYMMDD values are now correct
                          - cosmetic changes
        bmy, 10 Aug 1999: - change I6 format for date to I6.6
                            so that leading zeroes are printed
        bmy, 03 Jan 2000: VERSION 1.44
                          - change I6.6 format to I8.8 and print the 
                            date in YYYYMMDD format for Y2K compliance
                          - declare TAU2YYMMDD as external with the
                            FORWARD_FUNCTION command
        bmy, 14 Feb 2001: GAMAP VERSION 1.47
                          - decrease tracer name from 10 to 7 chars
                          - Now use 10-digit date string YYYYMMDDHH
        bmy, 02 Jul 2001: GAMAP VERSION 1.48
                          - now assume that GENERIC grids use GEOS
                            time epoch for NYMD2TAU 
        bmy, 21 Oct 2002: GAMAP VERSION 1.52
                          - now assume MOPITT grid uses GEOS epoch
                          - deleted obsolete code
        bmy, 03 May 2005: GAMAP VERSION 2.04
                          - wrap tracer number into 5 digits
                          - GCAP uses the same TAU values as GEOS models
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
         bmy 24 Jan 2014: GAMAP VERSION 2.17
                          - Adjust output format string to allow for
                            a few extra spaces in UNIT and TRACER #.

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_print_datainfo.pro)


CTM_READ3DB_HEADER

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_READ3DB_HEADER

 PURPOSE:
        retrieve header information and file positions of data
        blocks from binary global 3D model output. This is a
        twin of CTM_READ3DP_HEADER which digests the header
        information from ASCII punch files.

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        test = CTM_READ3DB_HEADER(LUN,FILEINFO,DATAINFO [,keywords])

 INPUTS:
        LUN --> logical file unit of the binary punch file. The file 
             must be open (see CTM_OPEN_FILE or OPEN_FILE)

        FILEINFO --> a (single) fileinfo structure containing information
             about the (open) file (see CREATE3DFSTRU). FILEINFO also
             contains information about the model which generated
             the output (see CTM_TYPE)

        DATAINFO --> a named variable that will contain an array of
             structures describing the file content (see
             CREATE3DHSTRU)

 KEYWORD PARAMETERS:
        PRINT  -> if activated, print all headers found in the file

 OUTPUTS:
        The function returns 1 if successful, and 0 otherwise. 

        FILEINFO --> toptitle and modelinfo tags will be set

        DATAINFO --> contains an array of named structures 
             (see CREATE3DHSTRU) with all relevant information
             from the punch file header and what is needed to find
             and load the data.
              
 SUBROUTINES:

 REQUIREMENTS:
        uses CREATE3DHSTRU function to create header structure
        uses CHKSTRU to test FILEINFO structure
        uses CTM_TYPE to create modelinfo structure
        needs gamap_cmn.pro to access global common block

 NOTES:
        This routine uses the new binary file format introduced
        first to the GEOS/Harvard CTM.

 EXAMPLE:
              fileinfo = create3dfstru()   ; not required !
              fname = '~bmy/terra/CTM4/results/ctm.bpch'
              open_file,fname,ilun,/F77_UNFORMATTED   ; <=== !!
              if (ilun gt 0) then $
                 result = CTM_READ3DB_HEADER(ilun,fileinfo,datainfo)
              print,result

        To get e.g. all scaling factors, type 
              print,datainfo[*].scale

        To retrieve the header structure for one data block, type
              blocki = datainfo[i]

 MODIFICATION HISTORY:
        mgs, 15 Aug 1998: VERSION 1.00
                          - derived from CTM_READ3DP_HEADER
        mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
        mgs, 14 Jan 1999: - now expects diag category name instead 
                            of number
        bmy, 11 Feb 1999: - change TAU0, TAU1 to double-precision,
                            in accordance w/ new binary file format
                          - clean up some POINT_LUN calls
        bmy, 22 Feb 1999: VERSION 1.01
                          - now store I0, J0, L0 from binary file
                            in new FIRST field from CREATE3DHSTRU
                          - comment out assignment statement for
                            SKIP; now use value from binary file
        mgs, 16 Mar 1999: - cosmetic changes
        mgs, 24 May 1999: - now supports 'CTM bin 02' files
                          - added a filetype check
                          - now defaults to 512 records (former 4096)
        mgs, 27 May 1999: - fixed bug with new record default: new
                            records were never added as they were 
                            supposed to.
        bmy, 26 Jul 1999: - also print out SKIP field in debug output
        bmy, 10 Jul 2003: GAMAP VERSION 1.53
                          - added kludge so that GEOS-3 reduced grid
                            w/ 30 layers will be added to FILEINFO
                            correctly
        bmy, 21 Nov 2003: GAMAP VERSION 2.01
                          - BPCH file v1 now has FILETYPE=101
                          - BPCH file v2 now has FILETYPE=102
                          - Now define separate DATAINFO.FORMAT values
                            for BPCH v1 and BPCH v2 type files   
                          - removed kludge for GEOS3_30L, since the
                            bug in CTM_TYPE has now been fixed
        bmy, 24 Aug 2004: GAMAP VERSION 2.03
                          - now assign FORMAT string for Filetype 105
                            which is BPCH file for GEOS-CHEM station
                            timeseries (e.g. ND48 diagnostic)
  phs & bmy, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now account for FILETYPE=106, which
                            denotes CTM bpch files w/ 4-D data.
        bmy, 23 Feb 2012: GAMAP VERSION 2.16
                          - Now make FILEPOS and NEWPOS LONG64
                            variables, in order to read bpch files
                            larger than 2.4 GB.
        bmy, 20 Jan 2016: GAMAP VERSION 2.19
                          - Bug fix: cast SKIP variable to LONG64

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read3db_header.pro)


CTM_READ3DP_HEADER

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_READ3DP_HEADER

 PURPOSE:
        retrieve header information and file positions of data
        blocks from global 3D model punch file output.

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        test = CTM_READ3DP_HEADER(LUN,FILEINFO,DATAINFO [,keywords])

 INPUTS:
        LUN --> logical file unit of the punch file. The file
             must be open (see CTM_OPEN_FILE or OPEN_FILE)

        FILEINFO --> a (single) fileinfo structure containing information
             about the (open) file (see CREATE3DFSTRU). FILEINFO also
             contains information about the model that generated the
             data, which is queried interactively.

        DATAINFO --> a named variable that will contain an array of
             structures describing the file content (see
             CREATE3DHSTRU)

 KEYWORD PARAMETERS:
        /NO_TOPTITLE --> do not interprete first line of file as
             header line. Only one header line will be skipped
             (as normally only one header line is read in).

        /EXTRA_SPACE -> digests output from GISS_II_PRIME model with
             extra spaces in the punch file. This keyword is optional
             in the following sense: If CTM_READ3DP_HEADER detects
             an error reading a header line, it is called again
             automatically with this option set.

        PRINT  -> if activated, print all headers found in the file

 OUTPUTS:
        The function returns 1 if successful, and 0 otherwise.

        FILEINFO --> toptitle and modelinfo tags will be set

        DATAINFO --> contains an array of named structures
             (see CREATE3DHSTRU) with all relevant information
             from the punch file header and what is needed to find
             and load the data.

 SUBROUTINES:

 REQUIREMENTS:
        uses CREATE3DHSTRU function to create header structure
        uses CHKSTRU to test FILEINFO structure
        uses CTM_TYPE to set modelinfo
        needs gamap_cmn.pro to set default in query for model type

 NOTES:
        This routine does rely on the output format from the global GCM
        as specified first for the GEOS/Harvard CTM. However, it is
        designed to digest the output from all models currently used
        in DJJ's group.
        It uses the NL parameter to skip blocks between headers.

        The window offsets (I0, J0, L0) are set to
        zero, since the ASCII punch file is not set up to save
        a sub-region of the globe (bmy, 2/11/99)

 EXAMPLE:
              fileinfo = create3dfstru()   ; not required !
              fname = '~bmy/terra/CTM4/results/ctm.pch.m2'
              open_file,fname,ilun
              if (ilun gt 0) then $
                 result = ctm_read3dp_header(ilun,fileinfo,datainfo)
              print,result

        To get e.g. all scaling factors, type
              print,datainfo[*].scale

        To retrieve the header structure for one data block, type
              blocki = datainfo[i]

 MODIFICATION HISTORY:
        mgs, 21 Aug 1997: VERSION 1.00
        mgs, 02 Mar 1998: VERSION 1.10
                  - can handle GEOS output now
                  - reads in file header
                  - returns structure instead of string array
                  - always returns all entries, filtering must be done later
        mgs, 03 Mar 1998: - now returns a structure and is a function
        mgs, 04 Mar 1998: - toptitle is now default, changed keyword to
                    NO_TOPTITLE ; eliminated search for '!' or '%'
        mgs, 10 Mar 1998: - rewritten again, now with named structure
                    returned as DATAINFO. Skipping of data blocks
                    drastically improved by setting the file pointer
                    instead of reading the lines.
        mgs, 16 May 1998: - removed DATATYPE3DP function, set type tag to -1
                  - added EXTRA_SPACE option for GISS_II_PRIME output and
                    LINELENGTH keyword for full flexibility
                  - now ignores time series ('TS...') data
        mgs, 13 Aug 1998: - format string now composed here, not in
                    read3dp_data
        mgs, 14 Aug 1998: VERSION 2.00 - major changes!
                  - now requires open file and uses ILUN parameter
                  - automatic EXTRA_SPACE detection
                  - fileinfo structure not created any more, and only
                    extended if present (chkstru)
                  - error messages as dialog box
                  - LINELENGTH keyword removed
        mgs, 15 Aug 1998: - now calls select_model and inserts model
                    information in fileinfo structure
                  - gamap_cmn.pro included for default model name
                  - had to change DEBUG keyword into PRINT
        mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
        mgs, 26 Oct 1998: - now resets error state in no_dim
        mgs, 14 Jan 1998: - new lcount for line counting in error report
                  - linelength adjusted for working in Windows (CR/LF)
        bmy, 11 Feb 1999: VERSION 2.01
                  - Add window offsets (I0,J0,L0) to DATAINFO 
                  - save DATAINFO.TAU0 and DATAINFO.TAU1 as double precision
        bmy, 17 Feb 1999: VERSION 2.02
                  - changed to accommodate the FIRST field (instead of OFFSET)
                    of the DATAINFO structure, which contains
                    the I, J, L indices of the first grid box
        bmy, 01 Mar 1999: 
                  - bug fix!  NL needs to be a longword, so that
                    we can read 2 x 2.5 punch files correctly!! 
        mgs, 23 Mar 1999: 
                  - cleaned up reading of dimensions from label a little
        mgs, 27 May 1999: 
                  - new default number of records is 512 instead of 4096.
                  - bug fix: new records were never appended.
        mgs, 22 Jun 1999: 
                  - bug fix: "title" needed to be trimmed.
        bmy, 20 Jan 2000: FOR GAMAP VERSION 1.44
                  - !ERR is now replaced by !ERROR_STATE.CODE
                  - !ERR_STRING is now replaced by !ERROR_STATE.MSG
                  - I/O error trapping is now done by testing error
                    messages instead of testing for error numbers
                  - cosmetic changes, updated comments
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read3dp_header.pro)


CTM_READ_COARDS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_READ_COARDS

 PURPOSE:
        Reads data blocks from a COARDS-compliant netCDF file (such
        as created by routine BPCH2COARDS) into GAMAP.  CTM_READ_COARDS 
        is is an internal routine which is called by CTM_OPEN_FILE.

        NOTE: COARDS is a formatting standard for netCDF files which
        is widely used in both the atmospheric & climate communities.
        COARDS-compliant netCDF files can be read by GAMAP, GrADS and
        other plotting packages.
        
        See http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html
        for more information about the COARDS standard.

 CATEGORY:
        GAMAP Internals, Scientific Data Formats

 CALLING SEQUENCE:
        CTM_READ_COARDS, [, Keywords ]

 INPUTS:
        ILUN -> GAMAP file unit which will denote the netCDF file.

        FILENAME -> Name of the netCDF grid file to be read.
 
        FILEINFO -> Array of FILEINFO structures which will be
             returned to CTM_OPEN_FILE.  CTM_OPEN_FILE will 
             append FILEINFO to the GAMAP global common block.

        DATAINFO -> Array of DATAINFO structures (each element 
             specifies a GAMAP data block) which will be returned
             to CTM_OPEN_FILE.  CTM_OPEN_FILE will append FILEINFO 
             to the GAMAP global common block.        

 KEYWORD PARAMETERS:
        _EXTRA=e -> Picks up extra keywords

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        ====================================================
        CRC_Get_DimInfo        CRC_Get_IndexVars   
        CRC_Read_Global_Atts   CRC_Get_Tracer
        CRC_Get_Data           CRC_Save_Data

        External Subroutines Required:
        ====================================================
        CTM_GRID          (function)   CTM_TYPE (function)
        CTM_MAKE_DATAINFO (function)   STRRIGHT (function)
        STRREPL           (function)

 REQUIREMENTS:
        Requires routines from both GAMAP and TOOLS packages.

 NOTES:
        (1) Assumes that data blocks have the following dimensions:
            (a) longitude, latitude, time  
            (b) longitude, latitude, levels, time

        (2) Assumes that times are given in GMT.

        (3) If information about each tracer in the COARDS-compliant
            netCDF file is stored in the GAMAP "tracerinfo.dat" file, 
            then CTM_READ_COARDS will be able to read the file without 
            having to ask the user to supply a GAMAP category and
            tracer name.  
       
 EXAMPLE:
        ILUN     = 21
        FILENAME = 'coards.20010101.nc'
        CTM_READ_COARDS, ILUN, FILENAME, FILEINFO, DATAINFO

             ; Reads data from the COARDS-compliant netCDF file 
             ; coards.20010101.nc and stores it the FILEINFO and 
             ; DATAINFO arrays of structures.  If you are calling 
             ; CTM_READ_COARDS from CTM_OPEN_FILE, then CTM_OPEN_FILE 
             ; will append FILEINFO and DATAINFO to the GAMAP global
             ; common block.

 MODIFICATION HISTORY:
        bmy, 21 Mar 2005: GAMAP VERSION 2.03
        bmy, 21 Jul 2005: GAMAP VERSION 2.04
                          - bug fix in CRC_SAVE_DATA
        bmy, 06 Mar 2006: GAMAP VERSION 2.05
                          - minor bug fix in CRC_READ_GLOBAL_ATTS
                          - bug fix in CRC_SAVE_DATA: add a fake 4th
                            dim to DATA array if needed
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 16 Sep 2008: GAMAP VERSION 2.13
                          - Convert some global attributes to number
                            types in case attributes were initially
                            saved to the netCDF file as strings
        phs, 15 Sep 2009: - Added check on reading tracerinfo.dat
                          - Convert some tracer names created by
                            BPCH2COARDS to their original value.
        bmy, 14 Dec 2011: GAMAP VERSION 2.16
                          - Updated to read the GAMAP category value
                            from a netCDF variable attribute (if present)
        bmy, 19 Dec 2011: - Generalized to handle several different
                            vertical levels
        bmy, 21 Dec 2011: - Now will interpret netCDF attributes
                            "begin_date" and "begin_time" in the same
                            way as "start_date" and "start_time"
        bmy, 22 Dec 2011: - Now compute FIRST (nested datablock offsets)
                            properly for nested grids.  For now assume
                            that the data will always start on the first
                            vertical level.
                          - Bug fix: test for Latrev gt 0 to avoid
                            INADVERTENTLY reversing latitudes
        bmy, 03 Jan 2012: - Skip over Ap and Bp index arrays
                          - Now use better error checks for
                            the time and vertical level dimensions
                            for each tracer in the netCDF file.
        bmy, 05 Jan 2012: - Now interpret DELTA_TIME attribute
                            correctly when specified in hhmmss format.
        bmy, 10 Jan 2012: - Fix to interpret data blocks with multiple 
                            vertical dimensions in the same file 
        bmy, 13 Jan 2012: - When the time dimension in the netCDF
                            file is 1 (esp. when time is an UNLIMITED
                            variable, we need to add a fake dimension
                            of 1 back onto the data block to avoid
                            crashes.  This is a quirk in how the IDL
                            NCDF_VARGET function works.
        bmy, 23 Jan 2017: GAMAP VERSION 2.19
                          - Add modifications to read netCDF restart files

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_coards.pro)


CTM_READ_DATA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_READ_DATA

 PURPOSE:
        read in one data block from a global model punch file output
        (ASCII or binary)

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        CTM_READ_DATA,data,datainfo
        or:
        CTM_READ_DATA,data,ilun,filepos,xsize,ysize[,zsize,keywords]

 INPUTS:
        DATAINFO -> a datainfo structure as retrieved from
             CTM_OPEN_FILE. This is the easiest way to read 3D
             model output. Alternatively, the individual parameters
             can be specified as follows.
             
        ILUN  -> logical file unit of input file (must be opened before)
        FILEPOS -> a long word containing the start position of the data
             block to be read (normally retrieved by CTM_OPEN_FILE)
        XSIZE -> 1st dimension of the data array
        YSIZE -> 2nd dimension of the data array
        ZSIZE -> optional 3rd dimension of the data array

 KEYWORD PARAMETERS:
        Note: These keywords are ineffective when parameters are passed
        via the DATAINFO structure!

        SCALE -> apply scaling factor to data (default = 1.0)

        FORMAT -> string with format identifier for data block
             Default is '(12f6.2)'. Use '(8e10.3)' for BUDGETS output and
             '(12(f6.2,1x))' for "extra_space" output. Format='BINARY'
             indicates a binary file with REAL*4 data. (As long as the
             dimensions are specified correctly ANY binary file can
             be read this way, i.e. there is no need for additional 
             routines to read in e.g. gridded emission data files)

        RESULT -> will return 1 if successful, 0 otherwise

 OUTPUTS:
        DATA  -> a float array containing the block of data which is 
             either a 2D or a 3D array.

 SUBROUTINES:

 REQUIREMENTS:
        file must have been opened and file positions of the data block
        must be known (see CTM_OPEN_FILE)

 NOTES:
        The data array is *not* added to the datainfo structure! 

 EXAMPLE:
        ; Open a punch file interactively
        CTM_OPEN_FILE,'',fileinfo,datainfo

        ; Test if successful
        IF (not chkstru(datainfo)) then return

        ; Read in data of first data block
        CTM_READ_DATA,data,datainfo[0]

        ; This is equivalent to:
        CTM_READ_DATA,data,fileinfo.ilun,datainfo[0].filepos, $
             datainfo[0].dim[0],datainfo[0].dim[1],datainfo[0].dim[2], $
             scale=datainfo[0].scale,format=datainfo[0].format

 MODIFICATION HISTORY:
        mgs, 13 Aug 1998: VERSION 1.00 (from CTM_READ3DP_DATA)
                          - replaced EFORMAT keyword by more flexible 
                            FORMAT keyword (involves changes in 
                            CTM_READ3DP_HEADER and CREATE_3DHSTRU)
        mgs, 17 Aug 1998: VERSION 2.00
                          - now possible to pass DATAINFO structure
                          - made it necessary to place DATA argument 
                            as first parameter
        mgs, 19 Aug 1998: - added RESULT keyword
        mgs, 26 Oct 1998: - changed print statements to message
                          - user is now prompted when dimensions 
                            are not given
        bmy, 07 Apr 2000: - Added DAO keyword for reading in DAO met fields
        bmy, 11 Apr 2001: - now uses DATA = TEMPORARY( DATA ) * SCALE[0]
                            in order to prevent excess memory usage
        bmy, 19 Nov 2003: GAMAP VERSION 2.01
                          - Removed GMAO keyword, we now use the
                            FORMAT string to test for GMAO data files
  phs & bmy, 13 Jul 2007: GAMAP VERSION 2.10
                          - Modified for 4-D data blocks

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_data.pro)


CTM_READ_EOSGR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_READ_EOSGR

 PURPOSE:
        Reads data blocks from a HDF-EOS Grid file into GAMAP.
        (This is an internal routine which is called by CTM_OPEN_FILE.)
        
 CATEGORY:
        GAMAP Internals, Scientific Data Formats

 CALLING SEQUENCE:
        CTM_READ_EOSGR, ILUN, FILENAME, FILEINFO, DATAINFO, [, Keywords ]

 INPUTS:
        ILUN -> GAMAP file unit which will denote the HDF-EOS file.

        FILENAME -> Name of the HDF-EOS grid file to be read.
 
        FILEINFO -> Array of FILEINFO structures which will be
             returned to CTM_OPEN_FILE.  CTM_OPEN_FILE will 
             append FILEINFO to the GAMAP global common block.

        DATAINFO -> Array of DATAINFO structures (each element 
             specifies a GAMAP data block) which will be returned
             to CTM_OPEN_FILE.  CTM_OPEN_FILE will append FILEINFO 
             to the GAMAP global common block.
      
 KEYWORD PARAMETERS:
        _EXTRA=e -> Picks up any extra keywords

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        =====================================================
        CRE_Get_DimInfo   CRE_Get_TracerInfo   CRE_Save_Data

        External Subroutines Required:
        =====================================================
        CTM_GRID          (function)   CTM_TYPE (function)
        CTM_MAKE_DATAINFO (function)   STRRIGHT (function)

 REQUIREMENTS:
        Requires routines from both GAMAP and TOOLS packages.

 NOTES:
        (1) Currently is set up to read HDF-EOS files containing
            GMAO met data files.  You must have all possible met
            field names listed in your "tracerinfo.dat" file or 
            else you will get an "Invalid Selection" error.
                
 EXAMPLE:
        ILUN     = 21
        FILENAME = 'a_llk_03.tsyn2d_mis_x.t20030801'
        CTM_READ_EOSGR, ILUN, FILENAME, FILEINFO, DATAINFO

             ; Reads data from HDF-EOS file a_llk_03.tsyn2d_mis_x.t20030801
             ; and stores it the FILEINFO and DATAINFO arrays of
             ; structures.  If calling CTM_READ_GMI from CTM_OPEN_FILE,
             ; then CTM_OPEN_FILE will append FILEINFO and DATAINFO
             ; to the GAMAP common block.

 MODIFICATION HISTORY:
        bmy, 12 Nov 2003: GAMAP VERSION 2.01
                          - initial version
        bmy, 19 Feb 2004: GAMAP VERSION 2.01a
                          - added c402_rp_02 to the assim list
                          - bug fix: use DEFAULT keyword for SELECT_MODEL
        bmy, 09 Mar 2004: GAMAP VERSION 2.02
                          - now test for "GEOS3", "GEOS4" strings in
                            the file name to determine model type
                          - now undefine variables after use
                          - now make sure that data block begins at the
                            date line and has longitude values in the
                            range [-180,180] degrees.
                          - always ensure that L=1 is the surface level
        bmy, 25 Aug 2004: GAMAP VERSION 2.03
                          - Added c402_cer to the assim list
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Remove reference to unused SORT_STRU
        bmy, 05 Dec 2007: GAMAP VERSION 2.12
                          - Modified for DAS.llk.asm files
        bmy, 01 Oct 2008: GAMAP VERSION 2.13
                          - Increase DI, DJ in CRE_GET_DIMINFO for
                            the 0.5 x 0.667 grid
                          - Also now test for GEOS-5 in the filename
                            in CRE_GET_DIMINFO
                          - Bug fix in CRE_SAVE_DATA: If there is
                            only one data time in the HDF-EOS file,
                            then add an extra dimension to THISDATA
                            so that the CASE statement will be
                            interpreted properly.

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_eosgr.pro)


CTM_READ_GMAO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_READ_GMAO

 PURPOSE:
        Reads GMAO I-6,(instantaneous 6h), A-6 (average 6h),
        or A-3 (average 3-h) met field files, and constructs
        a DATAINFO structure for each met field.

 CATEGORY:
        GAMAP Internals
 
 CALLING SEQUENCE:
        Result = CTM_READ_GMAO( Ilun, FileInfo, DataInfo [, Keywords ] )

 INPUTS:
        ILUN --> The name of the input file (or a file mask).
             FILENAME is passed to OPEN_FILE.  If FILENAME is a null 
             string or a file mask, then OPEN_FILE will open a
             pickfile dialog box.

        FILEINFO --> a (single) fileinfo structure containing information
             about the (open) file (see CREATE3DFSTRU). FILEINFO also
             contains information about the model which generated
             the output (see CTM_TYPE)

        DATAINFO --> a named variable that will contain an array of
             structures describing the file content (see
             CREATE3DHSTRU)

 KEYWORD PARAMETERS:
        PRINT  -> if activated, print all headers found in the file

 OUTPUTS:
        The function returns 1 if successful, and 0 otherwise. 

        FILEINFO --> toptitle and modelinfo tags will be set

        DATAINFO --> contains an array of named structures 
             (see CREATE3DHSTRU) with all relevant information
             from the punch file header and what is needed to find
             and load the data.

 SUBROUTINES:
        Internal Subroutines:
        ================================================
        CRG_GET_MODELINFO

        External Subroutines Required:
        ================================================
        CHKSTRU  (function)     CTM_GRID      (function)
        CTM_TYPE (function)     CREATE3DHSTRU (function)
        

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.

 NOTES:
        (1) You must also add additional met field names to your
        "tracerinfo.dat" file as is neccesary.  CTM_READ_GMAO looks
        up met fields stored under the GAMAP categories "GMAO-2D"
        and "GMAO-3D$".

        (2) GEOS-4 met field files have an 8-char ident string 
        of the format "G4 45 19", where:

           (a) "G4" means that it is a GEOS-4 met field file/
           (b) "45" is the resolution code (in this case 4x5).
           (c) "19" is the number of met fields stored w/in the file.

        CTM_READ_GMAO will now set the modeltype and resolution from
        the information in this ident string.  For older met field 
        types (e.g. GEOS-3) which do not have this ident string,
        CTM_READ_GMAO will determine the modeltype and resolution 
        from the filename and date.

 EXAMPLES:
        FileInfo = CREATE3DFSTRU()   ; not required !
        FName    = '/r/amalthea/N/scratch/bmy/960101.a3.4x5'
        OPEN_FILE, FName, Ilun, /F77_Unformatted   
        if ( Ilun gt 0 ) $
            then Result = CTM_READ_GMAO( Ilun, FileInfo, DataInfo )
        print,result

 MODIFICATION HISTORY:
        bmy, 16 May 2000: GAMAP VERSION 1.45
                          - adapted from original program "read_gmao"
        bmy, 12 Jun 2000: - declare XYMD and XHMS as integers for
                            GEOS-2 and GEOS-3 data
        bmy, 28 Jul 2000: GAMAP VERSION 1.46
                          - added GEOS-3 names to list of recognized fields
                          - deleted a couple of field names we don't use 
        bmy, 25 Sep 2000: - added new field: SLP (sea level pressure)
        bmy, 08 Dec 2000: GAMAP VERSION 1.47
                          - added new fields: TKE, RH, KH
        bmy, 07 Mar 2001: - added new fields: CLDTMP, TPW
        bmy, 25 Apr 2001: - added new fields: TAULOW, TAUMID, TAUHI
        bmy, 26 Jul 2001: GAMAP VERSION 1.48
                          - added new field: T2M
        bmy, 15 Aug 2001: - added new field: OPTDEPTH
        bmy, 06 Nov 2001: GAMAP VERSION 1.49
                          - added new field: DELP
                          - changed units from "mb" to "hPa"
        bmy, 29 Jan 2002: GAMAP VERSION 1.50
                          - added new field: GWET
                          - removed obsolete code from 11/6/01
        bmy, 01 May 2002: - added GWETTOP as synonym for GWET
                          - now assign correct units for fvDAS/GEOS-4
                            CLDMAS and DTRAIN fields: kg/m2/s
                          - now assign correct units for fvDAS/GEOS-4
                            PBL field: m (instead of hPa)
        bmy, 17 Jul 2002: GAMAP VERSION 1.51
                          - added PBLH, Z0M, Z0H fields for fvDAS/GEOS-4
        bmy, 16 Dec 2002: GAMAP VERSION 1.52:
                          - added new fvDAS fields: CMFDTR, CMFETR,
                            ZMDU, ZMED, ZMEU, ZMMD, ZMMU, HKETA, HKBETA
        bmy, 21 May 2003: GAMAP VERSION 1.53:
                          - added T, U, V as synonyms of TMPU, UWND, VWND
                          - added Q as a synonym of SPHU
                          - removed CMFDTR, CMFETR fields
                          - HKBETA is now #18; HKETA is now #19
                          - updated comments
                          - added EVAP field as tracer #28 
                          - TGROUND and T2M are now tracers #29, #30
                          - LAI is now tracer #31
                          - PARDF, PARDR are now tracers #32, 33
        bmy, 30 Jul 2003: - added TSKIN as a synonym for TGROUND
        bmy, 12 Dec 2003: GAMAP VERSION 2.01
                          - renamed to CTM_READ_GMAO to reflect the
                            change of name from "DAO" to "GMAO".
                          - GMAO binary files now have FILETYPE=104
                          - Rewrote so that we don't have to hardwire
                            met field names...it now gets the met
                            field names from "tracerinfo.dat"
                          - Now gets modeltype and resolution info
                            from GEOS-4 ident string 
                          - Added internal function CRG_GET_MODELINFO
                            to generate the MODELINFO structure based
                            on the filename and date. 
                          - Improved error output if we can't find
                            the tracer name
  bmy & phs, 03 Aug 2007: GAMAP VERSION 2.10
                          - Ident string value "56" now will specify
                            a grid with 0.5 x 0.666 degree resolution
                          - Ident string value "10" now will specify
                            a grid with 1.0 x 1.0 degree resolution
                          - Now don't reset ILUN for GEOS-5 files
                          - Now call EXTRACT_FILENAME in CRG_GET_MODELINFO
                            to get just the filename instead of the full
                            path name.
                          - Adjusted for GEOS-5 fields with LMX+1 levels
                          - Bug fix: set null strings if GMAO-2D and/or
                            GMAO-3D$ categories aren't found
                          - Bug fix: change "gt" to "ge" in IF statements
                            where NAME2D, NAME3D, etc. are defined.
                          - Now use IS_EDGED
                          - Added routine CRG_GET_HORZDIM to return NI,
                            NJ, NL, FIRST for global or nested grids.
        bmy, 06 Aug 2010: GAMAP VERSION 2.14
                          - Now check for MERRA grid.  This is
                            identical to GEOS-5, but retains the
                            "MERRA" name for clarity. 
        bmy, 11 Aug 2010: - Bug fix: define STRUC array of structures
                            with 1024 entries.  512 is not enough for
                            the hourly MERRA data.              
        bmy, 17 Aug 2010: - Bug fix: define STRUC array of structures
                            with 2048 entries.  1024 may not be
                            enough for the hourly MERRA data.              
  

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_gmao.pro)


CTM_READ_GMI

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_READ_GMI

 PURPOSE:
        Reads data blocks from a GMI netCDF file into GAMAP.
        (This is an internal routine called from CTM_OPEN_FILE.)

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        CTM_READ_GMI, ILUN, FILENAME, FILEINFO, DATAINFO, [, Keywords ]

 INPUTS:
        ILUN -> GAMAP file unit which will denote the GMI netCDF file.

        FILENAME -> Name of the GMI netCDF grid file to be read.
 
        FILEINFO -> Array of FILEINFO structures which will be
             returned to CTM_OPEN_FILE.  CTM_OPEN_FILE will 
             append FILEINFO to the GAMAP global common block.

        DATAINFO -> Array of DATAINFO structures (each element 
             specifies a GAMAP data block) which will be returned
             to CTM_OPEN_FILE.  CTM_OPEN_FILE will append FILEINFO 
             to the GAMAP global common block.

 KEYWORD PARAMETERS:
        _EXTRA=e -> Picks up extra keywords
 
 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        ===============================================
        CRG_Debug_Print   CRG_Get_Name   CRG_Get_Tau0       
        CRG_Get_Tracer    CRG_Get_Data   CRG_Save_Data

        External Subroutines Required:
        ===============================================
        CTM_GRID (function)   CTM_TYPE (function)
        NCDF_GET (function)   TVMAP

 REQUIREMENTS:
        Requires routines from both GAMAP and TOOLS packages.

 NOTES:
        (1) Currently is hardwired to reading in data blocks 
            from netCDF files created for the GMI comparison
            study.  It is difficult to create a general netCDF
            reader since there are many different ways to store
            data w/ in a netCDF file.

 EXAMPLE:
        ILUN     = 21
        FILENAME = 'gmit4_maccm3_year_CO.nc'
        CTM_READ_GMI, ILUN, FILENAME, FILEINFO, DATAINFO

             ; Reads data from the netCDF file gmit4_maccm3_year_CO.nc
             ; and stores it the FILEINFO and DATAINFO arrays of
             ; structures.  If calling CTM_READ_GMI from CTM_OPEN_FILE,
             ; then CTM_OPEN_FILE will append FILEINFO and DATAINFO
             ; to the GAMAP common block.
 
 MODIFICATION HISTORY:
        bmy, 05 Nov 2003: GAMAP VERSION 2.01
                          - initial version
        bmy, 13 Feb 2004: GAMAP VERSION 2.01a
                          - bug fix: now should get multiple months
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_gmi.pro)


CTM_READ_MULTILEVEL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_READ_MULTILEVEL

 PURPOSE:
        Read all levels of a multilevel diagnostic (e.g. IJ-AVG-$)
        and return a 3D data block. The associated datainfo structure
        must be created before and passed into this routine.
        This is an internal procedure which should not be used
        directly.

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        CTM_READ_MULTILEVEL,data,datainfo, $
                   Use_DataInfo=Use_DataInfo, $
                   Use_FileInfo=Use_FileInfo, $
                   result=result

 INPUTS:
        DATAINFO -> The datainfo structure that is to hold the new 
             3D data block.

 KEYWORD PARAMETERS:
        USE_DATAINFO, USE_FILEINFO -> The array of Datainfo and Fileinfo
             stuctures to select from. Unlike the higher level routines,
             CTM_READ_MULTILEVEL does not provide default values for 
             these! 

        RESULT -> A named variable that will be 1 if successful, 
             0 otherwise.

 OUTPUTS:
        DATA -> The 3D data block composed of the individual levels
             from the ASCII punch file. 

 SUBROUTINES:
        External Subroutines Required:
        ===========================================
        EXPAND_CATEGORY     CTM_DIAGINFO
        CTM_DOSELECT_DATA   CTM_READ_DATA

 REQUIREMENTS:
        Requires routines from both GAMAP and TOOLS packages.

 NOTES:
        The dimensional information of the DATAINFO parameter is 
        adapted to the number of levels actually read from disk.

 EXAMPLE:
        See source code of CTM_RETRIEVE_DATA

 MODIFICATION HISTORY:
        mgs, 19 Aug 1998: VERSION 1.00
        mgs, 26 Oct 1998: - made more error tolerant: 
                            = if file ends within record, now returns 
                              what's there
                            = if no dimensions were read, 
                              assumes 72x46 and prints warning
                            = added status keyword
        mgs, 10 Nov 1998: VERSION 3.00
                          - major design change
        mgs, 28 Nov 1998: - hopefully fixed scaling bug now
        bmy, 19 Nov 2003: GAMAP VERSION 2.01
                          - Now get diagnostic spacing from CTM_DIAGINFO
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_multilevel.pro)


CTM_READ_MULTITRACER

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_READ_MULTITRACER

 PURPOSE:
        Read all entries of a 'multitracer' diagnostic (i.e.
        source type diagnostic) and return a 3D data block.
        The associated datainfo structure must be created before 
        and passed into this routine. This routien is meant for
        internal use in the CTM_GET_DATA routines.

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        CTM_READ_MULTITRACER,data,datainfo, $
                   Use_DataInfo=Use_DataInfo,  $
                   Use_FileInfo=Use_FileInfo,  $
                   result=result,debug=debug

 INPUTS:
        DATAINFO -> The datainfo structure that is to hold the new
             3D data block. 

 KEYWORD PARAMETERS:
        USE_DATAINFO, USE_FILEINFO -> The array of Datainfo and Fileinfo
             stuctures to select from. Unlike the higher level routines,
             CTM_READ_MULTILEVEL does not provide default values for
             these!

        RESULT -> A named variable that will be 1 if successful, 
             0 otherwise.

 OUTPUTS:
        DATA -> The 3D data block composed of the individual levels
             from the ASCII punch file.

 SUBROUTINES:

 REQUIREMENTS:
        Uses CTM_DOSELECT_DATA, CTM_READ_DATA

 NOTES:
        The dimensional information of the DATAINFO parameter is
        adapted to the number of levels actually read from disk.

 EXAMPLE:
        See source code of CTM_***

 MODIFICATION HISTORY:
        mgs, 19 Aug 1998: VERSION 1.00
        mgs, 26 Oct 1998: made more error tolerant:
             - if file ends within record, now returns what's there
             - if no dimensions were read, assumes 72x46 and prints warning
        mgs, 10 Nov 1998: VERSION 3.00
             - major design change
        mgs, 28 Nov 1998: 
             - hopefully fixed scaling bug now
  bmy & phs: 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_multitracer.pro)


CTM_READ_NCDF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_READ_NCDF

 PURPOSE:
        Reads data blocks from a netCDF file created by routine
        BPCH2NC or BPCH2GMI into GAMAP.  (This is an internal routine 
        which is called by CTM_OPEN_FILE.)

 CATEGORY:
        GAMAP Internals, Scientific Data Formats

 CALLING SEQUENCE:
        CTM_READ_NCDF, [, Keywords ]

 INPUTS:
        ILUN -> GAMAP file unit which will denote the netCDF file.

        FILENAME -> Name of the netCDF grid file to be read.
 
        FILEINFO -> Array of FILEINFO structures which will be
             returned to CTM_OPEN_FILE.  CTM_OPEN_FILE will 
             append FILEINFO to the GAMAP global common block.

        DATAINFO -> Array of DATAINFO structures (each element 
             specifies a GAMAP data block) which will be returned
             to CTM_OPEN_FILE.  CTM_OPEN_FILE will append FILEINFO 
             to the GAMAP global common block.        

 KEYWORD PARAMETERS:
        _EXTRA=e -> Picks up extra keywords

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        ====================================================
        CRN_Get_DimInfo       CRN_Get_Time   CRN_Get_Tracer     
        CRN_Read_Global_Atts  CRN_Get_Data   CRN_Save_Data

        External Subroutines Required:
        ====================================================
        CTM_GRID          (function)   CTM_TYPE (function)
        CTM_MAKE_DATAINFO (function)   STRRIGHT (function)

 REQUIREMENTS:
        Requires routines from both GAMAP and TOOLS packages.

 NOTES:
        (1) Currently assumes that the netCDF file was written
            by GAMAP routine BPCH2NC.

 EXAMPLE:
        ILUN     = 21
        FILENAME = 'geos.20010101.nc'
        CTM_READ_NCDF, ILUN, FILENAME, FILEINFO, DATAINFO

             ; Reads data from the netCDF file geos.20010101.nc
             ; and stores it the FILEINFO and DATAINFO arrays of
             ; structures.  If calling CTM_READ_GMI from CTM_OPEN_FILE,
             ; then CTM_OPEN_FILE will append FILEINFO and DATAINFO
             ; to the GAMAP common block.

 MODIFICATION HISTORY:
        bmy, 05 Nov 2003: GAMAP VERSION 2.01
                          - initial version
        bmy, 26 Mar 2004: GAMAP VERSION 2.02
                          - bug fix: now correctly separates "__"
                            in netCDF tracer names with STRPOS
        bmy, 28 Feb 2005: GAMAP VERSION 2.03
                          - bug fix: now also exclude ETAC from
                            being passed to CRN_GET_TRACER
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Modified to read files from BPCH2GMI
        bmy, 19 Dec 2007: GAMAP VERSION 2.12
                          - Now also skip ETAE, SIGE arrays
                          - Also don't add any vertical info to 
                            the GRIDINFO structure if NLAYERS=1
        bmy, 24 Jan 2011: GAMAP VERSION 2.15
                          - Now skip over Ap and Bp index fields
                            in the netCDF file
        bmy, 14 Dec 2011: GAMAP VERSION 2.16
                          - Now also check to see if the GAMAP
                            category string is passed via the netCDF
                            "gamap_category" attribute

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_read_ncdf.pro)


CTM_READ_PLANEFLIGHT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_READ_PLANEFLIGHT

 PURPOSE:
        Reads GEOS-CHEM plane flight diagnostic (ND40) data.  

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        RESULT = CTM_READ_PLANEFLIGHT( FILENAME )

 INPUTS:
        FILENAME -> Name of the file containing data from the GEOS-CHEM
             plane following diagnostic ND40.  If FILENAME is omitted,
             then a dialog box will prompt the user to supply a file name.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> Array of structures containing data from read from
             the input file.  Each different plane type will have 
             a structure in RESULT containing the following tags:
 
             NPOINTS  : Number of points read from the file 
             NVARS    : Number of variables read from the file
             PLATFORM : Name of plane type (e.g. DC8, P3B, FALCON)
             DATE     : Array w/ YYYYMMDD  at each flight point [GMT date]
             TIME     : Array w  HHMM      at each flight point [GMT time]
             LAT      : Array w/ latitude  at each flight point [degrees ]
             LON      : Array w/ longitude at each flight point [degrees ]   
             PRESS    : Array w/ pressure  at each flight point [hPa     ]
             VARNAMES : Array w/ names of each variable 
             DATA     : Array w/ data for each variable

 SUBROUTINES:

        External Subroutines Required:
        ==========================================
        OPEN_FILE   STRBREAK (function)  UNDEFINE

 REQUIREMENTS:
        None

 NOTES:
        We read the data into arrays first, and then save the arrays
        into an IDL structure.  If you read the data into an array of
        structures, this executes much more slowly.  Also arrays of
        structures seem to suck up an inordinate amount of memory.

 EXAMPLES:
        PLANEINFO = CTM_READ_PLANEFLIGHT( 'plane.log.20040601' )
             ; Reads data from file into the PLANEINFO structure

        DC8 = WHERE( PLANEINFO[*].PLATFORM eq 'DC801' )
             ; Look for DC8 data

        PRINT, PLANEINFO[DC8].LAT[*]
        PRINT, PLANEINFO[DC8].LON[*]
             ; Prints latitudes and longitudes of DC8 to the screen

        IND = WHERE( PLANEINFO[DC8].VARNAMES eq 'TRA_004' )
        CO  = PLANEINFO[DC8].DATA[ *, IND ]
             ; Extracts CO (tracer #4 in a GEOS-CHEM fullchem
             ; simulation) to an array

        IND  = WHERE( PLANEINFO[DC8].VARNAMES eq 'GMAO_UWND' )
        UWND = PLANEINFO[DC8].DATA[ *, IND ]
             ; Extracts U-wind information to an array 

 MODIFICATION HISTORY:
        bmy, 23 Mar 2005: GAMAP VERSION 2.03
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_read_planeflight.pro)


CTM_REGRIDH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_REGRIDH

 PURPOSE:
        Regrids data horizontally from one CTM grid to another, 
        for both cases:

           (1) fine grid    -->  coarse grid  OR
           (2) coarse grid  -->  fine grid

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        NEWDATA = CTM_REGRIDH( DATA, OLDGRID, NEWGRID [ , Keywords ] )

 INPUTS:
        DATA -> a 2-D or 3-D data field to be regridded.  DATA can be
             either in single-precision or double-precision.  

        OLDGRID, NEWGRID -> GRIDINFO structures (use "ctm_grid.pro" 
             to create one) defining the old and new grids.

 KEYWORD PARAMETERS:
        /DOUBLE -> If set, will return NEWDATA as a double-precision
             array.  Default is to return NEWDATA as a floating-point
             single-precision array.

        /PER_UNIT_AREA -> Set this switch if the quantity you want to
             regrid is per unit area or per unit volume (i.e. molec/cm2, 
             molec/cm3, kg/m2, etc.).  CTM_REGRIDH will multiply by
             the input grid's surface areas, so as to convert it to
             an area-independent quantity for regridding.  After the 
             regridding, CTM_REGRIDH will then divide the quantity
             by the surface areas on the new grid.  

        /USE_SAVED_WEIGHTS -> If set, will use the mapping weights
             saved by a prior call to CTM_REGRIDH.  This is useful
             if you are regridding 3-D data, thus CTM_REGRIDH can be
             told only to compute the mapping weights for the first
             level, thus saving processing time.

        /VERBOSE -> If set, will echo informational messages to the
             screen during the regridding process.  Totals on both
             old and new grids will also be printed.

        WFILE -> Name of the file with pre-saved mapping weights from
             the old grid to the new grid (created by CTM_GETWEIGHT).
             If WFILE is not specified, then CTM_REGRIDH will compute 
             the mapping weights on the fly.  These weights will be
             returned to the calling program via the WEIGHT keyword
             for use on subsequent calls to CTM_REGRIDH.  

 OUTPUTS:
        NEWDATA -> a 2-D or 3-D array containing the regridded data.

 SUBROUTINES:
        Internal Subroutines Included:
        =================================================
        CRH_GETWEIGHT 

        External Subroutines Required:
        =================================================
        CHKSTRU  (function)   CTM_BOXSIZE (function)   
        CTM_GETWEIGHT         UNDEFINE
       
 REQUIREMENTS:
        References routines from the GAMAP and TOOLS packages.

 NOTES:
        (1) CTM_REGRIDH now supersedes CTM_REGRID.  The old
            CTM_REGRID program worked fine, but could only 
            go from fine grids to coarse grids.

        (2) Assumes that you are passing globally-sized arrays.
            If you have less than global-sized data, then you 
            must add that data to a globally sized array, and
            then call CTM_REGRIDH.    

 EXAMPLE:
        (1)

        ; Define old grid
        OLDTYPE    = CTM_TYPE( 'GENERIC',    RES=[1,1], $
                                HALFPOLAR=0, CENTER180=0 )
        OLDGRID    = CTM_GRID( OLDTYPE )

        ; Define new grid
        NEWTYPE    = CTM_TYPE( 'GEOS_STRAT', RES=4 )
        NEWGRID    = CTM_GRID( NEWTYPE )

        ; Regrid data
        NEWDATA = CTM_REGRIDH( DATA, OLDGRID, NEWGRID, $
                               /PER_UNIT_AREA, /VERBOSE )

             ; Regrids a quantity such as fossil fuel emissions 
             ; in [molec/cm2/s] from the generic 1 x 1 emissions
             ; grid to GEOS-STRAT 4 x 5 resolution.  Message info 
             ; will be echoed to the screen during the regridding.
             ; The mapping weights from OLDGRID to NEWGRID will
             ; be computed by CTM_REGRIDH and stored internally
             ; for possible future use.  

        (2)

        ; Define old grid
        OLDTYPE  = CTM_TYPE( 'GEOS_STRAT', RES=2 )
        OLDGRID  = CTM_GRID( OLDTYPE )

        ; Define new grid
        NEWTYPE  = CTM_TYPE( 'GEOS_STRAT', RES=4 )
        NEWGRID  = CTM_GRID( NEWTYPE )

        ; Regrid first data array, read mapping weights from disk
        NEWDATA1 = CTM_REGRIDH( DATA1, OLDGRID, NEWGRID, $
                                WFILE='weights_generic1x1_geos4x5.dat' )

        ; Regrid second data array, use weights from prior call
        NEWDATA2 = CTM_REGRIDH( DATA2, OLDGRID, NEWGRID, $
                               /USE_SAVED_WEIGHTS )

             ; Regrids quantities such as air mass in [kg] from
             ; 2 x 2.5 resolution to 4 x 5 resolution for the
             ; GEOS-STRAT grid.  Since WFILE is specified,
             ; will read the mapping weights between OLDGRID and 
             ; from a file on disk instead of having to compute
             ; them online.  These mapping weights will then be
             ; saved internally for possible future use.
             ;
             ; Note that you can specify that you want to use the
             ; pre-saved with the /USE_SAVED_WEIGHTS flag.  This 
             ; prevents CTM_REGRIDH from having to re-read the 
             ; mapping weights all over again -- a real timesaver.

 MODIFICATION HISTORY:
        bmy, 13 Feb 2002: GAMAP VERSION 1.50
                          - adapted from CTM_REGRID plus 
                            other various existing codes
        bmy, 16 Jan 2003: GAMAP VERSION 1.52
                          - fixed a small bug which prevented flagging
                            coarse --> fine regridding when going from
                            1 x 1.25 to 1 x 1
        phs, 24 Oct 2005: GAMAP VERSION 2.05
                          - Fix the Coarse-to-Fine case. Works as
                            expected for both PER_UNIT_AREA=1 and =0.
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
     jintai, 14 Apr 2010: GAMAP VERSION 2.14
                          - Added fix for NaN's

(See /n/home09/ryantosca/IDL/gamap2/regridding/ctm_regridh.pro)


CTM_RESEXT

[Previous Routine] [Next Routine] [List of Routines]
 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)


CTM_RESTART_O3

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_RESTART_O3

 PURPOSE:
        Merges single-tracer Ox data into a full-chemistry
        CTM restart file.

 CATEGORY:
        GAMAP Utilities

 CALLING SEQUENCE:
        CTM_RESTART_O3 [, BATCHFILE [, Keywords ] ]

 INPUTS:
        BATCHFILE (optional) -> Name of the input file containing
             the names of the full chemistry restart file, the
             single tracer O3 file, the annual mean tropopause file,
             and the output file.  If BATCHFILE is omitted, then the
             user will be prompted to make a selection via a dialog box.

 KEYWORD PARAMETERS:
        /STRAT_ONLY -> Set this keyword to only merge the stratospheric
             Ox into the full chemistry restart file.  Stratospheric 
             levels are determined by reading in the annual mean 
             tropopause file (as specified in BATCHFILE).  Default is
             to merge all levels into the full chemistry restart file.

 OUTPUTS:
        Will write merged data to an output file whose name is
        specified in BATCHFILE.

 SUBROUTINES:
        External subroutines required:
        ------------------------------------------------------
        CTM_GRID     (function)  CTM_GET_DATABLOCK (function)
        CTM_GET_DATA             OPEN_FILE
        STR2BYTE     (function)

 REQUIREMENTS:
        None

 NOTES:
        CTM_RESTART_O3 is currently only applicable to the GEOS-CTM,
        since this is the only model that can run single tracer Ox.

        A Sample BATCHFILE is given below.  There must be 3 header 
        lines before the first file name:

CTM_RESTART_O3.DAT -- defines filenames to read in for merging single 
                      tracer Ox data into a full chem restart file
=============================================================================
Full Chem File : /r/amalthea/N/scratch/bmy/run_3.2/gctm.trc.941001
Ox Run File    : /r/amalthea/N/scratch/bmy/run_o3_3.2/gctm.trc.941001
T-Pause File   : /r/amalthea/Li/data/ctm/GEOS_4x5/ann_mean_trop.geos1.4x5
Output File    : /scratch/bmy/gctm.trc.941001.new
=============================================================================

 EXAMPLE:
        CTM_RESTART_O3, 'filenames.dat', /STRAT_ONLY
             
             ; Will merge stratospheric single tracer Ox into the 
             ; full chemistry restart file.  Input and output file
             ; names are given in "filenames.dat".

 MODIFICATION HISTORY:
        bmy, 17 Feb 2000: VERSION 1.45
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_restart_o3.pro)


CTM_RETRIEVE_DATA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_RETRIEVE_DATA

 PURPOSE:
        Read one "compound" data block from disk. The datainfo
        parameter must contain only one entry, and it must have
        status=0. The data pointer is assumed to be NULL.
        If requested data block is a multilevel or multitracer 
        diagnostics, the routine will search all individual data 
        records that belong to that block and loop over them
        (this is actually done in ctm_read_multilevel and 
        ctm_read_multitracer).

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        CTM_RETRIEVE_DATA,DataInfo,DiagStru,  $
                  Use_DataInfo=Use_DataInfo,  $
                  Use_FileInfo=Use_FileInfo,  $
                  result=result

 INPUTS:
        DataInfo -> DataInfo structure that is to hold the data.
            Normally, this is either created in CTM_GET_DATA for
            multilevel or multitracer diagnostics, or it is created
            upon parsing the header information (ctm_read3d?_header).

        DIAGSTRU -> A (single) diagnostic structure containing
            information what to load (see CTM_DIAGINFO)

 KEYWORD PARAMETERS:
        USE_DATAINFO, USE_FILEINFO -> The array of Datainfo and Fileinfo
             stuctures to select from. Unlike the higher level routines,
             CTM_READ_MULTILEVEL does not provide default values for
             these!

        RESULT -> A named variable that will be 1 if successful,
             0 otherwise.

 OUTPUTS:
        The DATAINFO structure will contain the correct dimensional
        information, the status will be set to 1, and the data pointer
        points to a 2D or 3D data array. (if reading was successful)

 SUBROUTINES:

 REQUIREMENTS:
        Uses CTM_DOSELECT_DATA, CTM_READ_MULTILEVEL, 
             CTM_READ_MULTITRACER, CTM_READ_DATA,
             gamap_cmn.pro

 NOTES:
        This routine is meant for internal use from CTM_GET_DATA.

 EXAMPLE:

 MODIFICATION HISTORY:
        mgs, 19 Aug 1998: VERSION 1.00
        mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
        mgs, 22 Oct 1998: - scale factor set to 1 after unit scaling
                            is applied for multi...
                          - tracername and unit setting now also done
                            for non-multi fields
        mgs, 26 Oct 1998: - added status keyword. If used (0,1,or 2)
                            no data will be read but datainfo record 
                            will be prepared as usual.
        mgs, 04 Nov 1998: - bug fix for reading of 2D arrays. Now return
                            correct (offset) tracer number
        mgs, 10 Nov 1998: VERSION 3.00
                          - major design change 
        mgs, 28 Nov 1998: - hopefully fixed scaling bug now!
        bmy, 07 Apr 2000: - now can read DAO met field files
        bmy, 21 Nov 2003: GAMAP VERSION 2.01
                          - Removed GMAO keyword in call to
                            CTM_READ_DATA
        bmy, 23 Aug 2004: GAMAP VERSION 2.03 
                          - Now account for single-point data blocks
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_retrieve_data.pro)


CTM_SELECT_DATA (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_SELECT_DATA (function)

 PURPOSE:
        Provide a user-friendly function to extract data
        from a DATAINFO structure. The function returns an 
        index to the given DATAINFO structure which points
        to all recored that fulfill the specified conditions.

 CATEGORY:
        GAMAP Internals, GAMAP Data Manipulation

 CALLING SEQUENCE:
        index = CTM_SELECT_DATA(DIAGN[,DATAINFO,keywords])

 INPUTS:
        DIAGN -> A diagnostic number or category name. Only one
            diagnostic can be extracted at the same time. Complete
            information about the requested diagnostic is returned 
            via the DIAGSTRU keyword. (see also CTM_DIAGINFO)

        DATAINFO -> An [optional] subset of the global DataInfo
            structure. As default, CTM_SELECT_DATA operates on
            the global DATAINFO structure (see gamap_cmn.pro) scanning
            all files that have been opened.

 KEYWORD PARAMETERS:
        ILUN -> A logical unit value or an array of logical unit
            values. Only recored from these files will be returned.
            Default is to use all files.
            A link between logical unit numbers and filenames can be
            made through the (global) FileInfo structure (see gamap_cmn.pro)

        TRACER -> A tracer number or an array of tracer numbers to
            restrict the selection of data records. Default is to
            return information about all tracers. 
            Tracer numbers less than 100 are automatically expanded
            to include the offset of certain diagnostics (see
            CTM_DIAGINFO and CTM_DOSELECT_DATA).

        TAU -> A time value (tau0 !) or an array of time values
            to restrict the selection of data records. Default is to
            return information about all time steps. (see also example)

        LEVELRANGE -> A 1 or 2 element vector with a level index or 
            a range of level indices for multilevel diagnostics
            (e.g. 'IJ-AVG$'). As default, information is returned
            about full 3D data blocks only. See also 
            EXPAND keyword.

        /EXPAND -> If set, multilevel diagnostic fields are
            expanded to return the individual layers in addition to
            the complete 3D cube.
        
        DATA -> A named variable that will contain an array with
            pointers to the indexed data blocks. Note that some may
            be NIL pointers if the STATUS value is 0 or 2.

        COUNT -> A named variable that will return the number of
            data blocks found with the given selection criteria
 
        DIAGSTRU -> A named variable that will contain complete 
            information about the requested diagnostics (see
            CTM_DIAGINFO)

        STATUS -> Restricts the data selection to
            Data that has not been read  (STATUS = 0)
            Data that has been read      (STATUS = 1, default)
            All data blocks              (STATUS = 2)
            If STATUS is 1, all pointers returned in DATA are valid.

 OUTPUTS:
        The function returns an (long) integer array that contains
        index values to all the data blocks that match the selection 
        criteria. If no data is found, -1 is returned.

 SUBROUTINES:

 REQUIREMENTS:
        Uses CTM_DOSELECT_DATA, EXPAND_CATEGORY, gamap_cmn.pro,
             GAMAP_INIT, CTM_DIAGINFO

 NOTES:
        This function acts for the most part as a convenient user
        interface to CTM_DOSELECT_DATA which performs the actual
        selection process and contains only minimal error checking.
        For programming purposes, use CTM_DOSELECT_DATA when possible.

 EXAMPLE:
        ; open a CTM punch file
        CTM_OPEN_FILE

        ; Read diagnostic number 45 for all tracers and time steps
        CTM_READ_DATA,45

        ; Select data for tracer 1 and diagnostics 45 
        index = CTM_SELECT_DATA(45,tracer=1,data=pdata)

        ; De-reference the data pointer for the first record
        ; (usually the first timestep)
        if (index[0] ge 0) then data = (*pdata)[0] 

        ; find data for a specific time range
        DataInfo = (*pGlobalDataInfo)[index]
        taus = where(DataInfo.tau0 ge 77666L AND DataInfo.tau1 le 78888L)
        taus = DataInfo.tau0[taus]
        index = CTM_SELECT_DATA(45,DataInfo,tracer=1,tau=taus,data=pdata)
        

 MODIFICATION HISTORY:
        mgs, 19 Aug 1998: VERSION 1.00
        mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
        mgs, 07 Oct 1998: - removed obsolete FILEINFO parameter
                          - changed NO_EXPAND to EXPAND
        bmy, 19 Nov 2003: GAMAP VERSION 2.01
                          - Now get spacing between diagnostic offsets
                            from CTM_DIAGINFO and pass to CTM_DOSELECT_DATA
                          - Now use the /NO_DELETE keyword in the
                            call to routine EXPAND_CATEGORY
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_select_data.pro)


CTM_SUM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_SUM

 PURPOSE:
        Calculate the sum of several CTM output data blocks
        and store them in a new datainfo structure as "derived 
        data".  The user can select data blocks by diagnostics,
        tracer, tau0, or logical unit of the source file.  With 
        the AVERAGE keyword averages will be computed instead of
        totals.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        CTM_SUM [, DIAGN ] [, Keywords ]

 INPUTS:
        DIAGN -> The diagnostic category name.  Default is 'IJ-AVG-$'

 KEYWORD PARAMETERS:
        TRACER -> Tracer number(s) to look for.

        TAU0 -> beginning of time step to look for. You can
            specify a date using function nymd2tau(YYMMDD,HHMMSS)

        ILUN -> If you want to restrict summation to datablocks from
            one particular file, set the ILUN keyword to the 
            respective logical unit number.  ILUN and FILENAME are
            mutually exclusive.  If you select FILENAME then ILUN 
            will be ignored.

        FILENAME -> Instead of ILUN you may pass the name of a
            CTM data file containing data blocks to be summed.
            FILENAME and ILUN are mutually exclusive.  If you 
            select FILENAME then ILUN will be ignored.

        NEWTRACER -> Tracer number for the new tracer. Default is 
            to use the same number as the tracer in the first 
            selected data block.

        NEWTAU0 -> A new pair of values for the time stamp. Default 
            is to use the minimum tau0 and maximum tau1 from the 
            selected data blocks. If only one value is passed (tau0),
            then tau1 will be set to tau0+1.

        /AVERAGE -> set this keyword to compute a (simple) average
            instead of the total.

 OUTPUTS:
        This routne produces no output but stores a new datainfo 
        and fileinfo structure into the global arrays.

 SUBROUTINES:
        uses gamap_cmn, ctm_get_data, ctm_grid, and ctm_make_datainfo

 REQUIREMENTS:
        None

 NOTES:
        All data blocks must originate from compatible models.
        No test can be made whether an identical addition had been
        performed earlier. Hence, it is a good idea to test the
        existence of the "target" record before in order to avoid 
        duplicates.

 EXAMPLE:
        (1) 
        CTM_GET_DATA, DATAINFO, 'IJ-AVG-$', $
          TRACER=1, TAU0=NYMD2TAU( 940301L )

        IF (N_ELEMENTS(DATAINFO) EQ 0) THEN $
           CTM_SUM, 'IJ-AVG-$', TRACER=[1,2,3,4,5],  $
              TAU0=NYMD2TAU(940301L), NEWTRACER=1

           ; Add individual CH3I tracers for 03/01/1994 and 
           ; store them  as total CH3I concentration. 
           ; But first: test!

        (2)
        CTM_SUM,'IJ-AVG-$',$
           TRACER=2, FILENAME='ctm.bpch.ox', /AVERAGE 
        
           ; Compute annual averages from monthly means for Ox

 MODIFICATION HISTORY:
        mgs, 18 May 1999: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Added FILENAME keyword as an 
                            alternative to ILUN
                          - Updated comments, cosmetic changes
        phs, 18 Aug 2008: GAMAP VERSION 2.13
                          - Added experimental keyword DIMAVER to
                            average along any dimension of the
                            datablocks.

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_sum.pro)


CTM_SUM_EMISSIONS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_SUM_EMISSIONS

 PURPOSE:
        Computes totals of emissions in Tg [or Tg C] for the
        following diagnostics: ND28, ND29, ND32, ND36, ND46, ND13, etc.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        CTM_SUM_EMISSIONS, DIAGN [, Keywords ]

 INPUTS:
        DIAGN -> A diagnostic category name to restrict 
             the record selection (default is "ANTHSRCE").

 KEYWORD PARAMETERS:
        FILENAME -> Punch file (ASCII or Binary) from which to 
             read CTM emissions data.  If omitted, the user
             will be prompted to select a file via a dialog box.

        FORMAT -> To overwrite the default format to output the
             sum.

        TRACER -> The tracer number (or a 1-D array of tracer
             numbers) to compute emission totals for.

        /CUM_ONLY -> If this switch is set, SUM_EMISSIONS will
             only print out cumuluative totals (and skip individual
             totals for each data block).

        RESULT -> An array of structures (tag names: NAME, SUM, UNIT) 
             that returns, the name of each tracer, its cumulative
             total, and its unit to the calling program.
           
        /NO_SECONDS -> Set this switch if the data to be summed is
             independent of seconds (e.g. molec/cm2).  CTM_SUM_EMISSIONS
             will not multiply the data by the number of seconds in the 
             interval when converting to Tg.

        /KG -> Set this switch if the data to be summed is in kg
             instead of molec/cm2 or molec/cm2/s.  CTM_SUM_EMISSIONS
             will not multiply the data by the surface area of each
             grid box when converting to Tg.

        /TO_Mg -> Set this switch if you wish to display emissions
             totals in Mg instead of Tg.

        /TO_Gg -> Set this switch if you wish to display emissions
             totals in Gg instead of Tg.

        /SHORT -> Use a shorter output format to print totals.
             Default is to print out w/ the long output format.

        _EXTRA=e -> Picks up any extra keywords for CTM_GET_DATA
             or CTM_TRACERINFO.
 
 OUTPUTS:
        Prints totals in Tg or Tg C for each tracer to the screen

 SUBROUTINES:
        Internal Subroutines:
        ==================================================
        CSE_GetUnit (function)  CSE_GetAreaCm2 (function)
        CSE_GetInfo

        External Subroutines Required:
        ==================================================
        CTM_DIAGINFO            CTM_TRACERINFO
        CTM_GETDATA             CTM_BOXSIZE    (function)
        CTM_GRID    (function)  GAMAP_CMN
        TAU2YYMMDD  (function)  UNDEFINE

 REQUIREMENTS:
        None

 NOTES:
        (1) Most of the time there will be 1 data block per month,
            and the cumulative total will be a yearly total.

        (2) For NOx, a molecular weight of 14e-3 kg/mole will report
            results in Tg N.  A molecular weight of 46e-3 will report
            results in Tg NOx.  This can be changed in the file
            "tracerinfo.dat".

        (3) Should now be compatible with any model type and grid
            resolution.  As of 6/19/01, has only been tested using
            GEOS-CHEM diagnostic output.
   
 EXAMPLE:
        CTM_SUM_EMISSIONS, 'ANTHSRCE', $
                           FILENAME='ctm.bpch', TRACER=1, $
                           MODELNAME='GEOS1', RESOLUTION=4

             ; Will print emission totals for tracer #1 (NOx)
             ; for the ANTHSRCE (ND36) diagnostic, using data
             ; in file "ctm.bpch".  The data is from a GEOS-1 
             ; simulation on a 4x5 grid.

 MODIFICATION HISTORY:
        bmy, 26 Apr 2001: GAMAP VERSION 1.47
        bmy, 08 Jun 2001: - now uses correct tracer name, unit,
                            and molecular weight for CO--SRCE
        bmy, 19 Jun 2001: GAMAP VERSION 1.48
                          - added internal function CSE_GETUNIT
                            to return the proper unit string
                            ("Tg N", "Tg C", or "Tg").
                          - added internal function CSE_GETAREACM2
                            which gets the proper surface area
                            for each data block
                          - removed MODELNAME, RESOLUTION keywords
        bmy, 03 Jul 2001: - now can sum emissions from GENERIC grids
        bmy, 16 Aug 2001: - added /NO_SECONDS and /KG keywords
        bmy, 26 Sep 2001: GAMAP VERSION 1.49
                          - set XNUMOL = 1d-3 if /KG is set; this
                            will convert from g/cm2 to Tg correctly
        bmy, 21 Nov 2001: - added internal routine CSE_GETINFO
                          - now call CTM_EXTRACT to restrict the
                            totaling to any arbitrary lat/lon rectangle
        bmy, 10 Jan 2002: GAMAP VERSION 1.50
                          - Bug fix: Don't call CTM_EXTRACT if /KG is, 
                            set, since AREACM2 will be 1 in that case 
        bmy, 31 Jan 2002: - change output format from f10.4 to f12.4
        bmy, 10 Jun 2002: GAMAP VERSION 1.51
                          - added "kludge" for biomass burning files
                            if /NO_SECONDS is set; will use proper
                            mol wts & units for ACET, C3H8, C2H6
        bmy, 14 Jan 2003: GAMAP VERSION 1.52
                          - added another quick fix to get the unit strings
                            correct for sulfate and nitrogen tracers for ND13
        bmy, 19 Sep 2003: GAMAP VERSION 1.53
                          - now call PTR_FREE to free the pointer memory
        bmy, 19 Nov 2003: GAMAP VERSION 2.01
                          - now get the spacing between diagnostic
                            offsets from CTM_DIAGINFO
        bmy, 26 Mar 2004: GAMAP VERSION 2.02
                          - added FORMAT keyword
        bmy, 03 Dec 2004: GAMAP VERSION 2.03
                          - now pass /QUIET to CTM_GET DATA which
                            reduces a lot of printing to the screen
        bmy, 15 Mar 2005: - Added /TO_Gg and TO_Mg keywords, which
                            will print totals in either Gg or Mg
                            instead of the default unit of Tg
                          - Now pass _EXTRA=e to CTM_GET_DATA so that
                            we can restrict to a given time 
        bmy, 07 Apr 2006: GAMAP VERSION 2.05
                          - Added /SHORT keyword
        bmy, 29 Sep 2006: - Bug fix: now test for molec wt in kg/mole
                            in internal function CSE_GETUNIT
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        phs, 20 Mar 2008: GAMAP VERSION 2.12
                          - updated to work with nested grid
        mps, 23 Jan 2014: - Added case for NO to CSE_GetUnit for output from
                            GEOS-Chem v9-02 and higher versions
                          - Now report NO emissions in Tg N
                          - Now print unit 'Tg C' for BC/OC tracers

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_sum_emissions.pro)


CTM_TRACERINFO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_TRACERINFO

 PURPOSE:
        Return information about one or all tracers for a given
        GEOS-Chem, GISS, or other CTM diagnostic.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation, Structures

 CALLING SEQUENCE:
        CTM_TRACERINFO, TRACERN, TRACERSTRU [, Keywords ]

 INPUTS:
        TRACERN -> Tracer number or name for which to extract the 
            information. If TRACERN is numeric, it is interpreted as 
            an index to the FULLCHEM or SMALLCHEM tracernumber
            in the global model. If it is a string, it will be compared 
            to NAME then FULLNAME. TRACERN may contain more than one 
            element. To retrieve information about all tracers, use the
            /ALL_TRACERS keyword.

 KEYWORD PARAMETERS:
        /ALL_TRACERS -> Retrieve information about all tracers

        FILENAME --> Name of the tracerinfo file (default tracerinfo.dat)
            The file will be searched in the current directory first, then
            in the directory where ctm_tracerinfo.pro is located. If not found
            in either location, a standard data block is retrieved from this 
            file.

        /FORCE_READING -> Overwrite the contents of the common block

        FULLNAME -> Returns the (long) name of the requested tracer(s)

        INDEX -> Returns the CTM index of the requested tracer(s)

        MOLC -> Returns the carbon number of the requested tracer(s)
             (For hydrocarbons, this is the # moles C/mole tracer)

        MOLWT -> Returns the molecular weight (kg/mole) of the 
             requested tracer(s)

        NAME -> Returns the (short) name of the requested tracer(s)

        SCALE -> Standard scale factor for tracer

        UNIT -> Returns the standard unit of the requested tracer(s)
             (i.e. unit as supplied by CTM with standard scale factor 
             applied (e.g. ppbv instead of V/V))

        IS_EDGED -> Returns whether the given tracer is defined on
             level edges (IS_EDGED=1) or level centers (IS_EDGED=0).  

 OUTPUTS:
        TRACERSTRU -> returns a structure or structure array with the 
            following tags:
               NAME     : short name for tracer as used in the model
               FULLNAME : long name for tracer (may be used in titles)
               MWT      : molec. weight as kg N or kg C 
               INDEX    : tracer number
               MOLC     : carbon number for NMHC
               SCALE    : standard scale factor
               UNIT     : standard unit for tracer with scale factor applied
               IS_EDGED : Is tracer defined on level edges?

 SUBROUTINES:
        External Subroutines Required:
        ================================================
        FILE_EXIST (function)   ROUTINE_NAME (function)
        OPEN_FILE 
 
 REQUIREMENTS:
        None

 NOTES:
        At first call, the tracer information structure array is
        either read from file or retrieved from the
        DATA block at the end of this program. Thereafter, the information
        is stored in a common block where it is accessible in subsequent 
        calls.
        The newer tags MOLC, SCALE and UNIT are optional and defaulted
        to 1.0, 1.0, and 'UNDEFINED', resp.

 EXAMPLE:
        CTM_TRACERINFO, 2, RES
        PRINT, RES.NAME, RES.MWT, RES.INDEX
        ; prints        Ox    0.0480000     2

        CTM_TRACERINFO,'OX',RES
        PRINT, RES.NAME, RES.MWT, RES.INDEX
        ; prints identical results

        CTM_TRACERINFO,[1,3,5],NAME=NAME,MOLWT=MWT,MOLC=MOLC,/FORCE_READING
        PRINT, NAME, MWT, MOLC
        ; reads tracerinfo.dat file and prints 
        ; NOx PAN ALK4
        ; 0.0140000     0.121000    0.0120000
        ; 1.00000      1.00000      4.00000

 MODIFICATION HISTORY:
        mgs, 22 Apr 1998: VERSION 1.00
        mgs, 24 Apr 1998: - added NAME keyword
        bmy, 07 May 1998: - added MOLC structure field to store 
                            carbon number for NMHC
        mgs, 07 May 1998: VERSION 2.00
                          - substantially revised
        mgs, 08 May 1998: - added SCALE and UNIT tags, made them optional
        mgs, 28 May 1998: - bug fix with on_ioerror
        mgs, 09 Oct 1998: - bug fix for tracern=0, changed CALLING SEQ. entry
        mgs, 12 Nov 1998: - unit string now defaulted to 'UNDEFINED' 
        bmy, 03 Jan 2001: GAMAP VERSION 1.47
                          - skip tracer lines beginning with '#' character
        bmy, 17 Nov 2003: GAMAP VERSION 2.01
                          - Removed FULLI, SMALLI, they're obsolete
                          - now use INDEX for tracer number
                          - Now use new file format for "tracerinfo.dat"
                            which allows for 8-digit offset numbers
                          - No longer read defaults from internal datablock
                          - Updated comments 
        bmy, 06 Apr 2004: GAMAP VERSION 2.02
                          - added /VERBOSE keyword
        bmy, 09 Mar 2006: GAMAP VERSION 2.05
                          - Use "./tracerinfo.dat" as default in
                            order to facilitate reading in IDL 5.5-
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Add IS_EDGED tag to TRACERINFO structure
                            to denote whether the tracer is defined
                            on level centers or level edges
                          - Implement temporary fix: call GET_IS_EDGED
                            to determine if a tracer is defined on
                            level edges.  There is probably a better way
                            to do this, work on that later.
                          - Now use FILE_WHICH to locate the
                            "tracerinfo.dat" file.
        phs, 30 Jun 2008: GAMAP VERSION 2.12
                          - bug fix to account for FILENAME
        phs, 22 Sep 2009: GAMAP VERSION 2.13
                          - added test on found/not found tracers

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_tracerinfo.pro)


CTM_TYPE (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 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)


CTM_VALIDATESTRUCTURES

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_VALIDATESTRUCTURES

 PURPOSE:
        Test validity of a FILEINFO and DATAINFO structure
        or array of structures.

 CATEGORY:
        GAMAP Internals, Structures

 CALLING SEQUENCE:
        CTM_VALIDATESTRUCTURES,FILEINFO,DATAINFO,result=result, $
              print_warn=print_warn

 INPUTS:
        FILEINFO -> A FileInfo structure (array) to be tested

        DATAINFO -> A DataInfo (array) to be tested

        Both arguments must be present!

 KEYWORD PARAMETERS:
        RESULT -> A named variable that will be set to 1 if
            both structures are valid. This keyword is mandatory.

        PRINT_WARN -> print a warning message on the screen if
            a structure is non-existent or corrupt.

 OUTPUTS:
        None

 SUBROUTINES:
        Uses ROUTINE_NAME and CHKSTRU functions

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        CTM_VALIDATESTRUCTURES,FileInfo,DataInfo,result=result
        if (not result) then return

 MODIFICATION HISTORY:
        mgs, 20 Aug 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/ctm_validatestructures.pro)


CTM_WRITEBPCH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_WRITEBPCH

 PURPOSE:
        Save GAMAP datainfo records to disk 
        (in binary punch file format).

 CATEGORY:
        GAMAP Utilities, BPCH Format

 CALLING SEQUENCE:
        CTM_WRITEBPCH, DATAINFO, [, Keywords ]

 INPUTS:
        DATAINFO -> a datainfo record or an array of datainfo records
 
        FILEINFO -> a fileinfo record or an array of fileinfo records

 KEYWORD PARAMETERS:
        FILENAME -> Filename of output file. Should end in '.bpch'.

        SCALE -> An optional scaling factor. This factor will be applied 
             to _all_ data record upon saving. The globally stored records
             are not affected.

        NEWUNIT -> With this keyword you can change the unit _name_ for
             the saved data. This will _not_ perform a unit conversion!
             For a true unit conversion you must also use the SCALE
             keyword. NEWUNIT will be applied to _all_ records!

        /APPEND -> If set, then will append to an existing binary
             punch file rather than writing to a new file.

 OUTPUTS:
        A binary punch file with the selected data records will be
        created.

 SUBROUTINES:
        External Subroutines Required:
        ====================================================
        CHKSTRU      (function)   CTM_DIAGINFO
        CTM_GET_DATA (function)   DATATYPE     (function)   
        OPEN_FILE

 REQUIREMENTS:
        None

 NOTES:
        This routine forces reading of all selected data records via
        CTM_GET_DATA.  This may take a while for huge ASCII punch files.

 EXAMPLE:
        gamap [,options]  ; call gamap to read records from a file
        @gamap_cmn        ; get global datainfo structure
        d = *pglobalDataInfo 
        ind = where(d.tracer eq 2)  ; select all Ox records
        ctm_writebpch,d[ind],filename='oxconc.bpch'
        
 MODIFICATION HISTORY:
        mgs, 20 May 1999: VERSION 1.00
                          - stores binary files version 1
        mgs, 24 May 1999: VERSION 2.00
                          - stores binary files version 2
        bmy, 26 Jul 1999: VERSION 2.01
                          - now call function DATATYPE
                          - make sure only floating point data gets
                            written to binary punch file v. 2.0
        bmy, 19 Jan 2000: - updated commetns
        bmy, 07 Jun 2000: GAMAP VERSION 1.45
                          - Save TRACER mod 100L to the punch file 
                          - updated comments
        bmy, 02 Mar 2001: GAMAP VERSION 1.47
                          - added FILEINFO as an argument; will use
                            PGLOBALFILEINFO structure if not passed
                          - removed obsolete comments
        bmy, 13 Mar 2001: - now supports Windows, MacOS, and Unix/Linux
        bmy, 07 Jun 2001: - removed obsolete code from 7/26/99
  mje & bmy, 17 Dec 2001: GAMAP VERSION 1.49
                          - added /APPEND keyword in order to
                            append to an existing binary punch file
                          - updated comments
        bmy, 15 Oct 2002: GAMAP VERSION 1.52
                          - added LEVELSAVE keyword to define certain
                            levels which to save to disk
                          - Updated comments, cosmetic changes
        bmy, 19 Nov 2003: GAMAP VERSION 2.01
                          - now get diagnostic spacing from CTM_DIAGINFO
                            and write TRACER mod SPACING to the BPCH file.
        bmy, 27 May 2004: GAMAP VERSION 2.02
                          - Bug fix: Don't call CTM_GET_DATA to initialize
                            data pointers if this has been done already
                          - removed LEVELSAVE keyword
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now save 4D datablock if the tag
                            of FILEINFO[0].FILETYPE = 106;

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_writebpch.pro)


CTM_WRITENC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CTM_WRITENC

 PURPOSE:
        Save GAMAP datainfo records to disk (in netCDF format)

 CATEGORY:
        GAMAP Utilities, Scientific Data Formats

 CALLING SEQUENCE:
        CTM_WRITENC, DATAINFO, FILENAME=FILENAME

 INPUTS:
        DATAINFO -> a datainfo record or an array of datainfo records

 KEYWORD PARAMETERS:
        FILENAME -> Filename of output file. Should end in '.bpch'.

        SCALE -> An optional scaling factor. This factor will be applied 
             to _all_ data record upon saving. The globally stored records
             are not affected.

        NEWUNIT -> With this keyword you can change the unit _name_ for
             the saved data. This will _not_ perform a unit conversion!
             For a true unit conversion you must also use the SCALE
             keyword. NEWUNIT will be applied to _all_ records!

 OUTPUTS:
        A binary punch file with the selected data records will be
        created.

 SUBROUTINES:
        External Subroutines Required:
        ====================================
        CTM_GET_DATA
        OPEN_FILE
        DATATYPE

 REQUIREMENTS:
        Must have a version of IDL w/ the netCDF library installed.

 NOTES:
        This routine forces reading of all selected data records via
        ctm_get_data. This may take a while for huge ASCII punch files.

 EXAMPLE:
        gamap [,options]  ; call gamap to read records from a file
        @gamap_cmn        ; get global datainfo structure
        d = *pglobalDataInfo 
        ind = where(d.tracer eq 2)  ; select all Ox records
        ctm_writebpch,d[ind],filename='oxconc.bpch'
        
 MODIFICATION HISTORY:
        mgs, 20 May 1999: GAMAP VERSION 1.47
                          - adapted from "ctm_writebpch.pro"
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_writenc.pro)


CUM_TOTAL (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CUM_TOTAL (function)

 PURPOSE:
        Compute cumulative total of a data vector.

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        RESULT = CUM_TOTAL(Y)

 INPUTS:
        Y -> The data vector

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        A data vector with the same number of elements 
        and the cumulative totals.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        See also function RUN_AV. 

 EXAMPLE:
        Y = FINDGEN(10)
        PRINT, CUM_TOTAL(Y)

             ; IDL prints:  0  1  3  6  10  15  21  28  36  45

 MODIFICATION HISTORY:
        mgs, 21 Oct 1998: VERSION 1.00
        bmy, 23 May 2007: TOOLS VERSION 2.06
                          - Now use longword for loop counter
                          - Updated comments, cosmetic changes
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/math_units/cum_total.pro)


CUSTOM_COLORTABLE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        CUSTOM_COLORTABLE

 PURPOSE:
        Defines various customized color tables for use with MYCT.
        Color tables may be stretched to more than the original #
        of colors, or compressed to less than the original # of 
        colors.  You may add more color tables as necessary.

        %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
        %% AS OF GAMAP v2-12, CUSTOM_COLORTABLE IS DEPRECATED.  %%
        %% MYCT NOW LOADS IDL AND ColorBrewer COLORTABLES FROM  %%
        %% THE "gamap_colors.tbl" FILE. (phs, bmy, 4/21/08)     %%
        %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
        
 CATEGORY:
        Color

 CALLING SEQUENCE:
        CUSTOM_COLORTABLE, R, G, B [ , Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS
        /BuWhRd -> Set this switch to load the BLUE-WHITE-RED 
             (diverging) color table from Harvard University.  This
             color table is a concatenation of the WHITE-BLUE and
             WHITE-RED ColorBrewer colortables.  The center color
             is white.  (Original # of colors = 19)

        /BuWhWhRd -> Set this switch to load the BLUE-WHITE-WHITE-RED 
             (diverging) color table.  This is a concatenation of 
             the WhBu and WhRd colortables from ColorBrewer.  The two
             center colors in this colortable are white, which makes
             it easier to align colorbar tickmarks at the divisions
             between colors.  (Original # of colors = 20)

        /BuYlRd -> Set this switch to load the BLUE-YELLOW-RED 
             (diverging) color table from ColorBrewer.  (Original 
             # of colors = 12)

        /BuYlYlRd -> Set this switch to load the BLUE-YELLOW-YELLOW-RED 
             (diverging) color table from ColorBrewer.  The two center
             colors in this colortable are light yellow, which makes
             it easier to align colorbar tickmarks at the divisions
             between colors.  Use this colortable instead of /BuWhWhRd 
             if you need to denote "missing data" values by white.  
             (Original # of colors = 12)

        /DIAL -> Set this switch to load the DIAL/LIDAR (diverging)
             color table from Ed Browell. (Original # of colors = 27)

        /DIFF -> Synonym for /BuWhRd.  Kept for backwards compatibility.

        /ModSpec -> Set this switch to load the MODIFIED SPECTRUM
             (diverging) color table from ColorBrewer.  (Original #
             of colors = 11)

        NAME -> Returns to the calling program the name of the color
             table that we have selected.

        NCOLORS -> The number of colors that you would like to be
             included in the colortable.  If NCOLORS is greater than
             the native number of colors for the given colortable,
             the colortable will be stretched to produce a finer
             gradation of colors.  Conversely, if NCOLORS is less
             than the native number of colors, then the colortable
             will be compressed to produce a coarser gradation of
             colors.

        /NOLOAD -> If set, then CUSTOM_COLORTABLE will just return R, 
             G, B to the calling program without loading the colortable.

        /TRUNCATE -> When NCOLORS is less than the number of colors
             in the given color table, setting /TRUNCATE will cause 
             CUSTOM_COLORTABLE to truncate the color table to NCOLORS
             rather than trying to compress it via interpolation.

        /UserDef -> Set this switch to load a user-defined colortable.
             In order to use this option, you must first add the R, G,
             B color vectors into internal routine DEFINE_UserDef.

        /WhBu -> Set this switch to load the WHITE-BLUE (spectral)
             color table from ColorBrewer.  (original # of colors = 10)

        /WhGrYlRd -> Set this switch to load the WHITE-GREEN-YELLOW-RED
             (spectral) color table from A. van Donkelaar.  (Original
             # of colors = 20)

        /WhGyBk -> Set this switch to load the WHITE-GRAY-BLACK 
             (spectral) color table from ColorBrewer.  (Original # 
             of colors = 10)

        /WhRd -> Set this switch to load the WHITE-RED (spectral) color
             table from ColorBrewer.  (original # of colors = 10)

 OUTPUTS:    
        R -> Returns to the calling program the red color
             vector that defines the customized colortable.

        G -> Returns to the calling program the green color
             vector that defines the customized colortable.

        B -> Returns to the calling program the blue color
             vector that defines the customized colortable.

 SUBROUTINES:
        Internal Subroutines Included:
        ================================================    
        DEFINE_BuWhRd     DEFINE_BuWhWhRd   DEFINE_BuYlRd   
        DEFINE_BuYlYlRd   DEFINE_DIAL       DEFINE_MODSPEC  
        DEFINE_WhBu       DEFINE_WhGrYlRd   DEFINE_WhRd     
        DEFINE_WhGyBk

 REQUIREMENTS:
        None

 NOTES:
        (1) For contour plots, the native resolution of the
            custom colortables should be sufficient.

        (2) For smoothed pixel plots, NCOLORS=100 or higher will
            eliminate the streaking caused by TVIMAGE's smoothing
            algorithm.

        (3) Some color tables were adapted from the ColorBrewer
            package (see license info below).

        (4) We will use the ColorBrewer color abbreviations:
               Bk = Black    Br = Brown    Bu = Blue      
               Gr = Green    Gy = Gray     Or = Orange    
               Pi = Pink     Pu = Purple   Rd = Red     
               Wh = White    Yl = Yellow

        (5) An MS Excel spreadsheet with all ColorBrewer color tables 
            is available for download from:
            www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_RGB.html

 EXAMPLES:

        CUSTOM_COLORTABLE, R, G, B, /NOLOAD, /DIAL

             ; Returns the red, green, blue color vectors for the
             ; DIAL colortable at native resolution (26 colors)

        CUSTOM_COLORTABLE, NCOLORS=120, /DIAL

             ; Loads the DIAL colortable and stretches it 
             ; from 26 to 120 colors.

        CUSTOM_COLORTABLE, /WhGrYlRd

             ; Loads the WHITE-GREEN-YELLOW-RED (spectral) 
             ; color table with 20 colors.
        
 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Adapted from "dial_ct.pro"
                          - Now can compress the colortable if
                            NCOLORS is less than N_ORIG
                          - Added /BuWhWhRd keyword for selecting
                            the BLUE-WHITE-WHITE-RED colortable
                          - Added /BuYlYlRd keyword for selecting
                            the BLUE-YELLOW-YELLOW-RED colortable
                          - /DIFF is now a synonym for /BuWhWhRd
                          - Added /UserDef keyword and internal
                            routine DEFINE_UserDef for selecting
                            a user-defined color table. 
        phs, 12 Feb 2008: GAMAP VERSION 2.12
                          - Now create /BuWhRd as a concatenation of
                            the /WhBu and /WhRd colortables.
                          - Updated the interpolation for case of  
                            NCOLORS lt NORIG.  It works fine with all 
                            the 4 diverging colortables, and keeps the 
                            doubling of the middle range color if NCOLORS 
                            is even and BuWhWhRd or BuYlYlRd is used. 
        bmy, 18 Apr 2008: - Bug fix: don't overwrite colortable name
                            for BuWhRd colortable 

(See /n/home09/ryantosca/IDL/gamap2/color/custom_colortable.pro)


DATATYPE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DATATYPE

 PURPOSE:
        Returns the number (or name) of the data type
        of an IDL scalar, array, structure, or object.

 CATEGORY:
        General

 CALLING SEQUENCE:
        RESULT = DATATYPE( Data [, Keywords ] )

 INPUTS:
        DATA -> A variable (scalar, array, structure, or object)
             whose data type is desired.

 KEYWORD PARAMETERS:
        /NAME -> If set, will return the name of the data type
             instead of the type number.
        
 OUTPUTS:
        The IDL data type number or data type name will be
        contained in RESULT. 

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        The IDL data type numbers are:
        -----------------------------------------
        0  : undefined    6  : complex
        1  : byte         7  : string
        2  : int          8  : structure
        3  : long         9  : double complex
        4  : float        10 : pointer
        5  : double       11 : object reference
 
 EXAMPLES:
        PRINT, DATATYPE( 0d0 )
           5
             ; Double precision data is type 5

        PRINT, DATATYPE( 0d0, /Name )
           DOUBLE
             ; Returns the name of the data type

 MODIFICATION HISTORY:
        bmy, 26 Jul 1999: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/datatype.pro)


DATE2YMD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DATE2YMD

 PURPOSE:
        Given a date in YYYYMMDD format, returns the year, month,
        and day in separate variables.  Also can be used to separate
        time in a HHMMSS format into hours, minutes, seconds.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        DATE2YMD, YYYYMMDD, YEAR, MONTH, DAY

 INPUTS:
        YYYYMMDD -> Today's date as YYYY/MM/DD (or time as HH/MM/SS)
        YEAR     -> Year  (or hour  ) value
        MONTH    -> Month (or minute) value
        DAY      -> Day   (or second) value

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        None
       
 REQUIREMENTS:
        None

 NOTES:
        None
    
 EXAMPLE:
        DATE2YMD, 20060101, Y, M, D
        PRINT, Y, M, D
           2006  1   1
             ; Separates the date into Y, M, D variables

        DATE2YMD, 123000, H, Mi, S
        PRINT, H, Mi, S
           12  30  0
             ; Separates the time into H, Mi, S variables

 MODIFICATION HISTORY:
        bmy, 06 Jun 2006: TOOLS VERSION 2.05
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/date_time/date2ymd.pro)


DAY_OF_YEAR (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DAY_OF_YEAR (function)

 PURPOSE:
        Computes the day number (0-365 or 0-366 if leap year) 
        of a given date.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = DAY_OF_YEAR( MONTH, DAY, YEAR )  OR
        RESULT = DAY_OF_YEAR( YYYYMMDD  )

 INPUTS:
        With 3 arguments:
        MONTH (int or long) -> the input month (1 - 12)
        DAY   (int or long) -> the input day   (0 - 31)
        YEAR  (int or long) -> the input year  (YEAR<0 is BC; YEAR>0 is AD)
        
        With 1 argument:
        YYYYMMDD (long) -> the input date in YYYYMMDD format.

 KEYWORD PARAMETERS:

 OUTPUTS:
        RESULT -> Day number of the year

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        (1) You cannot abbreviate YEAR.  If you specify 10/14/97
            DAY_OF_YEAR will compute the day number for 14 Oct 97 AD 
            instead of 14 Oct 1997 AD

 EXAMPLES:
        (1)
        PRINT, DAY_OF_YEAR( 10, 14, 1997 )
          287
             ; A typical modern date: 14 Oct 1997 AD

        (2)
        PRINT, DAY_OF_YEAR( 19971014 )
          287
             ; The same as example #1, but this time we call
             ; DAY_OF_YEAR with a date in YYYYMMDD format

        (3)
        PRINT, DAY_OF_YEAR( 1, 1, 1 )
          1
             ; Beginning of the "Anno Domini" era: 1 Jan 1 AD

        (4)
        PRINT, DAY_OF_YEAR( 3, 15, -44 )  
           74
             ; When Julius Caesar was murdered: 15 Mar 44 BC

 MODIFICATION HISTORY:
        bmy, 14 Oct 1997: VERSION 1.00
        bmy, 26 Mar 1998: VERSION 1.01
                           -- now written as a function with 
                              more elegant error checking.
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 03 Apr 2008: GAMAP VERSION 2.12
                          - Modified to accept either 3 arguments
                            (month, day, year) or one argument
                            (date in YYYYMMDD format)
                          

(See /n/home09/ryantosca/IDL/gamap2/date_time/day_of_year.pro)


DEFAULT_DIRS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DEFAULT_DIRS

 PURPOSE:
        Define a couple of system variables to facilitate 
        file searching across or in multiple platforms.
        The settings are made depending on the host name which
        is queried with getenv(). 
          This file is meant to be modified for your own computing
        environment and directory structure. It's probably a good 
        idea to include a call to Default_Dirs in your startup file.
        A string (or string array) argument allows individual users
        to add their own default settings for individual projects
        (see INPUTS).

 CATEGORY:
        General

 CALLING SEQUENCE:
        DEFAULT_DIRS [,projectlist [,searchpath=searchpath] ]

 INPUTS:
        PROJECTLIST -> A string or string array containing the names
            of projects of individual users for which additional
            settings shall be made. For each entry for which a procedure
            named default_.pro exists, this procedure
            will be called with the host name (lower case) as argument.
            If the procedure is not found, a warning message is issued.

 KEYWORD PARAMETERS:
        SEARCHPATH -> A string that will be inserted at the beginning 
            of the !PATH variable to look for the default_
            procedures. This keyword is only evaluated when a
            PROJECTLIST is present. For simplicity, the user must make sure
            that SEARCHPATH adheres to the syntax of the curent OS. Since
            DEFAULT_DIRS is usually caled from the startup file, this
            shouldn't be too much of a problem.
           
         /PRINT -> print all system variables ending in 'DIR' after
            the definition. 

 OUTPUTS:
        Various system variables are created. As a minimum, these are
          !RootDir = the root of the file system
          !HomeDir = the user's home directory
          !DataDir = a general data depository
          !TmpDir  = a temporary directory

          !FNSep   = filename seperator ('/' for unix and '\' for windows)

        Further project-specific directories should also end in 'Dir',
        this allows an easy query of all default directories:
          help,/system_variables,output=o
          print,o[ where(strpos(o,'DIR') gt 0) ]
        (see PRINT keyword).
 *******  NEED TO WORK THAT OUT !! ******  it's not that easy !!!  *********

 SUBROUTINES:
        none.

 REQUIREMENTS:
        none.

 NOTES:
        This routine uses a common block (yes!) to remember whether
        the user had already been warned about non-exisiting project
        procedures. Therefore, when you add projects on the fly,
        you can probably call default_dirs safely every time you wish 
        to compose a search mask.

 EXAMPLE:
        default_dirs    ; set platform dependent default directories

        default_dirs,['GTE','CTM'],searchpath='~/myprogs',/PRINT
        ; as above, but add definitions from default_gte.pro and
        ; default_ctm.pro which may be in ~/myprogs or the regular
        ; IDL search !PATH. Print all !...DIR system variables upon 
        ; exit. See attached default_gte procedure for an example.

 MODIFICATION HISTORY:
        mgs, 12 May 1999: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/default_dirs.pro)


DEFAULT_GTE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DEFAULT_GTE

 PURPOSE:
        Define default system variables for GTE data directories
        and GTE programs. Specific entries are made for the
        PEM-Tropics A and B projects.
        This procedure is caled from DEFAULT_DIRS when 'GTE' is
        added as an argument.

 CATEGORY:
        General

 CALLING SEQUENCE:
        DEFAULT_GTE,host

 INPUTS:
        HOST -> the name of the host computer which is running IDL.
            In our environment these are sol or cyclope or now.

 KEYWORD PARAMETERS:

 OUTPUTS:
        Additional system variables are created:
           !GTE_Dir   = home of GTE data on current platform
           !PEMTA_Dir = PEM-Tropics A data
           !PEMTB_Dir = PEM-Tropics B data

           !GTE_Filetypes = list of fiel extensions used with GTE data

 SUBROUTINES:

 REQUIREMENTS:
        It is assumed that this routine is called from DEFAULT_DIRS
        although it should be working stand-alone as well.

 NOTES:

 EXAMPLE:
        see default_dirs

 MODIFICATION HISTORY:
        mgs, 12 May 1999: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/default_gte.pro)


DEFAULT_RANGE (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DEFAULT_RANGE  (function)

 PURPOSE:
        Make sure a RANGE argument or keyword is a valid vector with 
        at least two elements.  Can also be used to limit RANGE to
        two elements.  The argument may be a string containing one or 
        more numeric values delimited by almost any character 
        combination (including '..' and '-').  A '-' will be treated 
        as a separator if it is preceeded by a digit or not followed
        by a digit.  The resulting range will be sorted and spans the 
        minimum and maximum of the "data" given in the argument.

 CATEGORY:
        General

 CALLING SEQUENCE:
        RANGE = DEFAULT_RANGE( ARG, DEFAULT [,/LIMIT2] )

 INPUTS:
        ARG -> The range argument or keyword as passed into 
              a procedure or function. This can be an undefined
              variable or a variable with 1 or more elements.
              If ARG contains 1 element, it will be repeated 
              to range from and to the same number.

        DEFAULT -> A 2-element vector containing the default range 
              if ARG is undefined. This argument is mandatory
              although it is not used if ARG contains at least 
              1 element.

 KEYWORD PARAMETERS:
        /LIMIT2 -> Limit the resulting RANGE vector to 2 elements.
               Default is to return *at least* 2 elements.

        RANGE -> Limit the RANGE vector to minimum and maximum 
               value given by this keyword.

        /NOSORT -> Do not sort the output. This can be useful for
               longitude vectors spanning the Pacific ;-)

 OUTPUTS:
        RANGE -> A two (or more) element vector that can be used in
               statements like WHERE(x ge RANGE[0] AND x lt RANGE[1]).

 SUBROUTINES:
        External Subroutines Required:
        ============================================
        ISALGEBRAIC (function)   ISDIGIT (function) 
        STRBREAK    (function)   STRREPL (function)

 REQUIREMENTS:
        None

 NOTES:
        This function is meant for argument checking in procedures
        or functions, hence it will generally not be called from the
        command line.

 EXAMPLE:
        LATRANGE = DEFAULT_RANGE( LATRANGE, [-90.,90.] )

             ; Suppose a procedure has a keyword parameter named 
             ; LATRANGE.  Before we use LATRANGE in any form, we 
             ; should test it (as above).  This ensures that we have 
             ; at least 2 elements in LATRANGE and it defaults
             ; LATRANGE to the whole globe if nothing was passed 
             ; in the LATRANGE keyword.

 MODIFICATION HISTORY:
        mgs, 29 Sep 1998: VERSION 1.00
        mgs, 17 Nov 1998: - added string handling
                          - added RANGE and NOSORT keywords
        bmy, 13 Jul 2001: TOOLS VERSION 1.48
                          - now uses new STRREPL function from mgs
        bmy, 16 Jul 2001: - bug fix: only call STRREPL if there are
                            non-algebraic characters to be replaced
                          - eliminate call to obsolete STR_SEP function
        bmy, 17 Jan 2002: TOOLS VERSION 1.50
                          - now call STRBREAK wrapper routine from
                            the TOOLS subdirectory for backwards
                            compatiblity for string-splitting
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/default_range.pro)


DIFFERENCES

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DIFFERENCES

 PURPOSE:
        Creates absolute difference plots ( New - Old ) 
        for GEOS-Chem tracers and OH. 

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        DIFFERENCES, FILES, LEVELS, TAUS, TRACERS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "old" and "new" GEOS-Chem model versions
             that are to be compared. 

        LEVELS -> A 4-element vector containing the level indices
             for the GEOS-Chem surface layer and 500 hPa layer.
             for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
             NOTE: This is in Fortran notation (starting from 1!)

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        TRACERS -> The list of transported tracers (i.e. diagnostic
             category "IJ-AVG-$").

        VERSIONS -> A 2-element vector containing the version
             numbers for the "old" and "new" GEOS-Chem model
             versions.

 KEYWORD PARAMETERS:
        /DO_FULLCHEM -> Set this switch to plot the chemically
             produced OH in addition to the advected tracers.

        /DYNRANGE -> Set this switch to create plots using the whole
             dynamic range of the data.  Default is to restrict
             the plot range to predetermined values as returned
             by routine GET_DIFF_RANGE.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output 
             to a file whose name is specified by this keyword.
             Default is "tracer_ratio.pro".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Included:
        ===================================================
        PlotDiff

        External Subroutines Required:
        ===================================================
        CLOSE_DEVICE           COLORBAR_NDIV    (function)
        CTM_GET_DATA           GET_DIFF_RANGE  
        GETMODELANDGRIDINFO    EXTRACT_FILENAME (function)
        MULTIPANEL             MYCT                       
        OPEN_DEVICE            TVMAP                      
        UNDEFINE        
        
 REQUIREMENTS:
        References routines from the GAMAP package.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLES:
        FILES    = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
        LEVELS   = [ 1, 1, 13, 13 ]
        TAUS     = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
        TRACERS  = INDGEN( 43 ) + 1
        VERSIONS = [ 'v7-04-10', 'v7-04-11' ]

        DIFFERENCES, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
             /DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'

             ; Creates ratio plots of two GEOS-CHEM versions
             ; (in this case v7-04-11 / v7-04-10) for July 2001.
             ; Output is sent to PostScript file "myplot.ps".
             ; The min and max of the data on each plot panel is 
             ; restricted to pre-defined values returned by
             ; function GET_DIFF_RANGE.

        DIFFERENCES, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
             /DO_FULLCHEM, /DYNRANGE, /PS, OUTFILENAME='myplot.ps'

             ; Same as the above example, but the min & max of 
             ; each plot panel corresponds to the dynamic range
             ; of the data.

 MODIFICATION HISTORY:
        bmy, 14 Nov 2007: VERSION 1.01
                          - Initial version
        bmy, 20 Nov 2007: VERSION 1.02
                          - Now draw out-of-bounds triangles for
                            the colorbar when using the "small"
                            data ranges.  New feature of TVMAP.
        bmy, 07 May 2008: VERSION 1.03
                          - Now allow for comparing models on 2
                            different vertical grids.
        bmy, 08 Feb 2011: VERSION 1.04
                          - Now display in the top-of-plot title
                            if the dynamic range option is used.
        bmy, 08 Jun 2011: VERSION 1.05
                          - Added /NO_FULLCHEM keyword
                          - Now call COLORBAR with the UPOS keyword 
                            to place the colorbar unit string properly
                          - Now use appropriate settings for creating
                            plots w/ the full dynamic range (/DYNRANGE)
                          - Now restore !MYCT sysvar to previous
                            settings upon exiting the program
        mps, 29 Mar 2013: - Now plot HO2 differences
 

(See /n/home09/ryantosca/IDL/gamap2/benchmark/differences.pro)


DIFFERENCES_AOD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DIFFERENCES_AOD

 PURPOSE:
        Creates column difference maps of aerosol optical depths from
        1-month GEOS-Chem benchmark simulation  output.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        DIFFERENCES_AOD, FILES, TAUS, TRACERS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "red", 'green", and "blue" GEOS-Chem model 
             versions that are to be compared. 

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        TRACERS -> The list of transported tracers (i.e. diagnostic
             category "IJ-AVG-$") to be plotted.

        VERSIONS ->  A 2-element vector containing the model version
             names from the "red", 'green", and "blue" simulations. 

 KEYWORD PARAMETERS:
        /DYNRANGE -> Set this switch to create plots using the entire
             dynamic range of the data (centered around zero).  The
             default is to use pre-defined data ranges.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output 
             to a file whose name is specified by this keyword.
             Default is "tracer_ratio.pro".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Provided:
        =========================================
        PLOTDIFF

        External Subroutines Required:
        =========================================
        OPEN_DEVICE     CLOSE_DEVICE
        MULTIPANEL      COLORBAR_NDIV (function)
        CTM_PLOT        CHKSTRU       (function)
     
 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLE:
        FILES    = [ 'ctm.bpch.v9-02p', 'ctm.bpch.v9-02q' ]
        TAUS     = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
        TRACERS  = [ 1, 2, 4 ]
        VERSIONS = [ 'v9-02p', 'v9-02q' ]

        DIFFERENCES_AOD, FILES, TAUS, TRACERS, VERSIONS, $
             /PS, OUTFILENAME='myplot.ps'

             ; Creates difference maps from 2 different model versions
             ; using output from GEOS-Chem 1-month benchmark simulations.

        DIFFERENCES_AOD, FILES, TAUS, TRACERS, VERSIONS, /DYNRANGE, $
             /PS, OUTFILENAME='myplot.ps'

             ; Same as above, but will create difference maps  using
             ; the full dynamic range of the data (centered around zero)
             ; instead of using pre-defined min & max values.


 MODIFICATION HISTORY:
        bmy, 09 Nov 2007: VERSION 1.01
                          - Initial version
        bmy, 20 Dec 2007: VERSION 1.02
                          - Now pass the month as a keyword to
                            put on the plot panel titles
        bmy, 02 Jun 2011: VERSION 1.03
                          - Make the colorbar a little wider
                          - Reduce the character size CsFac to 0.75
                            to better display long plot titles
                          - Now call COLORBAR with the UPOS keyword 
                            to place the colorbar unit string properly
                          - Now use appropriate settings for creating
                            plots w/ the full dynamic range (/DYNRANGE)
                          - Also restore the !MYCT sysvar to defaults
        mps, 16 Sep 2013: - Modified for 1-month benchmark output
        bmy, 24 Jan 2014: GAMAP VERSION 2.17
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/benchmark/differences_aod.pro)


DIFF_2D_MET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DIFF_2D_MET

 PURPOSE:
        Creates absolute difference plots ( New - Old ) 
        for GEOS-Chem 2-D meteorology fields. 

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        DIFF_2D_MET, FILES, TAUS, TRACERS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "old" and "new" GEOS-Chem model versions
             that are to be compared. 

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        TRACERS -> The list of transported tracers (i.e. diagnostic
             category "IJ-AVG-$").

        VERSIONS -> A 2-element vector containing the version
             numbers for the "old" and "new" GEOS-Chem model
             versions.

 KEYWORD PARAMETERS:
        /DYNRANGE -> Set this switch to create plots using the whole
             dynamic range of the data.  Default is to restrict
             the plot range to predetermined values as returned
             by routine GET_DIFF_RANGE.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output 
             to a file whose name is specified by this keyword.
             Default is "tracer_ratio.pro".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Included:
        ===================================================
        PlotDiff

        External Subroutines Required:
        ===================================================
        CLOSE_DEVICE           COLORBAR_NDIV    (function)
        CTM_GET_DATA           GET_DIFF_RANGE  
        GETMODELANDGRIDINFO    EXTRACT_FILENAME (function)
        MULTIPANEL             MYCT                       
        OPEN_DEVICE            TVMAP                      
        UNDEFINE        
        
 REQUIREMENTS:
        References routines from the GAMAP package.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLES:
        FILES    = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
        TAUS     = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
        TRACERS  = INDGEN( 43 ) + 1
        VERSIONS = [ 'v7-04-10', 'v7-04-11' ]

        DIFF_2D_MET, FILES, TAUS, TRACERS, VERSIONS, $
             /PS, OUTFILENAME='myplot.ps'

             ; Creates ratio plots of two GEOS-CHEM versions
             ; (in this case v7-04-11 / v7-04-10) for July 2001.
             ; Output is sent to PostScript file "myplot.ps".
             ; The min and max of the data on each plot panel is 
             ; restricted to pre-defined values returned by
             ; function GET_DIFF_RANGE.

        DIFF_2D_MET, FILES, TAUS, TRACERS, VERSIONS, $
             /DYNRANGE, /PS, OUTFILENAME='myplot.ps'

             ; Same as the above example, but the min & max of 
             ; each plot panel corresponds to the dynamic range
             ; of the data.

 MODIFICATION HISTORY:
        mps, 02 Dec 2013: - Initial version, based on differences.pro
        ewl, 14 Mar 2016: - Fix bug in PlotPctDiff by passing Log=Log to TvMap
 

(See /n/home09/ryantosca/IDL/gamap2/benchmark/diff_2d_met.pro)


DIFF_3D_MET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DIFF_3D_MET

 PURPOSE:
        Creates absolute difference plots ( New - Old ) 
        for GEOS-Chem 3-D meteorology fields.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        DIFF_3D_MET, FILES, LEVELS, TAUS, TRACERS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "old" and "new" GEOS-Chem model versions
             that are to be compared. 

        LEVELS -> A 4-element vector containing the level indices
             for the GEOS-Chem surface layer and 500 hPa layer.
             for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
             NOTE: This is in Fortran notation (starting from 1!)

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        TRACERS -> The list of transported tracers (i.e. diagnostic
             category "IJ-AVG-$").

        VERSIONS -> A 2-element vector containing the version
             numbers for the "old" and "new" GEOS-Chem model
             versions.

 KEYWORD PARAMETERS:
        /DYNRANGE -> Set this switch to create plots using the whole
             dynamic range of the data.  Default is to restrict
             the plot range to predetermined values as returned
             by routine GET_DIFF_RANGE.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output 
             to a file whose name is specified by this keyword.
             Default is "tracer_ratio.pro".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Included:
        ===================================================
        PlotDiff

        External Subroutines Required:
        ===================================================
        CLOSE_DEVICE           COLORBAR_NDIV    (function)
        CTM_GET_DATA           GET_DIFF_RANGE  
        GETMODELANDGRIDINFO    EXTRACT_FILENAME (function)
        MULTIPANEL             MYCT                       
        OPEN_DEVICE            TVMAP                      
        UNDEFINE        
        
 REQUIREMENTS:
        References routines from the GAMAP package.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLES:
        FILES    = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
        LEVELS   = [ 1, 1, 13, 13 ]
        TAUS     = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
        TRACERS  = INDGEN( 43 ) + 1
        VERSIONS = [ 'v7-04-10', 'v7-04-11' ]

        DIFF_3D_MET, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
             /PS, OUTFILENAME='myplot.ps'

             ; Creates ratio plots of two GEOS-CHEM versions
             ; (in this case v7-04-11 / v7-04-10) for July 2001.
             ; Output is sent to PostScript file "myplot.ps".
             ; The min and max of the data on each plot panel is 
             ; restricted to pre-defined values returned by
             ; function GET_DIFF_RANGE.

        DIFF_3D_MET, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
             /DYNRANGE, /PS, OUTFILENAME='myplot.ps'

             ; Same as the above example, but the min & max of 
             ; each plot panel corresponds to the dynamic range
             ; of the data.

 MODIFICATION HISTORY:
        mps, 02 Dec 2013: - Initial version, based on differences.pro
 

(See /n/home09/ryantosca/IDL/gamap2/benchmark/diff_3d_met.pro)


DIFF_CLOUDS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DIFF_CLOUDS

 PURPOSE:
        Creates absolute difference plots ( New - Old ) for cloud fraction
        (CLDTOT) and cloud optical depth (OPTD) in the surface - 500 hPa
        column.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        DIFF_CLOUDS, FILES, TAUS, TRACERS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "old" and "new" GEOS-Chem model versions
             that are to be compared. 

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        TRACERS -> The list of transported tracers (i.e. diagnostic
             category "IJ-AVG-$").

        VERSIONS -> A 2-element vector containing the version
             numbers for the "old" and "new" GEOS-Chem model
             versions.

 KEYWORD PARAMETERS:
        /DYNRANGE -> Set this switch to create plots using the whole
             dynamic range of the data.  Default is to restrict
             the plot range to predetermined values as returned
             by routine GET_DIFF_RANGE.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output 
             to a file whose name is specified by this keyword.
             Default is "tracer_ratio.pro".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Included:
        ===================================================
        PlotAbsDiff
        PlotPctDiff

        External Subroutines Required:
        ===================================================
        CLOSE_DEVICE           COLORBAR_NDIV    (function)
        CTM_GET_DATA           GET_DIFF_RANGE  
        GETMODELANDGRIDINFO    EXTRACT_FILENAME (function)
        MULTIPANEL             MYCT                       
        OPEN_DEVICE            TVMAP                      
        UNDEFINE        
        
 REQUIREMENTS:
        References routines from the GAMAP package.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLES:
        FILES    = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
        TAUS     = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
        TRACERS  = [ 1, 2 ]
        VERSIONS = [ 'v7-04-10', 'v7-04-11' ]

        DIFF_CLOUDS, FILES, TAUS, TRACERS, VERSIONS, $
             /DYNRANGE, /PS, OUTFILENAME='myplot.ps'

             ; Creates ratio plots of two GEOS-CHEM versions
             ; (in this case v7-04-11 / v7-04-10) for July 2001.
             ; Output is sent to PostScript file "myplot.ps".
             ; The min and max of the data on each plot panel
             ; corresponds to the dynamic range of the data.

 MODIFICATION HISTORY:
        mps, 23 Mar 2016: - Initial version
 

(See /n/home09/ryantosca/IDL/gamap2/benchmark/diff_clouds.pro)


DISTRIBUTE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DISTRIBUTE

 PURPOSE:
        Collect all the routine names and file names that are
        used in a given program.

 CATEGORY:
        General

 CALLING SEQUENCE:
        DISTRIBUTE [, ROUTINENAME ]

 INPUTS:
        ROUTINENAME -> (OPTIONAL) The name of the routine to be 
             searched.  If omitted, then the user will be prompted
             to supply a file name via a dialog box.

 KEYWORD PARAMETERS:
        OUTFILE -> Name of file where output will be sent.  If
             OUTFILE is omitted then DISTRIBUTE will print the
             information to the screen.

        /NO_IDL -> Set this switch to exclude IDL library routines
             from the search process.

 OUTPUTS:
        A list of filenames with full pathnames and a list of 
        routinenames together with the filenames where they can 
        be found.  Sorry, for local files, no pathname is provided.

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        OPEN_FILE

 REQUIREMENTS:
        Requires routines from the TOOLS package.

 NOTES:
        Unfortunately there is no way to figure out which routines
        really belong to a given ROUTINENNAME, so DISTRIBUTE will 
        always return too many routinenames and filenames, including 
        itself and FILE_EXIST, as well as a couple of IDL standard 
        library routines (The latter can be left out with the keyword 
        NO_IDL).  In order to get the closest results, run DISTRIBUTE 
        only at the start of an IDL session.

 EXAMPLE:
        DISTRIBUTE, 'iterate'
        
             ; Get all routines that belong to "iterate.pro". 
             ; A subsequent call with routinename 'create_master' 
             ; will return both, the routines for "create_master.pro" 
             ; and the routines for "iterate.pro".

 MODIFICATION HISTORY:
        mgs, 16 Nov 1997: VERSION 1.00
        mgs, 20 Nov 1997: - added OUTFILE and NO_IDL keywords
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now use IDL routine RESOLVE_ALL
                          - Now use OPEN_FILE instead of OPENW
                          - Updated comments, cosmetic changes

(See /n/home09/ryantosca/IDL/gamap2/general/distribute.pro)


DOCUMENT_COLOR_TABLE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DOCUMENT_COLOR_TABLE

 PURPOSE:
        Displays all of the color tables within a standard IDL
        *.tbl file.  Can display output to the Xwindow device,
        or create PostScript and PDF output.

 CATEGORY:
	 Color

 CALLING SEQUENCE:
	 DOCUMENT_COLOR_TABLE [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
	 FILE -> Name of the the color table (*.tbl) file to read. 
             Default is "gamap_colors.tbl".

        /PS -> Set this switch to print output to a PostScript
             document instead of plotting to the screen.

        /PDF -> Set this switch to create a PostScript document
             and then also create a PDF document.

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        The Unix utility "ps2pdf" must be installed on your system 
        for the /PDF keyword to work.  The ps2pdf utility should come
        standard with most Unix or Linux builds. 

 NOTES:
        None

 EXAMPLES
        DOCUMENT_COLOR_TABLE

             ; Prints out the color tables to the screen.
             ; Will set a 900x900 pixel window by default.
         
        DOCUMENT_COLOR_TABLE, /PS

             ; Prints color tables to a PostScript file
             ; called "table_info.ps".

        DOCUMENT_COLOR_TABLE, /PDF

             ; Prints out the color tables to a PostScript file
             ; "table_info.ps", then also creates a PDF file
             ; "table_info.pdf" using "ps2pdf".

 MODIFICATION HISTORY:
        phs, 21 Apr 2008: VERSION 1.00
        phs, 25 Mar 2009: GAMAP VERSION 2.13
                          - Added FUN keyword

(See /n/home09/ryantosca/IDL/gamap2/color/document_color_table.pro)


DRAWDOTONMAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        DRAWDOTONMAP

 PURPOSE:
        Draws a dot atop a world map, in order to highlight a given
        (lat,lon) location.  Also prints a label next to the point,
        and draws a line from the point to the label.

 CATEGORY:
        Plotting

 CALLING SEQUENCE:
        DRAWDOTONMAP, X, Y, R, THETA, NAME, COLOR  [, ALIGN=ALIGN ]

 INPUTS:
        X -> Longitude of the point to be drawn (degrees)

        Y -> Latitude of the point to be drawn (degrees)

        R -> Radius (in degrees) of the line that will extend from
             the point to the the label.

        THETA -> Angle (in the trigonometric sense, 0=due east) 
             which specifies the direction of the line that will
             connect the plot label to the point.

        NAME -> String for the plot label.  Default is ''.

        COLOR -> Color of the point to be plotted.  Default 
             is !MYCT.BLACK.  


 KEYWORD PARAMETERS:
        ALIGN -> Specifies the alignment of NAME.  Works in the same
             way as the ALIGN keyword to XYOUTS (e.g. ALIGN=0 is
             left-justified, ALIGN=0.5 is centered, ALIGN=1 is 
             right-justified).

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        SYM (function)

 REQUIREMENTS:
        Assumes that we are using a MYCT-defined colortable.

 NOTES:
        None

 EXAMPLE:
        MAP_SET, LIMIT=[ 10, -140, 55,-40 ], GRID=0, $
             COLOR=!MYCT.BLACK, /CYL, /NOBORDER

        MAP_CONTINENTS, /COUNTRIES, /COASTS, $
             COLOR=!MYCT.BLACK, /USA

        DRAWDOTONMAP, -71, 42, 3, 0, 'Harvard', !MYCT.RED

             ; Draws a USA map and then plots a dot at the (lat,lon) 
             ; of Harvard University.  The label will be plotted 3
             ; units away along THETA=0 (due east).

 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/plotting/drawdotonmap.pro)


EMISSION_DIFFERENCES

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EMISSION_DIFFERENCES

 PURPOSE:
        Creates emission difference plots ( New - Old ) for GEOS-Chem.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        EMISSION_DIFFERENCES, FILES, TAUS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "old" and "new" GEOS-Chem model versions
             that are to be compared. 

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        VERSIONS -> A 2-element vector containing the version
             numbers for the "old" and "new" GEOS-Chem model
             versions.

 KEYWORD PARAMETERS:
        /PS -> Set this switch to generate PostScript output.

        OUTDIR -> If /PS is set, then EMISSION_DIFFERENCES will
             create PostScript files in this directory.

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Included:
        ===========================================
        ComputeEmDiff   PlotEmDiff
        CreatePlots

        External Subroutines Required:
        ============================================
        OPEN_DEVICE     CLOSE_DEVICE
        MULTIPANEL      COLORBAR_NDIV    (function)
        TVMAP           CHKSTRU          (function)
        UNDEFINE        EXTRACT_FILENAME (function)  
        CTM_GET_DATA    ADD_SEPARATOR    (function)
     
 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLES:
        FILES    = [ 'ctm.bpch.v9-01-01', 'ctm.bpch.v9-01-02' ]
        TAUS     = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
        VERSIONS = [ 'v9-01-01', 'v9-01-02' ]
 
        EMISSION_DIFFERENCES, FILES, TAUS, VERSIONS, $
             /PS, OUTDIR='v9-01-02/output/'

             ; Creates emission difference plots of two GEOS-CHEM versions
             ; (in this case v9-01-02 - v9-01-01) for July 2005.

 MODIFICATION HISTORY:
        mps, 21 Apr 2015: Initial version based on emission_ratios.pro

(See /n/home09/ryantosca/IDL/gamap2/benchmark/emission_differences.pro)


EMISSION_MAPS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EMISSION_MAPS

 PURPOSE:
        Creates emission plots for GEOS-Chem tracers. 

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        EMISSION_MAPS, FILE, TAU, VERSION, [, Keywords ]

 INPUTS:
        FILE -> The name of the file containing data to be plotted.

        TAU  -> The TAU value (hours GMT from /1/1985) corresponding
                to the data to be plotted.

        VERSION -> The model version number corresponding to the
             data to be plotted.

 KEYWORD PARAMETERS:
        /PS -> Set this switch to generate PostScript output.

        OUTDIR -> If /PS is set, then EMISSION_MAPS will
             create PostScript files in this directory.

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Included:
        ===========================================
        CreatePlots     PlotEmissions

        External Subroutines Required:
        ============================================
        OPEN_DEVICE     CLOSE_DEVICE
        MULTIPANEL      COLORBAR_NDIV    (function)
        TVMAP           CHKSTRU          (function)
        UNDEFINE        EXTRACT_FILENAME (function)  
        CTM_GET_DATA    ADD_SEPARATOR    (function)
     
 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLES:
        FILE    = 'ctm.bpch.v10-01i'
        TAU     = NYMD2TAU( 20130701 )
        VERSION = 'v10-01i'
 
        EMISSION_MAPS, FILE, TAU, VERSION, /PS, OUTDIR='v10-01i/output/'

          ; Creates emission maps of GEOS-CHEM v10-01i for July 2013.

 MODIFICATION HISTORY:
        mps, 21 Apr 2015: Initial version based on emission_ratios.pro

(See /n/home09/ryantosca/IDL/gamap2/benchmark/emission_maps.pro)


EMISSION_RATIOS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EMISSION_RATIOS

 PURPOSE:
        Creates emission ratio plots ( New / Old ) for GEOS-Chem.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        EMISSION_RATIOS, FILES, LEVELS, TAUS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "old" and "new" GEOS-Chem model versions
             that are to be compared. 

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        VERSIONS -> A 2-element vector containing the version
             numbers for the "old" and "new" GEOS-Chem model
             versions.

 KEYWORD PARAMETERS:
        /PS -> Set this switch to generate PostScript output.

        OUTDIR -> If /PS is set, then EMISSION_RATIOS will
             create PostScript files in this directory.

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Included:
        ===========================================
        ComputeEmRatios   PlotEmRatio
        CreatePlots

        External Subroutines Required:
        ============================================
        OPEN_DEVICE     CLOSE_DEVICE
        MULTIPANEL      COLORBAR_NDIV    (function)
        TVMAP           CHKSTRU          (function)
        UNDEFINE        EXTRACT_FILENAME (function)  
        CTM_GET_DATA    ADD_SEPARATOR    (function)
     
 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLES:
        FILES    = [ 'ctm.bpch.v9-01-01', 'ctm.bpch.v9-01-02' ]
        TAUS     = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
        VERSIONS = [ 'v9-01-01', 'v9-01-02' ]
 
        EMISSION_RATIOS, FILES, TAUS, VERSIONS, $
             /PS, OUTDIR='v9-01-02/output/'

             ; Creates emission ratio plots of two GEOS-CHEM versions
             ; (in this case v9-01-02 / v9-01-01) for July 2005.

 MODIFICATION HISTORY:
        bmy, 10 Jun 2011: VERSION 1.00
                          - Initial version, based on "ratios.pro"
                          - Make sure directory ends with a path
                            separator character
        bmy, 23 Jun 2011: - Add ratio plot for lightning NOx
        bmy, 27 Jun 2011: - Now split top-title into 2 lines
        bmy, 11 Aug 2011: VERSION 1.01
                          - Fix bug by making values less than 0.5
                            not show up as missing data.
        bmy, 16 Dec 2011: GAMAP VERSION 2.16
                          - Remove ACET from dryleaf and ACET from
                            grass.  These were GEIA diagnostics,
                            which are now obsoleted.
        mps, 02 Apr 2013: Renamed NOx-xxxx emissions diagnostics to
                          NO-xxxx. NO emissions have now replaced
                          NOx emissions in GEOS-Chem (v9-02h). 
        mps, 15 Jul 2013: Fixed bug in MaxLev: Now plot column NO for
                          anthro, aircraft, and lightning emissions.
        mps, 25 Nov 2014: Now plot anthro + biofuel emissions because HEMCO
                          does not separate them
        ewl, 18 Mar 2015: Bug fixes: change NO, SO2, and SO4 anthro level 
                          from 2 to 1; change 'Tracer_bf ge 1' to 'Tracer_bf 
                          ge 0' to add biofuels to anthro in Create_Plots;
                          change Files index from 0 to 1 for Data2 err msg. 

(See /n/home09/ryantosca/IDL/gamap2/benchmark/emission_ratios.pro)


EOS_GETGR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EOS_GETGR

 PURPOSE: 
        Convenience routine to read variables from an HDF-EOS
        grid data structure.

 CATEGORY:
        File & I/O, Scientific Data Formats

 CALLING SEQUENCE:
        DATA = EOS_GETGR( FID, NAME [, Keywords, _EXTRA=e ] )

 INPUTS:
        FID -> HDF-EOS File ID, as returned by routine EOS_GD_START.

        NAME -> Name of the HDF-EOS grid dataset variable that
             you want to extract from the HDF-EOS file. 

 KEYWORD PARAMETERS:
        GRIDNAME -> Name of the HDF-EOS grid under which the data
             is stored in the file.  You can use the IDL HDF_BROWSER
             routine to easily find the grid name. 

        _EXTRA=e -> Passes extra keywords to routine EOS_SW_READFIELD.

 OUTPUTS:
        DATA -> Array containing extracted data from the HDF-EOS file.

 SUBROUTINES:
        None

 REQUIREMENTS:
        Need to use a version of IDL w/ HDF-EOS routines installed.

 NOTES:
        None

 EXAMPLE:

        ; Make sure HDF is supported on this platform
        IF ( EOS_EXISTS() eq 0 ) then MESSAGE, 'HDF not supported!'

        ; Open the HDF file and get the file ID # (FID)
        FID = EOS_GD_OPEN( 'gridfile.hdf', /READ )
        IF ( FID lt 0 ) THEN MESSAGE, 'Error opening file!'

        ; Read a variable from a grid file
        DATA = EOS_GETGR( fId, 'Latitude', GRIDNAME='GRID1' )

        ; Close the file 
        STATUS = EOS_GD_CLOSE( FID )
        IF ( STATUS lt 0 ) THEN MESSAGE, 'Error closing file!'

 MODIFICATION HISTORY:
        bmy, 18 Sep 2002: TOOLS VERSION 1.51
        bmy, 19 Dec 2002: TOOLS VERSION 1.52
                          - fixed typos
        bmy, 04 Jun 2003: TOOLS VERSION 1.53
                          - fixed more typos
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/eos_getgr.pro)


EOS_GETSW

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EOS_GETSW

 PURPOSE: 
        Convenience routine to read variables from an HDF-EOS
        satellite swath data structure.

 CATEGORY:
        File & I/O, Scientific Data Formats

 CALLING SEQUENCE:
        DATA = EOS_GETSW( FID, NAME [, Keywords, _EXTRA=e ] )

 INPUTS:
        FID -> HDF File ID, as returned by routine EOS_SW_START.

        NAME -> Name of the satellite swath dataset variable that
             you want to extract from the HDF-EOS file. 

 KEYWORD PARAMETERS:
        SWATHNAME -> Name of the HDF-EOS swath under which the data
             is stored in the file.  You can use the IDL HDF_BROWSER
             routine to easily find the swath name. 

        _EXTRA=e -> Passes extra keywords to routine EOS_SW_READFIELD.

 OUTPUTS:
        DATA -> Array containing extracted data from the HDF-EOS file.

 SUBROUTINES:
        None

 REQUIREMENTS:
        Need to use a version of IDL w/ HDF-EOS routines installed.

 NOTES:
        None

 EXAMPLE:

        ; Make sure HDF is supported on this platform
        IF ( EOS_EXISTS() eq 0 ) then MESSAGE, 'HDF not supported!'

        ; Open the HDF file and get the file ID # (FID)
        FID = EOS_SW_OPEN( 'swathfile.hdf', /READ )
        IF ( FID lt 0 ) THEN MESSAGE, 'Error opening file!'

        ; Read a variable from a swath file
        DATA = EOS_GETSW( fId, 'Latitude', SWATHNAME='swath1' )

        ; Close the file 
        STATUS = EOS_SW_CLOSE( FID )
        IF ( STATUS lt 0 ) THEN MESSAGE, 'Error closing file!'

 MODIFICATION HISTORY:
        bmy, 18 Sep 2002: TOOLS VERSION 1.51
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/eos_getsw.pro)


ERRORBAR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	 ERRORBAR

 PURPOSE:
        Plots error bars atop data points, 
        along the X or Y dimension.
  
 CATEGORY:
	 Plotting

 CALLING SEQUENCE:
	 ERRORBAR, XARR, YARR, ERROR [ , Keywords ]

 INPUTS:
        XARR, YARR -> Arrays of X and Y values correspoinding
             to the location of the data points.  XARR and YARR
             must have the same number of elements.

        ERROR -> An array (or scalar) of error values.  If ERROR
             is a scalar, its value will be used for all data
             points.  If ERROR is an array, it must be of the
             same dimension as XARR and YARR, or else an error
             message will be generated.

 KEYWORD PARAMETERS:
        /X -> If set, will plot error bars along the X-dimension.
             Default is to plot error bars along the Y-dimension.

 SUBROUTINES:
        None

 REQUIREMENTS
        None

 NOTES: 
        ERRORBAR just plots the error bars, but not the
        data points.  This is useful if you want to use 
        different colors for data points and error bars.

 MODIFICATION HISTORY:
        bmy, 21 Jul 1999: VERSION 1.01
                          - based on IDL routine OPLOTERR
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/plotting/errorbar.pro)


EXAMPLES_MANIP_4D

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EXAMPLES_MANIP_4D

 PURPOSE:
        Shows how to manipulate TS data saved as 4D array with
        GC_COMBINE_ND49 or GC_COMBINE_ND48.
        The routine loops over all available 4D data blocks and print 
        information for each of them.

 CATEGORY:
        GAMAP Data Manipulation, GAMAP Examples, Time Series

 CALLING SEQUENCE

        EXAMPLES_MANIP_4D, File [ , Keywords ]

 INPUTS:

        FILE -> The name of the file created by GC_COMBINE_ND48/9.


 OUTPUT KEYWORD PARAMETERS: 
  #### ONLY THE LAST DATA SET IF MORE THAN ONE IS AVAILABLE ####

        DATA -> Output keyword. Set to a variable name that will
             contain the data set on exist.

        LON -> Output keyword. Set to a variable name that will
             contain the vector of LONGITUDES on exit.

        LAT -> Output keyword. Set to a variable name that will
             contain the vector of LATITUDES on exit.

        TIME -> Output keyword. Set to a variable name that will
              contain the vector of TIME STEP on exit. Format is
              YYYYMMDD if daily max is asked for (see DMAX keyword),
              TAU value else.

        LOCALTIME -> to get the output TIME in LOCALTIME. If there
             is more than one longitude in the data block, TIME
             becomes an array : one vector for each longitude.

 KEYWORD PARAMETERS:
        MAVG -> The window size (boxcar) of the moving average, if
             you want to apply one.

        DMAX -> Return daily maximum of the TS.

        VERBOSE -> to print some basic information about the data
                   set.

        _EXTRA=e -> Picks up extra keywords for routines


 OUTPUTS:
        With optional keyword.

 SUBROUTINES:

 REQUIREMENTS:
        References many routines from GAMAP package. Requires GAMAP
        v2.10 for handling 4D dataset.

 NOTES:

 EXAMPLES:

      file = dialog_pickfile()

      EXAMPLES_MANIP_4D, file, /v, data=ts, lat=lat, lon=lon, time=time

      PLOT, time-time[0], ts[0,0,0,*], title='Time series at lon='+ $
            strtrim(lon[0],2)+' / lat='+strtrim(lat[0],2)



 MODIFICATION HISTORY:
        phs, 6 Jun 2007: GAMAP VERSION 2.10
                          - Initial version

(See /n/home09/ryantosca/IDL/gamap2/examples/examples_manip_4d.pro)


EXAMPLE_ANIM_TS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EXAMPLE_ANIM_TS

 PURPOSE:
        Illustrates how to use XINTERANIMATE with GAMAP 
        timeseries routine GC_COMBINE_ND49.

 CATEGORY:
        GAMAP Examples, GAMAP Utilities

 CALLING SEQUENCE:
        EXAMPLE_ANIM_TS [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ================================================
        GC_COMBINE_ND49         MULTIPANEL
        MYCT                    PROGRAM_DIR (function)
        TAU2YYMMDD (function)   TVMAP

 REQUIREMENTS:
        Requires routines from the GAMAP package.

 NOTES:
        None

 EXAMPLE:
        EXAMPLE_ANIM_TS
             ; Creates sample animation from timeseries data.

 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.11

(See /n/home09/ryantosca/IDL/gamap2/examples/example_anim_ts.pro)


EXAMPLE_ND48_ND49

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EXAMPLE_ND48_ND49

 PURPOSE:
        Creates several example plots to illustrate the use of GAMAP
        timeseries routines GC_COMBINE_ND48 and GC_COMBINE_ND49.

 CATEGORY:
        GAMAP Examples, GAMAP Utilities, Time Series

 CALLING SEQUENCE:
        EXAMPLE_ND48_ND49 [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        /PNG -> Set this switch to save screen output
             Portable Network Graphics (PNG) format.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        =========================================
        GC_COMBINE_ND48   GC_COMBINE_ND49
        MULTIPANEL        PROGRAM_DIR (function)
        SCREEN2PNG

 REQUIREMENTS:
        Requires routines from the GAMAP package.

 NOTES:
        None

 EXAMPLE:
        EXAMPLE_ND48_ND49, /PNG
             ; Create example plots and save to PNG file.

 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.11

(See /n/home09/ryantosca/IDL/gamap2/examples/example_nd48_nd49.pro)


EXAMPLE_OVERPLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EXAMPLE_OVERPLOT

 PURPOSE:
        Example program for overlay of data with model results.
        This program is meant to provide a demonstration example
        rather than a ready-to-use program, so please copy it
        and adapt it to your needs.
          For a try, just call EXAMPLE_OVERPLOT with no options.
        Before you rewrite this code, try some of the keyword 
        options to get a feel how it works.

 CATEGORY:
        GAMAP Examples, GAMAP Utilities

 CALLING SEQUENCE:
        EXAMPLE_OVERPLOT [,DATA [,ALTITUDE]] [,keywords]

 INPUTS:
        DATA -> A vector with your vertical profile data. If nothing
           is supplied, a dummy ozone profile is generated.

        ALTITUDE -> Altitude vector correspondign to your data. If not
           supplied, a vector will be created ranging from 0-12 km.

 KEYWORD PARAMETERS:
        Keywords to select certain model results:
        DIAGN -> Name (or number) of a diagnostic. Default is 'IJ-AVG-$'

        TRACER -> A tracer number (default is 2 = 'Ox')

        TAU0 -> A time step value. You can specify a date using the
             NYMD2TAU function.

        Keywords to select the geographical domain:
        LONRANGE, LATRANGE -> 2-element vectors specifying the minimum
             and maximum longitude and latitude for the model results
             to be considered. Not that LONRANGE[1] < LONRANGE[0] is 
             possible, denoting a region across the Pacific.

        Keywords to change the appearance of the plot:
        TITLE -> Give your plot a title. Default is 'EXAMPLE PLOT'
             with longitude and latitude rang and date.
             If you are sure that you select only one data record each
             time, you can leave it up to CTM_PLOT to construct a title
             (simply remove the TITLE keyword in the call to CTM_PLOT).
             Note that you can take advantage of various "variables"
             with the '%NAME%' notation (see GAMAP documentation for
             details).

        _EXTRA -> Look at the documentation of CTM_PLOT and add your
             favorite keywords to the call to EXAMPLE_OVERPLOT. You are
             likely to use XRANGE or XSTYLE. 

 OUTPUTS:
        just a plot ;-)

 SUBROUTINES:
        none

 REQUIREMENTS:
        uses ctm_get_dat and ctm_plot as well as everything that is
        needed by these to.

 NOTES:

 EXAMPLE:
        EXAMPLE_OVERPLOT

        data = your_fancy_reading_routine(filename)
        EXAMPLE_OVERPLOT,data,tau0=nymd2tau(940601L)

 MODIFICATION HISTORY:
        mgs, 21 May 1999: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/examples/example_overplot.pro)


EXAMPLE_POLAR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EXAMPLE_POLAR

 PURPOSE:
        Quick and dirty examples of polar plots made with CTM_PLOT.

 CATEGORY:
        GAMAP Examples, GAMAP Utilities

 CALLING SEQUENCE:
        EXAMPLE_POLAR

 INPUTS:
        None

 KEYWORD PARAMETERS:
        /PS -> Set this switch to write output to a PostScript file.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        =================================
        MYCT     CTM_PLOT   MULTIPANEL

 REQUIREMENTS:
        None

 NOTES:
        none

 EXAMPLE:
        EXAMPLE_POLAR, /PS
             ; Create polar plots and save to PostScript file.

 MODIFICATION HISTORY:
        mgs, 20 Aug 1998: INITIAL VERSION
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - now uses FILE_WHICH to find ctm.bpch.examples
                          - rewritten for clarity
        bmy, 14 Mar 2008: GAMAP VERSION 2.12
                          - Bug fix: save output from FILE_WHICH to
                            FILE (instead of FILENAME)
                                

(See /n/home09/ryantosca/IDL/gamap2/examples/example_polar.pro)


EXAMPLE_TVMAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EXAMPLE_TVMAP

 PURPOSE:
        Generates several example plots using CTM_PLOT and TVMAP.

 CATEGORY:
        GAMAP Examples, GAMAP Utilities

 CALLING SEQUENCE:
        EXAMPLE_TVMAP [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        /PNG -> Set this switch to save screen output
             Portable Network Graphics (PNG) format.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ====================================
        CTM_PLOT     MULTIPANEL
        MYCT         NYMD2TAU  (function)
        SCREEN2PNG   TVMAP

 REQUIREMENTS:
        Requires routines from the GAMAP package.

 NOTES:
        None

 EXAMPLE:

        EXAMPLE_TVMAP, /SAMPLE
             ; Create example plots with pixel plots for all plots.

        EXAMPLE_TVMAP, /PNG
             ; Create example plots and save to a PNG file.

 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.11

(See /n/home09/ryantosca/IDL/gamap2/examples/example_tvmap.pro)


EXPAND_CATEGORY (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EXPAND_CATEGORY  (function)

 PURPOSE:
        Replace wildcards in a multilevel diagnostic category
        and return a string array with one entry for each 
        level.

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        xcatgeory = EXPAND_CATEGORY(category)

 INPUTS:
        CATGEORY -> The original category name containing one
            wildcard character (see CTM_DIAGINFO). If category 
            does not contain a wildcard character, the category
            will be returned unchanged.

 KEYWORD PARAMETERS:
        RANGE -> A level index or range of level indices (2-elements)
            to be returned. Default is to return the maximum
            possible range (currently 1..24).

        WILDCHARD -> a character value that is searched for as
            wildchard. Default is '$' which is used in CTM_DIAGINFO
            to denote a varying level index.

        /NO_DELETE -> if set, will return category with wildcard as
            first entry in result list. Default is to delete the 
            wildcard string. 

 OUTPUTS:
        A string array with category names.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        PRINT, EXPAND_CATEGORY('IJ-AVG-$')

             ; prints IJ-AVG-1 IJ-AVG-2 IJ-AVG-3 ... 
             ;        ... IJ-AVG-A IJ-AVG-B ...

        print, EXPAND_CATEGORY( 'IJ-AVG-$', range=5 )

             ; prints IJ-AVG-5 

 MODIFICATION HISTORY:
        mgs, 19 Aug 1998: VERSION 1.00
        mgs, 26 Oct 1998: added no_delete keyword
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - added extra letters for grids w/
                            more than about 30 layers

(See /n/home09/ryantosca/IDL/gamap2/internals/expand_category.pro)


EXTRACT_COMMENTS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EXTRACT_COMMENTS

 PURPOSE:
        Split a string returned from READDATA.PRO into 
        items of a string array.

 CATEGORY:
        General

 CALLING SEQUENCE:
        RESULT = EXTRACT_COMMENTS( COMMENTS, INDEX, DELIM=' ' ) 

 INPUTS:
        COMMENTS -> String array of comment lines returned from
            readdata.pro

        INDEX -> line number of comments to be analyzed

 KEYWORD PARAMETERS:
        DELIM -> delimiter character between items. Default: 1 blank.

 OUTPUTS:
        RESULT -> A string array containing the single "words" 
             of 1 comment line.

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        STRBREAK (function)

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        UNITS = EXTRACT_COMMENTS( comments, 2, delim=' ' )

 MODIFICATION HISTORY:
        mgs, 10 Nov 1997: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now use version-independent STRBREAK
                            routine instead of older STR_SEP routine

(See /n/home09/ryantosca/IDL/gamap2/general/extract_comments.pro)


EXTRACT_FILENAME

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EXTRACT_FILENAME

 PURPOSE:
        Extract the filename from a fully qualified filepath

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
        FILENAME = EXTRACT_FILENAME( FULLNAME [ , Keywords ] ) 

 INPUTS:
        FULLNAME --> a fully qualified filename containing path information.

 KEYWORD PARAMETERS:
        FILEPATH --> a named variable that returns the path of the
           file. This can be used if both, the filename and the name
           of the file will be used. Otherwise it is recommended to
           use EXTRACT_PATH instead.

 OUTPUTS:
        A string containing the filename to be analyzed.

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        ADD_SEPARATOR (function)

 REQUIREMENTS:
        Requires routines from the TOOLS package.

 NOTES:
        See also EXTRACT_PATH

 EXAMPLE:
        PRINT, EXTRACT_FILENAME( '~/IDL/tools/extract_filename.pro')
           extract_filename.pro

             ; Prints just the file name part of a longer path.

        PRINT,EXTRACT_FILENAME( 'example.dat', filepath=filepath )
             example.dat'
             ; will print  'example.dat', and filepath will contain ''


 MODIFICATION HISTORY:
        mgs, 18 Nov 1997: VERSION 1.00
        mgs, 21 Jan 1999: - added extra check for use of '/' path 
                            specifiers in Windows OS;
        bmy, 19 Jan 2000: TOOLS VERSION 1.44
                          - replaced obsolete RSTRPOS( ) command with
                            STRPOS( /REVERSE_SEARCH ) for IDL 5.3+
                          - updated comments, few cosmetic changes
        bmy, 13 Mar 2001: TOOLS VERSION 1.47
                          - Add support for MacOS operating system
        bmy, 17 Jan 2002: TOOLS VERSION 1.50
                          - now call RSEARCH for backwards compatibility
                            with versions of IDL prior to v. 5.2
                          - use FORWARD_FUNCTION to declare RSEARCH
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - now use ADD_SEPARATOR
                          - updated comments

(See /n/home09/ryantosca/IDL/gamap2/file_io/extract_filename.pro)


EXTRACT_PATH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        EXTRACT_PATH

 PURPOSE:
        Extract the file path from a full qualified filename

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
        Path = EXTRACT_PATH( FULLNAME [, Keywords] )

 INPUTS:
        FULLNAME --> a fully qualified filename. If this input is
           already a path it must end with the delimiter '/' (Unix),
           '\' (Windows), or ':' (MacOS).

 KEYWORD PARAMETERS:
        FILENAME --> a named variable that returns the name of the
           file. This can be used if both, the path and the name
           of the file will be used. Otherwise it is recommended to
           use EXTRACT_FILENAME instead.

 OUTPUTS:
        A string containing the path to the file given.

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        ADD_SEPARATOR (function)   
        RSEARCH (function)

 REQUIREMENTS:
        None

 NOTES:
        See also EXTRACT_FILENAME

 EXAMPLE:
        print,extract_path('~mgs/IDL/tools/extract_path.pro')

             will print  '~mgs/IDL/tools/'

        print,extract_path('example.dat',filename=filename)

             will print  '', and filename will contain 'example.dat'


 MODIFICATION HISTORY:
        mgs, 18 Nov 1997: VERSION 1.00
        mgs, 21 Jan 1999: - added extra check for use of '/' path 
                            specifiers in Windows OS
        bmy, 19 Jan 2000: TOOLS VERSION 1.44
                          - replaced obsolete RSTRPOS( ) command with
                            STRPOS( /REVERSE_SEARCH ) for IDL 5.3+
                          - updated comments, few cosmetic changes
        bmy, 13 Mar 2001: TOOLS VERSION 1.47
                          - Add support for MacOS operating system
        bmy, 17 Jan 2002: TOOLS VERSION 1.50
                          - now call RSEARCH for backwards compatibility
                            with versions of IDL prior to v. 5.2
                          - use FORWARD_FUNCTION to declare RSEARCH
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now use ADD_SEPARATOR
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/file_io/extract_path.pro)


E_H2O

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        E_H2O  

 PURPOSE:
        Calculate water vapour pressure for a given temperature

 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        RESULT = E_H2O( TEMPERATURE [,/WATER,/ICE,minval=minval] )

 INPUTS:
        TEMPERATURE --> dew or frostpoint reading in K. If you supply
              the dry air temperature (or static air temperature),
              you will get a value for the water vapor saturation 
              pressure.

 KEYWORD PARAMETERS:
        /WATER --> interprete temperature as dewpoint (default)

        /ICE --> interpret temperature as frostpoint

        MINVAL -> minimum valid data value (default -1.0E30)

 OUTPUTS:
        RESULT -> The water vapour pressure [hPa]

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        The algorithm has been taken from the NASA GTE project data
        description.

 EXAMPLE:
        PH2O = E_H2O(266.)

             ; Calculate water vapor pressure for a 
             ; dewpoint reading of 266 K

        RH = PH2O/E_H2O(283.)

             ; Compute relative humidity 
             ; (divide ph2o by saturation pressure of DRY temperature)

        PRINT,PH2O,RH
          3.61742     0.294607
 
             ; Prints values        

 MODIFICATION HISTORY:
        mgs, 23 Feb 1997: VERSION 1.00
        mgs, 03 Aug 1997: split e_h2o and rh, renamed, added template
        mgs, 23 May 1998: changed default behaviour to set reference
               temperature to given TD value
        mgs, 29 Aug 1998: VERSION 2.00
          - much simpler and more logical interface
          - no automatic detection of dew- or frostpoint any longer
          - can now accomodate arrays
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/e_h2o.pro)


FCONVERT_UNIT (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FCONVERT_UNIT (function)

 PURPOSE:
        Wrapper for CONVERT_UNIT.  Passes all of the input data to
        CONVERT_UNIT and returns the result to the calling program.

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        RESULT = FCONVERT_UNIT( DATA, UNIT, TOPARAM [, Keywords ] )

 INPUTS:
        DATA -> A data vector, array, or a single value that shall
            be converted to a new unit. 

        UNIT -> A string variable containing the (current) unit of 
            DATA. This will be replaced by the new unit afterwards.
            If omitted, you must give the FROM_UNIT keyword to 
            indicate the current unit of DATA.

        TOPARAM -> The unit to convert DATA to. This is equivalent to 
            the keyword TO_UNIT and overwrites it.;  

 KEYWORD PARAMETERS:
        RESULT -> returns 1 if conversion was successful, 0 otherwise
            This keyword is mostly for consistency witholder routines.
            It is more convenient to test !ERROR_STATE.CODE for being
            0.

        _EXTRA=e -> Passes extra keywords to CONVERT_UNIT.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        CONVERT_UNIT 

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:

 MODIFICATION HISTORY:
        mgs, 26 Aug 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Added std documentation header

(See /n/home09/ryantosca/IDL/gamap2/math_units/fconvert_unit.pro)


FILE_EXIST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FILE_EXIST

 PURPOSE:
        FILE_EXIST checks to see whether a specified file
        can be found on disk, or if it does not exist.

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
        RESULT = FILE_EXIST( FILE [,OPTIONS])

 INPUTS:
        FILE (str) --> the name of the file to be checked

 KEYWORD PARAMETERS:
        PATH -> a path string (e.g. the IDL system variable !PATH)
            or a list (string array) of directory names to be
            searched for FILE. Under Unix, a trailing '/' is 
            attached to each entry; under Windows, a trailing 
            '\'; under MacOS, a trailing ':'.  VMS isn't supported. 

        FULL_PATH -> returns the path of FILE if found.  This is 
            not a true systemwide path but rather a combination
            of a PATH element (which may be relative) and FILE.

        DIRNAMES -> This keyword is now replaced by PATH, and 
            should not be used any more.

 OUTPUTS:
        RESULT -> =1 if the file is found or =0 otherwise

 SUBROUTINES:
        External Subroutines Required:
        ================================================
        ADD_SEPARATOR (function)   MFINDFILE (function)

 REQUIREMENTS:
        Requires routines from the TOOLS package.

 NOTES:
        (1) The PATH entries are expanded prior to use, so it is 
            possible to specify e.g. '~mgs/bla.pro'

        (2) FILE_EXIST will always return the first file it 
            finds that matches your specification. 

 EXAMPLES: 
        (1)
        IF ( FILE_EXIST( 'file_exist.pro' ) ) THEN PRINT, 'Found it!'

             ; Search for file_exist.pro 
       
        (2)
        DIRS = [ '../', '~/DATA/' ]
        OK   = FILE_EXIST( 'test.dat', path=dirs, full=path )
        IF ( OK ) THEN OPENR, U1, PATH
        ...
 
             ; Search for a file given a list of directories.
             ; If file is found, then open it for reading.
         
        
 MODIFICATION HISTORY:
        mgs, 26 Sep 1997: VERSION 1.00
        mgs, 28 Sep 1997: - added expand_path() in order to digest ~-pathnames
                          - initializes FULL_PATH with a zero string
        mgs, 06 Nov 1997: - replaced DIRNAMES by PATH and added 
                            string seperation if PATH is a path
                            string with multiple entries
        mgs, 05 Feb 1998: - bug fix: use expand_path also if only 
                            filename is given
        bmy, 13 Mar 2001: TOOLS VERSION 1.47
                          - now supports Windows, MacOS, and Unix
                          - cosmetic change, updated comments
        bmy, 17 Jan 2002: TOOLS VERSION 1.50
                          - now call STRBREAK wrapper routine from
                            the TOOLS subdirectory for backwards
                            compatiblity for string-splitting;
        bmy, 03 Oct 2003: TOOLS VERSION 1.53
                          - minor bug fix: FILE must be placed w/in
                            the call to EXPAND_PATH for IDL 6.0+
                          - deleted obsolete code from Jan 2002
        bmy, 28 May 2004: TOOLS VERSION 2.02
                          - now call MFINDFILE instead of FINDFILE,
                            since MFINDFILE will call the new
                            FILE_SEARCH program for IDL 5.5+
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now use ADD_SEPARATOR
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/file_io/file_exist.pro)


FIND_CELLS_BY_COUNTRY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FIND_CELLS_BY_COUNTRY

 PURPOSE:
        Returns an index array which can be used to determine 
        which CTM grid boxes lie within a given country.

 CATEGORY:
        GAMAP Utilities

 CALLING SEQUENCE:
        RESULT = FIND_CELLS_BY_COUNTRY( COUNTRYID, GRIDINFO [, Keywords] )

 INPUTS:
        COUNTRYID -> Name of the country you are interested in, OR
             the country ID number ID from "countries.table".  

        GRIDINFO -> Structure from CTM_GRID which defines the output
             CTM model grid in which you wish to find a given country.

 KEYWORD PARAMETERS:
        /MAXIMIZE -> Set this switch to search for all grid boxes that
             contain any portion of the specified country.  The
             default is to determine the specified country by the
             center of the grid box.

        /INDEX -> Set this switch to return RESULT as an 1-D index 
             vector (i.e. similar to output from the WHERE command). 

 OUTPUTS:
        RESULT -> Integer index array for OUTGRID.  Grid boxes where 
             RESULT[I,J] = 1 designate the desired country.  If the
             /INDEX flag is set then RESULT will be an 1-D index
             vector (i.e. similar to output from the WHERE command). 
       
 SUBROUTINES:
        Internal Subroutines:
        ============================
        GET_COUNTRY_NUMBER (function)

        External Subroutines Required:
        ===========================================
        CHKSTRU  (function)    CTM_GRID (function)
        CTM_TYPE (function)    DATATYPE (function)
        STRBREAK (function) 

 REQUIREMENTS:
        None

 NOTES:
        (1) Requires the following input files:
            (a) countries.table                
            (b) countries.generic.025x025.gif

        (2) The search algorithm is brute-force (i.e. FOR loops
            over lat & lon).  Maybe in a later version we can 
            optimize this w/ IDL array notation.

 MODIFICATION HISTORY:
  tmf & bmy, 01 Jul 2006: GAMAP VERSION 2.05
                          - Initial version
  bmy & phs, 27 Jul 2007: GAMAP VERSION 2.10
                          - Use FILE_WHICH to find countries.table
                          - Use FILE_WHICH to find countries.gif 

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/find_cells_by_country.pro)


FIND_TRACER_INDEX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FIND_TRACER_INDEX

 PURPOSE:
        Given the diagnostic category and tracer name, returns the
        tracer number as specified in the "tracerinfo.dat" file.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        RESULT = FIND_TRACER_INDEX( DIAGN, NAME )

 INPUTS:
        DIAGN -> Diagnostic category name as specified in the
             "diaginfo.dat" file (e.g. "IJ-AVG-$", "GMAO-2D", etc.).

        NAME -> Tracer name as specified in the "tracerinfo.dat"
              file (e.g. NOx, Ox, CO, PS, TAUCLI, etc.)

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> Tracer number corresponding to NAME and DIAGN.

 SUBROUTINES:
        External subroutines required:
        ------------------------------
        CTM_DIAGINFO   CTM_TRACERINFO

 REQUIREMENTS:
        Requires routines from the GAMAP package.

 NOTES:
        Here, "tracer" is used in the wider sense.  It can be can be 
        any quantity saved out from a CTM diagnostic output, as long
        as it is specified by "diaginfo.dat" and "tracerinfo.dat".

 EXAMPLE:
        PRINT, FIND_TRACER_INDEX( 'GMAO-2D', 'PS' )
        IDL prints   5931

             ; Returns the tracer index number for the "PS"
             ; quantity in the "GMAO-2D" diagnostic category.
             
 MODIFICATION HISTORY:
        bmy, 06 Aug 2010: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/find_tracer_index.pro)


FIND_UNIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FIND_UNIT

 PURPOSE:
        Return classification and conversion information for
        physical units. You pass a unit name, and you will
        get a standard form of that name as well as a factor
        and an offset that convert the unit to SI standard.
        To convert one unit to another, use FIND_UNIT twice
        (see example below).

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        FIND_UNIT,NAME,STDNAME,FACTOR,OFFSET,CATEGORY [,keywords]

 INPUTS:
        NAME -> A string containing the name to search for

 KEYWORD PARAMETERS:
        /GET_SI -> Return the name of the SI unit of the category of 
            the given unit. Factor and offset will always be 1.0 and 
            0.0, CATEGORY will contain the category number.
 
        /NO_STANDARD -> Do not return the standard name of a unit. The
            standard spelling is identified as the first occurrence
            of a given unit with the same conversion factor and offset
            in the same category and normally replaces the input name.

        /TEST -> Check standard unit strings for consistency
            This keyword is only useful when you add extra units.

 OUTPUTS:
        STDNAME -> The unit name as saved in the stdunits array
            (e.g. 'KG' is returned as 'kg')

        FACTOR -> A conversion factor to SI 

        OFFSET -> A conversion offset

        CATEGORY -> The class to which the unit belongs:
           -1 : unit not found
            0 : distance
            1 : area
            2 : volume
            3 : time
            4 : frequency
            5 : speed
            6 : accelaration
            7 : temperature
            8 : weight
            9 : pressure
           10 : force
           11 : energy
           12 : power
           13 : mixing ratio
           14 : currency
           15 : voltage

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        FIND_UNIT,'kM/H',stdname,factor,offset,category
        print,stdname,factor,offset,category
        ; prints km/h     0.277780      0.00000       5

        ; conversion from Fahrenheit to Celsius
        temp = [ 0., 32., 80., 100. ]
        FIND_UNIT,'F',fromname,fromfac,fromoff,fromcat
        FIND_UNIT,'C',toname,tofac,tooff,tocat
        if (fromcat ne tocat) then print,'bullsh...'
        ctemp = ((fromfac*temp+fromoff) - tooff) / tofac
        print,ctemp
        ; prints  -17.7778  0.000152588   26.6670   37.7782

        ; find name of corresponding SI unit 
        FIND_UNIT,'mph',stdname,/get_si
        print,stdname
        ; prints  m/s

        ; find standard form of any unit
        FIND_UNIT,'miles/hour',stdname
        print,stdname
        ; prints  mph

 MODIFICATION HISTORY:
        mgs, 26 Aug 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/math_units/find_unit.pro)


FIX_MANUAL_HTML

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FIX_MANUAL_HTML

 PURPOSE:
        Removes text from the GAMAP manual pages that is
        automatically inserted by IDL's MK_HTML_HELP routine,
        and replaces them with better HTML code.

 CATEGORY:
        Documentation

 CALLING SEQUENCE:
        FIX_MANUAL_HTML

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ======================================================
        EXTRACT_FILENAME (function)   EXTRACT_PATH (function)
        MFINDFILE        (function)   OPEN_FILE    
        REPLACE_TOKEN    (function)

 REQUIREMENTS:
        Requires routines from the GAMAP package

 NOTES:
        Also see routines GAMAP2_HTML and IDL2HTML.

 EXAMPLE:
        GAMAP2_HTML, /ALL,         OUTDIR='manual/html/all'
        GAMAP2_HTML, /BY_CATEGORY, OUTDIR='manual/html/by_category'
        GAMAP2_HTML, /BY_ALPHABET, OUTDIR='manual/html/by_alphabet'
        FIX_MANUAL_HTML

             ; Creates GAMAP manual pages (HTML format) and then
             ; removes unwanted text that is automatically added
             ; by IDL's MK_HTML_HELP routine.

 MODIFICATION HISTORY:
        bmy, 23 Apr 2008: GAMAP VERSION 2.12
        bmy, 06 Aug 2010: GAMAP VERSION 2.14
                          - Stop w/ error if "gamap_manual_replace.html"
                            file cannot be found

(See /n/home09/ryantosca/IDL/gamap2/doc/fix_manual_html.pro)


FORMAT_INP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FORMAT_INP

 PURPOSE:
        Display one line of S-type input file for CHEM1D model
        formatted so that each line contains name, unit, value and
        scaling factor of 1 species (may help to find errors).
        
 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        FORMAT_INP, FILENAME [ , Keywords ]

 INPUTS:
        FILENAME -> name of the input file

 KEYWORD PARAMETERS:
        OUTFILE -> filename for ASCII file with formatted output
             (default: FILENAME+'.formatted')

        SKP1, SKP2, DELIM -> parameters for READDATA routine:
             number of lines to skip before variable names and 
             delimiter for variable names (defaults: 1, 3, and ' ')

        LINE -> data line to be displayed (default=1)

        SIMPLE -> assume no unit and scale factor line, and print
             dummies instead. Will be automatically set if SKP2 is 
             less than 2.

 OUTPUTS:
        Screen output and output to file OUTFILE

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        READDATA

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        FORMAT_inp, 'test.inp', LINE=3

        will display the third line of a chem1d input file test.inp in a
        format similar to:
               NAME         UNIT       VALUE       SCALE
          O3_COLUMN           DU     227.330   2.687e+16
        DECLINATION          deg      -1.634   1.000e+00
               PSMB           mb     238.434   1.000e+00
    ...

 MODIFICATION HISTORY:
        mgs, 18 Dec 1997: VERSION 1.00
        mgs, 11 Jun 1998: - added SIMPLE and SKP2 keyword
        mgs, 30 Oct 1998: - bug fix with units and scale
                          - improved formatting for large numbers
                            (allows display of chem1d output files)
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/format_inp.pro)


FORMSTRLEN (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FORMSTRLEN (function)

 PURPOSE:
        Return the (approximated) length of a string that 
        contains Hershey formatting characters. If the string 
        does not contain any formatting characters, the result
        equals that of STRLEN, otherwise it will be shorter.
        Hershey characters ('!'+1 char) are ignored, characters in
        super or subscript mode are counted as of width 0.6

 CATEGORY:
        Strings, Plotting

 CALLING SEQUENCE:
        LEN = FORMSTRLEN( S )

 INPUTS:
        S -> A string that may contain Hershey formatting characters.
             As with STRLEN, S may be a string array.

 KEYWORD PARAMETERS:
        none

 OUTPUTS:
        A float(!) value that gives the "true" length of the string

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        PRINT, FORMSTRLEN('C2H6')
           4

        PRINT, FORMSTRLEN('C!L2!NH!L6!N')
           3.2

 MODIFICATION HISTORY:
        mgs, 27 Oct 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments 

(See /n/home09/ryantosca/IDL/gamap2/strings/formstrlen.pro)


FREQ_DIST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FREQ_DIST   

 PURPOSE:
        Creates frequency distribution and percentile plots
        for GEOS-CHEM tracers from benchmark simulations.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        FREQ_DIST, FILES, TAUS, TRACERS, VERSIONS [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "old" and "new" GEOS-Chem model versions
             that are to be compared. 

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        TRACERS -> The list of transported tracers (i.e. diagnostic
             category "IJ-AVG-$").

        VERSIONS -> A 2-element vector containing the version
             numbers for the "old" and "new" GEOS-Chem model
             versions.

 KEYWORD PARAMETERS:
        /DO_FULLCHEM -> Set this switch to plot the chemically
             produced OH and aerosol optical depths in addition 
             to the advected tracers.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output 
             to a file whose name is specified by this keyword.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==========================================
        OPEN_DEVICE    CLOSE_DEVICE
        MULTIPANEL     EXTRACT_FILENAME (function)        
        CTM_GET_DATA   

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.

 NOTES:
 
        (2) Assumes the version # is located at the end of FILENEW.

        (3) Assumes the following diagnostics are archived in FILENEW:
            (a) ND43 ("CHEM-L=$"): Fullchem benchmark
            (b) ND45 ("IJ-AVG-$"): Radon and Fullchem benchmarks
        
 EXAMPLE:
        FILES    = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
        TAUS     = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
        VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
 
        FREQ_DIST, FILES, LEVELS, TAUS, VERSIONS, $
             /DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'

             ; Creates a frequency-ratio plot from the data
             ; files for GEOS-Chem versions v7-04-10 and v7-04-11

 MODIFICATION HISTORY:
        bmy, 12 Aug 2002: VERSION 1.01
                          - adapted from Isabelle Bey's "comparison.pro"
        bmy, 21 Jan 2003: VERSION 1.02
                          - increased from 24 to 31 tracers  
        bmy, 28 Apr 2004: VERSION 1.03
                          - increased from 31 to 35 tracers
        bmy, 03 May 2004: VERSION 1.04
                          - increased from 35 to 39 tracers
        bmy, 21 May 2004: VERSION 1.05
                          - increased from 39 to 41 tracers
        bmy, 02 Nov 2004: VERISION 1.06
                          - bug fix: now print out top title on each
                            page (when it is the first panel)
        bmy, 06 May 2005: VERSION 1.07
                          - Now use -9.99e30 to flag strat boxes
        bmy, 08 Jul 2005: VERSION 1.08
                          - Increased from 41 to 43 tracers
        bmy, 09 Nov 2007: VERSION 1.09
                          - Modified argument list and some 
                            internal variable names.
                          - Removed Radon keyword
        bmy, 25 May 2011: VERSION 1.10
                          - Added /DO_FULLCHEM keyword
        bmy, 17 Apr 2012: GAMAP VERSION 2.16
                          - Omit modelname error check
        

(See /n/home09/ryantosca/IDL/gamap2/benchmark/freq_dist.pro)


FULLCHEM_BUDGET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FULLCHEM_BUDGET

 PURPOSE:
        Computes the budgets of Ox and CO from the GEOS-CHEM model.
        for full chemistry benchmark simulations.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        FULLCHEM_BUDGET [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        TAU0 -> Time index of the data to plot.  Units are hours 
             since 0 GMT on 1/1/1985.  Default is 144600D (July 1, 2001).

        FILENEW -> Name of a binary punch file containing model
             output from a "New" version of the GEOS-CHEM. 
             If omitted, a dialog box will prompt the user to
             supply a file name.   

        OUTFILENAME -> Name of the file where budget information
             will be written to.  Default is "(VERSION).budget.fullchem", 
             where VERSION is the version number contained w/in
             FILENEW.

        INITIALFILE -> Name of a binary file containing the mass of
             Ox [in kg] at the start of a GEOS-CHEM model run.

        FINALFILE -> Name of a binary file containing the mass of
             Ox [in kg] at the end of a GEOS-CHEM model run.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ====================================
        OPEN_FILE     CTM_BOXSIZE (function)   
        CTM_GET_DATA  TAU2YYMMDD  (function)
        UNDEFINE      GETMODELANDGRIDINFO 

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.

 NOTES:
        (1) Assumes the version # is located at the end of FILENEW.

        (2) Assumes the following GEOS-CHEM diagnostics 
            have been archived in the input files:
            (a) ND24 ("EW-FLX-$")   (f) ND65 ("PORL-L=$")
            (b) ND25 ("NS-FLX-$")   (g) ND66 ("DAO-3D-$")
            (c) ND26 ("UP-FLX-$")   (h) ND68 ("BXHGHT-$")
            (d) ND44 ("DRYD-FLX")   (i)      ("TCMASS-$") 
            (e) ND45 ("CHEM-L=$")   (j)      ("TR-PAUSE")

 EXAMPLE:
        FULLCHEM_BUDGET, TAU0=144600D,
                         FILENEW='ctm.bpch.v5-01'
                         INITIALFILE='fullchem.mass.initial.v5-01',  $
                         FINALFILE='fullchem.mass.final.v5-01',      $
                         OUTFILENAME='v5-01.budget.fullchem'

 MODIFICATION HISTORY:
        bmy, 15 Aug 2002: VERSION 1.01
                          - adapted from Isabelle Bey's "budget.pro"
        bmy, 14 Jan 2003: VERSION 1.02
                          - In GEOS-CHEM v5-03+, ND44 saves out tracers
                            using the CTM tracer number 
        bmy, 30 Oct 2003: VERSION 1.03
                          - now call PTR_FREE to free the heap memory
                            so that we don't run out of memory
                          - now compute mean mass-weighted OH instead
                            of methyl chloroform lifetime
  ccc & bmy, 11 Aug 2010: VERSION 1.04
                          - Updated computation of Ox budget
        bmy, 10 Jan 2011: VERSION 1.05
                          - Updated 200hPa level for MERRA
        bmy, 08 Jun 2011: - Also print out MCF lifetime
        bmy, 11 May 2012: GAMAP VERSION 2.16
                          - Modified for GEOS-5.7.2 met
        mps, 06 Jan 2014: - Fix bug in calculation of WetYear so that wetdep
                            from convective updrafts is not double counted
                            (P. Kasibhatla)
        mps, 04 Mar 2016: - Modified for MERRA2 met

(See /n/home09/ryantosca/IDL/gamap2/benchmark/fullchem_budget.pro)


FULLCHEM_EMISSIONS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FULLCHEM_EMISSIONS

 PURPOSE:
        Prints totals of GEOS-CHEM emission species for two different
        model versions.  Also prints the difference in emission 
        totals between the two model versions.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        FULLCHEM_EMISSIONS [ , Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        FILENEW -> Name of a binary punch file containing model
             output from a "New" version of the GEOS-Chem   

        FILEOLD -> Name of a binary punch file containing model
             output from a "Old" version of the GEOS-Chem. 

        VERSION_NEW -> String that specifies the GEOS-Chem version 
             number pertaining to FILENEW.  If not specified, then 
             FULLCHEM_EMISSIONS will look for this at the end of
             the filename FILENEW.

        VERSION_OLD -> String that specifies the GEOS-Chem version 
             number pertaining to FILEOLD  If not specified, then 
             FULLCHEM_EMISSIONS will look for this at the end of
             the filename FILEOLD.

        OUTFILENAME -> Name of the text file where emission totals
             and differences will be sent.  Default is "emissions.txt".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines:
        ==================================
        GetVersionInfo (function)
        WriteHeader
        WriteTracers

        External Subroutines Required:
        ==================================
        CTM_SUM_EMISSIONS 
        UNDEFINE
        STRPAD (function)
 
 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.

 NOTES:
        (1) Assumes the version number is located at the end of
            both FILENEW and FILEOLD

        (2) Assumes that both FILENEW and FILEOLD contain the
            following GEOS-CHEM diagnostic categories:
            (a) ND06: DUSTSRCE
            (b) ND07: BC-ANTH,  BC-BIOB,  BC-BIOF,  PL-BC=$,
                      OC-ANTH,  OC-BIOB,  OC-BIOF,  PL-OC=$
            (c) ND08: SALTSRCE
            (d) ND11: ACETSRCE
            (e) ND13: DMS-BIOG, SO2-AC-$, SO2-AN-$, SO2-EV-$, 
                      SO2-NV-$, SO4-AN-$, NH3-ANTH, NH3-BIOB, 
                      NH3-BIOG, NH3-NATU, SO2-SHIP
            (f) ND28: BIOBSRCE
            (g) ND29: CO--SRCE
            (h) ND32: NO-AC-$,  NO-AN-$,  NO-BIOB,  NO-FERT, 
                      NO-LI-$,  NO-SOIL
            (i) ND34: BIOFSRCE
            (j) ND36: ANTHSRCE
            (k) ND46  BIOGSRCE

 EXAMPLE:
        FULLCHEM_EMISSIONS, FILENEW='ctm.bpch.v10-01e', $
                            FILEOLD='ctm.bpch.v10-01d', $
                            OUTFILENAME='emissions.txt'

             ; Prints emissions & differences between 
             ; versions v10-01d and v10-01e
                           
 MODIFICATION HISTORY:
        bmy, 18 Jun 2001: VERSION 1.00
        bmy, 20 Jun 2001: VERSION 1.01
                          - now omit ALD2 (#11) from ANTHROPOGENIC
        bmy, 20 Sep 2001: VERSION 1.02
                          - now print ND11 acetone sources, sinks
        bmy, 15 Aug 2002: VERSION 1.03
                          - renamed to FULLCHEM_EMISSIONS
                          - renamed FILE_NEW to FILENEW and 
                            FILE_OLD to FILEOLD
        bmy, 17 Jan 2003: VERSION 1.04
                          - also sum up sulfate emission categories
        bmy, 27 Mar 2003: VERSION 1.05
                          - adjust FORMAT string for branch versions
                          - now also print out NH3-NATU source
        bmy, 09 Apr 2004: VERSION 1.06
                          - Now print out emissions of BC/OC tracers
                          - Now print out hydrophilic BC/OC which
                            came from hydrophobic BC/OC
        bmy, 28 Apr 2004: VERSION 1.07
                          - Now print out dust emissions
        bmy, 03 May 2004: VERSION 1.08
                          - Now print out seasalt emissions
        bmy, 21 May 2004: VERSION 1.09
                          - Now print out ship exhaust SO2 emissions
        bmy, 08 Jul 2005: VERSION 1.10
                          - Updated for 43 tracers
        bmy, 10 Jan 2011: VERSION 1.11
                          - Now make numeric fields 13 chars wide to
                            allow for wider title headers
        bmy, 16 Dec 2011: GAMAP VERSION 2.16
                          - Remove ACET from dryleaf and ACET from
                            grass; these are obsolete GEIA quantities
        mps, 23 Jan 2014: - Now report NH3 emissions in Tg N
        bmy, 18 Aug 2014: GAMAP VERSION 2.18
                          - Now display Anthro + Biofuels together
                            which facilitates use w/ HEMCO emissions
        bmy, 18 Aug 2014: - Now pass VERSION_NEW and VERSION_OLD as
                            keywords.  If these are not specified, 
                            then FULLCHEM_EMISSIONS will obtain these
                            from the filenames FILENEW and FILEOLD.
        ewl, 18 Mar 2015: - Replace SO2-BF-$ and SO4-BF-$ with SO2-BIOF
                            and SO4-BIOF in anthro+biofuel section.

(See /n/home09/ryantosca/IDL/gamap2/benchmark/fullchem_emissions.pro)


FUTURE2BPCH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        FUTURE2BPCH

 PURPOSE:
        Converts future emission growth factor files from the obsolete
        binary format to binary punch format (so that they can be
        read by GAMAP).

 CATEGORY:
        File & I/O, BPCH Format

 CALLING SEQUENCE:
        FUTURE2BPCH, [ Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INFILENAME -> Name of the input file containing fossil 
             fuel scale factors.  If omitted, SCALEFOSS2BPCH
             will prompt the user for a filename via a dialog box.

        OUTFILENAME -> Name of the binary punch file containing 
             fossil fuel scale factors.  Default is to add a
             ".bpch" extension to INFILENAME.

 OUTPUTS:
         None

 SUBROUTINES:
         External Subroutines Required
         ==================================================
         CTM_TYPE (function)   CTM_GRID          (function) 
         NYMD2TAU (function)   CTM_MAKE_DATAINFO (function) 
         CTM_WRITEBPCH         EXTRACT_FILENAME  (function)

 REQUIREMENTS:
         None

 NOTES:
         None

 EXAMPLE:
         FUTURE2BPCH, INFILENAME='scalefoss.liq.2x25.1998', $
                      OUTFILENAME='scalefoss.liq.2x25.1998.bpch'

             ; Converts scalefoss files to BPCH format. 

 MODIFICATION HISTORY:
        bmy, 25 Jan 2006: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 02 Apr 2008: GAMAP VERSION 2.12
                          - Now read bpch as big-endian

(See /n/home09/ryantosca/IDL/gamap2/file_io/future2bpch.pro)


GAMAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GAMAP

 PURPOSE:
        Menu-driven user interface for creating plots with
        the GAMAP package subroutines. The actual data retrieval
        and plotting is done with ctm_plot.pro. This routine
        mainly collects all user requests and passes them on to
        CTM_PLOT.

 CATEGORY:
        GAMAP Utilities, GAMAP Plotting

 CALLING SEQUENCE:
        GAMAP, [ DiagN [, Keywords ] ]

 INPUTS:
        DIAGN -> A diagnostic number or category to restrict
             the record selection (default is: use all).

 KEYWORD PARAMETERS:
        General keywords:
        -----------------------------------------------------------------
        FILENAME -> CTM output file name. Default is to display a
             pickfile dialog and let the user select. You can have
             wildcards ('*', '?') in your filename which restricts
             the file selection.

        /NOFILE -> Don't query for filename but display all records that
             have already been loaded. This can save you a couple of
             mouse clicks when you want to create several plots with
             data from one file, and it also useful when you want
             to plot data from 'external' files that were converted
             with ctm_make_datainfo. If a filename is given or no
             data were loaded, the file selection dialog will appear
             anyhow.

        /RESETDEFAULTS -> If set, will reset all GAMAP values to their
             defaults.

        /HELP -> Displays a help page.

        RESULT -> Returns a structure with the data subset as plotted and
             the respective X and Y coordinates. Returns only one data
             record though.

        TOPTITLE -> Add a specific title centered on top of each page
             of output.

        Keywords to restrict the number of records displayed for selection:
        -----------------------------------------------------------------
        TRACER -> A tracer number to restrict record selection

        TAU0 -> Time value (at beginning of record)

        DATE -> 6 digit date (e.g. 940101) at the beginning of the
             output record (this gets translated into a TAU0
             value via the function nymd2tau). You can specify more
             than one date at a time using a vector (e.g. [940101, 940301]).
             For the GISS model(s), you also have to specify /GISS_Date in
             order to get correct tau values. The time is assumed to
             be 00 GMT. For other times use the TAU0 keyword as
             TAU0=nymd2tau(dates,times).

        /GISS_Date -> set this flag if you are using the DATE keyword
             with GISS model output.

        Keywords defining output options (these override defaults in
        gamap.defaults)
        -----------------------------------------------------------------
        /PS -> If set, will directly send output to the 'idl.ps' file.
             If not set, GAMAP will prompt the user whether to create
             the 'idl.ps' file.

        OUTFILENAME -> Name of file to send PostScript output to.

        /NOTIMESTAMP -> Do not include a user ID and time stamp
             on the postscript plot. Unnecessary if the TIMESTAMP value
             in gamap.defaults is set to 0.

        XSIZE, YSIZE, XOFFSET, YOFFSET -> GAMAP will pass these
             keywords to routine OPEN_DEVICE, for setting the size
             and margins of PostScript output.  

        /DO_BMP -> If set, GAMAP will save animation frames as BMP
             files.  If not set, GAMAP will prompt the user whether
             to save animation frames to BMP files.  DO_BMP overrides
             the default setting in "gamap.defaults".

        BMPFILENAME -> Name of BMP file to save animation frames to.
             If the token %N% is used in BMPFILENAME, then GAMAP
             will replace %N% with the actual frame number.  If
             BMPFILENAME is not set, or if DO_BMP is set to *QUERY in
             "gamap.defaults", GAMAP will prompt user to supply
             BMPFILENAME.

        /DO_GIF -> If set, GAMAP will save animation frames as GIF
             files.  If not set, GAMAP will prompt the user whether
             to save animation frames to GIF files.  DO_GIF overrides
             the default setting in "gamap.defaults".

        GIFFILENAME -> Name of GIF file to save animation frames to.
             If the token %N% is used in GIFFILENAME, then GAMAP
             will replace %N% with the actual frame number.  If
             GIFFILENAME is not set, or if DO_GIF is set to *QUERY in
             "gamap.defaults", GAMAP will prompt user to supply
             GIFFILENAME.

        /DO_JPEG -> If set, GAMAP will save animation frames as BMP
             files.  If not set, GAMAP will prompt the user whether
             to save animation frames to JPEG files.  DO_JPEG overrides
             the default setting in "gamap.defaults".

        JPEGFILENAME -> Name of JPEG file to save animation frames to.
             If the token %N% is used in JPEGFILENAME, then GAMAP
             will replace %N% with the actual frame number.  If
             JPEGFILENAME is not set, or if DO_JPEG is set to *QUERY in
             "gamap.defaults", GAMAP will prompt user to supply
             JPEGFILENAME.

        /DO_PNG -> If set, GAMAP will save animation frames as PNG
             files.  If not set, GAMAP will prompt the user whether
             to save animation frames to PNG files.  DO_PNG overrides
             the default setting in "gamap.defaults".

        PNGFILENAME -> Name of PNG file to save animation frames to.
             If the token %N% is used in PNGFILENAME, then GAMAP
             will replace %N% with the actual frame number.  If
             PNGFILENAME is not set, or if DO_PNG is set to *QUERY in
             "gamap.defaults", GAMAP will prompt user to supply
             PNGFILENAME.

        /DO_TIFF -> If set, GAMAP will save animation frames as TIFF
             files.  If not set, GAMAP will prompt the user whether
             to save animation frames to TIFF files.  DO_TIFF overrides
             the default setting in "gamap.defaults".

        TIFFFILENAME -> Name of TIFF file to save animation frames to.
             If the token %N% is used in TIFFFILENAME, then GAMAP
             will replace %N% with the actual frame number.  If
             TIFFFILENAME is not set, or if DO_PNG is set to *QUERY in
             "gamap.defaults", GAMAP will prompt user to supply
             TIFFFILENAME.

        /POLAR -> Set this keyword for polar pots. This forces latitude
             ranges to extend to one pole and longitude ranges to span
             the globe. Polar plots only work for global (at least 
             longitudinally) data sets.  Currently, polar plots are 
             supported only for contour plots.

        _EXTRA=e -> Picks up extra keywords for CTM_PLOT, etc...

 OUTPUTS:

 SUBROUTINES:
        Internal subroutines:
        ------------------------------------------------------
        GAMAP_CheckDataBlockConsistency (function)
        GAMAP_FindNearestCenters        (function)
        GAMAP_GetDataBlockRanges        (function)
        GAMAP_GetDefaultRanges
        GAMAP_AutoYRange                (function)
        GAMAP_PrintDimInfo
        GAMAP_QueryAnimationOptions
        GAMAP_QueryAverageOrTotal
        GAMAP_QueryPostScriptOptions
        GAMAP_SelectDataBlocks          (function)
        GAMAP_SelectPlotType
        GAMAP_QueryIsoPleth
        GAMAP_StoreGridInfo
        GAMAP_UserRangeEntry            (function)
        GAMAP_GetFrameFileName          (function)


        Also uses external subroutines:
        ------------------------------------------------------
        CHOICE        (function)    CLOSE_DEVICE
        CTM_PLOT                    OPEN_DEVICE
        STRREPL       (function)    STRWHERE    (function)
        DEFAULT_RANGE (function)    CHKSTRU     (function)
        REPLACE_TOKEN (function)    CTM_GRID    (function)
        MAKE_SELECTION(function)    TVREAD      (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) GAMAP can read ASCII punch files with GEOS or GISS, model II
            diagnostics, binary punch files (as defined in Jan 1999),
            and GEOS-CTM binary restart files. Binary punch files
            are processed much faster and allow "windowing" of output.

        (2) For pixel plots, GAMAP can only plot cylindrical maps
            with rectangular projections.  Arbitrary map projections
            should be possible with any type of contour plot. For 
            polar plots, use the /POLAR keyword. Other projections 
            have not been tested and may lead to unexpected results.

        (3) GAMAP forces map ranges to coincide with the grid box
            edges, so that the map and pixel plot will be aligned.
            Each "pixel" size corresponds to one full grid box.
            For grids with half-polar boxes, it is therefore recommended
            not to plot the polar latitudes, since those boxes will
            show up as full-size boxes and shift the rest of the plot
            accordingly.

        (4) When the user selects multiple data blocks, GAMAP will produce
            a multi-panel plot if !p.multi indicates more than one panel
            on the screen (use the MULTIPANEL procedure to turn it on).
            If you plot only one panel per screen, GAMAP will automatically
            start XInterAnimate to present your own movie to you. Be
            aware that XInterAnimate is limited by your system resources.
            With default window sizes, we can usually display at least
            30 frames.  ADDENDUM: 3-D isopleth maps will not be
            animated. (bmy, 1/22/01)

        (5) Animation frames can also be written to GIF or MPEG
            files.  Defaults can be set in "gamap.defaults", or
            specified via the command line. You can also save individual
            GAMAP plots as GIF files. If you want to animate them later
            (e.g. using ULead's GIF-Animator), make sure to specify the
            RANGE keyword to get identical color schemes (or use contours).

        (6) The GAMAP authors wish to point out that it is still relatively
            expensive to produce color plots on the printer. We encourage
            you to try out contour plots and make a test print on a black
            and white printer before you make a color print.

        (7) The 3-D isopleth maps do not quite work with MULTIPANEL, since
            they are produced with screen capture in the Z-Buffer.  Hence  
            Hence, the X window device has to be re-initialized each time, 
            which negates the MULTIPANEL utility.  PostScript plots of 3-D
            isopleth maps will print one plot per page.  We can live with
            this for the time being.  Isopleth maps can also be written
            to GIF files.

        (8) Now uses D. Fanning's TVREAD function to perform better
            device-independent screen capture. (cf. www.dfanning.com)

 EXAMPLES:
        (1)
        GAMAP
            ; operates fully interactively

        MULTIPANEL,nplots=6       ; turn on multi-panel environment
        GAMAP
            ; same as above, but produce multi-panel plots with
            ; 6 plots per page

        (2)
        GAMAP, 'IJ-AVG-$', tra=4
            ; Will create a CO (tracer=4) plot for the ND45 diagnostic.
            ; GAMAP will display dialog pickfile box and will scan the
            ; file for all records with ND45 and tracer 4. Those will be
            ; displayed and the user can then select a record to be plotted.

        (3)
        GAMAP, [ 'IJ-AVG-$', 'BIOBSRCE' ], tra=[2,4], $
               date=[19940601, 19940801], $
            FileName='~bmy/terra/CTM4/ctm.pch',/ps
            ; In this example the file is fully specified, hence no file
            ; selection dialog will be displayed. GAMAP scans the file
            ; for all records of 'IJ-AVG-$' and 'BIOBSRCE' and tracers
            ; 2 (OX) and 4 (NOX) and it seelcts only those records that
            ; begin on the first of JUNE or AUGUST 1994. Because the ps
            ; flag is set, the output will be directed to the postscript
            ; file 'idl.ps' without first being displayed on the screen.


 MODIFICATION HISTORY:
        mgs, 12 Nov 1998: VERSION 1.00
        bmy, 16 Nov 1998: - added defaults for LAT, LEV, LON, PTYPE
                          - now prompts for PS
                          - now prompts user for /PS output
        bmy, 17 Nov 1998: - now call DEFAULT_RANGE to ensure that
                            that LAT, LON, LEVEL have two elements,
                            even if there is only one unique value.
                          - now uses N_UNIQ.PRO to test for the number
                            of unique elements in LON, LAT, and LEVEL.
        mgs, 17 Nov 1998: - finishing touches for first release.
                          - added NOFILE keyword
                          - added plot type b/w contours
        mgs, 18 Nov 1998: - added timestamp as default when closing
                            postscript files
        bmy, 08 Jan 1999: - Will also prompt for totaling (if
                            averaging is not selected)
        bmy, 13 Jan 1999: - now prompt user for OUTFILENAME
        bmy, 15 Jan 1999: VERSION 1.02
                          - add support for 3-D data slices
                          - clean up user interface so that the user
                            menu of plotting options is only invoked
                            when plotting a 2-D map.
        bmy, 19 Jan 1999: - added binary flag masking
                          - added defaults for averaging and selection
                          - improved echoback of information to user
        bmy, 20 Jan 1999: - prompts user again if data block selection
                            or averaging selection is out of range
                          - fixed bug: now default data block
                            selection is saved.
                          - Reset PS to 0 and OUTFILENAME to '' if we
                            are plotting a 0-D or 3-D data block
                          - updated comments
        mgs, 21 Jan 1999: - dimensional information now in subroutine
                          - improved binary masking
                          - added several Quit options
                          - Postscript options now controlled from
                            gamap.defaults
                          - removed NoTimeStamp keyword (now set in
                            gamap.defaults)
        bmy, 12 Feb 1999: VERSION 1.03
                          - now works with data blocks that are
                            sub-regions of the globe
                          - added functions GAMAP_GetDataBlockRanges
                            GAMAP_SelectDataBlock, and
                            GAMAP_QueryAverageOrTotal
                          - updated comments
        bmy, 17 Feb 1999: VERSION 1.20
                          - Replace DATAINFO.OFFSET by DATAINFO.FIRST,
                            which contains the I, J, L indices of
                            the first grid box
                          - Animation facility added
                          - added functions GAMAP_GetModelInfo,
                            GAMAP_CheckDataBlockConsistency,
                            GAMAP_SelectPlotType, and
                            GAMAP_QueryPostScriptOptions.
                          - Also renamed function GAMAP_SelectDataBlock to
                            GAMAP_SelectDataBlocks, since one can now
                            select multiple data blocks
        bmy, 18 Feb 1999: - added /RESETDEFAULTS keyword
                          - removed /ANIMATE keyword
        bmy, 19 Feb 1999: - added NOAUTOYRANGE keyword
                          - added function GAMAP_AutoYRange
                          - added GIFFILENAME keyword
                          - added GIF_SAV to common block SAVEVALUES
                          - call REPLACE_TOKEN to replace token text
                            in DEFAULTGIFFILENAME
        bmy, 22 Feb 1999: - added more animation options
                          - added DO_GIF, DO_MPEG, DO_ANIMATE, and
                            MPEGFILENAME keywords
                          - added GAMAP_QueryAnimationOptions routine
        bmy, 23 Feb 1999: - small bug fixes
        bmy, 04 Mar 1999: - added internal routines GAMAP_FindNearestEdges
                            and GAMAP_GetDefaultRanges
                          - now force lat/lon ranges to coincide with
                            grid box edges
                          - warn user if lat range contains half-polar
                            boxes, since TVIMAGE will treat them as
                            whole boxes and the map overlay will be
                            inaccurate!
        bmy, 05 Mar 1999: - Clean up FILEINFO/DATAINFO matching process
                          - renamed/reorganized internal functions\
        bmy, 20 Mar 1999: - bug fix for default ranges (may need more
                            fixing later on)
        mgs, 22 Mar 1999: - added ALREADY_PS flag for multi-panel use
                          - animation now only if !p.multi does not
                            have more than 1 panel to display
        mgs, 23 Mar 1999: - improved comments and examples
                          - removed unnecessary function MatchFileInfo...
                            (easier with make_selection)
                          - changed all "string booleans" to booleans
                          - Do_Animation now an entirely local variable
        mgs, 25 Mar 1999: - few minor bug fixes
                          - improved handling of default ranges
                          - detect out of range in record selection
                          - now allows for 2D field plots
        bmy, 17 May 1999: - now resolve DEFAULT_RANGE explicitly and
                            call DEFRANGE_STR2NUM separately
                          - few minor fixes in GAMAP_UserRangeEntry for
                            data blocks that straddle the date line.
        mgs, 19 May 1999: - some more cleaning
                          - implemented SAVE option after data record
                            selection
                          - user selection for longitudes greatly improved
                          - some adjustments in FindNearestEdges, notably
                            for range 0..360. Unfortunately, the 0 meridian
                            gridline will be omitted in such plots. If we
                            wanted to include it we would need to carry
                            an extra GLOBAL flag because lower and upper
                            edges (grid box indices) are identical.
        mgs, 20 May 1999: - added option to save record seelction to file.
        mgs, 24 May 1999: - yet more work had to be done to make lon/lat
                            selection as user would expect it to work.
                          - renamed FindNearestEdges to ..Centers
        mgs, 25 May 1999: - still more fiddling. Yuck!

                          RELEASE OF GAMAP VERSION 1.40

        bmy, 26 May 1999: - Added polar plot capabilities
                          - fixed reset of plot ranges when latitude is +-90
        mgs, 27 May 1999: - already_ps flag now also prevents user query.
                          - default lat range for global fields now back
                            to -88..88 only for "reset" conditions. Otherwise
                            -90..90 is recognized and remembered.
        mgs, 28 May 1999: - added RESULT keyword.
                          - added TOPTITLE keyword.
        bmy, 28 May 1999: - restrict plot type menu for polar plots
  bmy & mgs, 02 Jun 1999: - add /NOERASE to MULTIPANEL call when
                            testing for last plot on page
                          - updated some comments
        mgs, 30 Jun 1999: - make sure to return only one lat/lon box
                            if user enters single value (even on edges).
        bmy, 07 Jul 1999: - small bug fixes
        bmy, 15 Sep 1999: GAMAP VERSION 1.43
                          - changes for 23L GISS-II-PRIME model
                          - minor bug fixes
        bmy, 25 Oct 1999: GAMAP VERSION 1.44
                          - added /MULTIPLE keyword -- option to
                            write to a GIF file w/ multiple frames
        bmy, 23 Nov 1999: - /SMALLCHEM now works correctly!
        bmy, 26 Apr 2000: GAMAP VERSION 1.45
                          - now make sure tracer numbers are mod 100L
                            when saving data blocks to disk
        bmy, 19 Jun 2000: - now create NS string array by concatenating 
                            smaller arrays of < 1024 elements
        bmy, 20 Jun 2000: - bug fix -- set NS[0] blank for string output
        bmy, 03 Oct 2000: GAMAP VERSION 1.46
        bmy, 22 Jan 2001: GAMAP VERSION 1.47
                          - removed obsolete code
                          - now produce a 3-D isopleth map instead of
                            calling the volume slicer routine
                          - added ISOPLETH keyword
                          - added internal subroutine GAMAP_QueryIsopleth
                          - allow PostScript output for 3-D maps, and
                            suppress animation for 3-D maps.
        bmy, 13 Mar 2001: - remove a couple more instances of the 
                            obsolete STR_SEP routine.  Replaced with
                            STRSPLIT( /EXTRACT ).  
        bmy, 28 Jun 2001: GAMAP VERSION 1.48
                          - bug fix in GAMAP_StoreDataInfo: for
                            GENERIC grids with NLAYERS=0, be sure to
                            call CTM_GRID with the /NO_VERTICAL flag.
        bmy, 29 Aug 2001: - added XSIZE, YSIZE, XOFFSET, YOFFSET 
                            keywords to pass to OPEN_DEVICE 
  mje & bmy, 17 Dec 2001: GAMAP VERSION 1.49
                          - add _EXTRA=e in call to CTM_WRITEBPCH, 
                            so that we can pass the /APPEND keyword 
        bmy, 17 Jan 2002: GAMAP VERSION 1.50
                          - now call STRBREAK wrapper routine from
                            the TOOLS subdirectory for backwards
                            compatiblity for string-splitting
                          - use FORWARD_FUNCTION to declare STRBREAK
        bmy, 24 Jan 2002: - deleted obsolete code
        bmy, 06 Dec 2002: GAMAP VERSION 1.52
                          - removed /DO_MPEG and MPEGFILENAME keywords
                          - now use D. Fanning's TVREAD for better
                            device-independent screen capture
                          - removed /MULTIPLE keyword for GIF output
                          - added /DO_PNG, /DO_BMP, /DO_JPEG,
                            /DO_TIFF keywords
                          - added internal function GAMAP_GetFrameFileName
        bmy, 13 Nov 2003: GAMAP VERSION 2.01
                          - comment out XINTERANIMATE options
        bmy, 27 Aug 2004: GAMAP VERSION 2.03
                          - now call CTM_PLOT_TIMESERIES to plot data
                            from bpch files containing GEOS-CHEM station
                            timeseries output (e.g. ND48 diagnostic)
        bmy, 27 Oct 2004: - now pass /QUIET keyword to GAMAP_AUTOYRANGE,
                            CTM_PLOT_TIMESERIES, and CTM_PLOT
                          - hardwire QUIET=1 in to suppress extra printing
        bmy, 28 Jun 2005: GAMAP VERSION 2.04
                          - Strip white spaces in FILENAME, if present
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
  bmy & phs, 20 Nov 2007: GAMAP VERSION 2.11
                          - If any 4D data blocks are encountered,
                            then only use the first 3 dimensions
        phs, 22 Sep 2009: GAMAP VERSION 2.13
                          - Added /NoDialog to all call to TVRead
        bmy, 26 Feb 2010: GAMAP VERSION 2.14
                          - Now allow polar maps to use pixel plots
        bmy, 11 Feb 2011: GAMAP VERSION 2.15
                          - Updated welcome screen

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/gamap.pro)


GAMAP2_HTML

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GAMAP2_HTML

 PURPOSE:
        Wrapper routine for IDL2HTML.  Is used to call IDL2HTML 
        repeatedly in order to create HTML documentation for each
        of the source code files in the GAMAP installation.  The
        user may sort routines by alphabetical order or by category.

 CATEGORY:
        Documentation

 CALLING SEQUENCE:
        GAMAP2_HTML [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        OUTDIR -> Specifies the directory in which HTML documenation
             will be created.  Passes this to IDL2HTML.

        /ALL_ROUTINES -> Select this option to create an HTML file
             with documentation information about all routines
             in the GAMAP directory.  The output file name will be
             "gamap2_html.pro".

        /BY_ALPHABET -> Select this option to create HTML documentation
             files for GAMAP routines by alphabetical order.  A file
             will be created for each letter of the alphabet.

        /BY_CATEGORY -> Select this option to create HTML documentation
             files for GAMAP routines according to category (as
             specified by the "CATEGORY" tag of the IDL doc header).
             A files will be created for each individual category.
             NOTE: GAMAP routines may be cross-linked across more
             than one category.  

 OUTPUTS:

 SUBROUTINES:
        External Routines Required:
        ============================
        IDL2HTML
        PROGRAM_DIR (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) See also the documentation to IDL2HTML and the IDL manual
            for routine MK_HTML_HELP.

        (2) One of /ALL_ROUTINES, /BY_ALPHABET, or /BY_CATEGORY must
            be selected.

 EXAMPLES:
        (1)
        GAMAP2_HTML, /ALL_ROUTINES, OUTDIR='manual/html'

             ; Creates HTML documentation from the std headers to
             ; each of the IDL source code programs in the GAMAP 
             ; installation.  Writes output to the manual/html
             ; directory.  The output file name is "gamap2.html",
             ; which directory.   

        (2) 
        GAMAP2_HTML, /BY_ALPHABET, OUTDIR="manual/html"
            
             ; Creates HTML documentation from the std headers to
             ; each of the IDL source code programs in the GAMAP 
             ; installation.  Will search through the IDL doc 
             ; headers and create a new HTML file for each
             ; letter of the alphabet.

        (3)
        GAMAP2_HTML, /BY_CATEGORY, OUTDIR='manual/html'

             ; Creates HTML documentation from the std headers to
             ; each of the IDL source code programs in the GAMAP 
             ; installation.  Will search through the IDL doc 
             ; headers and create a new HTML file for each
             ; category.


 MODIFICATION HISTORY:
  bmy & phs, 23 Jul 2007: GAMAP VERSION 2.10
        bmy, 20 Nov 2007: GAMAP VERSION 2.11
                          - Added new category for timeseries routines
        bmy, 06 Aug 2010: GAMAP VERSION 2.14
                          - Now check to see if OUTDIR exists

(See /n/home09/ryantosca/IDL/gamap2/doc/gamap2_html.pro)


GAMAP2_MANUAL_CREATE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GAMAP2_MANUAL_CREATE

 PURPOSE:
        This routine creates the HTML documentation pages for each of
        the GAMAP routines.  This is a convenience wrapper routine
        which calls both GAMAP2_HTML and FIX_MANUAL_HTML.

 CATEGORY:
        Documentation

 CALLING SEQUENCE:
        GAMAP2_MANUAL_CREATE

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Routines Required:
        ============================
        GAMAP2_HTML
        FIX_MANUAL_HTML

 REQUIREMENTS:
        None

 NOTES:
        Will save output to the ../manual/html/* directories.

 EXAMPLES:
        GAMAP2_MANUAL_CREATE

             ; Creates HTML documentation from the std headers to
             ; each of the IDL source code programs in the GAMAP 
             ; installation.  Writes output to the manual/html
             ; directory. 

 MODIFICATION HISTORY:
        bmy, 01 Jul 2008: GAMAP VERSION 2.12

(See /n/home09/ryantosca/IDL/gamap2/doc/gamap2_manual_create.pro)


GAMAP2_REVISIONS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GAMAP2_REVISIONS

 PURPOSE:
        Wrapper routine for REVISIONS, used to create a "REVISIONS"
        file for each code directory in the GAMAP installation.

 CATEGORY:
        Documentation

 CALLING SEQUENCE:
        GAMAP2_REVISIONS

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        PROGRAM_DIR (function)
        REVISIONS

 REQUIREMENTS:
        None

 NOTES:
        The REVISIONS routine requires the tag "MODIFICATION HISTORY"
        to be present.  Files without this tag (e.g. data files or
        input files) will not be included in the REVISIONS output.

 EXAMPLE:
        GAMAP2_REVISIONS

             ; Search through all of the directories in the GAMAP
             ; installation and create a REVISIONS file containing
             ; the modification histories of each *.pro file.

 MODIFICATION HISTORY:
        bmy, 17 Jul 2007: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/doc/gamap2_revisions.pro)


GAMAP_CMN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GAMAP_CMN

 PURPOSE:
        Contains global common block for Global Atmospheric Model 
        output Analysis Package include file (include with @gamap_cmn)

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        @gamap_cmn

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        Referenced by gamap_init.pro and gamap.pro

 NOTES:
        None

 MODIFICATION HISTORY:
        mgs, 14 Aug 1998  INITIAL VERSION
        mgs, 21 Jan 1999: - added postscript variables
        bmy, 22 Feb 1999: - added options for animation (GIF, MPEG filenames)
        bmy, 10 Dec 2002: GAMAP VERSION 1.52
                          - removed DO_MPEG and DEFAULTMPEGFILENAME
                          - added DO_BMP and DEFAULTBMPFILENAME
                          - added DO_JPEG and DEFAULTJPEGFILENAME
                          - added DO_PNG and DEFAULTPNGFILENAME
                          - added DO_TIFF and DEFAULTTIFFFILENAME 
        bmy, 13 Nov 2003: GAMAP VERSION 2.01
                          - re-added DO_MPEG and DEFAULTMPEGFILENAME
                          - removed CREATEANIMATION, this was only
                            ever used for XINTERANIMATE (obsolete)
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/gamap_cmn.pro)


GAMAP_COLORS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GAMAP_COLORS

 PURPOSE:
        Concatenates several different color tables (including
        IDL standard color tables and the ColorBrewer color
        tables) into single file for for use with GAMAP.

 CATEGORY:
        Color

 CALLING SEQUENCE:
        GAMAP_COLORS

 INPUTS:
        OUTFILENAME -> Name of the color table file to modify.
             Default is "gamap_colors.tbl".  GAMAP_COLORS will
             locate this file with FILE_WHICH.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        MYCT

 REQUIREMENTS:
        None

 NOTES:
        IDL's MODIFYCT function may require that the file to be
        modified already be on disk.

 EXAMPLE:
        GAMAP_COLORS, 'new_gamap_colors.tbl'

             ; Will modify the colortable file 
             ; 'new_gamap_colors.tbl'.

 MODIFICATION HISTORY:
        bmy, 18 Apr 2008: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/color/gamap_colors.pro)


GAMAP_INIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GAMAP_INIT

 PURPOSE:
        Initialize global common block for Global Atmospheric Model 
        (output) Analysis Package (GAMAP).  This routine is called
        automatically when gamap_cmn.pro is included in a file 
        ( @gamap_cmn.pro ), but it executes only once.  User 
        preferences are read from the file gamap.defaults in the 
        current directory or the directory where gamap_init.pro 
        resides.

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        GAMAP_INIT

 INPUTS:
        none

 KEYWORD PARAMETERS:
        DEBUG -> set a (new) debug level (0 or 1). 

 OUTPUTS:
        none

 SUBROUTINES:
        Uses FILE_EXIST, EXTRACT_PATH, and OPEN_FILE

 REQUIREMENTS:
        None

 NOTES:
        If you change the definition of the common block
        in gamap_cmn.pro, make sure to accomodate these changes
        in GAMAP_INIT.

 EXAMPLE:
        GAMAP_INIT

 MODIFICATION HISTORY:
        mgs, 14 Aug 1998: VERSION 1.00
        mgs, 21 Sep 1998: - changed gamap.cmn to gamap_cmn.pro
        mgs, 05 Oct 1998: - type assignment fix to DEBUG when read
        mgs, 08 Oct 1998: - now runs through after CTM_CLEANUP and does
                            not delete global pointers if valid.
                          - added DEBUG keyword
        mgs, 21 Jan 1999: - added postscript options
        bmy, 19 Feb 1999: - added GIF_FILENAME
        bmy, 22 Feb 1999: VERSION 1.01
                          - added more animation options
                          - changed POSTSCRIPT to DO_POSTSCRIPT
                          - default path now amalthea
        mgs, 23 Mar 1999: - slight change in defaults
        bmy, 19 Jan 2000: GAMAP VERSION 1.44
                          - replaced the deprecated STR_SEP function
                            with STRSPLIT for IDL 5.3+
                          - Now STRTRIM each token so that the case
                            statement will find matches
                          - cosmetic changes, updated comments
        bmy, 13 Mar 2001: GAMAP VERSION 1.47
                          - now supports MacOS operating system
        bmy, 07 Jun 2001: - removed obsolete code prior to 3/13/01
        bmy, 17 Jan 2002: GAMAP VERSION 1.50
                          - now call STRBREAK wrapper routine from
                            the TOOLS subdirectory for backwards
                            compatiblity for string-splitting;
                          - use FORWARD_FUNCTION to declare STRBREAK
        bmy, 10 Dec 2002: GAMAP VERSION 1.52
                          - added options for BMP, JPEG, PNG, TIFF output
                          - added internal function TRIMTOK 
        bmy, 13 Nov 2003: GAMAP VERSION 2.01
                          - re-added option for MPEG animation
                          - removed CREATEANIMATION, this was only
                            ever used for XINTERANIMATE (obsolete)
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now use the IDL FILE_WHICH routine to
                            locate the gamap.defaults file

(See /n/home09/ryantosca/IDL/gamap2/internals/gamap_init.pro)


GC_COMBINE_ND48

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GC_COMBINE_ND48

 PURPOSE:
        Combine timeseries data from the Geos-CHEM ND48
        diagnostics contained in one or more binary punch files.

        The goal is to combine, for one station, all the data blocks
        (there is one per time step) into one single 4-D data block
        (we want the time to be the 4th dimension). This is basically
        to take advantage of support for 4D dataset in GAMAP v2-10.

        GEOS-Chem ND48 (as in v7-04-12) outputs one file for all
        stations and all time steps. GC_COMBINE_ND48 will write one
        file but each timeseries will be in one data block instead of
        as many as the number of timesteps. This will make reading
        the timeseries with CTM_GET_DATA a lot faster.

        Two basic signal processing before saving the data can be
        applied: moving average and/or daily maximum.

        LIMITATION: daily maximum will not make sense if series do
        not cover full days.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation, Time Series

 CALLING SEQUENCE:
        GC_COMBINE_ND48 [, Keywords ]

 OPTIONAL INPUTS:

        By defaults all stations are processed. And one output file
        is created that contains all the stations timeseries.

 KEYWORD PARAMETERS:

        ;============ For I/O files/directory =====================

        INFILE -> one or more station file(s) from ND48
              diagnostic. If more than one file is processed, it is
              assumed that, once sorted in alphabetical order, they
              are in chronological order (this is automatically the
              case, if you insert YYYYMMDD into ND48 filenames in
              input.geos).

        INDIR -> Directory where to look for "stations" files. Can be
             either input or output keyword:

             Input: when defined, ALL files satisfying the MASK
                    keyword in the directory will be selected.

             Ouput: set to a variable name that will contains the DIR
                    of the selected files.

             It is ignored (both input and output roles) if INFILE is
             provided.

             If neither INFILE nor INDIR is set, then a dialog window
             that allows multiple files selection (keep CTRL or SHIFT
             key down) will pop-up.


        MASK -> Pattern Mask to find files in INDIR. Default is
             "stations*".

        OUTFILENAME -> Name of the file that will contain the
             new timeseries. Default is 'combined'+INFILE[0], in the
             same directory as stations file. If the full path is not
             included, the file is created in the working directory.

            The routine prevents from overwriting any input file.

        ;================= Data Selection ======================

        STATIONNB -> Station(s) number. Can be one or more elements
              (up to the number of stations in ND48). Use to select a
              subset of the stations instead of all of them.

        TIME -> vector for selecting time span. The data covering
              [min(TIME),max(TIME)] are selected. If only one
              element, then the closest-in-time data is selected.

              If min and/or max of TIME is outside the range of
              available time steps, the first or last available time
              step is used.

              Note 1: this is also an output keyword. Then, if passed
              by reference, TIME becomes the time vector in
              output. See example (6).

              Note 2: if using DMAX or DAVG, then TIME should be long 
              integer (YYYYMMDD), if not it should be Tau format.

        ;================= Signal Processing ======================

        MAVG -> to apply a running average filter to the series. MAVG
              value will define the boxcar size and must be GE
              3. Even numbers are increased by +1. The IDL SMOOTH
              routine is called and accept _extra keywords (NAN,
              EDGE_TRUNCATE, and MISSING).

        DMAX -> to select the daily maxima of the time series. If
              both MAVG and Dmax are set, the moving average is
              performed first and you get the daily max of the moving
              average. (Local time is not accounted for: days start
              and end at 0 UT everywhere).

        DAVG -> to select the daily average of the time series. If
              both MAVG and DAVG are set, the moving average is
              performed first and you get the daily average of the
              moving average. (Local time is not accounted for: days
              start and end at 0 UT everywhere).


        ;================= Output keywords ========================

        All the following keywords will apply to only ONE
        station. The last one is used if none or more than one is
        requested.

        DATA -> set to a variable name that will hold the selected
             timeseries data on exit. This is a 4D array
             (1,1,lev,time) even though only one station is
             selected.

        LON -> set to a variable name that will hold the
             longitude of the data set on exit.

        LAT -> set to a variable name that will hold the
             latitude of the data set on exit.

        LEV -> set to a variable name that will hold the vector
             of levels for the data set on exit.

        TIME -> set to a variable name that will hold the time
             vector for the station on exit. Given as Tau values,
             unless DMAX or DAVG is set, then as YYYYMMDD.

        LOCALTIME -> if set, the TIME vector is in local time
             instead of UT. Has no effect if /DMAX or /DAVG.


        ;================= Others ========================

        NOSAVE -> set to not save output into a BPCH file. Useful if
             you just want to check results with output keywords.

        VERBOSE -> Set to print informational message about the time
             series. particularly useful to double check
             area/location selected with subset keywords.

        _EXTRA=e -> Picks up extra keywords for SMOOTH and
                 DIALOG_PICKFILE.


 OUTPUTS:
        See output keywords above.

 SUBROUTINES:

 REQUIREMENTS:
        References many routines from GAMAP package. Requires GAMAP
        v2.10 for handling 4D dataset.

 NOTES:
       If memory issues show up, try to save one timeseries (i.e.,
       one station at a time).

 EXAMPLES:

        ;; (1) Read multiple timeseries files selected w/ a pop-up
        window (use SHIFT key for muliple selections). Save with the
        default filename in the default directory:

        GC_COMBINE_ND48


        ;; (2) Like example (1), but saves only the daily max of the
        ;;     9-hours average timeseries:

        GC_COMBINE_ND48, /dmax, mavg=8



        ;; (3) read ALL stations files from directory '~/path/'
        ;; without a pop-up window (no interactivity, good for batch
        ;; processing). Default MASk and outfile name are used.

        GC_COMBINE_ND48, indir='~/path/'


        ;; (4) Like example (3) but select only the first available
        ;; station, and save the result in a specified file:

        GC_COMBINE_ND48, Station=1, indir='~/path/', outfile='~/path/series1.bpch'


        ;; (5) read files from directory '~/path/', and select 3rd station.
        ;; Do not save combined timeseries. Get outputs in variables
        ;; data, lon, lat and time.

        GC_COMBINE_ND48, indir='~/path/', station=3, data=data, lon=lon, lat=lat, time=time

        Help, reform(data)
        PLOT, time, data[0,0,0,*], title='Lon= strtrim(lon,2)+'- Lat='+strtrim(lat,2)


        ;; (6) Like (5), but limit the time to 23rd-28th of July
        ;;     2001. Not the use of two commands to get the output
        ;;     time vector.

        time = [nymd2tau(20010723L,20010728l)]
        GC_COMBINE_ND48, indir='~/path/', station=3, data=data, lon=lon, lat=lat, time=time 
        HELP, time


 MODIFICATION HISTORY:
        phs, 31 Jul 2007: GAMAP VERSION 2.10
                          - Initial version
        phs, 11 Oct 2007: - few bugs fix
                          - added output keywords
        phs, 15 Oct 2007: - added LOCALTIME keyword
        phs, 18 Oct 2007: - do not save if output file is one of the
                            input file.
        phs, 26 Oct 2007: - TIME can be use to select the time span
                            of the series.
                            Added DAVG keyword.
        phs, 30 Oct 2007: - couple of minor fixes.
        phs, 11 Aug 2009: - major fix: bug fix when same tracer 
                            in several stations 
        bmy, 12 Mar 2009: GAMAP VERSION 2.14
                          - Typo at line 429 fixed

(See /n/home09/ryantosca/IDL/gamap2/timeseries/gc_combine_nd48.pro)


GC_COMBINE_ND49

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GC_COMBINE_ND49

 PURPOSE:
        Combine timeseries data from several bpch files into 4D
        data. Typically used with Geos-CHEM ND49 timeseries output
        and met fields in bpch files (a3, a6, i6). 
        
        For met fields, see example (9) and (10).

        Each ND49 and Met Fields file has data for one day. But,
        files with time series that do no cover a day per file, can
        also be processed. See example (11), but keep in mind that
        the daily max or average options are then **** MEANINGLESS
        ****, and should not be used.


        WHAT IS DONE:
        
        (1) We combine all the data blocks for one tracer (there is
        one per time step) into one single 4-D data block (with time
        in 4th dimension). This takes advantage of support for 4D
        dataset introduced in GAMAP v2-10.

        (2) The combined series can be saved into a binary punch
        file. You end up with one file per tracer that covers many
        days of output, instead of one file per day for all
        tracers. The space saving can be more than 60%.

        (3) A subarea (even a single location) can be extracted. But
        for multiple but not contiguous locations, call the routine
        as many time as needed.

        (4) Shorter timeseries can be selected/saved, by specifying
        Tau range, or day (as YYYYMMDD long integer) range if daily
        max or average is selected.

        (5) Two basic signal processing before saving the data can be
        performed: moving average and/or daily
        maximum/minimum/average.

        ## LIMITATION ## : full days considered for ND49, ie,
        GEOS-Chem runs should start and end at midnight (YYYYMMDD
        000000 in input.geos)

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation, Time Series

 CALLING SEQUENCE:
        GC_COMBINE_ND49 [, TRACER ][, CATEGORY ][, Keywords ]

 INPUTS:
        TRACER -> The tracer number. Default is 1.

        CATEGORY -> The category name (default is "IJ-AVG-$")
             for which to read data.

 KEYWORD PARAMETERS:

        ;============ For I/O files/directory =====================

        FILELIST -> list of files to process. Usually used as output
             keyword to get the list of files selected with INDIR and
             MASK or through a dialog window.
             Can be used as input. Then INDIR and MASK are ignored.

        INDIR -> Directory where to look for MASK files.  If
             provided, ALL files satisfying the MASK keyword in the
             directory will be selected. If not provided, a dialog
             window that allows multiple files selection (keep SHIFT
             key down) will pop-up. See EXAMPLES below for tips.

             If set to an undefined variable name, it will hold the
             directory of the selected files (output keyword).

             NOTE: If more than one file is processed, it is assumed
             that, once sorted in alphabetical order, they are in
             chronological order (this is the case with GEOS-Chem
             default naming of ND49 output files: they contain
             YYYYMMDD).

        MASK -> Pattern Mask to find files in INDIR. Default is
             "ts*.bpch".

        OUTDIR -> Output directory where to save the file with the
             new timeseries data set will be. Default is INDIR. If
             the user has not write permission in INDIR, writintg is
             cancelled.

        OUTFILENAME -> Name of the file that will contain the
             timeseries. Default is 'combts_%TRACERNAME%.bpch', for
             COMB ined  T ime  S eries.

            The routine prevents from overwriting any input file.

        ;============ To extract subset of data ===================

        LON -> A one or two-elements vector specifying the longitude
            of one location or one area. If LON is outside the ND49
            area, the program print a warning, and uses border
            value.

        LAT -> same as LON, but for Latitudes

        LEV -> same as LON, but for Levels. Refers to the model grid.


        ; - - you can also select indices into the requested 3D cube:

        LLEV -> A one or two-element vector specifying the min and
             max of available levels to be included in the file.
             Default is ALL available levels.
             Default FORTRAN indexing is used: LLEV #1 is the first
             level ***requested*** in ND49. See LEV above otherwise.

        ILON, JLAT -> same as LLEV but for Longitude and Latitude
             indices. Starting at 1 at the first ***requested***
             grid box in ND49.


        TIME -> vector for selecting time span. The data covering
              [min(TIME),max(TIME)] are selected. If only one
              element, then the closest-in-time data are selected.
              TIME must be given as Tau (double) or YYYYMMDD (long)
              if /DMAX or /DAVG.
              If both DMAX (or DAVG) and LOCALTIME are set, TIME is
              ignored. 

          ** TIP ** if you select a short time span, it may be
                    useful to limit the number of files to process
                    by redefining MASK or using FILELIST. That will
                    speed up the process.


        ;================= Signal Processing ======================

        MAVG -> to apply a running average filter to the series. MAVG
              value will define the boxcar size and must be GE
              3. Even numbers are increased by +1. The IDL SMOOTH
              routine is called and accept _extra keywords (NaN,
              Edge_truncate, missing).

        DMAX -> to select the daily maxima of the time series. If
              both MAVG and Dmax are set, the moving average is
              performed first and you get the daily max of the moving
              average.

        DAVG -> to select the daily average of the time series. If
              both MAVG and DAVG are set, the moving average is
              performed first and you get the daily average of the
              moving average.

        LOCALTIME -> to get DAVG or DMAX computed over local days
              instead of UT days. See details below.


        ;================= Output keywords ========================

        DATA -> set to a variable name that will hold the selected
             timeseries data on exit. This is a 4D array
             (nLon, nLat, nLevel, ntime) even if only one location is
             selected.

        OUTLON -> set to a variable name that will hold the vector
             of longitudes of the data set on exit.

        OUTLAT -> set to a variable name that will hold the vector
             of latitudes of the data set on exit.

        OUTLEV -> set to a variable name that will hold the vector
             of Levels of the data set on exit.

        OUTALT -> set to a variable name that will hold the vector
             of altitudes for the data set on exit.

        OUTTIME -> set to a variable name that will hold the time
             vector corresponding to the data set on exit. Format
             is Tau, or YYYYMMDD if /DMAX.

        LOCALTIME -> if set, OUTTIME becomes a Nb_OutLon X Nb_TimeStep
             array, with each vector OUTTIME[i,*] holding the time
             vector in local time instead of UT. That vector will
             apply to all j and k for DATA[i,j,k,*].


           Specific case of...  both DMAX (or DAVG) and LOCALTIME
             being set. The daily max (average) is obtained after
             shifting the timeseries, so they start at 00 LT
             everywhere (or the first available time step just before
             00 LT). The first max (average) value is for the first
             complete local day of the series. The OUTTIME array is
             then a [numbers of complete days, 2] array that gives
             the local YYYYMMDD for both positive and negative
             longitudes.

             See also note about TAU0/TAU1 below.

             Note that the time step of the series must be small
             enough for the DMAX/DAVG w/r/t Local Time to be
             reliable.


        ;================= Others ========================

        NOSAVE -> set to not save output into a BPCH file. Useful if
             you just want to check results with output keywords.

        VERBOSE -> Set to print informational message about the time
             series. Particularly useful to double check the
             area/location selected with subset keywords.

        _EXTRA=e -> Picks up extra keywords for SMOOTH and
                 DIALOG_PICKFILE.


 OUTPUTS:
        See output keywords above.

 SUBROUTINES:

 REQUIREMENTS:
        References many routines from GAMAP package. Requires GAMAP
        v2.10 for saving 4D dataset into binary punch file.

 NOTES:
        ######## ND49 and Met Fields only. For ND48, see  ########
        ######## GC_COMBINE_ND48 (not as well maintained) ########

        Written with batch processing in mind. It is recommended to
        save all ND49 outputs into one dedicated directory, and to
        use keywords (INDIR, OUTDIR, OUTFILE..) and save the new
        combined timeseries in a new directory.

        About TAU0 and TAU1 : in the DataInfo structure, they are set
        to the beginning and end of the timeseries. For daily data,
        we compute them by setting HH:MM:SS to 00:00:00. If LocalTime
        is set, UT is still used for TAU0 and TAU1, so we can use
        only one value. If both LocalTime and DMAX are set, tau0 and
        tau1 give the first and last (local) days for longitudes less
        than 0 (west). For East longitudes, you need to add one day
        to these to get the correct date.
 

 EXAMPLES:
        ;; In the following examples, it is assumed that tracer 1
        ;; has been saved with ND49


        ;; (1) Read multiple timeseries files selected w/ a pop-up
        window (use SHIFT key for muliple selections). Saved series
        at ALL available locations into default directory and filename:

            GC_COMBINE_ND49

        exactly the same as:

            GC_COMBINE_ND49, 1, 'IJ-AVG-$'


        ;; (2) Like example (1), but saves only the daily max of the
        ;; 9-hours average timeseries:

            GC_COMBINE_ND49, 1, 'IJ-AVG-$', /dmax, mavg=8


        ;; (3) Like example (1), but do not save the timeseries. Get
        ;; the timeseries in the variable TS in output:

            GC_COMBINE_ND49, 1, 'IJ-AVG-$', /nosave, data=TS


        ;; (4) read **ALL** MASK-files from directory '~/path/'
        ;; without a pop-up window (no interactivity, good for batch
        ;; processing):

            GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='series1.dat'


        ;; (5) Like example (4), but with selection of ONE station:

            GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='station1.bpch',$
                             lon=-65., lat=45., lev=1


        ;; (6) Like example (5), but with shorter time series (from
        ;; 2001/7/20 20:00 to 2001/7/23 2:00):

            GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='station1.bpch',$
                             lon=-65., lat=45., lev=1, $
                             Time=[nymd2tau(20010720l,200000l),nymd2tau(20010723l,20000l)]


        ;; (7) Like example (6), but select Daily Max and for few
        ;;  days only (from 23rd to 28th of July 2001):

            GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir='~/path/', outfile='station1.bpch',$
                             lon=-65., lat=45., lev=1, /DMax,
                             Time=[20010723L,20010728L]


        ;; (8) read **ALL** MASK-files from a directory selected with
        ;; a pop-up window:

            GC_COMBINE_ND49, 1, 'IJ-AVG-$', indir=dialog_pickfile(/dir)



        ;; (9) read CLOUD FRACTION from GEOS-4 met fields. Interactive way.

            GC_COMBINE_ND49, nosave=1, data=ts,  $
                             mask='/as/data/master/ctm/GEOS_4x5.d/GEOS_4_v4/1985/02/*a6*', $
                             7, 'GMAO-2d', outtime=time


        ;; (10) read CLOUD FRACTION from GEOS-4 met fields. All data
        from February 1985 automatically:

            GC_COMBINE_ND49, nosave=1, data=ts,  $
                             indir='/as/data/master/ctm/GEOS_4x5.d/GEOS_4_v4/1985/02/', $
                             mask='*a6*', $
                             7, 'GMAO-2d', outtime=time


        ;; (11) Read 3 series of 2004 GFED2 emissions (3hr, 8-day and
                monthly):

         ; -- get data from MASK and DIRECTORY
         dir3hr  = '/as/data/geos/GEOS_1x1/GFED2_3hr_200901/2004/'
         dirMon  = '/as/data/geos/GEOS_1x1/GFED2_200601/2004/'
         dir8day = '/as/data/geos/GEOS_1x1/GFED2_8day_200712/2004/'
   
         mask3hr =  'GFED2.3hr.C_20040*.generic.1x1'
         maskMon =  'GFED2_C_2004*.generic.1x1'
         mask8day = 'GFED2_8day_C_2004*.generic.1x1'

         gc_combine_nd49, 99, 'GFED2-BB', /nosave,       data=d3hr,      $
                          mask=mask3hr,   indir=dir3hr,  outTime=tau3hr, /verb

         gc_combine_nd49, 99, 'GFED2-BB', /nosave,       data=d8day,      $
                          mask=mask8day,  indir=dir8day, outTime=tau8day, /verb

         gc_combine_nd49, 99, 'GFED2-BB', /nosave,       data=dMon,      $
                          mask=maskMon,   indir=dirMon,  outTime=tauMon, /verb



         ;-- Julian Time for each data set (the half time step is added to
         ;   get the time series centered on their period, since we plot
         ;   histograms, with psym=10)
         temp   = tau2yymmdd( tau3hr + 1.5 )
         Jul3hr = JulDay(temp.month, temp.day, temp.year, temp.hour, temp.minute)

         temp    = tau2yymmdd( tau8day + (4.*24.) )
         Jul8day = JulDay(temp.month, temp.day, temp.year, temp.hour, temp.minute)

         temp   = tau2yymmdd(tauMon + 15.*24.)
         JulMon = JulDay(temp.month, temp.day, temp.year, temp.hour, temp.minute)

         ; -- convert from [g C/m2/time-period] to [Tg C/time-period]
         GridInfo = CTM_GRID( CTM_TYPE( 'generic', res=[1., 1.] ) )
         Surface  = CTM_BOXSIZE( GridInfo, /cm2 )

         dim = size(surface, /dimensions)

         d3hr  = d3hr  * rebin( Surface, dim[0], dim[1], 1, (size(d3hr))[4] )
         d8day = d8day * rebin( Surface, dim[0], dim[1], 1, (size(d8day))[4] )
         dMon  = dMon  * rebin( Surface, dim[0], dim[1], 1, (size(dMon))[4] )

         d3hr  = d3hr  * 1e-9
         d8day = d8day * 1e-9
         dMon  = dMon  * 1e-9

         ; -- Sum data over space, and convert to [ Tg C/s ]
         sum3hr  = total( total( total(d3hr,  1), 1), 1) / (3. * 3600.)
         sum8day = total( total( total(d8day, 1), 1), 1) / (8. *24. * 3600.)


         ; -- Plot time series

         dummy = label_date( date_format=['%D', '%M'] )

         plot, Jul3hr, sum3hr, /ynozero, color=!myct.black, $
                title='Total GFED2 emissions in 2004 (Tg C/sec)', $
                /xstyle, $
                xtickformat=['label_date', 'label_date', 'label_date'], $
                xtickunit=['day', 'month'], $
                position=[0.1, 0.15, 0.9, 0.9], $
                psym=10


          oplot, Jul8day, sum8day, thick=2., color=!myct.black, psym=10




 MODIFICATION HISTORY:
        phs,  6 Jun 2007: GAMAP VERSION 2.05
                          - Initial version
        phs, 25 Jul 2007: GAMAP VERSION 2.10
                          - added Moving Average and Daily Max as
                            signal processing available before 
                            saving/passing data.
                          - added Lon and Lat keywords to select one
                            location or a smaller area.
                          - added output keywords.
        phs,  4 Oct 2007: - Bug fix for OUTTIME keyword
        phs, 12 Oct 2007: - Added OUTLEV output keyword, and LEV
                            input keyword.
                          - INDIR can be used as output keyword.
        phs, 15 Oct 2007: - added LOCALTIME keyword
        phs, 18 Oct 2007: - do not save if output file is one of the
                            input file.
        phs, 26 Oct 2007: - bug fix for LON and LAT
                          - added TIME keyword to limit
                            timeseries in time.
        phs, 28 Oct 2007: - DMAX accounts for LOCALTIME if set.
                          - Bug fix for OutTime when /DMax.
        phs, 04 Apr 2008: GAMAP VERSION 2.12
                          - added DAVG keyword
                          - now cleanup the /no_global pointers
                          - added the FILELIST keyword
        phs, 17 Jul 2008: - Added comments
        phs, 15 Aug 2008: GAMAP VERSION 2.13
                          - Bug fix for OutTime when /DMax or /DMean
                            and input are from at least two different
                            months
   mb & phs, 02 Dec 2008: - DIM is forced to 32-bit integer (LONG)
        phs, 08 Jan 2009: - Now can process files that cover time
                            periods different from one day. 
        bmy, 14 Apr 2010: GAMAP VERSION 2.14
                          - Add _EXTRA=e to CTM_GET_DATA so as to pass
                            down any flags for nested grids 

(See /n/home09/ryantosca/IDL/gamap2/timeseries/gc_combine_nd49.pro)


GETDATABLOCK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GETDATABLOCK

 PURPOSE:
        Retrieve information stored in a DATA block somewhere
        within an IDL routine. The DATA block must be "hidden"
        as comment lines for the IDL compiler. The data will be 
        returned as string array.

 CATEGORY:
        General

 CALLING SEQUENCE:
        GETDATABLOCK, DATA [, FILENAME=FILENAME, ,LABEL=LABEL ]

 INPUTS:

 KEYWORD PARAMETERS:
        FILENAME -> optional filename. Normally, the data block is
            read from the file that contains the current procedure

        LABEL -> a unique identifier for the start of the data block.
            Default is '/DATA/'. The end of the data block is reached
            at the end of file or if the block of comment lines ends.

 OUTPUTS:
        DATA -> a string array with the information contained in the 
            data block

 SUBROUTINES:
        External Subroutines Required:
        ======================================
        FILE_EXIST (function)   ROUTINE_NAME

 REQUIREMENTS:
        None

 NOTES:
        The file with the datablock is always searched in !PATH

 EXAMPLE:
        GETDATABLOCK, SDATA

             ; This will retrieve a data block labeled '/DATA/' 
             ; from the file of the current IDL routine

 MODIFICATION HISTORY:
        mgs, 22 Apr 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments, cosmetic changes

(See /n/home09/ryantosca/IDL/gamap2/general/getdatablock.pro)


GETETA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GETETA

 PURPOSE:
        Defines the eta levels for the various hybrid model grids.
        GETETA is called by function CTM_GRID.

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        RESULT = GETETA( MNAME [, NLAYERS [, Keywords ] ] )

 INPUTS:
        MNAME -> The name of the model for which eta level
             information is desired ('GEOS4' or 'GEOS4_30L').

        NLAYERS -> Specifies the number of eta layers for the 
             model type.  Default is 55 layers.

 KEYWORD PARAMETERS:
        PSURF -> Surface pressure in hPa.  If PSURF is not specified,
             GETETA will use 1013.25 hPa (e.g. 1 atmosphere).

        /CENTERS -> Returns to the calling program an array 
             containing the eta coordinate at grid box centers.

        /EDGES -> Returns to the calling program an array 
             containing the eta coordinate at grid box edges.

        A -> Returns to the calling program the "A" vector of
             values that define the hybrid grid.  A has units of
             [hPa].

        B -> Returns to the calling program the "B" vector of
             values that define the hybrid grid.  B is unitless.

        PRESSURE -> Returns the pressure [hPa] at the grid box edges 
             (if /EDGES is set) or the pressure at the grid box centers
             (if /CENTERS is set).

 OUTPUTS:
        RESULT -> contains the array of eta edges (if /EDGES is
             set), or eta centers (if /CENTERS is set).

 SUBROUTINES:
        None

 REQUIREMENTS:
        Called by CTM_GRID.PRO

 NOTES:
        Supported models:
        -----------------------------------------------------------
        (1 ) GCAP,         23-layer (name: "GCAP"         )
        (2 ) GEOS-4,       55-layer (name: "GEOS4"        )
        (3 ) GEOS-4        30-layer (name: "GEOS4_30L"    )
        (4 ) GEOS-5,       72-layer (name: "GEOS5"        )
        (5 ) GEOS-5        47-layer (name: "GEOS5_47L"    )
        (6 ) GEOS-FP       72-layer (name: "GEOSFP"       )
        (7 ) GEOS-FP       47-layer (name: "GEOSFP_47L"   )
        (8 ) MERRA,        72-layer (name: "MERRA"        )
        (9 ) MERRA         47-layer (name: "MERRA_47L"    )
        (10) MERRA2,       72-layer (name: "MERRA2"       )
        (11) MERRA2,       47-layer (name: "MERRA2_47L"   )
        (12) GISS_II_PRIME 23-layer (name: "GISS_II_PRIME")
        (13) MATCH         52-layer (name: "MATCH"        )

        Computing pressure and eta coordinates:
        -----------------------------------------------------------
        In a vertical column, the pressure at the bottom edge of 
        grid box (L) is given by:

           Pe(L)   = A(L) + ( B(L) * Psurface )

        and the pressure at the vertical midpoint of grid box (L)
        is just a simple average of the pressures at the box edges:

           Pc(L)   = ( Pe(L) + Pe(L+1) ) * 0.5

        From PEDGE and PCENTER, we can construct the unitless coordinate 
        ETA (which is very similar to the sigma coordinate) as follows:

           ETAe(L) = ( Pe(L) - Ptop ) / ( Psurface - Ptop ) 

           ETAc(L) = ( Pc(L) - Ptop ) / ( Psurface - Ptop )
 
        For GAMAP plotting routines, we will use the ETA coordinate 
        for hybrid models instead of the sigma coordinate.

        Psurface is a function of longitude and latitude.  GAMAP uses 
        a default Psurface of 1013 hPa (1 atm).  However, you should 
        always compute the pressure edges and centers from an accurate 
        surface pressure field (i.e. from met field data files or from 
        GEOS-Chem or other model output.
   
 EXAMPLE:
        EETA = GETETA( 'GEOS4' PSURF=984.0, /EDGES );
             ; assigns GEOS-1 eta edges to array EETA

        CETA = GETETA( 'GEOS4', /CENTERS, PRESSURE=CPRESS )
             ; assigns GISS-II eta centers to array CETA
             ; (Optional) also returns the pressure at level centers

 MODIFICATION HISTORY:
        bmy, 06 Nov 2001: GAMAP VERSION 1.49
                          - based on routine "getsigma.pro"
        bmy, 04 Nov 2003: GAMAP VERSION 2.01
                          - now supports "GEOS4_30L" grid
                          - now tests for model name using STRPOS 
                            instead of just a straight match
                          - stop w/ an error for non-hybrid grids
                          - now supports 23-layer GISS_II_PRIME model
                          - now supports 52-layer MATCH model
        bmy, 18 Jun 2004: GAMAP VERSION 2.02a
                          - now supports GCAP 23-layer hybrid grid
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments
        bmy, 15 Oct 2009: GAMAP VERSION 2.13
                          - Now supports GEOS-5 grids    
        bmy, 29 Nov 2010: GAMAP VERSION 2.15
                          - Now returns hybrid-grid A and B 
                            values via the A & B keywords      
                          - Now returns the pressure corresponding 
                            to ETA via the PRESSURE keyword 
                          - Renamed /CENTER to /CENTERS  

(See /n/home09/ryantosca/IDL/gamap2/internals/geteta.pro)


GETMODELANDGRIDINFO

[Previous Routine] [Next Routine] [List of Routines]
 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)


GETSIGMA (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GETSIGMA (function)

 PURPOSE:
        Defines the sigma levels for the various grids.
        GETSIGMA is called by function CTM_GRID.

 CATEGORY:
        GAMAP Internals

 CALLING SEQUENCE:
        RESULT = GETSIGMA( MNAME [ NLAYERS [ , keywords ] ] )

 INPUTS:
        MNAME -> The name of the model for which sigma level
             information is desired (e.g. 'geos1', 'giss_ii', etc.)

        NLAYERS -> Specifies the number of sigma layers for the 
             GISS family of models.  Default is 9 layers.

 KEYWORD PARAMETERS:
        CENTER -> Returns to the calling program an array 
             containing the sigma centers. 

        EDGES -> Returns to the calling program an array 
             containing the sigma edges.

        /HELP -> Prints a help screen and returns a value
             of -1 to the calling program.

 OUTPUTS:
        RESULT contains the array of sigma edges (if /EDGES is
        set), or sigma centers (if /CENTERS is set).

 SUBROUTINES:

 REQUIREMENTS:

 NOTES:
        Supported models:
        -------------------------------------------------------
        (1 ) GEOS-1     20-layer   (6 ) GEOS-3        30-layer
        (2 ) GEOS-STRAT 46-layer   (7 ) GISS-II        9-layer    
        (3 ) GEOS-STRAT 26-layer   (8 ) GISS-II-PRIME  9-layer 
        (4 ) GEOS-2     70-layer   (9 ) GISS-II-PRIME 23-layer
        (5 ) GEOS-2     47-layer   (10) FSU           14-layer   
        (6 ) GEOS-3     48-layer   (11) MOPITT         7-layer

        You can add more grids as is necessary.
        
 EXAMPLE:
        ESIG = GETSIGMA( 'GEOS1' /EDGES );
           ; assigns GEOS-1 sigma edges to array ESIG

        CSIG = GETSIGMA( 'GISS_II', 9, /CENTERS )
           ; assigns GISS-II sigma centers (9 layer model) to array CSIG 
 
 MODIFICATION HISTORY:
        mgs, 02 Mar 1998: VERSION 1.00
        bmy, 19 Jun 1998: - added dummy FSU sigma edges and centers
                          - brought comments up to date
        bmy, 16 Oct 1998: - added 26 layer GEOS-STRAT sigma levels
        mgs, 25 Nov 1998: - improved defaulting of NLayers
        bmy, 24 Feb 1999: - updated FSU sigma centers & edges
                            with values provided by Amanda Staudt
        bmy, 27 Jul 1999: GAMAP VERSION 1.42
                          - added GISS-II-PRIME 23-layer sigma levels
                          - updated comments, cosmetic changes
        bmy, 16 May 2000: GAMAP VERSION 1.45
                          - added GEOS-2 grids (47 and 70 layers)
        bmy, 19 Jun 2000: - added GEOS-2 36 pressure-layer grid
        bmy, 26 Jul 2000: GAMAP VERSION 1.46
                          - added GEOS-3 grid (48 layers)
        bmy, 26 Jul 2001: GAMAP VERSION 1.48
                          - added GEOS-3 grid (30 layers, regridded)
        bmy, 18 Dec 2003: GAMAP VERSION 2.01
                          - Now recognizes GEOS3_30L grid name
                          - Now sets 30 layers as default for GEOS3_30L
                          - Removed HELP keyword, you can use usage.pro
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/getsigma.pro)


GET_CHARSIZE_NORM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GET_CHARSIZE_NORM

 PURPOSE:
        Returns the size in normal coordinates of an average
        character. The function accounts for !P.MULTI, !P.CHARSIZE,
        and the charsize scaling you pass to a plotting routine with
        the CHARSIZE keyword.

 CATEGORY:
        Plotting, Strings

 CALLING SEQUENCE:
        RESULT = GET_CHARSIZE_NORM( CHARSIZE [, Keywords ] )

 INPUTS:
        CHARSIZE -> A N-elements vector that gives the character
             size, in character unit: 1.0 is normal size, 2.0 is
             double size, etc. Default is 1.0. 
 
 KEYWORD PARAMETERS:
        /DEVICE -> Set this switch to compute the average character
             size in device units (which is usually pixel) instead of 
             the default normal coordinates.

 OUTPUTS:
        A N-by-2 array that gives average character size in
        normal coordinates:
            RESULT[*,0] are along the X direction, 
            RESULT[*,1] are along the Y direction. 

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        PRINT, GET_CHARSIZE_NORM

            0.00878049    0.0168750    


        PRINT, GET_CHARSIZE_NORM( /DEVICE )

             7.20000      10.8000


        MULTIPANEL, 6
        PRINT, GET_CHARSIZE_NORM( [1, 2, 3.5 ], /DEVICE )

           3.60000      7.20000      12.6000   ; => X sizes in pixel
           5.40000      10.8000      18.9000   ; => Y sizes in pixel          


 MODIFICATION HISTORY:
        phs,  3 Dec 2007: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/plotting/get_charsize_norm.pro)


GET_CONC_RANGE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GET_CONC_RANGE

 PURPOSE:
        Returns a default plotting range for given GEOS-Chem tracers 
        This will be used to create concentration plots for GEOS-Chem 
        benchmarking.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        GET_CONC_RANGE, TRACERNAME, THIS_RANGE, THIS_UNIT

 INPUTS:
        TRACERNAME -> Name of the tracer for which a default
             plotting range will be returned.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        THIS_RANGE -> A 2 element vector with the [min,max] values
             to be used in creating a tracer difference plot.

        THIS_UNIT -> String with the units of the data.

 SUBROUTINES:
        None

 REQUIREMENTS:
        Routine READ_CONC_RANGE must be called before this routine
        may be used.  This will normally be done at the top of
        driver routine BENCHMARK_1YR.

 NOTES:
        (1) Meant to be used in conjunction with the GEOS-Chem 
            benchmark plotting codes.
 
        (2) Default ranges for each tracer are read from a file by the 
            complementary routine READ_DIFF_RANGE and stored in the
            GDR common block.

 EXAMPLE:
        READ_CONC_RANGE, 'conc_range.1mon'
        GET_CONC_RANGE, 'NOx', THIS_LOBOUND, THIS_HIBOUND, THIS_UNIT
        PRINT, THIS_LOBOUND, THIS_HIBOUND
            0.50000  2.00000
        PRINT, THIS_UNIT
            ppbv

            ; Prints the default plotting range and unit for NOx
          

 MODIFICATION HISTORY:
        bmy, 05 Sep 2012: VERSION 1.00
        bmy, 24 Jan 2014: GAMAP VERSION 2.17
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/benchmark/get_conc_range.pro)


GET_DEFAULTFORMAT (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GET_DEFAULTFORMAT (function)

 PURPOSE:
        Return format string that will produce legible and
        concise strings for a given value range. The format
        should be applied in a string() statement and the 
        string should be trimmed.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        MYFORMAT = GET_DEFAULTFORMAT(minval,maxval [,/LOG])

 INPUTS:
        MINVAL, MAXVAL -> the range of values that shall be 
            displayed with this format.

 KEYWORD PARAMETERS:
        /LOG -> set this keyword if you plan logarithmic labels.
            (changes behaviour for 0.001)

        DEFAULTLEN -> 1 or 2 strings with the default length 
            specification for 'f' and 'e' formats. If only one
            string is passed, it will be used for both, otherwise
            the first string applies to 'f' and the second to 'e'.
            Example: DEFAULTLEN='10.3' results in 'f10.3'.

        THRESHOLD -> threshold value to switch from 'f' to 'e' format.
            Default is '2' for linear and '3' for log scale. This
            value is determined by the negative decadal log of (maxv-minv)
            plus 2.

 OUTPUTS:
        MYFORMAT -> A format string (e.g. '(f14.2)' )

 SUBROUTINES:
        none

 REQUIREMENTS:
        none

 NOTES:
        None

 EXAMPLE:
        PRINT, GET_DEFAULTFORMAT( 0.01, 1. )
          '(f14.2)'

        PRINT, GET_DEFAULTFORMAT( 0.0001, 0.01 )
          '(e12.3)'

 MODIFICATION HISTORY:
        mgs, 17 Mar 1999: VERSION 1.00
        mgs, 25 Mar 1999: - added DEFAULTLEN keyword
        mgs, 19 May 1999: - DEFAULTLEN now converted to string.
                          - added THRESHOLD keyword
        bmy, 27 Sep 2002: TOOLS VERSION 1.51
                          - made default exponential format e12.2
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/get_defaultformat.pro)


GET_DIFF_RANGE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GET_DIFF_RANGE

 PURPOSE:
        Returns a default plotting range for given GEOS-Chem tracers 
        This will be used to create absolute difference plots for 
        GEOS-Chem benchmarking.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        RANGE = GET_DIFF_RANGE( TRACERNAME )

 INPUTS:
        TRACERNAME -> Name of the tracer for which a default
             plotting range will be returned.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RANGE -> A 2 element vector with the [min,max] values
             to be used in creating a tracer difference plot.

 SUBROUTINES:
        None

 REQUIREMENTS:
        Routine READ_DIFF_RANGE must be called before this routine
        may be used.  This will normally be done at the top of
        driver routine BENCHMARK_1MON.

 NOTES:
        (1) Meant to be used in conjunction with the GEOS-Chem 
            benchmark plotting codes.
 
        (2) Default ranges for each tracer are read from a file by the 
            complementary routine READ_DIFF_RANGE and stored in the
            GDR common block.

 EXAMPLE:
        READ_DIFF_RANGE, 'diff_range.1mon'
        PRINT, GET_DIFF_RANGE( 'NOx' )
            -0.100000  0.100000
   
            ; Prints the default plotting range for NOx
          

 MODIFICATION HISTORY:
        bmy, 14 Nov 2007: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/benchmark/get_diff_range.pro)


GET_FREELUN (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GET_FREELUN (function)

 PURPOSE:
        Return next available logical unit number. Unlike 
        the internal GET_LUN procedure, this function is not
        restricted to unit numbers above 100, and it will 
        detect any blocked unit number.

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
        lun = GET_FREELUN([LUN])

 INPUTS:
        none

 KEYWORD PARAMETERS:
        none

 OUTPUTS:
        The lowest available logical unit number. This number is 
        also returned in the LUN parameter for later use.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        OPENW, GET_FREELUN( LUN ), FILENAME

             ; Open a file and get the next free unit number.

 MODIFICATION HISTORY:
        mgs, 17 Sep 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments, cosmetic changes

(See /n/home09/ryantosca/IDL/gamap2/file_io/get_freelun.pro)


GET_GEOS5_PRESS

[Previous Routine] [Next Routine] [List of Routines]
 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)


GET_IS_EDGED (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GET_IS_EDGED  (function)

 PURPOSE:
        Determine if a GEOS-5 data field is defined on the
        vertical grid box edges or centers.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        RESULT = GET_IS_EDGED( NAME )

 INPUTS:
        NAME -> Name of the tracer or met field to be tested.

 KEYWORD PARAMETERS:

 OUTPUTS:
        RESULT -> Returns 1 if the tracer or met field specified by
             NAME is defined on grid box vertical edges, or 0
             otherwise.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        (1) This is currently a KLUDGE.  Figure out a more 
            robust way of determining if fields are defined on 
            level edges or level centers later on. (bmy, 7/16/07)

        (2) Add more names to the CASE statement as necessary.

 EXAMPLES:
        (1)
        PRINT, GET_IS_EDGED( 'PEDGE' )
          1
             ; The GEOS-5 PEDGE field is defined on the vertical
             ; grid edges, so GET_IS_EDGED returns 1.

        (2)
        PRINT, GET_IS_EDGED( 'UWND' )
          0

             ; The GEOS-5 UWND field is defined on the vertical
             ; grid centers, so GET_IS_EDGED returns 0.

 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/internals/get_is_edged.pro)


GET_RANGE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GET_RANGE

 PURPOSE:
        Enter the data range into a variable descriptor array

 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        GET_RANGE,data,vardesc [,minvalid]

 INPUTS:
        DATA -> The data array (NLINES, NVARS)

        VARDESC -> The variable descriptor array (see GTE_VARDESC).
            Must contain NVARS elements, and a 2-element vector
            tagged RANGE. These values will be changed.

        MINVALID -> minimum valid data value to discriminate against
            missing values etc. Default is -1.0E30.

 KEYWORD PARAMETERS:
        none

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required
        ===============================
        GTE_VARDESC (function)

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        ; read binary data and retrieve range
        READ_BDT0001, '~/tmp/*.bdt', DATA, VARDESC
        GET_RANGE, DATA, VARDESC

 MODIFICATION HISTORY:
        mgs, 24 Aug 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/get_range.pro)


GIF2PS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GIF2PS

 PURPOSE:
        Translates GIF images to PostScript format.

 CATEGORY:
        Graphics

 CALLING SEQUENCE:
        GIF2PS [, FILENAME [, Keywords ] ]

 INPUTS:
        FILENAME (optional) -> Name of the input GIF file.  
             If FILENAME is omitted then GIF2PS will prompt
             the user to supply a file name via a dialog box.
             FILENAME may contain wild card characters.

 KEYWORD PARAMETERS:
        OUTFILENAME -> Name of the output PostScript file.
             Default is "idl.ps".

        /FLIP_BW -> Set this keyword to turn black pixels into
             white pixels and vice-versa.  This is useful for
             creating PostScript files of GIF images that have a 
             dark background color. 

        XOFFSET, YOFFSET (optional) -> Set these keywords to specify
             the X and Y Margins in inches.  Defaults are 
             XMARGIN = 0.5 inches and YMARGIN = 0.5 inches.
 
        _EXTRA=e -> Picks up extra keywords for OPEN_DEVICE,
             TVIMAGE, and CLOSE_DEVICE.

 OUTPUTS:
        Sends output to a PostScript file, whose name is given
        by the OUTFILENAME keyword.

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        EXTRACT_FILEPATH (function)
        DIALOG_PICKFILE  (function)
        TVIMAGE

 REQUIREMENTS:
        None

 NOTES:
        (1) Image processing options are limited to flipping the
            black and white pixels.  This should be good enough
            for most purposes.

        (2) XMARGIN and YMARGIN assume that we are printing out for
            standard USA 8.5 x 11" page.  Device sizes listed below
            are also in inches.  

 EXAMPLE:
        (1)
        GIF2PS, 'my_gif.gif', OUTFILENAME='my_ps.ps'

             ; Translates the image in "my_gif.gif" to 
             ; the PostScript file "my_ps.ps".

        (2)
        GIF2PS, 'my_gif.gif', OUTFILENAME='my_ps.ps', /FLIP_BW
        
             ; Same as in (1), but also changes all black
             ; pixels to white and vice-versa.  

        (3)
        GIF2PS, 'my_gif.gif', OUTFILENAME='my_ps.ps', /FLIP_BW, $
             XMARGIN=0.5, YMARGIN=0.5
        
             ; Same as in (2), but also will "pad" the image with
             ; 0.5" of white space around each side.

 MODIFICATION HISTORY:
        bmy, 28 Jan 2000: VERSION 1.45
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/graphics/gif2ps.pro)


HCOLORBAR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        HCOLORBAR

 PURPOSE:
        Plot a horizontal colorbar.
        %%% NOTE: This is obsolete, you should use COLORBAR instead! %%%

 CATEGORY:
        Color

 CALLING SEQUENCE:
        HCOLORBAR, CX, CY, [,keywords]

 INPUTS:
        CX     -> [Min X, Max X] vector in NORMAL coords
        CY     -> [Min Y, Max Y] vector in NORMAL coords

 KEYWORD PARAMETERS:
        COLORS -> array of color levels
        LABELS -> string array of labels for the color levels

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        HCOLORBAR assumes n_elements(COLORS) >= n_elements(LABELS)+1

 NOTES:
       (1) HCOLORBAR is more or less obsolete.  You should use
           the COLORBAR routine instead.  However, there may be
           some applications where HCOLORBAR is required, so we
           keep this routine for backwards compatibility with
           older IDL code.

       (2) The colorbar will be plotted as follows:

             LABELS(0)   LABELS(1)                     LABELS(NL-1)
    +-----------+-----------+----------- // --------------+------------+
    | COLORS(0) | COLORS(1) | COLORS(2)  //  COLORS(NL-1) | COLORS(NL) |
    +-----------+-----------+----------- // --------------+------------+

        COLORS(0) = color index for data < first contour level
        COLORS(1) = color index for data between 1st and 2nd levels
           ...
        COLORS(NL) = color index for data >= the last contour level

        LABELS(0)  = label for the first contour level
        LABELS(1)  = label for the 2nd contour level, etc...
           ...
        LABELS(NL) = label for data >= the last contour level
  
 EXAMPLE:
        HCOLORBAR, [0.025, 0.275], [0.680, 0.690], $
           COLORS=[0,1,2,3,4,5],  LABELS=['1','2','3','4','5']

 MODIFICATION HISTORY:
        bmy, 10 Nov 1994: VERSION 1.00
        bmy, 24 Jun 1997: VERSION 1.01
        bmy, 30 Sep 1997: TOOLS VERSION 1.10
        bmy, 20 Nov 1997: TOOLS VERSION 1.11
        bmy, 02 Aug 1999: TOOLS VERSION 1.43 
                          - minor bug fix
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments, cosmetic changes

(See /n/home09/ryantosca/IDL/gamap2/color/hcolorbar.pro)


HDF_GETSD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        HDF_GETSD

 PURPOSE: 
        Convenience routine to read scientific dataset variables 
        from Hierarchical Data Format (HDF) files

 CATEGORY:
        File & I/O, Scientific Data Formats

 CALLING SEQUENCE:
        DATA = HDF_GETSD( FID, NAME [, _EXTRA=e ] )

 INPUTS:
        FID -> HDF File ID, as returned by routine HDF_SD_START.

        NAME -> Name of the scientific dataset variable that
             you want to extract from the file.  

 KEYWORD PARAMETERS:
        _EXTRA=e -> Passes extra keywords to routine HDF_SD_GETDATA.

 OUTPUTS:
        DATA -> Array containing extracted data from the HDF file.

 SUBROUTINES:
        None

 REQUIREMENTS:
        Need to use a version of IDL w/ HDF routines installed.

 NOTES:
        Taken from MOP02Viewer by Yottana Khunatorn (bmy, 7/17/01)
        
 EXAMPLE:

        ; Make sure HDF is supported on this platform
        IF ( HDF_EXISTS() eq 0 ) then MESSAGE, 'HDF not supported!'

        ; Open the HDF file and get the file ID # (FID)
        FID = HDF_SD_START( 'fvdas_flk_01.ana.eta.20011027.hdf', /Read )
        IF ( FID lt 0 ) then MESSAGE, 'Error opening file!'

        ; Read the UWND field from disk
        DATA = HDF_GETSD( fId, 'UWND' )

        ; Close the file 
        HDF_SD_END, FID

 MODIFICATION HISTORY:
        bmy, 05 Nov 2001: VERSION 1.00
        bmy, 23 Apr 2002: TOOLS VERSION 1.50
                          - updated documentation
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/hdf_getsd.pro)


HDF_GETSDATTR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        HDF_GETSDATTR

 PURPOSE: 
        Convenience routine to read attributes (global or variable-
        associated) from Hierarchical Data Format (HDF) files.

 CATEGORY:
        File & I/O, Scientific Data Formats

 CALLING SEQUENCE:
        DATA = HDF_GETSDATTR( ID, NAME [ , Keywords ] )

 INPUTS:
        ID -> HDF File ID as returned by routine HDF_SD_START,
             or scientific dataset ID, as returned by routine
             HDF_SD_SELECT.

        NAME -> Name of the attribute to be read from the HDF file.

 KEYWORD PARAMETERS:
        COUNT -> Returns the total number of values in the 
             specified attribute to the calling program.
 
        HDF_TYPE -> Returns the HDF type of the attribute to the
             calling program.  HDF types are returned as a scalar
             string.  Possible returned values are DFNT_NONE, 
             DFNT_CHAR, DFNT_FLOAT32, DFNT_FLOAT64, DFNT_INT8, 
             DFNT_INT16, DFNT_INT32, DFNT_UINT8, DFNT_UINT16, and 
             DFNT_UINT32.

        TYPE -> Returns the IDL type pf the attribute to the calling 
             program.  The type of the attribute is returned as a
             scalar string. Possible returned values are BYTE, INT, 
             LONG, FLOAT, DOUBLE, STRING, or UNKNOWN.

 OUTPUTS:
        DATA -> Array containing attribute data from the HDF file.

 SUBROUTINES:
        IDL HDF routines used:
        ==========================
        HDF_SD_AttrInfo  
        HDF_SD_AttrFind (function)

 REQUIREMENTS:
        Need to use a version of IDL w/ HDF routines installed.

 NOTES:
        None
        
 EXAMPLE:

        ; Make sure HDF is supported on this platform
        IF ( NCDF_EXISTS() eq 0 ) then MESSAGE, 'HDF not supported!'

        ; Open the HDF file and get the file ID # (FID)
        FID = HDF_SD_START( 'fvdas_flk_01.ana.eta.20011027.hdf', /READ )
        IF ( FID lt 0 ) then MESSAGE, 'Error opening file!'

        ; Read the Ak, Bk, and PTOP attributes from the HDF file
        ; These are GLOBAL attributes associated w/ the file
        AK   = HDF_GETSDATTR( FID, 'ak'   )
        BK   = HDF_GETSDATTR( FID, 'bk'   )
        PTOP = HDF_GETSDATTR( FID, 'ptop' )

        ; Close the HDF file 
        HDF_SD_END, FID

 MODIFICATION HISTORY:
        bmy, 30 Apr 2002: TOOLS VERSION 1.50
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/hdf_getsdattr.pro)


HDF_GETVD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        HDF_GETVD

 PURPOSE: 
        Convenience routine to read VDATA variables 
        from Hierarchical Data Format (HDF) files

 CATEGORY:
        File & I/O, Scientific Data Formats

 CALLING SEQUENCE:
        VDATA = HDF_GETVD( FID, NAME [, _EXTRA=e ] )

 INPUTS:
        FID -> HDF File ID, as returned by routine HDF_OPEN.

        NAME -> Name of the VDATA variable that you 
             want to extract from the file.  

 KEYWORD PARAMETERS:
        _EXTRA=e -> Passes extra keywords to routine HDF_VD_READ.

 OUTPUTS:
        VDATA -> Array containing extracted data from the HDF file.

 SUBROUTINES:
        None

 REQUIREMENTS:
        Need to use a version of IDL w/ HDF routines installed.

 NOTES:
        Taken from MOP02Viewer by Yottana Khunatorn (bmy, 7/17/01)
        
 EXAMPLE:
        FID = HDF_OPEN( 'fvdas_flk_01.ana.eta.20011027.hdf', /Read )
        IF ( FID lt 0 ) then Message, 'Error opening file!'
        PTOP = HDF_GETVD( fId, 'PTOP' ) 
        HDF_CLOSE, FID

             ; Opens an HDF-format file and gets the file ID.  Then
             ; call HDF_GETSD to return the PTOP variable from the 
             ; file.  Then close the file and quit.

 MODIFICATION HISTORY:
        bmy, 05 Nov 2001: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/hdf_getvd.pro)


HDF_SETSD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        HDF_SETSD

 PURPOSE:
        Convenience routine to write data into the Hierarchical Data
        Format Scientific Dataset (HDF-SD) structure

 CATEGORY:
        File & I/O, Scientific Data Formats

 CALLING SEQUENCE:
        HDF_SETSD, FID, DATA, NAME [, Keywords ]

 INPUTS:
        FID -> HDF File ID, as returned by routine HDF_SD_START.

        DATA -> Data (array or scalar) to be written to HDF-SD format.

        NAME -> Name under which the data array will be saved 
             to the HDF file.  

 KEYWORD PARAMETERS:
        LONGNAME -> Longer descriptive name for the data.  This will 
             be saved as the "long_name" attribute.  Default is ''.

        RANGE -> A 2-element vector containing the [min,max] of
             the data array.  If not passed, RANGE will be computed
             (but only for numeric data types).  RANGE will be saved 
             to the HDF file as the "valid_range" attribute.

        _EXTRA=e -> picks up extra keywords for HDF_SD_SETINFO, such
             as FILL, UNIT, COORDSYS, etc...

 OUTPUTS:
        None

 SUBROUTINES:
        Uses the following IDL HDF routines:
        ===========================================
        HDF_SD_Create (function)  HDF_SD_SetInfo
        HDF_SD_AddData            HDF_SD_EndAccess 
        DATATYPE      (function) 

 REQUIREMENTS:
        Need to use a version of IDL w/ HDF routines installed.

 NOTES:
        (1) Since HDF supports the STRING type, we do not have to
            treat BYTE data like ASCII characters (cf ncdf_set.pro)

 EXAMPLE:
 
        ; Find out if HDF is supported on this platform
        IF ( HDF_EXISTS() eq 0 ) then MESSAGE, 'HDF not supported!'

        ; Open the HDF file
        FID = HDF_SD_START( 'myhdf.hdf', /Create )
        IF ( FID lt 0 ) then Message, 'Error opening file!'

        ; Write data to disk
        HDF_SETSD, FID, DATA, 'NOx',         $
                   LONGNAME='Nitrogen Oxide',$
                   UNIT='v/v',               $
                   FILL=0.0, 

        ; Close HDF File
        HDF_SD_END, FID

             ; Writes NOx data to an HDF file.

 MODIFICATION HISTORY:
        bmy, 17 Apr 2002: TOOLS VERSION 1.50
        bmy, 11 Sep 2002: TOOLS VERSION 1.51
                          - Now call routine DATATYPE to determine
                            the type of the data so that we can
                            write all data types to the HDF file.
                          - Don't add the RANGE attribute to
                            the HDF file for a string type value.
                          - Updated comments 
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/hdf_setsd.pro)


HIST_ND

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       HIST_ND

 PURPOSE:

       Perform an N-dimensional histogram, also known as the joint
       density function of N variables, ala HIST_2D.

 CATEGORY:
       Regridding

 CALLING SEQUENCE:
       hist=HIST_ND(V,BINSIZE,MIN=,MAX=,NBINS=,REVERSE_INDICES=)

 INPUTS:

       V: A NxP array representing P data points in N dimensions.  

       BINSIZE: The size of the bin to use. Either an N point vector
         specifying a separate size for each dimension, or a scalar,
         which will be used for all dimensions.  If BINSIZE is not
         passed, NBINS must be.

 OPTIONAL INPUTS: 

       MIN: The minimum value for the histogram.  Either a P point
         vector specifying a separate minimum for each dimension, or
         a scalar, which will be used for all dimensions.  If
         omitted, the natural minimum within the dataset will be
         used.

       MAX: The maximum value for the histogram.  Either a P point
         vector specifying a separate maximmum for each dimension, or
         a scalar, which will be used for all dimensions. If omitted,
         the natural maximum within the dataset will be used.

       NBINS: Rather than specifying the binsize, you can pass NBINS,
         the number of bins in each dimension, which can be a P point
         vector, or a scalar.  If BINSIZE it also passed, NBINS will
         be ignored, otherwise BINSIZE will then be calculated as
         binsize=(max-min)/nbins.  Note that *unlike* RSI's version
         of histogram as of IDL 5.4, this keyword actually works as
         advertised, giving you NBINS bins over the range min to max.

 KEYWORD PARAMETERS:
       
       MIN,MAX,NBINS: See above
       
       REVERSE_INDICES: Set to a named variable to receive the
         reverse indices, for mapping which points occurred in a
         given bin.  Note that this is a 1-dimensional reverse index
         vector (see HISTOGRAM).  E.g., to find the indices of points
         which fell in a histogram bin [i,j,k], look up:

             ind=[i+nx*(j+ny*k)]
             ri[ri[ind]:ri[ind+1]-1]

         See also ARRAY_INDICES for converting in the other
         direction.

 OUTPUTS:

       hist: The N-Dimensional histogram, of size N1xN2xN3x...xND
         where the Ni's are the number of bins implied by the data,
         and/or optional inputs min, max and binsize.

 OPTIONAL OUTPUTS:

       The reverse indices.

 EXAMPLE:
       
       v=randomu(sd,3,100)
       h=hist_nd(v,.25,MIN=0,MAX=1,REVERSE_INDICES=ri)

 SEE ALSO:

       HISTOGRAM, HIST_2D

 MODIFICATION HISTORY:

       Mon Mar 5 09:45:53 2007, J.D. Smith 

               Correctly trim out of range elements from the
               histogram, when MIN/MAX are specified. Requires IDL
               v6.1 or later.

       Tue Aug 19 09:13:43 2003, J.D. Smith 

               Slight update to BINSIZE logic to provide consistency
               with HIST_2D.

       Fri Oct 11 10:10:01 2002, J.D. Smith 

               Updated to use new DIMENSION keyword to MAX/MIN.

       Fri Apr 20 12:57:34 2001, JD Smith 

               Slight update to NBINS logic.  More aggressive keyword
               checking.

       Wed Mar 28 19:41:10 2001, JD Smith 

               Written, based on HIST_2D, and suggestions of CM.

   phs, bmy, 30 May 2008: GAMAP VERSION 2.12
                          - Added to GAMAP under "Regridding" category
   

(See /n/home09/ryantosca/IDL/gamap2/regridding/hist_nd.pro)


HYSTAT (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        HYSTAT (function)

 PURPOSE:
        Compute atmospheric pressures in hydrostatic equilibrium.
        This function is adapted from the Harvard photochemical
        point model (CHEM1D).

 CATEGORY:
        Atmospheric Sciences 

 CALLING SEQUENCE:
        pressure = HYSTAT,alt,temp,psurf,g0,rearth

 INPUTS:
        ALT -> Altitude in km. This can be a single value or an array.

        TEMP -> Temperatures corresponding to the altitudes in ALT

        PSURF -> A surface pressure value in mbar. Default is 1013.25 mbar.

        G0 -> acceleration du eto gravity in m/s2. Default is 9.80665 m/s2 .

        REARTH -> Radius of the earth in km. Default is 6356.77 km.

 KEYWORD PARAMETERS:
        none

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        ALT = FINDGEN(20)               ; create altitude array 0..19 km
        TEMP = TEMP = 205.+(19-ALT)*4.  ; a semi-realistic temperature 
                                        ; profile
        PRESS = HYSTAT(ALT,TEMP)        ; compute pressures
        PRINT, PRESS

           1013.25   896.496   791.815   698.104   614.349   
           539.613   473.041   413.843   361.298   314.745   
           273.581   237.254   205.261   177.146   152.492   
           130.924   112.098   95.7080   81.4736   69.1443

 MODIFICATION HISTORY:
        mgs, 21 Aug 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/hystat.pro)


IDL2HTML

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        IDL2HTML

 PURPOSE:
        Wrapper for MK_HTML_HELP.  Can be used to create HTML files
        which contain the comments from the standard doc headers
        that are included with each IDL routine.

 CATEGORY:
        Documentation

 CALLING SEQUENCE:
        IDL2HTML, PATH, [ , Keywords ]

 INPUTS:
        PATH -> A file path (can be a directory, single file name,
             or file mask) for the IDL routines whose doc headers
             you wish to convert to HTML format.

 KEYWORD PARAMETERS:
        /ALPHABETICAL -> Set this switch to create a separate HTML 
             documentation file for files beginning with each letter
             of the alphabet.  This is useful if you have a lot of
             files to process.

        /CATEGORY -> If specified, IDL2HTML will create a HTML file
             for all *.pro files corresponding to a given category
             (as specified by the CATEGORY tag in the standard
              IDL documentation headers).

        HTMLFILE -> Name of the HTML file that will be created.
             A default file name will be used if HTMLFILE is omitted.

        OUTDIR -> Name of the directory into which the HTML
             documentation files will be written.

        _EXTRA=e -> Passes extra keywords to MK_HTML_HELP.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        =======================================================
        ADD_SEPARATOR (function)   EXTRACT_FILENAME (function)
        IS_DIR (function)          STRWHERE         (function)

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        IDL2HTML, '~/IDL/tools/', OUTDIR='~/doc/html/', /ALPHABETICAL

             ; Will create HTML files with documentation from the
             ; IDL routines in the ~/IDL/tools directory.  Will
             ; place the output in the ~/doc/html directory.

 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/doc/idl2html.pro)


IMAGE_MAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	IMAGE_MAP

 PURPOSE:
	Overlay an image and a map (satellite projection)

 CATEGORY:
	Plotting

 CALLING SEQUENCE:
	IMAGE_MAP, A

 INPUTS:
	A -> The two-dimensional array to display.

 KEYWORD PARAMETERS:
       WINDOW_SCALE -> Set this keyword to scale the window size to 
           the image size. Otherwise, the image size is scaled to 
           the window size.  This keyword is ignored when outputting 
           to devices with scalable pixels (e.g., PostScript).
           [original as in image_contour]

	ASPECT-> Set this keyword to retain the image's aspect ratio.
	    Square pixels are assumed.  If WINDOW_SCALE is set, the 
	    aspect ratio is automatically retained.
           [original as in image_contour]

	INTERP -> If this keyword is set, bilinear interpolation 
           is used if the image is resized.
           [original as in image_contour]

       CENTERX -> longitudinal position of geostationary satellite
           (default -135 = GEOS-9)

       DIST -> distance of satellite from Earth surface (in earth radii)
           (default = 7)

       CONTINENTS -> superimpose map continents on the image

 OUTPUTS:
	No explicit outputs.

 COMMON BLOCKS:
	None

 SIDE EFFECTS:
	The currently selected display is affected.

 RESTRICTIONS:
	None

 NOTES:
       Derived from IDL routine image_contour.
       Not very flexible - quick hack to analyze PEM-T data

 PROCEDURE:
	If the device has scalable pixels, then the image is written over
	the plot window.

 MODIFICATION HISTORY:
	 mgs, 01 Oct 1997: based on IMAGE_CONT by DMS, May, 1988.
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/plotting/image_map.pro)


IND_COMB

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        IND_COMB

 PURPOSE:
        Combine two index arrays that result from different
        WHERE calls to the same data set.

 CATEGORY:
        General

 CALLING SEQUENCE:
        RESULT = IND_COMB( INDEX1, INDEX2, TYPE [, keywords ] )

 INPUTS:
        INDEX1, INDEX2 --> the two index arrays (may be single 
             integers or -1, but must be given)

        TYPE --> a string containing the type of index combination:
             The result will contain an index value if the index is 
             contained in ...
               type eq "OR":   ... at least one of INDEX1 or INDEX2
               type eq "AND":  ... INDEX1 and INDEX2
               type eq "NOR":  ... neither INDEX1 nor INDEX2
               type eq "XOR":  ... only one of INDEX1 or INDEX2
               type eq "NAND": ... not in both
             The default combination is "OR".

 KEYWORD PARAMETERS:
        TOTALN --> optional: number of elements in the data set. 
             If not given, this value is calculated as 
             max([index1,index2]).  If this argument is passed, 
             the user has full responsibility that array indices 
             are not exceeded.  ATTENTION: types NAND and NOR may 
             give wrong results if TOTALN is not specified 
             (see example).

 OUTPUTS:
        RESULT -> An array of type lon that contains the combined 
             indices and can be used as an array subscript.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        DATA = FINDGEN(100)+1
        IND1 = WHERE(DATA le 50)
        IND2 = WHERE(DATA ge 50 AND DATA lt 80)

        RES = IND_COMB(IND1,IND2,"OR")
            print,'1:',min(data(res)),max(data(res)) 

        RES = IND_COMB(IND1,IND2,"AND")
            print,'2:',min(data(res)),max(data(res))

        RES = IND_COMB(IND1,IND2,"NOR")   ; <------  WRONG !!
            print,'3:',res                         

        RES = IND_COMB(IND1,IND2,"NOR",TOTALN=100)
            print,'4:',min(data(res)),max(data(res))

        RES = IND_COMB(IND1,IND2,"XOR")
            print,'5:',min(data(res)),max(data(res))

        RES = IND_COMB(IND1,IND2,"NAND")  ; <------  WRONG !!
            print,'6:',min(data(res)),max(data(res))

        RES = IND_COMB(IND1,IND2,"NAND",TOTALN=100)
            print,'7:',min(data(res)),max(data(res))

        IDL will print:
            1:  1    79
            2: 50    50 
            3: -1           <------  WRONG !!
            4: 80   100
            5:  1    79
            6:  1    79     <------  WRONG !!
            7:  1   100

 MODIFICATION HISTORY:
        mgs, 04 Dec 1997: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - updated comments, cosmetic changes

(See /n/home09/ryantosca/IDL/gamap2/general/ind_comb.pro)


INTERPOLATE_2D

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        INTERPOLATE_2D

 PURPOSE:
        Interpolates a 2-D array from one grid to another.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        NEWDATA = INTERPOLATE_2D( DATA,    OLDXMID, OLDYMID,    $
                                  NEWXMID, NEWYMID  [, Keywords ] )

 INPUTS:
        DATA -> A 2-D array containing the data to be interpolated.

        OLDXMID -> A 1-D vector containing the X-coordinates (e.g. 
             longitude) corresponding to the DATA array.

        OLDYMID -> A 1-D vector containing the Y-coordinates (e.g. 
             latitude) corresponding to the DATA array.

        NEWXMID -> A 1-D vector containing the X-coordinates (e.g. 
             longitude) of the new grid onto which DATA will be 
             interpolated.

        NEWYMID -> A 1-D vector containing the Y-coordinates (e.g. 
             latitude) of the new grid onto which DATA will be 
             interpolated.

 KEYWORD PARAMETERS:
        /DOUBLE -> Set this switch to force computation in double 
             precision.  Default is to use single precision.

 OUTPUTS:
        NEWDATA -> A 2-D array containing the data on the new grid.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        INTERPOLATE_2D can be used to interpolate from coarse grids
        to fine grids or fine grids to coarse grids.  This routine
        uses the IDL INTERPOL command.
    
 EXAMPLE:

        ; Define old grid (GEOS-Chem 2x25)
        OLDTYPE  = CTM_TYPE( 'GEOS4', RES=2 )
        OLDGRID  = CTM_GRID( OLDTYPE        )

        ; Define new grid (GEOS-Chem 4x5)
        NEWTYPE  = CTM_TYPE( 'GEOS4', RES=4 )
        NEWGRID  = CTM_GRID( NEWTYPE        )

        ; Interpolate DATA array from 2x25 to 4x5
        NEWDATA  = INTERPOLATE_2D( DATA,                       $
                                   OLDGRID.XMID, OLDGRID.YMID, $
                                   NEWGRID.XMID, NEWGRID.YMID )

             ; Interpolate a data array from the GEOS-Chem 
             ; 2 x 2.5 grid to the GEOS-Chem 4 x 5 grid
        
 MODIFICATION HISTORY:
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/interpolate_2d.pro)


INV_INDEX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        INV_INDEX

 PURPOSE:
        Find the indices that do NOT match a WHERE condition

 CATEGORY:
        General

 CALLING SEQUENCE:
        RESULT = INV_INDEX( INDEX, TOTALN )

 INPUTS:
        INDEX -> An index array, e.g. previously generated by a
              WHERE command (may be -1)

        TOTALN -> the number of elements in the reference data
              set, i.e. totaln = n_elements(index)+n_elements(result)

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> an integer array with all indices that were NOT
              in index or -1 if index was complete

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        The function returns -1 if one of the following errors occurs:
        - invalid number of arguments
        - index variable is undefined
        - totaln is less than n_elements(index)
        - totaln less or equal 1, i.e. no associated data
        The last error does not produce an error message, since this
        feature was found to be very useful (in EXPLORE, the widget based
        interactive data explorer)

 EXAMPLE:
        DATA   = FINDGEN( 50 )
        INDEX  = WHERE( DATA ge 25 )
        INVERS = INV_INDEX( INDEX, N_ELEMENTS( DATA ) )
        PRINT, INVERS
           0  1  2  3  4  5  6  7  8  9
          10 11 12 13 14 15 16 17 18 19
          20 21 22 23 24

             ; Find the elements of DATA that are greater than 25
             ; and then print the inverse condition

 MODIFICATION HISTORY:
        mgs, 10 May 1997: VERSION 1.00
        mgs, 18 Aug 1997: - added template and check if n_elements(index) eq 0
        mgs, 05 Apr 1999: - bug fix: needed to make sure result is type long
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/inv_index.pro)


IN_RANGE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        IN_RANGE

 PURPOSE:
        IN_RANGE checks to see if an input value lies
        between a minimum value and a maximum value.

 CATEGORY:
        General

 CALLING SEQUENCE:
        RESULT = IN_RANGE(VALUE, MINVAL, MAXVAL)

 INPUTS:
        VALUE  -> The value to be checked
        MINVAL -> The minimum value 
        MAXVAL -> The maximum value

 KEYWORD PARAMETERS:

 OUTPUTS:
       If MINVAL <= VALUE <= MAXVAL, IN_RANGE returns 0
       If VALUE < MINVAL,            IN_RANGE returns 1
       If VALUE > MAXVAL,            IN_RANGE returns 1 

 SUBROUTINES:
       None

 REQUIREMENTS:
       None

 EXAMPLE: 
        IF ( NOT IN_RANGE( VALUE, 0, 100 ) ) $
           THEN PRINT, 'VALUE is not in between 0-100'

             ; Print a message if VALUE lies outside
             ; of the range 0-100
   
  
 MODIFICATION HISTORY:
        bmy, 24 Sep 1997: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/general/in_range.pro)


ISALGEBRAIC (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISALGEBRAIC (function)

 PURPOSE:
        Locates the position of algebraic characters in a string
        (e.g. locations that are EITHER digits '.' OR +/- signs).

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        Result = ISALGEBRAIC( S [, Keywords ] )

 INPUTS:
        S -> The string to be tested.  

 KEYWORD PARAMETERS:

 OUTPUTS:
        Result -> The value of the function.  RESULT is an index array
            (integer) that contains as many elements as S has 
            characters.  If S is a single character, then RESULT will 
            be scalar. Where RESULT = 1, the corresponding characters 
            in S are algebraic.

 SUBROUTINES:

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        print, ISALGEBRAIC( '-100;+100' )
            ; prints 1 1 1 1 0 1 1 1 1 

 MODIFICATION HISTORY:
        bmy, 17 Nov 1998: VERSION 1.00
        mgs, 17 Nov 1998: - removed INVERT keyword. It's 
                            simply 1-isalgebraic
                          - added test for '.'
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isalgebraic.pro)


ISALNUM (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISALNUM (function)

 PURPOSE:
        IDL analog to the 'isalnum' routine in C.  Locates 
        alphanumeric characters ( A...Z, a...z, 0..9 ) in a string.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        Result = ISALNUM( S )

 INPUTS:
        S  -> The string to be tested.  

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        Result -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are alphanumeric

 SUBROUTINES:
        ISALPHA (function)
        ISDIGIT (function)

 REQUIREMENTS:

 NOTES:
        None

 EXAMPLE:
        print, isalnum( 'ABCD0123#' )
            ; prints, 1 1 1 1 1 1 1 1 0

        print, isalnum( '#' )
            ; prints 0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998  - now use BYTE function in where statement
                            instead of hardwired constants
        bmy, 02 Jun 1998  VERSION 1.10
                          - now uses ISALPHA and ISDIGIT
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isalnum.pro)


ISALPHA (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISALPHA (function)

 PURPOSE:
        IDL analog to the 'isalpha' routine in C.  Locates the
        positions of alphabetic characters ( A...Z, a...z ).

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISALPHA( S )

 INPUTS:
        S  -> The string to be tested. 

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are alphabetic.
        
 SUBROUTINES:
        ISUPPER (function)
        ISLOWER (function)

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        PRINT, ISALPHA( 'ABcd0123' )
          1 1 1 1 0 0 0 0

        PRINT, ISALPHA( '#' )
          0

 MODIFICATION HISTORY:
        bmy, 29 May 1998: VERSION 1.00
        bmy, 01 Jun 1998: - now returns 0 for condition FALSE
                          - fixed bug that allowed byte values from
                            91-96 to be treated as letters
        bmy, 02 Jun 1998  - now use BYTE function in where statement
                            instead of hardwired constants
        bmy, 02 Jun 1998  VERSION 1.10
                          - now uses ISUPPER and ISLOWER 
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isalpha.pro)


ISDIGIT (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISDIGIT (function)

 PURPOSE:
        IDL analog to the 'isdigit' routine in C.  Locates
        numeric characters ( '0' ... '9') in a string. 

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISDIGIT( S )

 INPUTS:
        S -> The string to be tested.  

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are numeric.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        print, isdigit( '3001ABcd' )
            ; prints, 1 1 1 1 0 0 0 0

        print, isdigit( '#' )
            ; prints 0

 MODIFICATION HISTORY:
        bmy, 29 May 1998: VERSION 1.00
        bmy, 01 Jun 1998: - now returns 0 for condition FALSE
        bmy, 02 Jun 1998  - now use BYTE function in where statement
                            instead of hardwired constants
        bmy, 02 Jun 1998  VERSION 1.10
                          - now can analyze an entire string
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isdigit.pro)


ISGRAPH (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISGRAPH (function)

 PURPOSE:
        IDL analog to the 'isgraph' routine in C.  Locates all
        graphics characters in a string.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISGRAPH( S ) 

 INPUTS:
        S  -> The string to be tested.  

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are graphics characters.

 SUBROUTINES:
        None

 REQUIREMENTS:

 NOTES:
        Graphics characters are printing characters (i.e. they can be
        seen on the screen or on a printout) but EXCLUDE the 
        space ( ' ' ) character.

 EXAMPLE:
        print, isgraph( 'ABCD !#~%' )
          1 1 1 1 0 1 1 1 1

        print, isgraph( string( 9B ) )  ; horizontal tab
          0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998  - now use BYTE function in where statement
                            instead of hardwired constants
        bmy, 02 Jun 1998  VERSION 1.10
                          - now can analyze an entire string
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isgraph.pro)


ISLEAP (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISLEAP (function)

 PURPOSE:
        Returns 1 for each year that is a leap year.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = ISLEAP( YEAR )

 INPUTS:
        YEAR -> A year or an array of years. Must be "4 digit" years.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> An integer value or array with 1 for each 
             year that is a leap year.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        For many purposes one should take a look at built-in
        IDL date functions first (version > 5.0).

 EXAMPLE:
        YEARS = FINDGEN(25) + 1980 
        PRINT, 365 + ISLEAP(YEARS), FORMAT='(10i4)'
          366 365 365 365 366 365 365 365 366 365
          365 365 366 365 365 365 366 365 365 365
          366 365 365 365 366

             ; Compute the number of days in each year
             ; from 1980 to 2005 using ISLEAP to add
             ; either 1 or 0 to 365.

 MODIFICATION HISTORY:
        mgs, 02 Oct 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - updated comments, cosmetic changes

(See /n/home09/ryantosca/IDL/gamap2/date_time/isleap.pro)


ISLOWER (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISLOWER (function)

 PURPOSE:
        IDL analog to the 'islower' routine in C.  Locates all 
        lowercase alphabetic characters in a string.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISLOWER( S )

 INPUTS:
        S  -> The string to be tested

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are lowercase alphabetic.

 SUBROUTINES:
        None

 REQUIREMENTS:

 NOTES:
        None

 EXAMPLE:
        print, islower( 'abcdefG' )
          1  1  1  1  1  1  0

        print, islower( 'A' )
          0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998: VERSION 1.10
                          - now can analyze entire strings
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/islower.pro)


ISOPLETH_MAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISOPLETH_MAP

 PURPOSE:
        Plots a 3-D (longitude, latitude, altitude) isopleth of
        a data concentration field atop a world map.

 CATEGORY:
        GAMAP Utilities

 CALLING SEQUENCE:
        ISOPLETH_3D

 INPUTS:
        DATA -> The data array to be plotted.  DATA must be
             3-dimensional.

        XMID, YMID, ZMID -> XMID is the array of longitude grid box
             centers.  YMID is the array of latitude grid box centers.  
             ZMID is the array of altitude grid box centers.  
             ISOPLETH_MAP will be able to label the X, Y, and Z axes
             based on the values of XMID, YMID, ZMID.

 KEYWORD PARAMETERS:
        ISOPLETH -> Value of data for which to show an iso-contour surface.  
             Default is 35.0 [ppbv].

        /LOW -> Set this keyword to display the low side of the iso-contour 
             surface (i.e., the contour surfaces enclose high data values). 
             If this keyword is omitted or is 0, the high side of the 
             contour surface is displayed and the contour encloses low
             data values. If this parameter is incorrectly specified,
             errors in shading will result.  

        TITLE1 -> First line of the title that is to be placed atop the plot
             window.  TITLE is passed explicitly to avoid keyword name
             duplication in the _EXTRA=e facility.  A default title
             string of "Volume Rendering" will be used if TITLE is not
             passed explicitly.
 
        TITLE2 -> Second line of the title string for the top of the plot
             window.  This line should be used for specifying the value
             and units of the isosurface.  A default string such as:
             "ISOSURFACE = 20.000 [ppbv]" will be created if TITLE2 is
             not passed explicitly.  Also, if TITLE2 is not passed 
             explicitly, the format descriptor string passed via the
             FORMAT keyword will be used to determine the number of
             decimal places 

        USTR -> String to specify the units of the isocontour surface
             (e.g. '[ppbv]', '[kg/s]', etc).  Default is a null
             string, ''.

        FORMAT -> Format descriptor string used in generating a default
             value of TITLE2.  Default is '(f14.3)'.

        MPARAM -> A 3 element vector containing values for
             [ P0Lat, P0Lon, Rot ], for the MAP_SET command.  
             Default is [ 0, 0, 0 ]. Elements not specified are 
             automatically set to zero.

        LIMIT -> A four-element vector which specifies the latitude
             and longitude extent of the map.  The elements of LIMIT
             are arranged thus: [ LatMin, LonMin, LatMax, LonMax ].
             Default is to set LIMIT = [ -90, -180, 90, 180 ] (i.e.
             to include the entire globe). P0Lon will be computed
             to fit into the LIMIT range unless it is explicitely
             requested in MParam.

        MCOLOR -> Color index of the map outline and title characters.
             Default is 1 (MYCT black).

        ACOLOR -> Color index of the 3-D axes which surround the map
             plot.  Defaults is 1 (MYCT black).

        [XYZ]MARGIN -> A 2-element array specifying the margin on
             the left (bottom) and right (top) sides of the plot
             window, in units of character size. Defaults are 
             XMARGIN=[ 5, 3 ], YMARGIN=[ 3, 3], ZMARGIN=[ 3, 3 ].
             These are used to put some "white space" into the plot
             window for aesthetic purposes.

        WINPARAM -> An integer vector with up to 5 elements:
             WINPARAM(0) = window number  (if negative, a window
                           will be opened with the /FREE option.
             WINPARAM(1) = X dimension of window in pixels (width)
             WINPARAM(2) = Y dimension of window in pixels (height)

 OUTPUTS:
        A picture will be displayed in the X-window device.

 SUBROUTINES:
        External Subroutines Required:
        ================================
        OPEN_DEVICE     CLOSE_DEVICE
        MULTIPANEL      MAP_LABELS
        TVIMAGE

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages

 NOTES:
        (1) Does not quite work for multi-panel plots, due to the 
            screen capturing done in the Z-buffer.  

        (2) Verified that the map and data coincide (bmy, 1/19/01)

 EXAMPLE:
      ISOPLETH_MAP, DATA, XMID, YMID, ZMID, $
         ISOPLETH=40, MPARAM=[0, 180, 0], MCOLOR=1, ACOLOR=1

             ; Will display a 35 [ppbv] isopleth with black
             ; map labels, lines, and axes.  MPARAM is set to
             ; accept longitude values (XMID) in the range of
             ; 0 - 360.  

 MODIFICATION HISTORY:
        bmy, 23 Jan 2001: GAMAP VERSION 1.47
                          - based on example code by David Fanning
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        phs, 17 Jul 2008: GAMAP VERSION 2.12
                          - Now set N_COLORS to !D.TBLE_SIZE 
        phs, 17 Jul 2008: GAMAP VERSION 2.13
                          - Bug fix: !D.TBLE_SIZE should be !D.TABLE_SIZE
        phs, 14 Oct 2009: - added AZ (so it is used for surface and
                            not map_set) and ZVALUE keywords
                          - added _EXTRA keyword to open_device for PS
                          - more control over TITLE2
        phs, 29 Oct 2009: GAMAP VERSION 2.14
                          - now draws the fram even if there is no
                            iso-surface

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/isopleth_map.pro)


ISPRINT (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISPRINT (function)

 PURPOSE:
        IDL analog to the 'isprint' routine in C.  Returns 1 if
        a character is a printable character (including space).

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISPRINT( S )

 INPUTS:
        S -> The string to be tested.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are printable.

 SUBROUTINES:
        None

 REQUIREMENTS:

 NOTES:
        Printing characters can be seen on the screen (these exclude
        control characters).

 EXAMPLE:
        print, isprint( '!X3d ' )
          1 1 1 1 0

        print, isprint( string( 9B ) )  ; horizontal tab
          0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998  - now use BYTE function in where statement
                            instead of hardwired constants
        bmy, 02 Jun 1998: VERSION 1.10
                          - now uses ISGRAPH
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isprint.pro)


ISSPACE (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISSPACE (function)

 PURPOSE:
        IDL analog to the 'isspace' routine in C.  Locates 
        white space characters in a string.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISSPACE( S ) 

 INPUTS:
        S  -> The string to be tested.  

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index 
             array that contains as many elements as S has 
             characters.  If S is a single character, then RESULT 
             will be scalar.  Where RESULT = 1, the corresponding 
             characters in S are numeric.

 SUBROUTINES:
        None

 REQUIREMENTS:

 NOTES:
        None

 EXAMPLES:
        PRINT, ISSPACE( '     ' )
            1 1 1 1 1

        PRINT, ISSPACE( 'A' )
            0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998: - now use BYTE function in where statement
                            instead of hardwired constants (where
                            possible)
        bmy, 02 Jun 1998: VERSION 1.10
                          - now can analyze an entire string 
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isspace.pro)


ISUPPER (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISUPPER (function)

 PURPOSE:
        IDL analog to the 'isupper' routine in C.  Locates all 
        uppercase alphabetic characters in a string.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISUPPER( S )

 INPUTS:
        S  -> The string to be tested

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Uppercase alphabetic characters in S are thus
                  denoted by the condition ( RESULT eq 1 ).

 SUBROUTINES:
        None

 REQUIREMENTS:
        Assumes that the ASCII character set is the character set
        installed on the system.  The byte values will be different
        for other character sets such as EBSDIC.  

 NOTES:
        None

 EXAMPLE:
        PRINT, ISUPPER( 'ABCDEFg' )
          1  1  1  1  1  1  0

        PRINT, ISUPPER( 'a' )
          0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998: VERSION 1.10
                          - now can analyze entire strings
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isupper.pro)


IS_DEFINED

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        IS_DEFINED

 PURPOSE:
        Tests if a program argument is defined (i.e. if it 
        was passed any value(s) from the calling program).

 CATEGORY:
        General

 CALLING SEQUENCE:
        RESULT = IS_DEFINED( ARG )

 INPUTS:
        ARG -> The argument to be tested.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1)
        PRINT, IS_DEFINED( ARG )
           0

             ; Because ARG has not been yet assigned a value,
             ; IS_DEFINED( ARG ) returns 0.
        
        (2)
        ARG = 1
        PRINT, IS_DEFINED( ARG )
           1

             ; Because ARG now has not been yet assigned a value,
             ; IS_DEFINED( ARG ) now returns 1.

 MODIFICATION HISTORY:
  D.Fanning, 02 Jul 1998: INITIAL VERSION
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments, cosmetic changes


(See /n/home09/ryantosca/IDL/gamap2/general/is_defined.pro)


IS_DIR (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	 IS_DIR (function)

 PURPOSE:
	 Tests if a directory exists

 CATEGORY:
	 File & I/O

 CALLING SEQUENCE:
	 RESULT = IS_DIR( PATH )

 INPUTS:
        PATH -> The variable to be tested.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> =1 if directory exists, =0 otherwise

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
	 PRINT, IS_DIR( '~/IDL/tools/' )
           1

	      ; Test the existence of the ~/IDL/tools directory.

 MODIFICATION HISTORY:
    R.Bauer, 26 Jan 1999: INITIAL VERSION
                          - from Forschungszentrum Juelich GmbH ICG-1
        bmy, 24 May 2007: TOOLS VERSION 2.06
                          - updated comments
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/is_dir.pro)


IS_SELECTED (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        IS_SELECTED (function)

 PURPOSE:
        Return a boolean vector with 1 for each element of VAR
        that is contained in SELECTION. This is a generalization
        of WHERE(VAR eq value) in that value can be an array
        instead of a single value.

 CATEGORY:
        General

 CALLING SEQUENCE:
        INDEX = IS_SELECTED(VAR,SELECTION)

 INPUTS:
        VAR -> The data vector

        SELECTION -> A vector with chosen values. If no selection
            is given, the function returns a vector with all entries
            set to zero.

 KEYWORD PARAMETERS:
        none

 OUTPUTS:
        INDEX -> An integer vector of length n_elements(VAR) 
             that contains 1 for each element of VAR that has
             one of the SELECTION values.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1)
        A = [ 1, 1, 1, 2, 2, 3 ]
        B = [ 2, 3 ]
        PRINT, IS_SELECTED( A, B )
           0 0 0 1 1 1

        (2)
        PRINT, WHERE( IS_SELECTED( A, B ) )
           3 4 5

        ; (i.e. indices of A that correspond to a value of 2 or 3)
        ; equivalent to:
        print,where(A eq 2 or A eq 3)

 MODIFICATION HISTORY:
        mgs, 19 Aug 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/is_selected.pro)


JPEG2PS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        JPEG2PS

 PURPOSE:
        Translates JPEG images to PostScript format.

 CATEGORY:
        Graphics

 CALLING SEQUENCE:
        JPEG2PS [, FILENAME [, Keywords ] ]

 INPUTS:
        FILENAME (optional) -> Name of the input JPEG file.  
             If FILENAME is omitted then JPEG2PS will prompt
             the user to supply a file name via a dialog box.
             FILENAME may contain wild card characters.

 KEYWORD PARAMETERS:
        OUTFILENAME -> Name of the output PostScript file.
             Default is "idl.ps".

        /FLIP_BW -> Set this keyword to turn black pixels into
             white pixels and vice-versa.  This is useful for
             creating PostScript files of JPEG images that have a 
             dark background color. 

        XOFFSET, YOFFSET (optional) -> Set these keywords to specify
             the X and Y Margins in inches.  Defaults are 
             XMARGIN = 0.5 inches and YMARGIN = 0.5 inches.
 
        _EXTRA=e -> Picks up extra keywords for OPEN_DEVICE,
             TVIMAGE, and CLOSE_DEVICE.

 OUTPUTS:
        Sends output to a PostScript file, whose name is given
        by the OUTFILENAME keyword.

 SUBROUTINES:
        External subroutines required:
        ------------------------------
        EXTRACT_FILEPATH (function)
        DIALOG_PICKFILE  (function)
        TVIMAGE

 REQUIREMENTS:
        References routines from the TOOLS package.

 NOTES:
        (1) Image processing options are limited to flipping the
            black and white pixels.  This should be good enough
            for most purposes.

        (2) XMARGIN and YMARGIN assume that we are printing out for
            standard USA 8.5 x 11" page.  Device sizes listed below
            are also in inches. 
 
        (3) Refer to the READ_JPEG procedure manual pages for
            JPEG image handling options. 

 EXAMPLE:
        (1)
        JPEG2PS, 'my_jpg.jpg', OUTFILENAME='my_ps.ps'

             ; Translates the image in "my_jpg.jpg" to 
             ; the PostScript file "my_ps.ps".

        (2)
        JPEG2PS, 'my_jpg.jpg', OUTFILENAME='my_ps.ps', /FLIP_BW
        
             ; Same as in (1), but also changes all black
             ; pixels to white and vice-versa.  

        (3)
        JPEG2PS, 'my_jpg.jpg', OUTFILENAME='my_ps.ps', /FLIP_BW, $
             XMARGIN=0.5, YMARGIN=0.5
        
             ; Same as in (2), but also will "pad" the image with
             ; 0.5" of white space around each side.

 MODIFICATION HISTORY:
        bmy, 28 Jan 2000: VERSION 1.45
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/graphics/jpeg2ps.pro)


JV_DIFF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        JV_DIFF

 PURPOSE:
        Creates difference (new - old) plots of J-values at both the
        surface and 500 hPa. 
       
 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        JV_DIFF, FILES, LEVELS, TAUS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "old" and "new" GEOS-Chem model versions
             that are to be compared. 

        LEVELS -> A 4-element vector containing the level indices
             for the GEOS-Chem surface layer and 500 hPa layer.
             for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
             NOTE: This is in Fortran notation (starting from 1!)

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        VERSIONS -> A 2-element vector containing the version
             numbers for the "old" and "new" GEOS-Chem model
             versions.

 KEYWORD PARAMETERS:
        /DYNRANGE -> Set this switch to create plots using the whole
             dynamic range of the data.  Default is to restrict
             the plot range to +/- 5%.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output
             to a file whose name is specified by this keyword.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==================================================
        PlotJVDiff

        External Subroutines Required:
        ==================================================
        CLOSE_DEVICE          COLORBAR_NDIV    (function)
        CTM_GET_DATA          EXTRACT_FILENAME (function)       
        GETMODELANDGRIDINFO   MULTIPANEL         
        MYCT                  OPEN_DEVICE   
        TVMAP  

 REQUIREMENTS:
        References routines from the GAMAP package.

 NOTES:
        (1) Meant to be called from BENCHMARK_1MON

 EXAMPLE:
        FILES    = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
        LEVELS   = [ 1, 1, 13, 13 ]
        TAUS     = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
        VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
 
        JV_DIFF, FILES, LEVELS, TAUS, VERSIONS, $
             /PS, OUTFILENAME='myplot.ps'

             ; Creates J-value difference plots [ v7-04-11 - v7-04-10 ]
             ; for July 2001 at the surface and 500 hPa.
             ; The max & min of the data will be fixed at +/- 5%.

        JV_DIFF, FILES, LEVELS, TAUS, VERSIONS, $
             /DYNRANGE, /PS, OUTFILENAME='myplot.ps'

             ; Same as above, but this time the full dynamic
             ; range of the data will be displayed.

 MODIFICATION HISTORY:
        mps, 02 Dec 2013: - Initial version, based on jv_ratios.pro
  mps & bmy, 29 May 2014: GAMAP VERSION 2.18
                          - Compatible with extra J-Value tracers
                            in v10-01c and higher versions
 

(See /n/home09/ryantosca/IDL/gamap2/benchmark/jv_diff.pro)


JV_MAP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        JV_MAP

 PURPOSE:
        Creates plots of J-values at both the surface and 500 hPa. 
       
 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        JV_MAP, FILE, LEVELS, TAU, VERSION, [, Keywords ]

 INPUTS:
        FILE -> The name of the file containing data to be plotted.

        LEVELS -> A 4-element vector containing the level indices
             for the GEOS-Chem surface layer and 500 hPa layer.
             for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
             NOTE: This is in Fortran notation (starting from 1!)

        TAU -> The TAU value (hours GMT from /1/1985) corresponding
             to the data to be plotted.

        VERSION -> The model version number corresponding to the
             data to be plotted.

 KEYWORD PARAMETERS:
        /DYNRANGE -> Set this switch to create plots using the whole
             dynamic range of the data.  Default is to restrict
             the plot range to +/- 5%.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output
             to a file whose name is specified by this keyword.

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Required:
        ==================================================
        PlotJVMap

        External Subroutines Required:
        ==================================================
        CLOSE_DEVICE          COLORBAR_NDIV    (function)
        CTM_GET_DATA          EXTRACT_FILENAME (function)       
        GETMODELANDGRIDINFO   MULTIPANEL         
        MYCT                  OPEN_DEVICE   
        TVMAP  

 REQUIREMENTS:
        References routines from the GAMAP package.

 NOTES:
        (1) Meant to be called from BENCHMARK_1MON

 EXAMPLE:
        FILE     = 'ctm.bpch.v10-01i'
        LEVELS   = [ 1, 1, 13, 13 ]
        TAUS     = NYMD2TAU( 20130701 )
        VERSIONS = 'v10-01i'
 
        JV_MAP, FILES, LEVELS, TAUS, VERSIONS, $
             /PS, OUTFILENAME='myplot.ps'

             ; Creates J-value plots for v10-01i for July 2013
             ; at the surface and 500 hPa.
             ; The max & min of the data will be fixed at +/- 5%.

        JV_MAP, FILE, LEVELS, TAU, VERSION, $
             /DYNRANGE, /PS, OUTFILENAME='myplot.ps'

             ; Same as above, but this time the full dynamic
             ; range of the data will be displayed.

 MODIFICATION HISTORY:
        mps, 19 Apr 2014: VERSION 1.01
                          - Adapted from jv_ratio.pro
  mps & bmy, 29 May 2014: GAMAP VERSION 2.18
                          - Compatible with extra J-Value tracers
                            in v10-01c and higher versions
 

(See /n/home09/ryantosca/IDL/gamap2/benchmark/jv_map.pro)


JV_RATIO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        JV_RATIO

 PURPOSE:
        Creates ratio (new/old) plots of J-values at both the surface
        and 500 hPa. 
       
 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        JV_RATIO, FILES, LEVELS, TAUS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "old" and "new" GEOS-Chem model versions
             that are to be compared. 

        LEVELS -> A 4-element vector containing the level indices
             for the GEOS-Chem surface layer and 500 hPa layer.
             for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
             NOTE: This is in Fortran notation (starting from 1!)

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        VERSIONS -> A 2-element vector containing the version
             numbers for the "old" and "new" GEOS-Chem model
             versions.

 KEYWORD PARAMETERS:
        /DYNRANGE -> Set this switch to create plots using the whole
             dynamic range of the data.  Default is to restrict
             the plot range to +/- 5%.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output
             to a file whose name is specified by this keyword.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==================================================
        ComputeJVRatios       PlotJVRatios

        External Subroutines Required:
        ==================================================
        CLOSE_DEVICE          COLORBAR_NDIV    (function)
        CTM_GET_DATA          EXTRACT_FILENAME (function)       
        GETMODELANDGRIDINFO   MULTIPANEL         
        MYCT                  OPEN_DEVICE   
        TVMAP  

 REQUIREMENTS:
        References routines from the GAMAP package.

 NOTES:
        (1) Meant to be called from BENCHMARK_1MON

 EXAMPLE:
        FILES    = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
        LEVELS   = [ 1, 1, 13, 13 ]
        TAUS     = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
        VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
 
        JV_RATIO, FILES, LEVELS, TAUS, VERSIONS, $
             /PS, OUTFILENAME='myplot.ps'

             ; Creates J-value ratio plots [ v7-04-11 / v7-04-10 ]
             ; for July 2001 at the surface and 500 hPa.
             ; The max & min of the data will be fixed at +/- 5%.

        JV_RATIO, FILES, LEVELS, TAUS, VERSIONS, $
             /DYNRANGE, /PS, OUTFILENAME='myplot.ps'

             ; Same as above, but this time the full dynamic
             ; range of the data will be displayed.

 MODIFICATION HISTORY:
        bmy, 14 Aug 2002: VERSION 1.01
                          - Adapted from Isabelle Bey's "cat_plot.pro"
                          - you may now specify different TAU values
        bmy, 13 Sep 2002: VERSION 1.02
                            for FILENEW and FILEOLD via the TAU0 keyword
        bmy, 04 Oct 2004: VERSION 1.03
                          - Remove MIN_VALID from call to TVMAP
        bmy, 09 Nov 2007: VERSION 1.04
                          - Modified argument list and some 
                            internal variable names.
        bmy, 20 Nov 2007: VERSION 1.05
                          - Now draw out-of-bounds triangles for
                            the colorbar when using the "small"
                            data ranges.  New feature of TVMAP.
        bmy, 07 May 2008: VERSION 1.06
                          - Now allow for comparing models on 2
                            different vertical grids.
        bmy, 08 Feb 2011: VERSION 1.07
                          - Now display in the top-of-plot title
                            if the dynamic range option is used.
        bmy, 08 Jun 2011: VERSION 1.08
                          - Now create log plots in range 0.5 - 2.0
                          - Added /DO_FULLCHEM keyword
                          - Adjust colorbar so that the 0.9 - 1.1
                            range shows up in white.
                          - Now restore !MYCT sysvar to previous
                            settings upon exiting the program
  mps & bmy, 29 May 2014: GAMAP VERSION 2.18
                          - Compatible with extra J-Value tracers
                            in v10-01c and higher versions; 

(See /n/home09/ryantosca/IDL/gamap2/benchmark/jv_ratio.pro)


KNMHC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        KNMHC

 PURPOSE:
        Returns an array of reaction rates for various non-methane 
        hydrocarbon reactions as a function of temperature and pressure.

        NOTE: Reaction rates may need updating to the latest JPL dataset.

 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        RESULT = KNMHC( T, P [, Keywords ] )

 INPUTS:
        T -> Temperature in [K].

        P -> Pressure in [hPa].

 KEYWORD PARAMETERS:
        NAMES -> Returns to the calling program a list of the names
             for the various chemical species 

 OUTPUTS:
        RESULT -> An array of rate constants corresponding to
             the species contained in NAMES.
        

 SUBROUTINES:
        External Subroutines Required:
        ================================
        KTROE (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) This should probably be rewritten to return a structure.
        (2) Definitely needs updating of rate constants.

 EXAMPLE:
        RESULT = KNMHC( 300, 1000, NAMES=NAMES  )
        PRINT, NAMES
          CO CH4 C2H2 C2H4 C2H6 C3H6 C3H8 i-BUT CH3CL
        PRINT, RESULT
          2.40000e-13  6.60071e-15  7.55980e-13  8.14644e-12  
          2.45774e-13  5.08118e-11  1.10803e-12  2.34511e-12
          3.76143e-14

             ; Compute rate constants for 300K and 1000hPa pressure

 MODIFICATION HISTORY:
        mgs, 1998?        INITIAL VERSION
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - added std doc header
                          - updated comments, cosmetic changes

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/knmhc.pro)


KTROE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        KTROE

 PURPOSE:
        compute reaction rate coefficient for a 3rd order reaction
        using Troe's formula as given in JPL97-4

 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        k=KTROE(T,p,k0300,n,kinf300,m [,keywords])

 INPUTS:
        T --> temperature in K

        p --> pressure in mbars

        k0300, n --> constants to get k0(T)  { see JPL97,table 2 }

        kinf300, m --> constants to get kinf(T)  { see JPL97,table 2 }

 KEYWORD PARAMETERS:
        k0, kinf, fc --> will return individual terms of the Troe expression

 OUTPUTS:
        K -> a rate coefficient

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        no error checking is done except for the correct 
        number of arguments

 EXAMPLE:

 MODIFICATION HISTORY:
        mgs, 20 Mar 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/ktroe.pro)


LEGEND

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        LEGEND

 PURPOSE:
        Annotate a plot with a legend.  Make it as simple as possible
        for the user.

 CATEGORY:
        Plotting

 CALLING SEQUENCE:
        LEGEND, [several keywords]

 INPUTS:

 KEYWORD PARAMETERS:
        HALIGN, VALIGN -> horizontal and vertical alignment of legend 
             with respect to plot window. Ranges from 0 to 1, and is 
             interpreted "dynamically": e.g. a value of 0.3 places 
             30% of the box left (below) 0.3*plotwindow size.
             Defaults are 0.98 and 0.03, i.e. the lower right corner.

        WIDTH -> width of the legend box. This parameter is defaulted
             to 40% of the plot area or may be adjusted to hold the
             longest LABEL string if CHARSIZE is given. If WIDTH is
             specified, it is used to determine the CHARSIZE. However,
             if both are given, they are both used and may lead to
             ugly results.

        POSITION -> a four element vector that gives complete control
             over the position of the legend box. Normally, you don't 
             need this keyword, but it may be handy in a multi-plot 
             situation where you want to place a legend independently
             of any individual plotting area. It can also be convenient 
             if you want to place legends interactively: simply call
             a rubberband program that returns the region coordinates 
             in normalized units, and pass this vector to the LEGEND 
             program.

        PLOTPOSITION -> 4 element vector that specifies the plotting 
             area.  Default is taken from !P.POSITION if set, otherwise 
             [0.2,0.1,0.9,0.9] is used as default. As noted above, 
             sizing and positioning of the legend box is with respect 
             to the plot position unless POSITION is specified.

        SYMBOL -> a vector (or one integer) containing symbol numbers 
             to plot. -1 can be used to skip one entry.  These values 
             are arguments to the SYM() function. If you like to
             label plain IDL symbols, use the PSYM keyword instead.
 
        PSYM -> same as symbol, but passes its values directly to PSYM
             in the plots command, i.e. produces generic IDL symbols.

        SYMSIZE -> symbol size. Normally, this value is adjusted auto-
             matically to match the character size. 
        
        COLOR -> a number or vector of color values for the symbols. 
             One entry is used per symbol. If only one entry is 
             provided, all symbols are plotted in the same color. 
             Default is black.

        LINE -> a vector with linestyles. Symbols and lines can be 
             used together. Entries with -1 are skipped.

        LCOLOR -> color values for the lines

        THICK -> line thickness. Can be any number of element. The
                 program cycles through them if there is more lines
                 than elements in THICK. Defaut is 1 for all. 

        LABEL -> a string array containing the legend text lines. 
             One line should correspond to one symbol. If you have a 
             two line entry, you can either pass it as two lines or
             use the '!C' carriage return command. In both cases you 
             have to set the SYMBOL and LINE values that correspond
             to the second line to -1 in order to skip the symbol for 
             it. If you use '!C', your next LABEL should be blank.

        TEXTCOLOR -> A color value for the label and title output.
             Default is black.

        TITLE -> a title string for the legend. 

        CHARSIZE -> character size for all labelling. Default is to 
             determine the character size automatically so that the largest
             LABEL and TITLE fit into the legend box. On the other hand you
             can specify CHARSIZE and have the legend size itself. 

        SPACING -> spacing between legend lines. Default is 2, lower values
             produce narrower spacing and may be useful for extensive 
             legends. You can set the IDL default line spacing by setting
             SPACING to float(!D.Y_CH_SIZE)/!D.X_CH_SIZE.

        NLINES -> number of lines the legend box shall hold. Normally,
             this value is determined automatically from the maximum number
             of entries in SYMBOL, PSYM, LINE, and LABEL. It may however
             be useful to set NLINES manually if you want to ADD extra
             curve identifiers lateron (see ADD keyword), or if your
             last LABEL is a multi line entry (using the '!C' character).

        FRAME -> draw a frame around the legend box. The value of FRAME
             is equal to the color index that will be used to draw the
             FRAME (hence /FRAME draws a black frame with MYCT).

        BOXCOLOR -> a background fill color for the legend box. Default is
             0 (which corresponds to white in MYCT). If you specify a
             negative number, no background box is drawn and your legend 
             may interfere with part of the plot.

        ADD -> set this keyword to add one or more entries to an existing 
             legend. All positioning and size keywords are ignored in this
             case, and the new entries are appended at the bottom. You 
             should use the NLINES keyword in the first call to legend in
             order to properly size your legend box, or (if you draw
             no FRAME and have a neutral BOXCOLOR) you can set VALIGN to 
             e.g. 0.98 to start from the top of the plotting area. 
             Technical NOTE: adding entries to an existing legend is 
             most flexible with the use of the LEGSTRU keyword which will
             return a structure with all necessary parameters to continue
             labelling at the next call. It is also accomplished by means 
             of a common block to facilitate its use. In this case, you can
             only continue the legend you last worked on. 

        LEGSTRU -> a named variable that will contain information to
             continue labelling with the /ADD keyword. Needs to be passed
             back into LEGEND if it shall be used. Otherwise, information
             is taken from a common block.

 OUTPUTS:
        None

 SUBROUTINES:
        DRAWLEGSYM : plots a single plot symbol and line.

 REQUIREMENTS:
        LEGEND uses the STR_SIZE function by David Fanning 
        and FORMSTRLEN to determine "true" size of label strings.
        If ADD keyword is used, you also need CHKSTRU.

        A plot must have been produced prior to calling LEGEND

 NOTES:
        A few color statements require MYCT in the present form
        of this program. See definitions of variables Black and
        White at the beginning of the program.

 EXAMPLES:
        (1) 
        PLOT, FINDGEN(60),              $
              SIN(FINDGEN(60)*!PI/15.), $
              COLOR=!MYCT.BLACK

        LEGEND, SYMBOL=[1,2,3], $
                LABEL=['Curve A','Curve B','Curve C']

             ; Plot a simple data curve and produce 
             ; legend at lower right corner


        (2)
        LEGEND, SYMBOL=[4,5,6],                        $
                LABEL=['Curve D','Curve E','Curve F'], $
                HALIGN=0.5,                            $
                VALIGN=0.98,                           $
                BOXCOLOR=-1,                           $
                CHARSIZE=1.2

             ; Place legend at center of x and at top of y, don't 
             ; draw a background box, write the labels with charsize 
             ; 1.2 and size the legend box automatically


        (4) 
        LEGEND, SYMBOL=[1,-1,6,-1,2,-1],      $
                LINE=[-1,0,-1,2,-1,3],        $
                COLOR=[1,1,2,2,3,3],          $
                LCOLOR=[1,1,2,2,3,3],         $
                LABEL=['PEM-West A','model',  $
                       'PEM-West B','model',  $
                        'TRACE-A','model'],   $
                NLINES=8,                     $
                FRAME=1,                      $
                BOXCOLOR=5,                   $
                TITLE='GTE missions',         $
                HALIGN=0.1,                   $
                VALIGN=0.06,                  $
                CHARSIZE=1.2

              ; Draw a legend on a yellow background.  It has 6
              ; entries but leaves room for 2 more lines which 
              ; will be filled later.  Use different colors for 
              ; symbols and lines. Symbols and lines are alternating.
              ; Draw a frame around legend and add a title.

        (5)
        LEGEND, SYMBOL=[4,-1],                   $
                LINE=[-1,4],                     $
                COLOR=4,                         $
                LCOLOR=4,                        $
                LABEL=['PEM-Tropics A','model'], $ 
                /ADD
 
             ; Now add two extra entries to the last legend
             ; (This will use the structure stored in the 
             ; common block)
             ;
             ; To make use of the more flexible "widget-proof" 
             ; structure, simply add legstru=legstru to the last
             ; two calls.


        (6)
        !P.POSITION = [0.6,0.5,0.93,0.93] 
        RECTANGLE, !P.POSITION, XBOX, YBOX     ; Get rectangle coordinates
        POLYFILL, XBOX, YBOX, /NORM, COLOR=0   ; Clear rectangle

        PLOT, FINDGEN(60), SIN(FINDGEN(60)*!PI/15.),$
             COLOR=!MYCT.BLACK, /NOERASE

        LEGEND, SYMBOL=[1,2,3],$
                LABEL=['Curve A','Curve B','Curve C']

        !P.POSITION = 0                        ; reset !p.position

             ; Produce an inset plot positioned via !P.POSITION 
             ; and add a legend.  The same effect can be reached 
             ; by passing the position=[..] parameter to the plot 
             ; command and the same vector as PLOTPOSITION to legend.

 MODIFICATION HISTORY:
        mgs, 23 Jun 1998: VERSION 1.00
        mgs, 24 Jun 1998: - now uses !X.Window and !Y.Window to get
               default size of the plotting window (thanks DWF)
        mgs, 25 Jun 1998: - added THICK keyword
        mgs, 27 Oct 1998: - more room for lines
                          - now uses formstrlen instead of strlen
        mgs, 28 Nov 1998: - box width not incremented by 1 if plotmode=0
        mgs, 25 Jun 1999: - added TEXTCOLOR keyword
  dbm & bmy, 23 Aug 2005: TOOLS VERSION 2.04
                          - now pass _EXTRA=e to XYOUTS 
                          - cosmetic changes
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments
        phs, 23 Apr 2007: GAMAP VERSION 2.13
                          - fixes for various Thickness

(See /n/home09/ryantosca/IDL/gamap2/plotting/legend.pro)


LITTLE_ENDIAN (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        LITTLE_ENDIAN (function)

 PURPOSE:
        Determines if the computer system on which we are 
        running IDL has little-endian byte ordering.

 CATEGORY:
        General

 CALLING SEQUENCE:
        RESULT = LITTLE_ENDIAN

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> Returns 1 if the machine on which you  are running IDL
             is a little endian machine, or 0 otherwise.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        PRINT, LITTLE_ENDIAN
           1
    
             ; Returns 1 if we are running IDL on a 
             ; little-endian  machine, or zero otherwise

 MODIFICATION HISTORY:
  R.Mallozi, 02 Jul 1998: INITIAL VERSION
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/little_endian.pro)


LOCALTIME

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        LOCALTIME

 PURPOSE:
        Returns the local time at a particular location, given the
        Universal Time (aka Greenwich Time) and longitude.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = LOCALTIME( UTC, LON )

 INPUTS:
        UTC -> Universal Time (aka Greenwich Time) in hours.
             UTC may be either a scalar or a vector.

        LON -> Longitude in degrees.  LON may be in the range
             -180..180 or 0..360.  LON may be either a scalar
             or a vector.

 KEYWORD PARAMETERS:
        /DOUBLE -> Set this switch to return local time in
             double precision.  Default is to return local time
             in single precision.
            
 OUTPUTS:
        RESULT -> The local time corresponding to UTC and LON.
             If UTC and LON are vectors, then RESULT will also
             be a vector of local times.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1)
        PRINT, LOCALTIME( 0, -71.06 )
          19.2627

             ; Returns the local time (approx 19.26 decimal, which
             ; is approx 19:15 PM) at Boston (lon=71.06W) when
             ; it is 00:00 UTC.

        (2)
        PRINT, LOCALTIME( 0, -71.06, /DOUBLE )
          19.262667

             ; Same as Example (1), but returns local time
             ; as double precision.
 
        (3) 
        PRINT, LOCALTIME( [0,1,2], -71.06, /DOUBLE )
             19.262667   20.262667   21.262667

             ; Returns the local times at Boston (as in 
             ; Examples (1) and (2)) when it is 00:00, 01:00,
             ; and 02:00 UTC time.

 MODIFICATION HISTORY:
        dbm, 30 Jul 2007: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/date_time/localtime.pro)


LOGLEVELS (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        LOGLEVELS (function)

 PURPOSE:
        Compute default values for logarithmic axis labeling or 
        contour levels. For a range from 1 to 100 these would be 
        1., 2., 5., 10., 20., 50., 100.  If the range spans more 
        than (usually) 3 decades, only decadal values will be
        returned unless the /FINE keyword is set.

 CATEGORY:
        Plotting

 CALLING SEQUENCE:
        RESULT = LOGLEVELS( [ RANGE | MIN=MIN, MAX=MAX ] $
                            [,/FINE ] [ ,COARSE=DEC ] )

 INPUTS:
        RANGE -> A 2-element vector with the minimum and maximum 
            value to be returned. Only levels _within_ this range
            will be returned. If RANGE contains only one element,
            this is interpreted as MAX and MIN will be assumed as
            3 decades smaller. RANGE superseeds the MIN and MAX 
            keywords. Note that RANGE must be positive definite
            but can be given in descending order in which case
            the labels will be reversed.

 KEYWORD PARAMETERS:
        MIN, MAX -> alternative way of specifying a RANGE. If only 
            one keyword is given, the other one is computed as
            3 decades smaller/larger than the given parameter.
            RANGE superseeds MIN and MAX.

        /FINE -> always return finer levels (1,2,5,...) 

        COARSE -> the maximum number of decades for which LOGLEVELS
            shall return fine labels. Default is 3. (non-integer 
            values are possible).

 OUTPUTS:
        RESULT -> A vector with "round" logarithmic values within 
            the given range.  The original (or modified) RANGE will
            be returned unchanged if RANGE does not span at least 
            one label interval.  The result will always contain at 
            least two elements.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        If COARSE is lt 0, the nearest decades will be returned 
        instead. The result will always have at least two elements.
        If COARSE forces decades, the result values may be out-of-
        range if RANGE spans less than a decade.
        
        Caution with type conversion from FLOAT to DOUBLE !!

 EXAMPLE:
        RANGE   = [ MIN( DATA, MAX=M ), M ]
        C_LEVEL = LOGLEVELS( RANGE )
        CONTOUR, ..., C_LEVEL=C_LEVEL

             ; Define log levels for the CONTOUR command
        
 MODIFICATION HISTORY:
        mgs, 17 Mar 1999: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/plotting/loglevels.pro)


LOOP

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        LOOP

 PURPOSE:
        This routine provides a wrapper for function calls that accept
        only scalars so that they can operate on arrays.

 CATEGORY:
        General

 CALLING SEQUENCE:
        RESULT = LOOP( name, arg, p1, p2, p3, p4)

 INPUTS:
        NAME -> the name of the function (string)

        ARG -> the argument (array)

        P1 .. P4 -> optional function parameters 

 KEYWORD PARAMETERS:
        Unfortunately None. Would be nice if _EXTRA would work.

 OUTPUTS:
        RESULT -> Vector with the same number of elements as ARG.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        A  = [ 0.05, 0.01, 0.001 ]
        PRINT, LOOP( "CHISQR_CVF", A, 17 )
          27.5871   33.4087   40.7903

             ; Define a vector of arguments and then then loop
             ; thru the vector, calling CHISQR_CVF each time.
             ; Then display the vector of results.

 MODIFICATION HISTORY:
        mgs, 05 Dec 1997: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/loop.pro)


MAKE_CH_DATA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAKE_CH_DATA

 PURPOSE:
        Driver program for CREATE_NESTED_DATA.  Hardwired to 
        the North-America nested-grid of Qinbin Li.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        MAKE_CH_DATA

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        MFINDFILE         (function)
        EXTRACT_FILENAME  (function)
        CREATE_NESTED_MET

 REQUIREMENTS:
        None

 NOTES:
        For simplicity, input & output dirs, and X and Y
        ranges have been hardwired.  Change as necessary.

 EXAMPLE:
        MAKE_CH_MET

 MODIFICATION HISTORY:
        bmy, 10 Apr 2003: VERSION 1.00
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/make_ch_data.pro)


MAKE_CH_MET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAKE_CH_MET

 PURPOSE:
        Driver program for CREATE_NESTED_MET.  Hardwired to 
        the China/SE Asia nested-grid of Yuxuan Wang.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        MAKE_CH_MET [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        MONYR -> Specifies the month & year (e.g. '2001/06/' )

        FMASK -> File mask (default is '*') 

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        MFINDFILE         (function)
        EXTRACT_FILENAME  (function)
        CREATE_NESTED_MET

 REQUIREMENTS:
        None

 NOTES:
        For simplicity, input & output dirs, and X and Y
        ranges have been hardwired.  Change as necessary.

 EXAMPLE:
        MAKE_NA_MET

 MODIFICATION HISTORY:
        bmy, 10 Apr 2003: VERSION 1.00
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/make_ch_met.pro)


MAKE_EUR_DATA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAKE_EUR_DATA

 PURPOSE:
        Driver program for CREATE_NESTED_DATA.  Hardwired to 
        the North-America nested-grid of Qinbin Li.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        MAKE_EUR_DATA

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        MFINDFILE         (function)
        EXTRACT_FILENAME  (function)
        CREATE_NESTED_MET

 REQUIREMENTS:

 NOTES:
        For simplicity, input & output dirs, and X and Y
        ranges have been hardwired.  Change as necessary.

 EXAMPLE:
        MAKE_EUR_DATA

 MODIFICATION HISTORY:
        bmy, 15 May 2003: VERSION 1.00
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/make_eur_data.pro)


MAKE_EUR_MET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAKE_EUR_MET

 PURPOSE:
        Driver program for CREATE_NESTED_MET.  Hardwired to 
        the European nested-grid of Isabelle Bey.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        MAKE_EUR_MET

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        MFINDFILE         (function)
        EXTRACT_FILENAME  (function)
        CREATE_NESTED_MET

 REQUIREMENTS:
        None

 NOTES:
        For simplicity, input & output dirs, and X and Y
        ranges have been hardwired.  Change as necessary.

 EXAMPLE:
        MAKE_EUR_MET

 MODIFICATION HISTORY:
        bmy, 10 Apr 2003: VERSION 1.00
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/make_eur_met.pro)


MAKE_MULTI_NC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAKE_MULTI_NC

 PURPOSE:
        Convert bpch files (matching a mask) to netCDF format. 
        The routine can work recursively : files in subdirectories
        are also searched for.
        
        This is a convenient generic wrapper for GAMAP routine
        Bpch2coards.pro, to work on several files and directories at
        once.
        
        When working recursively, the directory tree in the input
        directory is recreated as needed in the output directory.

 CATEGORY:
        File & I/O, BPCH Format, Scientific Data Formats

 CALLING SEQUENCE:
        MAKE_MULTI_NC

 INPUTS:
        none

 KEYWORD PARAMETERS:
        MASK -> string, default is '*', that is all files

        INPUT_PARENT_DIR -> top directory of files to convert, if
             not specified, a dialog window pops up

        OUTPUT_PARENT_DIR -> top directory destination for netCDF
             files, if not specified, a dialog window pops up.

        RECURSION -> to search subdirectories. Default is 0
             (OFF). Set to 1 to turn it on.

        TOKEN -> set if you want to replace 'bpch' with 'nc' in all
             part of the full name. Default is to have extension
            ".nc" added to file name only.

 OUTPUTS:
        None

 REQUIREMENTS:
        References routines from the GAMAP package.

 NOTES:
        To work recursively on the directories, I use FILE_SEARCH
        with 2 arguments. This is not possible with MFINDFILE, and
        works only with IDL 5.5 and above. 

 EXAMPLES:

        indir  = '/as/data/geos/GEOS_1x1/EDGAR_200607/'         
        outdir = '/home/phs/data/EDGAR_200607/nc/'             
        mask   = '*1x1'                                          
        make_multi_nc, input_parent_dir=indir, out=outdir, mask=mask, /r

 MODIFICATION HISTORY:

       Thu Oct 29 16:40:28 2009, Philippe Le Sager
       

		now pass _extra keyword to BPCH2COARDS (eg /NAMER
		needed for nested data)

       Thu Feb 19 11:12:16 2009, Philippe Le Sager
       

               renamed MAKE_MULTI_NC. Added recursion keyword
               (default is OFF). Now **AUTOMATICALLY** creates missing
               subdirectory in output directory tree, when in
               recursive mode.

       Tue Jan 27 10:40:49 2009, Philippe Le Sager
       

		v1, based on make_c_nc.pro to work on several
		directories at once.

        bmy, 30 Nov 2010: GAMAP VERSION 2.15
                          - Updated comments and category in header
        bmy, 01 Feb 2012: GAMAP VERSION 2.16
                          - Skip processing ASCII text files
        mps, 04 Mar 2015: - Bug fix: Now assign InFileName before checking
                            file type
        

(See /n/home09/ryantosca/IDL/gamap2/file_io/make_multi_nc.pro)


MAKE_NA_DATA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAKE_NA_DATA

 PURPOSE:
        Driver program for CREATE_NESTED_DATA.  Hardwired to 
        the North-America nested-grid of Qinbin Li.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        MAKE_NA_DATA

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        MFINDFILE         (function)
        EXTRACT_FILENAME  (function)
        CREATE_NESTED_MET

 REQUIREMENTS:
        None

 NOTES:
        For simplicity, input & output dirs, and X and Y
        ranges have been hardwired.  Change as necessary.

 EXAMPLE:
        MAKE_NA_MET

 MODIFICATION HISTORY:
        bmy, 10 Apr 2003: VERSION 1.00
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/make_na_data.pro)


MAKE_NA_MET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAKE_NA_MET

 PURPOSE:
        Driver program for CREATE_NESTED_MET.  Hardwired to 
        the North-America nested-grid of Qinbin Li.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        MAKE_NA_MET

 INPUTS:
        None

 KEYWORD PARAMETERS:
        MONYR -> Specifies the month & year (e.g. '2001/06/' )

        FMASK -> File mask (default is '*') 

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        MFINDFILE         (function)
        EXTRACT_FILENAME  (function)
        CREATE_NESTED_MET

 REQUIREMENTS:
        None

 NOTES:
        For simplicity, input & output dirs, and X and Y
        ranges have been hardwired.  Change as necessary.

 EXAMPLE:
        MAKE_NA_MET

 MODIFICATION HISTORY:
        bmy, 10 Apr 2003: VERSION 1.00
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/make_na_met.pro)


MAKE_NC_RECURSIVE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAKE_NC_RECURSIVE

 PURPOSE:
        Converts files matching a mask to netCDF format. 
        The routine works recursively. This is a convenience 
        wrapper for GAMAP routine bpch2coards.pro, to work on 
        several directories at once.

        You just need to (1) create the same directory tree in the
        output location, then (2) run the routine once.

 CATEGORY:
        File & I/O, BPCH Format, Scientific Data Formats

 CALLING SEQUENCE:
        MAKE_NC_RECURSIVE

 INPUTS:
        none

 KEYWORD PARAMETERS:
        MASK -> string, default is '*', that is all files

        INPUT_PARENT_DIR -> top directory of files to convert, if
             not specified, a dialog window pops up

        NEW_PARENT_DIR -> top directory destination for netCDF
             files, if not specified, a dialog window pops up
        
        TOKEN -> set if you want to replace 'bpch' with 'nc' in all
             part of the full name 

 OUTPUTS:
        None

 REQUIREMENTS:
        References routines from the GAMAP package.

 NOTES:
        To work recursively on the directories, I use FILE_SEARCH
        with 2 arguments. This is not possible with MFINDFILE, and
        works only with IDL 5.5 and above. 

 EXAMPLE:

        ; after creating a subdirectories tree in outdir similar to the
        ; one in indir: 
        indir  = '/as/data/geos/GEOS_1x1/EDGAR_200607/'         
        outdir = '/home/phs/data/EDGAR_200607/nc/'             
        mask   = '*1x1'                                          
        make_nc_recursive, input_parent_dir=indir, new=outdir, mask=mask

 MODIFICATION HISTORY:

       Tue Jan 27 10:40:49 2009, Philippe Le Sager
       

		v1, based on make_c_nc.pro to work on several
		directories at once.

        bmy, 30 Nov 2010: GAMAP VERSION 2.15
                          - Updated comments and categories in header

(See /n/home09/ryantosca/IDL/gamap2/file_io/make_nc_recursive.pro)


MAKE_PDF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAKE_PDF

 PURPOSE:
        Wrapper program for the Unix utility "ps2pdf".  Creates
        a PDF file for each PostScript file located in the
        a user-specified directory.

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
        MAKE_PDF, DIR

 INPUTS:
        DIR -> Directory where PostScript files reside.  
             PDF files will be written out to this directory.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        ADD_SEPARATOR (function)
        MFINDFILE     (function)
        REPLACE_TOKEN (function)

 REQUIREMENTS:
        You need "ps2pdf" installed on your system.  This ships
        with most versions of Unix or Linux.

        Also requires routines from the GAMAP package.

 NOTES:
        PDF files will have the same names as the PostScript files
        but with the *.pdf extension.  

 EXAMPLES:
        MAKE_PDF, 'output'

             ; Create *.pdf Files from all *.ps files 
             ; in the "output" directory.
      

 MODIFICATION HISTORY:
        bmy, 30 Nov 2010: GAMAP VERSION 2.15
                          - Initial version
        bmy, 08 Jun 2011: - Make sure that the directory ends with a
                            path separator

(See /n/home09/ryantosca/IDL/gamap2/file_io/make_pdf.pro)


MAKE_RESTART

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAKE_RESTART

 PURPOSE:
        Creates a restart file for GEOS-Chem.  

 CATEGORY:
        File & I/O, BPCH Format

 CALLING SEQUENCE:
        MAKE_RESTART [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        OUTMODELNAME -> Name of the model grid onto which the data
             will be regridded.  Default is "GEOS4_30L".

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  OUTRESOLUTION
             can be 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.

        OUTFILENAME -> Name of the restart file that will be created.
             Default is "restart.bpch".

        TAU0 -> TAU value (hours from 0 GMT on 01 Jan 1985) that 
             that will be used to timestamp the restart file.
             The default TAU0 value 140256.00 (corresponds to 
             0 GMT on 01 Jan 2001).
 
        TRACERLIST -> A scalar value (or vector) of tracer numbers
             to write to the restart file.  Default is 1.
      
        DATAVALUE -> Specifies the data value that will be assigned
             to all grid boxes in the restart file.  Default is 0e0.

        DIAGN -> Specifies the diagnostic category name that will
             be used to index data fields in the restart file.
             Default is "IJ-AVG-$".

        UNIT -> Use this keyword to overwrite the default unit
             string (as specified in the "tracerinfo.dat" file)
             for each data block in the restart file.

        /NO_VERTICAL -> Set this switch to create a restart file
             with 2-D data blocks (e.g. lon x lat) instead of 3-D
             data blocks (e.g. lon x lat x alt).

        DIM -> Allows you to manually set the dimensions of the
             data blocks (for nested grids).  DIM is passed to
             CTM_MAKE_DATAINFO.

        FIRST -> Allows you to manually set the starting indices
             (in Fortran notation, starting from 1) of the data 
             block.  FIRST is passed to CTM_MAKE_DATAINFO.
        
 OUTPUTS:
         None

 SUBROUTINES:
         External Subroutines Required:
         ===================================================
         CTM_GET_DATABLOCK (function)   CTM_GRID (function)   
         CTM_MAKE_DATAINFO (function)   CTM_TYPE (function) 
         CTM_WRITEBPCH                  NYMD2TAU

 REQUIREMENTS:
         None

 NOTES:
         (1) You must make sure that your "diaginfo.dat" and 
             "tracerinfo.dat" file lists the diagnostic categories
             and tracers that you wish to save to the restart file.

 EXAMPLE:
         MAKE_RESTART, OUTMODELNAME='GEOS4_30L',              $
                       OUTRESOLUTION=2,                       $
                       OUTFILENAME='restart.2x25.2005010100', $
                       TAU0=NYMD2TAU( 20050101L ),            $
                       DATAVALUE=100e0,                       $
                       TRACERLIST=[1,2,3,4,5,6],              $
                       UNIT='ppbv',                           $
                       DIAGN='IJ-AVG-$'

             ; Create a GEOS-4 30-level 2x25 restart file for 
             ; CO2 tracers 1-6, setting all tracers equal to 
             ; 100 ppbv.
                           

 MODIFICATION HISTORY:
        bmy, 19 Jul 2007: VERSION 1.00
        bmy, 27 Oct 2010: GAMAP VERSION 2.15
                          - Added DIM and FIRST for setting the
                            region properly for nested grids

(See /n/home09/ryantosca/IDL/gamap2/file_io/make_restart.pro)


MAKE_SELECTION (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAKE_SELECTION (function)

 PURPOSE:
        Convert an array of selected values to an index array that
        identifies the selected values in a list or data array. 

 CATEGORY:
        General

 CALLING SEQUENCE:
        INDEX = MAKE_SELECTION( NAMES, SELNAMES [,keywords] )

 INPUTS:
        NAMES -> A list or array of values to choose from 

        SELNAMES -> A list of selected values

 KEYWORD PARAMETERS:
        ONLY_VALID -> Return only indices of found values. Values not
            found are skipped. Default is to return 1 index value for
            each SELNAME, which is -1 if SELNAME is not contained in 
            NAMES. If ONLY_VALID is set, the -1 values will be deleted,
            and a value of -1 indicates that no SELNAME has been found
            at all.

        REQUIRED -> Normally, MAKE_SELECTION will return indices for
            all values that are found, simply ignoring the selected
            values that are not in the NAMES array (although an error
            message is displayed). Set this keyword to return with
            -1 as soon as a selected value is not found.

        QUIET -> Suppress printing of the error message if a
            selected value is not found (the error condition will
            still be set).

 OUTPUTS:
        INDEX -> A (long) array with indices to reference the 
            selected values in the NAMES array.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        If the NAMES array contains multiple entries of the same value,
        only the index to the first entry will be returned.

        A selection can contain multiple instances of the same value.
        The index array will contain one entry per selected item
        (See example below)

 EXAMPLES:
        (1)
        NAMES = [ 'Alfred','Anton','Peter','John','Mary']
        INDEX = MAKE_SELECTION( NAMES, ['Peter','Mary'] )
        PRINT, INDEX
          2  4

        (2)
        VALS = INDGEN(20)
        INDEX = MAKE_SELECTION( VALS, [9,-5,8,7,7,8,9] )
        PRINT, INDEX
          9  -1  8  7  7  8  9

        (3)
        INDEX = MAKE_SELECTION( VALS,[9,-5,8,7,7,8,9], /ONLY_VALID )
        PRINT, INDEX
          9  8  7  7  8  9

        (4)
        INDEX = MAKE_SELECTION( vals, [9,-5,8,7,7,8,9], /REQUIRED )
        PRINT, INDEX
          -1


 MODIFICATION HISTORY:
        mgs, 28 Aug 1998: VERSION 1.00
        mgs, 29 Aug 1998: - changed behaviour and added ONLY_VALID keyword
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/make_selection.pro)


MAPS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAPS

 PURPOSE:
        Creates lon-lat maps of GEOS-Chem tracers at the 
        surface and 500 hPa levels.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        MAPS, FILE, LEVELS, TAUS, TRACERS, VERSION, [, Keywords ]

 INPUTS:
        FILE -> The name of the file containing data to be plotted.

        LEVELS -> A 4-element vector containing the level indices
             for the GEOS-Chem surface layer and 500 hPa layer.
             for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
             NOTE: This is in Fortran notation (starting from 1!)

        TAU -> The TAU value (hours GMT from /1/1985) corresponding
             to the data to be plotted.

        TRACERS -> The list of transported tracers (i.e. diagnostic
             category "IJ-AVG-$").

        VERSION -> The model version number corresponding to the
             data to be plotted.

 KEYWORD PARAMETERS:
        /DO_FULLCHEM -> Set this switch to plot the chemically
             produced OH in addition to the advected tracers.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output 
             to a file whose name is specified by this keyword.
             Default is "tracer_ratio.pro".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Provided:
        ==================================================
        PlotMap

        External Subroutines Required:
        ==================================================
        CLOSE_DEVICE          COLORBAR_NDIV    (function)
        CTM_GET_DATA          EXTRACT_FILENAME (function)
        GETMODELANDGRIDINFO   MULTIPANEL
        MYCT                  OPEN_DEVICE
        TVMAP                 CHKSTRU          (function)
        UNDEFINE
        
 REQUIREMENTS:
        References routines from the GAMAP package.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLES:
        FILE     = 'ctm.bpch.v7-04-11'
        LEVELS   = [ 1, 1, 13, 13 ]
        TAUS     = NYMD2TAU( 20010701 )
        TRACERS  = INDGEN( 43 ) + 1
        VERSIONS = 'v7-04-11'

        MAPS, FILE, LEVELS, TAU, TRACERS, VERSION, $
             /DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'

             ; Creates tracer maps of GEOS-CHEM v7-04-11 for July 2001.
             ; Output is sent to PostScript file "myplot.ps".

 MODIFICATION HISTORY:
        bmy, 14 Nov 2007: VERSION 1.01
                          - Based on "tracer_map.pro" 
        bmy, 07 May 2008: VERSION 1.06
                          - Now allow for comparing models on 2
        bmy, 08 Jun 2011: VERSION 1.07
                          - Added /DO_FULLCHEM keyword
                          - Now restore !MYCT sysvar to previous
                            settings upon exiting the program
        mps, 29 Mar 2013: - Now plot chemically produced HO2

(See /n/home09/ryantosca/IDL/gamap2/benchmark/maps.pro)


MAPS_AOD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAPS_AOD

 PURPOSE:
        Creates column maps of aerosol optical depths from 1-month
        GEOS-Chem benchmark simulation output.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        MAPS_AOD_1YR, FILES, TRACERS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "red", 'green", and "blue" GEOS-Chem model 
             versions that are to be compared. 

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        TRACERS -> The list of transported tracers (i.e. diagnostic
             category "IJ-AVG-$") to be plotted.

        VERSIONS ->  A 2-element vector containing the model version
             names from the "red", 'green", and "blue" simulations. 

 KEYWORD PARAMETERS:
        /DYNRANGE -> Set this switch to create plots using the entire
             dynamic range of the data (centered around zero).  The
             default is to use pre-defined data ranges.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output 
             to a file whose name is specified by this keyword.
             Default is "tracer_ratio.pro".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Provided:
        =========================================
        PLOTDIFF

        External Subroutines Required:
        =========================================
        OPEN_DEVICE     CLOSE_DEVICE
        MULTIPANEL      COLORBAR_NDIV (function)
        CTM_PLOT        CHKSTRU       (function)
     
 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLE:
        FILES    = [ 'ctm.bpch.v9-02p', 'ctm.bpch.v9-02q' ]
        TAUS     = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
        TRACERS  = [ 1, 2, 4 ]
        VERSIONS = [ 'v9-02p', 'v9-02q' ]

        DIFFERENCES_1YR, FILES, TAUS, TRACERS, VERSIONS, $
             /PS, OUTFILENAME=myplot.ps'

             ; Creates maps from 2 different model versions
             ; using output from GEOS-Chem 1-month benchmark simulations.

        DIFFERENCES_1YR, FILES, TAUS, TRACERS, VERSIONS, /DYNRANGE, $
             /PS, OUTFILENAME=PSNAME

             ; Same as above, but will create difference maps  using
             ; the full dynamic range of the data (centered around zero)
             ; instead of using pre-defined min & max values.


 MODIFICATION HISTORY:
        bmy, 05 Sep 2012: VERSION 1.01
                          - Initial version
        mps, 16 Sep 2013: - Modified for 1-month benchmark output
        bmy, 24 Jan 2014: GAMAP VERSION 2.17
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/benchmark/maps_aod.pro)


MAP_LABELS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MAP_LABELS

 PURPOSE:
        Constructs map labels from numerical values, in either
        numerical format (e.g. "-90", "0", "90" ), or in
        directional format ( e.g. "90S, "0", "90N" ).

 CATEGORY:
        Plotting

 CALLING SEQUENCE:
        MAP_LABELS, LATLABEL, LONLABEL [ , Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        LATRANGE, LONRANGE -> The range of latitudes (longitudes)
            for the map or plot area.

        LATS, LONS  -> Returns to the calling program the array of
            latitudes (longitudes) used to construct the map labels.
            Can also be use as input: if LATS has one element, the
            LATS vector is build with LATS+n*DLAT; if it has more
            than one element, it is not modified and is the final
            grid.

        DLAT, DLON -> Returns to the calling program the latitude
            (longitude) interval between grid lines.
            Now, can also be used as input so the user can specify
            the grid spacing.

        /MAPGRID -> If set, will assume that latitude and longitude
            labels are for grid lines on a world map.  Also compute
            normal coordinates which can be used for placing the
            labels next to the map.

        NORMLATS -> 2D Array containing normal X and Y
            coordinates for placing latitude labels outside map
            boundaries.  These are computed only if /MAPGRID is set.

        NORMLONS -> 2D-Array containing normal X and Y
            coordinates for placing latitude labels outside map
            boundaries.  These are computed only if /MAPGRID is set.

     Keywords Passed to CONSTRUCT_MAP_LABELS:
     ========================================
        FORMAT -> Format descriptor string used in converting the
            values from DATA into string representation.  The
            default value is '(i10)'.

        /NUMERIC -> If set, will return latitude or longitude
            labels in numerical format (e.g. "-90", "0", "+90").
            If not set, will return latitude or longitude labels
            in directional format (e.g. "90S, "0", "90N")

        /NODEGREE -> If set, will prevent the raised degree symbol
            from being appended to MAPLABEL.  Default is to add the
            raised degree symbol to MAPLABEL.

 OUTPUTS:
        LATLABEL -> String array of latitude labels

        LONLABEL -> String array of longitude labels

 SUBROUTINES:
        Internal Subroutines Used:
        =================================
        CONSTRUCT_MAP_LABELS (function)
        GET_GRIDSPACING

        External Subroutines Required:
        =================================
        STRREPL (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) LATLABEL and LONLABEL are in the range of -180..180 degrees.

        (2) We should at some point allow the user to supply individual values
            that override the default spacing.

 EXAMPLES:
        (1) For use in conjunction with the PLOT command...

         MAP_LABELS, YTICKNAME, XTICKNAME,           $    ; Call MAP_LABELS
            LATRANGE=[ -90,90], LONRANGE=[-180,180], $    ; to get the
            LATS=LATS,          LONS=XTICKV,         $    ; lat and lon
            _EXTRA=e                                      ; tick labels

         PLOT, XARR, YARR, XTICKV=XTICKV,            $    ; call PLOT,
             XTICKNAME=XTICKNAME,                    $    ; using the
             XTICKS=N_ELEMENTS( XTICKV )-1,          $    ; labels as
             _EXTRA=e                                     ; tick names


        (2) For use in conjunction with MAP_SET and MAP_GRID

        LIMIT    = [ -90, -180, 90, 180 ]                 ; set up the
        MAP_SET, LIMIT=Limit, _EXTRA=e                    ; world map

        LATRANGE = [ Limit[0], Limit[2] ]                 ; define lat and
        LONRANGE = [ Limit[1], Limit[3] ]                 ; lon ranges

        MAP_LABELS, LATLABEL,    LONLABEL,            $   ; call MAP_LABELS
           LATS=LATS,            LATRANGE=LATRANGE,   $   ; to return
           LONS=LONS,            LONRANGE=LONRANGE,   $   ; the lat/lon
           NORMLATS=NORMLATS,    NORMLONS=NORMLONS,   $   ; values, labels
           /MAPGRID,             _EXTRA=e                 ; normal coordinates

        MAP_GRID, LATS=LATS, LONS=LONS, _EXTRA=e
            ; Plots the grid lines on the map

        XYOUTS, NORMLATS[0,*], NORMLATS[1,*], $
           LATLABEL, ALIGN=1.0, /NORMAL
            ; Plots latitude labels using normal coordinates

        XYOUTS, NORMLONS[0,*], NORMLONS[1,*], $
            LONLABEL, ALIGN=0.5, /NORMAL
            ; Plots longitude labels using normal coordinates


        (2) For use in conjunction with TVMAP to control grid
     
        TVMAP, DIST(42)


 MODIFICATION HISTORY:
        mgs, 19 Feb 1999: VERSION 1.00
        bmy, 26 Feg 1999: VERSION 1.10
                          - now works for maps that are smaller
                            than global size.
        bmy, 04 Mar 1999: VERSION 1.11
                          - added DEBUG keyword for output
                          - now computes NORM_XLAT correctly for
                            grids that are centered on -180 degrees
        mgs, 17 Mar 1999: - cleaned up
                          - replaced Norm[XY]... by two dimensional
                            NormLons and NormLats
                          - Longitude conversion now done in CONSTRUCT_...
                          - calls MAP_SET if /MAPGRID is set and no
                            map has been established.
        bmy, 25 Mar 1999: - double default DLON if more than 2 plots
                            per page
        mgs, 23 Apr 1999: - bug fix for LON labels in Pacific mode
  mgs & bmy, 03 Jun 1999: - fix for Pacific ranges in GET_GRIDSPACING
        bmy, 17 Nov 2005: GAMAP VERSION 2.04
                          - Now allows for a spacing of 1 degree
                            if the plot range is smaller or equal to
                            10 degrees
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        phs, 29 Feb 2008: GAMAP VERSION 2.12
                          - Grid spacing can be set by user with
                            DLON and DLAT
                          - LONS/LATS can be use as input to specify
                            the start (if 1 element) or the entire
                            grid (more than 1 element)
                          - GET_GRIDSPACING is now a procedure
        phs, 14 Mar 2008: - Added a new method to find the Labels
                            position. This can be used to overwrite
                            the old position with two new keywords,
                            NEWLONLAB and NEWLATLAB. Useful for map
                            projection defined with SCALE instead
                            of LIMIT. Need to pass MapPosition to work.

(See /n/home09/ryantosca/IDL/gamap2/plotting/map_labels.pro)


MCF_LIFETIME

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MCF_LIFETIME

 PURPOSE:
        Computes the methylchloroform (CH3CCl3, aka "MCF") lifetime
        w/r/t tropospheric OH from monthly-mean  GEOS-Chem archived
        fields. 

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        MCF_LIFETIME, FILE, [ Keywords ]

 INPUTS:
        FILE -> Specifies the name of the file with GEOS-Chem
            diagnostic output (bpch format or otherwise).
      

 KEYWORD PARAMETERS:
        LON -> A 2-element vector containing the minimum and maximum
             longitude values to include in the computation of the MCF
             lifetime.  Default is [ -180, 180 ].

        LAT -> A 2-element vector containing the minimum and maximum
             latitude values to include in the computation of the MCF
             lifetime.  Default is [ -90, 90 ].

        LEV_a -> A 2-element vector containing the minimum and maximum
             levels (i.e. all vertical levels) to include in the
             computation of the MCF lifetime.  Default is [ 1, 47 ] 
             (corresponding to the GEOS-5 47-level simulation).

        LEV_t -> a 2-element vector containing the minimum and
             maximum tropospheric levels to include in the
             computation of the MCF lifetime.  Default is [ 1, 38 ]
             (corresponding to the value of the max tropospheric
             level  LLTROP for a GEOS-5 47-level simulation.)

        TAU0 -> TAU value (hours from 0 GMT on 1985/01/01) with which
             the GEOS-Chem diagnostic data blocks are timestamped.  
             Default is 179664.00 (corresponding to 0 GMT on 
             2005/07/01).

        /VERBOSE -> Will cause MCF_LIFETIME to print the methyl
             chlofororm lifetime to the screen.  The default is to
             suppress printing.
             
 OUTPUTS:
        LIFE_YEARS -> Returns the MCF lifetime w/r/t tropopsheric
             OH in years.

 SUBROUTINES:
        External subroutines required:
        ==============================
        CTM_BoxSize       (function)
        CTM_Get_DataBlock (function)
        Nymd2Tau          (function)

 REQUIREMENTS:
        MCF_LIFETIME requires that the following GEOS-Chem
        diagnostics be present in the input file:
 
          (a) Grid box surface area    [m2       ] (DXYP,     tracer #1)
          (b) Grid box heights         [m        ] (BXHGHT-$, tracer #1)
          (c) Air number density       [molec/m3 ] (BXHGHT-$, tracer #4)
          (d) Chemically produced OH   [molec/cm3] (CHEM-L=$, tracer #1)
          (e) Time spent in tropopause [fraction ] (TIME-TPS, tracer #1)
          (f) Temperature              [K        ] (DAO-3D-$, tracer #5)

        Requires routines from the GAMAP package.

 NOTES:
        Derivation of MCF lifetime w/r/t tropospheric OH
        ----------------------------------------------------------

        We assume that MCF has a uniform mixing ratio in air (=1).  
        Thus the density of air can be substituted for the density
        of MCF in the equations below.


        The lifetime of MCF w/ respect to tropospheric OH is:

           T_OH = Atmospheric Burden / Tropospheric loss rate


        The atmospheric burden of MCF is:

           SUM{ AIRDEN(I,J,L) * VOLUME(I,J,L) }

           where:
              I        = longitudes
              J        = latitudes
              L        = levels from the surface to top of atmosphere
              AIRDEN   = Air density at ([I,J,L) in molec/cm3
              VOLUME   = Grid box volume at (I,J,L) in cm3
 

        The tropospheric loss rate of MCF is:

           SUM{ K(I,J,X) * OH(I,J,X) * AIRDEN(I,J,X) * VOLUME(I,J,X) }
    
           where
              I        = longitudes
              J        = latitudes
              X        = levels from the surface to the 
                          location of the tropopause at (I,J)
                          (we only count boxes fully in the tropopause)
              K(I,J,X) = 1.64e-12 * EXP( -1520 / T(I,J,X) )
              T(I,J,X) = Temperature at grid box (I,J,X)
   

        T_OH has several reported values in the literature:
      
           (a) Spivakovsky et al (2000) : 5.7 years
           (b) Prinn et al (2001)       : 6.0 years

        Derivation of total MCF lifetime:
        ----------------------------------------------------------

        Once you have obtained the MCF lifetime w/r/t tropospheric
        OH, you can compute the total lifetime of MCF as:

           1/T_total = 1/T_OH + 1/T_strat + 1/T_ocean

        where 

           T_total = total lifetime of MCF in atmosphere
           T_OH    = the output of this function
           T_strat = 43 years (cf. Spivakovsky et al)
           T_ocean = 94 years (range 81-145 years, cf WMO/UNEP) 

        References:
        ----------------------------------------------------------

        (1) Prather, M. and C. Spivakovsky, "Tropospheric OH and
             the lifetimes of hydrochlorofluorocarbons", JGR,
             Vol 95, No. D11, 18723-18729, 1990.

        (2) Lawrence, M.G, Joeckel, P, and von Kuhlmann, R., "What
             does the global mean OH concentraton tell us?",
             Atm. Chem. Phys, 1, 37-49, 2001.

        (3) WMO/UNEP Scientific Assessment of Ozone Depletion: 2010
            
 EXAMPLE:
        LIFE = MCF_LIFETIME( 'ctm.bpch',       $
                              LON=[-180,-180], $
                              LAT=[ -90,  90], $
                              LEV_A=[ 1, 47 ], $
                              LEV_T=[ 1, 38 ], $
                              TAU0=NYMD2TAU( 20050101 ) )

             ; Will return the MCF lifetime w/r/t tropospheric OH
             ; (in years) based on GEOS-Chem diagnostic output at 
             ; model date 2005/01/01.
                                   
 MODIFICATION HISTORY:
        bmy, 08 Jun 2011: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/benchmark/mcf_lifetime.pro)


MEAN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MEAN

 PURPOSE:
        Computes the mean value of an array, along a given dimension.

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        RESULT = MEAN( X, DIM, _EXTRA=e )

 INPUTS:
        X -> The input vector or array.

        DIM -> The dimension along which to compute the mean of X.
             DIM may be omitted if the X is 1-dimensional.
             
 KEYWORD PARAMETERS:
        _EXTRA=e -> Passes extra keywords to the TOTAL command.

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        Multidimensional version from Kevin Ivory (04/03/1997)

 EXAMPLES:
        (1)

        PRINT, MEAN( FINDGEN(10) )

        IDL prints:
           4.50000

            ; Prints the mean of a 1-D array

        (2)

        ARRAY = MEAN( DIST(10,10), 2 )
        HELP, ARRAY
        PRINT, ARRAY

        IDL prints:
           ARRAY           FLOAT     = Array[10]
           2.50000   2.79703   3.36695   4.08519   4.89073      
           5.75076   4.89073   4.08519   3.36695   2.79703

            ; Prints the mean of a 2-D array along
            ; the second dimension.
         
 MODIFICATION HISTORY:
      ivory, 04 Mar 1997: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Cosmetic changes, added comments

(See /n/home09/ryantosca/IDL/gamap2/math_units/mean.pro)


MERGE_FERT_SOILPREC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MERGE_FERT_SOILPREC

 PURPOSE:
        Merges nonzero soil fertilizer and soil precipitation 
        data onto the same indexing scheme.  Also computes
        NLAND, the number of land boxes used in "commsoil.h".
        
 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        MERGE_FERT_SOILPREC [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        FERTFILE -> Name of the binary punch file containing soil 
             fertilizer data to be merged.  The default file name
             is hardwired (change as necessary).

        SOILPRECFILE -> Name of the binary punch file containing soil 
             precipitation data to be merged.  The default file name
             is hardwired (change as necessary).

        OUTDIR -> Name of the directory where the output file will
             be written.  Default is './'.  

 OUTPUTS:
        Writes to ASCII output files:
             fert_scale.dat.{MODELNAME}.{RESOLUTION}
             climatprep{RESOLUTION}.dat.{MODELNAME} 
  
 SUBROUTINES:
        External Subroutines Required:
        ==============================================
        CTM_TYPE   (function)   CTM_GRID   (function)
        CTM_NAMEXT (function)   CTM_RESEXT (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) Input files must be binary punch files, created with
            routines REGRID_FERT and REGRID_SOILPREC.

        (2) Output files are in ASCII format and are compatible
            with the existing Harvard CTM routines.

 EXAMPLE: 
        MERGE_FERT_PRECIP, FERTFILE='nox_fert.geos1.2x25',      $
                           PRECIPFILE='soil_precip.geos1.2x25', $
                           OUTDIR='/scratch/bmy'

             ; Will merge the soil fertilizer data contained in
             ; "nox_fert.geos1.2x25" and the soil precip data 
             ; contained in soil_precip.geos1.2x25".  Output files
             ; will be sent to the /scratch/bmy directory.

 MODIFICATION HISTORY:
        bmy, 04 Aug 2000: VERSION 1.00
                          - adapted from older IDL code 
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/merge_fert_soilprec.pro)


MERGE_OH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MERGE_OH

 PURPOSE:
        Creates a "Merged OH" file, with OH from the GEOS-CHEM 
        model in the troposphere and zonal mean OH from a 2-D 
        model in the stratosphere.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        MERGE_OH, MODELNAME

 INPUTS:
        None
       
 KEYWORD PARAMETERS:
        MODELNAME -> Name of the model (e.g. GEOS1, GEOS-STRAT) 
             for which we are going to merge tropospheric OH with 
             stratospheric OH.

        RESOLUTION -> Horizontal latitude resolution of the grid.
             RESOLUTION=2 specifies 2 x 2.5 grid and
             RESOLUTION=4 specifies 4 x 5   grid.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ====================================================
        CTM_TYPE (function)   CTM_GET_DATABLOCK (function)   
        CTM_GRID (function)   CTM_MAKE_DATAINFO 

 REQUIREMENTS:
        None

 NOTES:
        (1) The output file name has the form:
             OH_3Dglobal.{MODELNAME}.{RESOLUTION}

        (2) Filenames are currently hardwired for 4x5,
              
 EXAMPLE:
        MERGE_OH, MODELNAME='GEOS3', RESOLUTION=4
 
             ; Will merge stratospheric and tropospheric OH
             ; at the GEOS-1 4 x 5 resolution into a single 
             ; binary punch file.

 MODIFICATION HISTORY:
        bey, 21 Jul 2000: VERSION 1.00
        bmy, 11 Aug 2000: VERSION 1.01
                          - added standard header, updated comments
                          - renamed to "merge_oh.pro"
        bmy, 04 Feb 2002: VERSION 1.02
                          - rewrote for expediency
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/merge_oh.pro)


MFINDFILE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MFINDFILE

 PURPOSE:
        Find all the files that match a given specification.
        MFINDFILE is a wrapper for IDL routines FILE_SEARCH 
        (v5.5 and higher) and FINDFILE (v5.4 and lower).

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
        LISTING = MFINDFILE( MASK )

 INPUTS:
        FILEMASK -> a path and filename specification to look for.

 KEYWORD PARAMETERS:
        none

 OUTPUTS:
        A string list containing all the files that match the 
        specification.

 SUBROUTINES:
        External Routines Required:
        ===========================
        ADD_SEPARATOR (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) For IDL 5.5+, use FILE_SEARCH to return a listing of
            files with the given path name specified by MASK.  This
            should work regardless of platform.

        (2) For IDL 5.4- running under Unix, The built-in FINDFILE() 
            function has problems on whenever a lot of files are 
            matching the file specification.  This is due to the fact 
            that filename expansion is done by the shell before 
            interpreting a command.  Too many files cause too long 
            commands which are not accepted.  This causes FINDFILE() 
            to return an empty list of candidates. (cf. www.dfanning.com)
            
            Therefore, we implement a workaround where we issue a
            "ls -1" command under the Unix shell.  This isn't 100%
            foolproof either but it's better than nothing.

        (3) For IDL 5.5- running under other operating systems,
            call the built-in IDL FINDFILE routine as usual.

 EXAMPLE:
        LIST = MFINDFILE( '~mgs/terra/chem1d/code/*.f' )

        ; returns all fortran files in Martin's chem1d directory.

 MODIFICATION HISTORY:
        mgs, 14 Sep 1998: VERSION 1.00
        bmy, 14 Oct 2003: TOOLS VERSION 1.53
                          - Now use built-in FINDFILE() routine to
                            return file listing for IDL 5.3 and higher
        bmy, 06 Nov 2003: TOOLS VERSION 2.01
                          - return to pre v1-53 algorithm
        bmy, 28 May 2004: TOOLS VERSION 2.02
                          - For IDL 5.5+, now use FILE_SEARCH to return
                            a list of files corresponding to MASK
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/mfindfile.pro)


MODEL2AIRNUMDENS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
 	MODEL2AIRNUMDENS

 PURPOSE:
 	Returns the monthly averaged Air Number Density in 
       each grid box for one GEOS-Chem model. 

       This let you get the Number Density from the average monthly
       pressure of the model.

 CATEGORY:
	Atmospheric Sciences

 CALLING SEQUENCE:
	airNumDens = Model2AirNumDens( Model [, tau] )

 INPUTS:
	Model : string for model name ("GEOS4_30L", "GEOS5_47L", ...)

 OPTIONAL INPUTS:
 	Tau   : tau0 for which Air Numb density is look for. The year
 	        does not matter, the month value is extracted. Default
 	        is 0D0, which selects January.

 OUTPUTS:
	A 3D array (same size as the model 3D grid) with Air
	Density Number in [molec/cm3].


 PROCEDURE:
	GetModelAndGridInfo, DataInfo, Model, Grid      
 
       airnumden = Model2AirNumDens( CTM_NamExt( Model ), DataInfo.tau0 )


 MODIFICATION HISTORY:
       Wed Sep 2 10:54:41 2009, Philippe Le Sager
       

		Gamap v2.13 - Init version
        bmy, 30 Nov 2010: GAMAP VERSION 2.15
                          - Updated comments and category in header

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/model2airnumdens.pro)


MULTIPANEL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MULTIPANEL

 PURPOSE:
        This routine provides an easy-to-use interface to 
        IDL's !p.multi mechanism and it can be used 
        to retrieve the position vector of the next plot 
        in line (even if !p.multi is not set). You can 
        specify plot margins and a page margin in normalized 
        coordinates.
           For multi-panel plots, multipanel works in three
        stages (somewhat similar to XInterAnimate): 
        1) set up a multi-panel page by specifying the number
           of rows and columns or the maximum number of plots
           on the page.
        2) advance to the next plot position and return that 
           position. If the page was filled (i.e. the maximum
           number of plots (advance steps) has been made, it 
           will be erased (unless /NOERASE is set).
        3) turn the multi-panel environment off and reset margin
           values.
        Subsequent PLOT, MAP_SET, etc. commands should use the
        POSITION vector returned from this routine and they should
        use the /NOERASE keyword.

 CATEGORY:
        Plotting

 CALLING SEQUENCE:
        Get position of next plot
        MULTIPANEL,position=p

        Setting up multi-panel pots
        MULTIPANEL,[rows=r,cols=c | nplots=n] [,options]

        Advance to the next panel (and get its position)
        MULTIPANEL,/advance [,position=p] [,options]

        Reset multi-panel environment to start over at the first panel
        MULTIPANEL,/reset   [,options]

        Turn multi-panel environment off (reset !p.multi and some other
        parameters)
        MULTIPANEL,/OFF

 INPUTS:
     Optionally you can give the number of plots (keyword NPLOTS) as
     a parameter instead. Th euse of a parameter will override the
     keyword.

 KEYWORD PARAMETERS:
        General keywords (honored under all circumstances)
        -------------------------------------------------------------------
        POSITION -> Returns a 4-element vector with the position of
            the next plot in the line. As always this vector contains
            [X0,Y0,X1,Y1].

        MARGIN -> specify a margin around the plot in normalized 
            coordinates. This keyword does not change any IDL
            system variables and will thus only become "visible" 
            if you use the POSITION returned by MULTIPANEL in subsequent plot
            commands.
            MARGIN can either be one value which will be applied to
            all four margins, or a 2-element vector which results in
            equal values for the left and right and equal values for 
            the bottom and top margins, or a 4-element vector with
            [left,bottom,right,top]. 

        OMARGIN -> specify a page margin around all panels in normalized
            coordinates. Works like MARGIN.
            
        Note that you can change the values of MARGIN and OMARGIN after
        you set up your plot page. The values given with MARGIN and OMARGIN 
        remain active until you specify a new one or use the /OFF keyword.

        /NOERASE -> This keyword prevents erasing the screen (or page) 
            when setting a multi-panel environment or after a page was
            filled. NOERASE is automatically turned ON when the /OFF
            keyword is given.


        Informational keywords:
        -------------------------------------------------------------------

        FIRSTPANEL -> returns 1 if the current plotting panel is
            the first one on a page

        LASTPANEL -> returns 1 if the current plotting panel is the last
            on a page

 
        Setting up a multi-panel page:
        -------------------------------------------------------------------
        ROWS, COLS -> specify the number of rows and columns
            you want on your page. If one is specified, the 
            other one must be given as well. Alternatively,
            you can use the NPLOTS keyword. 

        NPLOTS -> maximum number of plots on one page. The 
            number of rows and columns is automatically computed
            so that the plots "approach a square" and they are
            returned in the ROWS and COLS keywords. Setting
            NPLOTS to a ROWS*COLS value is equivalent to using
            ROWS and COLS. If you specify an "uneven" number
            (e.g. 5), multipanel,/advance will erase the page 
            after 5 plots instead of 6.

        /PORTRAIT -> Normally, ROWS tends to be larger than COLS
            when NPLOTS is used (e.g. 12 gives 4 rows and 3 cols).
            Use this keyword to revert this behaviour.

        /LANDSCAPE -> Make ROWS larger than COLS if necessary. This
            is the default. Thi skeyword is actually unnecessary and
            was introduced for purely aesthetic reasons (symmetry).


        Advance to the next plot:
        -------------------------------------------------------------------
        /ADVANCE -> this keyword issues a hidden plot command to find
            out the position of the next plot to be made. The position
            is then returned in the POSITION keyword. The value of
            !P.MULTI[0] is increased afterwards so that you can issue
            your plot command without explicitely specifying the
            position or /NOERASE. When the maximum number of plots set
            with NPLOTS is reached, MULTIPANEL,/ADVANCE will erase the
            screen and reset the plot position to the upper left corner.

        CURPLOT -> use this keyword to advance to a specific plot position
            on the page. If you specify 0, the screen will be erased.
            CURPLOT also returns the current plot number. If you don't
            want to set the plot number but just query it, you must pass 
            an undefined variable (see procedure UNDEFINE.PRO).


        Reset the plot position (and erase the screen)
        -------------------------------------------------------------------
        /RESET -> does just this.


        Turn multi-panel environment off
        -------------------------------------------------------------------
        /OFF -> Overrides all other keywords. Resets !p.multi to 0.
            

 OUTPUTS:
        none.

 SUBROUTINES:
        function GET__PLOTPOSITION() issues a dummy plot command
            and returns the plot position from the ![xy].window
            variables.

 REQUIREMENTS:
        none. (example uses RECTANGLE.PRO)

 NOTES:
        Side effect: Opens a window in standard size if none was open 
        before. This happens because the next plot position is 
        determined by issuing a hidden (or dummy) plot command with
        no visible output.
        
        Make sure to use POSITION=P,/NOERASE with all your PLOT, MAP_SET
        CONTOUR, etc. commands. In fact, you don't _need_ /NOERASE for
        PLOT, but it guarantees consistent behaviour with MAP_SET etc.)
        A PLOT command without /NOERASE will advance to the next panel
        and thereby interfere with MULTIPANEL's plot counter.

        If you don't use MARGIN and OMARGIN, the values in ![XY].margin
        ![XY].omargin will take effect.

        A common block is used to store the current plot number and 
        margin information. This limits the use to one window at a time
        (although you can save all parameters elsewhere and supply them
        to the routine on a window-by-window basis).

 EXAMPLES:
        (1)
        MULTIPANEL, position=p
        PLOT, findgen(10), color=1, position=p, /noerase

             ; Just retrieve the position of the next plot

        (2) 
        MULTIPANEL, MARGIN=[0.1,0.05], POSITION=P
        PLOT, FINDGEN(10), COLOR=1, POSITION=P, /NOERASE

             ; same thing but use a specific margin (2-element form) 
             ;
             ; If you want to see both previous plots together use 
             ; /NOERASE with MULTIPANEL

        (3) 
        ; Set up for 5 plots
        MULTIPANEL, NPLOTS=5                     

        FOR I = 0, 4 DO BEGIN

           ; Get current plot position
           MULTIPANEL, POSITION=P, MARGIN=0.04     

           ; Do the plot
           PLOT, FINDGEN(10), COLOR=!MYCT.BLACK,$
               POSITION=P, /NOERASE   
            
           ; Go to the next panel
           ; Note that the screen would be erased after the last plot
           ; without the /NoErase keyword.;
           MULTIPANEL, /ADVANCE, /NOERASE 

        ENDFOR

             ; Multi-panel example

        (4) 
        MULTIPANEL, /OFF, OMARGIN=0.01, MARGIN=0., $
            POSITION=P, /NOERASE 
        RECTANGLE, P, XVEC, YVEC        
        PLOTS, XVEC, YVEC, COLOR=!MYCT.BLACK, /NORM

            ; Now let's draw a frame around everything

 MODIFICATION HISTORY:
        mgs, 19 Mar 1999: VERSION 1.00
        mgs, 22 Mar 1999: - improved documentation, changed OMARGIN
                 to accept normalized coordinates.
                          - position now also returned if turned OFF
                          - added FIRSTPANEL and LASTPANEL keywords
                          - allow NPLOTS to be specified as parameter 
        mgs, 02 Jun 1999: - now saves old values of !X, !Y, and !P
                            and restores them when turned OFF.
        mgs, 03 Jun 1999: - save !X, !Y, and !P only if !p.multi was 
                            really off
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/plotting/multipanel.pro)


MULTISORT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MULTISORT

 PURPOSE:
        hierarchical sorting of a data set, each column can be sorted
        reversely. Works well together with W_SORT, a widget interface 
        that handles up to three sort levels/columns. COLUMNS are defined
        as first array index (e.g. DATA=FLTARR(5,20) has 5 columns).

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        multisort,data,index=index,revert=revert

 INPUTS:
        DATA --> a 2D array to be sorted

 KEYWORD PARAMETERS:
        INDEX --> an integer or integer array containing the indices for
            which the array shall be sorted (e.g. [ 3,1,0 ] will sort DATA
            first by column 3, then within groups of same values for column
            3 values will be sorted by column 1, and finally by column 0.
            Default is to sort by the first column.

        REVERT --> an integer or integer array indicating which columns shall
            be sorted in reverse order. REVERT=1 reverts all sorting,
            REVERT=[0,1,0] reverts the sort order only for the 2nd column.
            Default is 0, i.e. do not revert.


 OUTPUTS:
        The DATA array will be sorted according to the specifications.

 SUBROUTINES:
        testsort : little test program (historic debugging purposes)

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        MULTISORT, DATA, INDEX=[3,1,0], REVERT=[0,1,0]

             ; Sort data first in column 3, then in reverse order 
             ; for column 1, and finally ascending order for column 0.

 MODIFICATION HISTORY:
        mgs, 30 Jun 1997: VERSION 1.00
        mgs, 08 Apr 1998: - now stand-alone routine and documentation
        mgs, 22 Dec 1998: - bug fix (startindex must be -1)
        mgs, 17 Mar 1999: - bug fix: now has default 0 for revert
                            (thanks to G. Fireman)
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/math_units/multisort.pro)


MYCT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MYCT

 PURPOSE:
        Define a set of standard drawing colors and load a colortable 
        on top of these.  The color table can be manipulated in various 
        ways (see KEYWORD PARAMETERS).

        The standard MYCT drawing colors are as follows.  These
        were implemented by Chris Holmes, based on the ColorBrewer 
        definitions.  These colors are less saturated than the 
        traditional MYCT drawing colors, and are easier to read
        on the screen:

           0 : white              9 : lightblue
           1 : black             10 : lightorange
           2 : red               11 : lightpurple
           3 : green             12 : 85% grey
           4 : blue              13 : 67% grey
           5 : orange            14 : 50% grey
           6 : purple            15 : 33% grey
           7 : lightred          16 : 15% grey
           8 : lightgreen        17 : white

        However, if you use the /BRIGHT_COLORS keyword to MYCT, you
        may still use the traditional MYCT drawing colors (which were
        created by Martin Schultz).  These are defined as follows:

           0 : white             9  : lightgreen
           1 : black             10 : lightblue
           2 : red               11 : black
           3 : green             12 : 85% grey
           4 : blue              13 : 67% grey
           5 : yellow            14 : 50% grey
           6 : magenta           15 : 33% grey
           7 : cyan              16 : 15% grey
           8 : lightred          17 : white
         
        With MYCT, you may load any of the standard IDL color tables
        or any of the ColorBrewer color tables.  For backwards
        compatibility, MYCT also supports several customized color
        tables that used to be defined with the CUSTOM_COLORTABLE
        routine.

        MYCT reads color table definitions from an IDL *.tbl file.
        The default file name is "gamap_colors.tbl".  You may specify
        a different file with the CTFILE keyword (see below).  Also,
        if you wish to add a custom color table, the best way to 
        proceed is to create your own *.tbl file with your custom
        color table definitions.  See the routine GAMAP_COLORS for
        more information.

 CATEGORY:
        Color

 CALLING SEQUENCE:
        MYCT, [ TABLE ] [ , keywords ]

 INPUTS:
        TABLE (optional) -> Number or name of the IDL color table 
             to be used.  If no number or name is provided, the
             routine will default to color table 0 (which for the 
             "gamap_colors.tbl" file is B-W LINEAR).  The MYCT
             drawing colors will be loaded first, and the color
             table will be loaded on top of that.  You can choose
             the bottom color index for the color table with the
             BOTTOM keyword.  MYCT will ensures that the system
             variable !D.N_COLORS is set correctly.  

 KEYWORD PARAMETERS:
        /BRIGHT_COLORS -> Selects the older set of MYCT drawing colors
             to be loaded at the bottom of the colortable.  Default is 
             to select the newer set of MYCT drawing colors, which
             are less saturated and easier to read on the screen.

        BOTTOM -> specify where to start color table (see BOTTOM keyword
             in LOADCT). Default is number of standard drawing colors+1
             or 0 (if NO_STD is set). If BOTTOM is less than the number
             of standard drawing colors (17), no standard colors will be
             defined (equivalent to setting NO_STD).  RANGE has no
             effect on the DIAL/LIDAR colortable.  Default is 18.
             NOTE: You should not normally have to change this value.

        CTFILE -> Specify a file containing the color table
             definitions.  Default is "gamap_colors.tbl", which is
             a combination of the standard IDL color tables plus
             the ColorBrewer color tables.  (See routine GAMAP_COLORS.)

        NCOLORS -> number of color indices to be used by the color table.
             Default is !D.N_COLORS-BOTTOM. 

        /NO_STD -> prevents definition of standard drawing colors.

        RANGE -> a two element vector which specifies the range of colors
             from the color table to be used (fraction 0-1). The colortable
             is first loaded into the complete available space, then
             the selected portion is interpolated in order to achieve the
             desired number of colors.   RANGE is only effective when
             a TABLE parameter is given.  RANGE has no effect on the 
             customized colortables.

        /REVERSE -> Set this switch to reverse the color table.
             /REVERSE works for both IDL and custom color tables.

        SATURATION -> factor to scale saturation values of the extra
             color table. Saturation ranges from 0..1 (but the factor 
             is free choice as long as positive).  SATURATION has no
             effect on the customized colortables.  Default is 1.

        USERDEF -> set to load the user defined colortable. The table
             is defined in the Define_UserDef routine. It can be
             loaded in three different ways:
                  MyCt, -1
                  MyCt, /user
                  MyCt, 'user'
             In the later version, the string is not case sensitive,
             and can be any string that contains the word "user".
               
        VALUE -> factor to scale the "value" of the added colortable.
             (i.e. this is like the contrast knobon a TV set).  Value 
             ranges from 0..1; 0 = black, 1 = white.  Default is 1.

        /USE_CURRENT -> By default, MYCT will reset the color table
             to all white before loading a new colortable.  Set
             /USE_CURRENT to prevent this from happening.

        /VERBOSE -> Set this switch to print out information about
             the color table that has just been selected.

        /XINTERACTIVE -> to call XLOADCT instead of LOADCT for
             interactivity. Has no effect if a custom colortable is
             loaded.


        The following keywords are kept for backwards compatibility.
        These will replicate the color tables that used to be defined
        with the now obsolete CUSTOM_COLORTABLE routine.
        
        /BuWhRd   -> Loads 19-color BLUE-WHITE-RED color table
        /BuWhWhRd -> Loads 20-color BLUE-WHITE-WHITE-RED color table
        /BuYlRd   -> Loads 11-color BLUE-YELLOW-RED color table
        /BuYlYlRd -> Loads 12-color BLUE-YELLOW-YELLOW-RED color table
        /DIAL     -> Loads the 26-color DIAL/LIDAR color table 
                      (cf. E. Browell)
        /DIFF     -> Synonym for /BuWhRd.  
        /ModSpec  -> Loads the 11 color MODIFIED SPECTRUM color table
        /WhBu     -> Loads the 10-color WHITE-BLUE color table
        /WhGrYlRd -> Loads the 20-color WHITE_GREEN-YELLOW-RED color table
                      (cf. Aaron van Donkelaar)
        /WhGyBk   -> Loads the 10-color the WHITE-GRAY-BLACK color
        /WhRd     -> Loads the 10-color the WHITE-RED color table

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Provided:
        ===============================
        MYCT_Drawing_Colors

        External Subroutines Required:
        ===============================
        COMPRESS_DIV_CT   
        DATATYPE (function)
        XCOLORS

 REQUIREMENTS:
        None

 NOTES:
        (1) It is recommended to use the COLOR keyword in all PLOT 
            commands. This will ensure correct colors on (hopefully) 
            all devices.  In order to get 256 colors on a postscript 
            printer use DEVICE,/COLOR,BITS_PER_PIXEL=8 

        (2) MYCT will also save several parameters in the MYCT system 
            variable, so that graphics programs can access them.

        (3) MYCT uses the "gamap_colors.tbl" file.  This file
            contains all of the IDL standard color table definitions
            all of the olorBrewer color table definitions, and some
            extra colortables.  If you wish to add a color table
            you should probably use routine GAMAP_COLORS to create
            a new *.tbl file.  Then call MYCT and specify the name
            of the new *.tbl file with the CTFILE keyword.

        (4) We will use the ColorBrewer color abbreviations:
               Bk = Black    Br = Brown    Bu = Blue      
               Gr = Green    Gy = Gray     Or = Orange    
               Pi = Pink     Pu = Purple   Rd = Red     
               Wh = White    Yl = Yellow

        (5) An MS Excel spreadsheet with all ColorBrewer color tables 
            is available for download from:
            www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_RGB.html

        (6) NOTE: Use a temporary hack to center the ColorBrewer
            diverging color tables. (phs, 4/23/08)

 EXAMPLES:
        MYCT, 8, /NO_STD     
             ; load IDL colortable green-white (#8)
             ; identical result as loadct,3

        MYCT, 'EOS B', NCOLORS=20  
             ; change first 17 colors to standard drawing colors
             ; and add EOS-B (#27) color table in indices 18-36

        MYCT, 0, NCOLORS=20, /REVERSE, /NO_STD, /Use_Current
             ; add reversed grey scale table on top

        MYCT, 'EOS B', NCOLORS=40, /NO_STD, /Use_Current, $
             RANGE=[0.1,0.7], SATURATION=0.7
             ; add a less saturated version of a fraction
             ; of the EOS-B color table in the next 40 indices
             ; NOTE that color indices above 97 will still contain 
             ; the upper portion of the green-white color table.

        MYCT, 0 /REVERSE     
             ; On b/w terminals MYCT can be used to reverse
             ; the IDL black & white (#0) colortable 

        MYCT, /DIAL, NCOLORS=120
            ; Loads the DIAL LIDAR color table with 120 colors

        MYCT, /BuYlYlRd
        MYCT, 'RdBu', /MIDCOLORPRESENT, /YELLOW, NCOLORS=20
            ; Both of these commands do the same thing: loads
            ; the ColorBrewer "RdBu" colortable and inserts yellow
            ; into the 2 middle colors.  This is a good choice
            ; if you are creating an absolute or % difference plot.

 MODIFICATION HISTORY:
        mgs, 06 Feb 1997: VERSION 1.00
        mgs, 03 Aug 1997: - added input parameter and template
        mgs, 26 Mar 1998: - added NCOLORS keyword
        mgs, 06 Apr 1998: - added BOTTOM, RANGE, and RGB keywords
        mgs, 04 May 1998: - added test for null device
        mgs, 03 Jun 1998: - return if !D.N_COLORS is less than 3 (b/w)
        mgs, 16 Jun 1998: - bug fix: range check now after tvlct
        mgs, 18 Jul 1998: - bug re-visited, added HLS keyword and changed
                            default to HSV. Also added SATURATION and
                            VALUE keywords.
        mgs, 12 Aug 1998: - re-written with bug fixes and more concise.
                            removed RGB and HLS keywords, added REVERSE 
                            and NO_STD               keywords.
        mgs, 14 Jan 1999: - limit oldcolors and ncolors to MaxColors (256) 
                            on PC with TrueColor Graphics to ensure 
                            compatibility with Unix.
        bmy, 26 Sep 2002: TOOLS VERSION 1.51
                          - added /DIAL keyword to specify the DIAL/LIDAR
                            colortable from Ed Browell et al.
                          - now save MYCT parameters into a system variable
                            so that plotting routines can access them.
        bmy, 22 Oct 2002: TOOLS VERSION 1.52
                          - fixed minor bugs in defining the !MYCT variable 
        bmy, 28 May 2004: TOOLS VERSION 2.02
                          - removed TESTMYCT routine, it's obsolete
                          - Bug fix: make sure RANGE is defined before
                            saving it to the !MYCT variable
        bmy, 09 Jun 2005: TOOLS VERSION 2.04
                          - Added default value for RANGE keyword
        bmy, 05 Oct 2006: TOOLS VERSION 2.05
                          - Now also define the DIFFERENCE color table
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Now calls CUSTOM_COLORTABLE to define
                            several custom colortables 
                          - Now allow /REVERSE to reverse custom
                            color table indices
                          - Added /VERBOSE keyword for printing info
                            about the selected color table
                          - Added /BuWhWhRd keyword for the 
                            BLUE-WHITE-WHITE-RED colortable
                          - Added /BuYlYlRd keyword for the 
                            BLUE-YELLOW-YELLOW-RED colortable
                          - Added /UserDef keyword to select
                            a user-defined color table.
  cdh & bmy, 19 Nov 2007: GAMAP VERSION 2.11
                          - Now implement newer, less-saturated MYCT
                            drawing colors as defaults
                          - Added /BRIGHT_COLORS keyword to use
                            the older drawing colors for backwards
                            compatibility.
       phs, 17 Apr 2008: GAMAP VERSION 2.12
                          - Now passes _extra to LOADCT, so a different
                            table file (*.tbl) can be used for example.
                          - bug fix: ncolors is correctly passed to
                            LOADCT if RANGE is not set.
                          - Added the XINTERACTIVE keyword to use
                            XCOLORS instead of LOADCT when no custom
                            table is loaded.
                          - Now use extra !MYCT tags: NAME, INDEX, FILE
                          - Added MIDCOLORPRESENT, USE_CURRENT keywords
       phs, 22 Sep 2008: GAMAP VERSION 2.13
                          - Re-Added UserDef keyword. Users can define
                            (and then load) their own color table in the
                            Define_UserDef subroutine.
                         

(See /n/home09/ryantosca/IDL/gamap2/color/myct.pro)


MYCT_DEFAULTS (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MYCT_DEFAULTS (function)

 PURPOSE:
        Returns a structure associating the names of MYCT
        drawing colors with their numeric values, plus
        the default bottom and number of colors. 

 CATEGORY:
        Color

 CALLING SEQUENCE:
        C = MYCT_DEFAULTS()

 INPUTS:
        None

 KEYWORD PARAMETERS:
        /GRAYSCALE -> If set, will define a grayscale colortable
             such that the lowest color is white, and the highest
             color is dark grey.  Otherwise the standard "TRACE-P"
             colortable (based on Mac Style #25) will be defined.

        NCOLORS -> Specifies the number of colors for MYCT.  The
             default is 120, but if your terminal can support more,
             you may specify a higher value.

 OUTPUTS:
        C -> Structure with the following tag names:
             WHITE       : Color index for "drawing color" WHITE
             BLACK       : Color index for "drawing color" BLACK
             RED         : Color index for "drawing color" RED
             GREEN       : Color index for "drawing color" GREEN
             BLUE        : Color index for "drawing color" BLUE
             ORANGE      : Color index for "drawing color" ORANGE
             PURPLE      : Color index for "drawing color" PURPLE
             LIGHTRED    : Color index for "drawing color" LIGHTRED   
             LIGHTGREEN  : Color index for "drawing color" LIGHTGREEN  
             LIGHTBLUE   : Color index for "drawing color" LIGHTBLUE
             LIGHTORANGE : Color index for "drawing color" LIGHTORANGE  
             LIGHTPURPLE : Color index for "drawing color" LIGHTPURPLE
             YELLOW      : Color index for "drawing color" YELLOW  
             MAGENTA     : Color index for "drawing color" MAGENTA  
             CYAN        : Color index for "drawing color" CYAN 
             GRAY85      : Color index for "drawing color" 85% GRAY 
             GRAY67      : Color index for "drawing color" 67% GRAY
             DARKGRAY    : Color index for "drawing color" 67% GRAY 
             GRAY50      : Color index for "drawing color" 50% GRAY
             MEDIUMGRAY  : Color index for "drawing color" 50% GRAY 
             GRAY33      : Color index for "drawing color" 33% GRAY
             GRAY        : Color index for "drawing color" 33% GRAY
             LIGHTGRAY   : Color index for "drawing color" 33% GRAY
             GRAY15      : Color index for "drawing color" 15% GRAY
             FILE        : Name of the color table (*.tbl) file
             NAME        : Color table name
             INDEX       : Color table index 
             BOTTOM      : Color table starts at this index
             NCOLORS     : Number of colors
             RANGE       : Range of IDL color table to be used
             SAT         : Saturation value for MYCT
             VALUE       : Hue value for MYCT
             REVERSE     : REVERSE=1 means light --> dark
                           REVERSE=0 means dark  --> light

 SUBROUTINES:
        None

 REQUIREMENTS:
        Designed to be used by the GAMAP routine "myct.pro".

 NOTES:
        (1) This routine is designed to be called by MYCT_DEFINE.
        You should not normally have to call MYCT_DEFAULTS.

        (2) MYCT defines a colortable such that the first 17
        colors are "drawing" colors, or pure colors intended
        for use with the PLOT, CONTOUR, MAP_SET, etc. commands.
        MYCT then loads a standard IDL colortable (with NCOLORS
        specifying the number of individual colors) into color
        indices 18  and higher.

        (3) New drawing colors (that are less saturated and
        easier to read on the screen) are now the defaults.
        See the documentation to the MYCT routine for more info.

 EXAMPLE:
        C = MYCT_DEFAULTS()

            ; Defines a grayscale colortable for use w/ MYCT.
            

 MODIFICATION HISTORY:
        bmy, 23 Jul 2001: TOOLS VERSION 1.48
                          - adapted from "default_colors.pro"
        bmy, 04 Feb 2004: TOOLS VERSION 2.01
                          - Increased grayscale color range slightly
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - renamed DIAL to CUSTOM, to reflect that
                            we have other custom colortables in use
  cdh & bmy, 19 Nov 2007: GAMAP VERSION 2.11
                          - Added names for the new MYCT drawing colors
        bmy, 21 Apr 2008: GAMAP VERSION 2.12
                          - Removed obsolete settings and keywords
                          - Removed IS_CUSTOM tag name from !MYCT
                          - Added INDEX, FILE tag names to !MYCT

(See /n/home09/ryantosca/IDL/gamap2/color/myct_defaults.pro)


MYCT_DEFINE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        MYCT_DEFINE

 PURPOSE:
        Defines the !MYCT system variable with default values.
        !MYCT is used to make colortable parameters available to
        plotting programs.

 CATEGORY:
        Color

 CALLING SEQUENCE:
        MYCT_DEFINE

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        MYCT_DEFAULTS (function)

 REQUIREMENTS:
        None

 NOTES:
        This routine should be called from your "idl_startup.pro"
        batch file, so that !MYCT will be defined and ready for
        use by all other routines that need it.

 EXAMPLE:
        MYCT_DEFINE

             ; Defines the !MYCT system variable 

 MODIFICATION HISTORY:
        bmy, 30 Sep 2002: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/color/myct_define.pro)


NCDF_GET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        NCDF_GET

 PURPOSE:
        Convenience routine to read data into netCDF format.

 CATEGORY:
        File & I/O, Scientific Data Formats

 CALLING SEQUENCE:
        DATA = NCDF_GET( FID, NAME [, Keywords ] )

 INPUTS:
        FID -> netCDF File ID, as returned by routine NCDF_OPEN.

        NAME -> Name under which the data array will be saved 
             to the netCDF file.  

 KEYWORD PARAMETERS:
        VARINFO -> Returns a structure containing information
             about the variable read in from disk.  The structure
             has the following form:

             { NAME      : "", $
               DATATYPE  : "", $
               NDIMS     : 0L, $
               NATTS     : 0L, $
               DIM       : LONARR(NDIMS) }


        LONGNAME -> Returns the value saved under the "long_name" 
             attribute in the netCDF file.

        UNIT -> Returns the value of the "unit" attribute 
             saved in the netCDF file.

        RANGE -> Returns the value of the "valid_range" 
             saved in the netCDF file

        _EXTRA=e -> Picks up extra keywords got NCDF_VarGet.

 OUTPUTS:
        DATA -> Array containing extracted data from the netCDF file.

 SUBROUTINES:
        Uses the following IDL netCDF routines:
        ========================================
        NCDF_VarId   (function)  NCDF_VarGet
        NCDF_VarInfo (function)  NCDF_AttGet
        NCDF_AttName (function)

 REQUIREMENTS:
        Need to use a version of IDL w/ netCDF routines installed.

 NOTES:
        (1) Only looks for the "long_name", "unit", and "valid_range"
            attributes.  The user can extend this as he/she desires.
            For a more general program, see ~/IDL/tools/ncdf_read.pro
            by Martin Schultz.

 EXAMPLE:

        ; Define array to write to file
        ARRAY = DIST( 100, 50 )

        ; Find out if netCDF is supported on this platform
        IF ( NCDF_EXISTS() eq 0 ) then MESSAGE, 'netCDF not supported!'

        ; Open netCDF file and get the file ID # (FID)
        FID   = NCDF_OPEN( 'myfile.nc' )
        IF ( FID lt 0 ) then Message, 'Error opening file!'

        ; Read data from the netCDF file
        ; Return data attributes in the VARINFO array
        ; Also returns the text from the UNIT string
        DATA = NCDF_GET( FID, 'BIOBSRCE::NOx', $
                         VARINFO=VARINFO, UNIT=UNIT ) 

        ; Close the netCDF file
        NCDF_CLOSE, FID

 MODIFICATION HISTORY:
        bmy, 22 May 2002: TOOLS VERSION 1.50
        bmy, 21 Oct 2003: TOOLS VERSION 1.53
                          - If we can't find a netCDF variable name,
                            then try again using a "sanitized" name
                            w/ all bad characters stripped out
        bmy, 28 Jun 2007: TOOLS VERSION 2.06
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Added /VERBOSE keyword to reduce
                            warning messages

(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_get.pro)


NCDF_READ

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        NCDF_READ

 PURPOSE:
        Open a netCDF file and read data from it. The data is 
        returned as a structure whose tag names are the names of 
        the variables with blanks etc. replaced. If no variables 
        are specified with the VARIABLES keyword, only dimensional 
        information is returned. You can load all variables using
        the ALL keyword. Other keyword options include OFFSET, COUNT, STRIDE,
        NO_DIMENSIONS, NO_STRUCT, DIMNAMES, VARNAMES, VARDIMS, ATTRIBUTES.
        Thus, this program includes ncdump functionality.
        If no filename is given, a file selection dialog is
        opened with the default mask '*.nc'. The name of the selected
        file is returned in the TRUENAME keyword. A file selection
        dialog also appears when the file cannot be found (see
        OPEN_FILE.PRO). This can be turned off with the NO_DIALOG
        keyword. The VERBOSE keyword provides information while
        analyzing and reading the file.

 AUTHOR:
        Dr. Martin Schultz
        Max-Planck-Institut fuer Meteorologie
        Bundesstr. 55, D-20146 Hamburg
        email: martin.schultz@dkrz.de
        
 CATEGORY:
        File & I/O, Scientific Data Formats

 CALLING SEQUENCE:
        NCDF_READ, result, filename=, truename=,
            variables=, all=, varnames=, 
            vardimid=, vardims=, attributes=,
            count=, offset=, stride=, 
            dimnames=, dims=, no_dimensions=,
            no_struct=, no_dialog=, verbose=, title=

 ARGUMENTS:
        RESULT(out) -> a structure containing all the variable data
             from the netCDF file. If only one variable is specified 
             and the NO_STRUCT keyword set, then RESULT will be an
             array instead of a structure. Use the ALL keyword
             to load all variables at once. Note, that the COUNT, OFFSET,
             and STRIDE keywords can affect the size of RESULT.
             RESULT is set to -1L if an error occurs before the structure
             has been built. You can use CHKSTRU.PRO to test for this.

 KEYWORD PARAMETERS:
        FILENAME(in) -> the name of the netCDF file to be opened.
             NCDF_READ uses OPEN_FILE to check the validity of
             the file first. You can specify a search mask
             instead of a filename in which case a file selection
             dialog is displayed (unless you set the NO_DIALOG
             keyword). The TRUENAME keyword contains the name
             of the selected file or an empty string if the
             file selection was canceled.

        TRUENAME(out) -> the (fully qualified) name of the file selected
             with the file selection dialog or an unaltered copy
             of FILENAME if FILENAME is a valid filename.

        VARIABLES(in) -> a string array containing the names of variables
             for which data shall be read. Default is to read 
             only the dimensional information from the file. 
             (Currently) no warning is issued if a variable is not in the file.

        ALL(in) -> set this keyword to load all variables stored in the 
             netCDF file. Generally, you cannot usethis keyword together with
             COUNT, OFFSET, and STRIDE.

        VARNAMES(out) -> a string array containing the names of all variables 
             as stored in the file. Note, that the tag names of e.g. the
             result structure are filtered with the Valid_TagName function.
             
        VARDIMID(out) -> a structure with integer arrays containing the 
             dimension ID's for all variables. See also VARDIMS which returns
             the dimensions themselves.

        VARDIMS(out) -> a structure with integer arrays containing the 
             dimensions for all variables in the netCDF file. These are not
             kept in sync with potential COUNT, OFFSET, and STRIDE values,
             but reflect the data sizes as stored in the file.

        ATTRIBUTES(out) -> a structure holding the variable and global
             attributes stored in the netCDF file (global attributes
             are stored in tag name GLOBAL). 

        COUNT(in) -> an integer array containing the number of values to
             be read for each dimension of the variables. Mapping of the
             COUNT dimensions to the variable dimensions is achieved via
             the first entry in the VARIABLES list and the COUNT parameter
             will be applied to all variables that have that dimension. 
             Example: The first variable has dimensions LON, LAT, LEV,
             the second variable has dimensions LON, LAT, and the third
             variable has LAT, LEV. A COUNT of [40,20,10] would lead to
             result dimensions of [40,20,10], [40,20], and [20,10].

        OFFSET(in) -> an integer array containing the offsets for each
             dimension of the variables to be read. Dimension mapping
             is the same as for COUNT.

        STRIDE(in) -> an integer array containing the stride for each
             dimension of the variables to be read. Dimension mapping
             is the same as for COUNT.
             
        DIMNAMES(out) -> a string array containing the names of the 
             dimensions stored in the netCDF file.

        DIMS(out) -> a long array containing the dimension values. Purely
             for convenience. Use VARDIMS to retrieve the dimensions of
             the variables.

        TITLE(in) -> A title for the file selection dialog if an
             incomplete or incorrect filename is specified. This
             keyword is ignored if the no_dialog keyword is set.

        NO_DIMENSIONS(in) -> set this keyword if you do not want to store
             the dimensional variables from the file in the result structure. 
             DIMNAMES and DIMS will still be retrieved.

        NO_STRUCT(in) -> if only one variable is selected with the
             VARIABLE keyword, you can set this keyword to return only
             the data for this variable as an array. This keyword implies
             the functionality of NO_DIMENSIONS.

        NO_DIALOG(in) -> set this keyword if you do not want interactive 
             behaviour when a file mask is given instead of a filename or
             when the specified file does not exist.

        VERBOSE(in) -> set this keyword to get detailed information while
             reading the netCDF file.

 SUBROUTINES:
        Valid_TagName : replaces invalid characters in variable names so that
            a structure can be built.
      
        ncdf_attributes : retrieves global and variable attributes from netcdf
            file and stores them as structure.

        ncdf_dimensions : retrieves size and name for all dimensions in netcdf file.

        ncdf_varnames : retrieves names and dimension information for all variables
            in the netCDF file.

        ncdf_mapdims : map dimension indices for COUNT, OFFSET, and STRIDE with 
            dimensions of first selected variable.

        ncdf_TestDimensions : compute the COUNT, OFFSET, and STRIDE vectors that
            must be applied for retrieving the data of one variable.

 REQUIREMENTS:
        uses OPEN_FILE and STRREPL.

 NOTES:
        Correct handling of dimensional information requires that the variables
        storing the dimension values have the same name as the dimensions
        themselves - a common feature in most netCDF standards.

        I am still working on a netcdf file object which will be even
        more powerful. At some point ncdf_read will only be a
        procedure interface to this objec!

 EXAMPLE:
        ncdf_read,result,/All
        ; plot ozone vs. temperature
        plot,result.temperature,result.ozone

 MODIFICATION HISTORY:
        mgs, 18 Sep 1999: VERSION 1.00
        mgs, 29 Feb 2000: - added variables keyword
                          - added CATCH error handler
        mgs, 21 Mar 2000: - bug fix for tag names
        mgs, 09 May 2000: VERSION 2.00
                          - now only reads dimensions as default
                          - added ALL keyword to compensate
                          - returns dimnames and attributes
                            (makes ncdf_detail obsolete)
                          - added COUNT, OFFSET and STRIDE keywords
                          - added NO_DIMENSIONS and NO_DIALOG
                            keywords and more
        mgs, 22 Aug 2000: - added title keyword
        bmy, 22 May 2002: GAMAP VERSION 1.50
                          - Now replace ":", "=", "#" with "_" in
                            structure tag names, so IDL won't choke
        bmy, 21 Oct 2003: GAMAP VERSION 1.53
                          - also replace "(" and ")" in tag names
                          - replace "$" with "S" (close to dollar sign)
                          - replace "*" with "A" (for Asterisk)
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
 

(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_read.pro)


NCDF_SET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        NCDF_SET

 PURPOSE:
        Convenience routine to write data into netCDF format.

 CATEGORY:
        File & I/O, Scientific Data Formats

 CALLING SEQUENCE:
        NCDF_SET, FID, DATA, NAME, DIMS [, Keywords ]

 INPUTS:
        FID -> netCDF File ID, as returned by routine NCDF_CREATE.

        DATA -> Data (array or scalar) to be written to netCDF file.

        NAME -> Name under which the data array will be saved 
             to the netCDF file.  

 KEYWORD PARAMETERS:
        LONGNAME -> Longer descriptive name for the data.  
             This will be saved as the "long_name" attribute.  

        RANGE -> A 2-element vector containing the [min,max] of
             the data array.  If not passed, RANGE will be computed
             (but only if DATA is a numeric type).  RANGE is saved 
             to the netCDF file as the "valid_range" attribute.

        UNIT -> String containing the units of the data. 
             This will be saved as the "unit" attribute.       

        _EXTRA=e -> Picks up extra keywords

 OUTPUTS:
        None

 SUBROUTINES:
        Uses the following routines:
        =====================================================
        NCDF_Control    NCDF_VarDef     (function)
        NCDF_AttPut     DATATYPE        (function from TOOLS)
        NCDF_VarPut     NCDF_VALID_NAME (function from TOOLS)   

 REQUIREMENTS:
        Need to use a version of IDL w/ netCDF routines installed.

 NOTES:
        (1) For now, treat BYTE data like CHAR data.  This is
            most likely since netCDF does not support STRING types,
            strings have to be stored as arrays of bytes.

 EXAMPLE:

        ; Define array to write to file
        ARRAY = DIST( 100, 50 )

        ; Find out if netCDF is supported on this platform
        IF ( NCDF_EXISTS() eq 0 ) then MESSAGE, 'netCDF not supported!'

        ; Open netCDF file and get the file ID # (FID)
        FID = NCDF_CREATE( 'myfile.nc', /CLOBBER )
        IF ( FID lt 0 ) then Message, 'Error opening file!'

        ; Set dimensions for netCDF file
        S    = SIZE( ARRAY, /DIM ) 
        DIM1 = NCDF_DIMDEF( FID, 'Length', S[0] )
        DIM2 = NCDF_DIMDEF( FID, 'Width',  S[1] )

        ; Go into netCDF DATA mode
        NCDF_CONTROL, FID, /ENDEF

        ; Call NCDF_SET to write the array to the file
        NCDF_SET, FID, ARRAY, 'My Data', [ DIM1, DIM2 ], $
                  LONGNAME='Data array created by me!',  $
                  UNIT='unitless'

        ; Close the netCDF file
        NCDF_CLOSE, FID

 MODIFICATION HISTORY:
        bmy, 19 Apr 2002: TOOLS VERSION 1.50
        bmy, 10 Sep 2002: TOOLS VERSION 1.51
                          - Now call routine DATATYPE to determine
                            the type of the data so that we can
                            write to the netCDF file appropriately
                          - Don't add the RANGE attribute to
                            the netCDF file for a string type value.
                          - Updated comments 
        bmy, 21 Oct 2003: TOOLS VERSION 1.53
                          - now "sanitize" the netCDF variable name
                            w/ routine NCDF_VALID_NAME.  The new netCDF
                            library in IDL 6.0+ chokes on bad characters.
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_set.pro)


NCDF_VALID_NAME

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        NCDF_VALID_NAME

 PURPOSE:
        Strips invalid characters from a string which is to be
        used as a netCDF variable name.  Based on original code
        by Martin Schultz.

 CATEGORY:
        File & I/O, Scientific Data Formats

 CALLING SEQUENCE:
        RESULT = NCDF_VALID_NAME( ARG )

 INPUTS:
        ARG -> netCDF variable name string to be examined.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> New netCDF name string with "bad" characters
             replaced by "good" characters.

 SUBROUTINES:
        External Subroutines Used:
        ==========================
        STRREPL (function)

 REQUIREMENTS:
        None

 NOTES:
        In IDL 6.0+, the netCDF library has been updated.  Some
        characters which used to be allowed in netCDF variable names
        are no longer allowed.  Therefore, use this function to
        replace "bad" characters with "good" characters when 
        reading or writing to/from netCDF files.

 EXAMPLE:
        RESULT = NCDF_VALID_NAME( 'IJ-AVG-$::CO' )
        PRINT, RESULT

             ; Prints "IJ-AVG-S__CO"

 MODIFICATION HISTORY:
        bmy, 21 Oct 2003: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/ncdf_valid_name.pro)


NUMDEN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        NUMDEN

 PURPOSE:
        Calculates the number density of air for a given temperature 
        and pressure.

 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        RESULT = NUMDEN( T, P, /DOUBLE )

 INPUTS:
        T -> Temperature (or vector of temperatures) in K.

        P -> Pressure (or vector of pressures) in hPa.  
             Default is 1000 hPa.

 KEYWORD PARAMETERS:
        /DOUBLE -> Set this switch to return the number density
             in double precision.  Default is to return the number
             density in single precision.

 OUTPUTS:
        RESULT -> Number density of air in molec/cm3.  If T and 
             P are vectors, then RESULT will be a vector of
             number densities

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1)
        PRINT, NUMDEN( 298.0, 1013.0 )
          2.46206e+19

             ; Prints the number density of air 
             ; at 298K and 1013 hPa.
         
        (2)
        PRINT, NUMDEN( 298.0, 1013.0, /DOUBLE )
          2.4620635e+19

             ; Prints the number density of air ; at 298K and 
             ; 1013 hPa.  Computation is done in double precision.


 MODIFICATION HISTORY:
        dbm, 30 Jul 2007: GAMAP VERSION 2.10
        phs,  1 Sep 2009: GAMAP VERSION 2.13
                          - let you pass array  

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/numden.pro)


NYMD2TAU (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        NYMD2TAU (function)

 PURPOSE:
        Computes the value of TAU, which is the elapsed hours between
        the current date/time and the beginning of an epoch. This is
        the starting date for 3D model data assimilation.

 CATEGORY:
        Date & Time

 CALLING SEQUENCE:
        RESULT = NYMD2TAU( NYMD, [NHMS [,NYMD0, NHMS0]] )

 INPUTS:
        NYMD (long)  -> YY/MM/DD for this date (e.g. 940101)
                  You can either specify year as 4 digits or 2 digits.
                  With 2 digits, year < 50 will be assumed to be 2000+YY.A

        NHMS (long)  -> HH/MM/SS for this date (e.g. 060000)
                  will be defaulted to 000000

        NYMD0 (long) -> YY/MM/DD for the start of the epoch
                  default is {19}850101 which is the GEOS-1 start

        NHMS0 (long) -> HH/MM/SS for the start of the epoch
                  will be defaulted to 000000
        
 KEYWORD PARAMETERS:
        /GEOS1 -> use 1985/01/01 as epoch start

        /GISS_II -> use 1980/01/01 as epoch start

 OUTPUTS:
        RESULT -> The function returns the TAU value as a 
             double-precision number

 SUBROUTINES:
        NYMD2STRU : extracts year, month, day, hour, minute and seconds from
            NYMD and NHMS values.

        JULDAY (IDL user library procedure)

 REQUIREMENTS:

 NOTES:
        Function NYMD2STRU is also contained in function TAU2YYMMDD.
        Take care when changes are necessary !

 EXAMPLE:
        ; (1) Compute TAU value for 0h on Jan 1, 1994, with the 
        ;     epoch starting on 0h on Jan 1, 1980 (GISS II value).
        ;
        TAU = nymd2tau( 940101L, 0L, 800101L, 0L )

        ; (2) Compute TAU value for 0h on Jan 1, 1994, for the 
        ;     default GEOS-1 epoch (850101L, 0L).
        ;
        TAU = nymd2tau( 940101L, 0L )

        ; (3) Compute GISS model II tau values for the first of
        ;     each month in 1990
        date = [ 900101L, 900201L, 900301L, 900401L, 900501L, 900601L, $
                 900701L, 900801L, 900901L, 901001L, 901101L, 901201L ]

        tau = nymd2tau(date,/GISS)


 MODIFICATION HISTORY:
        bmy, 26 Mar 1998: VERSION 1.00
        mgs, 26 Mar 1998: - now year 2000 compliable 
        mgs, 23 Mar 1999: - now handles vectors as input
        bmy, 23 Mar 2005: GAMAP VERSION 2.03
                          - Added /NO_Y2K keyword to suppress 
                            special Y2K treatment of dates (i.e.
                            treat dates w/ 2 digits as from 1900's)
                          - renamed internal function NYMD2STRU to
                            N2T_NYMD2STRU to avoid conflict with
                            similar function in "tau2yymmdd.pro"
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/date_time/nymd2tau.pro)


N_UNIQ (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        N_UNIQ (function)

 PURPOSE:
        Returns the number of unique elements in an array.

 CATEGORY:
        General

 CALLING SEQUENCE:
        Result = N_UNIQ( Arr )

 INPUTS:
        ARR -> The array to be searched for unique values.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        Returns the number of unique values in ARR as the value
        of the function

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        (1)
        PRINT, N_UNIQ( [10, 20, 30] )
           3

        (2)
        PRINT, N_UNIQ( [10,10] )
           1

 MODIFICATION HISTORY:
        bmy, 17 Nov 1998: VERSION 1.00
        mgs, 17 Nov 1998: - little streamlining
        mgs, 16 Mar 1999: - don't print out warning for empty argument
                            and return 0 instead of -1
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/n_uniq.pro)


OPEN_DEVICE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        OPEN_DEVICE

 PURPOSE:
        If hard copy is to be generated, OPEN_DEVICE opens the 
        PostScript device.  Otherwise OPEN_DEVICE opens an Xwindow. 

 CATEGORY:
        Graphics

 CALLING SEQUENCE:
        OPEN_DEVICE [,OLD_DEVICE] [,keywords]

 INPUTS:
        OLD_DEVICE -> This is now obsolete, and is only maintained
             for backwards compatibility.

 KEYWORD PARAMETERS:
        /PS -> will send PostScript file to printer

        FILENAME -> The name to be given the PostScript file.
             Default: idl.ps

        /LANDSCAPE  -> will enable PostScript landscape mode

        /PORTRAIT -> will enable PostScript portrait mode

        XOFFSET, YOFFSET -> Keywords for the DEVICE command.  XSIZE
             specifies the horizontal offset (in inches) of the page,
             and YSIZE specifies the vertical offset (in inches) of
             the page.  Defaults are as follows:

             Plot type         XOFFSET          YOFFSET

             -------------------------------------------------
             Portrait           0.25             0.25
             Landscape          0.75             0.75
             
        XSIZE, YSIZE -> Keywords for the DEVICE command.  XSIZE
             specifies the horizontal size (in inches) of the page,
             and YSIZE specifies the vertical size (in inches) of
             the page.  Defaults are as follows:
             
             Plot type         XSIZE            YSIZE
             -------------------------------------------------
             Portrait           8.0              10.0
             Landscape      11 - 2*XOFFSET   8.5 - 2*YOFFSET


        /COLOR -> will enable PostScript color mode

        WINPARAM -> An integer vector with up to 5 elements:
             WINPARAM(0) = window number  (if negative, a window
                          will be opened with the /FREE option.
             WINPARAM(1) = X dimension of window in pixels (width)
             WINPARAM(2) = Y dimension of window in pixels (height)
             WINPARAM(3) = X offset of window (XPOS)
             WINPARAM(4) = Y offset of window (YPOS)

        TITLE -> window title

        /Z -> If set, will initialize the Z-buffer device.  If WINPARAM
             is specified, then the size of the Z-buffer region will be
             WINPARAM[1] x WINPARAM[2] pixels.  If WINPARAM is not 
             specified, then the size of the Z-buffer region will be 
             set to a default size of 640 x 512 pixels.

        NCOLORS -> If /Z is set, NCOLORS specifies the number of colors
             that will be made available to the Z-buffer device.
         
        _EXTRA=e -> additional keywords that are passed to the call to
             the DEVICE routine (e.g. /ENCAPSULATED)

 OUTPUTS:
        OLD_DEVICE -> stores the previous value of !D.NAME for
             use in CLOSE_DEVICE. Note that CLOSE_DEVICE will automatically
             set the default screen device if OLD_DEVICE is not provided,
             hence it will only rarely be used.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        If PS=0 then  
            Open Xwindow WINPARAM(0), which is WINPARAM(1) pixels wide
            in the X-direction, and WINPARAM(2) pixels wide in the
            Y-direction. 

        If PS=1 then 
           depending on /PORTRAIT or /LANDSCAPE and /COLOR
           postscript is enabled in either portrait or landscape
           mode as color or b/w plot

        The key parameter which determines whether to open a postscript
        file or a screen window is PS. Therefore, e.g. in a widget 
        application, you can pass a standard set of parameters for both,
        postscript and screen, to this routine, and determine the device
        to be chosen by a button state or checkbox which is passed into PS.
              
        Also is currently hardwired for 8.5 x 11 inch paper (US
        format).  Need to extend this to European A4 paper soon.
        

 EXAMPLES:
        (1)
        OPEN_DEVICE, WINPARAM=[0,800,800]  

             ; opens a screen window of size 800x800 
             ; pixels at the default position

        (2)
        OPEN_DEVICE, /LANDSCAPE, FILENAME='myplot.ps'

             ; opens a postscript file named myplot.ps in 
             ; b/w and landscape orientation

        (3)
        OPEN_DEVICE, PS=PS, /PORTRAIT, /COLOR, WIN=2

             ; depending on the value of PS either a color 
             ; postscript file named idl.ps is opened or screen 
             ; window number 2 in default size.

        (4)
        OPEN_DEVICE, /Z

             ; Opens the IDL Z-buffer device.  The current 
             ; color table will be preserved in the Z-buffer device.

 MODIFICATION HISTORY:
        bmy  15 Aug 1997: VERSION 1.00
        bmy, 19 Aug 1997: VERSION 1.01
        mgs, 20 Aug 1997: VERSION 1.02
        mgs, 09 Apr 1998: VERSION 1.10 
                          - added 2 more parameters for WINPARAM
                            and TITLE keyword
        bmy, 28 Jul 2000: VERSION 1.46   
                          - now make XSIZE, XOFFSET, YSIZE, YOFFSET keywords
                          - cosmetic changes, updated comments
        bmy, 30 Jan 2001: VERSION 1.47
                          - added /Z and NCOLORS keywords for the Z-buffer
                          - updated comments
        bmy, 26 Jul 2001: VERSION 1.48
                          - use default window size of 640 x 512 for
                            the Z-buffer, if WINPARAM isn't specified.
        bmy, 27 Aug 2001: - now call DEVICE with XSIZE, YSIZE,
                            XOFFSET, YOFFSET for /LANDSCAPE plots
                          - Updatedd comments
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/graphics/open_device.pro)


OPEN_FILE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        OPEN_FILE

 PURPOSE:
        Open a file for input. This routine can automatically
        decide whether to use DIALOG_PICKFILE, and it contains
        basic error handling. After successful operation the
        file with logical unit LUN will be open for input.

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
        OPEN_FILE,filemask,lun [,keywords]

 INPUTS:
        FILEMASK -> a filename with path information that may
            contain wildcards ('*', '?')

        LUN -> a named variable that will contain the logical unit
            number upon return. If a unit number > 0 is passed,
            an attempt is made to open the file with this number,
            otherwise, a free unit is selected with /GET_LUN. In case
            of an error, LUN contains -1. This can be used instead of
            the RESULT keyword to detect errors (see below).

        (both parameters are mandatory !)

 KEYWORD PARAMETERS:
        FILENAME -> a named variable that will contain the complete
            filename upon return (i.e. the file selected with PICKFILE)

        WRITE -> Set this keyword to open a file for read and write
            operations. Normally, a file is opened for reading only.

        RESULT -> a named variable that will return the error status
            of the operation. A value of 0 indicates the file was
            opened sucessfully, otherwise the value of !Error_State.Code
            is returned.

        PICKFILE -> logical flag to force use of the DIALOG_PICKFILE
            routine, even if a complete filemask without wildcards was
            passed.

        TITLE -> the title of the pickfile dialog. Default is
            'Choose a file'.

        DEFAULTMASK -> A default filemask to be used when no filename
            is given or the filename does not contain wildcards and
            /PICKFILE is set. This mask will also be used if the
            file cannot be opened because of 'FILE NOT FOUND' error.

        NO_PICKFILE -> prevents the pickfile dialog for batch operation.
            The filemask must not contain wildcards.
            Normally a 'FILE NOT FOUND' condition leads to
            a second attempt with the /PICKFILE flag set (recursive
            call). Use this flag if you want to abort instead.

        _EXTRA keywords are passed to the openr routine
            (e.g. /F77_UNFORMATTED)

 OUTPUTS:

 SUBROUTINES:

 REQUIREMENTS:
        Uses EXTRACT_FILENAME function

 NOTES:

 EXAMPLE:
        (1)
        ; Quick and dirty with pickfile dialog
        OPEN_FILE,'*.dat',ilun
        if (ilun le 0) then stop    ; check error condition

        (2)
        ; A few more options invoked
        OPEN_FILE,'~/data/thisfile.dat',lun,default='*.dat', $
            title='Choose a data file',filename=name

        IF (LUN LE 0) THEN STOP    ; check error condition

        PRINT, FILENAME,' was opened successfully
        ; NOTE that filename does not have to be identical with
        ; '~/data/thisfile.dat' !
        ; readf,lun,...

        CLOSE,    LUN
        FREE_LUN, LUN

 MODIFICATION HISTORY:
        mgs, 13 Aug 1998: VERSION 1.00
                          - extracted from ctm_read3dp_header.pro and 
                            modified
        mgs, 14 Aug 1998: - small bug fix: handle empty filename
                            string correctly
        mgs, 22 Aug 1998: - added WRITE keyword to open writable files
        mgs, 22 Oct 1998: - now always returns LUN=-1 in case of an error
        mgs, 21 Jan 1999: - Added explicit F77_Unformatted keyword and set
                            Swap_If_Little_Endian or Swap_If_Big_Endian  
                            automatically
        mgs, 10 Feb 1999: - bug fix: swap_if was wrong way round
        mgs, 12 May 1999: - ok. finally got the hang of byte swapping! 
                            It's the machine architecture not the operating
                            system!  Now changed it so that !VERSION.ARCH is
                            tested for 'x86'
        mgs, 20 May 1999: - abandoned SWAP_IF completely and use explicit
                            SWAP_ENDIAN keyword in users grace now.
        bmy, 14 Oct 2003: TOOLS VERSION 1.53
                          - For IDL 6.0+, if PATH is a null string, then
                            manually reset it to './'.  This will avoid
                            the contents of the !PATH variable from being
                            listed in the dialog box. 
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
  cdh & phs, 30 Jun 2008: GAMAP VERSION 2.12
                          - declare dummy GET_LUN keyword. It
                            prevents passing GET_LUN w/ _extra to
                            openr/w, since LUN is already assigned in
                            all cases.

(See /n/home09/ryantosca/IDL/gamap2/file_io/open_file.pro)


ORG_CORR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ORG_CORR

 PURPOSE:
        Calculate reduced major axis.  Given two vectors X and Y, this
        subroutine computes the Gradient and Y intercept of the line 
        given by the reduced major axis.  The main advantage of this 
        is that the best fit line of X and Y will be the same as the 
        best fit line of Y and X.

 CATEGORY:
        Math & Units 

 CALLING SEQUENCE:
        ORG_CORR, X, Y, R, NP, GRADIENT, INTERCEPT,            $
                  GRADIENT_ERR, INTERCEPT_ERR [, VERBOSE=VERBOSE ]

 INPUTS:
        X -> Vector containing X-axis values.

        Y -> Vector containing Y-axis values.

        R -> Correlation coefficient
 
        NP -> Number of elements of X and Y arrays to process. 
             NP should be smaller than or equal to the number of
             elements of X and Y.

 KEYWORD PARAMETERS:
        /VERBOSE -> Set this switch to print the gradient,
             intercept, and standard errors to the screen.   
             The default is not to print these values.

 OUTPUTS:
        GRADIENT -> Gradient of reduced major axis

        INTERCEPT -> Y-Intercept of reduced major axis
  
        GRADIENT_ERR -> Standard error in gradient.

        INTERCEPT_ERR -> Standard error in Y-intercept.

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        SIGN (function)

 REQUIREMENTS:
        References routines from the TOOLS package.

 NOTES:
        (1) More details are in Hirsch and Gilroy, Water Res. Bull., 
            20(5), Oct 1984.

        (2) Standard errors also calculated according to Miller and 
            Kahn, Statistical Analysis in the Geological Sciences,
            1962, pp. 204-210.

        (3) Computations are now performed in double precision.

 EXAMPLE:

 MODIFICATION HISTORY:
  pip, clh, bmy, 10 Oct 2002: TOOLS VERSION 1.52
            bmy, 26 Jan 2007: TOOLS VERSION 2.06
                              - Now compute gradient of YNEW with max 
                                & min values & subscripts of.  This avoids
                                the assumption that the first & last 
                                elements of YNEW are different.  
                                (Fix submitted by Mike Barkley, 1/26/07)
      bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/math_units/org_corr.pro)


PAUSE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PAUSE

 PURPOSE:
        Halts program execution until the user presses RETURN.

 CATEGORY:
        General

 CALLING SEQUENCE:
        PAUSE

 INPUTS:
        MSG -> Specify a message to be displayed before pausing
             program execution.  MSG may be omitted.
            
 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        PRINT, DATA
        PAUSE
             ; Prints a data array and then pauses to allow
             ; the user time to examine the results.

        PRINT, DATA
        PAUSE, 'look at data'
             ; Same as above exmaple, but this time, print an
             ; informational message before pausing.
 

 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/pause.pro)


PEDGE (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PEDGE  (function)

 PURPOSE:
        Given the pressures at the centers of a model grid, returns
        the pressures at the edges of the grid.

 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        RESULT = PEDGE( MID, PSURF )

 INPUTS:
        MID -> Vector of pressure centers that defines the grid.  
             MID will be sorted in descending order.

        PSURF -> Surface pressure (which also corresponds to the
             lowest pressure edge).  Default is 1000.0 (mb).

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The vector of pressures at level edges [hPa]

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        The relationship between sigma centers and sigma edges is
        as follows:
   
              MID[N] = ( EDGE[N] + EDGE[N+1] ) / 2
   
        or conversely:
    
              EDGE[N+1] = ( 2 * MID[N] ) - EDGE[N]
   
        where EDGE[N] is the lower pressure edge, and EDGE[N+1]
        is the upper sigma edge of the box with center MID[N].
          
        The boundary condition PE[0] = PSURF is necessary to
        start the iteration.
      
 EXAMPLE:
        RESULT = PEDGE( [ 900, 700, 500 ], 1000.0 ) 
        PRINT, RESULT
           1000.00      800.000      600.000      400.000

             ; Prints edges between levels 900, 700, 500 hPa
             ; with the surface pressure being 1000 hPa.

 MODIFICATION HISTORY:
        bmy, 17 Jun 1999: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/pedge.pro)


PERCENTILES

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PERCENTILES

 PURPOSE:
        Compute percentiles of a data array (both ways: data that
        correspond to %, and % that correspond to data)

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        Y = PERCENTILES( DATA [,VALUE=value-array] )

 INPUTS:
        DATA -> the vector containing the data

 KEYWORD PARAMETERS:
 
        VALUE --> array or scalar that specify percentile(s) to
             compute.  If /REVERSE is set, a percentage that
             correspond to Value is return.
             
             Default percentile to compute is standard set of min
             (0%), 25%, median (=50%), 75%, and max(100%) which can
             be used for box- and whisker plots.  The values in the
             VALUE array must lie between 0. and 1.

             If /REVERSE, default value is mean(data) 

        INTERPOLATE --> Behaves like EVEN keyword for MEDIAN. 
             If no element of the data falls exactly on the requested
             percentile value, then the 2 adjacent data elements are 
             linearly interpolated to the requested percentile value.
             When using the INTERPOLATE keyword, returned values may
             not be elements of the input array. 
             
        /NAN  --> if set, ignores NaN values. You must use that
                  keyword if your dataset may have NaN.
        
        /REVERSE --> to get % corresponding to data value, instead of
                    data corresponding to %

 OUTPUTS:
        Y -> The function returns an array with the percentile 
             values or -1 if no data was passed or value contains 
             invalid numbers.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
      x = (findgen(31)-15.)*0.2     ; create sample data
      y = exp(-x^2)/3.14159         ; compute some Gauss distribution
      p = percentiles(y,value=[0.05,0.1,0.9,0.95])
      print,p

      IDL prints :  3.92826e-05  0.000125309     0.305829     0.318310

 MODIFICATION HISTORY:
        mgs, 03 Aug 1997: VERSION 1.00
        mgs, 20 Feb 1998: - improved speed and memory usage
                (after tip from Stein Vidar on newsgroup)
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
  cdh & jaf, 21 Oct 2009: GAMAP VERSION 2.13
                          - fixed incorrect values for small sample sizes
                          - removed unnecessary loop
			   - added NaN keyword
        phs, 22 Oct 2009: - added REVERSE keyword
			   - updated handling of NaN
        cdh, 19 Jun 2012: - added INTERPOLATE keyword
       

(See /n/home09/ryantosca/IDL/gamap2/math_units/percentiles.pro)


PHYSCONST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PHYSCONST

 PURPOSE:
        Creates a system variable named !PHYSCONST which contains 
        various physical constants.

 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        PHYSCONST

 INPUTS:
        None

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:

 NOTES:
        The !PHYSCONST system variable contains both the short names
        (e.g. C) and long names (e.g. SPEED_OF_LIGHT) for the various
        physical constatnts.

 EXAMPLE:
        PHYSCONST
        HELP, !PHYSCONST, /STRU

        ** Structure <108c0378>, 18 tags, length=144, data length=144, refs=2:
        C                            DOUBLE   2.9979000e+08
        SPEED_OF_LIGHT               DOUBLE   2.9979000e+08
        H                            DOUBLE   6.6260000e-34
        PLANCK                       DOUBLE   6.6260000e-34
        E                            DOUBLE   1.6020000e-19
        ELEMENTARY_CHARGE            DOUBLE   1.6020000e-19
        ME                           DOUBLE   9.1090000e-31
        ELECTRON_MASS                DOUBLE   9.1090000e-31
        NA                           DOUBLE   6.0220000e+23
        AVOGADRO                     DOUBLE   6.0220000e+23
        R                            DOUBLE   8.3140000
        MOLAR_GAS                    DOUBLE   8.3140000
        K                            DOUBLE   1.3810000e-23
        BOLTZMANN                    DOUBLE   1.3810000e-23
        SIGMA                        DOUBLE   5.6710000e-08
        STEFAN_BOLTZMANN             DOUBLE   5.6710000e-08
        G                            DOUBLE   9.8066500
        ACCELERATION_DUE_TO_GRAVITY  DOUBLE   9.8066500
          

 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments, cosmetic changes

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/physconst.pro)


PIE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PIE

 PURPOSE:
	 This procedure plots a pie chart.

 CATEGORY:
        Plotting

 CALLING SEQUENCE:
	 PIE, DATA

 INPUTS:
	 DATA -> The data vector to be plotted in the pie chart.

 KEYWORD PARAMETERS:
	 BORDERCOLOR -> The color of the circumference line of the 
             pie chart. The default is the background color.

	 BORDERTHICK -> The thickness of the circumference line of 
             the pie chart.

	 COLORS -> A vector containing the color table for the 
             pie slices.

	 DATA ->  If set, the plot is done in data coordinates.  
             The default is normal coordinates.

	 DEVICE ->  If set, the plot is done in device coordinates.  
             The default is normal coordinates.

	 NORMAL -> If set, the plot is done in normal coordinates.  
             This is the default.

	 NPOINTS ->  The total number of points to be used for 
             defining all of the arcs, measured around the 
             circumference.

	 XPOS, YPOS ->  The [X,Y] coordinates of the centre of the 
             pie chart.

	 RADIUS -> The radius of the pie chart.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
	 PIE, [2,3,4,5]

	      ; Make a pie chart of the values 2, 3, 4, and 5.

 MODIFICATION HISTORY:
	 Written by: Edward C. Wiebe, 1998-02-05.
	 Modified:   Daithi A. Stone (stoned@atm.ox.ac.uk), 2002-04-12 
		     (re-wrote, added documentation)
	 Modified:   DAS, 2005-08-05 (replaced SUM.PRO use with TOTAL; 
		     removed CONSTANTS.PRO use)
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - updated comments

(See /n/home09/ryantosca/IDL/gamap2/plotting/pie.pro)


PLANE_PLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PLANE_PLOT

 PURPOSE: 
        Plots data from the GEOS-CHEM plane following diagnostic
        atop a world map.  Multiple flights can be plotted.

 CATEGORY:
        GAMAP Utilities, GAMAP Plotting

 CALLING SEQUENCE:
        PLANE_PLOT, VAR, FLTID [, Keywords ]

 INPUTS:
        VAR -> Variable name for which to plot data.  VAR should
             match the variable names in the GEOS-CHEM input file
             "Planeflight.dat" (e.g. TRA_001, GMAO_TEMP, REA_O1D, etc.)
           
        FLTID -> Flight ID(s) for which to plot data.  These should
             match the flight ID's in the GEOS-CHEM input file
             "Planeflight.dat" (e.g. P3B01, DC801, etc.)

 KEYWORD PARAMETERS:
        FILENAME -> Name of the file containing GEOS-CHEM plane 
             following diagnostic output.  If FILENAME is omitted,
             then a dialog box will prompt the user to supply a file
             name.

        LIMIT -> A 4-element vector with [MINLAT,MINLON,MAXLAT,MAXLON],
             which will specify the bottom left and top right corners
             of the map plot in degrees.  Default is to plot the 
             entire Northern Hemisphere [0,-180,90,180].

        MPARAM -> A 3 element vector which specifies the LAT0, LON0,
             and ROT values to be passed to MAP_SET.  Default is
             [0,0,0].
        
        SYMBOL -> Number of the symbol used to plot each data point.
             SYMBOL corresponds to the types of symbols defined with
             the routine "sym.pro" in the TOOLS package.  Default is
             1 (filled circle).

        SYMSIZE -> Size of the plot symbol.  Default is 1.5

        _EXTRA=e -> Passes extra keywords to MAP_SET, MAP_GRID,
             and MAP_CONTINENTS.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        =================================
        COLORBAR
        CTM_READ_PLANEFLIGHT (function)
        UNDEFINE

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        PLANE_PLOT, 'O3', 'P3B04',           $
                     LIMIT=[20,-120,50,-60], $
                     FILENAME='plane.log'
        
             ; Plots GEOS-CHEM O3 data (stored in "plane.log) from
             ; the model grid boxes corresponding to flight P3BO4 
             ; over the USA.
 
        PLANE_PLOT, 'O3', ['P3B04','DC801'], $
                     LIMIT=[20,-120,50,-60], $
                     FILENAME='plane.log'

             ; Plots GEOS-CHEM O3 data (stored in "plane.log) from
             ; the model grid boxes corresponding to flights P3BO4 
             ; and DC801 over the USA.

 MODIFICATION HISTORY:
        bmy, 23 Apr 2004: GAMAP VERSION 2.03
        bmy, 13 Mar 2006: GAMAP VERSION 2.05
                          - Slight modifications for new version
                            of ctm_read_planeflight.pro
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/plane_plot.pro)


PLOTSIGMA

[Previous Routine] [Next Routine] [List of Routines]
 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)


PLOT_CPD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PLOT_CPD

 PURPOSE:
        Plots a cumulative probability distribution from a data array.

 CATEGORY:
        Plotting

 CALLING SEQUENCE:
        PLOT_CPD, DATA, [ , Keywords ]

 INPUTS:
        DATA -> The array holding the data points to plot as a 
             cumulative probability distribution.

 KEYWORD PARAMETERS:
        COLOR -> Sets the color of the plot window and data.
             Default is !MYCT.BLACK.
 
        CHARSIZE -> Sets the size of the text in the plot window.
             Default is 1.8.

        /OVERPLOT -> Set this switch to overplot data atop an 
             existing plot window.  Default is to create a new plot.

        SYMBOL -> Input argument for SYM, which will define the type
             of plot symbol.  Default is 6 (open circle).

        XMARGIN, YMARGIN -> Specifies the "cushion" of space around
             the plot window.  Defaults are XMARGIN=[10,1], and
             YMARGIN=[4,2].

        XMINOR, YMINOR -> Specifies the number of minor ticks (i.e.
             small ticks between the major ticks) along the X and Y
             axes.  Defaults are is XMINOR=4 and YMINOR=4.

        XRANGE, YRANGE -> Defines the plot range along the X and Y
             axes.  Defaults are XRANGE=[-4,4] and YRANGE=[0,100].

        XTICKNAME, YTICKNAME -> Specifies the tick labels on the 
             X and Y axes.

        XTICKS, YTICKS -> Specifies the number of major ticks (i.e.
             along the X and Y axes.  Defaults are is XTICKS=8 and 
             YTICKS=4.

        XTITLE, YTITLE -> Specifies the X and Y axis title strings.
           
 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ===================================
        QQNORM (function)   SYM (function)

 REQUIREMENTS:
        Requires routines from both TOOLS and GAMAP packages.

 NOTES:
        None

 EXAMPLE:
        PLOT_CPD, FINDGEN(200), COLOR=!MYCT.BLACK
        PLOT_CPD, FINDGEN(100), COLOR=!MYCT.RED, /OVERPLOT

             ; Plot 2 data arrays as cumulative probability
             ; distributions.  The 2nd array (red) is overplotted 
             ; onto the existing plot window.

 MODIFICATION HISTORY:
  swu & bmy, 10 Oct 2006: TOOLS VERSION 2.05
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/plotting/plot_cpd.pro)


PLOT_GPROF

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PLOT_GPROF

 PURPOSE:
        Reads a GNU Profile (gprof) text output and creates a bar graph
        of how long subroutines take to execute.  This is useful in
        examining code for computational bottlenecks.

 CATEGORY:
        Plotting

 CALLING SEQUENCE:
        PLOT_GPROF, FILENAME [,keywords]

 INPUTS
        FILENAME -> Text file containing profiling output from gprof.

 KEYWORD PARAMETERS:
        N_DISPLAY -> The number of routines to display, from slowest
             to fastest.  The default is 30.

        BARCOLOR -> The color table value that will be used to plot
             the bars.  Default is !MYCT.RED.
 
        /VERBOSE -> If set, will print a listing of the N_DISPLAY
             slowest routines.  The routine name, execution time, 
             and percentage of total run time will be printed.

 OUTPUTS:
        None

 SUBROUTINES:
        None
        
 REQUIREMENTS:
        Uses these GAMAP routines
        ==========================
        STRPAD   (function)  
        STRRIGHT (function)   

 NOTES:
       For instructions on using the GNU Profiler (gprof) and creating
       a text file with profiling output, please see this wiki page:
       http://wiki.geos-chem.org/Profiling_GEOS-Chem.

 EXAMPLE:
        PLOT_GPROF, 'Profile_Gfortran_Intel.txt', N_DISPLAY=40, /VERBOSE

             ; Creates a bar plot showing the 40 slowest routines
             ; contained in the GNU profiler output file named
             ; "Profile_Gfortran_Intel.txt".  Also will print the
             ; profiling info to the screen.

 MODIFICATION HISTORY:
        bmy, 15 Dec 2016: GAMAP VERSION 2.19
                          - Initial version

(See /n/home09/ryantosca/IDL/gamap2/plotting/plot_gprof.pro)


PLOT_MASSCONS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PLOT_MASSCONS

 PURPOSE:
        Plots the evolution of total mass vs. time from the
        geosfp_2x25_masscons simulation.
       
 CATEGORY
        Benchmarking

 CALLING SEQUENCE:
        PLOT_MASSCONS, FILENAME, _EXTRA=e

 INPUTS:
        FILENAME -> Name of the file containing the total mass
             printed every 6 hours from the geosfp_2x25_masscons
             simulation.  Default is "tracer_mass_kg.dat".
 
 OUTPUT:
        None (creates a plot)

 KEYWORD PARAMETERS:
        /VERBOSE -> Print extra information (min and max of time
             and total mass) to the screen.
 
        _EXTRA =e -> Passes extra keywords to PLOT and OPLOT routins.

 SUBROUTINES:
        External Subroutines Required:
        ===============================
        NYMD2TAU   (function)
        STRBREAK   (function)
        STRSCI     (function)

 REQUIREMENTS:
        None

 NOTES:
        This could probably be written a little more efficiently.
        Also, plotting output has been kept very basic, as we are
        mostly using this for quick validation plots, which do not
        need to be fancy.

 EXAMPLE:
        PLOT_MASSCONS, 'tracer_mass_kg_2017.dat'

        ; Creates a plot from the data in the given file name.

 MODIFICATION HISTORY:
        bmy, 22 Feb 2017: GAMAP VERSION 2.19
                          - Initial version

(See /n/home09/ryantosca/IDL/gamap2/benchmark/plot_masscons.pro)


PMID (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PMID   (function)

 PURPOSE:
        Given the pressures at the vertical edges of a model grid,
        return the pressures at the centers of the grid.

 CATEGORY:
        Atmospheric Sciences

 CALLING SEQUENCE:
        RESULT = PMID( EDGE )

 INPUTS:
        EDGE -> Vector of pressures or pressure-altitudes at
             the edges of the model grid [hPa]

 KEYWORD PARAMETERS:

 OUTPUTS:
        RESULT -> The vector of pressures at the grid centers [hPa]

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        The relationship between sigma centers and sigma edges is
        as follows:
   
              MID[N] = ( EDGE[N] + EDGE[N+1] ) / 2.0

        where EDGE[N] is the lower sigma edge, and EDGE[N+1]
        is the upper sigma edge of the box with center MID[N].

 EXAMPLE:
        Result = PMID( [ 1000.0, 800.0, 600.0, 400.0 ] )
        print, Result
            900.000      700.000      500.000

 MODIFICATION HISTORY:
        bmy, 17 Jun 1999: VERSION 1.00
        bmy, 22 Oct 1999: VERSION 1.44
                          - Now use SHIFT to compute the average
                            between successive edges
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/pmid.pro)


PROFILES

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PROFILES

 PURPOSE:
        Creates longitudinal difference profiles of tracers along 
        15S latitude and 42N latitude.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        PROFILES, FILES, ALTRANGE, TAUS, TRACERS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "old" and "new" GEOS-Chem model versions
             that are to be compared. 

        ALTRANGE -> A 2-element vector containing the altitude range
             (in km) of the data to be plotted.  ALTRANGE will be 
             passed to CTM_EXTRACT.  

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        TRACERS -> The list of transported tracers (i.e. diagnostic
             category "IJ-AVG-$").

        VERSIONS -> A 2-element vector containing the version
             numbers for the "old" and "new" GEOS-Chem model
             versions.

 KEYWORD PARAMETERS:
        /DO_FULLCHEM -> Set this switch to plot the chemically
             produced OH in addition to the advected tracers.

        /DYNRANGE -> Set this switch to create plots using the whole
             dynamic range of the data.  Default is to restrict
             the plot range to predetermined values as returned
             by routine GET_DIFF_RANGE.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output 
             to a file whose name is specified by this keyword.
             Default is "tracer_ratio.pro".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Included:
        =======================================================
        PlotProfile

        External Subroutines Required:
        =======================================================
        CLOSE_DEVICE                  COLORBAR_NDIV (function)   
        CTM_EXTRACT      (function)   CTM_GET_DATA 
        GET_DIFF_RANGE   (function)   GETMODELANDGRIDINFO   
        EXTRACT_FILENAME (function)   MULTIPANEL                 
        CHKSTRU          (function)   MYCT                          
        OPEN_DEVICE                   TVMAP                         
        UNDEFINE   
     
 REQUIREMENTS:
        References routines from the GAMAP package.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLE:
        FILES    = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
        ALTRANGE = [ 0, 20 ]
        TAUS     = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
        TRACERS  = INDGEN( 43 ) + 1
        VERSIONS = [ 'v7-04-10', 'v7-04-11' ]

        PROFILES, FILES, ALTRANGE, TAUS, TRACERS, VERSIONS, $
             /DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'

             ; Creates ratio plots of two GEOS-CHEM versions
             ; (in this case v7-04-11 / v7-04-10) for July 2001.
             ; Output is sent to PostScript file "myplot.ps".
             ; The min and max of the data on each plot panel is 
             ; restricted to pre-defined values returned by
             ; function GET_DIFF_RANGE.
             
        PROFILES, FILES, ALTRANGE, TAUS, TRACERS, VERSIONS, $
             /DYNRANGE, /PS, OUTFILENAME='myplot.ps'

             ; Same as the above example, but the min & max of 
             ; each plot panel corresponds to the dynamic range
             ; of the data (centered around zero)

 MODIFICATION HISTORY:
        bmy, 14 Nov 2007: VERSION 1.01
                          - Initial version
        bmy, 20 Nov 2007: VERSION 1.02
                          - Now draw out-of-bounds triangles for
                            the colorbar when using the "small"
                            data ranges.  New feature of TVMAP.
        bmy, 08 Feb 2011: VERSION 1.03
                          - Now display in the top-of-plot title
                            if the dynamic range option is used.
        bmy, 08 Jun 2011: VERSION 1.04
                          - Added /DO_FULLCHEM keyword
                          - Now call COLORBAR with the UPOS keyword 
                            to place the colorbar unit string properly
                          - Now use appropriate settings for creating
                            plots w/ the full dynamic range (/DYNRANGE)
                          - Now restore !MYCT sysvar to previous
                            settings upon exiting the program
                          - Better adjust colorbar position for /PS
        bmy, 11 May 2012: GAMAP VERSION 2.16
                          - Modify the error check to allow
                            comparison of equivalent vertical grids
                            (e.g. GEOS-5, MERRA, GEOS-5.7) even if
                            the model names differ
        mps, 04 Mar 2016: - Include MERRA2 in the check for equivalent
                            vertical grids
 

(See /n/home09/ryantosca/IDL/gamap2/benchmark/profiles.pro)


PROGRAM_DIR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PROGRAM_DIR

 PURPOSE:
        Given a file, returns the directory in which the file resides.

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
        RESULT = PROGRAM_DIR( FILE [, Keywords ] )

 INPUTS:
        FILE -> Name of the file for which a directory search
             will be performed.

 KEYWORD PARAMETERS:
        /FULL_PATH -> Set this switch to return the directory
             name as an absolute path (e.g. /users/home/IDL/) 
             instead of a relative path (e.g. ~/IDL).

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        EXPAND_PATH      (function) 
        EXTRACT_FILENAME (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) Unix is case-sensitive.  It is recommended to keep 
            file names in all lowercase on Unix to avoid file 
            search confusion.

 EXAMPLES:
        (1) 
        PRINT, PROGRAM_DIR( 'myct.pro' )
           ~/IDL/tools/

            ; Finds the directory in which "myct.pro" resides.

        (2)
        PRINT, PROGRAM_DIR( 'myct.pro', /FULL_PATH )
           /users/ctm/bmy/IDL/tools

            ; Same as the above example, but this time returns
            ; the directory as an absolute path name.


 MODIFICATION HISTORY:
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/file_io/program_dir.pro)


PULL_PL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PULL_PL

 PURPOSE:
        Copies datablocks from NRT bpch files for category PORL-L=$
        to a separate file for archival purposes.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        PULL_PL, DATE

 INPUTS:
        DATE -> YYYYMMDD of the date for which to extract data.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        =============================================
        CTM_GET_DATA    CTM_MAKE_DATAINFO  (function)
        CTM_WRITEBPCH   GETMODELANDGRIDINFO

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        PULL_PL, 20051201
             - Extracts PORL-L=$ data for 2005/12/01.

 MODIFICATION HISTORY:
  rch & bmy, 06 Dec 2005: VERSION 1.00
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/pull_pl.pro)


PWD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        PWD

 PURPOSE:
        Print current working directory

 CATEGORY:
        General

 CALLING SEQUENCE:
        PWD [,result]

 INPUTS:
        none

 KEYWORD PARAMETERS:
        none

 OUTPUTS:
        RESULT -> (optional) string containing the current directory

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        Set !QUIET to 1 if you only want to return the working directory
        but no screen output.

 EXAMPLE:
        PWD
             ; Prints current directory.

 MODIFICATION HISTORY:
        mgs, 23 Dec 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/general/pwd.pro)


QQNORM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        QQNORM

 PURPOSE:
        Procedure: sort the data, assign actual "probability" and 
        calculate the expected deviation from the mean.

 CATEGORY:
        Math & Units

 CALLING SEQUENCE:
        RESULT = QQNORM( DATA )

 INPUTS:
        DATA -> Vector containing the data values.  NOTE: DATA 
             will be sorted in ascending order and then returned.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> Array where each element contains the expected
              deviation from the mean of DATA.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        RESULT = QQNORM( DATA )
            ; Computes expected deviation from the mean.         

 MODIFICATION HISTORY:
            mgs, 14 Dec 1998: VERSION 1.0
                              - extracted from w_calc.pro
  pip, clh, bmy, 10 Oct 2002: TOOLS VERSION 1.52
  amf, swu, bmy, 10 Oct 2006: TOOLS VERSION 2.05
                              - Now use simpler algorithm from
                                Arlene Fiore's code
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/math_units/qqnorm.pro)


RATIOS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        RATIOS

 PURPOSE:
        Creates ratio plots ( New/Old ) for GEOS-Chem tracers and OH. 

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        RATIOS, FILES, LEVELS, TAUS, VERSIONS, [, Keywords ]

 INPUTS:
        FILES -> A 2-element vector containing the names of files
             from the "old" and "new" GEOS-Chem model versions
             that are to be compared. 

        LEVELS -> A 4-element vector containing the level indices
             for the GEOS-Chem surface layer and 500 hPa layer.
             for both models (e.g. SFC_1, SFC_2, 500_1, 500_2).
             NOTE: This is in Fortran notation (starting from 1!)

        TAUS -> A 2-element vector contaning TAU values (hours GMT
             from /1/1985) corresponding to the "old" and "new"
             GEOS-Chem model versions.

        TRACERS -> The list of transported tracers (i.e. diagnostic
             category "IJ-AVG-$").

        VERSIONS -> A 2-element vector containing the version
             numbers for the "old" and "new" GEOS-Chem model
             versions.

 KEYWORD PARAMETERS:
        /DO_FULLCHEM -> Set this switch to plot the chemically
             produced OH in addition to the advected tracers.

        /DYNRANGE -> Set this switch to create plots using the whole
             dynamic range of the data.  Default is to restrict
             the plot range from 0.5 to 2.0.

        /PS -> Set this switch to generate PostScript output.

        OUTFILENAME -> If /PS is set, will write PostScript output 
             to a file whose name is specified by this keyword.
             Default is "tracer_ratio.pro".

 OUTPUTS:
        None

 SUBROUTINES:
        Internal Subroutines Included:
        ===========================================
        ComputeRatios   PlotRatio

        External Subroutines Required:
        ============================================
        OPEN_DEVICE     CLOSE_DEVICE
        MULTIPANEL      COLORBAR_NDIV    (function)
        TVMAP           UNDEFINE 
        CTM_GET_DATA,   EXTRACT_FILENAME (function)     
     
 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.
        
 NOTES:
        (1) Meant to be called from BENCHMARK_1MON.

 EXAMPLES:
        FILES    = [ 'ctm.bpch.v7-04-10', 'ctm.bpch.v7-04-11' ]
        LEVELS   = [ 1, 1, 13, 13 ]
        TAUS     = [ NYMD2TAU( 20010701 ), NYMD2TAU( 20010701 ) ]
        TRACERS  = INDGEN( 43 ) + 1
        VERSIONS = [ 'v7-04-10', 'v7-04-11' ]
 
        RATIOS, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
             /DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'

             ; Creates ratio plots of two GEOS-CHEM versions
             ; (in this case v7-04-11 / v7-04-11) for July 2001.
             ; Output is sent to PostScript file "myplot.ps".
             ; The min & max of the data will be fixed at -/+ 5%.

        RATIOS, FILES, LEVELS, TAUS, TRACERS, VERSIONS, $
             /DYNRANGE, /PS, OUTFILENAME='myplot.ps'

             ; Same as above, but this time the full dynamic range
             ; of the data will be displayed.


 MODIFICATION HISTORY:
        bmy, 14 Nov 2007: VERSION 1.01
                          - based on older routine "tracer_ratio.pro"
        bmy, 20 Nov 2007: VERSION 1.02
                          - Now draw out-of-bounds triangles for
                            the colorbar when using the "small"
                            data ranges.  New feature of TVMAP.;
        bmy, 07 May 2008: VERSION 1.03
                          - Now allow for comparing models on 2
                            different vertical grids.
        bmy, 08 Feb 2011: VERSION 1.04
                          - Now display in the top-of-plot title
                            if the dynamic range option is used.
        bmy, 08 Jun 2011: VERSION 1.05
                          - Now create log plots in range 0.5 - 2.0
                          - Added /DO_FULLCHEM keyword
                          - Adjust colorbar so that the 0.9 - 1.1
                            range shows up in white.
                          - Now restore !MYCT sysvar to previous
                            settings upon exiting the program
                          - Better adjust colorbar position for /PS
        mps, 29 Mar 2013: - Now plot HO2 ratios
 

(See /n/home09/ryantosca/IDL/gamap2/benchmark/ratios.pro)


READDATA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READDATA

 PURPOSE:
        This subroutine reads in  almost any ASCII file and returns 
        two arrays containing the names of the variables and their 
        values.  The data is read line by line or in one step if 
        LINES is specified.

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
       READDATA, FILENAME, DATA, HEADER [, NCOL, NDAT ] [, KEYWORDS ]

 INPUTS:
       FNAME -> Name of fname to be read, e.g. 'flight12.dat'

 KEYWORD PARAMETERS:
       COLS -> number of columns to be read (must be used if no header 
             is read in, i.e. /NOHEADER is specified). Can be used
             to read in a subset of columns if the file contains a header
             line with variable names (i.e. if *not* /NOHEADER).

       LINES -> number of lines to be read (not much faster for large
             data sets, but allows to read in a subset of the data)

       DELIM -> Separator between names in the header (default=',')

       SKP1 -> Number of lines to be skipped before the variable 
             definition (default=0)

       SKP2 -> .. after the variable definition (default=0)

       SKIP -> same as SKP1 (SKP1 will overwrite SKIP. SKIP may be
             not longer supported in future versions !)

       AUTOSKIP  -> for files that state the number of comment lines 
             in the first line. If keyword NOHEADER is not set, READDATA 
             expects a list of variable names as last comment line.
             AUTOSKIP overrides settings of SKP1 and SKP2.

       TRANSPOSE -> Normally, 1st array dimension is for variables, 
             2nd is for observations. /TRANSPOSE will reverse that 
             order (see note).

       NOHEADER -> don't read a header (COLS must be specified in 
             this case !)

       NODATA -> don't read data (stop after header). DATA parameter 
             must still be specified !

       COMMENTS -> returns string array of all the comment lines in 
             the data file for later use

       MAXCOMMENTS -> limits maximum number of comment lines to be 
             retrieved (default: 255)

       QUIET -> Normally, READDATA prints the number of variables 
             found and  number of data lines read.  Use this option 
             to suppress all output.

       /DOUBLE -> If set, will return data in double precision.
             (Default is to return data in single precision.)

       NAN_REPLACEMENT -> Allows you to provide a replacement value
             for the following types of missing data fields: NaN,
             nan, NA, na, Infinity, infinity, Missing, missing.

 OUTPUTS:
       DATA -> data array that was read in

       NAMES -> string array of names in header

       NCOL -> integer containing the number of columns

       NDAT -> long integer containing the number of observations

       COMMENTS  -> string array containing all header lines.  
             If AUTOSKIP is set, skp1, and skp2 will contain the 
             actual amount of lines to skip (e.g. for re-storing 
             header information in EXPLORE)

 SUBROUTINES:
      External Subroutines Required:
      ==============================
      OPEN_FILE
      STRBREAK (function)
      USAGE

 REQUIREMENTS:
      None

 NOTES:
      Default of the returned DATA array is: 1st index = variable, 
      2nd index = observation. Use the /TRANSPOSE option for reverse order

      If /NOHEADER is used, then COLS must specify the actual number of
      data columns in FNAME. Otherwise it can be used to read a subset of 
      the data from 0 to cols-1 columns.

      IDL Parameters are optional. Of course, you should not readdata without
      passing a DATA argument, but you can ignore the HEADER,NCOL, and NDAT 
      params.

 EXAMPLES:
      (1)
      READDATA,'mydata.dat',DATA,HEADER,DELIM=' ',SKIP=5

      ... will read in the ASCII file mydata.dat and store the data in DATA.
      The header information will be stored in HEADER. The header items are
      seperated by blank spaces, and the first 5 lines should be ignored.
      To pick a certain variable afterwards, type:
      VAR = DATA(WHERE HEADER EQ 'MYVAR'),*)

      (2)
      READDATA,'noheader.dat',DATA,DELIM=';',NCOLS=3

      ... will read a three column ASCII file with no header information.
      You can manually make up a header with 
      HEADER = ['VAR1','VAR2','VAR3'] 
      or you can pass the HEADER argument and receive ['X1','X2','X3'] as
      header.

      (3)
      READDATA,'mydata.dat',DATA,HEADER,DELIM=' ',SKP1=5,LINES=60,COLS=4, $
         COMMENTS=COMMENTS

      ... will read in 60 lines and 4 columns of the ASCII file mydata.dat 
      and return 6 comment lines in COMMENTS (5 + variable names)


 MODIFICATION HISTORY:
         mgs  03/12/1997: - last update : 05/22/97
         mgs 01 Aug 1997: - added template
         mgs 15 Sep 1997: - added LINES option and removed some twitch in the
                            handling of TRANSPOSE. Unfortunately,
                            LINES does not improve the speed as
                            desired, but you can restrict the reading to
                            a smaller subset of the data.
         mgs 26 Sep 1997: MAJOR REVIEW
                          - bug fixes in noheader option
                          - bug fixes in COLS and NCOL handling
                          - removed units option and created comments 
                            keyword instead.  program now reads in
                            all header lines into a string array
                            including the variable names line.
                          - automatic generation of a header if 
                            /NOHEADER is specified
         mgs 06 Nov 1997: - Added AUTOSKIP option for easier reading 
                            of e.g. NASA formatted files.
         mgs 01 Dec 1997: added MAXCOMMENTS keyword and limit
                          - skp1 now returns correct amount if
                            autoskip is set
         mgs 30 Dec 1997: added NODATA keyword
         mgs 21 Aug 1998: now uses open_file routine to allow wildcards
         bmy 12 May 2005: added /DOUBLE keyword to force double precision
  bmy & phs, 21 Aug 2007: GAMAP VERSION 2.10
                          - Now use STRBREAK, which is version independent
                          - Remove internal function USE_READDATA; we
                            now call USAGE to display program options
                            if the wrong # of arguments are passed
                          - Updated comments
        bmy, 12 Dec 2012: GAMAP VERSION 2.16 
                          - Now give the user the option to read in
                            data as characters and then to strip out
                            strings such as "NaN" or "NA" via the
                          - NAN_REPLACEMENT keyword

(See /n/home09/ryantosca/IDL/gamap2/file_io/readdata.pro)


READ_BDT0001

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READ_BDT0001

 PURPOSE:
        Read a simple binary data file with size information
        and variable names and units (format BDT0001).

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
        READ_BDT0001,filename,data,vardesc,nvars,nlines [,keywords]

 INPUTS:
        FILENAME -> Name of the file to read or a file mask that
            will be used in the PICKFILE dialog (see OPEN_FILE)
            If FILENAME is a named variable, the actual filename
            will be returned and replace a template.

 KEYWORD PARAMETERS:
        NAMES -> a named variable will contain a string array with
            NVARS variable names

        UNITS -> ... a string array with NVARS physical units

        COMMENTS -> A named variable that will return comment lines
            stored in the data file. NOTE that comments are not
            saved in vardesc.

        DEFAULTMASK -> Default mask for PICKFILE dialog (see
            OPEN_FILE).

        FILE_ID -> A named variable will return the file identifier
            string (80 characters). This string will be returned
            even if the file is of wrong type and no data was read.

        TYPE -> A named variable will contain the data type

        _EXTRA keywords are passed on to OPEN_FILE

 OUTPUTS:
        DATA -> an array with NLINES * NVARS values. The type of the
            data array depends on the information stored in the file.

        VARDESC -> A variable descriptor structure (see GTE_VARDESC)

        NVARS -> number of variables in file

        NLINES -> number of data lines


 SUBROUTINES:

 REQUIREMENTS:
        Uses OPEN_FILE

 NOTES:
        See also WRITE_BDT0001

        Format specification:
        file_ID  :      80 byte character string
        NVARS, NLINES, NCOMMENTS, TYPE : 4 byte integer (long)
        NAMES :         NVARS*40 byte character string
        UNITS :         NVARS*40 byte character string
        COMMENTS :      NCOMMENTS records of 80 byte length
        DATA  :         8 byte float (double) array NLINES*NVARS

 EXAMPLE:
        READ_BDT0001,'~/tmp/*.bdt',data,vardesc,comments=comments

        ; Will read a file that the user selects with the PICKFILE
        ; dialog. No information about the actual filename is
        ; returned.

        FILE = '~/tmp/*.bdt'
        READ_BDT0001,FILE,data,vardesc,nvars,nlines,file_id=file_id

        ; Does the same thing, but this time FILE will contain the
        ; actual filename. The number of variables and lines are
        ; returned in NVARS and NLINES, the file identifier string
        ; is returned in file_id

 MODIFICATION HISTORY:
        mgs, 24 Aug 1998: VERSION 1.00
        mgs, 23 Dec 1998: VERSION 1.10:
                          - DATA now undefined if unsuccessful
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 02 Apr 2008: GAMAP VERSION 2.12
                          - Now read data as big-endian

(See /n/home09/ryantosca/IDL/gamap2/file_io/read_bdt0001.pro)


READ_BIN AND PLOT_BIN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READ_BIN  and  PLOT_BIN

 PURPOSE:
        Read a simple binary 2-D file. The file must be F77 
        unformatted and contain the XDIM and YDIM information
        as LONG integers in the first record.

 CATEGORY:
        File & I/O

 CALLING SEQUENCE:
        READ_BIN,FILENAME,DATA [,keywords]
        PLOT_BIN,DATA [,keywords]

 INPUTS:
        FILENAME -> Name of the file to read

        DATA (for PLOT_BIN) -> The data array as read with READ_BIN 

 KEYWORD PARAMETERS:
        XDIM, YDIM -> return the dimensions of the data set.

        _EXTRA -> used to pass extra keywords to OPEN_FILE. Probably
              only useful with /SWAP_ENDIAN.

        /PLOT -> Call PLOT_BIN directly.

        (for PLOT_BIN)
        MIN, MAX -> minimum and maximum to be used for conversion of
              data to a byte array for display with TVIMAGE

        TOP -> top value for BYTSCL

        CT -> colortable numebr to use

        /MAP -> set this keyword to overlay a map (isotropic cylindrical
              projection)

 OUTPUTS:
        DATA -> The data array returned from READ_BIN

 SUBROUTINES:
        Uses OPEN_FILE and TVIMAGE

 REQUIREMENTS:
        None

 NOTES:
        Rather primitive program but demonstrates the principle use
        of binary data files and TVIMAGE.

 EXAMPLES:
        READ_BIN,'~/mydata/*.bdat', DATA
        PLOT_BIN, DATA, MIN=MIN(DATA,MAX=M), MAX=M

        ; is equivalent to 
        READ_BIN, '~/mydata/*.bdat', DATA, /PLOT

 MODIFICATION HISTORY:
        mgs, 15 Jan 1999: VERSION 1.00
        mgs, 15 Jun 1999: - added header
                          - added PLOT keyword and _EXTRA
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
        bmy, 02 Apr 2008: GAMAP VERSION 2.12
                          - Now read data as big-endian
             

(See /n/home09/ryantosca/IDL/gamap2/file_io/read_bin.pro)


READ_CONC_RANGE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READ_CONC_RANGE

 PURPOSE:
        Reads a file containing default plotting range for given 
        GEOS-Chem tracers.  This will be used to create absolute 
        difference plots for GEOS-Chem benchmarking.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        READ_CONC_RANGE, INPUTFILE

 INPUTS:
        INPUTFILE -> Name of the file that contains the default
             plotting ranges for each GEOS-Chem tracer.  Default
             is "diff_range.1mon".

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ================================
        OPEN_FILE   STRBREAK (function)

 REQUIREMENTS:
        READ_CONC_RANGE must be called first to read the file with
        default plotting ranges.  This is normally done at the top
        of driver routine BENCHMARK_1MON.  After this has been done,
        function GET_CONC_RANGE may be used to return the default
        plotting range from within another program.

 NOTES:
        (1) Meant to be used in conjunction with the GEOS-Chem 
            benchmark plotting codes.
 
        (2) Default ranges for each tracer are read from a file by 
            this routine and stored in the GDR common block.

 EXAMPLE:
        READ_CONC_RANGE, 'conc_range.1mon'
        GET_CONC_RANGE, 'NOx', THIS_LOBOUND, THIS_HIBOUND, UNIT
        PRINT*, THIS_LOBOUND, THIS_HIBOUND, UNIT
            -0.100000  0.100000, ppbv
   
            ; Prints the default plotting range for NOx

 MODIFICATION HISTORY:
        bmy, 05 Sep 2012: VERSION 1.00
        bmy, 24 Jan 2014: GAMAP VERSION 2.17
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/benchmark/read_conc_range.pro)


READ_DIFF_RANGE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READ_DIFF_RANGE

 PURPOSE:
        Reads a file containing default plotting range for given 
        GEOS-Chem tracers.  This will be used to create absolute 
        difference plots for GEOS-Chem benchmarking.

 CATEGORY:
        Benchmarking

 CALLING SEQUENCE:
        READ_DIFF_RANGE, INPUTFILE

 INPUTS:
        INPUTFILE -> Name of the file that contains the default
             plotting ranges for each GEOS-Chem tracer.  Default
             is "diff_range.1mon".

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ================================
        OPEN_FILE   STRBREAK (function)

 REQUIREMENTS:
        READ_DIFF_RANGE must be called first to read the file with
        default plotting ranges.  This is normally done at the top
        of driver routine BENCHMARK_1MON.  After this has been done,
        function GET_DIFF_RANGE may be used to return the default
        plotting range from within another program.

 NOTES:
        (1) Meant to be used in conjunction with the GEOS-Chem 
            benchmark plotting codes.
 
        (2) Default ranges for each tracer are read from a file by 
            this routine and stored in the GDR common block.

 EXAMPLE:
        READ_DIFF_RANGE, 'diff_range.1mon'
        PRINT, GET_DIFF_RANGE( 'NOx' )
            -0.100000  0.100000
   
            ; Prints the default plotting range for NOx

 MODIFICATION HISTORY:
        bmy, 14 Nov 2007: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/benchmark/read_diff_range.pro)


READ_EPTOMS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READ_EPTOMS

 PURPOSE:
        Read Earth Probe TOMS data as retrieved from 
        http://jwocky.gsfc.nasa.gov and store them as datainfo
        records so that they can be displayed with GAMAP.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        READ_EPTOMS [,DATA] [,keywords]

 INPUTS:

 KEYWORD PARAMETERS:
        FILENAME -> filename of TOMS data

        DATAINFO -> A named variable will return the newly
             created daatinfo structure.

        MODELINFO, GRIDINFO -> named variables will return 
             the "model" and grid information for the EP-TOMS
             data. The grid is a 2-dimensional "generic" grid.

 OUTPUTS:
        DATA -> contains 2D array with EP-TOMS data (for use without
             GAMAP).

 SUBROUTINES:
        uses open_file, ctm_type, ctm_grid, ctm_make_datainfo

 REQUIREMENTS:
        None

 NOTES:
        For tropical ozone in March, I used the following options
        in the call to GAMAP:
           myct,27,ncol=32,bot=20,range=[0.15,0.8]
           c_lev = [150,200,220,230,240,250,260,270,280,  $
                    290,300,310,320,330,340,350,375,400]
           gamap,/nofile,c_lev=c_lev,c_col=[0,17,2*indgen(21)+18],  $
                    /cbar,mlinethick=2,ncolors=32,bottom=18,  $
                    cbmin=220,cbmax=400,div=10  [,frame0=4]
           
           (the frame0 keyword is used to save GIF files)

 EXAMPLE:
        read_eptoms,file='/data/pem-tb/satellite/eptoms/*.ept'
        gamap [... options]

 MODIFICATION HISTORY:
        mgs, 02 Apr 1999: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/read_eptoms.pro)


READ_H5DATASET

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READ_H5DATASET

 PURPOSE: 
        Convenience routine to read dataset variables 
        from Hierarchical Data Format version 5 (HDF5) files.
        Also works for HDF-EOS files!

 CATEGORY:
        File & I/O, Scientific Data Formats

 CALLING SEQUENCE:
        DATAFIELD = READ_H5DATASET( FID, DATASET_NAME )

 INPUTS:
        FID -> HDF5 File ID, as returned by routine H5F_OPEN

        DATASET_NAME -> Name of the scientific dataset variable that
             you want to extract from the file.  

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        DATAFIELD -> Array containing extracted data from the HDF file.

 SUBROUTINES:
        None

 REQUIREMENTS:
        Need to use a version of IDL w/ HDF5 library installed.

 NOTES:
        From Trevor Beck (trevor.beck@noaa.gov) for GOME-2.
        
 EXAMPLE:

        ; Specify the file name
        FILE = 'GOME_xxx_1B_M02_20070105012056Z_20070105030556Z_R_O_20080613081807Z.337p4_356p1.brs.hcho.he5'

        ; Make sure the file is a HDF5 file
        IF ( H5F_IS_HDF5( FILE ) eq 0 ) then MESSAGE, 'Not an HDF-5 file!'

        ; Open the HDF file and get the file ID # (FID)
        FID = H5F_OPEN( FILE ) 
        IF ( FID lt 0 ) then MESSAGE, 'Error opening file!'

        ; Read the AMF field from disk
        ; NOTE: the swath name is "Column"
        AMF = READ_H5DATASET( FID, "/Column/Amf" )

        ; Close the file 
        H5_CLOSE, FID

 MODIFICATION HISTORY:
        bmy, 28 May 2009: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/file_io/read_h5dataset.pro)


READ_MLD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READ_MLD

 PURPOSE:
        Read Ocean mixed layer depth data as retrieved from 
        http://www.nodc.noaa.gov/OC5/mixdoc.html and store 
        them as datainfo records so that they can be displayed 
        with GAMAP.

 CATEGORY:
        GAMAP Utilities, GAMAP Data Manipulation

 CALLING SEQUENCE:
        READ_MLD [,DATA] [,keywords]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        FILENAME -> filename of MLD data

        DATAINFO -> A named variable will return the newly
             created daatinfo structure.

        MODELINFO, GRIDINFO -> named variables will return 
             the "model" and grid information for the EP-TOMS
             data. The grid is a 2-dimensional "generic" grid.

 OUTPUTS:
        DATA -> contains 2D array with mixed layer depth data 
             (for use without GAMAP).

 SUBROUTINES:
        uses open_file, ctm_type, ctm_grid, ctm_make_datainfo

 REQUIREMENTS:
        None

 NOTES:
        In the call to GAMAP you must use the /NOFILE option.

 EXAMPLE:
        READ_MLD, FILE='~/download/mixed_layer_depth/mld*'
        GAMAP, /NOFILE, ...

 MODIFICATION HISTORY:
        mgs, 30 Jun 1999: VERSION 1.00 (derived from read_eptoms)
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/gamap_util/read_mld.pro)


READ_SONDE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READ_SONDE

 PURPOSE:
        Read climatological ozone sonde data as compiled by 
        Jennifer A. Logan at Harvard University.
        If successful, the procedure returns a structure 
        with all information from a sondeXXX.* file.
        Ozone concentrations are automatically converted to ppbv.
        The data can be downloaded via ftp from io.harvard.edu
        path= pub/exchange/sonde. Please read the README files!

 CATEGORY:
        Atmospheric Sciences, File & I/O

 CALLING SEQUENCE:
        READ_SONDE,filename,data

 INPUTS:
        filename -> Name of the file containing the sonde data.
            This parameter can contain wildcards (*,?) in which case
            a file selection dialog will be displayed. If filename
            is a variable, it will be replaced by the actual filename
            that was opened.

 KEYWORD PARAMETERS:
        MBAR -> return ozone concentrations in mbar rather than ppbv

        STATIONS -> Can be used either as input or output for a list
            of station codes, locations and names as retrieved with
            procedure read_sondestations. STATIONS must be specified
            (or is returned) as an array of structures.

 OUTPUTS:
        DATA -> A structure containing the following fields:
                TITLE           STRING    'Ozone sonde data'
                STATION         STRING    
                STATIONCODE     INT       
                TIMERANGE       STRING    

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/read_sonde.pro)


READ_SONDESTATIONS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READ_SONDESTATIONS

 PURPOSE:
        Retrieve station codes and geographical locations for 
        ozone sonding stations as listed in file station.codes
        from Jennifer A. Logan's ozone sonde climatology.
        This routine is called from procedure READ_SONDE, and
        only needs to be called explicitely if the station.codes
        file resides neither in the current directory nor the 
        directory of the sonde data files.
        The procedure will read the file station.codes once then
        store the information in a common block for later use.

 CATEGORY:
        Atmospheric Sciences, File & I/O

 CALLING SEQUENCE:
        READ_SONDESTATIONS,stations [,filename]

 INPUTS:
        FILENAME (optional) -> if given, it specifies the path and filename
              of the file that is normally called station.codes.
              FILENAME may contain wildcards (*,?) in which case a 
              file selector dialog is displayed. 

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        STATIONS -> An array with structures containing the stations
              codes (integer), latitude, longitude, altitude (float),
              amd name (string). 

 SUBROUTINES:
        Uses OPEN_FILE and EXTRACT_FILENAME (used in OPEN_FILE)

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        read_sondestations,stations,'station.codes'
        ; if called for the first time, reads file station.codes
        ; and returns information for all stations in stations.
        ; NOTE: In this case, the filename argument could have been
        ; omitted.


 MODIFICATION HISTORY:
        mgs, 02 Nov 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/atm_sci/read_sondestations.pro)


RECTANGLE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        RECTANGLE

 PURPOSE:
        Converts a vector with corner coordinates into X and Y 
        vectors that can be used with PLOTS, POLYFILL, or similar
        IDL plotting commands.
     
 CATEGORY:
        Plotting

 CALLING SEQUENCE:
        RECTANGLE, CORNERS, XVEC, YVEC [, Keywords ]

 INPUTS:
        CORNERS -> A 1-D vector with [ X0, Y0, X1, Y1 ] coordinates.
             (X0,Y0) is the bottom left corner of the plot region and
             (X1,Y1) is the top right corner of the plot region.

 KEYWORD PARAMETERS:
        EXPAND -> A value that will be used to expand the size 
             of the rectangle by the same amount on all sides.
             Default is 0.
 
 OUTPUTS:
        XVEC -> A 1-D vector with the X-coordinates listed in the
             proper order for the POLYFILL or PLOTS commands.
 
        YVEC -> A 1-D vector with the X-coordinates listed in the
             proper order for the POLYFILL or PLOTS commands.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:         
        ; Get a plot position vector from MULTIPANEL
        MULTIPANEL, 2, POSITION=POSITION
        PRINT, POSITION
             0.112505   0.0874544  0.466255  0.956280

        ; Convert to X and Y vectors for PLOTS input
        RECTANGLE, POSITION, XPOINTS, YPOINTS
        PRINT, XPOINTS
             0.112505   0.466255   0.466255  0.112505  0.112505
        PRINT, YPOINTS
             0.0874544  0.0874544  0.956280  0.956280  0.0874544

        ; Call PLOTS to draw a box
        PLOTS, XPOINTS, YPOINTS, THICK=2, COLOR=1, /NORMAL

 MODIFICATION HISTORY:
        mgs, 13 Apr 1998: INITIAL VERSION
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments, cosmetic changes

(See /n/home09/ryantosca/IDL/gamap2/plotting/rectangle.pro)


REGRIDAVHRR_LAI

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDAVHRR_LAI

 PURPOSE:
        Regrids LAI from a 0.5 x 0.5 grid onto a
        CTM grid of equal or coarser horizontal resolution.
        
 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDAVHRR_LAI [, Keywords ]

 INPUTS:
        NONE

 KEYWORD PARAMETERS:
        YEAR (string) -> 4 character string for the year in process

        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the data will be regridded.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  RESOLUTION
             can be 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.

        OUTDIR -> Name of the directory where the output file will
             be written.  Default is './'.  

 OUTPUTS:
        Writes files:
             vegtype.global
             lai{MONTHNUM}.global
             lai.global.{YEAR}.bpch
  
 SUBROUTINES:
        External Subroutines Required:
        ===============================================
        CTM_TYPE   (function)   CTM_GRID (function)
        CTM_RESEXT (function)   CTM_GETWEIGHT
        CTM_Make_DataInfo (function)
        CTM_WriteBpch (fucntion)
        nymd2tau   (function)

        Internal Subroutines:
        ==============================
        RL_GETWEIGHT

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS directories

 NOTES:
        (1) Filenames are hardwired -- change as necessary
        (2) Regridding can take a while, especially at 1x1 resolution.

 EXAMPLE: 
        REGRIDAVHRR_LAI, '2000', MODELNAME='GEOS1', RES=2, OUTDIR='~/scratch/bmy/'
 
             ; Regrids 1 x 1 NOx fertilizer data onto the GEOS-1
             ; 2 x 2.5 resolution grid.  The output file will be
             ; written to the '~/scratch/bmy/' directory.

 MODIFICATION HISTORY:
        bmy, 04 Aug 2000: VERSION 1.00
                          - adapted from old FORTRAN code
        bmy, 15 Jan 2003: VERSION 1.01
                          - renamed to "regridh_lai.pro"
                          - renamed MODELNAME to OUTMODELNAME
                          - renamed RESOLUTION to OUTRESOLUTION
        tmf, 18 Jun 2003: VERSION 2.00
                          - adapted from bmy's "regridh_lai.pro"
                          - renamed to "regridavhrr.pro" 
                          - modified to read in Boston University's
                            0.5x0.5 AVHRR LAI    
                          - modified to output bpch files on CTM grid   
                            at the same time

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridavhrr_lai.pro)


REGRIDH_3D_OH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_3D_OH

 PURPOSE:
        Horiziontally regrids 3-D OH data from one CTM grid to another.
        
 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_3D_OH [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INFILENAME -> Name of the file containing OH data to be 
             regridded.  If not specified, then a dialog box 
             will ask the user to supply a file name.

        OUTFILENAME -> Name of file to contain the regridded OH.
             If not specified, then REGRID_3D_OH will use default 
             output file name "OH_3Dglobal.{MODELNAME}.{RESOLUTION}".

        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the data will be regridded.  If
             OUTMODELNAME is not specified, then REGRID_3D_OH will
             use the same model name as the input grid.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  RESOLUTION
             can be 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.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==============================================
        CTM_TYPE    (function)   CTM_GRID   (function)
        CTM_NAMEXT  (function)   CTM_RESEXT (function)
        CTM_REGRIDH (function)

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages

 NOTES:
        (1) The merged OH file is generated by "merge_oh.pro".

 EXAMPLE:
        REGRIDH_3D_OH, INFILENAME='OH_3Dglobal.geos3.2x25', $
                       OUTFILENAME='OH_3Dglobal.geos3.4x5', $
                       OUTRESOLUTION=4

             ; Horizontally regrids 3-D OH file from the GEOS-3
             ; 2 x 2.5 grid to the GEOS-3 4 x 5 grid.
              
 MODIFICATION HISTORY:
        bmy, 12 Sep 2002: VERSION 1.01
        bmy, 22 Dec 2003: VERSION 1.02
                          - totally rewritten for GAMAP v2-01
                          - now call PTR_FREE to free the memory
                          - added DIAGN keyword

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_3d_oh.pro)


REGRIDH_AEROSOL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_AEROSOL

 PURPOSE:
        Horiziontally regrids aerosol concentrations from
        one CTM grid to another.  Total mass is conserved.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_AEROSOL [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        MONTH -> Month of year for which to process data.
             Default is 1 (January).

        INFILENAME -> Name of the file containing data to be regridded.
             If omitted, then REGRIDH_AEROSOL will prompt the user to
             select a filename with a dialog box.

        OUTMODELNAME -> Name of the model grid onto which the data
             will be regridded.  If OUTMODELNAME is not specified, 
             REGRIDH_AEROSOL will use the same model name as the
             input grid.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  OUTRESOLUTION
             can be 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.

        OUTFILENAME -> Name of the file which will contain the
            regridded data.  

        DIAGN -> Diagnostic category of the data blocks that you 
            wish to regrid.  Default is "ARSL-L=$".

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        =================================================
        CTM_GRID    (function)   CTM_TYPE          (function)
        CTM_REGRIDH (function)   CTM_NAMEXT        (function)   
        CTM_RESEXT  (function)   CTM_MAKE_DATAINFO (function)
        CTM_GET_DATA             CTM_WRITEBPCH            
        GETMODELANDGRIDINFO      UNDEFINE

 REQUIREMENTS:
        References routines from the GAMAP and TOOLS packages.

 NOTES:
        (1) It is best to regrid the aeorsol dust files 1 month
            at a time, since it can take quite a while to regrid
            all of the tracers and levels.  One can then use GAMAP
            to concatenate the monthly files.

        (2) Aerosol concentrations are used in the photolysis code
            since they also cause the incoming solar radiation
            to be scattered out of a column.

        (3) Assumes that the input file is already in binary punch
            format.  To regrid data directly from Paul Ginoux's
            GOCART model simulations, use "regridh_dust.raw.pro".

 EXAMPLE:
        REGRIDH_AEROSOL, INFILENAME='aerosol.geos3.2x25', $
                         OUTFILENAME='aerosol.geos3.4x5', $
                         OUTRESOLUTION=4, MONTH=1
           
             ; Regrids January aerosol data from 2 x 2.5 GEOS-3
             ; resolution to 4 x 5 resolution.

 MODIFICATION HISTORY:
        bmy, 15 Jan 2003: VERSION 1.01
        bmy, 22 Dec 2003: VERSION 1.02
                          - rewritten for GAMAP v2-01
                          - call PTR_FREE to free the pointer heap memory 
                

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_aerosol.pro)


REGRIDH_AIRCRAFT_DATA

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_AIRCRAFT_DATA

 PURPOSE:
        Driver program for routines REGRIDH_AIRCRAFT_NOX 
        and REGRIDH_AIRCRAFT_FUEL.  

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_AIRCRAFT_DATA [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        /NOX -> Set this switch to regrid aircraft NOx data.

        /SOx -> Set this switch to regrid aircraft SOx data.

        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the NOx emissions will be regridded.
             Default is 'GEOS3'.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the NOX emissions will be regridded.  
             OUTRESOLUTION can be 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 is 1.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ================================
        REGRIDH_AIRCRAFT_NOX  (function)
        REGRIDH_AIRCRAFT_FUEL (function)

 REQUIREMENTS:
        References routines from the GAMAP and TOOLS packages.

 NOTES:
        Input & output directories are hardwired for now, 
        you can change them as is necessary.

 EXAMPLE:
        REGRIDH_AIRCRAFT_DATA, /NOX,                 $
                               OUTMODELNAME='GEOS3', $
                               OUTRESOLUTION=1
           
             ; Regrids aircraft NOx data from native
             ; resolution to GEOS-3 1x1 grid.

 MODIFICATION HISTORY:
        bmy, 23 Dec 2003: VERSION 1.01
                          - Initial version
        bmy, 28 Apr 2008: GAMAP VERSION 2.12
                          - Corrected typo at line 142
                                

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_aircraft_data.pro)


REGRIDH_AIRCRAFT_FUEL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_AIRCRAFT_FUEL

 PURPOSE:
        Regrids aircraft  emissions to GEOS-CHEM grid resolution.
        Can also trim to nested-grid resolution if necessary.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_AIRCRAFT_FUEL [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INFILENAME -> Name of the input file containing data to be 
             trimmed down to "nested" model grid resolution.  If 
             omitted, a dialog box will prompt the user to supply
             a filename.

        OUTFILENAME -> Name of the file that will contain trimmed
             data on the "nested" model grid.  OUTFILENAME will be
             in binary punch resolution.  If omitted, a dialog box 
             will prompt the user to supply a filename.

        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the NOx emissions will be regridded.
             Default is 'GEOS3'.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the NOX emissions will be regridded.  
             OUTRESOLUTION can be 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 is 1.

        XRANGE -> A 2-element vector containing the minimum and
             maximum box center longitudes which define the nested
             model grid. Default is [-180,180].

        YRANGE -> A 2-element vector containing the minimum and
             maximum box center latitudes which define the nested
             model grid. Default is [-180,180].

        /USE_SAVED_WEIGHTS -> Set this flag to tell CTM_REGRIDH to
             use previously-saved mapping weights.  Useful if you
             are regridding many files at once.  

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ================================================
        CTM_TYPE    (function)   CTM_GRID (function)
        CTM_REGRIDH (function)   OPEN_FILE

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages

 NOTES:

 EXAMPLE:
        REGRIDH_AIRCRAFT_FUEL, INFILENAME='total_1992_apr.kg_day.3d', $
                               OUTFILENAME='airapr.1x1',              $
                               OUTMODELNAME='GEOS3',                  $
                               OUTRESOLUTION=1,                       $
                               XRange=[-140,40],                      $
                               YRange=[10,60] 

             ; Regrids aircraft fuel emissions to a GEOS-3 1x1
             ; nested grid resolution given by 

 MODIFICATION HISTORY:
        bmy, 10 Apr 2003: VERSION 1.00
        bmy, 29 Nov 2006: VERSION 1.01
                          - Updated for SO2 output

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_aircraft_fuel.pro)


REGRIDH_AIRCRAFT_NOX

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_AIRCRAFT_NOX

 PURPOSE:
        Regrids aircraft NOx emissions to GEOS-CHEM grid resolution.
        Can also trim to nested-grid resolution if necessary.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_AIRCRAFT_NOX [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INFILENAME -> Name of the input file containing data to be 
             trimmed down to "nested" model grid resolution.  If 
             omitted, a dialog box will prompt the user to supply
             a filename.

        OUTFILENAME -> Name of the file that will contain trimmed
             data on the "nested" model grid.  If omitted, a dialog 
             box will prompt the user to supply a filename.

        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the NOx emissions will be regridded.
             Default is 'GEOS3'.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the NOX emissions will be regridded.  
             OUTRESOLUTION can be 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 is 1.

        /USE_SAVED_WEIGHTS -> Set this flag to tell CTM_REGRIDH to
             use previously-saved mapping weights.  Useful if you
             are regridding many files at once.  

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ================================================
        CTM_TYPE    (function)   CTM_GRID (function)
        CTM_REGRIDH (function)   OPEN_FILE

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages

 NOTES:

 EXAMPLE:
        REGRIDH_AIRCRAFT_NOX, InFileName='total_1992_apr.kg_day.3d', $
                              OutFileName='airapr.1x1',              $
                              OUTMODELNAME='GEOS3',                  $
                              OUTRESOLUTION=1,                       $
                              XRange=[-140,40],                      $
                              YRange=[10,60] 

             ; Regrids aircraft NOx emissions to a GEOS-3 1x1
             ; nested grid resolution given by 

 MODIFICATION HISTORY:
        bmy, 10 Apr 2003: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_aircraft_nox.pro)


REGRIDH_ANTHRO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_ANTHRO

 PURPOSE:
        Regrids 1 x 1 GEIA anthropogenic emissions "merge file" 
        onto a CTM grid of equal or coarser resolution.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_ANTHRO [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the data will be regridded.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  RESOLUTION
             can be 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.

        OUTFILENAME -> Name of the directory where the output file will
             be written.  Default is 'merge_nobiofuels.geos.{resolution}'.  

        /COPY -> If set, will just copy the 1 x 1 data from the ASCII
             file to a binary punch file format, w/o regridding.

 OUTPUTS:
        Writes to binary "merge" file:
             merge.{MODELNAME}.{RESOLUTION}.bpch

 SUBROUTINES:
        External Subroutines Required:
        =================================================
        CTM_GRID    (function)   CTM_TYPE   (function)
        CTM_BOXSIZE (function)   CTM_REGRID (function)
        CTM_RESEXT  (function)   CTM_MAKE_DATAINFO (function)


 REQUIREMENTS:
        References routines from the GAMAP and TOOLS packages.

 NOTES:
        (1) The path names for the files containing 1 x 1 data are
            hardwired -- change this number as is necessary.

        (2) Also assumes 10 fossil fuel emission species -- 
            change this number as is necessary.

        (3) Now use CTM_REGRIDH, which is much quicker since it
            saves the mapping weights

 EXAMPLE:
        REGRIDH_ANTHRO, OUTMODELNAME='GEOS_STRAT', $
                        OUTRESOLUTION=4 
           
             ; Regrids 1 x 1 GEIA fossil fuel emissions onto the
             ; 4 x 5 GEOS-STRAT grid.  The default output filename
             ; will be "merge_nobiofuels.geos.4x5".  

 MODIFICATION HISTORY:
        bmy, 01 Aug 2000: VERSION 1.00
        bmy, 14 Mar 2001: VERSION 1.01
                          - now write output to binary punch file format
        bmy, 30 Oct 2001: VERSION 1.02
                          - added /COPY keyword
                          - now can also copy data from 1 x 1 ASCII
                            file to binary punch file w/o regridding
        bmy, 09 Jan 2003: VERSION 1.03
                          - renamed to "regridh_anthro.pro"
                          - now uses CTM_REGRIDH, which is faster
                            when regridding multiple arrays

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_anthro.pro)


REGRIDH_AVHRRCO

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_AVHRRCO

 PURPOSE:
        Regrids AVHRR biomass burning emissions at 
        1 x 1 resolution to CTM resolution.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_AVHRRCO [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the data will be regridded.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  RESOLUTION
             can be 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.

        /COPY -> Use this switch to write the original 1 x 1
             biomass burning data to a binary punch file without
             regridding.  

 OUTPUTS:
        Writes binary punch files: 
             bioburn.avhrr.mon.{RESOLUTION}

 SUBROUTINES:
        External Subroutines Required:
        =================================================
        CTM_GRID      (function)   CTM_TYPE   (function)
        CTM_BOXSIZE   (function)   CTM_RESEXT (function)   
        CTM_NAMEXT    (function)   NYMD2TAU   (function)
        CTM_REGRIDH   (function)   CTM_WRITEBPCH

 REQUIREMENTS:
        References routines from the GAMAP and TOOLS packages.

 NOTES:
        (1) The path names for the files containing 1 x 1 data are
            hardwired -- change as necessary!

        (2) Sometimes you might have to close all files and call
            "ctm_cleanup.pro" in between calls to this routine.

        (3) Can be extended to other tracers than CO...

 EXAMPLE:
        REGRIDH_AVHRRCO, OUTMODELNAME='GEOS_STRAT', $
                         OUTRESOLUTION=4
           
             ; Regrids 1 x 1 AVHRR CO biomass burning data
             ; onto the 4 x 5 GEOS-STRAT grid

 MODIFICATION HISTORY:
  clh & bmy, 09 Jun 2000: VERSION 1.00
                          - adapted from "regrid_bioburn.pro"  
        bmy, 14 Nov 2002: VERSION 1.01
                          - now use CTM_REGRIDH for horiz regridding
                          - renamed to "regridh_avhrrco.pro"
        bmy, 23 Dec 2003: VERSION 1.02
                          - updated for GAMAP v2-01

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_avhrrco.pro)


REGRIDH_BIOBURN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_BIOBURN

 PURPOSE:
        Regrids 1 x 1 biomass burning emissions for various tracers
        onto a CTM grid of equal or coarser resolution.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_BIOBURN [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the data will be regridded.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  RESOLUTION
             can be 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.

        OUTDIR -> Name of the directory where the output file will
             be written.  Default is './'.  

        /COPY -> Use this switch to write the original 1 x 1
             biomass burning data to a binary punch file without
             regridding.  

        /SEASONAL -> Use this switch to process seasonal biomass
             burning files (instead of interannual variability
             files).

        YEAR -> 4-digit year number for which to regrid data 
             for interannual variability biomass burning.  YEAR
             is ignored if SEASONAL=0.  Default is 1996.
             
 OUTPUTS:
        Writes binary punch files: 
             bioburn.seasonal.{MODELNAME}.{RESOLUTION} OR
             bioburn.interannual.{MODELNAME}.{RESOLUTION}.YEAR  

 SUBROUTINES:
        Internal Subroutines:
        =================================================
        RBB_GetWeight     RBB_GetTracerInfo (function)
        RBB_ReadData

        External Subroutines Required:
        =================================================
        CTM_GRID      (function)   CTM_TYPE   (function)
        CTM_BOXSIZE   (function)   CTM_REGRID (function)
        CTM_NAMEXT    (function)   CTM_RESEXT (function)
        CTM_WRITEBPCH

 REQUIREMENTS:
        References routines from the GAMAP and TOOLS packages.

 NOTES:
        (1) The path names for the files containing 1 x 1 data are
            hardwired -- change as necessary!

        (2) Now assumes 13 biomass burning tracers -- change this
            number as necessary.

        (3) REGRID_BIOBURN now will produce output for a whole
            year in one file.  This is most convenient.

        (4) Sometimes you might have to close all files and call
            "ctm_cleanup.pro" in between calls to this routine.

 EXAMPLE:
        REGRIDH_BIOBURN, OUTMODELNAME='GEOS_STRAT', OUTRESOLUTION=4, $
                         /SEASONAL, WEIGHTFILE="weights_gen1x1_geos4x5.dat"
           
             ; Regrids seasonal 1 x 1 biomass burning data from February
             ; for CO (tracer #2) onto the 4 x 5 GEOS-STRAT grid, using
             ; mapping weights stored in "weights_gen1x1_geos4x5.dat".

 MODIFICATION HISTORY:
        bmy, 09 Jun 2000: VERSION 1.00
        bmy, 14 Jul 2000: VERSION 1.01
                          - adapted for 9 biomass burning tracers
        bmy, 24 Jul 2000: - added OUTDIR keyword
        bmy, 13 Feb 2001: VERSION 1.02
                          - added ALK4, CH4, CH3I as biomass 
                            burning tracers
        bmy, 15 Feb 2001: VERSION 1.03
                          - now use pre-saved mapping weights, 
                            for computational expediency
                          - now no longer use
                          - added /SEASONAL keyword to regrid
                            seasonal climatological biomass burning
                            instead of interannual variability BB.
        bmy, 28 Jun 2001: VERSION 1.04
                          - added COPY keyword, to just write a 1x1
                            binary punch file w/o regridding
        bmy, 02 Jul 2001: VERSION 1.05
                          - YEAR is now 4 digits
                          - now uses 1985 TAU values for seasonal
                            BB emissions and TAU values corresponding
                            to YEAR for interannual BB emissions
        bmy, 21 Sep 2001: VERSION 1.06
                          - modified to handle Randall's year 2000
                            files for interannual variability
                          - renamed MODELNAME to OUTMODELNAME and
                            RESOLUTION to OUTRESOLUTION
        bmy, 24 Sep 2001: VERSION 1.07
                          - now created TINFO array of structures
                            w/ information about each biomass tracer
                          - also save TOTB (CTM tracer #33) as g/cm2 
        bmy, 11 Feb 2002: VERSION 1.08
                          - now regrid all months of 2000
        bmy, 14 Nov 2002: VERSION 1.09
                          - renamed to REGRIDH_BIOBURN
                          - removed WEIGHTFILE keyword
        bmy, 23 Dec 2003: VERSION 1.10
                          - updated for GAMAP v2-01

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_bioburn.pro)


REGRIDH_BIOBURN2

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_BIOBURN2

 PURPOSE:
        Regrids 1 x 1 biomass burning emissions for various tracers
        onto a CTM grid of equal or coarser resolution.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_BIOBURN [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the data will be regridded.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  RESOLUTION
             can be 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.

        OUTFILENAME -> 

        DIAGN -> 
             
 OUTPUTS:
        Writes binary punch files: 
             bioburn.seasonal.{MODELNAME}.{RESOLUTION} OR
             bioburn.interannual.{MODELNAME}.{RESOLUTION}.YEAR  

 SUBROUTINES:

        External Subroutines Required:
        =================================================
        CTM_GRID   (function)   CTM_TYPE   (function)
        CTM_REGRID (function)   CTM_NAMEXT (function)   
        CTM_RESEXT (function)   CTM_WRITEBPCH
        UNDEFINE

 REQUIREMENTS:
        References routines from the GAMAP and TOOLS packages.

 NOTES:
        none

 EXAMPLE:
        REGRIDH_BIOBURN, INFILENAME='biomass.seasonal.generic.1x1', $
                         OUTMODELNAME='GEOS4'
                         OUTRESOLUTION=2 $
                         OUTFILENAME='biomass.seasonal.geos.2x25'GEOS_STRAT', 
           
             ; Regrids seasonal 1 x 1 biomass burning data 
             ; onto the GEOS_4 2 x 2.5 grid.

 MODIFICATION HISTORY:
        bmy, 08 Apr 2004: VERSION 1.00
        bmy, 20 Oct 2005: VERSION 1.01
                          - If units are per m3, m2, cm3, or cm2 then 
                            set PER_UNIT_AREA flag in routine CTM_REGRIDH;

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_bioburn2.pro)


REGRIDH_BIOFUEL

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_BIOFUEL

 PURPOSE:
        Regrids 1 x 1 biofuel burning emissions for NOx or CO
        onto a CTM grid of equal or coarser resolution.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_BIOFUEL [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the data will be regridded.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  RESOLUTION
             can be 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.

        OUTDIR -> Name of the directory where the output file will
             be written.  Default is './'.  
 
        /COPY -> If set, then will just copy 1 x 1 "raw" biofuel
             data from native ASCII format to binary punch format.

 OUTPUTS:
        Writes binary punch files: 
             biofuel.generic.1x1        (if /COPY is set)  OR
             biofuel.geos.{RESOLUTION}  (if OUTRESOLUTION=2 or =4)

 SUBROUTINES:
        External Subroutines Required:
        ===============================================
        CTM_GRID    (function)   CTM_TYPE    (function)
        CTM_REGRIDH (function)   CTM_NAMEXT  (function)   
        CTM_RESEXT  (function)   CTM_WRITEBPCH

        Internal Subroutines
        ===============================================
        RBF_READDATA (function) 

 REQUIREMENTS:
        References routines from the GAMAP and TOOLS packages.

 NOTES:
        The path names for the files containing 1 x 1 data are
        hardwired -- change as necessary!

 EXAMPLE:
        (1)
        REGRIDH_BIOFUEL, MODELNAME='GEOS_STRAT', RESOLUTION=[5,4]
           
             ; Regrids 1 x 1 biofuel data to the 4 x 5 GEOS-STRAT grid

 MODIFICATION HISTORY:
        bmy, 09 Jun 2000: VERSION 1.00
        bmy, 12 Jul 2000: VERSION 1.01 
                          - added NOx keyword
                          - now read original data with 
                            internal function RBF_READDATA
        bmy, 24 Jul 2000: - added OUTDIR keyword
        bmy, 26 Jan 2001: VERSION 1.02
                          - added extra species names
        bmy, 29 Oct 2001: VERSION 1.03
                          - added /COPY keyword to just copy data
                            from ASCII format to binary punch format
                          - now loop over multiple tracer names
                          - removed TRCNAME keyword
        bmy, 28 Jan 2002: VERSION 1.04
                          - bug fix: now convert C2H6, C3H8 and 
                            ACET from kg/yr to kg C/yr
        bmy, 14 Nov 2002: VERSION 1.05
                          - renamed to REGRIDH_BIOFUEL
        bmy, 23 Dec 2003: VERSION 1.06
                          - updated for GAMAP v2-01

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_biofuel.pro)


REGRIDH_C3H8_C2H6

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_C3H8_C2H6

 PURPOSE:
        Horizontally regrids emissions of C3H8 and C2H6
        from one CTM grid to another. 

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_C3H8_C2H6 [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INFILENAME -> Name of the file containing C3H8 and C2H6 to
             be regridded.  If omitted, then REGRIDH_C3H8_C2H6 will
             prompt the user to select a filename via a dialog box.

        OUTFILENAME -> Name of output file containing the regridded
             data.  If OUTFILENAME is not specified, then REGRIDH_C3H8_C2H6 
             will ask the user to specify a file via a dialog box.

        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the data will be regridded.  If
             OUTMODELNAME is not specified, REGRIDH_C3H8_C2H6 will 
             use the same model name as the input grid.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  RESOLUTION
             can be 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.

        DIAGN -> Diagnostic category of the data blocks that you 
            wish to regrid.  Default is "IJ-AVG-$".

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        =======================================================
        CTM_GRID          (function)   CTM_TYPE     (function)
        CTM_REGRIDH       (function)   CTM_RESEXT   (function)
        CTM_MAKE_DATAINFO (function)   CTM_WRITEBPCH            
        UNDEFINE

 REQUIREMENTS:
        References routines from the GAMAP and TOOLS packages.

 NOTES:
        None

 EXAMPLE:
        REGRIDH_C3H8_C2H6, INFILENAME='C3H8_C2H6_ngas.geos.4x5',   $
                           OUTFILENAME='C3H8_C2H6_ngas.geos.2x25', $
                           OUTRESOLUTION=2,                        $

             ; Regrids C3H8 and C2H6 data onto from the 4 x 5
             ; GEOS-3 grid to the the 2 x 2.5 GEOS-3 grid.

 MODIFICATION HISTORY:
        bmy, 08 Jan 2003: VERSION 1.00
        bmy, 22 Dec 2003: VERSION 1.01
                          - rewritten for GAMAP v2-01 
                          - now call PTR_FREE to free pointer memory

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_c3h8_c2h6.pro)


REGRIDH_CM2_S

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_CM2_S

 PURPOSE:
        Horizontally Regrids a CTM quantity (such as emissions) in 
        units of [molec/cm2/s] or [atoms C/cm2/s] to a new CTM grid.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_CM2_S [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INFILENAME -> Name of the file containing data to be regridded.
             If INFILENAME is not specified, then REGRIDH_RESTART
             will prompt the user to select a file via a dialog box.

        OUTFILENAME -> Name of the file which will contain the regridded 
             data.  If OUTFILENAME is not specified, then REGRIDH_RESTART
             will prompt the user to select a file via a dialog box.
 
        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the data will be regridded.  If not
             passed, then the model name corresponding to the data
             contained in INPUTFILE will be used as the default.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  RESOLUTION
             can be 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.

        DIAGN -> Diagnostic category of the data blocks that you 
            wish to regrid.  Default is "IJ-AVG-$".
             
 OUTPUTS:
        Writes binary punch files: 
             bioburn.seasonal.{MODELNAME}.{RESOLUTION} OR
             bioburn.interannual.{MODELNAME}.{RESOLUTION}.YEAR  

 SUBROUTINES:

        External Subroutines Required:
        =================================================
        CTM_GRID   (function)   CTM_TYPE   (function)
        CTM_REGRID (function)   CTM_NAMEXT (function)   
        CTM_RESEXT (function)   CTM_WRITEBPCH
        UNDEFINE

 REQUIREMENTS:
        References routines from the GAMAP and TOOLS packages.

 NOTES:
        none

 EXAMPLE:
        REGRIDH_BIOBURN, INFILENAME='biomass.seasonal.generic.1x1', $
                         OUTMODELNAME='GEOS4'
                         OUTRESOLUTION=2 $
                         OUTFILENAME='biomass.seasonal.geos.2x25'GEOS_STRAT', 
           
             ; Regrids seasonal 1 x 1 biomass burning data 
             ; onto the GEOS_4 2 x 2.5 grid.

 MODIFICATION HISTORY:
        bmy, 08 Apr 2004: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_cm2_s.pro)


REGRIDH_CROPLANDS

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_CROPLANDS

 PURPOSE:
        Regrids crop land fraction data from 0.5 x 0.5 degree 
        resolution to a coarser CTM grid.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_CROPLANDS [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INFILENAME -> Name of a netCDF file containing input 
             data to be be regridded.  Default is 
             '~rmy/Croplands/crop92_v1.1_0.5.nc'.

        OUTFILENAME -> Name of the binary punch file to contain
             output data.  Default is "croplands.bpch"

        OUTMODELNAME -> A string containing the name of the model
             grid on which the input data resides.  Default is GENERIC.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             on which the input data resides.  RESOLUTION can be 
             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 is 1.

 OUTPUTS:
        None -- writes output to file

 SUBROUTINES:
        Internal Subroutines
        ===================================================
        RC_ReadData (function)
 
        External Subroutines Required:
        ===================================================
        NCDF_READ             CTM_MAKE_DATAINFO (function) 
        CTM_TYPE (function)   CTM_GRID          (function)  
        CTM_WRITEBPCH         UNDEFINE

 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.

 NOTES:
        Some hardwiring for now...this is OK.

 EXAMPLE:
        REGRID_CROPLANDS, INFILENAME='croplands.nc',       $
                          OUTMODELNAME='generic',          $
                          OUTRESOLUTION=1,                 $
                          OUTFILENAME='newcroplands.bpch'


             ; Regrids 0.5 x 0.5 croplands data from "croplands.nc"
             ; file to 1 x 1 resolution.  Output is to the binary
             ; punch file "newcroplands.bpch".

 MODIFICATION HISTORY:
        bmy, 19 Jul 2001: VERSION 1.00
        bmy, 09 Jan 2003: VERSION 1.02
                          - Now use CTM_REGRIDH to regrid data
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_croplands.pro)


REGRIDH_DUST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_DUST

 PURPOSE:
        Horizontally regrids mineral dust concentrations [kg/m3]
        from one CTM grid to another.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_DUST [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        MONTH -> Month of year for which to process data.  Default is
             1 (January).  Since the dust files are very large, it may
             take several iterations to regrid an entire year of
             data.  You can break the job down 1 month at a time.

        INFILENAME -> Name of the file containing the dust data 
             which is to be regridded.  If INFILENAME is not specified,
             then REGRIDH_DUST will prompt the user to specify a file
             name via a dialog box.

        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the data will be regridded.  If not
             specified, then OUTMODELNAME will be set to the same
             value as the grid stored in INFILENAME.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  OUTRESOLUTION
             can be 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.

        OUTFILENAME -> Name of the directory where the output file will
             be written.  If not specified, then a dialog box
             will ask the user to supply a file name.

        DIAGN -> Diagnostic category of data block that you want
             to regrid.  Default is "MDUST-$".

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ======================================================
        CTM_GRID     (function)   CTM_TYPE          (function)
        CTM_REGRID   (function)   CTM_NAMEXT        (function)  
        CTM_RESEXT   (function)   CTM_MAKE_DATAINFO (function)
        CTM_WRITEBPCH             GETMODELANDGRIDINFO
        UNDEFINE

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        REGRIDH_DUST, INFILENAME='dust.geos3.2x25', $
                      OUTRESOLUTION=4,              $
                      OUTFILENAME='dust.geos3.4x5'
           
             ; Regrids dust data from 2 x 2.5 native resolution
             ; to 4 x 5 resolution for the GEOS-3 grid

 MODIFICATION HISTORY:
        bmy, 09 Jun 2000: VERSION 1.00
        rvm, 18 Jun 2000: VERSION 1.01
        bmy, 07 Jul 2000: VERSION 1.10
                          - added OUTDIR keyword
                          - save regridded data one month at a time
                            since regridding takes so long 
        bmy, 19 Dec 2003: VERSION 1.11
                          - Rewritten for GAMAP v2-01
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_dust.pro)


REGRIDH_FERT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_FERT

 PURPOSE:
        Regrids fertilizer NOx from a 1 x 1 grid onto a
        CTM grid of equal or coarser horizontal resolution.
        
 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_FERT [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        OUTMODELNAME -> A string containing the name of the model 
             grid onto which the data will be regridded.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  RESOLUTION
             can be 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.

        OUTFILENAME -> Name of the binary punch file that will hold
             regridded data.  If not specified, the default OUTFILENAME
             will be nox_fert.geos.{OUTRESOLUTION}

 OUTPUTS:
        None
  
 SUBROUTINES:
        External Subroutines Required:
        ==============================================
        CTM_TYPE    (function)   CTM_GRID   (function)
        CTM_NAMEXT  (function)   CTM_RESEXT (function)
        CTM_REGRIDH (function)   CTM_WRITEBPCH
        

 REQUIREMENTS:
        None

 NOTES:
        (1) Filenames are hardwired -- change as necessary
        (2) Regridding can take a while, especially at 1x1 resolution.

 EXAMPLE: 
        REGRIDH_FERT, OUTMODELNAME='GEOS1', $
                      OUTRESOLUTION=2,      $
                      OUTFILENAME='nox_fert.geos.2x25'
 
             ; Regrids 1 x 1 NOx fertilizer data onto the GEOS-1
             ; 2 x 2.5 resolution grid.  

 MODIFICATION HISTORY:
        bmy, 01 Aug 2000: VERSION 1.00
        bmy, 13 Jan 2003: VERSION 1.01
                          - renamed to "regridh_fert.pro"
                          - now uses CTM_REGRIDH
                          - removed OUTDIR, added OUTFILENAME
                          - updated comments
        bmy, 23 Dec 2003: VERSION 1.02
                          - updated for GAMAP v2-01
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_fert.pro)


REGRIDH_JO1D

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_JO1D

 PURPOSE:
        Regrids JO1D data (used for acetone emissions) 
        from one CTM grid to another.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_JO1D, [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INFILENAME -> Name of the input file containing JO1D data
             to be regridded.  If INFILENAME is not specified, then 
             REGRIDH_JO1D will prompt the user to select a file via 
             a dialog box.

        OUTFILENAME -> Name of the binary punch file which
             will contain regridded data.  Default is 
             "JO1D.{MODELNAME}.{RESOLUTION}"

        OUTMODELNAME -> Name of the model grid onto which the data
             will be regridded.  If OUTMODELNAME is not specified, 
             then REGRIDH_RESTART will use the same model name as the
             input grid.

        OUTRESOLUTION -> Specifies the resolution of the output
             model grid onto which the data will be regridded.
             OUTRESOLUTION can be 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.

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ========================================================
        CTM_TYPE          (function)   CTM_GRID       (function)
        CTM_NAMEXT        (function)   CTM_RESEXT     (function)
        CTM_MAKE_DATAINFO (function)   INTERPOLATE_2D (function)
        CTM_GET_DATA                   GETMODELANDGRIDINFO
        UNDEFINE       
 
 REQUIREMENTS:
        References routines from both GAMAP and TOOLS packages.

 NOTES:
        None

 EXAMPLE:
        REGRIDH_JOID, INFILENAME='JO1D.geos.4x5',   $
                      OUTFILENAME='JO1D.geos.2x25', $
                      OUTRESOLUTION=2

             ; Regrids JO1D data from 4 x 5 to 2 x 2.5 resolution.

 MODIFICATION HISTORY:
        bmy, 11 Aug 2000: VERSION 1.01
        bmy, 23 Dec 2003: VERSION 1.02
                          - updated for GAMAP v2-01
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/regridding/regridh_jo1d.pro)


REGRIDH_JV

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REGRIDH_JV

 PURPOSE:
        Horizontally interpolates J-values from one CTM grid to another.
        Can also be used to interpolate other data quantities.

 CATEGORY:
        Regridding

 CALLING SEQUENCE:
        REGRIDH_JV, [, Keywords ]

 INPUTS:
        None

 KEYWORD PARAMETERS:
        INFILENAME -> Name of the file containing data to be regridded.
             If INFILENAME is not specified, then REGRIDH_JV
             will prompt the user to select a file via a dialog box.

        OUTFILENAME -> Name of the file which will contain the regridded 
             data.  If OUTFILENAME is not specified, then REGRIDH_JV
             will prompt the user to select a file via a dialog box.

        OUTMODELNAME -> Name of the model grid onto which the data
             will be regridded.  If OUTMODELNAME is not specified, 
             then REGRIDH_JV will use the same model name as the
             input grid.

        OUTRESOLUTION -> Specifies the resolution of the model grid
             onto which the data will be regridded.  OUTRESOLUTION
             can be 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.

        DIAGN -> Diagnostic category of the data blocks that you 
            wish to regrid.  Default is "IJ-AVG-$".

 OUTPUTS:
        None

 SUBROUTINES:
        External Subroutines Required:
        ==========================================================
        CTM_TYPE           (function)   CTM_GRID       (function)
        CTM_NAMEXT         (function)   CTM_RESEXT     (function)
        CTM_MAKE_DATAINFO  (function)   INTERPOLATE_2D (function)
        GETMODELANDGRIDINFO             UNDEFINE

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        REGRIDV_JV, INFILENAME='JH2O2.geos4.4x5', $
                    OUTRESOLUTION='2'
                    OUTFILENAME='JH2O2.geos4.2x25'

             ; Regrids GEOS-4 stratospheric J-value data 
             ; at 4 x 5 resolution to 2 x 2.5 resolution.

 MODIFICATION HISTORY:
        bmy, 11 Aug 2000: VERSION 1.01
        bmy, 22 Dec 2003: VERSION 1.02
                          - updated for GAMAP v2-01
  bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10

(See /n/home09/ry