Overview of History diagnostics

From Geos-chem
Jump to: navigation, search

Previous | Next | Guide to GEOS-Chem History diagnostics

  1. Overview of History diagnostics
  2. Legend for History diagnostics
  3. Collections for History diagnostics
  4. History collections for advection and mixing
  5. History collections for aerosols
  6. History collections for budgets
  7. History collections for chemistry and photolysis
  8. History collections for convection and wet deposition
  9. History collections for dry deposition
  10. History collections for mercury and POPs
  11. History collections for met fields and related quantities
  12. History collections for methane
  13. History collections for species concentrations
  14. History collections for TransportTracers
  15. Replicating the behavior of the prior timeseries diagnostics
  16. Adding new History diagnostics


Overview

An introduction to netCDF diagnostics

GEOS-Chem 12.0.0 and later versions can save diagnostic output to netCDF format. There are two types of netCDF diagnostic output files:

  1. Emissions diagnostics archived directly by HEMCO
  2. Non-emissions diagnostics computed by GEOS-Chem

The GEOS-Chem Support Team has developed a new netCDF diagnostic capability for GEOS-Chem "Classic" (point #2 above) that replicates how the existing netCDF diagnostics work in GCHP (aka "History"). A common input file named HISTORY.rc can be used for both GEOS-Chem "Classic" and GCHP.

Bob Yantosca has created an overview presentation about the new netCDF diagnostics for v11-02.

--Bob Yantosca (talk) 22:40, 13 March 2019 (UTC)

Sample HISTORY.rc diagnostic input file

NOTE: Horizontal and vertical subsetting (i.e. archiving regions that are smaller than the entire global grid) will be available in GEOS-Chem 12.6.0 and later versions (Git commit ID: 740bd2d3). For details, see the SpeciesConcSubset collection in the sample HISTORY.rc file listed below.

Here is a sample HISTORY.rc file that is used to request netCDF diagnostic output from a GEOS-Chem “Classic” simulation.

#============================================================================ 
# EXPID allows you to specify the beginning of the file path corresponding
# to each diagnostic collection.  For example:
#
#   EXPID: ./GEOSChem 
#      Will create netCDF files whose names begin "GEOSChem",
#      in this run directory.
#
#   EXPID: ./OutputDir/GEOSChem
#      Will create netCDF files whose names begin with "GEOSChem"
#      in the OutputDir sub-folder of this run directory.
#
#============================================================================
EXPID:  ./GEOSChem

#==============================================================================
# %%%%% COLLECTION NAME DECLARATIONS %%%%%
#
# To disable a collection, place a "#" character in front of its name
#
# NOTE: These are the "default" collections for GEOS-Chem.  
# But you can create your own custom diagnostic collections as well.
#==============================================================================
COLLECTIONS: 'SpeciesConc',
             'SpeciesConcSubset',
             'ConcAfterChem',
::
#==============================================================================
# %%%%% THE SpeciesConc COLLECTION %%%%%
#
# GEOS-Chem species concentrations (default = advected species)
#
# Available for all simulations
#==============================================================================
SpeciesConc.template:           '%y4%m2%d2_%h2%n2z.nc4',
SpeciesConc.frequency:          00000000 060000,
SpeciesConc.format:             'CFIO',
SpeciesConc.duration:           00000001 000000,
SpeciesConc.mode:               'instantaneous',
SpeciesConc.fields:             'SpeciesConc_?ADV?',  'GIGCchem',
::
#==============================================================================
# %%%%% THE SpeciesConcSubset COLLECTION %%%%%
#
# Same as the SpeciesConc collection, but will subset data in the horizontal
# and vertical dimensions so that the netCDF diagnostic files will cover
# a smaller region of the globe.  This can save disk space and memory.
#
# NOTE: This capability will be available in GEOS-Chem "Classic" 12.5.0
# and later versions.
#
# Available for all simulations
#==============================================================================
SpeciesConcSubset.template:     '%y4%m2%d2_%h2%n2z.nc4',
SpeciesConcSubset.frequency:    060000,
SpeciesConcSubset.format:       'CFIO',
SpeciesConcSubset.duration:     00000001 000000,
SpeciesConcSubset.mode:         'instantaneous',
SpeciesConcSubset.LON_RANGE     -40.0 60.0,
SpeciesConcSubset.LAT_RANGE     -10.0 50.0,
SpeciesConcSubset.levels:       1 2 3 4 5,
SpeciesConcSubset.fields:       'SpeciesConc_?ADV?',  'GIGCchem',
::
#==============================================================================
# %%%%% THE ConcAfterChem COLLECTION %%%%%
#
# Concentrations of OH, HO2, O1D, O3P immediately after exiting the KPP solver
# or OH after the CH4 specialty-simulation chemistry routine.
#
# OH:       Available for all full-chemistry simulations and CH4 specialty sim
# HO2:      Available for all full-chemistry simulations
# O1D, O3P: Availalbe for full-chemistry simulations using UCX mechanism
#==============================================================================
ConcAfterChem.template:         '%y4%m2%d2_%h2%n2z.nc4',
ConcAfterChem.frequency:        00000100 000000,
ConcAfterChem.format:           'CFIO',
ConcAfterChem.duration:         00000100 000000,
ConcAfterChem.mode:             'time-averaged',
ConcAfterChem.fields:           'OHconcAfterChem',     'GIGCchem',
                                'HO2concAfterChem',    'GIGCchem',
                                'O1DconcAfterChem',    ‘GIGCchem’,
                                'O3PconcAfterChem',    ‘GIGCchem’,
::


In this HISTORY.rc file, we are requesting three collections, or types of netCDF file output. The table below explains in more detail parameters shown in the HISTORY.rc file above.

Attribute Explanation
The first collection: SpeciesConc
SpeciesConc Name of the first collection in this HISTORY.rc file. A collection is a series of files containing the same GEOS-Chem diagnostic quantities.
SpeciesConc.template Determines the date and time format for each netCDF file name belonging to the SpeciesConc collection.
  • The string %y4%m2%d2_%h2%n2z.nc4 will print YYYYMMDD_hhmmz.nc4 to the end of each netCDF filename
    • YYYYMMDD is the date in year/month/day format
    • hhmm is the time in hour:minutes format.
    • z denotes "Zulu", which is an abbreviation for UTC time.
    • .nc4 denotes that the data file is in the netCDF-4 format.
SpeciesConc.frequency Determines how often the diagnostic quantities belonging to SpeciesConc collection will be saved to a netCDF file.
  • This can be specified as either "hhmmss" or "YYYYMMDD hhmmss".
  • In the above example, data belonging to the SpeciesConc collection will be written to the file every 6 hours. (Because SpeciesConc is an instantaneous collection, no time-averaging will be performed.)
SpeciesConc.format For GCHP simulations only: indicates the I/O library that will be used. This can be omitted for GEOS-Chem "Classic" simualations.
SpeciesConc.duration Determines how often a new SpeciesConc netCDF file will be created.
  • This can be specified as either hhmmss or YYYYMMDD hhmmss.
  • In the above example, a new SpeciesConc netCDF file will be created every 24 hours.
SpeciesConc.mode Determines the averaging method for the SpeciesConc collection.
  • Possible values for mode are either 'instantaneous' or 'time-averaged'.

In the example shown above:

  • SpeciesConc is defined as an 'instantaneous' (aka "time-series") collection.
  • Diagnostic quantities belonging to SpeciesConc will be written directly to disk without any temporal averaging, at the specified frequency.
SpeciesConc.fields Lists the diagnostic quantities to be included in the SpeciesConc collection.
  • In the above example, we are requesting to archive the concentrations of all advected species to the SpeciesConc collection.
  • The text 'GIGCchem' is only needed for GCHP simulations. It is ignored for GEOS-Chem "Classic" simulations. We keep the 'GIGCchem' in the file in order HISTORY.rc files to be interchanged between GEOS-Chem "Classic" and GCHP simulations.

See the sections below for in-depth descriptions of all possible diagnostic quantities that can be archived to netCDF format.

NOTE: You may use wildcards to request a subset of all possible chemical species. See the next section for more information about wildcards.

:: Signifies the end of the SpeciesConc definition section.
  • "::" may be placed at any column in the file.
The second collection: SpeciesConcSubset
SpeciesConcSubset Name of the second collection in this HISTORY.rc file.
SpeciesConcSubset.template
SpeciesConcSubset.frequency
SpeciesConcSubset.format
SpeciesConcSubset.duration
SpeciesConcSubset.mode
SpeciesConcSubset.fields
::
In the sample HISTORY.rc file above, these attributes of the SpeciesConcSubset collection happen to be identical to those used by the SpeciesConc collection (see above). Therefore, we will omit re-describing these.
SpeciesConcSubset.LON_RANGE
(OPTIONAL)
Specifies a longitude range (lonMin lonMax). Only those grid boxes whose longitudes fall within this range will be archived to disk.
  • In the above example, we have requested a subset region from -40 to 60 degrees longitude.
  • If omitted, then all longitudes (-180..180) will be archived.
  • New in GEOS-Chem 12.6.0.
SpeciesConcSubset.LAT_RANGE
(OPTIONAL)
Specifies a latitude range (latMin latMax). Only those grid boxes whose latitudes fall within this range will be archived to disk.
  • In the above example, we have requested a subset region from 10 to 50 degrees latitude.
  • If omitted, then all latitudes (-90..90) will be archived.
  • New in GEOS-Chem 12.6.0.


SpeciesConcSubset.levels
(OPTIONAL)
Specifies the levels that you wish to be printed to disk.
  • NOTE: In GEOS-Chem "Classic", all levels between the minimum and maximum level specified will be archived to disk. This differs than the behavior in GCHP, which archives only the specified levels.
  • In the above example, we are requesting output from levels 1-5.
  • If omitted, then the entire vertical extent of the grid [(1 72) or (1 47), depending on simulation] will be archived.
  • New in GEOS-Chem 12.6.0.
The thirdcollection: ConcAfterChem
ConcAfterChem Name of the third collection in this HISTORY.rc file.
ConcAfterChem.template Determines the date and time format for each netCDF file name belonging to the ConcAfterChem collection.
ConcAfterChem.frequency Determines the length of the period in which the diagnostic quantities belonging to ConcAfterChem collection will be temporally-averaged, before being saved to a netCDF file.
  • This can be can be specified as either "hhmmss" or "YYYYMMDD hhmmss".
  • In the above example, data belonging to the ConcAfterChem collection will be averaged into monthly mean output.
ConcAfterChem.format For GCHP simulations only: indicates the I/O library that will be used. This can be omitted for GEOS-Chem "Classic" simualations.
ConcAfterChem.duration Determines how often a new netCDF file belongng to the ConcAfterChem will be created.
  • The duration attribute can be specified as either hhmmss or YYYYMMDD hhmmss.
  • In the above example, a new ConcAfterChem netCDF file will be created at the start of each new month.
ConcAfterChem.mode Determines the averaging method for the ConcAfterChem collection
  • In the above example, ConcAfterChem is defined as an time-averaged collection.
  • Diagnostic quantities belonging to the ConcAfterChem collection will be temporally-averaged for a period whose length is specified by the frequency attribute before being written to a netCDF file.
ConcAfterChem.fields Lists the diagnostic quantities to be included in the ConcAfterChem collection.
  • In the above example, we are requesting to archive to the ConcAfterChem collection the concentrations of OH, HO2, O1D, and O3P upon exiting the FlexChem/KPP solver
  • The text 'GIGCchem' is only needed for GCHP simulations. It is ignored for GEOS-Chem "Classic" simulations. We keep the 'GIGCchem' in the file in order HISTORY.rc files to be interchanged between GEOS-Chem "Classic" and GCHP simulations.

See the sections below for in-depth descriptions of all possible diagnostic quantities that can be archived to netCDF format.

NOTE: You may use wildcards to request a subset of all possible species. See the next section for more information about wildcards.

:: Signifies the end of the ConcAfterChem definition section.
  • "::" may be placed at any column in the file.

For more examples, please see Bob Yantosca’s netCDF diagnostics overview presentation. We will also add more documentation to the GEOS-Chem wiki in the coming weeks.

--Bob Yantosca (talk) 22:12, 8 February 2018 (UTC)

netCDF filename convention

The names of the netCDF files corresponding to each collection will adhere to this convention:

 EXPID.CollectionName.Template

Where EXPID can be specified at the very top of the HISTORY.rc file. This parameter controls the filename prefix. In the example from the previous section, EXPID is set to ./GEOSChem. This means that all netCDF output files will be placed in the current run directory (specified by ./) and will begin with GeosChem.

If you wish to send the netCDF diagnostic output to a sub-folder of the run directory (say named OutputDir), then you can set e.g. EXPID: ./OutputDir/GeosChem. (NOTE: You can also omit the ./, but we have included it to make it clear that the files will be placed in the same directory where the GEOS-Chem executable resides.)

The CollectionName and Template settings are defined as shown in our example HISTORY.rc file from the previous section, namely:

 SpeciesConc.template:           '%y4%m2%d2_%h2%n2z.nc4',
 SpeciesConcSubset.template:     '%y4%m2%d2_%h2%n2z.nc4',
 ConcAfterChem.template:         '%y4%m2%d2_%h2%n2z.nc4',

In the template tags:

  • The notation %y4%m2%d5_%h2%n2 specifies a in the format YYYYMMDD_hhmm into the netCDF filename.
  • The lowercase zdenotes UTC time (aka "Zulu time").
  • The .nc4 extension denotes that the file will be in netCDF-4 format.

Also recall that the duration tag of HISTORY.rc controls how often a new file will be written to disk, as we saw in our example from the previous section:

 SpeciesConc.duration:           00000001 000000,     # Write a new file each day
 SpeciesConcSubset.duration:     00000001 000000,     # Write a new file each day
 ConcAfterChem.duration:         00000100 000000,     # Write a new file each month

Therefore, based on all of these settings in our example HISTORY.rc file, GEOS-Chem will write the following netCDF files to disk in the current run directory:

GEOSChem.SpeciesConc.20160101_0000z.nc4    GEOSChem.SpeciesConcSubset.20160101_0000z.nc4
GEOSChem.SpeciesConc.20160102_0000z.nc4    GEOSChem.SpeciesConcSubset.20160102_0000z.nc4
GEOSChem.SpeciesConc.20160103_0000z.nc4    GEOSChem.SpeciesConcSubset.20160102_0000z.nc4
GEOSChem.SpeciesConc.20160104_0000z.nc4    GEOSChem.SpeciesConcSubset.20160104_0000z.nc4
... etc ...

and

GEOSChem.ConcAfterChem.20160101_0000z.nc4
GEOSChem.ConcAfterChem.20160201_0000z.nc4
GEOSChem.ConcAfterChem.20160301_0000z.nc4
GEOSChem.ConcAfterChem.20160401_0000z.nc4
... etc ...

--Bob Yantosca (talk) 19:24, 6 June 2019 (UTC)

Vertical coordinates in netCDF files

All netCDF files produced by GEOS-Chem (i.e. diagnostic files and restart files) adhere to the the COARDS netCDF convention for the lon, lat, and time dimensions.

For the vertical dimension, we have chosen to use the following coordinate variables, emulating the file format of the NCAR Community Earth System Model (CESM):

variables:
     double lev(lev) ;
         lev:long_name = "hybrid level at midpoints (1000*(A+B))" ;
         lev:units = "level" ;
         lev:positive = "down" ;\
         lev:standard_name = "atmosphere_hybrid_sigma_pressure_coordinate" ;
         lev:formula_terms = "a: hyam b: hybm p0: P0 ps: PS" ;
     double hyam(lev) ;
         hyam:long_name = "hybrid A coefficient at layer midpoints" ;
     double hybm(lev) ;
         hybm:long_name = "hybrid B coefficient at layer midpoints" ;
     double ilev(ilev) ;
         ilev:long_name = "hybrid level at interfaces (1000*(A+B))" ;
         ilev:units = "level" ;
         ilev:positive = "down" ;
         ilev:standard_name = "atmosphere_hybrid_sigma_pressure_coordinate" ;
         ilev:formula_terms = "a: hyai b: hybi p0: P0 ps: PS" ;
     double hyai(ilev) ;
         hyai:long_name = "hybrid A coefficient at layer interfaces" ;
     double hybi(ilev) ;
         hybi:long_name = "hybrid B coefficient at layer interfaces" ;
     double P0 ;
         P0:long_name = "reference pressure" ;

The lev variable is used for data that is placed on the midpoints between vertical levels. This is an "approximate" eta coordinate, which is close to 1 at the surface and close to zero at the atmosphere top.

 lev = 0.99250002413, 0.97749990013, 0.962499776, 0.947499955, 0.93250006, 
    0.91749991, 0.90249991, 0.88749996, 0.87249996, 0.85750006, 0.842500125, 
    0.82750016, 0.8100002, 0.78750002, 0.762499965, 0.737500105, 0.7125001, 
    0.6875001, 0.65625015, 0.6187502, 0.58125015, 0.5437501, 0.5062501, 
    0.4687501, 0.4312501, 0.3937501, 0.3562501, 0.31279158, 0.26647905, 
    0.2265135325, 0.192541016587707, 0.163661504087706, 0.139115, 0.11825, 
    0.10051436, 0.085439015, 0.07255786, 0.06149566, 0.05201591, 0.04390966, 
    0.03699271, 0.03108891, 0.02604911, 0.021761005, 0.01812435, 0.01505025, 
    0.01246015, 0.010284921, 0.008456392, 0.0069183215, 0.005631801, 
    0.004561686, 0.003676501, 0.002948321, 0.0023525905, 0.00186788, 
    0.00147565, 0.001159975, 0.00090728705, 0.0007059566, 0.0005462926, 
    0.0004204236, 0.0003217836, 0.00024493755, 0.000185422, 0.000139599, 
    0.00010452401, 7.7672515e-05, 5.679251e-05, 4.0142505e-05, 2.635e-05, 
    1.5e-05 ;

The lev variable may be used for quick plotting. To compute the actual pressure at the midpoint of the grid box (I,J,L), you will need to supply your own 2-D surface pressure field (e.g. saved from another diagnostic file):

 Pmid = ( hyam(L) * PS(I,J) ) + hybm(L)

The ilev variable is used for data that is placed on vertical level edges or "interfaces" (hence the "i" in ilev). This is also an "approximate" eta coordinate.

 ilev = 1, 0.98500004826, 0.969999752, 0.9549998, 0.94000011, 0.92500001, 
    0.90999981, 0.89500001, 0.87999991, 0.86500001, 0.85000011, 0.83500014, 
    0.82000018, 0.80000022, 0.77499982, 0.75000011, 0.7250001, 0.7000001, 
    0.6750001, 0.6375002, 0.6000002, 0.5625001, 0.5250001, 0.4875001, 
    0.4500001, 0.4125001, 0.3750001, 0.3375001, 0.28808306, 0.24487504, 
    0.208152025, 0.176930008175413, 0.150393, 0.127837, 0.108663, 0.09236572, 
    0.07851231, 0.06660341, 0.05638791, 0.04764391, 0.04017541, 0.03381001, 
    0.02836781, 0.02373041, 0.0197916, 0.0164571, 0.0136434, 0.0112769, 
    0.009292942, 0.007619842, 0.006216801, 0.005046801, 0.004076571, 
    0.003276431, 0.002620211, 0.00208497, 0.00165079, 0.00130051, 0.00101944, 
    0.0007951341, 0.0006167791, 0.0004758061, 0.0003650411, 0.0002785261, 
    0.000211349, 0.000159495, 0.000119703, 8.934502e-05, 6.600001e-05, 
    4.758501e-05, 3.27e-05, 2e-05, 1e-05 ;

To compute the actual pressure at the bottom and top edges of the grid box (I,J,L), you will need to supply your own 2-D surface pressure field (e.g. saved from another diagnostic file):

 Pbot = ( hyai(L  ) * PS(I,J) ) + hybi(L  )
 Ptop = ( hyai(L+1) * PS(I,J) ) + hybi(L+1)

Seb Eastham wrote:

Daniel Rothenberg has been in touch regarding how vertical co-ordinates are set up in CESM. It's mostly the same (as COARDS), with the exception that EVERY file which includes a vertical co-ordinate also includes both lev and ilev dimensions. In this case, lev is the cell mid-points, and ilev is cell edges ("i"nterfaces). Both lev and ilev are set up just as we discussed before, although CESM doesn't include the formula_terms attribute, which I think we should use. In this case formula_terms would be ap: hyai b: hybi p0: P0 ps: ps for the ilev dimension and ap: hyam b: hybm p0: P0 ps: ps for the lev dimension.
  1. For lev and ilev, they should be set to A/1000 + B, where P0 = 1000.
  2. Both ilev and lev should be in all 3D files, even though only one of the two dimensions is used in a given file).
  3. I think we can leave PS out of the files. It will make them non-compliant but I think it's one of those "accepted" non-compliances. If it turns out to be a problem we can revisit it later, but for plotting the expectation is that it's up to the user to figure out where they're getting PS from, rather than automatically archiving it in every file.

--Bob Yantosca (talk) 19:27, 5 September 2018 (UTC)



Previous | Next | [[Guide to GEOS-Chem History diagnostics]