Merge branch 'whannah/new-gen_domain-tool' (PR #6347)

Adds a new tool to replace gen_domain in CIME

"generate_domain_files_E3SM.py" is a new tool to replace the fortran
gen_domain.F90 tool that exists in CIME. The old version was problematic
to use because the build configuration was almost always broken when a
user went to build it. The new python version works efficiently due to
the numba package, which is included in the E3SM unified environment.

[BFB]

* whannah/new-gen_domain-tool:
  revert lfrac threshold and adjust default fminval
  add opts.lnd_mask_threshold for new gen domain tool
  remove "test" prefix for output domain files
  cosmetic fix
  misc bug fixes after PR changes
  switch bash to shell
  change yaml to yml
  typo fix in docs
  refactor domain generation tool
  remove un-used eps variable
  linter fixes
  update docs
  update docs
  add text to docs
  fix typo
  rename yaml file
  move domain tool and add documentation
  update tools/generate_domain_files_E3SM.py
  add new tool to replace gen_domain in cime

docs/index.md

@@ -1,12 +1,16 @@
 # The Energy Exascale Earth System Model (E3SM)
 
-The documentation for the components of E3SM is found here.
+The E3SM documentation is organized into sections for each component model and additional sections for shared tools and general guides.
 
-## Components
+## Component Models
 
 - [EAM](./EAM/index.md)
 - [EAMxx](./EAMxx/index.md)
 - [ELM](./ELM/index.md)
 - [MOSART](./MOSART/index.md)
 
-Please see [Developing Docs](https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/3924787306/Developing+Documentation) to learn about developing documentation for E3SM.
+## Tools
+
+- [generate_domain_files](./generate_domain_files/index.md)
+
+Please see [Developing Docs](https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/3924787306/Developing+Documentation) to learn about how to contribute to the documentation.

mkdocs.yaml

@@ -4,6 +4,7 @@ nav:
   - Introduction: 'index.md'
   - 'Developing Docs': 'https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/3924787306/Developing+Documentation'
   - Components: '*include ./components/*/mkdocs.yml'
+  - Tools:      '*include ./tools/*/mkdocs.yml'
 
 repo_name: E3SM-Project/E3SM
 repo_url: https://github.com/E3SM-Project/E3SM

tools/generate_domain_files/docs/index.md

@@ -0,0 +1,47 @@
+# Generating Domain Files
+
+Domain files are needed at runtime by the coupler, data models, and land model. The land model uses the mask to determine where to run and the coupler use the land fraction to merge fluxes from multiple surface types to the atmosphere above them.
+
+Domain files are created from a conservative, monotone mapping file from the ocean grid (where the mask is defined) to the atmosphere grid.
+
+## Environment
+
+The new domain generation tool requires a few special packages, such as xarray, numba, and itertools. These are all included in the E3SM unified environment:
+<https://e3sm.org/resources/tools/other-tools/e3sm-unified-environment/>
+
+Alternatively, a simple conda environment can be created with the following command:
+
+```shell
+conda create --name example_env --channel conda-forge xarray numpy numba scikit-learn netcdf4
+```
+
+## Map File Generation
+
+The map file used to generate the domain files can be created a few different ways. For a typical E3SM configuration we recommend using a conservative, monotone map. Here is an example command that can be used to generate one (as of NCO version 5.2.2)
+
+```shell
+ncremap -5 -a traave --src_grd=${OCN_GRID} --dst_grd=${ATM_GRID} --map_file=${MAP_FILE}
+```
+
+Note that existing ocean grid files can be found in the inputdata repository: `inputdata/ocn/mpas-o/<ocn_grid_name>/`
+
+The atmosphere grid file should be on the "pg2" grid. These grid files are easily generated with three TempestRemap commands as follows:
+
+```shell
+NE=30
+GenerateCSMesh --alt --res ${NE} --file ${GRID_FILE_PATH}/ne${NE}.g
+GenerateVolumetricMesh --in ${GRID_FILE_PATH}/ne${NE}.g --out ${GRID_FILE_PATH}/ne${NE}pg2.g --np 2 --uniform
+ConvertMeshToSCRIP --in ${GRID_FILE_PATH}/ne${NE}pg2.g --out ${GRID_FILE_PATH}/ne${NE}pg2_scrip.nc
+```
+
+For RRM grids the last two commands would be used on the exodus file produced by [SQuadGen](https://github.com/ClimateGlobalChange/squadgen) (See the [Adding Support for New Grids](https://docs.e3sm.org/user-guides/adding-grid-support-overview.md) tutorial for more information.).
+
+## Running the Domain Generation Tool
+
+Below is a typical example of how to invoke the domain generation tool from the command line:
+
+```shell
+NE=30
+MAP_FILE=${MAP_FILE_ROOT}/map_oEC60to30v3_to_ne${NE}pg2_traave.20240313.nc
+python generate_domain_files_E3SM.py -m ${MAP_FILE} -o oEC60to30v3 -l ne${NE}pg2 --date-stamp=9999 --output-root=${OUTPUT_ROOT}
+```