Add configurable feature-mask tasks for mesh and ocean components

[xylar]

Summary

This PR adds a shared framework for computing geometric-feature region and transect masks on MPAS meshes, plus configurable mesh and ocean tasks that expose the workflow through Polaris.

Detailed Description

The PR adds a reusable ComputeFeatureMasksStep that builds mask feature collections from geometric_features, validates feature object and mask types, computes MPAS region or transect masks with mpas_tools, and writes both mask NetCDF output and the source GeoJSON. The workflow supports configurable mesh inputs, mesh metadata, mask groups, mask types, multiprocessing settings, subdivision options, and transect edge signs.

The branch also registers configurable feature-mask tasks under both the mesh and ocean components. The ocean task subclasses the shared step so native MPAS-Ocean or Omega mesh files are opened through the ocean I/O layer before using the same mask-generation logic. nRegions and nTransects are added to the MPAS-Ocean-to-Omega dimension map so mask output can be written in native Omega names.

get_feature_mask_steps() is available for workflows that already have an upstream mesh-producing step; it takes the mesh step and filename explicitly rather than special-casing base or culled meshes.

The "MOC Basins" regions get special treatment. A southern-boundary transect is added for each region, and the combined file is given the mocBasinsAndTransects prefix that E3SM and MPAS-Analysis expect.

That MOC behavior lives in polaris/tasks/mesh/spherical/feature_masks/moc.py, not in the ocean step. Both pieces of it — the filename convention and appending the transects — are model-agnostic: they operate on standard MPAS meshes and masks, and neither needs a step instance. Keeping them in a leaf module means a step in another component can subclass the model-neutral ComputeFeatureMasksStep and reuse them without inheriting the Omega name translation, and so without having to supply an [ocean] config section. ComputeOceanFeatureMasksStep delegates to the same two functions, so the MOC logic exists in exactly one place. polaris/tasks/e3sm/init/component_inputs/ is the motivating caller: MPAS-Ocean reads the per-mesh MOC file at run time through its regionalMasksInput and transectMasksInput streams, so it is a component input rather than an analysis product.

Testing

Unit tests cover feature object-type detection, mask-type validation, shared-step configuration, configurable setup, output metadata and filenames, and a full step run against a small synthetic mesh.

The MOC helpers are tested directly, including that the module's own imports name neither polaris.ocean nor polaris.tasks.ocean, and that a step in another component can subclass the model-neutral step, use both helpers, and set up against a config with no [ocean] section. On the ocean side the tests cover the Omega name-translation boundary and the delegation to the shared helpers.

pytest tests/ passes in full (365 tests), and pre-commit run --all-files is clean.

Checklist

• User's Guide has been updated
• Developer's Guide has been updated
• API documentation in the Developer's Guide (api.md) has any new or modified class, method and/or functions listed
• Documentation has been built locally and changes look as expected
• Testing comment in the PR documents testing used to verify the changes

[xylar]

The idea is that this shared step will be used in later workflows to generate masks for use in online Omega analysis members (e.g. the MOC and regional stats) as well as offline analysis here in Polaris.

[xylar]

Testing

On Chrysalis, I set up:

polaris setup -n 184 --model omega -w $POLARIS_SCRATCH/feature-mask

Then, in the compute step directory, I symlinked an Omega initial condition file:

cd /lcrc/group/e3sm/ac.xylar/polaris_1.0/chrysalis/test_20260528/feature-mask/ocean/feature_masks/configurable/compute
ln -s /lcrc/group/e3sm/public_html/polaris/ocean/realistic_global/ocean.QU.240km.151209.omega.teos10eos.nc .

I edited the feature_masks.cfg with the mesh file and name:

# options for creating region or transect masks on an MPAS mesh
[feature_masks]

# Path to an existing standard MPAS mesh file for configurable use
# source: /gpfs/fs1/home/ac.xylar/e3sm_work/polaris/add-region-mask-framework/polaris/tasks/mesh/spherical/feature_masks/feature_masks.cfg
mesh_filename = ocean.QU.240km.151209.omega.teos10eos.nc

# Mesh name used in output filenames and metadata
# source: /gpfs/fs1/home/ac.xylar/e3sm_work/polaris/add-region-mask-framework/polaris/tasks/mesh/spherical/feature_masks/feature_masks.cfg
mesh_name = oQU240

When I ran the step, I got:

$ ncdump -h oQU240_oceanBasins20240830.nc 
netcdf oQU240_oceanBasins20240830 {
dimensions:
	nRegions = 10 ;
	StrLen = 64 ;
	nCells = 7153 ;
	nVertices = 15211 ;
variables:
	char constituents(nRegions, StrLen) ;
	int regionCellMasks(nCells, nRegions) ;
	char regionNames(nRegions, StrLen) ;
	int regionVertexMasks(nVertices, nRegions) ;
	char zmax(nRegions, StrLen) ;
	char zmin(nRegions, StrLen) ;

// global attributes:
		:mesh_name = "oQU240" ;
		:mask_group = "Ocean Basins" ;
		:feature_object_type = "region" ;
		:geometric_features_prefix = "oceanBasins" ;
		:geometric_features_date = "20240830" ;
		:source_mesh_filename = "ocean.QU.240km.151209.omega.teos10eos.nc" ;
		:history = "Thu May 28 14:18:26 2026: ncks -O -5 _tmp_oQU240_oceanBasins20240830.netcdf4.nc oQU240_oceanBasins20240830.nc\n",
			"Thu May 28 14:18:24 2026: /gpfs/fs1/home/ac.xylar/e3sm_work/polaris/add-region-mask-framework/pixi-env/.pixi/envs/default/bin/polaris serial" ;
		:NCO = "netCDF Operators version 5.3.9 (Homepage = http://nco.sf.net, Code = http://github.com/nco/nco, Citation = 10.1016/j.envsoft.2008.03.004)" ;
}

So far, no attempt to translate these variable names into an Omega-friendly format but the hooks are in place to do that later.

[xylar]

I'm not sure we actually want these. We may instead want dimensions that are specific to different region groups.