View source for GEOS-Chem restart files

__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]]
#[[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 input 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]]
#[[Guide_to_visualization_and_analysis_tools_for_GEOS-Chem|Visualizing and processing output]]
#[[GEOS-Chem_coding_and_debugging|Coding and debugging]]
#[[GEOS-Chem_overview#Further_reading|Further reading]]


== Overview ==

In this section, we provide some basic information about GEOS-Chem 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:

{| border=1 cellspacing=0 cellpadding=5 
|-valign="top" bgcolor="#CCCCCC"
!width="325px"|File(s)
!width="75px"|Format
!width="650px"|Description

|-valign="top"
|[[#GEOS-Chem restart files|<tt>GEOSChem.Restart.YYYYMMDD_hhmmz.nc4</tt>]]
|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: <tt>GEOSChem.Restart.20160801_0000z.nc4</tt>. 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 <tt>OutputDir/</tt> folder, which is where [[GEOS-Chem diagnostic output files|History diagnostic output files]] are created.)

|-valign="top"
|<tt>HEMCO_restart.YYYYMMDDhhmm.nc</tt>
|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.)

|}

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.

=== How can I determine the date of a restart file? ===

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

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

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.

=== Where can I get a restart file for my simulation? ===

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:

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

When you [[Creating_GEOS-Chem_run_directories|generate a new GEOS-Chem run directory]], a link to a sample restart file will be created.

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

=== 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 [http://acmg.seas.harvard.edu/geos/geos_working_groups.html 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.  

=== 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 <tt>HEMCO_Config.rc</tt>. For more information, see the [[The_HEMCO_User's_Guide#Restart_variables|HEMCO User's Guide]].

--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 12:25, 16 July 2019 (UTC)<br>--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:10, 12 December 2019 (UTC)

== Restart files in GEOS-Chem 12 and later versions ==

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:

=== Restart collection in HISTORY.rc ===

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.

=== New restart file names ===

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

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.

=== New variable names ===

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:

  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#12.1.0|GEOS-Chem 12.1.0]] and later versions, the species names now begin with the prefix <tt>SpeciesRst_</tt> 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...

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|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.

{| border=1 cellpadding=5 cellspacing=0

|-valign="top"
!width="50px"  bgcolor="#CCCCCC"|Item
!width="950px" bgcolor="#CCCCCC"|Description

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

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

|-valign="top"
|3
|Move <tt>State_PSC</tt> from the HEMCO restart file to the GEOS-Chem restart file.

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

|}

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.

=== Read restart file via HEMCO ===

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

   #==============================================================================
   # --- 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)<br>--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:12, 12 December 2019 (UTC)

== HEMCO restart files ==

Please see the [[The HEMCO User's Guide#Restart_variables|'''Restart variables''' section of ''The HEMCO User's Guide]] for more information.

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|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 [[Working with netCDF data files|our ''Working with netCDF data files'' wiki page]]:

# [[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]]
# [[Working_with_netCDF_data_files#Adding_a_new_variable_to_a_netCDF_file|Adding a new species to a restart file]]
# [[Working_with_netCDF_data_files#Cropping_netCDF_files|Cropping restart files to a subset of the globe]]
# [[Working_with_netCDF_data_files#Chunking_and_deflating_a_netCDF_file_to_improve_I.2FO|Chunking and deflating restart files]]

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:19, 30 November 2018 (UTC)


-----
'''''[[GEOS-Chem log files|Previous]] | [[GEOS-Chem diagnostic output files|Next]] | [[Getting Started with GEOS-Chem]]'''''