Moving config files pages from supplemental to user guide

This update also consolidates some of the information and separated the
individual config file pages into one config file per page.

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

docs/source/index.rst

@@ -61,7 +61,6 @@ with Spack, as well as how to use Spack to install GCHP's dependencies if needed
    :maxdepth: 1
    :caption: Supplemental Guides
 
-   supplement/config-files.rst
    supplement/building-gchp-dependencies.rst
    supplement/setting-up-aws-parallelcluster.rst
    supplement/caching-input-data.rst

docs/source/user-guide/config-files/CAP_rc.rst

@@ -0,0 +1,48 @@
+CAP.rc
+======
+
+:file:`CAP.rc` is the configuration file for the top-level gridded component called CAP. 
+This gridded component can be thought of as the primary driver of GCHP. 
+Its config file handles general runtime settings for GCHP including time parameters, performance profiling routines, and system-wide timestep (hearbeat). 
+Combined with output file :file:`cap_restart`, :file:`CAP.rc` configures the exact dates for the next GCHP run.
+
+ROOT_NAME	
+   Sets the name MAPL uses to initialize the ROOT child gridded component component within CAP. CAP uses this name in all operations when querying and interacting with ROOT. It is set to GCHP.
+
+ROOT_CF	
+   Resource configuration file for the ROOT component. It is set to :file:`GCHP.rc`.
+
+HIST_CF	
+   Resource configuration file for the MAPL HISTORY gridded component (another child gridded component of CAP). It is set to :file:`HISTORY.rc`.
+
+BEG_DATE	
+   Simulation begin date in format YYYYMMDD hhmmss. This parameter is overrided in the presence of output file :file:`cap_restart` containing a different start date.
+
+END_DATE	
+   Simulation end date in format YYYYMMDD hhmmss. If BEG_DATE plus duration (JOB_SGMT) is before END_DATE then simulation will end at BEG_DATE + JOB_SGMT. If it is after then simulation will end at END_DATE.
+
+JOB_SGMT	
+   Simulation duration in format YYYYMMDD hhmmss. The duration must be less than or equal to the difference between start and end date or the model will crash.
+
+HEARTBEAT_DT	
+   The timestep of the ESMF/MAPL internal clock, in seconds. All other timesteps in GCHP must be a multiple of HEARTBEAT_DT. ESMF queries all components at each heartbeat to determine if computation is needed. The result is based upon individual component timesteps defined in :file:`GCHP.rc`.
+
+MAPL_ENABLE_TIMERS
+   Toggles printed output of runtime MAPL timing profilers. This is set to YES. Timing profiles are output at the end of every GCHP run.
+
+MAPL_ENABLE_MEMUTILS	
+   Enables runtime output of the programs' memory usage. This is set to YES.
+
+PRINTSPEC	
+   Allows an abbreviated model run limited to initializat and print of Import and Export state variable names. Options include: 
+
+   * 0 (default): Off
+   * 1: Imports and Exports only
+   * 2: Imports only
+   * 3: Exports only
+
+USE_SHMEM	
+   This setting is deprecated but still has an entry in the file.
+
+REVERSE_TIME	
+   Enables running time backwards in CAP. Default is 0 (off).

docs/source/supplement/config-files/ExtData.rst → docs/source/user-guide/config-files/ExtData_rc.rst

@@ -1,5 +1,5 @@
 ExtData.rc
-==================
+==========
 
 :file:`ExtData.rc` contains input variable and file read information for GCHP. 
 Explanatory information about the file is located at the top of the configuration file in all run directories. 

docs/source/supplement/config-files/others.rst → docs/source/user-guide/config-files/GCHP_rc.rst

