Update documentation for compass.landice.mesh

Add compass.landice.mesh to framework documentation, and update
some doc-strings.

compass/landice/mesh.py

@@ -130,8 +130,9 @@ def set_cell_width(self, section, thk, bed=None, vx=None, vy=None,
     :py:func:`mpas_tools.mesh.creation.build_mesh.build_planar_mesh()`.
     Requires the following options to be set in the given config section:
     ``min_spac``, ``max_spac``, ``high_log_speed``, ``low_log_speed``,
-    ``high_dist``, ``low_dist``,``cull_distance``, ``use_speed``,
-    ``use_dist_to_edge``, and ``use_dist_to_grounding_line``.
+    ``high_dist``, ``low_dist``, ``high_dist_bed``, ``low_dist_bed``,
+    ``high_bed``, ``low_bed``, ``cull_distance``, ``use_speed``,
+    ``use_dist_to_edge``, ``use_dist_to_grounding_line``, and ``use_bed``.
 
     Parameters
     ----------
@@ -517,6 +518,40 @@ def build_cell_width(self, section_name, gridded_dataset,
 def build_MALI_mesh(self, cell_width, x1, y1, geom_points,
                     geom_edges, mesh_name, section_name,
                     gridded_dataset, projection, geojson_file=None):
+    """
+    Create the MALI mesh based on final cell widths determined by
+    py:func:`compass.landice.mesh.build_cell_width()`, using Jigsaw and
+    MPAS-Tools functions. Culls the mesh based on config options, interpolates
+    all available fields from the gridded dataset to the MALI mesh using the
+    bilinear method, and marks domain boundaries as Dirichlet cells.
+
+    Parameters
+    ----------
+    cell_width : numpy.ndarray
+        Desired width of MPAS cells calculated by :py:func:`build_cell_width()`
+        based on mesh density functions define in :py_func:`set_cell_width()`
+        to pass to
+        :py:func:`mpas_tools.mesh.creation.build_mesh.build_planar_mesh()`.
+    x1 : float
+        x coordinates from gridded dataset
+    y1 : float
+        y coordinates from gridded dataset
+    geom_points : jigsawpy.jigsaw_msh_t.VERT2_t
+        xy node coordinates to pass to build_planar_mesh()
+    geom_edges : jigsawpy.jigsaw_msh_t.EDGE2_t
+        xy edge coordinates between nodes to pass to build_planar_mesh()
+    mesh_name : str
+        Filename to be used for final MALI .nc mesh file.
+    section_name : str
+        Name of config section containing mesh creation options.
+    gridded_dataset : str
+        Name of gridded dataset file to be used for interpolation to MALI mesh
+    projection : str
+        Projection to be used for setting lat-long fields.
+        Likely 'gis-gimp' or 'ais-bedmap2'
+    geojson_file : str
+        Name of geojson file that defines regional domain extent.
+    """
 
     logger = self.logger
     section = self.config[section_name]

compass/landice/tests/antarctica/mesh_gen/mesh_gen.cfg

@@ -28,10 +28,18 @@ low_log_speed = 0.75
 high_dist = 1.e5
 # distance to ice edge or grounding line within which cell spacing = min_spac (meters)
 low_dist = 1.e4
+
+# These will not be applied unless use_bed = True.
+# They are taken from the humboldt.mesh_gen test case
+# and have not been evaluated for Antarctica.
 # distance at which bed topography has no effect
 high_dist_bed = 1.e5
 # distance within which bed topography has maximum effect
 low_dist_bed = 7.5e4
+# Bed elev beneath which cell spacing is minimized
+low_bed = 50.0
+# Bed elev above which cell spacing is maximized
+high_bed = 100.0
 
 # mesh density functions
 use_speed = True

docs/developers_guide/landice/framework.rst

@@ -10,3 +10,96 @@ extrapolate
 The landice framework module ``compass/landice/extrapolate.py`` provides a
 function for extrapolating variables into undefined regions.  It is copied
 from a similar script in MPAS-Tools.
+
+mesh
+~~~
+
+The landice framework module :py:mod:`compass.landice.mesh` provides functions
+used by all ``mesh_gen`` tests cases, which currently exist within the
+``antarctica``, ``greenland``, ``humboldt``, ``kangerlussuaq``, ``koge_bugt_s``,
+and ``thwaites`` test groups. These functions include:
+
+py:func:`compass.landice.mesh.gridded_flood_fill()` applies a flood-fill algorithm
+to the gridded dataset in order to separate the ice sheet from peripheral ice.
+
+py:func:`compass.landice.mesh.set_rectangular_geom_points_and_edges()` sets node
+and edge coordinates to pass to py:func:`mpas_tools.mesh.creation.build_mesh.build_planar_mesh()`.
+
+py:func:`compass.landice.mesh.set_cell_width()` sets cell widths based on settings
+in config file to pass to :py:func:`mpas_tools.mesh.creation.build_mesh.build_planar_mesh()`.
+Requires the following options to be set in the given config section: ``min_spac``,
+``max_spac``, ``high_log_speed``, ``low_log_speed``, ``high_dist``, ``low_dist``,
+``high_dist_bed``, ``low_dist_bed``, ``high_bed``, ``low_bed``, ``cull_distance``,
+``use_speed``, ``use_dist_to_edge``, ``use_dist_to_grounding_line``, and ``use_bed``.
+
+py:func:`compass.landice.mesh.get_dist_to_edge_and_GL()` calculates distance from
+each point to ice edge and grounding line, to be used in mesh density functions in
+:py:func:`compass.landice.mesh.set_cell_width()`. In future development,
+this should be updated to use a faster package such as `scikit-fmm`.
+
+py:func:`compass.landice.mesh.build_cell_width()` determine final MPAS mesh cell sizes
+using desired cell widths calculated by py:func:`compass.landice.mesh.set_cell_width()`,
+based on user-defined density functions and config options.
+
+py:func:`compass.landice.mesh.build_MALI_mesh()` creates the MALI mesh based on final
+cell widths determined by py:func:`compass.landice.mesh.build_cell_width()`, using Jigsaw
+and MPAS-Tools functions. Culls the mesh based on config options, interpolates
+all available fields from the gridded dataset to the MALI mesh using the bilinear
+method, and marks domain boundaries as Dirichlet cells.
+
+py:func:`compass.landice.mesh.make_region_masks()` creates region masks using regions
+defined in Geometric Features repository. It is only used by the ``antarctica``
+and ``greenland`` test cases.
+
+The following config options should be define for all ``mesh_gen`` test cases (although
+not necessarily with the same values shown here, which are the defaults for the 1–10km
+Humboldt mesh):
+
+.. code-block:: cfg
+
+    # config options for humboldt test cases
+    [mesh]
+
+    # number of levels in the mesh
+    levels = 10
+
+    # Bounds of Humboldt domain
+    x_min = -630000.
+    x_max = 84000.
+    y_min = -1560000.
+    y_max = -860000.
+
+    # distance from ice margin to cull (km).
+    # Set to a value <= 0 if you do not want
+    # to cull based on distance from margin.
+    cull_distance = 5.0
+
+    # mesh density parameters
+    # minimum cell spacing (meters)
+    min_spac = 1.e3
+    # maximum cell spacing (meters)
+    max_spac = 1.e4
+    # log10 of max speed (m/yr) for cell spacing
+    high_log_speed = 2.5
+    # log10 of min speed (m/yr) for cell spacing
+    low_log_speed = 0.75
+    # distance at which cell spacing = max_spac (meters)
+    high_dist = 1.e5
+    # distance within which cell spacing = min_spac (meters)
+    low_dist = 1.e4
+
+    # These *_bed settings are only applied when use_bed = True.
+    # distance at which bed topography has no effect
+    high_dist_bed = 1.e5
+    # distance within which bed topography has maximum effect
+    low_dist_bed = 5.e4
+    # Bed elev beneath which cell spacing is minimized
+    low_bed = 50.0
+    # Bed elev above which cell spacing is maximized
+    high_bed = 100.0
+
+    # mesh density functions
+    use_speed = True
+    use_dist_to_grounding_line = False
+    use_dist_to_edge = True
+    use_bed = True

docs/users_guide/landice/framework.rst

@@ -0,0 +1,105 @@
+.. _dev_landice_framework:
+
+Land-ice Framework
+==================
+
+
+extrapolate
+~~~~~~~~~~~
+
+The landice framework module ``compass/landice/extrapolate.py`` provides a
+function for extrapolating variables into undefined regions.  It is copied
+from a similar script in MPAS-Tools.
+
+mesh
+~~~
+
+The landice framework module :py:mod:`compass.landice.mesh` provides functions
+used by all ``mesh_gen`` tests cases, which currently exist within the
+``antarctica``, ``greenland``, ``humboldt``, ``kangerlussuaq``, ``koge_bugt_s``,
+and ``thwaites`` test groups. These functions include:
+
+py:func:`compass.landice.mesh.gridded_flood_fill()` applies a flood-fill algorithm
+to the gridded dataset in order to separate the ice sheet from peripheral ice.
+
+py:func:`compass.landice.mesh.set_rectangular_geom_points_and_edges()` sets node
+and edge coordinates to pass to py:func:`mpas_tools.mesh.creation.build_mesh.build_planar_mesh()`.
+
+py:func:`compass.landice.mesh.set_cell_width()` sets cell widths based on settings
+in config file to pass to :py:func:`mpas_tools.mesh.creation.build_mesh.build_planar_mesh()`.
+Requires the following options to be set in the given config section: ``min_spac``,
+``max_spac``, ``high_log_speed``, ``low_log_speed``, ``high_dist``, ``low_dist``,
+``high_dist_bed``, ``low_dist_bed``, ``high_bed``, ``low_bed``, ``cull_distance``,
+``use_speed``, ``use_dist_to_edge``, ``use_dist_to_grounding_line``, and ``use_bed``.
+
+py:func:`compass.landice.mesh.get_dist_to_edge_and_GL()` calculates distance from
+each point to ice edge and grounding line, to be used in mesh density functions in
+:py:func:`compass.landice.mesh.set_cell_width()`. In future development,
+this should be updated to use a faster package such as `scikit-fmm`.
+
+py:func:`compass.landice.mesh.build_cell_width()` determine final MPAS mesh cell sizes
+using desired cell widths calculated by py:func:`compass.landice.mesh.set_cell_width()`,
+based on user-defined density functions and config options.
+
+py:func:`compass.landice.mesh.build_MALI_mesh()` creates the MALI mesh based on final
+cell widths determined by py:func:`compass.landice.mesh.build_cell_width()`, using Jigsaw
+and MPAS-Tools functions. Culls the mesh based on config options, interpolates
+all available fields from the gridded dataset to the MALI mesh using the bilinear
+method, and marks domain boundaries as Dirichlet cells.
+
+py:func:`compass.landice.mesh.make_region_masks()` creates region masks using regions
+defined in Geometric Features repository. It is only used by the ``antarctica``
+and ``greenland`` test cases.
+
+The following config options should be define for all ``mesh_gen`` test cases (although
+not necessarily with the same values shown here, which are the defaults for the 1–10km
+Humboldt mesh):
+
+.. code-block:: cfg
+
+    # config options for humboldt test cases
+    [mesh]
+
+    # number of levels in the mesh
+    levels = 10
+
+    # Bounds of Humboldt domain
+    x_min = -630000.
+    x_max = 84000.
+    y_min = -1560000.
+    y_max = -860000.
+
+    # distance from ice margin to cull (km).
+    # Set to a value <= 0 if you do not want
+    # to cull based on distance from margin.
+    cull_distance = 5.0
+
+    # mesh density parameters
+    # minimum cell spacing (meters)
+    min_spac = 1.e3
+    # maximum cell spacing (meters)
+    max_spac = 1.e4
+    # log10 of max speed (m/yr) for cell spacing
+    high_log_speed = 2.5
+    # log10 of min speed (m/yr) for cell spacing
+    low_log_speed = 0.75
+    # distance at which cell spacing = max_spac (meters)
+    high_dist = 1.e5
+    # distance within which cell spacing = min_spac (meters)
+    low_dist = 1.e4
+
+    # These *_bed settings are only applied when use_bed = True.
+    # distance at which bed topography has no effect
+    high_dist_bed = 1.e5
+    # distance within which bed topography has maximum effect
+    low_dist_bed = 5.e4
+    # Bed elev beneath which cell spacing is minimized
+    low_bed = 50.0
+    # Bed elev above which cell spacing is maximized
+    high_bed = 100.0
+
+    # mesh density functions
+    use_speed = True
+    use_dist_to_grounding_line = False
+    use_dist_to_edge = True
+    use_bed = True

docs/users_guide/landice/index.rst

@@ -30,4 +30,4 @@ Some helpful external links:
 
    test_groups/index
    suites
-   framework/index
+   framework