Difference between revisions of "GEOS-Chem restart files"

From Geos-chem
Jump to: navigation, search
(New fields in GEOS-Chem restart file)
(Does the date of my restart file matter?)
(39 intermediate revisions by 3 users not shown)
Line 1: Line 1:
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|''GEOS-Chem Input Files'' wiki page]].
+
__FORCETOC__
 +
'''''[[GEOS-Chem log files|Previous]] | [[GEOS-Chem diagnostic output files|Next]] | [[Getting Started with GEOS-Chem]]'''''
 +
#[[Minimum system requirements for GEOS-Chem|Minimum system requirements]]
 +
#[[Installing required software]]
 +
#[[Configuring your computational environment]]
 +
#[[Downloading GEOS-Chem source code|Downloading source code]]
 +
#[[Downloading GEOS-Chem data directories|Downloading data directories]]
 +
#[[Creating GEOS-Chem run directories|Creating run directories]]
 +
#[[GEOS-Chem configuration files|Configuring runs]]
 +
#[[Compiling GEOS-Chem|Compiling]]
 +
#[[Running GEOS-Chem|Running]]
 +
#[[GEOS-Chem output files|Output files]]
 +
#*[[GEOS-Chem log files|Log files]]
 +
#*<span style="color:blue">'''Restart files'''</span>
 +
#*[[GEOS-Chem diagnostic output files|Diagnostic output files]]
 +
#[[Python tools for use with GEOS-Chem]]
 +
#[[GEOS-Chem_coding_and_debugging|Coding and debugging]]
 +
#[[GEOS-Chem_overview#Further_reading|Further reading]]
  
== Restart files in GEOS-Chem 12 ==
 
  
<span style="color:green">'''''These updates were included in [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]], which was released on 26 Nov 2018.'''''</span>
+
== Overview ==
  
In [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]], several restart file updates were introduced. These include:
+
In this section, we provide some basic information about GEOS-Chem Classic restart files and how they are used.
  
=== New fields in GEOS-Chem restart files ===
+
=== What is a 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.
+
GEOS-Chem restart files contain the initial conditions for a GEOS-Chem simulation. There are two restart files for GEOS-Chem:
  