@@ -1,56 +1,5 @@
-CAP.rc, GCHP.rc, input.nml
-==============================
-
-CAP.rc
-------
-
-:file:`CAP.rc` is the configuration file for the top-level gridded component called CAP. 
-This gridded component can be thought of as the primary driver of GCHP. 
-Its config file handles general runtime settings for GCHP including time parameters, performance profiling routines, and system-wide timestep (hearbeat). 
-Combined with output file :file:`cap_restart`, :file:`CAP.rc` configures the exact dates for the next GCHP run.
-
-ROOT_NAME	
-   Sets the name MAPL uses to initialize the ROOT child gridded component component within CAP. CAP uses this name in all operations when querying and interacting with ROOT. It is set to GCHP.
-
-ROOT_CF	
-   Resource configuration file for the ROOT component. It is set to :file:`GCHP.rc`.
-
-HIST_CF	
-   Resource configuration file for the MAPL HISTORY gridded component (another child gridded component of CAP). It is set to :file:`HISTORY.rc`.
-
-BEG_DATE	
-   Simulation begin date in format YYYYMMDD hhmmss. This parameter is overrided in the presence of output file :file:`cap_restart` containing a different start date.
-
-END_DATE	
-   Simulation end date in format YYYYMMDD hhmmss. If BEG_DATE plus duration (JOB_SGMT) is before END_DATE then simulation will end at BEG_DATE + JOB_SGMT. If it is after then simulation will end at END_DATE.
-
-JOB_SGMT	
-   Simulation duration in format YYYYMMDD hhmmss. The duration must be less than or equal to the difference between start and end date or the model will crash.
-
-HEARTBEAT_DT	
-   The timestep of the ESMF/MAPL internal clock, in seconds. All other timesteps in GCHP must be a multiple of HEARTBEAT_DT. ESMF queries all components at each heartbeat to determine if computation is needed. The result is based upon individual component timesteps defined in :file:`GCHP.rc`.
-
-MAPL_ENABLE_TIMERS
-   Toggles printed output of runtime MAPL timing profilers. This is set to YES. Timing profiles are output at the end of every GCHP run.
-
-MAPL_ENABLE_MEMUTILS	
-   Enables runtime output of the programs' memory usage. This is set to YES.
-
-PRINTSPEC	
-   Allows an abbreviated model run limited to initializat and print of Import and Export state variable names. Options include: 
-
-   * 0 (default): Off
-   * 1: Imports and Exports only
-   * 2: Imports only
-   * 3: Exports only
-
-USE_SHMEM	
-   This setting is deprecated but still has an entry in the file.
-
-REVERSE_TIME	
-   Enables running time backwards in CAP. Default is 0 (off).
-
-----------------------------------
+GCHP.rc
+=======
 
 GCHP.rc
 ------------------
@@ -206,34 +155,3 @@ MEMORY_DEBUG_LEVEL
 
 WRITE_RESTART_BY_OSERVER	
    Determines whether MAPL restart write should use o-server. This must be set to YES for high core count (>1000) runs to avoid hanging during file write. It is NO by default.
-
-----------------------------------
-
-input.nml
------------------
-
-input.nml controls specific aspects of the FV3 dynamical core used for advection. Entries in input.nml are described below.
-
-&fms_nml	
-   Header for the FMS namelist which includes all variables directly below the header.
-
-print_memory_usage	
-   Toggles memory usage prints to log. However, in practice turning it on or off does not have any effect.
-
-domain_stack_size	
-   Domain stack size in bytes. This is set to 20000000 in GCHP to be large enough to use very few cores in a high resolution run. If the domain size is too small then you will get an "mpp domain stack size overflow error" in advection. If this happens, try increasing the domain stack size in this file.
-
-&fv_core_nml	
-   Header for the finite-volume dynamical core namelist. This is commented out by default unless running on a stretched grid. Due to the way the file is read, commenting out the header declaration requires an additional comment character within the string, e.g. :literal:`#&fv#_core_nml`.
-
-do_schmidt	
-   Logical for whether to use Schmidt advection. Set to .true. if using stretched grid; otherwise this entry is commented out.
-
-stretch_fac	
-   Stretched grid factor, equal to the ratio of grid resolution in targeted high resolution region to the configured run resolution. This is commented out if not using stretched grid.
-
-target_lat	
-   Target latitude of high resolution region if using stretched grid. This is commented out if not using stretched grid.
-
-target_lon	
-   Target longitude of high resolution region if using stretched grid. This is commented out if not using stretched grid.

docs/source/supplement/config-files/HEMCO.rst → docs/source/user-guide/config-files/HEMCO_Config_rc.rst

@@ -1,9 +1,6 @@
 
-HEMCO_Config.rc, HEMCO_Diagn.rc
-==================================
-
 HEMCO_Config.rc
