Remove job script examples, move run directory config to user guide

Signed-off-by: Lizzie Lundgren <elundgren@seas.harvard.edu>

docs/source/index.rst

@@ -55,15 +55,12 @@ with Spack, as well as how to use Spack to install GCHP's dependencies if needed
    user-guide/rundir-init.rst
    user-guide/getting-input-data.rst
    user-guide/running.rst
-
+   user-guide/rundir-config.rst
 
 .. toctree::
    :maxdepth: 1
    :caption: Supplemental Guides
-
-   supplement/rundir-config.rst
    supplement/config-files.rst
-   supplement/job-script-examples.rst
    supplement/building-gchp-dependencies.rst
    supplement/setting-up-aws-parallelcluster.rst
    supplement/caching-input-data.rst

docs/source/supplement/rundir-config.rst → docs/source/user-guide/rundir-config.rst

@@ -3,9 +3,7 @@
 Run Directory Configuration
 ===========================
 
-All GCHP run directories have default simulation-specific run-time settings that are set when you create a run directory. 
-You will likely want to change these settings. 
-This page goes over how to do this.
+All GCHP run directories have default simulation-specific run-time settings that are set in the configuration files. The many configuration files in GCHP can be overwhelming. However, you should be able to accomplish most if not all of what you wish to configure from one place in :file:`setCommonRunSettings.sh`. Use the rest of this guide to get acquainted with the configuration files and hone in on what to change to make based on what you would like to do.
 
 .. contents:: Table of contents
     :depth: 4
@@ -17,46 +15,70 @@ Configuration files
 
 GCHP is controlled using a set of configuration files that are included in the GCHP run directory. Files include:
 
-1. :file:`CAP.rc`
-2. :file:`ExtData.rc`
-3. :file:`GCHP.rc`
-4. :file:`geoschem_config.yml`
-5. :file:`HEMCO_Config.rc`
-6. :file:`HEMCO_Diagn.rc`
-7. :file:`input.nml`
-8. :file:`HISTORY.rc`
-9. :file:`logging.yml`
+1. setCommonRunSettings.sh
+2. CAP.rc
+3. ExtData.rc
+4. GCHP.rc
+5. geoschem_config.yml
+6. HEMCO_Config.rc
+7. HEMCO_Diagn.rc
+8. input.nml
+9. HISTORY.rc
+10. logging.yml
 
-Several run-time settings must be set consistently across multiple files. 
-Inconsistencies may result in your program crashing or yielding unexpected results. 
-To avoid mistakes and make run configuration easier, bash shell script :file:`setCommonRunSettings.sh` is included in all run directories to set the most commonly changed config file settings from one location. 
-Sourcing this script will update multiple config files to use values specified in file.
+The following table lists the core functions of each of these files. 
+See the individual subsections on each file for additional information.
 
-Sourcing :file:`setCommonRunSettings.sh` is done automatically prior to running GCHP if using any of the example run scripts, or you can do it at the command line. 
-Information about what settings are changed and in what files are standard output of the script. 
-To source the script, type the following:
+setCommonRunSettings.sh
+^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: console
+This file is actually a bash script that includes commonly changed run settings. It makes it easier to manage configuring GCHP since settings can be changed from one file rather than across multiple configuration files. When this file is executed it updates settings in other configuration files, overwriting what is there. Please get very familiar with the options in :file:`setCommonRunSettings.sh` and be conscientious about not updating the same setting elsewhere.
 
-   $ source setCommonRunSettings.sh
+CAP.rc
+^^^^^^
+
+Controls parameters used by the highest level gridded component (CAP). This includes simulation run time information, name of the Root gridded component (GCHP), config filenames for Root and History, and toggles for certain MAPL logging utilities (timers, memory, and import/export name printing).
+
+ExtData.rc
+^^^^^^^^^^
+
+Config file for the MAPL ExtData component. Specifies input variable information, including name, regridding method, read frequency, offset, scaling, and file path. All GCHP imports must be specified in this file. Toggles at the top of the file enable MAPL ExtData debug prints and using most recent year if current year of data is unavailable. Default values may be used by specifying file path :file:`/dev/null`.      
+
+GCHP.rc
+^^^^^^^
+
+Controls high-level aspects of the simulation, including grid type and resolution, core distribution, stretched-grid parameters, timesteps, and restart filename.
+
+geoschem_config.yml
+^^^^^^^^^^^^^^^^^^^
 
-You may also use it in silent mode if you wish to update files but not display settings on the screen:
+Primary config file for GEOS-Chem. Same file format as in GEOS-Chem Classic but containing only options relevant to GCHP.
 
-.. code-block:: console
+HEMCO_Config.rc
+^^^^^^^^^^^^^^^
 
-   $ source setCommonRunSettings.sh --silent
+Contains emissions information used by HEMCO. Same function as in GEOS-Chem Classic except only HEMCO name, species, scale IDs, category, and hierarchy are used. Diagnostic frequency, file path, read frequency, and units are ignored, and are instead stored in GCHP config file :file:`ExtData.rc`. All HEMCO variables listed in :file:`HEMCO_Config.rc` for enabled emissions must also have an entry in :file:`ExtData.rc`.
 
