Create docs, generalize cfg file values

compass/landice/tests/mesh_modifications/subdomain_extractor/subdomain_extractor.cfg

@@ -1,16 +1,16 @@
 [subdomain]
 
 # path to file from which to extract subdomain
-source_file = /global/cfs/cdirs/fanssie/MALI_projects/ISMIP6-2300/initial_conditions/AIS_4to20km_20230105/AIS_4to20km_r01_20220907_m5_drop_bed_20m_bulldoze_troughs_75_to_400m_Enderby_maxstiffness_0.8_TG_pinning_40maf_bedmap2_surface_ASE_05perc_seafloor_mu.nc
+source_file = TO BE SUPPLIED BY USER
 
 # path to region mask file for source_file
-region_mask_file = /global/cfs/cdirs/fanssie/MALI_projects/ISMIP6-2300/initial_conditions/AIS_4to20km_20230105/AIS_4to20km_r01_20220907.regionMask_ismip6.nc
+region_mask_file = TO BE SUPPLIED BY USER
 
 # region number to extract
-region_number = 3
+region_number = 1
 
 # filename for the subdomain to be generated
-dest_file_name = Amery.nc
+dest_file_name = subdomain.nc
 
 # mesh projection to be used for setting lat/lon values
 # Should match the projection used in the source_file
@@ -22,7 +22,7 @@ mesh_projection = ais-bedmap2
 # or if the ice-shelf is covered by two regions.
 # It is recommended to try extracting a subdomain with this False, and if the
 # ocean buffer is inadequate, trying again with this True.
-extend_ocean_buffer = True
+extend_ocean_buffer = False
 
 # number of iterations to grow open ocean buffer along ice-shelf margin
 # Only used if extend_ocean_buffer is True

docs/developers_guide/landice/api.rst

@@ -362,6 +362,20 @@ koge_bugt_s
    mesh.Mesh
    mesh.Mesh.run
 
+mesh_modifications
+~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: compass.landice.tests.mesh_modifications
+
+.. autosummary::
+   :toctree: generated/
+
+   MeshModifications
+
+   subdomain_extractor.SubdomainExtractor
+
+   subdomain_extractor.extract_region.ExtractRegion
+
 mismipplus
 ~~~~~~~~~~
 

docs/developers_guide/landice/test_groups/index.rst

@@ -21,5 +21,6 @@ Test groups
    ismip6_run
    kangerlussuaq
    koge_bugt_s
+   mesh_modifications
    mismipplus
    thwaites

docs/developers_guide/landice/test_groups/mesh_modifications.rst

@@ -0,0 +1,48 @@
+.. _mesh_modifications:
+
+mesh_modifications
+==================
+
+The ``mesh_modifications`` test group includes test cases for modifying
+existing meshes.
+(see :ref:`mesh_modifications`).
+
+It currently contains one test case for extracting a subdomain from an
+existing larger domain.
+
+framework
+---------
+
+There is no shared framework for this test group.
+
+subdomain_extractor
+-------------------
+
+The class :py:class:`compass.landice.tests.mesh_modifications.subdomain_extractor.SubdomainExtractor`
+extracts a subdomain from a larger domain.  It simply calls the class
+:py:class:`compass.landice.tests.mesh_modifications.subdomain_extractor.extract_region.ExtractRegion`.
+
+extract_region
+--------------
+
+The :py:class:`compass.landice.tests.mesh_modifications.subdomain_extractor.extract_region.ExtractRegion`
+class performs the operations to extract a region subdomain from a larger
+domain.  Using user-supplied config information, it performs the following
+steps:
+
+* create a cull mask
+
+* optionally extend culling mask a certain number of cells into the ocean
+  along the ice-shelf front
+
+* cull mesh, convert mesh, mark horns for culling, cull again
+
+* create a landice mesh from base MPAS mesh
+
+* set lat/lon fields in mesh based on specified projection
+
+* interpolate data fields from source mesh to subdomain mesh
+
+* mark domain boundary cells as Dirichlet velocity conditions
+
+* create a graph file for the subdomain mesh

docs/users_guide/landice/test_groups/index.rst

@@ -26,5 +26,6 @@ physics but that are not run routinely.
    ismip6_run
    kangerlussuaq
    koge_bugt_s
+   mesh_modifications
    mismipplus
    thwaites

docs/users_guide/landice/test_groups/mesh_modifications.rst

@@ -0,0 +1,63 @@
+.. _mesh_modifications:
+
+mesh_modifications
+==================
+
+The ``mesh_modifications`` test group includes test cases for modifying
+existing meshes.
+
+It currently contains one test case for extracting a subdomain from an
+existing larger domain.
+
+subdomain_extractor
+-------------------
+
+``landice/mesh_modifications/subdomain_extractor`` extracts a subdomain from a
+larger domain.  The extraction is defined by a specified region in a
+regionCellMask file.  In the future, this test could be extended to optionally
+use a GeoJSON file for defining the culling mask instead.
+The user should modify the default config for their application.
+
+In the future, the ability to apply the extractor to forcing files as well may
+be added.
+
+config options
+~~~~~~~~~~~~~~
+
+The ``subdomain_extractor`` test case uses the following default config
+options.  They should be adjusted by the user before setting up and running
+the test case.
+
+.. code-block:: cfg
+
+    [subdomain]
+
+    # path to file from which to extract subdomain
+    source_file = TO BE SUPPLIED BY USER
+
+    # path to region mask file for source_file
+    region_mask_file = TO BE SUPPLIED BY USER
+
+    # region number to extract
+    region_number = 1
+
+    # filename for the subdomain to be generated
+    dest_file_name = subdomain.nc
+
+    # mesh projection to be used for setting lat/lon values
+    # Should match the projection used in the source_file
+    # Likely one of 'ais-bedmap2' or 'gis-gimp'
+    mesh_projection = ais-bedmap2
+
+    # whether to extend mesh into the open ocean along the ice-shelf margin
+    # This is necessary if the region mask ends right along the ice-shelf edge,
+    # or if the ice-shelf is covered by two regions.
+    # It is recommended to try extracting a subdomain with this False, and if the
+    # ocean buffer is inadequate, trying again with this True.
+    extend_ocean_buffer = False
+
+    # number of iterations to grow open ocean buffer along ice-shelf margin
+    # Only used if extend_ocean_buffer is True
+    # Should be equal to approximately the number of ocean buffer cells in the
+    # source_file
+    grow_iters = 15