------------------------
+===============
 
 Like :file:`geoschem_config.yml`, information about the :file:`HEMCO_Config.rc` file is the same as for GEOS-Chem Classic with a few exceptions. 
 Refer to the HEMCO documentation for an overview of the file.
@@ -29,12 +26,3 @@ In the BASE EMISSIONS section and beyond, columns that are ignored include:
 * SrcUnit
 
 All of the above information is specified in file :file:`ExtData.rc` instead with the exception of diagnostic prefix and frequency. Diagnostic filename and frequency information is specified in :file:`HISTORY.rc`.
-
----------------------------------
-
-HEMCO_Diagn.rc
------------------------
-
-Like in GEOS-Chem Classic, the :file:`HEMCO_Diagn.rc` file is used to map between HEMCO containers and output file diagnostic names. 
-However, while all uncommented diagnostics listed in :file:`HEMCO_Diagn.rc` are output as HEMCO diagnostics in GEOS-Chem Classic, only the subset also listed in :file:`HISTORY.rc` are output in GCHP. 
-See the HEMCO documentation for an overview of the file.

docs/source/user-guide/config-files/HEMCO_Diagn_rc.rst

@@ -0,0 +1,7 @@
+
+HEMCO_Diagn.rc
+==============
+
+Like in GEOS-Chem Classic, the :file:`HEMCO_Diagn.rc` file is used to map between HEMCO containers and output file diagnostic names. 
+However, while all uncommented diagnostics listed in :file:`HEMCO_Diagn.rc` are output as HEMCO diagnostics in GEOS-Chem Classic, only the subset also listed in :file:`HISTORY.rc` are output in GCHP. 
+See the HEMCO documentation for an overview of the file.

docs/source/user-guide/config-files/input_nml.rst

@@ -0,0 +1,28 @@
+input.nml
+=========
+
+input.nml controls specific aspects of the FV3 dynamical core used for advection. Entries in input.nml are described below.
+
+&fms_nml	
+   Header for the FMS namelist which includes all variables directly below the header.
+
+print_memory_usage	
+   Toggles memory usage prints to log. However, in practice turning it on or off does not have any effect.
+
+domain_stack_size	
+   Domain stack size in bytes. This is set to 20000000 in GCHP to be large enough to use very few cores in a high resolution run. If the domain size is too small then you will get an "mpp domain stack size overflow error" in advection. If this happens, try increasing the domain stack size in this file.
+
+&fv_core_nml	
+   Header for the finite-volume dynamical core namelist. This is commented out by default unless running on a stretched grid. Due to the way the file is read, commenting out the header declaration requires an additional comment character within the string, e.g. :literal:`#&fv#_core_nml`.
+
+do_schmidt	
+   Logical for whether to use Schmidt advection. Set to .true. if using stretched grid; otherwise this entry is commented out.
+
+stretch_fac	
+   Stretched grid factor, equal to the ratio of grid resolution in targeted high resolution region to the configured run resolution. This is commented out if not using stretched grid.
+
+target_lat	
+   Target latitude of high resolution region if using stretched grid. This is commented out if not using stretched grid.
+
+target_lon	
+   Target longitude of high resolution region if using stretched grid. This is commented out if not using stretched grid.

docs/source/user-guide/config-files/logging_yml.rst

@@ -0,0 +1,4 @@
+logging.yml
+===========
+
+Coming soon

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

@@ -15,19 +15,20 @@ Configuration files
 
 GCHP is controlled using a set of configuration files that are included in the GCHP run directory. Files include:
 
-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
-
-The following table lists the core functions of each of these files. 
-See the individual subsections on each file for additional information.
+.. toctree::
+   :maxdepth: 1
+
+   config-files/GCHP_rc.rst
+   config-files/CAP_rc.rst
+   config-files/ExtData_rc.rst
+   config-files/geoschem_config_yml.rst
+   config-files/HEMCO_Config_rc.rst
+   config-files/input_nml.rst
+   config-files/logging_yml.rst
+   config-files/HISTORY_rc.rst
+   config-files/HEMCO_Diagn_rc.rst
+
+In addition to these core configuration files are a helpful bash script, :file:`setCommonRunningSetting.sh`, to edit commonly changed settings in other files from one place. This section lists the core functions of all of these files.
 
 setCommonRunSettings.sh
 ^^^^^^^^^^^^^^^^^^^^^^^