Difference between revisions of "GEOS-Chem restart files"

From Geos-chem
Jump to: navigation, search
(Vertical coordinates in netCDF files produced by GEOS-Chem)
(Viewing and manipulating restart files in netCDF format)
Line 77: Line 77:
 
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 16:30, 7 November 2018 (UTC)
 
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 16:30, 7 November 2018 (UTC)
  
== Viewing and manipulating restart files in netCDF format ==
+
== Viewing and manipulating restart files ==
  
There are many free and open-source software packages readily available for visualizing and manipulating netCDF files. These tools will reduce the need for the GEOS-Chem user community to rely on IDL (and GAMAP), which can be prohibitively expensive for some user groups. Some recommend tools are listed below.
+
For information on viewing and manipulating GEOS-Chem restart files in netCDF format, please see the following resources:
  
:1. '''[http://www.unidata.ucar.edu/software/netcdf/old_docs/docs_4_1/netcdf/ncdump.html ncdump]''': This command-line tool generates a text representation of netCDF data and can be used to quickly view the variables contained in a netCDF file. For example:
+
# [[Working_with_netCDF_data_files#Viewing and manipulating netCDF files|Resources for viewing and manipulating netCDF files]]
 
+
# [[Working_with_netCDF_data_files#Regridding_netCDF_files|Regridding netCDF files]]
      # Display header information (dimensions, variables, attributes) only
+
# [[Working_with_netCDF_data_files#Adding_a_new_variable_to_a_netCDF_file|Adding a new species to a restart file]]
      ncdump -h GEOSChem_restart.201308010000 | less
+
# [[Working_with_netCDF_data_files#Cropping_netCDF_files#Cropping restart files to a subset of the globe]]
+
      # Display header information followed by data values for variable(s) specified
+
      ncdump -v SPC_NO GEOSChem_restart.201308010000 | less
+
 
+
:2. '''[http://meteora.ucsd.edu/~pierce/ncview_home_page.html ncview]''': Visualization package for netCDF files, recommended for a quick and easy look at netCDF files.
+
 
+
:3. '''[https://www.giss.nasa.gov/tools/panoply/ Panoply]:''' Data viewer for netCDF files. This package offers an alternative to ncview. From our experience, Panoply works nicely when installed on the desktop, but is slow to respond in the Linux environment.
+
 