{| border=1 cellpadding=5 cellspacing=0
+
{| border=1 cellspacing=0 cellpadding=5  
 +
|-valign="top" bgcolor="#CCCCCC"
 +
!width="325px"|File(s)
 +
!width="75px"|Format
 +
!width="650px"|Description
  
 
|-valign="top"
 
|-valign="top"
!width="50px"  bgcolor="#CCCCCC"|Item
+
|[[#GEOS-Chem restart files|<tt>GEOSChem.Restart.YYYYMMDD_hhmmz.nc4</tt>]]
!width="950px" bgcolor="#CCCCCC"|Description
+
|netCDF
 +
|'''The GEOS-Chem restart file.''' Contains species concentrations that are read in at simulation startup. 
  
|-valign="top"
+
GEOS-Chem writes a restart file at the end of each simulation. This allows a long simulation to be split into several individal run stages..
|1
+
|Module-level variables <tt>H2O2s</tt> and <tt>SO2s</tt> from <tt>wetscav_mod.F</tt> have been added to State_Chm (as <tt>State_Chm%H2O2AfterChem, StateChm%SO2AfterChem</tt>). 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'''''.
+
  
|-valign="top"
+
For example, the restart file that was created at 00:00 UTC on August 1, 2016 is named: <tt>GEOSChem.Restart.20160801_0000z.nc4</tt>. The z indicates "Zulu" or "Z" time, which is another name for UTC.
|2
+
|Module-level variables <tt>DRY_TOTN</tt> and <tt>WET_TOTN</tt> from <tt>get_ndep_mod.F</tt> have been added to State_Chm (as <tt>State_Chm%DryDepNitrogen, StateChm%WetDepNitrogen</tt>). 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'''''.
+
  
|-valign="top"
+
GEOS-Chem restart files are created in the top-level of your GEOS-Chem run directory (and NOT in the <tt>OutputDir/</tt> folder, which is where [[GEOS-Chem diagnostic output files|History diagnostic output files]] are created).
|3
+
|Move <tt>State_PSC</tt> from the HEMCO restart file to the GEOS-Chem restart file.
+
  
 
|-valign="top"
 
|-valign="top"
|4
+
|<tt>HEMCO_restart.YYYYMMDDhhmm.nc</tt>
|Save out instantaneous met fields <tt>TMPU1, SPHU1, PS1DRY, PS1WET, DELPDRY</tt> 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.
+
|netCDF
 +
|'''The HEMCO restart file.'''  The [[HEMCO|HEMCO emissions component]] will save out certain quantities (mostly pertaining to soil NOx and biogenic emissions) in order to facilitate long GEOS-Chem simulations with several run stages. 
 +
 
 +
HEMCO restart files are created in the top-level of your GEOS-Chem run directory (and NOT in the <tt>OutputDir/</tt> folder, which is where HEMCO diagnostic putput files are created).
  
 
|}
 
|}
  
While this update was added to GEOS-Chem Classic in [[GEOS-Chem_12#12.1.0|12.1.0]], it will be added to GCHP in 12.2.0.
+
When you run a GEOS-Chem simulation, it will write new GEOS-Chem restart files at the intervals you specify in <tt>HISTORY.rc</tt>. New HEMCO restart files are written with frequency configured in <tt>HEMCO_Config.rc</tt> if HEMCO is used in your simulation.
  
=== Restart collection in History.rc ===
+
=== How can I determine the date of a restart file? ===
  
GEOS-Chem restart files are now saved out via the History component. A new [[List_of_diagnostics_archived_to_netCDF_format#The_Restart_collection|Restart collection]] has been defined in <tt>HISTORY.rc</tt> and fields saved out to the restart file can be modified in that file.
+
To determine the date of a netCDF restart file, you may use <tt>ncdump</tt> For example:
  
As a result of this update, GEOS-Chem restart file names now are now named: <tt>GEOSChem.Restart.YYYYMMDD_hhmmz.nc4</tt>.  For example, the restart file that was created at 00:00 UTC on August 1, 2016 is named: <tt>GEOSChem.Restart.20160801_0000z.nc4</tt>.  The <tt>z</tt> indicates "Zulu" or "Z" time, which is another name for UTC.
+
ncdump -v time -t initial_GEOSChem_rst.4x5_standard.nc
  
=== Read restart file via HEMCO ===
+
The <tt>-t</tt> option will return the time value in human-readable date-time strings rather than numerical values in unit such as "hours since 1985-1-1 00:00:0.0." The date of a binary punch restart file can be determined by opening the file in GAMAP.
  
GEOS-Chem restart files are now read in via HEMCO. The entries listed below have been added to <tt>HEMCO_Config.rc</tt> (and may vary slightly for different simulation types). These fields are obtained from HEMCO and copied to the appropriate <tt>State_Chm</tt> and <tt>State_Met</tt> fields in the new routine <tt>Get_GC_Restart</tt> (found in <tt>GeosCore/hcoi_gc_main_mod.F90</tt>).
+
=== Where can I get a restart file for my simulation? ===
 
+
  #==============================================================================
+
  # --- 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 <tt>CS</tt> cycle flag was added as an option to HEMCO in [[GEOS-Chem 12#12.1.0|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.
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 16:30, 7 November 2018 (UTC)
+
 
+
== Viewing and manipulating restart files in netCDF format ==
+
 
+
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.
+
 
+
: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:
+
 
+
      # Display header information (dimensions, variables, attributes) only
+
      ncdump -h GEOSChem_restart.201308010000 | less
+
+
      # 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.
+
GEOS-Chem run directories are configured to use sample GEOS-Chem restart files in [[Introduction_to_netCDF|netCDF format]]. These files are available for download at:
  
: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.
+
http://ftp.as.harvard.edu/gcgrid/data/ExtData/GEOSCHEM_RESTARTS/
  
:4. '''[http://nco.sourceforge.net/ NCO]''' and '''[https://code.zmaw.de/projects/cdo CDO]''': Command-line tools for manipulating and analyzing netCDF files.
+
When you [[Creating_GEOS-Chem_run_directories|generate a new GEOS-Chem run directory]], a a sample restart file will be copied to your run directory.
+
: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.
+
Monthly restart files from the [[GEOS-Chem 13.0.0]] 10-year full-chemistry benchmark (2010-2019) can be found at:
  
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 15:58, 17 January 2017 (UTC)
+
http://ftp.as.harvard.edu/gcgrid/geos-chem/10yr_benchmarks/13.0.0/GCClassic/restarts/
  
=== Regridding netCDF restart files ===
+
<span style="color:red">'''CAVEAT: The sample restart files do not reflect the actual atmospheric state and should only be used to "spin up" the model. In other words, they should be used as initial values in an initialization simulation to generate more accurate initial conditions for your production runs.'''</span>
  
The same netCDF tools listed above can also be used to regrid netCDF restart files produced by GEOS-Chem.
+
=== For how long should I spin up before starting a production simulation? ===
  
: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:
+
Doing a one year spin up is usually sufficient; however, we recommend ten years for ozone, carbon dioxide, and methane simulations, and four years for radon-lead-beryllium simulations. If you are in doubt about how long your spin up should be for your simulation, we recommend contacting the [http://acmg.seas.harvard.edu/geos/geos_working_groups.html GEOS-Chem Working Group] that specializes in your area of research.
 
   
 
   
      cdo remapdis,gridfile infile.nc outfile.nc
+
You may spin up the model starting at any year for which there is met data, but you should always start your simulations at the month and day corresponding to the restart file to more accurately capture seasonal variation. If you want to start your production run at a specific date, we recommend doing a spin up for the appropriate number of years plus the number of days needed to reach your ultimate start date. For example, if you want to do a production simulation starting on 12/1/13, you could spin up the model for one year using the initial GEOS-FP restart file dated 7/1/13 and then use the new restart file to spin up the model for five additional months, from 7/1/13 to 12/1/13.
  
: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.
+
See also this discussion on our Github page for further guidance: https://github.com/geoschem/geos-chem/discussions/911.
  
<blockquote>'''''Bram Maasakkers wrote:'''''
+
=== Does the date of my restart file matter? ===
: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>
+
Starting in GEOS-Chem 13.0.1, HEMCO will automatically expect the date in the restart file to match the simulation date. This is done by enforcing the <tt>EFYO</tt> time cycle flag in HEMCO_Config.rc:
  
: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:
+
* SPC_          ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 SpeciesRst_?ALL?    $YYYY/$MM/$DD/$HH EFYO xyz 1 * - 1 1
  
::<code>cdo remapbic,geos.2x25.grid GEOSChem_restart.200901010000.nc GEOSChem_restart.2009_2x25_bicub.nc</code>
+
If HEMCO does not find the restart file for the correct date, it will crash.  
</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.
+
If you wish to have HEMCO continue when encountering missing values in the restart file, use the <tt>EY</tt> time cycle flag instead:  
  
: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:
+
* SPC_          ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 SpeciesRst_?ALL?    $YYYY/$MM/$DD/$HH EY  xyz 1 * - 1 1
  
:<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>
+
When <tt>EY</tt> is specified, HEMCO will no longer stop with an error if it cannot find a variable in the restart file. In this case, the default background concentration (as specified in the <tt>species_database.yml</tt> file will be used for the initial species concentration.  But HEMCO will still stop with an error if the starting date of the simulation does not match the date contained in the restart file.
  
: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.
+
=== What happens if a species is missing from my restart file? ===
  
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 22:06, 19 January 2017 (UTC)
+
If a species is not found in the restart file, it will be initialized to the default background concentrations specified by the <tt>Background_VV</tt> field in the <tt>species_database.yml</tt> file. If no value is specified for <tt>Background_VV</tt> then 1e-20 will be used.
  
=== Creating a netCDF restart file or adding new species to a netCDF restart file ===
+
=== How do I check my initial conditions? ===
  
You have a few options for adding new species to a netCDF restart file:
+
To ensure you are using the expected initial conditions for your simulation, please check the GEOS-Chem log file. You should see something like:
  
: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.
+
HEMCO: Opening ./GEOSChem.Restart.20190701_0000z.nc4
 
+
      - Found all CN    met fields for 2011/01/01 00:00
:2. You can use CDO and NCO to copy the restart field for one species to a new species. For example:
+
      - Found all A1    met fields for 2019/07/01 00:30
 
+
      - Found all A3cld  met fields for 2019/07/01 01:30
    module load nco
+
      - Found all A3dyn  met fields for 2019/07/01 01:30
    module load cdo
+
      - Found all A3mstC met fields for 2019/07/01 01:30
 +
      - Found all A3mstE met fields for 2019/07/01 01:30
 +
      - Found all I3    met fields for 2019/07/01 00:00
 +
  Initialize TMPU1    from restart file
 +
  Initialize SPHU1    from restart file
 +
  Initialize PS1_WET  from restart file
 +
  Initialize PS1_DRY  from restart file
 +
  Initialize DELP_DRY from restart file
 +
      - Found all I3    met fields for 2019/07/01 03:00
 +
===============================================================================
 +
R E S T A R T  F I L E  I N P U T
 
   
 
   
    # Extract field SPC_PMN from the original restart file
+
Min and Max of each species in restart file [mol/mol]:
    cdo selvar,SPC_PMN initial_GEOSChem_rst.4x5_standard.nc GEOSChem_restart.PMN.nc
+
Species  1,     ACET: Min = 1.000458833E-22  Max = 6.680149323E-09
   
+
  Species  2,     ACTA: Min = 6.574137699E-23  Max = 6.108235029E-10
     # Rename selected field to SPC_NPMN
+
Species  3,     AERI: Min = 4.122849756E-16  Max = 1.213838925E-11
    ncrename -h -v SPC_PMN,SPC_NPMN GEOSChem_restart.PMN.nc GEOSChem_restart.NPMN.nc
+
  Species  4,     ALD2: Min = 4.186668786E-23  Max = 4.571487633E-09
   
+
...
     # 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:
+
If a species is not found in the restart file, you may see something like:
  
    #!/usr/bin/env python
+
  Species 178,       pFe: Use background = 9.999999683E-21
    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)
+
=== Do I need a HEMCO restart file for my initial spin-up run? ===
  
==== Cropping netCDF restart files to nested domains ====
+
Using a HEMCO restart file for your initial spin up run is optional. The HEMCO restart file contains fields for initializing variables required for [[Soil NOx emissions]], [[MEGAN biogenic emissions]], and the [[UCX chemistry mechanism]]. The HEMCO restart file that comes with a run directory may only be used for the date and time indicated in the filename. HEMCO will automatically recognize when a restart file is not available for the date and time required, and in that case HEMCO will use default values to initialize those fields. You can also force HEMCO to use the default initialization values by setting "HEMCO_RESTART" to false in <tt>HEMCO_Config.rc</tt>. For more information, see the [[The_HEMCO_User's_Guide#Restart_variables|HEMCO User's Guide]].
  
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].
+
== Restart files in GEOS-Chem 12 and later versions ==
  
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:
+
In [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]] (release data 26 Nov 2018), several restart file updates were introduced. These include:
  
cdo sellonlatbox,lon1,lon2,lat1,lat2 infile outfile
+
=== Restart collection in HISTORY.rc ===
  
See page 44 of the [https://code.zmaw.de/projects/cdo/embedded/cdo.pdf CDO guide] for more information.
+
GEOS-Chem restart files are now saved out via the History component. A new [[List_of_diagnostics_archived_to_netCDF_format#The_Restart_collection|Restart collection]] has been defined in <tt>HISTORY.rc</tt> and fields saved out to the restart file can be modified in that file.
  
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 19:04, 3 May 2017 (UTC)
+
=== New restart file names ===
  
=== Vertical coordinates in netCDF files produced by GEOS-Chem ===
+
Because we are now [[#Restart collection in HISTORY.rc|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: <tt>GEOSChem.Restart.YYYYMMDD_hhmmz.nc4</tt>.
  
All netCDF files produced by GEOS-Chem (i.e. diagnostic files and restart files) adhere to the [[Preparing_data_files_for_use_with_HEMCO#The_COARDS_netCDF_standard|the COARDS netCDF convention]] for the lon, lat, and time dimensions.   
+
For example, the restart file that was created at 00:00 UTC on August 1, 2016 is named: <tt>GEOSChem.Restart.20160801_0000z.nc4</tt>The <tt>z</tt> indicates "Zulu" or "Z" time, which is another name for UTC.
  
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):
+
=== New variable names ===
  
variables:
+
Prior to [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]], species names in restart files began with the <tt>SPC_</tt> prefix:
      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 <tt>lev</tt> 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.
+
  SPC_NO          # Initial concentration of NO
 +
  SPC_O3          # Initial concentration of O3
 +
  SPC_CO          # Initial concentration of CO
 +
  SPC_CH4          # Initial concentration of CH4
 +
  ...etc...
  
  lev = 0.99250002413, 0.97749990013, 0.962499776, 0.947499955, 0.93250006,  
+
In [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]] and later versions, the species names now begin with the prefix <tt>SpeciesRst_</tt> prefix:
    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 <tt>lev</tt> 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):
+
  SpeciesRst_NO    # Initial concentration of NO
 +
  SpeciesRst_O3    # Initial concentration of O3
 +
  SpeciesRst_CO    # Initial concentration of CO
 +
  SpeciesRst_CH4  # Initial concentration of CH4
 +
  ...etc...
  
  Pmid = ( hyam(L) * PS(I,J) ) + hybm(L)
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:16, 30 November 2018 (UTC)
  
The <tt>ilev</tt> variable is used for data that is placed on vertical level edges or "interfaces" (hence the "i" in <tt>ilev</tt>).  This is also an "approximate" eta coordinate.
+
=== New fields added to the GEOS-Chem restart file ===
  
  ilev = 1, 0.98500004826, 0.969999752, 0.9549998, 0.94000011, 0.92500001,
+
Several new fields have been added to the GEOS-Chem output restart file in an attempt to remove differences between single and multi-segmented GEOS-Chem simulations.
    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):
+
{| border=1 cellpadding=5 cellspacing=0
  
  Pbot = ( hyai(L ) * PS(I,J) ) + hybi(L  )
+
|-valign="top"
  Ptop = ( hyai(L+1) * PS(I,J) ) + hybi(L+1)
+
!width="50px" bgcolor="#CCCCCC"|Item
 +
!width="950px" bgcolor="#CCCCCC"|Description
  
'''''[[User:Sebastian D. Eastham|Seb Eastham]] wrote:'''''
+
|-valign="top"
 +
|1
 +
|Module-level variables <tt>H2O2s</tt> and <tt>SO2s</tt> from <tt>wetscav_mod.F</tt> have been added to State_Chm (as <tt>State_Chm%H2O2AfterChem, StateChm%SO2AfterChem</tt>). 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'''''.
  
<blockquote>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 <tt>lev</tt> and <tt>ilev</tt> dimensions. In this case, <tt>lev</tt> is the cell mid-points, and <tt>ilev</tt> is cell edges ("i"nterfaces). Both <tt>lev</tt> and ilev are set up just as we discussed before, although CESM doesn't include the <tt>formula_terms</tt> attribute, which I think we should use. In this case <tt>formula_terms</tt> would be <tt>ap: hyai b: hybi p0: P0 ps: ps</tt> for the <tt>ilev</tt> dimension and <tt>ap: hyam b: hybm p0: P0 ps: ps</tt> for the <tt>lev</tt> dimension.
+
|-valign="top"
 +
|2
 +
|Module-level variables <tt>DRY_TOTN</tt> and <tt>WET_TOTN</tt> from <tt>get_ndep_mod.F</tt> have been added to State_Chm (as <tt>State_Chm%DryDepNitrogen, StateChm%WetDepNitrogen</tt>). 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'''''.
  
#For <tt>lev</tt> and <tt>ilev</tt>, they should be set to <tt>A/1000 + B</tt>, where <tt>P0</tt> = 1000.
+
|-valign="top"
#Both <tt>ilev</tt> and <tt>lev</tt> 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 <tt>PS</tt> 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 <tt>PS</tt> from, rather than automatically archiving it in every file.
+
|Move <tt>State_PSC</tt> from the HEMCO restart file to the GEOS-Chem restart file.
</blockquote>
+
  
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 19:27, 5 September 2018 (UTC)
+
|-valign="top"
 +
|4
 +
|Save out instantaneous met fields <tt>TMPU1, SPHU1, PS1DRY, PS1WET, DELPDRY</tt> 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.
  
== Previous issues that are now resolved ==
+
|}
  
=== Enable compression in netCDF-4 output files ===
+
While this update was added to GEOS-Chem Classic in [[GEOS-Chem_12#12.1.0|12.1.0]], it will be added to GCHP in 12.2.0.
  
<span style="color:green">'''''This update was included in [[GEOS-Chem v11-02#v11-02a|v11-02a]] (approved 12 May 2017).'''''</span>
+
=== Read restart file via HEMCO ===
  
For more information about this issue, please see [[The_NcdfUtilities_package#Enable_compression_in_netCDF-4_output_files|this post on our ''The NcdfUtilities package'' wiki page]].
+
GEOS-Chem restart files are now read in via HEMCO. The entries listed below have been added to <tt>HEMCO_Config.rc</tt> (and may vary slightly for different simulation types). These fields are obtained from HEMCO and copied to the appropriate <tt>State_Chm</tt> and <tt>State_Met</tt> fields in the new routine <tt>Get_GC_Restart</tt> (found in <tt>GeosCore/hcoi_gc_main_mod.F90</tt>).
  
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 17:50, 24 May 2018 (UTC)
+
  #==============================================================================
 +
  # --- 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
  
=== Improve write speed of netCDF output files ===
+
The <tt>CS</tt> cycle flag was added as an option to HEMCO in [[GEOS-Chem 12#12.1.0|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.
  
<span style="color:green">'''''This update was included in [[GEOS-Chem v11-01#v11-01 public release|GEOS-Chem v11-01 public release]]'''''</span>
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 16:30, 7 November 2018 (UTC)<br>--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:12, 12 December 2019 (UTC)
  
For more information about this issue, please see [[The_NcdfUtilities_package#Improve_write_speed_of_netCDF_output_files|this post on our ''The NcdfUtilities package'' wiki page]].
+
== HEMCO restart files ==
  
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 19:05, 8 March 2017 (UTC)
+
Please see the [[The HEMCO User's Guide#Restart_variables|'''Restart variables''' section of ''The HEMCO User's Guide]] for more information.
  
=== GAMAP can now read GEOS-Chem restart files in netCDF format ===
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 17:08, 30 November 2018 (UTC)
  
<span style="color:green">'''''This update was included in [[GEOS-Chem v11-01#v11-01 public release|GEOS-Chem v11-01 public release]]'''''</span>
+
== Viewing and manipulating restart files ==
  
Starting in [[GEOS-Chem v11-01]], all restart files are now saved in [[Preparing_data_files_for_use_with_HEMCO#The_COARDS_netCDF_standard|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.
+
For information on viewing and manipulating GEOS-Chem restart files in netCDF format, please see the following sections of [[Working with netCDF data files|our ''Working with netCDF data files'' wiki page]]:
  
{| border=1 cellspacing=0 cellpadding=5
+
# [[Working_with_netCDF_data_files#Viewing and manipulating netCDF files|Resources for viewing and manipulating netCDF files]]
|-valign="top" bgcolor="#CCCCCC"
+
# [[Working_with_netCDF_data_files#Regridding_netCDF_files|Regridding netCDF files]]
!width="100px"|GEOS-Chem or GAMAP?
+
# [[Working_with_netCDF_data_files#Adding_a_new_variable_to_a_netCDF_file|Adding a new species to a restart file]]
!width="250px"|File
+
# [[Working_with_netCDF_data_files#Cropping_netCDF_files|Cropping restart files to a subset of the globe]]
!width="650px"|Modification
+
# [[Working_with_netCDF_data_files#Chunking_and_deflating_a_netCDF_file_to_improve_I.2FO|Chunking and deflating restart files]]
  
|-valign="top"
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:19, 30 November 2018 (UTC)
|GEOS-Chem
+
|<tt>GeosCore/gamap_mod.F</tt>
+
|In routine <tt>INIT_TRACERINFO</tt>, 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 <tt>tracerinfo.dat</tt> file created by GEOS-Chem contains metadata for all species.
+
  
|-valign="top"
 
|GAMAP
 
|<tt>internals/ctm_open_file.pro</tt>
 
|The prior algorithm always assumed that a netCDF file would end in either <tt>.nc</tt> or <tt>.nc4</tt>.  We now have removed this restriction.  We now split the filename string on <tt>.</tt> and then examine the substrings for <tt>nc</tt> or <tt>nc4</tt> (case-insensitive).
 
 
|-valign="top"
 
|GAMAP
 
|<tt>internals/ctm_read_coards.pro</tt>
 
|Added some minor modifications to read netCDF restart files:
 
   
 
#Determine vertical grid from the number of layers (if the <tt>Model</tt> global attribute is not specified).
 
#Assign category <tt>DXYP</tt> to variable <tt>AREA</tt>, which is included in the netCDF restart file.
 
#Assign category <tt>IJ-AVG-$</tt> to variables beginning with either <tt>SPC_</tt> or <tt>TRC_</tt>.  Also remove the <tt>SPC_</tt> and <tt>TRC_</tt> from the variable name internally so that the variable name will match the metadata in <tt>tracerinfo.dat</tt>.
 
 
|}
 
  
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 19:29, 23 January 2017 (UTC)
+
-----
 +
'''''[[GEOS-Chem log files|Previous]] | [[GEOS-Chem diagnostic output files|Next]] | [[Getting Started with GEOS-Chem]]'''''

Revision as of 19:53, 19 May 2022

Previous | Next | Getting Started with GEOS-Chem

  1. Minimum system requirements
  2. Installing required software
  3. Configuring your computational environment
  4. Downloading source code
  5. Downloading data directories
  6. Creating run directories
  7. Configuring runs
  8. Compiling
  9. Running
  10. Output files
  11. Python tools for use with GEOS-Chem
  12. Coding and debugging
  13. Further reading


Overview

In this section, we provide some basic information about GEOS-Chem Classic restart files and how they are used.

What is a restart file?

GEOS-Chem restart files contain the initial conditions for a GEOS-Chem simulation. There are two restart files for GEOS-Chem:

File(s) Format Description
GEOSChem.Restart.YYYYMMDD_hhmmz.nc4 netCDF The GEOS-Chem restart file. Contains species concentrations that are read in at simulation startup.

GEOS-Chem writes a restart file at the end of each simulation. This allows a long simulation to be split into several individal run stages..

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.

GEOS-Chem restart files are created in the top-level of your GEOS-Chem run directory (and NOT in the OutputDir/ folder, which is where History diagnostic output files are created).

HEMCO_restart.YYYYMMDDhhmm.nc netCDF The HEMCO restart file. The HEMCO emissions component will save out certain quantities (mostly pertaining to soil NOx and biogenic emissions) in order to facilitate long GEOS-Chem simulations with several run stages.

HEMCO restart files are created in the top-level of your GEOS-Chem run directory (and NOT in the OutputDir/ folder, which is where HEMCO diagnostic putput files are created).

When you run a GEOS-Chem simulation, it will write new GEOS-Chem restart files at the intervals you specify in HISTORY.rc. New HEMCO restart files are written with frequency configured in HEMCO_Config.rc if HEMCO is used in your simulation.

How can I determine the date of a restart file?

To determine the date of a netCDF restart file, you may use ncdump For example:

ncdump -v time -t initial_GEOSChem_rst.4x5_standard.nc

The -t option will return the time value in human-readable date-time strings rather than numerical values in unit such as "hours since 1985-1-1 00:00:0.0." The date of a binary punch restart file can be determined by opening the file in GAMAP.

Where can I get a restart file for my simulation?

GEOS-Chem run directories are configured to use sample GEOS-Chem restart files in netCDF format. These files are available for download at:

http://ftp.as.harvard.edu/gcgrid/data/ExtData/GEOSCHEM_RESTARTS/

When you generate a new GEOS-Chem run directory, a a sample restart file will be copied to your run directory.

Monthly restart files from the GEOS-Chem 13.0.0 10-year full-chemistry benchmark (2010-2019) can be found at:

http://ftp.as.harvard.edu/gcgrid/geos-chem/10yr_benchmarks/13.0.0/GCClassic/restarts/

CAVEAT: The sample restart files do not reflect the actual atmospheric state and should only be used to "spin up" the model. In other words, they should be used as initial values in an initialization simulation to generate more accurate initial conditions for your production runs.

For how long should I spin up before starting a production simulation?

Doing a one year spin up is usually sufficient; however, we recommend ten years for ozone, carbon dioxide, and methane simulations, and four years for radon-lead-beryllium simulations. If you are in doubt about how long your spin up should be for your simulation, we recommend contacting the GEOS-Chem Working Group that specializes in your area of research.

You may spin up the model starting at any year for which there is met data, but you should always start your simulations at the month and day corresponding to the restart file to more accurately capture seasonal variation. If you want to start your production run at a specific date, we recommend doing a spin up for the appropriate number of years plus the number of days needed to reach your ultimate start date. For example, if you want to do a production simulation starting on 12/1/13, you could spin up the model for one year using the initial GEOS-FP restart file dated 7/1/13 and then use the new restart file to spin up the model for five additional months, from 7/1/13 to 12/1/13.

See also this discussion on our Github page for further guidance: https://github.com/geoschem/geos-chem/discussions/911.

Does the date of my restart file matter?

Starting in GEOS-Chem 13.0.1, HEMCO will automatically expect the date in the restart file to match the simulation date. This is done by enforcing the EFYO time cycle flag in HEMCO_Config.rc:

* SPC_           ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 SpeciesRst_?ALL?    $YYYY/$MM/$DD/$HH EFYO xyz 1 * - 1 1

If HEMCO does not find the restart file for the correct date, it will crash.

If you wish to have HEMCO continue when encountering missing values in the restart file, use the EY time cycle flag instead:

* SPC_           ./GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 SpeciesRst_?ALL?    $YYYY/$MM/$DD/$HH EY   xyz 1 * - 1 1

When EY is specified, HEMCO will no longer stop with an error if it cannot find a variable in the restart file. In this case, the default background concentration (as specified in the species_database.yml file will be used for the initial species concentration. But HEMCO will still stop with an error if the starting date of the simulation does not match the date contained in the restart file.

What happens if a species is missing from my restart file?

If a species is not found in the restart file, it will be initialized to the default background concentrations specified by the Background_VV field in the species_database.yml file. If no value is specified for Background_VV then 1e-20 will be used.

How do I check my initial conditions?

To ensure you are using the expected initial conditions for your simulation, please check the GEOS-Chem log file. You should see something like:

HEMCO: Opening ./GEOSChem.Restart.20190701_0000z.nc4
     - Found all CN     met fields for 2011/01/01 00:00
     - Found all A1     met fields for 2019/07/01 00:30
     - Found all A3cld  met fields for 2019/07/01 01:30
     - Found all A3dyn  met fields for 2019/07/01 01:30
     - Found all A3mstC met fields for 2019/07/01 01:30
     - Found all A3mstE met fields for 2019/07/01 01:30
     - Found all I3     met fields for 2019/07/01 00:00
 Initialize TMPU1    from restart file
 Initialize SPHU1    from restart file
 Initialize PS1_WET  from restart file
 Initialize PS1_DRY  from restart file
 Initialize DELP_DRY from restart file
     - Found all I3     met fields for 2019/07/01 03:00
===============================================================================
R E S T A R T   F I L E   I N P U T

Min and Max of each species in restart file [mol/mol]:
Species   1,     ACET: Min = 1.000458833E-22  Max = 6.680149323E-09
Species   2,     ACTA: Min = 6.574137699E-23  Max = 6.108235029E-10
Species   3,     AERI: Min = 4.122849756E-16  Max = 1.213838925E-11
Species   4,     ALD2: Min = 4.186668786E-23  Max = 4.571487633E-09
...

If a species is not found in the restart file, you may see something like:

Species 178,       pFe: Use background = 9.999999683E-21

Do I need a HEMCO restart file for my initial spin-up run?

Using a HEMCO restart file for your initial spin up run is optional. The HEMCO restart file contains fields for initializing variables required for Soil NOx emissions, MEGAN biogenic emissions, and the UCX chemistry mechanism. The HEMCO restart file that comes with a run directory may only be used for the date and time indicated in the filename. HEMCO will automatically recognize when a restart file is not available for the date and time required, and in that case HEMCO will use default values to initialize those fields. You can also force HEMCO to use the default initialization values by setting "HEMCO_RESTART" to false in HEMCO_Config.rc. For more information, see the HEMCO User's Guide.

Restart files in GEOS-Chem 12 and later versions

In GEOS-Chem 12.1.0 (release data 26 Nov 2018), 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 variable names

Prior to GEOS-Chem 12.1.0, species names in restart files began with the SPC_ prefix:

 SPC_NO           # Initial concentration of NO
 SPC_O3           # Initial concentration of O3
 SPC_CO           # Initial concentration of CO
 SPC_CH4          # Initial concentration of CH4
 ...etc...

In GEOS-Chem 12.1.0 and later versions, the species names now begin with the prefix SpeciesRst_ prefix:

 SpeciesRst_NO    # Initial concentration of NO
 SpeciesRst_O3    # Initial concentration of O3
 SpeciesRst_CO    # Initial concentration of CO
 SpeciesRst_CH4   # Initial concentration of CH4
 ...etc...

--Bob Yantosca (talk) 15:16, 30 November 2018 (UTC)

New fields added to the GEOS-Chem restart file

Several new fields have been added to the GEOS-Chem output 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)
--Bob Yantosca (talk) 22:12, 12 December 2019 (UTC)

HEMCO restart files

Please see the Restart variables section of The HEMCO User's Guide for more information.

--Bob Yantosca (talk) 17:08, 30 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 sections of our Working with netCDF data files wiki page:

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

--Bob Yantosca (talk) 15:19, 30 November 2018 (UTC)



Previous | Next | Getting Started with GEOS-Chem