add docs

docs/developers_guide/landice/api.rst

@@ -419,7 +419,12 @@ Landice Framework
 
    iceshelf_melt.calc_mean_TF
 
+   mesh.add_bedmachine_thk_to_ais_gridded_data
+   mesh.clean_up_after_interp
    mesh.gridded_flood_fill
+   mesh.interp_ais_bedmachine
+   mesh.interp_ais_measures
+   mesh,preprocess_ais_data
    mesh.set_rectangular_geom_points_and_edges
    mesh.set_cell_width
    mesh.get_dist_to_edge_and_gl

docs/developers_guide/landice/framework.rst

@@ -34,9 +34,39 @@ 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.add_bedmachine_thk_to_ais_gridded_data()`
+copies BedMachine thickness to the AIS reference gridded dataset.
+It replaces thickness field in the compilation dataset with the one we
+will be using from BedMachine for actual thickness interpolation
+There are significant inconsistencies between the masking of the two,
+particularly along the Antarctic Peninsula, that lead to funky
+mesh extent and culling if we use the thickness from 8km composite
+dataset to define the cullMask but then actually interpolate thickness
+from BedMachine.
+This function uses bilinear interpolation to interpolate from the 500 m
+resolution of BedMachine to the 8 km resolution of the reference dataset.
+It is not particularly accurate, but is fast and adequate for generating
+the flood filled mask for culling the mesh.  Highly accurate conservative
+remapping is performed later for actually interpolating BedMachine
+thickness to the final MALI mesh.
+
+:py:func:`compass.landice.mesh.clean_up_after_interp()` performs some final
+clean up steps after interpolation for the AIS mesh case.
+
 :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.interp_ais_bedmachine()` interpolates BedMachine
+thickness and bedTopography dataset to a MALI mesh, accounting for masking of
+the ice extent to avoid interpolation ramps.
+
+:py:func:`compass.landice.mesh.interp_ais_interp_ais_measures()` interpolates
+MEASURES ice velocity dataset to a MALI mesh, accounting for masking at the ice
+edge and extrapolation.
+
+:py:func:`compass.landice.mesh.preprocess_ais_data()` performs adjustments to
+gridded AIS datasets needed for rest of compass workflow to utilize them.
+
 :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()`.
 

docs/developers_guide/landice/test_groups/antarctica.rst

@@ -4,7 +4,7 @@ antarctica
 ==========
 
 The ``antarctica`` test group (:py:class:`compass.landice.tests.antarctica.Antarctica`)
-creates a variable resolution 8-80 km mesh for the whole region of Antarctica.
+creates a variable resolution 4-20 km mesh for the whole region of Antarctica.
 (see :ref:`landice_antarctica`). Here, we describe framework for this test group.
 
 .. _dev_landice_antarctica_framework:
@@ -27,4 +27,26 @@ mesh_gen
 
 The :py:class:`compass.landice.tests.antarctica.mesh_gen.MeshGen`
 calls the :py:class:`compass.landice.tests.antarctica.mesh.Mesh` to create
-the 8-80 km variable resolution Antarctica mesh.
+the variable resolution Antarctica mesh.  It makes extensive use of
+functions in :py:class:`compass.landice.mesh`.
+
+The mesh generation is based around an 8 km reference dataset, which
+is updated in a number of ways directly from high resolution source
+data.  In the future, a complete workflow from source datasets may
+replace this hybrid method.
+
+First, ``add_bedmachine_thk_to_ais_gridded_data`` is used to update
+the thickness field in the reference dataset with that from BedMachine
+for the purposes of defining an ice-sheet extent and mesh resolution
+(not the actual thickness interpolation).
+
+Second, ``build_cell_width`` is called in the standard way to define the
+resolution density function.
+
+Third, ``preprocess_ais_data`` is called to perform a series of adjustments
+to the AIS datasets needed to work with the rest of the workflow.
+
+From here, dataset interpolation happens, starting with the standard
+interpolation script applied to the standard dataset, followed by bespoke
+interpolation of the high resolution BedMachine and MEASURES datasets.
+The step completes with some clean up and creation of a graph file.

docs/users_guide/landice/test_groups/antarctica.rst

@@ -20,40 +20,86 @@ the mesh generation options are adjusted through the config file.
 
 .. code-block:: cfg
 
-    [antarctica]
+    # config options for antarctica test cases
+    [mesh]
 
     # number of levels in the mesh
     levels = 5
 
+    # Bounds of Antarctic mesh
+    x_min = -3333500.
+    x_max = 3330500.
+    y_min = -3333500.
+    y_max = 3330500.
+
     # 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 = 70.0
+    cull_distance = 50.0
 
     # mesh density parameters
     # minimum cell spacing (meters)
-    min_spac = 8.e3
+    min_spac = 4.e3
     # maximum cell spacing (meters)
-    max_spac = 8.e4
+    max_spac = 2.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
+    low_log_speed = 0.5
+    # distance to ice edge or grounding line at which cell spacing = max_spac (meters)
+    high_dist = 2.e5
+    # distance to ice edge or grounding line within which cell spacing = min_spac (meters)
+    low_dist = 4.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
     use_dist_to_grounding_line = True
     use_dist_to_edge = False
+    use_bed = False
+
+    [antarctica]
+    # path to directory containing BedMachine and Measures datasets
+    data_path = /usr/projects/climate/trhille/data/AIS
+
+    # number of processors to use for ESMF_RegridWeightGen
+    nProcs = 128
 
 mesh_gen
 --------
 
-``landice/antarctica/mesh_gen`` creates a 8-80km variable resolution mesh with
+``landice/antarctica/mesh_gen`` creates a 4-20km variable resolution mesh with
 the mesh file name `Antarctica.nc`. In addition, two region masks are
 generated based on the IMBIE1 (http://imbie.org/imbie-2016/drainage-basins/)
 and ISMIP6 basins (defined in Jourdain et al. 2020).
+
+The test case performs interpolation of observational data from gridded datasets
+to the Antarctic mesh. This takes care of the peculiarities of the current gridded
+compilation dataset (antarctica_8km_2020_10_20.nc), as well as using conservative
+remapping directly from the high-resolution BedMachineAntarctica and MeASUReS
+velocity datasets. There is a fairly heavy degree of pre-processing done to get
+the BedMachine and MeASUReS datasets ready to be used here. The pre-processing
+includes renaming variables, setting reasonable _FillValue and missing_value
+attributes, extrapolating fields to avoid interpolation ramps at ice margins,
+updating mask values, and raising the bed topography at Lake Vostok to ensure
+a flat ice surface there.
+
+Those data files and processing scripts currently live here on Chicoma:
+``/usr/projects/climate/trhille/data``.
+Eventually that pre-processing could be integrated into a new step in COMPASS,
+or the processed data files could be added to the server on Anvil and downloaded
+as needed. However, until then, this test case provides a reproducible workflow
+for setting up Antarctic meshes at varying resolutions
+
 There is no model integration step.