+
:4. '''[http://nco.sourceforge.net/ NCO]''' and '''[https://code.zmaw.de/projects/cdo CDO]''': Command-line tools for manipulating and analyzing netCDF files.
+
+
:5. Other programming languages may be used for viewing or manipulating netCDF files, including but not limited to:
+
:*[https://www.ncl.ucar.edu/index.shtml NCL]
+
:*[http://www.python.org/ Python]
+
:*[https://www.mathworks.com/products/matlab.html Matlab]
+
 
+
Some of the tools listed above, such as ncdump and ncview, may come pre-installed on your system. Others like NCO, CDO, and Panoply may need to be installed or loaded (e.g. via the <tt>module load</tt> command). Check with your system administrator or IT staff to see what is available on your system.
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 15:58, 17 January 2017 (UTC)
+
 
+
=== Regridding netCDF restart files ===
+
 
+
The same netCDF tools listed above can also be used to regrid netCDF restart files produced by GEOS-Chem.
+
 
+
:1. '''[https://code.zmaw.de/projects/cdo CDO]''': The Climate Data Operators include tools for regridding netCDF files. For example, the following command will apply distance-weighted regridding:
+
+
      cdo remapdis,gridfile infile.nc outfile.nc
+
 
+
:For <tt>gridfile</tt>, you can use the files in ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/HEMCO/grids/. See the [https://www.rsmas.miami.edu/users/rajib/cdo.pdf#page=106&zoom=auto,70.8662,789.2717 Interpolation section in the CDO Guide] for more information.
+
 
+
<blockquote>'''''Bram Maasakkers wrote:'''''
+
:I have noticed a problem regridding a 4x5 restart file to 2x2.5 using cdo 1.9.4. When I use:
+
 
+
::<code>cdo remapdis,geos.2x25.grid GEOSChem_restart.200901010000.nc GEOSChem_restart.2009_2x25.nc</code>
+
 
+
:The last latitudinal band (-89.5) remains empty and gets filled with the standard missing value of cdo, which is really large. This leads to immediate problems in the methane simulation as enormous concentrations enter the domain from the South Pole. For now I’ve solved this problem by just using bicubic interpolation:
+
 
+
::<code>cdo remapbic,geos.2x25.grid GEOSChem_restart.200901010000.nc GEOSChem_restart.2009_2x25_bicub.nc</code>
+
</blockquote>
+
 
+
:2. '''[http://nco.sourceforge.net/ NCO]''': The netCDF Operators also include tools for regridding. See the [http://nco.sourceforge.net/nco.html#Regridding Regridding section of the NCO User Guide] for more information.
+
 
+
:3. Jenny Fisher provided an IDL script <tt>regridh_restart_nc.pro</tt> which is now included with [http://acmg.seas.harvard.edu/gamap/doc/ GAMAP]. Jenny wrote:
+
 
+
:<blockquote>The one caveat that I cannot figure out is something weird with the units. I have done this in such a way that it reads in whatever attributes (including units) are in the original file and writes the same units back to the regridded file. But when GEOS-Chem reads the new file it gives an “incompatible units” error — although printing them in the code shows something identical to what the case statement is searching for, as far as I can tell. If I use ncatted to overwrite the units (with identical name) they are fine. So it must be something to do with the way IDL encodes the units string, but I have no idea what. The relevant nco command is <tt>ncatted -O -a units,,m,c,"mol mol-1" INFILENAME.nc</tt>​</blockquote>
+
 
+
:4. Regridding routines written in [http://www.ncl.ucar.edu/ NCL] are also available in the [[NCL_tools_for_GEOS-Chem|NCL4GC package]] available on Bitbucket.
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 22:06, 19 January 2017 (UTC)
+
 
+
=== Creating a netCDF restart file or adding new species to a netCDF restart file ===
+
 
+
You have a few options for adding new species to a netCDF restart file:
+
 
+
:1. In [[GEOS-Chem v11-01]], if the model cannot find a species in the netCDF restart file, it should set the initial concentration to the background concentration. The default background concentration is 1e-20 v/v. If you want to change that to a different value, you can add <tt>BackgroundVV = {VALUE}_fp</tt> to the call to <tt>Spc_Create</tt> for that species in <tt>Headers/species_database_mod.F90</tt>. To confirm your species is getting set to the background value you can turn on ND70 debug output, which will print the initial species concentrations (min/max) read from the restart file to the log file. At the end of your simulation, a new restart file will be saved out with the new species included. We recommend spinning up GEOS-Chem for an appropriate duration to achieve reasonable concentrations for the new species.
+
 
+
:2. You can use CDO and NCO to copy the restart field for one species to a new species. For example:
+
 
+
    module load nco
+
    module load cdo
+
+
    # Extract field SPC_PMN from the original restart file
+
    cdo selvar,SPC_PMN initial_GEOSChem_rst.4x5_standard.nc GEOSChem_restart.PMN.nc
+
+
    # Rename selected field to SPC_NPMN
+
    ncrename -h -v SPC_PMN,SPC_NPMN GEOSChem_restart.PMN.nc GEOSChem_restart.NPMN.nc
+
+
    # Append new species to existing restart file
+
    ncks -h -A -M GEOSChem_restart.NPMN.nc initial_GEOSChem_rst.4x5_standard.nc
+
 
+
:3. Sal Farina wrote a simple Python script for adding a new species to the netCDF restart file:
+
 
+
    #!/usr/bin/env python
+
    import netCDF4 as nc
+
    import sys
+
    import os
+
+
    for nam in sys.argv[1:]:
+
        f = nc.Dataset(nam,mode='a')
+
        try:
+
                o = f['SPC_OCPI']
+
        except:
+
                print "SPC_OCPI not defined"
+
+
        f.createVariable('SPC_SOAP',o.datatype,dimensions=o.dimensions,fill_value=o._FillValue)
+
        soap = f['SPC_SOAP']
+
        soap[:] = 0.0
+
        soap.long_name= 'SOAP tracer'
+
        soap.units =  o.units
+
        soap.add_offset = 0.0
+
        soap.scale_factor = 1.0
+
        soap.missing_value = 1.0e30
+
+
        f.close()
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 23:33, 7 November 2017 (UTC)
+
 
+
=== Cropping netCDF restart files to nested domains ===
+
 
+
If needed, regrid a coarse netCDF restart file to the nested grid resolution using GAMAP routine [http://acmg.seas.harvard.edu/gamap/doc/by_alphabet/gamap_r.html#REGRIDH_RESTART_NC regridh_restart_nc.pro].
+
 
+
Cropping netCDF files can be easily achieved with tools such as [https://code.zmaw.de/projects/cdo CDO] or [http://nco.sourceforge.net/ NCO]. For example, CDO has a SELBOX operator for selecting a box by specifying the lat/lon bounds:
+
 
+
cdo sellonlatbox,lon1,lon2,lat1,lat2 infile outfile
+
 
+
See page 44 of the [https://code.zmaw.de/projects/cdo/embedded/cdo.pdf CDO guide] for more information.
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 19:04, 3 May 2017 (UTC)
+
  
 
== Previous issues that are now resolved ==
 
== Previous issues that are now resolved ==

Revision as of 20:48, 29 November 2018

This page contains information about files produced by GEOS-Chem simulations, including diagnostic data and restart files used for initial conditions. For information the input files that ship with the GEOS-Chem run directories, please see our GEOS-Chem Input Files wiki page.

Restart files in GEOS-Chem 12

These updates were included in GEOS-Chem 12.1.0, which was released on 26 Nov 2018.

In GEOS-Chem 12.1.0, several restart file updates were introduced. These include:

Restart collection in HISTORY.rc

GEOS-Chem restart files are now saved out via the History component. A new Restart collection has been defined in HISTORY.rc and fields saved out to the restart file can be modified in that file.

New restart file names

Because we are now using the History component to archive restart files in GEOS-Chem 12.1.0 and later versions, GEOS-Chem restart file names now use this nomenclature: GEOSChem.Restart.YYYYMMDD_hhmmz.nc4.

For example, the restart file that was created at 00:00 UTC on August 1, 2016 is named: GEOSChem.Restart.20160801_0000z.nc4. The z indicates "Zulu" or "Z" time, which is another name for UTC.

New fields added to the GEOS-Chem restart file

Several new fields have been added to the GEOS-Chem restart file in an attempt to remove differences between single and multi-segmented GEOS-Chem simulations.

Item Description
1 Module-level variables H2O2s and SO2s from wetscav_mod.F have been added to State_Chm (as State_Chm%H2O2AfterChem, StateChm%SO2AfterChem). These fields will be output to the GEOS-Chem restart file and then initialized to the values saved in the restart file at the start of the next simulation. Prior to this update, both H2O2s and SO2s were initialized to the H2O2 and SO2 tracer concentrations at the start of every simulation. This change will impact multi-segmented runs only.
2 Module-level variables DRY_TOTN and WET_TOTN from get_ndep_mod.F have been added to State_Chm (as State_Chm%DryDepNitrogen, StateChm%WetDepNitrogen). These fields will be output to the GEOS-Chem restart file and then initialized to the values saved in the restart file at the start of the next simulation. Prior to this update, both variables were initialized to zero at the start of every simulation. Storing them in the restart file may improve accuracy of soil NOx emissions over multi-segmented runs. This change will impact multi-segmented runs only.
3 Move State_PSC from the HEMCO restart file to the GEOS-Chem restart file.
4 Save out instantaneous met fields TMPU1, SPHU1, PS1DRY, PS1WET, DELPDRY to the GEOS-Chem restart file. These will be used to initialize the met fields at the start of the timestep, otherwise they will be set to the values of those fields at the end of the timestep.

While this update was added to GEOS-Chem Classic in 12.1.0, it will be added to GCHP in 12.2.0.

Read restart file via HEMCO

GEOS-Chem restart files are now read in via HEMCO. The entries listed below have been added to HEMCO_Config.rc (and may vary slightly for different simulation types). These fields are obtained from HEMCO and copied to the appropriate State_Chm and State_Met fields in the new routine Get_GC_Restart (found in GeosCore/hcoi_gc_main_mod.F90).

  #==============================================================================
  # --- GEOS-Chem restart file ---
  #
  # PSC state only needed for UCX
  #==============================================================================
  (((GC_RESTART
  * SPC_           ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 SpeciesRst_?ALL?    $YYYY/$MM/$DD/$HH CS xyz 1 * - 1 1
  * TMPU1          ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 Met_TMPU1           $YYYY/$MM/$DD/$HH E  xyz 1 * - 1 1
  * SPHU1          ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 Met_SPHU1           $YYYY/$MM/$DD/$HH E  xyz 1 * - 1 1
  * PS1DRY         ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 Met_PS1DRY          $YYYY/$MM/$DD/$HH E  xy  1 * - 1 1
  * PS1WET         ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 Met_PS1WET          $YYYY/$MM/$DD/$HH E  xy  1 * - 1 1
  * DELPDRY        ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 Met_DELPDRY         $YYYY/$MM/$DD/$HH E  xyz 1 * - 1 1
  * KPP_HVALUE     ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 Chem_KPPHvalue      $YYYY/$MM/$DD/$HH E  xyz 1 * - 1 1
  * WETDEP_N       ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 Chem_WetDepNitrogen $YYYY/$MM/$DD/$HH E  xy  1 * - 1 1
  * DRYDEP_N       ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 Chem_DryDepNitrogen $YYYY/$MM/$DD/$HH E  xy  1 * - 1 1
  * SO2_AFTERCHEM  ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 Chem_SO2AfterChem   $YYYY/$MM/$DD/$HH E  xyz 1 * - 1 1
  * H2O2_AFTERCHEM ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 Chem_H2O2AfterChem  $YYYY/$MM/$DD/$HH E  xyz 1 * - 1 1
  (((+STATE_PSC+
  * STATE_PSC      ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 Chem_StatePSC       $YYYY/$MM/$DD/$HH E  xyz count       * - 1 1
  )))+STATE_PSC+
  )))GC_RESTART

The CS cycle flag was added as an option to HEMCO in GEOS-Chem 12.1.0 to tell HEMCO to skip fields that aren't found in the provided file. This is useful when certain species aren't found in the restart file and, in that case, GEOS-Chem will initialize that species to the background concentrations specified in the species database.

--Melissa Sulprizio (talk) 16:30, 7 November 2018 (UTC)

Viewing and manipulating restart files

For information on viewing and manipulating GEOS-Chem restart files in netCDF format, please see the following resources:

  1. Resources for viewing and manipulating netCDF files
  2. Regridding netCDF files
  3. Adding a new species to a restart file
  4. Working_with_netCDF_data_files#Cropping_netCDF_files#Cropping restart files to a subset of the globe

Previous issues that are now resolved

Enable compression in netCDF-4 output files

This update was included in v11-02a (approved 12 May 2017).

For more information about this issue, please see this post on our The NcdfUtilities package wiki page.

--Bob Yantosca (talk) 17:50, 24 May 2018 (UTC)

Improve write speed of netCDF output files

This update was included in GEOS-Chem v11-01 public release

For more information about this issue, please see this post on our The NcdfUtilities package wiki page.

--Bob Yantosca (talk) 19:05, 8 March 2017 (UTC)

GAMAP can now read GEOS-Chem restart files in netCDF format

This update was included in GEOS-Chem v11-01 public release

Starting in GEOS-Chem v11-01, all restart files are now saved in COARDS-compliant netCDF format. We have had to make some minor modifications to both GEOS-Chem and GAMAP in order to allow GAMAP to read these files. The table below gives a summary of these modifications.

GEOS-Chem or GAMAP? File Modification
GEOS-Chem GeosCore/gamap_mod.F In routine INIT_TRACERINFO, we now write metadata for all species (advected or not) to the tracerinfo.dat file under the ND45 tracer concentration diagnostic section. Because the netCDF restart file contains concentrations for both advected and non-advected species, we need to make sure that the tracerinfo.dat file created by GEOS-Chem contains metadata for all species.
GAMAP internals/ctm_open_file.pro The prior algorithm always assumed that a netCDF file would end in either .nc or .nc4. We now have removed this restriction. We now split the filename string on . and then examine the substrings for nc or nc4 (case-insensitive).
GAMAP internals/ctm_read_coards.pro Added some minor modifications to read netCDF restart files:
  1. Determine vertical grid from the number of layers (if the Model global attribute is not specified).
  2. Assign category DXYP to variable AREA, which is included in the netCDF restart file.
  3. Assign category IJ-AVG-$ to variables beginning with either SPC_ or TRC_. Also remove the SPC_ and TRC_ from the variable name internally so that the variable name will match the metadata in tracerinfo.dat.

--Bob Yantosca (talk) 19:29, 23 January 2017 (UTC)