# Z routines

All GAMAP Routines

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

# Routine Descriptions

## ZMID (FUNCTION)

[Next Routine] [List of Routines]
``` NAME:
ZMID  (function)

PURPOSE:
Given a vector of altitudes at vertical edges of a model grid
computes the altitudes at the grid centers.

CATEGORY:
Atmospheric Sciences

CALLING SEQUENCE:
RESULT = ZMID( EDGE )

INPUTS:
EDGE -> Vector of altitude edges that defines the grid.
EDGE will be sorted in ascending order.

KEYWORD PARAMETERS:
None

OUTPUTS:
RESULT -> Altitudes at grid centers [m, km, etc]

SUBROUTINES:
None

REQUIREMENTS:
None

NOTES:
The relationship between altitude centers and edges is:

ZMID[N] = ( ZEDGE[N] + ZEDGE[N+1] ) / 2.0

EXAMPLE:
PRINT, ZMID( [ 0.0, 2.0, 4.0, 6.0, 8.0 ] )
1.00000  3.00000  5.00000  7.00000

; Given the altitude at grid edges at 0, 2, 4, 6, 8 km
; returns the altitude at grid centers.
;
MODIFICATION HISTORY:
bmy, 21 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/zmid.pro)

## ZONAL

[Previous Routine] [Next Routine] [List of Routines]
``` NAME:
ZONAL

PURPOSE:
Creates zonal-mean curtain plots of GEOS-Chem tracers

CATEGORY:
Benchmarking

CALLING SEQUENCE:
ZONAL, FILE, LONS, TAUS, TRACERS, VERSION, [, Keywords ]

INPUTS:
FILE -> The name of the file containing data to be plotted.

LONS -> Longitudes to plot

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

/PRESSURE -> Set this switch to plot pressure on the Y-axis.
The default is to plot altitude on the Y-axis.

/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:
==================================================
PlotZonal

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'

ZONAL, FILE, LONS, TAU, TRACERS, VERSION, \$
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'

MODIFICATION HISTORY:
cdh, 01 May 2012: Created zonal.pro based on maps.pro
bmy, 29 May 2013: GAMAP VERSION 2.17
- Remove reference to MEAN2 function
mps, 07 Aug 2013: - Now plot chemically produced HO2
mps, 10 Sep 2015: - Added /PRESSURE keyword to plot pressure
on the Y-axis (instead of altitude)

```

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

## ZONAL_DIFF

[Previous Routine] [Next Routine] [List of Routines]
``` NAME:
ZONAL_DIFF

PURPOSE:
Creates zonal mean absolute and percent difference plots
of tracers from the GEOS-Chem 1-month benchmark simulations.

CATEGORY:
Benchmarking

CALLING SEQUENCE:
ZONAL_DIFF, 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

/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.

/PRESSURE -> Set this switch to plot pressure on the Y-axis.
The default is to plot altitude on the Y-axis.

/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".

ZDFORMAT -> This keyword passes a colorbar format string
(Fortran-style) to the COLORBAR routine (via TVPLOT).
This keyword is purposely not named CBFORMAT, in order
to avoid passing this quantity to other routines.

OUTPUTS:
None

SUBROUTINES:
Internal Subroutines Included:
==================================================
PlotZonalAbsDiff      PlotZonalPctDiff

External Subroutines Required:
==================================================
CLOSE_DEVICE          COLORBAR_NDIV    (function)
CTM_GET_DATA          GET_DIFF_RANGE   (function)
GETMODELANDGRIDINFO   EXTRACT_FILENAME (function)
MULTIPANEL            CHKSTRU          (function)
MYCT                  OPEN_DEVICE
TVPLOT                UNDEFINE

REQUIREMENTS:
References routines from the GAMAP package.

NOTES:
(1) Meant to be called from BENCHMARK_1MON.

EXAMPLE:
FILES    = [ 'ctm.bpch.v9-01-01', 'ctm.bpch.v9-01-02a' ]
TAUS     = [ NYMD2TAU( 20050701 ), NYMD2TAU( 20050701 ) ]
TRACERS  = INDGEN( 43 ) + 1
VERSIONS = [ 'v9-01-01', 'v9-01-02a' ]

ZONAL_DIFFS, FILES, ALTRANGE, TAUS, TRACERS, VERSIONS, \$
/DO_FULLCHEM, /PS, OUTFILENAME='myplot.ps'

; Creates zonal mean difference plots of two GEOS-Chem
; versions; (in this case v9-01-01 / v9-01-01a) for
; July 2001.  Output is sent to the 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.

ZONAL_DIFFS, 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, 21 Jun 2011: VERSION 1.01
- Initial version, based on profiles.pro
bmy, 18 Jul 2011: - Added /PRESSURE keyword to plot pressure
on the Y-axis (instead of altitude)
bmy, 11 May 2012: GAMAP VERSION 2.16
- Now allow comparision of equivalent model
grids, even if the model names differ
(e.g. GEOS5_47L, MERRA_47L, GEOSFP_47L)
mps, 29 Mar 2013: - Now plot HO2 difference profiles
mps, 07 Aug 2013: - Now plot OH differences everywhere to fix bug
- Pre-defined range for ratio plots is now set to
+/- 30, so that we only plot ratios > 10%
- Cap dynamic range ratio plots at 1000% to avoid
going beyong max number of digits for colorbar
mps, 01 Oct 2015: - Include MERRA2 in the check for equivalent
vertical grids

```

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

## ZSTAR (FUNCTION)

[Previous Routine] [List of Routines]
``` NAME:
ZSTAR  (function)

PURPOSE:
Computes pressure-altitudes from pressures.

CATEGORY:
Atmospheric Sciences

CALLING SEQUENCE:
RESULT = ZSTAR( PRESS )

INPUTS:
PRESS -> The input pressure value, in [hPa].
PRESS can be either a scalar or a vector.

KEYWORD PARAMETERS:
None

OUTPUTS:
RESULT -> Computed pressure altitude(s) [km]

SUBROUTINES:
None

REQUIREMENTS:
None

NOTES:
Pressure-altitude is defined as:

Z* = 16 * log10[ 1000 / P(mb) ]

which, by the Laws of Logarithms, is equivalent to

Z* = 48 - ( 16 * log10[ P(mb) ] ).

EXAMPLE:
PRINT, ZSTAR( [ 900, 700, 500 ] )
0.732121  2.47843  4.81648

; Returns pressure-altitudes at 900, 700, 500 hPa

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

```

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