-While using :file:`setCommonRunSettings.sh` to configure common settings makes run configure much simpler, it comes with a major caveat. 
-If you manually edit a config file setting that is also set in :file:`setCommonRunSettings.sh` then your manual update will be overrided via string replacement. 
-Please get very familiar with the options in :file:`setCommonRunSettings.sh` and be conscientious about not updating the same setting elsewhere.
+HEMCO_Diagn.rc
+^^^^^^^^^^^^^^
+
+Contains information mapping :file:`HISTORY.rc` diagnostic names to HEMCO containers. Same function as in GEOS-Chem Classic except that not all items in :file:`HEMCO_Diagn.rc` will be output; only emissions listed in :file:`HISTORY.rc` will be included in diagnostics. All GCHP diagnostics listed in :file:`HISTORY.rc` that start with Emis, Hco, or Inv must have a corresponding entry in :file:`HEMCO_Diagn.rc`.
+
+input.nml
+^^^^^^^^^
+
+Namelist used in advection for domain stack size and stretched grid parameters.
+
+HISTORY.rc
+^^^^^^^^^^
+
+Config file for the MAPL History component. Configures diagnostic output from GCHP.
 
-You generally will not need to know more about the GCHP configuration files beyond what is listed on this page. 
-However, for a comprehensive description of all configuration files used by GCHP see the Configuration Files section of this user manual.
 
 ---------------------------------------------------------------------------------------------------
 
-Common options
---------------
+Configure run-time settings
+---------------------------
 
 Compute configuration
 ^^^^^^^^^^^^^^^^^^^^^
@@ -127,31 +149,26 @@ They are set to match GEOS-Chem Classic default values for low resolutions for c
 Timesteps are automatically reduced for high resolution runs. 
 Read the documentation in :file:`setCommonRunSettings.sh` section :literal:`Timesteps` for setting them.
 
-Set simulation start and end dates
-""""""""""""""""""""""""""""""""""
+Set simulation start date and duration
+""""""""""""""""""""""""""""""""""""""
 
-Set simulation start and end in :file:`setCommonRunSettings.sh` section :literal:`Simulation Start, End, Duration, # runs`.
-Read the comments in the file for a complete description of the options. 
-Typically a "CAP" runtime error indicates a problem with start, end, and duration settings. 
-If you encounter an error with the words "CAP" near it then double-check that these settings make sense.
+Set simulation start date in :file:`cap_restart` using string format :literal:`YYYYMMDD HHmmSS`. Set simulation duration in :file:`setCommonRunSettings.sh` using the same string format as start date. For example, if you want to do a 1-year run starting January 1, 2019 you would enter :literal:`20190101 000000` as your start date and :literal:`00010000 000000` to configure your run for one year.
 
 ---------------------------------------------------------------------------------------------------
 
 Inputs
 ^^^^^^
 
-Change initial restart file
+Change restart file
 """""""""""""""""""""""""""
 
-All GCHP run directories come with symbolic links to initial restart files for commonly used cubed sphere resolutions. 
-The appropriate restart file is automatically chosen based on the cubed sphere resolution you set in :file:`setCommonRunSettings.sh`.
+All GCHP run directories come with symbolic links to initial restart files for commonly used cubed sphere resolutions. These are located in the :file:`Restarts` directory in the run directory. All initial restart files contain start date and grid resolution in the filename using the start date in :file:`cap_restart`. Prior to running GCHP, either you or your run script will execute :file:`setRestartLink.sh` to create a symbolic link :file:`gchp_restart.nc4` to point to the appropriate restart file given configured start date and grid resolution. :file:`gchp_restart.nc4` will always be used as the restart file for all runs since it is specified as the restart file in :file:`GCHP.rc`.
+
+If you want to change the restart file then you should put the restart file you want to use in the :file:`Restarts` directory using the expected filename format with the start date you configure in :file:`cap_restart` and the grid resolution you configure in :file:`setCommonRunSettings.sh`. The expected format is :literal:`GEOSChem.Restarts.YYYYMMDD_HHmmSSz.cN.nc4`. Running :file:`setRestartLink.sh` will update :file:`gchp_restart.nc4` to use it.
 
-You may overwrite the default restart file with your own by specifying the restart filename in :file:`setCommonRunSettings.sh` section :literal:`Initial Restart File`. 
-Beware that it is your responsibility to make sure it is the proper grid resolution.
+If you do not want to rename your restart file then you can create a symbolic link in the :file:`Restarts` folder that points to it.
 
-Unlike GEOS-Chem Classic, HEMCO restart files are not used in GCHP. 
-HEMCO restart variables may be included in the initial species restart file, or they may be excluded and HEMCO will start with default values. 
-GCHP initial restart files that come with the run directories do not include HEMCO restart variables, but all output restart files do.
+Please note that unlike GC-Classic, GCHP does not use a separate HEMCO restart file. All HEMCO restart variables are included in the main GCHP restart.
 
 Turn on/off emissions inventories
 """""""""""""""""""""""""""""""""
@@ -261,11 +278,7 @@ See the :literal:`Diagnostics` section of :file:`setCommonRunSettings.sh` for mo
 Generate monthly mean diagnostics
 """""""""""""""""""""""""""""""""
 
-You can toggle monthly mean diagnostics on/off from within :file:`setCommonRunSettings.sh` in the diagnostics configurations section. 
-If you do this then ALL time-averaged diagnostic collections listed in :file:`setCommonRunSettings.sh` will have monthly diagnostics enabled. 
-As for collection frequency and duration, you can remove collections from the list in :file:`setCommonRunSettings.sh` to prevent auto-update, or set :literal:`AutoUpdate_Diagnostics` to :literal:`OFF`, and then manually update settings for those collections in :file:`HISTORY.rc` prior to your run. 
-This would allow you to have some time-averaged diagnostics be monthly mean and some not. 
-If using monthly diagnostics, be sure to always start and end your run on the first day and time of the month.
+You can toggle monthly mean diagnostics on/off from within :file:`setCommonRunSettings.sh` in the diagnostics configurations section if you also also set auto-update of diagnostics from that file to on. Alternatively, you can edit :file:`HISTORY.rc` directory and set the "monthly" field to value 1 for each collection you wish to output monthly diagnostics for. 
 
 ---------------------------------------------------------------------------------------------------