Add output files page and specify version for all requirements

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

docs/requirements.txt

@@ -7,9 +7,9 @@
 # compatibility with the older ReadTheDocs package, so we need to
 # use a version of jinja2 prior to 3.1.0. (Bob Yantosca, 02 May 2022)
 #
-sphinx<4.0.0
+sphinx==3.5.4
 sphinx_rtd_theme==0.5.2
 sphinxcontrib-bibtex==2.2.0
 recommonmark
 docutils==0.16
-jinja2<3.1.0
+jinja2==3.0.3

docs/source/index.rst

@@ -56,6 +56,7 @@ with Spack, as well as how to use Spack to install GCHP's dependencies if needed
    user-guide/getting-input-data.rst
    user-guide/running.rst
    user-guide/rundir-config.rst
+   user-guide/output_files.rst
 
 .. toctree::
    :maxdepth: 1

docs/source/user-guide/output_files.rst

@@ -0,0 +1,47 @@
+Output Files
+============
+
+A successful GCHP run produces three categories of output files: diagnostics, restarts (also called checkpoints), and logs. Diagnostic and restart files are always in netCDF4 format, and logs are always ascii viewable with any text editor. Diagnostic files are output to the :file:`OutputDir` directory in the run directory. The end-of-run restart file is output to the :file:`Restarts` directory. All other output files, including periodic checkpoints if enabled, are saved to the main level of the run directory.
+
+.. note::
+   It is important to be aware that GCHP 3D data files in this version of GCHP have two different vertical dimension conventions. Restart files and Emissions diagnostic files are defined with top-of-atmospheric level equal to 1. All other data files, meaning all diagnostic files that are not Emissions collections, are defined with surface level equal to 1. This means files may be vertically flipped relative to each other. This should be taken into account when doing data visualization and analysis using these files.
+
+Descriptions
+------------
+
+:file:`gchp.YYYYMMSS_HHmmSSz.log`
+   Standard output log file of GCHP, including both GEOS-Chem and HEMCO. The date in the filename is the start date of the simulation. Using this file is technically optional since it appears only in the run script. However, the advantage of sending GCHP standard output to this file is that the logs of consecutive runs will not be over-written due to the date in the filename. Note that the file contains HEMCO log information as well as GEOS-Chem. Unlike in GEOS-Chem Classic there is no :file:`HEMCO.log` in GCHP. 
+
+:file:`batch job file, e.g. slurm-jobid.out`
+   If you use a job scheduler to submit GCHP as a batch job then you will have a job log file. This file will contain output from your job script unless sent to a different file. If your run crashes then the MPI error messages and error traceback will also appear in this file.
+
+:file:`allPES.log`
+   GCHP logging output based on configuration in :file:`logging.yml`. Treat this file as a debugging tool to help diagnose problems in MAPL, particularly the ExtData component of the model which handles input reading and regridding.
+
+:file:`logfile.000000.out`
+   Log file for advection. It includes information such as the domain stack size, stretched grid factors, and FV3 parameters used in the run.
+
+:file:`cap_restart`
+   This file is both input and output. As an input file it contains the simulation start date. After a successful run the content of the file is updated to the simulation end date. As an output file it is therefore the input file for the next run if running GCHP simulations consecutively in time.
+
+:file:`Restarts/GEOSChem.Restart.YYYYMMDD_HHmmSSz.cN.nc4`
+   GCHP restart file output at the end of the run. This file is actually the GCHP end-of-run checkpoint file that is moved and renamed as part of the run script. Unless including the code to do that in your run script you will instead get :file:`gcchem_internal_checkpoint` in the main run directory. Moving and renaming is a better option because (1) it includes the datetime to prevent overwriting upon consecutive runs, (2) it enables using the :file:`gchp_restart.nc4` symbolic link in the main run directory to automatically point to the correct restart file based on start date and grid resolution, and (3) it minimizes clutter in the run directory. Please note that the vertical level dimension in all GCHP restart files is positive down, meaning level 1 is top-of-atmosphere.
+
+:file:`OutputDir/GEOSChem.HistoryCollectionName.YYYYMMDD_HHmmz.nc4`
+   GCHP diagnostic data files. Each file contains the collection name configured in :file:`HISTORY.rc` and the datetime of the first data in the file. For time-averaged data files the datetime is the start of the averaging period. Please note that the vertical level dimension in GCHP diagnostics files is collection-dependent. Data are positive down, meaning level 1 is top-of-atmosphere, for the Emissions collection. All other collections are positive up, meaning level 1 is surface.
+
+:file:`HistoryCollectionName.rcx`
+   Summary of settings used to generate data in each diagnostic collection file that is output.
+
+:file:`EGRESS`
+   This file is empty and can be ignored. It is an artifact of the MAPL software used in GCHP.
+
+:file:`warnings_and_errors.log`
+   This file is empty and can be ignored.
+
+Data visualization and post-processing
+--------------------------------------
+
+With the exception of the restart file, all GCHP output netCDF files may be viewed with Panoply software freely available from NASA GISS. In addition, the GEOS-Chem python package GCPy is fully functional with GCHP output files. 
+
+

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

@@ -18,8 +18,7 @@ This section gives an overview of all run directory configuration files used at
 .. toctree::
    :maxdepth: 1
 
-   :ref:`setCommonRunSetting.sh <_setCommonRunSettings_sh>`
-   :ref:`GCHP.rc <_GCHP_rc>`
+   config-files/GCHP_rc.rst
    config-files/CAP_rc.rst
    config-files/ExtData_rc.rst
    config-files/geoschem_config_yml.rst
@@ -36,7 +35,7 @@ The run directory also includes bash script :file:`setCommonRunningSetting.sh` t
 
 :file:`setCommonRunSettings.sh`
 
-This file is 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.
+   This file is 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.
 
 .. _GCHP_rc: