Difference between revisions of "GCHP Run Configuration Files"

Latest revision as of 15:41, 8 December 2020

The GCHP documentation has moved to https://gchp.readthedocs.io/. The GCHP documentation on http://wiki.seas.harvard.edu/ will stay online for several months, but it is outdated and no longer active!

Previous | Getting Started with GCHP | GCHP Main Page

Hardware and Software Requirements
Setting Up the GCHP Environment
Downloading Source Code and Data Directories
Compiling
Obtaining a Run Directory
Running GCHP: Basics
Running GCHP: Configuration
Output Data
Developing GCHP
Run Configuration Files

Overview

GCHP is controlled using a set of resource configuration files that are included in the GCHP run directory, most of which are denoted by suffix .rc. These files contain all run-time information required by GCHP. Files include:

CAP.rc
ExtData.rc
GCHP.rc
input.geos
HEMCO_Config.rc
HEMCO_Diagn.rc
input.nml
HISTORY.rc

As described in the Running GCHP: Configuration chapter of this user guide, much of the labor of updating the configuration files has been eliminated by run directory shell script runConfig.sh. It is important to remember that sourcing runConfig.sh will overwrite settings in other configuration files, and you therefore should never manually update other configuration files unless you know the specific option is not available in runConfig.sh.

That being said, it is still worth understanding the contents of all configuration files and what all run options include. This page details the settings within all configuration files and what they are used for.

Configuration file descriptions

The following table lists the core functions of each of the configuration files in the GCHP run directory. See the individual subsections on each file for additional information.

File	Primary function in GCHP
`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 `/dev/null`.
`GCHP.rc`	Controls high-level aspects of the simulation, including grid type and resolution, core distribution, stretched-grid parameters, timesteps, and restart file configuration.
`input.geos`	Primary config file for GEOS-Chem. Same function as in GEOS-Chem Classic except grid, simulation start/end, met field source, timers, and data directory information are ignored.
`HEMCO_Config.rc`	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 `ExtData.rc`. All HEMCO variables listed in `HEMCO_Config.rc` for enabled emissions must also have an entry in `ExtData.rc`.
`HEMCO_Diagn.rc`	Contains information mapping `HISTORY.rc` diagnostic names to HEMCO containers. Same function as in GEOS-Chem Classic except that not all items in `HEMCO_Diagn.rc` will be output; only emissions listed in `HISTORY.rc` will be included in diagnostics. All GCHPctm diagnostics listed in `HISTORY.rc` that start with `Emis`, `Hco`, or `Inv` must have a corresponding entry in `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.

CAP.rc

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 cap_restart, CAP.rc configures the exact dates for the next GCHP run.

Parameter	Description
`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 `GCHP.rc`.
`HIST_CF`	Resource configuration file for the MAPL HISTORY gridded component (another child gridded component of CAP). It is set to `HISTORY.rc`.
`BEG_DATE`	Simulation begin date in format `YYYYMMDD hhmmss`. This parameter is overrided in the presence of output 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 `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; and `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).

ExtData.rc

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.

The following two parameters are set at the top of the file:

Parameter Name	Description
`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 `HEMCO_Config.rc`. That functionality of `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.

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:

Name in Column Header	Description
`Export Name`	Name of imported met field (e.g. `ALBD`) or HEMCO emissions container name (e.g. `GEIA_NH3_ANTH`).
`Units`	Unit string nested within single quotes. `'1'` indicates there is no unit conversion from the native units in the netCDF file.
`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.
`Conservative`	Enter `Y` the data should be regridded in a mass conserving fashion through a tile file. `F;{VALUE}` can also be used for fractional regridding. Otherwise enter `N` to use the non-conervative bilinear regridding.
`Refresh Time Template`	Possible values include: `-`: 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).
`Offset Factor`	Factor the variable will be shifted by. Use `none` for no shifting.
`Scale Factor`	Factor the variable will be scaled by. Use `none` for no scaling.
`External File Variable`	The name of the variable in the netCDF data file, e.g. `ALBEDO` in met fields.
`External File Template`	Path to the netCDF data file. If not using the data, specify `/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.

GCHP.rc

GCHP.rc is the resource configuration file for the ROOT component within GCHP. The ROOT gridded component includes three children gridded components, including one each for GEOS-Chem, FV3 advection, and the data utility environment needed to support them.

Parameter	Description
`NX, NY`	Number of grid cells in the two MPI sub-domain dimensions. NX * NY must equal the number of CPUs. NY must be a multiple of 6.
`GCHP.GRID_TYPE`	Type of grid GCHP will be run at. Should always be `Cubed-Sphere`.
`GCHP.GRIDNAME`	Descriptive grid label for the simulation. The default grid name is `PE24x144-CF`. The grid name includes how the pole is treated, the face side length, the face side length times six, and whether it is a Cubed Sphere Grid or Lat/Lon. The name `PE24x144-CF` indicates polar edge (PE), 24 cells along one face side, 144 for 246, and a cubed-sphere grid (CF). Many options here are defined in MAPL_Generic. Must be consistent with `IM` and `JM`.'*
`GCHP.NF`	Number of cubed-sphere faces. This is set to 6.
`GCHP.IM_WORLD`	Number of grid cells on the side of a single cubed sphere face.
`GCHP.IM`	Number of grid cells on the side of a single cubed sphere face.
`GCHP.JM`	Number of grid cells on one side of a cubed sphere face, times 6. This represents a second dimension if all six faces are stacked in a 2-dimensional array. Must be equal to IM*6.
`GCHP.LM`	Number of vertical grid cells. This must be equal to the vertical resolution of the offline meteorological fields (72) since MAPL cannot regrid vertically.
`GCHP.STRETCH_FACTOR`	Ratio of configured global resolution to resolution of targeted high resolution region if using stretched grid.
`GCHP.TARGET_LON`	Target longitude for high resolution region if using stretched grid.
`GCHP.TARGET_LAT`	Target latitude for high resolution region if using stretched grid.
`IM`	Same as `GCHP.IM` and `GCHP.IM_WORLD`.
`JM`	Same as `GCHP.JM`.
`LM`	Same as `GCHP.LM`.
`GEOChem_CTM`	If set to 1, tells FVdycore that it is operating as a transport model rather than a prognostic model.
`AdvCore_Advection`	Toggles offline advection. 0 is off, and 1 is on.
`DYCORE`	Should either be set to OFF (default) or ON. This value does nothing, but MAPL will crash if it is not declared.
`HEARTBEAT_DT`	The timestep in seconds that the DYCORE Component should be called. This must be a multiple of `HEARTBEAT_DT` in `CAP.rc`.
`SOLAR_DT`	The timestep in seconds that the SOLAR Component should be called. This must be a multiple of `HEARTBEAT_DT` in `CAP.rc`.
`IRRAD_DT`	The timestep in seconds that the IRRAD Component should be called. ESMF checks this value during its timestep check. This must be a multiple of `HEARTBEAT_DT` in `CAP.rc`.
`RUN_DT`	The timestep in seconds that the RUN Component should be called.
`GCHPchem_DT`	The timestep in seconds that the GCHPchem Component should be called. This must be a multiple of `HEARTBEAT_DT` in `CAP.rc`.
`RRTMG_DT`	The timestep in seconds that RRTMG should be called. This must be a multiple of `HEARTBEAT_DT` in `CAP.rc`.
`DYNAMICS_DT`	The timestep in seconds that the FV3 advection Component should be called. This must be a multiple of `HEARTBEAT_DT` in `CAP.rc`.
`SOLARAvrg, IRRADAvrg`	Default is 0.
`GCHPchem_REFERENCE_TIME`	HHMMSS reference time used for GCHPchem MAPL alarms.
`PRINTRC`	Specifies which resource values to print. Options include 0: non-default values, and 1: all values. Default setting is 0.
`PARALLEL_READFORCING`	Enables or disables parallel I/O processes when writing the restart files. Default value is 0 (disabled).
`NUM_READERS, NUM_WRITERS`	Number of simultaneous readers. Should divide evenly unto `NY`. Default value is 1.
`BKG_FREQUENCY`	Active observer when desired. Default value is 0.
`RECORD_FREQUENCY`	Frequency of periodic restart file write in format HHMMSS.
`RECORD_REF_DATE`	Reference date(s) used to determine when to write periodic restart files.
`RECORD_REF_TIME`	Reference time(s) used to determine when to write periodic restart files.
`GCHOchem_INTERNAL_RESTART_FILE`	The filename of the internal restart file to be written.
`GCHPchem_INTERNAL_RESTART_TYPE`	The format of the internal restart file. Valid types include `pbinary` and `pnc4`. Only use `pnc4` with GCHP.
`GCHPchem_INTERNAL_CHECKPOINT_FILE`	The filename of the internal checkpoint file to be written.
`GCHPchem_INTERNAL_CHECKPOINT_TYPE`	The format of the internal checkstart file. Valid types include `pbinary` and `pnc4`. Only use `pnc4` with GCHP.
`GCHPchem_INTERNAL_HEADER`	Only needed when the file type is set to `pbinary`. Specifies if a binary file is self-describing.
`DYN_INTERNAL_RESTART_FILE`	The filename of the DYNAMICS internal restart file to be written. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file.
`DYN_INTERNAL_RESTART_TYPE`	The format of the DYNAMICS internal restart file. Valid types include `pbinary` and `pnc4`. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file.
`DYN_INTERNAL_CHECKPOINT_FILE`	The filename of the DYNAMICS internal checkpoint file to be written. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file.
`DYN_INTERNAL_CHECKPOINT_TYPE`	The format of the DYNAMICS internal checkpoint file. Valid types include `pbinary` and `pnc4`. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file.
`DYN_INTERNAL_HEADER`	Only needed when the file type is set to `pbinary`. Specifies if a binary file is self-describing.
`RUN_PHASES`	GCHP uses only one run phase. The GCHP gridded component for chemistry, however, has the capability of two. The two-phase feature is used only in GEOS.
`HEMCO_CONFIG`	Name of the HEMCO configuration file. Default is `HEMCO_Config.rc` in GCHP.
`STDOUT_LOGFILE`	Log filename template. Default is `PET%%%%%.GEOSCHEMchem.log`. This file is not actually used for primary standard output.
`STDOUT_LOGLUN`	Logical unit number for stdout. Default value is 700.
`MEMORY_DEBUG_LEVEL`	Toggle for memory debugging. Default is 0 (off).
`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.geos

Information about the input.geos file is the same as for GEOS-Chem Classic with a few exceptions. See the input.geos file wiki page for an overview of the file.

The input.geos file used in GCHP is different in the following ways:

Start/End datetimes are ignored. Set this information in CAP.rc instead.
Root data directory is ignored. All data paths are specified in ExtData.rc instead with the exception of the FAST-JX data directory which is still listed (and used) in input.geos.
Met field is ignored. Met field source is described in file paths in ExtData.rc.
GC classic timers setting is ineffectual. GEOS-Chem Classic timers code is not compiled when building GCHP.

Other parts of the GEOS-Chem Classic input.geos file that are not relevant to GCHP are simply not included in the file that is copied to the GCHP run directory.

HEMCO_Config.rc

Like input.geos, information about the HEMCO_Config.rc file is the same as for GEOS-Chem Classic with a few exceptions. See the [[The_HEMCO_Config.rc_file |HEMCO_Config.rc file wiki page]] for an overview of the file.

Some content of the HEMCO_Config.rc file is ignored by GCHP. This is because MAPL ExtData handles file input rather than HEMCO in GCHP.

Items at the top of the file that are ignored include:

ROOT data directory path
METDIR path
DiagnPrefix
DiagnFreq
Wildcard

In the BASE EMISSIONS section and beyond, columns that are ignored include:

sourceFile
sourceVar
sourceTime
C/R/E
SrcDim
SrcUnit

All of the above information is specified in file ExtData.rc instead with the exception of diagnostic prefix and frequency. Diagnostic filename and frequency information is specified in HISTORY.rc.

HEMCO_Diagn.rc

Like in GEOS-Chem Classic, the HEMCO_Diagn.rc file is used to map between HEMCO containers and output file diagnostic names. However, while all uncommented diagnostics listed in HEMCO_Diagn.rc are output as HEMCO diagnostics in GEOS-Chem Classic, only the subset also listed in HISTORY.rc are output in GCHP. See the HEMCO_Diagn.rc file wiki page for an overview of the file.

input.nml

input.nml controls specific aspects of the FV3 dynamical core used for advection. Entries in input.nml are described below.

Parameter	Description
`&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. `#&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.

HISTORY.rc

The HISTORY.rc configuration file controls the diagnostic files output by GCHP. Information is organized into several sections:

Single parameters set at the top of the file
Grid label declaration list
Definition for each grid in grid label list
Variable collection declaration list
Definition for each collection in collection list.

Single parameters set at the top of HISTORY.rc are as follows and apply to all collections:

Parameter	Description
`EXPID`	Filename prefix concatenated with each collection template string to define file path. It is set to `OutputDir/GCHP` so that all output diagnostic files are output to run subdirectory `OutputDir` and have filename begin with `GCHP`.
`EXPDSC`	Export description included as attribute "Title" in output files
`CoresPerNode`	Number of CPUs per node for your simulation.
`VERSION`	Optional parameter included as attribute in output file.

The grid labels section of HISTORY.rc declares a list of descriptive grid strings followed by a definition for each declared grid label. Grids not in the grid label list may have definitions in the file; however, this will prevent them from being used in output collections. See the HISTORY.rc grid label section for syntax on declaring and defining grid labels.

Keywords that may be used for grid label definitions are in the table below. Note that this list is not exhaustive; MAPL may have additional keywords that may be used that have not yet been explored for use with GCHP.

Grid label keyword	Description
`GRID_TYPE`	Type of grid. May be `Cubed-Sphere` or `LatLon`.
`IM_WORLD`	Side length of one cubed-sphere face, e.g. 24 if grid resolution is C24, or number of longitudinal grid boxes if lat-lon.
`JM_WORLD`	Same as `IM_WORLD` but multiplied by 6 (number of faces), or number of latitudinal grid boxes if lat-lon.
`POLE`	For lat-lon grids only. `PC` if latitudes are pole-centered and `PE` if latitudes are polar edge.
`DATELINE`	For lat-lon grids only. `DC` if longitudes are dateline-centered and `DE` if longitudes are dateline-edge.
`LAT_RANGE`	For lat-lon grids only. Regional grid latitudinal bounds.
`LON_RANGE`	For lat-lon grids only. Regional grid longitudinal bounds.
`LM`	Number of vertical levels.

The collections section of HISTORY.rc declares a list of descriptive strings that define unique collections of output variables and settings. As with grid labels, it is followed by a definition for each declared collection. Collections not in the collection list, or present but commented out, may have definitions in the file; however, this will prevent them from being output. See the HISTORY.rc collection section for syntax on declaring and defining output collections.

Keywords that may be used for collection definitions are in the table below. Note that this list is not exhaustive; MAPL may have additional keywords that may be used that have not yet been explored for use with GCHP.

Collection keyword	Description
`{COLLECTION}.template`	The output filename suffix that is appended to global parameter `EXPID` to define full output file path. Including a date string, such as `'%y4%m2%d2`, will insert the simulation start day following GrADS conventions. The default template for GCHP is set to `%y4%m2%d2_%h2%n2z.nc4`.
`{COLLECTION}.format`	Character string defining the file format. Options include `CFIO` (default) for netCDF-4 or `flat` for binary files. Always output as `CFIO` when using GCHP.
`{COLLECTION}.grid_label`	Declared grid label for output grid. If excluded the collection will be output on the cubed-sphere grid at native resolution, e.g. C24 if you run GCHP with grid resolution C24.
`{COLLECTION}.conservative`	For lat-lon grids only. Set to 1 to conservatively regrid from cubed-sphere to lat-lon upon output. Exclude or set to 0 to use bilinear interpolation instead (not recommended).
`{COLLECTION}.frequency`	The frequency at which output values are computed and archived, in format `HHMMSS`. For example, `010000` will calculate diagnostics every hour. The method of calculation is determined by the `mode` keyword. Unlike GEOS-Chem Classic, you cannot specify number of days, months, or years.
`{COLLECTION}.duration`	The frequency at which files are written, in format `HHMMSS`. For example, `240000` will output daily files. The number of times in the file are determined by the `frequency` keyword. Unlike GEOS-Chem Classic, you cannot specify number of days, months, or years.
`{COLLECTION}.mode`	Method of diagnostic calculation. Options are either `instantaneous` or `time-averaged`.
`{COLLECTION}.fields`	List of character string pairs including diagnostic name and gridded component. All GCHP diagnostics belong to the `GCHPchem` gridded component. Diagnostic names have prefixes that determine where MAPL History will look for them. Prefixes `Emis`, `Inv`, and `Hco` are HEMCO diagnostics and must have definitions in config file `HEMCO_Diagn.rc`. Prefixes `Chem` and `Met` are GEOS-Chem state variables stored in objects `State_Chm` and `State_Met` respectively. Prefix `SPC` corresponds to internal state species, meaning the same arrays that are output to the restart file. Prefix `GEOS` is reserved for use in the `GEOS` model. All other diagnostic name prefixes are interpreted as variables stored in the GEOS-Chem `State_Diag` object.

Previous | Getting Started with GCHP | GCHP Main Page

Difference between revisions of "GCHP Run Configuration Files"

Latest revision as of 15:41, 8 December 2020

Contents

Overview

Configuration file descriptions

CAP.rc

ExtData.rc

GCHP.rc

input.geos

HEMCO_Config.rc

HEMCO_Diagn.rc

input.nml

HISTORY.rc

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools

@@ Line 1: / Line 1: @@
-'''''[[Developing_GCHP|Previous]] | [[Getting_Started_With_GCHP|User Manual Home]] | [[GCHP_Main_Page|GCHP Main Page]]'''''
+----
+<span style="color:crimson;font-size:120%">'''The GCHP documentation has moved to https://gchp.readthedocs.io/.''' The GCHP documentation on http://wiki.seas.harvard.edu/ will stay online for several months, but it is outdated and no longer active!</span>
+----
+'''''[[Developing_GCHP|Previous]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]'''''
 #[[GCHP_Hardware_and_Software_Requirements|Hardware and Software Requirements]]
+#[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]]
 #[[Downloading_GCHP|Downloading Source Code and Data Directories]]
+#[[Compiling_GCHP|Compiling]]
 #[[Obtaining_a_GCHP_Run_Directory|Obtaining a Run Directory]]
-#[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]]
-#[[Compiling_GCHP|Compiling]]
 #[[Running_GCHP:_Basics|Running GCHP: Basics]]
 #[[Running_GCHP:_Configuration|Running GCHP: Configuration]]
@@ Line 14: / Line 18: @@
 == Overview ==
-GCHP is controlled using a set of resource configuration files that are included in the GCHP run directory and are denoted by suffix <tt>.rc</tt>. These files contain information required by GCHP including hardware allocation, initialization and runtime parameters, locations of necessary files, and where, what and how to read and write data to and from GCHP. Files include:
+GCHP is controlled using a set of resource configuration files that are included in the GCHP run directory, most of which are denoted by suffix <tt>.rc</tt>. These files contain all run-time information required by GCHP. Files include:
 #[[#CAP.rc|CAP.rc]]
 #[[#ExtData.rc|ExtData.rc]]
 #[[#GCHP.rc|GCHP.rc]]
+#[[#input.geos|input.geos]]
+#[[#HEMCO_Config.rc|HEMCO_Config.rc]]
+#[[#HEMCO_Diagn.rc|HEMCO_Diagn.rc]]
+#[[#input.nml|input.nml]]
 #[[#HISTORY.rc|HISTORY.rc]]
-#[[#fvcore_layout.rc|fvcore_layout.rc]]
-#[[#input.nml|input.nml]]
-Within GCHP, GEOS-Chem also still relies upon settings controlled by <tt>input.geos</tt> and <tt>HEMCO_Config.rc</tt>. However, several of the entries are superseded by settings in the config files or must be set consistently across multiple files. Inconsistencies may result in your program crashing or yielding unexpected results.
+As described in the [[Running_GCHP:_Configuration|Running GCHP: Configuration]] chapter of this user guide, much of the labor of updating the configuration files has been eliminated by run directory shell script <tt>runConfig.sh</tt>. It is important to remember that sourcing <tt>runConfig.sh</tt> will overwrite settings in other configuration files, and you therefore should never manually update other configuration files unless you know the specific option is not available in <tt>runConfig.sh</tt>.
-To avoid mistakes and make run configuration easier, we include bash shell script <tt>runConfig.sh</tt> to update the most commonly used settings in the configuration files, with the exceptions of <tt>HEMCO_Config.rc</tt> and <tt>ExtData.rc</tt> which must be edited manually (e.g. if you turn on/off, edit, remove, or add emissions). Executing this script will over-write existing values in files and write the new settings to output file <tt>runConfig.log</tt>. The sample run scripts, e.g. <tt>gchp.run</tt>, that comes with the run directory includes executing <tt>runConfig.sh</tt> prior to submitting a GCHP run job.
+That being said, it is still worth understanding the contents of all configuration files and what all run options include. This page details the settings within all configuration files and what they are used for.
-Using <tt>runConfig.sh</tt> to configure common settings makes run configure much simpler, but also comes with peril. If you edit a different config file with a setting that is also configured in <tt>runConfig.sh</tt> then your update will be over-written. This is a common mistake that new users make, particularly when editing the diagnostics frequency in HISTORY.rc since they may be used to editing that for GEOS-Chem Classic. Please get very familiar with the options in <tt>runConfig.sh</tt> and be conscientious about not updating the same setting elsewhere.
+== Configuration file descriptions ==
-While much of the labor of updating the various configuration files has been eliminated by <tt>runConfig.sh</tt>, it is still worth understanding what is happening under the hood with the other files. This page details the settings within those other configuration files and what they are used for, as well as how you should set them if you were running GCHP without <tt>runConfig.sh</tt>.
-== Configuration File Descriptions ==
 The following table lists the core functions of each of the configuration files in the GCHP run directory. See the individual subsections on each file for additional information.
@@ Line 38: / Line 40: @@
 !width="280px"|File
 !width="720px"|Primary function in GCHP
-|-valign="top"
-| <tt>input.geos</tt>
-| Controls which aspects of the chemistry simulation are run. Note that input.geos does not currently control input and output information such as restart file, met-field paths, and diagnostics.
 |-valign="top"
 | <tt>CAP.rc</tt>
-| Controls the simulation timing parameters such as start date and duration.
+| 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).
 |-valign="top"
 | <tt>ExtData.rc</tt>
-| Specifies where all input files are located. All files requested by GCHP must be specified in this file. Using default values can be given by specifying the path as “/dev/null”.
+| 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 <tt>/dev/null</tt>.
 |-valign="top"
 | <tt>GCHP.rc</tt>
-| Controls all major aspects of the simulation. Grid resolution, core distribution, timesteps, and restart files are be defined in this file.
+| Controls high-level aspects of the simulation, including grid type and resolution, core distribution, stretched-grid parameters, timesteps, and restart file configuration.
 |-valign="top"
-| <tt>HISTORY.rc</tt>
+| <tt>input.geos</tt>
-| Controls and directs output from GCHP.
+| Primary config file for GEOS-Chem. Same function as in GEOS-Chem Classic except grid, simulation start/end, met field source, timers, and data directory information are ignored.
 |-valign="top"
-| <tt>fvcore_layout.rc</tt>
+| <tt>HEMCO_Config.rc</tt>
-| Specifies the cubed-sphere layout for the FV3 dynamic core. Grid resolution and timestep are included in this file and must match values in other configuration files.
+| 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 <tt>ExtData.rc</tt>. All HEMCO variables listed in <tt>HEMCO_Config.rc</tt> for enabled emissions must also have an entry in <tt>ExtData.rc</tt>.
+|-valign="top"
+| <tt>HEMCO_Diagn.rc</tt>
+| Contains information mapping <tt>HISTORY.rc</tt> diagnostic names to HEMCO containers. Same function as in GEOS-Chem Classic except that not all items in <tt>HEMCO_Diagn.rc</tt> will be output; only emissions listed in <tt>HISTORY.rc</tt> will be included in diagnostics. All GCHPctm diagnostics listed in <tt>HISTORY.rc</tt> that start with <tt>Emis</tt>, <tt>Hco</tt>, or <tt>Inv</tt> must have a corresponding entry in <tt>HEMCO_Diagn.rc</tt>.
 |-valign="top"
 | <tt>input.nml</tt>
-| Contains the configurable domain stack size.
+| Namelist used in advection for domain stack size and stretched grid parameters.
+|-valign="top"
+| <tt>HISTORY.rc</tt>
+| Config file for the MAPL History component. Configures diagnostic output from GCHP.
 |}
 === CAP.rc ===
-<tt>CAP.rc</tt> is the configuration file for the top-level "Cap" (in ESMF/MAPL lingo) component. It handles general runtime settings for GCHP including time and data parameters, performance profiling routines, and system-wide timestep (hearbeat). Combined with file <tt>cap_restart</tt>, <tt>CAP.rc</tt> configures the exact dates for the next run of GCHP.
+<tt>CAP.rc</tt> is the configuration file for the top-level gridded component called <tt>CAP</tt>. 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 <tt>cap_restart</tt>, <tt>CAP.rc</tt> configures the exact dates for the next GCHP run.
 {| border=1 cellspacing=0 cellpadding=5
@@ Line 77: / Line 87: @@
 |-valign="top"
 |<tt>ROOT_NAME</tt>
-|Sets the child name (<tt>GCHP</tt>) that MAPL will use to initialize the ROOT component within CAP. It uses this name in all operations when querying and interacting with ROOT.
+|Sets the name MAPL uses to initialize the <tt>ROOT</tt> child gridded component component within CAP. CAP uses this name in all operations when querying and interacting with ROOT. It is set to <tt>GCHP</tt>.
 |-valign="top"
 |<tt>ROOT_CF</tt>
-|Resource configuration file for the ROOT component (<tt>GCHP.rc</tt>) which stores run information such as timesteps.
+|Resource configuration file for the ROOT component. It is set to <tt>GCHP.rc</tt>.
 |-valign="top"
 |<tt>HIST_CF</tt>
-|MAPL's HISTORY component resource configuration file (<tt>HISTORY.rc</tt>) which stores output configuration information such as variable names and grid.
+|Resource configuration file for the MAPL HISTORY gridded component (another child gridded component of CAP). It is set to <tt>HISTORY.rc</tt>.
 |-valign="top"
 |<tt>BEG_DATE</tt>
-|Begin date for the range of the experiment, in format <tt>YYYYMMDD hhmmss</tt>.<br>'''Set <tt>BEG_DATE</tt> to your simulation start date.'''
+|Simulation begin date in format <tt>YYYYMMDD hhmmss</tt>. This parameter is overrided in the presence of output file <tt>cap_restart</tt> containing a different start date.
 |-valign="top"
 |<tt>END_DATE</tt>
-|End date for the range of the experiment, in format <tt>YYYYMMDD hhmmss</tt>.<br>'''Ensure <tt>END_DATE</tt> is later than or equal to your simulation end date.'''
+|Simulation end date in format <tt>YYYYMMDD hhmmss</tt>. If <tt>BEG_DATE</tt> plus duration (<tt>JOB_SGMT</tt>) is before <tt>END_DATE</tt> then simulation will end at <tt>BEG_DATE + JOB_SGMT</tt>. If it is after then simulation will end at <tt>END_DATE</tt>.
 |-valign="top"
 |<tt>JOB_SGMT</tt>
-|Duration of each individual run, in format <tt>YYYYMMDD hhmmss</tt>. Should be shorter than or equal to the span of <tt>BEG_DATE</tt> and <tt>END_DATE</tt>. <br>'''Set <tt>JOB_SGMT</tt> to your simulation duration.'''
+|Simulation duration in format <tt>YYYYMMDD hhmmss</tt>. The duration must be less than or equal to the difference between start and end date or the model will crash.
-|-valign="top"
-|<tt>DEBUG_LEVEL</tt>
-|Similar to the [[The_HEMCO_User's_Guide#HEMCO_settings|HEMCO <tt>VERBOSE</tt> flag]], the debug flag enables debug output in GCHP. Values range from 0 (no debug output; default) to 20 (maximum amount of debug output).
-Setting this flag to 20 is especially helpful in identifying problems concerning reading input files in ExtData. <br>'''Set <tt>DEBUG_LEVEL</tt> to 20 if having problems reading input files with ExtData.'''
-|-valign="top"
-|<tt>TILEPATH</tt>
-|Path to tile files used in ExtData. Default is symbolic link <tt>TileFiles</tt> set when setting up your GCHP run directory.
 |-valign="top"
 |<tt>HEARTBEAT_DT</tt>
-|The 'ticking' rate of the ESMF/MAPL internal clock, in seconds. At every tick of the heartbeat, ESMF queries all components to see if anything needs to be calculated based upon the components' defined timesteps. Default is 1800.<br>'''Set <tt>HEARTBEAT_DT</tt> to the minimum timestep set in <tt>GCHP.rc</tt>.'''
+|The timestep of the ESMF/MAPL internal clock, in seconds. All other timesteps in GCHP must be a multiple of <tt>HEARTBEAT_DT</tt>. ESMF queries all components at each heartbeat to determine if computation is needed. The result is based upon individual component timesteps defined in <tt>GCHP.rc</tt>.
 |-valign="top"
 |<tt>MAPL_ENABLE_TIMERS</tt>
-|Enables output of MAPL's run-profile timers. Default is <tt>YES</tt>.
+|Toggles printed output of runtime MAPL timing profilers. This is set to <tt>YES</tt>. Timing profiles are output at the end of every GCHP run.
 |-valign="top"
 |<tt>MAPL_ENABLE_MEMUTILS</tt>
-|Enables runtime output of the programs' memory usage. Default is <tt>YES</tt>.
+|Enables runtime output of the programs' memory usage. This is set to <tt>YES</tt>.
 |-valign="top"
 |<tt>PRINTSPEC</tt>
-|If enabled, runs the model until all components are initialized. Then, dumps all the names of the members of the internal import/export states and ends the model. Setting options include: 0 (default): Off, 1: Import & Export, 2: Import, and 3: Export.
+|Allows an abbreviated model run limited to initializat and print of Import and Export state variable names. Options include: <tt>0</tt> (default): Off; <tt>1</tt>: Imports and Exports only; <tt>2</tt>: Imports only; and <tt>3</tt>: Exports only.
+|-valign="top"
+|<tt>USE_SHMEM</tt>
+| This setting is deprecated but still has an entry in the file.
+|-valign="top"
+|<tt>REVERSE_TIME</tt>
+|Enables running time backwards in CAP. Default is <tt>0</tt> (off).
 |}
 === ExtData.rc ===
-<tt>ExtData.rc</tt> contains emissions information for use with MAPL and ESMF. For more information see the [https://geos5.org/wiki/index.php?title=Using_the_ExtData_component ''ExtData component'' page on the GEOS-5 wiki].
+<tt>ExtData.rc</tt> 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 <tt>GEOS</tt> model, and GMAO/NASA documentation for it can be found at the [https://geos5.org/wiki/index.php?title=Using_the_ExtData_component ExtData component page on the GEOS-5 wiki].
-The information that <tt>ExtData.rc</tt> contains overlaps with GEOS-Chem configuration file [[The_HEMCO_User's_Guide|<tt>HEMCO_Config.rc</tt>]]. However, during a GCHP run, emissions files are found using the paths in <tt>ExtData.rc</tt> rather than in <tt>HEMCO_Config.rc</tt>; the file paths in <tt>HEMCO_Config.rc</tt> are ignored. Unlike the <tt>HEMCO_Config.rc</tt> file, the <tt>ExtData.rc</tt> file also includes GMAO Meteorological data.
+The following two parameters are set at the top of the file:
-Note that meteorology data paths in <tt>input.geos</tt> are ignored by GCHP and are superceded by paths in <tt>ExtData.rc</tt>.  See the [http://geos5.org/wiki/index.php?title=Using_the_ExtData_component GEOS-5 wiki] for detailed information about <tt>ExtData</tt> component. If you run into a problem with met fields when you later run GCHP, first check <tt>ExtData.rc</tt> to ensure you have the correct data paths.
+{| border=1 cellspacing=0 cellpadding=5
+|-bgcolor="#CCCCCC"
+!width="280px"|Parameter Name
+!width="720px"|Description
+|-valign="top"
+|<tt>Ext_AllowExtrat</tt>
+|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 <tt>HEMCO_Config.rc</tt>. That functionality of <tt>HEMCO_Config.rc</tt> is ignored in GCHP.
+|-valign="top"
+|<tt>DEBUG_LEVEL</tt>
+|Turns MAPL ExtData debug prints on/off. This is set to <tt>0</tt> in GCHP (off), but may be set to <tt>1</tt> 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.
+|}
-<tt>ExtData.rc</tt> includes the following information in a space-delimited single row for each primary export (e.g. met field), 2D variable at the edge (e.g. <tt>VEGFRAC_*</tt>), and emission field.
+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:
 {| border=1 cellspacing=0 cellpadding=5
 |-bgcolor="#CCCCCC"
-!width="280px"|Info Name
+!width="280px"|Name in Column Header
 !width="720px"|Description
@@ Line 148: / Line 171: @@
 |<tt>Units</tt>
 |Unit string nested within single quotes. <tt>'1'</tt> indicates there is no unit conversion from the native units in the netCDF file.
-|-valign="top"
-|<tt>Dimension</tt>
-|2D is <tt>xy</tt> and 3D is <tt>xyz</tt>.
-|-valign="top"
-|<tt>Vertical Location</tt>
-|Possible values include <tt>C</tt> for center, <tt>E</tt> for edge. If 2D enter <tt>C</tt> or <tt>E</tt> but this will obviously not be used.
 |-valign="top"
@@ Line 189: / Line 204: @@
 |}
 === GCHP.rc ===
-<tt>GCHP.rc</tt> is resource configuration file for the ROOT component within GCHP. It controls, at a minimum, global model resolution, grid type, parallel sub-domain size, component time steps, and job restart parameters.
+<tt>GCHP.rc</tt> is the resource configuration file for the ROOT component within GCHP. The ROOT gridded component includes three children gridded components, including one each for GEOS-Chem, FV3 advection, and the data utility environment needed to support them.
 {| border=1 cellspacing=0 cellpadding=5
@@ Line 201: / Line 217: @@
 |-valign="top"
 |<tt>NX, NY</tt>
-|Number of boxes in the two MPI sub-domain dimensions. <br>'''''<tt>NX * NY</tt> must equal your number of CPUs; <tt>NX</tt> or <tt>NY</tt> must be a multiple of 6 (the number of faces); typically <tt>NY</tt> is set as a multiple of 6.'''''
+|Number of grid cells in the two MPI sub-domain dimensions. NX * NY must equal the number of CPUs. NY must be a multiple of 6.
+|-valign="top"
+|<tt>GCHP.GRID_TYPE</tt>
+|Type of grid GCHP will be run at. Should always be <tt>Cubed-Sphere</tt>.
+|-valign="top"
+|<tt>GCHP.GRIDNAME</tt>
+|Descriptive grid label for the simulation. The default grid name is <tt>PE24x144-CF</tt>. The grid name includes how the pole is treated, the face side length, the face side length times six, and whether it is a Cubed Sphere Grid or Lat/Lon. The name <tt>PE24x144-CF</tt> indicates polar edge (PE), 24 cells along one face side, 144 for 24*6, and a cubed-sphere grid (CF). Many options here are defined in MAPL_Generic. <br>'''''Must be consistent with <tt>IM</tt> and <tt>JM</tt>.''''
+|-valign="top"
+|<tt>GCHP.NF</tt>
+|Number of cubed-sphere faces. This is set to 6.
+|-valign="top"
+|<tt>GCHP.IM_WORLD</tt>
+|Number of grid cells on the side of a single cubed sphere face.
+|-valign="top"
+|<tt>GCHP.IM</tt>
+|Number of grid cells on the side of a single cubed sphere face.
+|-valign="top"
+|<tt>GCHP.JM</tt>
+|Number of grid cells on one side of a cubed sphere face, times 6. This represents a second dimension if all six faces are stacked in a 2-dimensional array. Must be equal to IM*6.
+|-valign="top"
+|<tt>GCHP.LM</tt>
+|Number of vertical grid cells. This must be equal to the vertical resolution of the offline meteorological fields (72) since MAPL cannot regrid vertically.
+|-valign="top"
+|<tt>GCHP.STRETCH_FACTOR</tt>
+|Ratio of configured global resolution to resolution of targeted high resolution region if using stretched grid.
+|-valign="top"
+|<tt>GCHP.TARGET_LON</tt>
+|Target longitude for high resolution region if using stretched grid.
+|-valign="top"
+|<tt>GCHP.TARGET_LAT</tt>
+|Target latitude for high resolution region if using stretched grid.
 |-valign="top"
 |<tt>IM</tt>
-|Number of grid cells on the side of a single cubed sphere face. <br>'''''Get a rough idea of equivalent lat/lon resolution by dividing 90 by <tt>IM</tt>. Choose your timestep settings accordingly (see <tt>RUN_DT</tt> below).'''''
+|Same as <tt>GCHP.IM</tt> and <tt>GCHP.IM_WORLD</tt>.
 |-valign="top"
 |<tt>JM</tt>
-|Number of grid cells times 6, essentially defining the second dimension if all six faces are stacked in a 2-dimensional array. <br>'''''Must be to equal to <tt>IM*6</tt>.'''''
+|Same as <tt>GCHP.JM</tt>.
 |-valign="top"
 |<tt>LM</tt>
-|Number of vertical grid cells. The default value is 72. <br>'''''Must be equal to the vertical resolution of the offline meteorological fields since MAPL cannot regrid vertically'''''
+|Same as <tt>GCHP.LM</tt>.
-|-valign="top"
-|<tt>GRIDNAME</tt>
-|The default grid name is <tt>PE24x144-CF</tt>. The grid name includes how the pole is treated, the face side length, the face side length times six, and whether it is a Cubed Sphere Grid or Lat/Lon. The name <tt>PE24x144-CF</tt> indicates polar edge (PE), 24 cells along one face side, 144 for 24*6, and a cubed-sphere grid (CF). Many options here are defined in MAPL_Generic. <br>'''''Must be consistent with <tt>IM</tt> and <tt>JM</tt>.'''''
 |-valign="top"
 |<tt>GEOChem_CTM</tt>
-|A toggle that tells FVDycore that it is operating as a transport model rather than a prognostic model if set to 1.
+|If set to 1, tells FVdycore that it is operating as a transport model rather than a prognostic model.
 |-valign="top"
 |<tt>AdvCore_Advection</tt>
-|Default is 1.
+|Toggles offline advection. 0 is off, and 1 is on.
 |-valign="top"
@@ Line 233: / Line 285: @@
 |-valign="top"
 |<tt>HEARTBEAT_DT</tt>
-|The timestep in seconds that the DYCORE Component should be called. Default is 600.<br>'''Must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.'''
+|The timestep in seconds that the DYCORE Component should be called. This must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.
 |-valign="top"
 |<tt>SOLAR_DT</tt>
-|The timestep in seconds that the SOLAR Component should be called. Default is 600.<br>'''Must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.'''
+|The timestep in seconds that the SOLAR Component should be called. This must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.
 |-valign="top"
 |<tt>IRRAD_DT</tt>
-|The timestep in seconds that the IRRAD Component should be called.  ESMF checks this value during its timestep check. Default is 600.<br>'''Must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.'''
+|The timestep in seconds that the IRRAD Component should be called. ESMF checks this value during its timestep check. This must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.
 |-valign="top"
 |<tt>RUN_DT</tt>
-|The timestep in seconds that the RUN Component should be called.  ESMF checks this value during its timestep check. The recommended timestep [s] per grid resolution (see <tt>IM</tt>) are: 1800 (4x5); 900 (2x2.5); 600 (1x1.25); 600 (1/2 degree); 300 (1/4 degree).<br>'''Must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.'''
+|The timestep in seconds that the RUN Component should be called.
 |-valign="top"
-|<tt>GIGCchem_DT</tt>
+|<tt>GCHPchem_DT</tt>
-|The timestep in seconds that the GIGCchem Component should be called. ESMF checks this value during its timestep check. Default is 1200.<br>'''Must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.'''
+|The timestep in seconds that the GCHPchem Component should be called. This must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.
+|-valign="top"
+|<tt>RRTMG_DT</tt>
+|The timestep in seconds that RRTMG should be called. This must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.
 |-valign="top"
 |<tt>DYNAMICS_DT</tt>
-|The timestep in seconds that the DYNAMICS Component should be called.  ESMF checks this value during its timestep check. Default is 600.<br>'''Must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.'''
+|The timestep in seconds that the FV3 advection Component should be called. This must be a multiple of <tt>HEARTBEAT_DT</tt> in <tt>CAP.rc</tt>.
 |-valign="top"
@@ Line 260: / Line 316: @@
 |-valign="top"
-|<tt>GIGCchem_REFERENCE_TIME</tt>
+|<tt>GCHPchem_REFERENCE_TIME</tt>
-|
+|HHMMSS reference time used for GCHPchem MAPL alarms.
 |-valign="top"
 |<tt>PRINTRC</tt>
-|Specifies which resource values to print. Options include 0: Non-Default Values, and 1: All Values. Default setting is 0.
+|Specifies which resource values to print. Options include 0: non-default values, and 1: all values. Default setting is 0.
 |-valign="top"
@@ Line 280: / Line 336: @@
 |-valign="top"
-|<tt>GIGCchem_INTERNAL_RESTART_FILE</tt>
+|<tt>RECORD_FREQUENCY</tt>
+|Frequency of periodic restart file write in format HHMMSS.
+|-valign="top"
+|<tt>RECORD_REF_DATE</tt>
+|Reference date(s) used to determine when to write periodic restart files.
+|-valign="top"
+|<tt>RECORD_REF_TIME</tt>
+|Reference time(s) used to determine when to write periodic restart files.
+|-valign="top"
+|<tt>GCHOchem_INTERNAL_RESTART_FILE</tt>
 |The filename of the internal restart file to be written.
 |-valign="top"
-|<tt>GIGCchem_INTERNAL_RESTART_TYPE</tt>
+|<tt>GCHPchem_INTERNAL_RESTART_TYPE</tt>
-|The format of the internal restart file. Valid types include <tt>pbinary</tt> and <tt>pnc4</tt>.
+|The format of the internal restart file. Valid types include <tt>pbinary</tt> and <tt>pnc4</tt>. Only use <tt>pnc4</tt> with GCHP.
 |-valign="top"
-|<tt>GIGCchem_INTERNAL_CHECKPOINT_FILE</tt>
+|<tt>GCHPchem_INTERNAL_CHECKPOINT_FILE</tt>
 |The filename of the internal checkpoint file to be written.
 |-valign="top"
-|<tt>GIGCchem_INTERNAL_CHECKPOINT_TYPE</tt>
+|<tt>GCHPchem_INTERNAL_CHECKPOINT_TYPE</tt>
-|The format of the internal checkstart file. Valid types include <tt>pbinary</tt> and <tt>pnc4</tt>.
+|The format of the internal checkstart file. Valid types include <tt>pbinary</tt> and <tt>pnc4</tt>. Only use <tt>pnc4</tt> with GCHP.
 |-valign="top"
-|<tt>GIGCchem_INTERNAL_HEADER</tt>
+|<tt>GCHPchem_INTERNAL_HEADER</tt>
 |Only needed when the file type is set to <tt>pbinary</tt>. Specifies if a binary file is self-describing.
 |-valign="top"
 |<tt>DYN_INTERNAL_RESTART_FILE</tt>
-|The filename of the DYNAMICS internal restart file to be written.
+|The filename of the DYNAMICS internal restart file to be written. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file.
 |-valign="top"
 |<tt>DYN_INTERNAL_RESTART_TYPE</tt>
-|The format of the DYNAMICS internal restart file. Valid types include <tt>pbinary</tt> and <tt>pnc4</tt>.
+|The format of the DYNAMICS internal restart file. Valid types include <tt>pbinary</tt> and <tt>pnc4</tt>. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file.
 |-valign="top"
 |<tt>DYN_INTERNAL_CHECKPOINT_FILE</tt>
-|The filename of the DYNAMICS internal checkpoint file to be written.
+|The filename of the DYNAMICS internal checkpoint file to be written. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file.
 |-valign="top"
 |<tt>DYN_INTERNAL_CHECKPOINT_TYPE</tt>
-|The format of the DYNAMICS internal checkpoint file. Valid types include <tt>pbinary</tt> and <tt>pnc4</tt>.
+|The format of the DYNAMICS internal checkpoint file. Valid types include <tt>pbinary</tt> and <tt>pnc4</tt>. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file.
 |-valign="top"
@@ Line 320: / Line 388: @@
 |-valign="top"
-|<tt>MAX_DIAG, MAX_TRCS, MAX_MEMB, MAX_FAMS, MAX_DEP, LINOZ_NFIELDS, LINOZ_NLAT, LINOZ_NLEVELS, LINOZ_NMONTHS, RUN_PHASES</tt>
+|<tt>RUN_PHASES</tt>
-|For reading the <tt>input.geos</tt> file. Default value is 80.
+|GCHP uses only one run phase. The GCHP gridded component for chemistry, however, has the capability of two. The two-phase feature is used only in GEOS.
 |-valign="top"
 |<tt>HEMCO_CONFIG</tt>
-|Name of the HEMCO configuration file. Default is <tt>HEMCO_Config.rc</tt>.
+|Name of the HEMCO configuration file. Default is <tt>HEMCO_Config.rc</tt> in GCHP.
 |-valign="top"
 |<tt>STDOUT_LOGFILE</tt>
-|Log filename template. Default is <tt>PET%%%%%.GEOSCHEMchem.log</tt>.
+|Log filename template. Default is <tt>PET%%%%%.GEOSCHEMchem.log</tt>. This file is not actually used for primary standard output.
 |-valign="top"
 |<tt>STDOUT_LOGLUN</tt>
-|Logical unit number for stdout. Default value is 6.
+|Logical unit number for stdout. Default value is 700.
 |-valign="top"
-|<tt>INIT_ZERO</tt>
+|<tt>MEMORY_DEBUG_LEVEL</tt>
-|Default is 0.
+|Toggle for memory debugging. Default is 0 (off).
 |-valign="top"
-|<tt>INIT_GCC</tt>
+|<tt>WRITE_RESTART_BY_OSERVER</tt>
-|Default is 0.
+|Determines whether MAPL restart write should use o-server. This must be set to <tt>YES</tt> for high core count (>1000) runs to avoid hanging during file write. It is <tt>NO</tt> by default.
 |}
-=== HISTORY.rc ===
+=== input.geos ===
-All output from GCHP is in netCDF format, with the contents of each output file controlled by <tt>HISTORY.rc</tt>. Information in <tt>HISTORY.rc</tt> is organized as follows:
+Information about the <tt>input.geos</tt> file is the same as for GEOS-Chem Classic with a few exceptions. See the [[The_input.geos_file|input.geos file wiki page]] for an overview of the file.
+The <tt>input.geos</tt> file used in GCHP is different in the following ways:
+*Start/End datetimes are ignored. Set this information in <tt>CAP.rc</tt> instead.
+*Root data directory is ignored. All data paths are specified in <tt>ExtData.rc</tt> instead with the exception of the FAST-JX data directory which is still listed (and used) in <tt>input.geos</tt>.
+*Met field is ignored. Met field source is described in file paths in <tt>ExtData.rc</tt>.
+*GC classic timers setting is ineffectual. GEOS-Chem Classic timers code is not compiled when building GCHP.
+Other parts of the GEOS-Chem Classic <tt>input.geos</tt> file that are not relevant to GCHP are simply not included in the file that is copied to the GCHP run directory.
+=== HEMCO_Config.rc ===
+Like <tt>input.geos</tt>, information about the <tt>HEMCO_Config.rc</tt> file is the same as for GEOS-Chem Classic with a few exceptions. See the [[The_HEMCO_Config.rc_file
+|HEMCO_Config.rc file wiki page]] for an overview of the file.
+Some content of the <tt>HEMCO_Config.rc</tt> file is ignored by GCHP. This is because MAPL ExtData handles file input rather than HEMCO in GCHP.
+Items at the top of the file that are ignored include:
+*ROOT data directory path
+*METDIR path
+*DiagnPrefix
+*DiagnFreq
+*Wildcard
+In the BASE EMISSIONS section and beyond, columns that are ignored include:
+*sourceFile
+*sourceVar
+*sourceTime
+*C/R/E
+*SrcDim
+*SrcUnit
+All of the above information is specified in file <tt>ExtData.rc</tt> instead with the exception of diagnostic prefix and frequency. Diagnostic filename and frequency information is specified in <tt>HISTORY.rc</tt>.
+=== HEMCO_Diagn.rc ===
+Like in GEOS-Chem Classic, the <tt>HEMCO_Diagn.rc</tt> file is used to map between HEMCO containers and output file diagnostic names. However, while all uncommented diagnostics listed in <tt>HEMCO_Diagn.rc</tt> are output as HEMCO diagnostics in GEOS-Chem Classic, only the subset also listed in <tt>HISTORY.rc</tt> are output in GCHP. See the [[The_HEMCO_Diagn.rc_file|HEMCO_Diagn.rc file wiki page]] for an overview of the file.
+=== input.nml ===
+<tt>input.nml</tt> controls specific aspects of the FV3 dynamical core used for advection. Entries in <tt>input.nml</tt> are described below.
 {| border=1 cellspacing=0 cellpadding=5
@@ Line 355: / Line 466: @@
 |-valign="top"
-|<tt>EXPID</tt>
+|<tt>&fms_nml</tt>
-|The beginning of where output files can be stored. Includes directory structure (<tt>OutputDir</tt>) and beginning of filename (<tt>GCHP</tt>).
+|Header for the FMS namelist which includes all variables directly below the header.
 |-valign="top"
-|<tt>EXPDSC</tt>
+|<tt>print_memory_usage</tt>
-|The Export Description. If one does <tt>ncdump -h</tt>, the attribute "Title" will be the set value of <tt>EXPDSC</tt>.
+|Toggles memory usage prints to log. However, in practice turning it on or off does not have any effect.
 |-valign="top"
-|<tt>CoresPerNode</tt>
+|<tt>domain_stack_size</tt>
-|Number of CPUs per node for your simulation. Should match <tt>NX</tt> in [[#GCHP.rc|<tt>GCHP.rc</tt>]].
+|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.
 |-valign="top"
-|<tt>COLLECTIONS</tt>
+|<tt>&fv_core_nml</tt>
-|String names of all collections you wish to output (e.g. <tt>'center'</tt>, <tt>'regrid'</tt>). GCHP outputs data as collections and each collection is output as a single file. You can create as many different collections as you want. For each collection, the following fields may be specified. Note that in some instances default values are used if a setting is not explicitly defined.
+|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. <tt>#&fv#_core_nml</tt>.
 |-valign="top"
-|<tt>{COLLECTION}.template</tt>
+|<tt>do_schmidt</tt>
-|The output filename suffix. Including a date string, such as <tt>'%y4%m2%d2</tt>, will insert the simulation start day (following GrADS conventions). This should also include the file extension (e.g. <tt>.nc4</tt>)
+|Logical for whether to use Schmidt advection. Set to <tt>.true.</tt> if using stretched grid; otherwise this entry is commented out.
 |-valign="top"
-|<tt>{COLLECTION}.format</tt>
+|<tt>stretch_fac</tt>
-|Character string defining the file format. Options include <tt>CFIO</tt> (default) for netCDF-4 or <tt>flat</tt> for binary files.
+|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.
 |-valign="top"
-|<tt>{COLLECTION}.resolution</tt>
+|<tt>target_lat</tt>
-|Defines the output resolution, <tt>IX</tt> <tt>IY</tt> (in lat-lon). Output can be at a different resolution than the model run. Defaults to the same as the model. This means if the model is running at cubed sphere, it will by default output a cubed-sphere grid unless specified otherwise.
+|Target latitude of high resolution region if using stretched grid. This is commented out if not using stretched grid.
 |-valign="top"
-|<tt>{COLLECTION}.frequency</tt>
+|<tt>target_lon</tt>
-|The frequency at which values are archived for output in <tt>hhmmss</tt> format. For example, the default <tt>010000</tt> will output data every hour.
+|Target longitude of high resolution region if using stretched grid. This is commented out if not using stretched grid.
+|}
+=== HISTORY.rc ===
+The <tt>HISTORY.rc</tt> configuration file controls the diagnostic files output by GCHP. Information is organized into several sections:
+#Single parameters set at the top of the file
+#Grid label declaration list
+#Definition for each grid in grid label list
+#Variable collection declaration list
+#Definition for each collection in collection list.
+Single parameters set at the top of <tt>HISTORY.rc</tt> are as follows and apply to all collections:
+{| border=1 cellspacing=0 cellpadding=5
+|-bgcolor="#CCCCCC"
+!width="280px"|Parameter
+!width="720px"|Description
 |-valign="top"
-|<tt>{COLLECTION}.mode</tt>
+|<tt>EXPID</tt>
-|String defining archived values. Options are either <tt>instantaneous</tt> or <tt>time-averaged</tt> data. Default is <tt>instantaneous</tt>.
+|Filename prefix concatenated with each collection template string to define file path. It is set to <tt>OutputDir/GCHP</tt> so that all output diagnostic files are output to run subdirectory <tt>OutputDir</tt> and have filename begin with <tt>GCHP</tt>.
 |-valign="top"
-|<tt>{COLLECTION}.acc_interval</tt>
+|<tt>EXPDSC</tt>
-|Needed when mode is set to <tt>time-averaged</tt>. Defines the accumulation interval of the time average. Must be less than or equal to frequency.<br>'''NOTE: Does not appear in downloaded run directory <tt>HISTORY.rc</tt>.'''
+|Export description included as attribute "Title" in output files
 |-valign="top"
-|<tt>{COLLECTION}.subset</tt>
+|<tt>CoresPerNode</tt>
-|Used to declare only outputting a subset of data for output. Values include <tt>lonMin</tt>, <tt>lonMax</tt>, <tt>latMin</tt>, and <tt>latMax</tt>.<br>'''NOTE: Does not appear in downloaded run directory <tt>HISTORY.rc</tt>.'''
+|Number of CPUs per node for your simulation.
 |-valign="top"
-|<tt>{COLLECTION}.fields</tt>
+|<tt>VERSION</tt>
-|Paired character strings for diagnostic names and its associated gridded component to be written out.
+|Optional parameter included as attribute in output file.
 |}
-'''Important note about output resolution:''' The native resolution of GCHP output is on a cubed-sphere grid. Output in the native resolution will have dimensions [Nx6NxKxT] where N is a cubed sphere side length, K is the number of vertical layers, and T is the number of time samples in the file (i.e. duration divided by frequency).  Specifying a regular lat-lon resolution in <tt>HISTORY.rc</tt> (e.g. <tt>144 91</tt>) causes GCHP to attempt to regrid the output variables from cubed sphere resolution to lat-lon, assuming a uniform cell size throughout the domain. In this example, a regular 4x5 output will be created, although it will be different from the standard GEOS-Chem 4x5 output grid (e.g. no half-polar grid cells).
-'''Important note about vertical dimensions:''' The vertical axis in the unprocessed GCHP output files are flipped relative to GEOS-Chem Classic output file. Level index 1 corresponds to the top of the atmospheric while the end corresponds to the surface. Please keep this in mind when you perform post-processing and data visualization using GCHP output.
+The grid labels section of <tt>HISTORY.rc</tt> declares a list of descriptive grid strings followed by a definition for each declared grid label. Grids not in the grid label list may have definitions in the file; however, this will prevent them from being used in output collections. See the <tt>HISTORY.rc</tt> grid label section for syntax on declaring and defining grid labels.
-=== fvcore_layout.rc ===
+Keywords that may be used for grid label definitions are in the table below. Note that this list is not exhaustive; MAPL may have additional keywords that may be used that have not yet been explored for use with GCHP.
-Setting options in fvcore_layout.rc are listed below. Note that additional file <tt>input.nml</tt> (see next section) controls specific aspects of the FV3 dycore. If this file is not present, you may have memory errors.
 {| border=1 cellspacing=0 cellpadding=5
 |-bgcolor="#CCCCCC"
-!width="280px"|Parameter
+!width="280px"|Grid label keyword
 !width="720px"|Description
 |-valign="top"
-|<tt>npx</tt>
+|<tt>GRID_TYPE</tt>
-|Number of grid cells on cubed sphere face. The default setting is 24 (roughly 4x5 lat/lon equivalent).<br>'''''Must match <tt>IM</tt> in [[#GCHP.rc|<tt>GCHP.rc</tt>]].'''''
+|Type of grid. May be <tt>Cubed-Sphere</tt> or <tt>LatLon</tt>.
 |-valign="top"
-|<tt>npy</tt>
+|<tt>IM_WORLD</tt>
-|Number of grid cells on cubed sphere face. The default setting is 24 (roughly 4x5 lat/lon equivalent).<br>'''''Must match <tt>IM</tt> in [[#GCHP.rc|<tt>GCHP.rc</tt>]].'''''
+|Side length of one cubed-sphere face, e.g. 24 if grid resolution is C24, or number of longitudinal grid boxes if lat-lon.
 |-valign="top"
-|<tt>npz</tt>
+|<tt>JM_WORLD</tt>
-|Number of levels. The default setting is 72.<br>'''''Must match <tt>LM</tt> in [[#GCHP.rc|<tt>GCHP.rc</tt>]].'''''
+|Same as <tt>IM_WORLD</tt> but multiplied by 6 (number of faces), or number of latitudinal grid boxes if lat-lon.
 |-valign="top"
-|<tt>dt</tt>
+|<tt>POLE</tt>
-|Transport timestep in seconds. The default setting is 600 (10 minutes).<br>'''''Must match <tt>HEARTBEAT_DT</tt> in [[#CAP.rc|<tt>CAP.rc</tt>]] and <tt>RUN_DT</tt> in [[#GCHP.rc|<tt>GCHP.rc</tt>]].'''''
+|For lat-lon grids only. <tt>PC</tt> if latitudes are pole-centered and <tt>PE</tt> if latitudes are polar edge.
 |-valign="top"
-|<tt>n_sponge<br>ADIABATIC<br>hydrostatic<br>nord<br>d2_bg<br>d4_bg<br>dddmp<br>ksplit<br>nsplit<br>msplit<br>hord_mt<br>hord_vt<br>hord_vt<br>hord_dp<br>hord_tr<br>kord_tm<br>kord_mt<br>kord_wz<br>kord_tr<br>FV_OFF<br>fv_debug<br>inline_q<br>z_tracer<br>chk_mass</tt>
+|<tt>DATELINE</tt>
-|Additional settings. You will generally only use the default values provided.
+|For lat-lon grids only. <tt>DC</tt> if longitudes are dateline-centered and <tt>DE</tt> if longitudes are dateline-edge.
+|-valign="top"
+|<tt>LAT_RANGE</tt>
+|For lat-lon grids only. Regional grid latitudinal bounds.
+|-valign="top"
+|<tt>LON_RANGE</tt>
+|For lat-lon grids only. Regional grid longitudinal bounds.
+|-valign="top"
+|<tt>LM</tt>
+|Number of vertical levels.
 |}
-=== input.nml ===
-Setting options in <tt>input.nml</tt> are listed below. <tt>input.nml</tt> controls specific aspects of the FV3 dycore. If this file is not present, you may have memory errors.
+The collections section of <tt>HISTORY.rc</tt> declares a list of descriptive strings that define unique collections of output variables and settings. As with grid labels, it is followed by a definition for each declared collection. Collections not in the collection list, or present but commented out, may have definitions in the file; however, this will prevent them from being output. See the <tt>HISTORY.rc</tt> collection section for syntax on declaring and defining output collections.
+Keywords that may be used for collection definitions are in the table below. Note that this list is not exhaustive; MAPL may have additional keywords that may be used that have not yet been explored for use with GCHP.
 {| border=1 cellspacing=0 cellpadding=5
 |-bgcolor="#CCCCCC"
-!width="280px"|Parameter
+!width="280px"|Collection keyword
 !width="720px"|Description
 |-valign="top"
-|<tt>print_memory_usage</tt>
+|<tt>{COLLECTION}.template</tt>
-|Supposed to toggle memory usage prints to log. However, in practice turning it on or off does not seem to have any effect. Memory usage is always printed.
+|The output filename suffix that is appended to global parameter <tt>EXPID</tt> to define full output file path. Including a date string, such as <tt>'%y4%m2%d2</tt>, will insert the simulation start day following GrADS conventions. The default template for GCHP is set to <tt>%y4%m2%d2_%h2%n2z.nc4</tt>.
 |-valign="top"
-|<tt>domain_stack_size</tt>
+|<tt>{COLLECTION}.format</tt>
-|Domain stack size in bytes. We use a default of 7000000 but this may not be large enough if using very few cores with a high resolution run (e.g. 6 or 12 cores at c48). 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 <tt>input.nml</tt>.
+|Character string defining the file format. Options include <tt>CFIO</tt> (default) for netCDF-4 or <tt>flat</tt> for binary files. Always output as <tt>CFIO</tt> when using GCHP.
-|}
+|-valign="top"
+|<tt>{COLLECTION}.grid_label</tt>
+|Declared grid label for output grid. If excluded the collection will be output on the cubed-sphere grid at native resolution, e.g. C24 if you run GCHP with grid resolution C24.
-== Automatic Updating with RunConfig.sh ==
+|-valign="top"
+|<tt>{COLLECTION}.conservative</tt>
+|For lat-lon grids only. Set to 1 to conservatively regrid from cubed-sphere to lat-lon upon output. Exclude or set to 0 to use bilinear interpolation instead (not recommended).
-Sourcing <tt>runConfig.sh</tt> overwrites files in several files. But which exactly does it overwrite? This information is printed out by <tt>runConfig.sh</tt> when you source it. Here is sample output to illustrate what is happening. In each snapshot of output, the left-most variable defined in the far-right file will be updated with the value in the center.
+|-valign="top"
+|<tt>{COLLECTION}.frequency</tt>
+|The frequency at which output values are computed and archived, in format <tt>HHMMSS</tt>. For example, <tt>010000</tt> will calculate diagnostics every hour. The method of calculation is determined by the <tt>mode</tt> keyword. Unlike GEOS-Chem Classic, you cannot specify number of days, months, or years.
-[[File:gchp RunConfig1.png]]
+|-valign="top"
+|<tt>{COLLECTION}.duration</tt>
+|The frequency at which files are written, in format <tt>HHMMSS</tt>. For example, <tt>240000</tt> will output daily files. The number of times in the file are determined by the <tt>frequency</tt> keyword. Unlike GEOS-Chem Classic, you cannot specify number of days, months, or years.
-[[File:gchp RunConfig2.png]]
+|-valign="top"
+|<tt>{COLLECTION}.mode</tt>
+|Method of diagnostic calculation. Options are either <tt>instantaneous</tt> or <tt>time-averaged</tt>.
+|-valign="top"
+|<tt>{COLLECTION}.fields</tt>
+|List of character string pairs including diagnostic name and gridded component. All GCHP diagnostics belong to the <tt>GCHPchem</tt> gridded component.<br>Diagnostic names have prefixes that determine where MAPL History will look for them. Prefixes <tt>Emis</tt>, <tt>Inv</tt>, and <tt>Hco</tt> are HEMCO diagnostics and must have definitions in config file <tt>HEMCO_Diagn.rc</tt>. Prefixes <tt>Chem</tt> and <tt>Met</tt> are GEOS-Chem state  variables stored in objects <tt>State_Chm</tt> and <tt>State_Met</tt> respectively. Prefix <tt>SPC</tt> corresponds to internal state species, meaning the same arrays that are output to the restart file. Prefix <tt>GEOS</tt> is reserved for use in the <tt>GEOS</tt> model. All other diagnostic name prefixes are interpreted as variables stored in the GEOS-Chem <tt>State_Diag</tt> object.
+|}
-[[File:gchp RunConfig3.png]]
 --------------------------------------
-'''''[[Developing_GCHP|Previous]] | [[Getting_Started_With_GCHP|User Manual Home]] | [[GCHP_Main_Page|GCHP Main Page]]'''''
+'''''[[Developing_GCHP|Previous]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]'''''