Updates to ExtData.rc section and minimum ESMF version

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

docs/source/getting-started/requirements.rst

@@ -26,7 +26,7 @@ To build and run GCHP your compute :term:`environment` needs the following softw
 
 * HDF5
 * NetCDF (with C, C++, and Fortran support)
-* Earth System Modeling Framework (ESMF) version ≥ 8.1.0
+* Earth System Modeling Framework (ESMF) version 8.4.2 recommended. Problems with 8.1 and prior have been reported.
 
 Your system administrator should be able to tell you if this software is already available on your cluster, and if so, how to activate it.
 If it is not already available, they might be able to build it for you.

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

@@ -4,43 +4,54 @@ 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. 
 The file format is the same as that used in the GEOS model, and GMAO/NASA documentation for it can be found at the ExtData component page on the GEOS-5 wiki.
+Note that this file will be retired in GCHP v15.0 when MAPL version 3 is integrated into GCHP. It will be replaced with a YAML format file with a
+simplified and easier to understand interface.
+
+The ins and outs of :file:`ExtData.rc` can be hard to grasp, particular with regards to variable data
+updating, time interpolation, and file read. Reach out on the GCHP GitHub Issues page if you need help. See also the GCHP ReadTheDocs page on enabling
+ExtData prints for debugging. Enable ExtData debug prints is the best way to determine what MAPL is doing for file I/O per import.
 
 The following two parameters are set at the top of the file:
 
 Ext_AllowExtrat	
-   Logical toggle to use data from nearest year available. This is set to true for GCHP. Note that GEOS-Chem Classic accomplishes the same effect but with more flexibility in :file:`HEMCO_Config.rc`. That functionality of :file:`HEMCO_Config.rc` is ignored in GCHP.
-
-DEBUG_LEVEL	
-   Turns MAPL ExtData debug prints on/off. This is set to 0 in GCHP (off), but may be set to 1 to enable. Beware that turning on ExtData debug prints greatly slows down the model, and prints are only done from the root thread. Use this when debugging problems with input files.
+   Logical toggle to use data from nearest year available, including meteorology if files for the simulation year are not found. This is set to true for GCHP. Note that GEOS-Chem Classic accomplishes the same effect but with more flexibility in :file:`HEMCO_Config.rc`, and the entries of :file:`HEMCO_Config.rc` which do this are ignored in GCHP.
 
-The rest of the file contains space-delimited lines, one for each variable imported to the model from an external file. 
-Columns are as follows in order as they appear left to right in the file:
+The rest of the file contains whitespace-delimited lines. Each line describes one data variable imported to the model from an external file. 
+Columns are as follows in order from left to right:
 
-Export Name	
-   Name of imported met field (e.g. ALBD) or HEMCO emissions container name (e.g. GEIA_NH3_ANTH).
+Name	
+   Name of the field stored in the MAPL Imports container. This is independent of the name of the data field in the input file. For the case of entries that also appear in :file:`HEMCO_Config.rc` it is also the name of the HEMCO emissions container (left-most column in that file). For those fields it is used to match scaling and masking information in :file:`HEMCO_Config.rc` with file I/O information in :file:`ExtData.rc`.
 
 Units	
-   Unit string nested within single quotes. '1' indicates there is no unit conversion from the native units in the netCDF file.
+   Unit string of the import. This entry is informational only.
+
 Clim	
-   Enter Y if the file is a 12 month climatology, otherwise enter N. If you specify it is a climatology ExtData the data can be on either one file or 12 files if they are templated appropriately with one per month.
+   Whether the data is climatology. Enter :file:`Y` if the data is a 12 month climatology, data year if the data is daily climatology (i.e. :file:`2019`), :file:`D` if the file is monthly day-of-week scale factors (7 values for each of 12 months), or :file:`N` for all other cases. If you specify monthly climatology then the data must be stored in either 1 or 12 files.
+
 Conservative	
-   Enter Y the data should be regridded in a mass conserving fashion through a tile file. :literal:`F;{VALUE}` can also be used for fractional regridding. Otherwise enter N to use the non-conervative bilinear regridding.
+   Method to regrid the input data to the simulation grid. Enter Y to use mass conserving regridding, :literal:`F;{VALUE}` for fractional regridding, or N to use non-conervative bilinear regridding.
 
 Refresh 
