Overview of History diagnostics
Previous | Next | Guide to GEOS-Chem History diagnostics
- Overview of History diagnostics
- Legend for History diagnostics
- Collections for History diagnostics
- History collections for advection and mixing
- History collections for aerosols
- History collections for budgets
- History collections for chemistry and photolysis
- History collections for convection and wet deposition
- History collections for dry deposition
- History collections for mercury and POPs
- History collections for met fields and related quantities
- History collections for methane
- History collections for species concentrations
- History collections for TransportTracers
- Replicating the behavior of the prior timeseries diagnostics
- Adding new History diagnostics
Contents
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:
- Emissions diagnostics archived directly by HEMCO
- 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) is available in GEOS-Chem 12.6.0 and later versions. 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.
|
| SpeciesConc.frequency | Determines how often the diagnostic quantities belonging to SpeciesConc collection will be saved to a netCDF file.
|
| 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.
|
| SpeciesConc.mode | Determines the averaging method for the SpeciesConc collection.
In the example shown above:
|
| SpeciesConc.fields | Lists the diagnostic quantities to be included in the SpeciesConc collection.
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.
|
| 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.
|
| 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.
|
| SpeciesConcSubset.levels (OPTIONAL) |
Specifies the levels that you wish to be printed to disk.
|
| 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.
|
| 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.
|
| ConcAfterChem.mode | Determines the averaging method for the ConcAfterChem collection
|
| ConcAfterChem.fields | Lists the diagnostic quantities to be included in the ConcAfterChem collection.
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.
|
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.
- For lev and ilev, they should be set to A/1000 + B, where P0 = 1000.
- Both ilev and lev should be in all 3D files, even though only one of the two dimensions is used in a given file).
- 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)
