Reduce number of empty cells in extended high-resolution Greenland Ice Sheet mesh

[trhille]

This merge includes changes needed for a new high-resolution (1–10 km) extended Greenland mesh with variable mesh resolution in the ocean and bare land. The goal is to have high enough resolution in the ocean to resolve fjords for coupling with the ocean, but to use lower resolution where possible to reduce wasted cells. The extended 1–10km without these changes contains 1.4 million cells, only ~350k of which contain ice. With these changes, the extended 1–10km mesh is 870k cells.

Checklist

• User's Guide has been updated
• Developer's Guide has been updated
• Documentation has been built locally and changes look as expected
• Document (in a comment titled Testing in this PR) any testing that was used to verify the changes

[trhille]

Testing

Using the .cfg file pasted below, I created a 1–10km mesh containing 870k cells instead of 1.4M. Only ~350k cells contain ice.

# config options for high_res_mesh test case
[mesh]

# number of levels in the mesh
levels = 10

# Bounds of GIS mesh. If any bound is set
# to None, the mesh will use the full extent
# of the gridded dataset.
x_min = None
x_max = None
y_min = None
y_max = None

# 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 = -100.0

# number of processors to use for ESMF_RegridWeightGen
nProcs = 2048

# mesh density parameters
# minimum cell spacing (meters)
min_spac = 1.e3
# maximum cell spacing (meters)
max_spac = 10.e3
# log10 of max speed for cell spacing
high_log_speed = 2.5
# log10 of min speed for cell spacing
low_log_speed = 0.75
# distance at which cell spacing = max_spac
high_dist = 1.e5
# distance within which cell spacing = min_spac
low_dist = 1.e4
# distance at which cell spacing in ocean = max_spac
high_dist_coast = 10.e3
# distance within which cell spaceing in ocean = min_spac
low_dist_coast = 2.e3
# 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 = False
use_dist_to_edge = True
use_dist_to_coast = True
use_bed = True

[greenland]
# path to directory containing BedMachine and Measures datasets
# (default value is for Perlmutter)
data_path = /global/cfs/cdirs/fanssie/standard_datasets/GIS_datasets/

# filename of the BedMachine thickness and bedTopography dataset
# (default value is for Perlmutter)
bedmachine_filename = BedMachineGreenland-v6_edits_floodFill_extrap.nc

# filename of the MEaSUREs ice velocity dataset
# (default value is for Perlmutter)
measures_filename = greenland_vel_mosaic500_extrap.nc

# projection of the source datasets, according to the dictionary keys
# create_scrip_file_from_planar_rectangular_grid from MPAS_Tools
src_proj = gis-gimp

# number of processors to use for ESMF_RegridWeightGen
nProcs = 2048

[trhille]

Testing after rebase. 1–10km GIS mesh looks qualitatively the same as before.

Masks appear to be correct:

This took 31 minutes on one Perlmutter compute node with interpolate_data = False.

[trhille]

All mesh_gen cases pass with these changes.

[trhille]

docs can be found here: https://portal.nersc.gov/cfs/fanssie/trhille/compass_docs_PR937/html/

[Copilot]

Pull request overview

This PR updates the Greenland high-resolution mesh-generation workflow to reduce “wasted” (empty) cells in an extended 1–10 km mesh by refining ocean resolution near the coast while allowing coarser resolution farther offshore and over bare land.

Changes:

• Add a new coast-based mesh-density control (use_dist_to_coast, high_dist_coast, low_dist_coast) and propagate it through cell-width generation.
• Update Greenland mesh-gen defaults (e.g., cull_distance, min/max spacing) and add an alternative mesh_gen_1to10km.cfg.
• Update Users/Developers documentation (including BedMachine v6 references and new config guidance).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
docs/users_guide/landice/test_groups/greenland.rst	Updates user-facing config snippet and documents the new 1–10 km alternative config and coast refinement option
docs/developers_guide/landice/test_groups/greenland.rst	Updates developer description to BedMachine v6 and mentions the alternative 1–10 km config
docs/developers_guide/landice/framework.rst	Documents new/conditional mesh-density options including use_dist_to_coast
compass/landice/tests/greenland/mesh_gen/mesh_gen_1to10km.cfg	Adds an alternative Greenland mesh-gen config targeting a finer 1–10 km mesh
compass/landice/tests/greenland/mesh_gen/mesh_gen.cfg	Updates Greenland mesh-gen defaults and adds coast-distance parameters
compass/landice/mesh.py	Implements coast-distance-based spacing and returns distance-to-coast from distance computation routine

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

set_cell_width() now computes land_mask/ocean_mask using comparisons on bed, but bed is still an optional argument (and may be None when use_bed = False). This will raise at runtime if bed is not provided. Consider either making bed required (and validating early with a clear error) or guarding these masks behind a bed is not None check.

Suggested change

	land_mask = np.logical_and(thk == 0.0, bed >= 0.)
	ocean_mask = np.logical_and(thk == 0.0, bed < 0.)
	# Cell spacing function based on union of masks
	if section.get('use_bed') == 'True':
	use_bed = section.get('use_bed') == 'True'
	if bed is None:
	if use_bed:
	raise ValueError(
	'bed must be provided when use_bed is True in '
	f'section "{section_name}".')
	land_mask = (thk == 0.0)
	ocean_mask = np.zeros_like(thk, dtype=bool)
	else:
	land_mask = np.logical_and(thk == 0.0, bed >= 0.)
	ocean_mask = np.logical_and(thk == 0.0, bed < 0.)
	# Cell spacing function based on union of masks
	if use_bed:

[Copilot]

The docstring lists high_log_speed/low_log_speed, high_dist/low_dist, high_dist_coast/low_dist_coast, and bed-related options as always required, but the implementation only reads these when the corresponding use_* flag is enabled. Please update the docstring to reflect which options are unconditional vs. conditional to avoid misleading config authors.

[trhille]

The docstring does not actually say these are required. I agree the phrasing there is a little vague, but the docstring points to documentation for more information, and I think that's the more appropriate place to add this explanation.

[Copilot]

Typo in the comment: "spaceing" → "spacing".

Suggested change

	# distance within which cell spaceing in ocean = min_spac
	# distance within which cell spacing in ocean = min_spac

[Copilot]

interpolate_data is not set in this config. In compass/landice/tests/greenland/mesh.py, the default fallback is False, so optional interpolation will be skipped even though dataset paths/filenames are provided below. Consider adding interpolate_data = True/False explicitly to make the intended behavior clear.

Suggested change

	# whether to interpolate the input datasets onto the mesh
	# set explicitly to preserve the current default behavior
	interpolate_data = False