-   Time Template	Possible values include:
+   Time template for frequency of updating data. This tells MAPL when to look for new data values. There are several options for specifying refresh:
 
-   * -: The field will only be updated once the first time ExtData runs
-   * 0: Update the variable at every step. ExtData will do a linear interpolation to the current time using the available data.
-   * %y4-%m2-%h2T%h2:%n2:00: Set the recurring time to update the file. The file will be updated when the evaluated template changes. For example, a template in the form %y4-%m2-%d2T12:00:00 will cause the variable to be updated at the start of a new day (i.e. when the clock hits 2007-08-02T00:00:00 it will update the variable but the time it will use for reading and interpolation is 2007-08-02T12:00:00).
+   * :file:`-` : Update variable data only once. Use this if the data is constant in time.
+   * :file:`0` : Update variable data at every timestep using linear interpolation. For example, if the data is hourly then MAPL will linearly interpolate between the previous and next hour's data for every timestep.
+   * :file:`0:003000` (or other HHMMSS specification for hours, minutes, seconds) : Use specified time offset (i.e. 30 minutes in this example) for setting previous and next time, and interpolate every timestep between the two. This is useful if, for example, you have time-averaged hourly data and you want the previous and next times to update half-way between the hour. This format is used for meteorology fields that are interpolated every timestep, specifically temperature and surface pressure.
+   * :file:`F0:003000` (or other HHMMSS specification for hours, minutes, seconds) : Like the previous option except there is no time interpolation. This format is used for meteorology fields that are not time-interpolated, such as cloud fraction.
+   * :file:`%y4-%m2-%h2T%h2:%n2:00` (or other combination of time tokens) : Update variable data when time tokens change. Interpreting this entry gets a little tricky. The data will be updated when the time tokens change, not he hard-coded times. For example, a template in the form %y4-%m2-%d2T12:00:00 changes at the start of each day because that is when the evaluation of %y4-%m2-%d2 changes. While the variable will be updated at the start of a new day (i.e. at time 2019-01-02T00:00:00), the time used for reading and interpolation is 2007-08-02T12:00:00).
+   * :file:`F%y4-%m2-%h2T%h2:%n2:00` (or other combination of time tokens) : Like the previous option except that there is no time interpolation.
 
 Offset Factor	
-   Factor the variable will be shifted by. Use none for no shifting.
+   Value the data will be shifted by upon read. Use :file:`none` for no shifting.
 
 Scale Factor	
-   Factor the variable will be scaled by. Use none for no scaling.
+   Value the data will be scaled by upon read. Use :file:`none` for no scaling.
 
 External File Variable	
-   The name of the variable in the netCDF data file, e.g. ALBEDO in met fields.
+   Name of the variable to read in the netCDF data file.
 
 External File Template	
-   Path to the netCDF data file. If not using the data, specify :file:`/dev/null` to reduce processing time. If there are no tokens in the template name ExtData will assume that all the data is on one file. Note that if the data on file is at a different resolution that the application grid, the underlying I/O library ExtData uses will regrid the data to the application grid.
+   Path to the netCDF data file, including time tokens as needed (%y4 for year, %m2 for month, %d2 for day, %h2 for hour, %n2 for minutes). If there are no time tokens in the template name then ExtData will assume that all the data is on one file. If you wish to ignore an entry in :file:`ExtData.rc` (i.e. not read then data) then put :file:`/dev/null` to reduce processing time. 
+
+Reference Time (optional)
+   Reference time and frequency of data. This optional entry is useful if you have data frequency that is offset from midnight. For example, 3-hourly data available for times 1:30, 4:30, 7:30, etc. The reference time could be specified as :file:`2000-01-01T01:30:00P03:00`. The first part (before :file:`P`) is the reference date (must be on or before your simulation start), and the second part (after :file:`P`) is the period of data availability (in this case 3 hours). This can be used in combination with the file template containing hours and minutes. It tells MAPL to only read the file at times that are regular 3 hr intervals from the reference date and time. Not including this would cause MAPL to read the file every minute if the file template contains the :file:`n2` time token.