# Unified Mesh: Fixing Resolution Leakage into the Ocean/Sea-Ice Domain date: 2026/07/23 Contributors: - Xylar Asay-Davis - Claude ## Summary Unified meshes prescribe finer resolution for the land/river domain than for parts of the ocean/sea-ice domain (e.g. 10 km land vs 30 km ocean in `u.oi30.lr10`). The ocean and sea ice are CFL limited, so land/river resolution "leaking" into the culled ocean/sea-ice meshes causes forward-run instability: `u.oi30.lr10` was found to contain edges with `dcEdge` down to 9.16 km against a 30 km nominal ocean background, and the MPAS-Ocean `short` forward run produced NaNs precisely at the finest cells. This design adds two capabilities: 1. A **ratio-based `dcEdge` diagnostic** in the `e3sm/init` `topo/cull` mask step that fails loudly if the culled ocean/sea-ice domain contains edges whose `dcEdge` deviates too far from the local ocean background cell width, before any forward run is attempted. 2. An **effective ocean mask** for the unified sizing field that anticipates what the MPAS cull will keep, by emulating the cull on the lat/lon sizing grid at mesh scale, so the sizing field never prescribes land/river resolution in regions that end up in the ocean/sea-ice domain. Success means (a) all four unified meshes rebuild with no ocean/sea-ice edge below the diagnostic threshold, and (b) any future regression of this kind is caught at the cull-mask step rather than by a forward-run crash. ## Diagnosis Analysis of the `test_20260721` results on Chrysalis (all four unified meshes: `u.oi30.lr10`, `u.oi240.lr240`, `u.oi6to18.lr6to10`, `u.oi.so12to30.lr10`) established two mechanisms. Defining the *ratio* of an edge as `dcEdge` divided by the ocean background cell width at the edge location, clean jigsaw noise spans about [0.76, 1.39]; every mesh except the uniform-resolution `u.oi240.lr240` had edges with ratios of 0.29–0.34. ### Mechanism A (dominant): flood-fill connectivity is resolution dependent Coastal lagoons and shallow banks (Banc d'Arguin, Chukotka lagoons, Exmouth Gulf, the Vistula/Curonian Lagoons, Gulf of Sidra, ...) are below sea level but sit behind thin barriers (spits, tidal flats). At the 1/32-degree resolution of the shared coastline products, the barrier is *resolved*: the coastline flood fill classifies the whole lagoon as land, so the sizing field places it in the land-side coastline blend (10 -> 30 km for `u.oi30.lr10`). On the MPAS mesh, however, the same cells have `ocean_frac` of 0.5–1.0 (the conservative remap of the same source ocean mask is correct — most of their *area* is below sea level), the barrier occupies too little area of any mesh-scale cell to pull `ocean_frac` below 0.5, and a connected path of candidate-ocean cells reaches the lagoon, so the MPAS flood fill keeps it. No land cell is promoted to ocean anywhere in this mechanism: the two grids simply see different topology at different resolutions. The lagoon is culled on the fine lat/lon grid but retained on the coarse MPAS mesh because averaging erases the narrow land barrier. ### Mechanism B (secondary): critical passages preserved wider on MPAS Critical ocean passages (Fury & Hecla Strait, the Northwest Passage, Nares Strait, Akimiski Strait, Ilulissat, Carroll Inlet) are preserved on the MPAS mesh via transect cell masks plus `widen_transect_edge_masks` — a swath 1–3 cells wide — while the lat/lon rasterization of the same transects is a single grid cell (~0.125 degree) wide. Cells with `ocean_frac` as low as 0.10 are kept inside a region the sizing field classifies as land-side blend. ## Requirements ### Requirement: dcEdge ratio diagnostic in the cull-mask step Date last modified: 2026/07/23 Contributors: Xylar Asay-Davis, Claude For unified meshes, the `topo/cull` mask step of the `e3sm/init` component must fail with an informative error if the ocean/sea-ice domain implied by the ocean cull mask contains base-mesh edges whose `dcEdge` is below `min_dc_edge_ratio` times, or above `max_dc_edge_ratio` times, the local ocean background cell width. The thresholds must be config options so each unified mesh can override them. The check must be ratio based (not absolute) so it applies to variable-resolution meshes. The error must localize the violations (worst clusters in lat/lon) and a diagnostics file must be written to aid debugging. ### Requirement: sizing field consistent with the MPAS-mesh view of topography Date last modified: 2026/07/23 Contributors: Xylar Asay-Davis, Claude The unified sizing field must prescribe (approximately) the full ocean background cell width everywhere the MPAS cull will keep as ocean/sea-ice, while preserving land/river refinement elsewhere. Constraints agreed during design: - The cull masks themselves stay on the MPAS mesh; culling from a remapped lat/lon coastline is not an option because much of the cull logic is mesh dependent. - The shared coastline products (`prepare_coastline`) stay mesh independent and unchanged; all mesh-dependent adjustments happen per mesh in the sizing-field step. - Widening of critical passages for sizing must be proportional to the local ocean background resolution. - Exact prediction of the cull is impossible (the outcome near the `ocean_frac` = 0.5 threshold depends on the exact MPAS cell tiling), so the prediction must be deliberately generous toward ocean, with the diagnostic from the first requirement as the backstop. ## Algorithm Design ### Algorithm Design: dcEdge ratio diagnostic in the cull-mask step Date last modified: 2026/07/23 Contributors: Xylar Asay-Davis, Claude After the ocean cull mask is created, select base-mesh edges whose two adjacent cells are both kept (the interior edges of the future culled ocean mesh). Sample the ocean background cell width from the mesh's sizing-field product (nearest neighbor on the lat/lon sizing grid) at each edge location and form `ratio = dcEdge / background`. Fail if `min(ratio) < min_dc_edge_ratio` or `max(ratio) > max_dc_edge_ratio`. Threshold justification (from `test_20260721`): clean jigsaw noise spans [0.76, 1.39] x background; the contaminated meshes reached 0.29. The lower bound is the meaningful guard, since fine cells leaking into the ocean are a CFL hazard; `min_dc_edge_ratio = 0.65` leaves margin above the clean noise floor while failing the contaminated meshes decisively. The upper bound only flags anomalously coarse edges, which are a mild mesh-quality issue rather than a stability hazard. It must tolerate isolated jigsaw outliers whose magnitude grows with the number of edges: across the four regenerated meshes the maximum ratio rose monotonically with edge count (1.32 at 21k edges, 1.42 at 1.4M, 1.50 at 2.4M, 1.51 at 12M), so a tight ceiling is fragile. `max_dc_edge_ratio = 2.0` still catches an edge that is genuinely double the intended resolution while tolerating lone coarse jigsaw blips on large meshes. ### Algorithm Design: effective ocean mask via mesh-scale cull emulation Date last modified: 2026/07/23 Contributors: Xylar Asay-Davis, Claude Build a per-mesh *effective ocean mask* on the lat/lon sizing grid: 1. **Candidate fraction**: start from the combined-topography `ocean_mask` fraction (the same source field that becomes `ocean_frac` on the MPAS mesh) block-averaged from the finest (1/32-degree) grid to the mesh's sizing grid. 2. **Mesh-scale averaging**: box-average the fraction over the local ocean background cell width L(x) — emulating `ocean_frac` on mesh-scale cells — and threshold at 0.5. The local window is quantized into geometric bins; the longitude window grows as 1/cos(latitude). 3. **Critical transects**: remove rasterized land blockages; add ocean passages dilated to a swath of `passage_widen_factor` x L (a larger factor poleward of the sea-ice latitude threshold, mimicking `widen_transect_edge_masks`). 4. **Flood fill** from the standard ocean seed points (as the MPAS cull does), with periodic longitude connectivity. 5. **Hysteresis growth**: extend the flood-filled mask into connected regions whose fraction is at least `grow_threshold` (< 0.5). This covers cells whose fate at the strict threshold depends on the exact MPAS cell tiling, without promoting isolated inland regions. 6. **Union** with the shared flood-filled coastline `ocean_mask`. The union never demotes shared-mask ocean, so true coastlines are unaffected. Recompute the signed distance from the effective coastline (reusing the existing KD-tree machinery) and apply the existing land-side blend to the effective signed distance. The trade-off is asymmetric by construction: over-prediction (effective ocean that the actual cull removes) only coarsens land/river sizing toward the ocean background — no CFL hazard — while under-prediction is caught by the diagnostic. Prototype validation on all four meshes (see below) showed over-prediction of 2.4–3.7% of the ocean cell count with essentially no overlap with river channels. ### Prototype validation (2026/07/23) The algorithm was prototyped offline with `grow_threshold = 0.35` and passage widening of 1.5x / 3.0x L equatorward/poleward of 43 degrees, and validated against the actual cull masks of the `test_20260721` runs: | mesh | kept cells | under-pred (base -> emul) | over-pred (on river) | current min ratio | predicted min ratio | | --- | --- | --- | --- | --- | --- | | u.oi30.lr10 | 462,924 | 1,328 -> 335 | 16,943 (0) | 0.31 | 0.76 | | u.oi240.lr240 | 7,313 | 125 -> 1 | 185 (0) | 0.80 (clean) | 1.00 | | u.oi6to18.lr6to10 | 4,015,940 | 5,930 -> 1,168 | 30,287 (19) | 0.34 | 0.86 | | u.oi.so12to30.lr10 | 794,665 | 1,179 -> 181 | 18,927 (0) | 0.29 | 0.82 | "Predicted min ratio" is the minimum, over the current culled-mesh edges, of the sizing the effective coastline would prescribe relative to the ocean background; it exceeds the 0.65 diagnostic threshold on every mesh (no edge below threshold), with residual under-predicted cells all lying close enough to the effective coastline that the blend keeps them near the ocean background. ## Implementation ### Implementation: dcEdge ratio diagnostic in the cull-mask step Date last modified: 2026/07/23 Contributors: Xylar Asay-Davis, Claude - The ratio check is a testable public function in `polaris/tasks/e3sm/init/topo/cull/dc_edge_diagnostics.py`; it writes `ocean_dc_edge_diagnostics.nc` (per-edge ratio and violation masks), logs a summary with the worst violation clusters, and raises `ValueError` on failure. - `CullMaskStep` gains an optional `sizing_field_step`; when set (unified meshes), `sizing_field.nc` is linked as an input and the check runs at the end of `run()`, after all masks are written, using `oceanCullMask` (the ocean/sea-ice domain including cavities). - `get_cull_topo_steps()` passes the sizing-field build step (already constructed upstream for unified meshes) to `CullMaskStep`; for simple meshes the diagnostic is skipped. - `_get_cull_topo_config()` additionally merges the unified-mesh configs (`unified_mesh.cfg` and `{mesh_name}.cfg`) so per-mesh threshold overrides are honored; defaults live in `polaris/tasks/e3sm/init/topo/cull/cull.cfg` (`[cull_mesh]` `min_dc_edge_ratio`, `max_dc_edge_ratio`). ### Implementation: effective ocean mask via mesh-scale cull emulation Date last modified: 2026/07/23 Contributors: Xylar Asay-Davis, Claude - Reusable helpers in a dependency-light leaf module `polaris/mesh/spherical/unified/effective_ocean.py`: mesh-scale variable box averaging, passage widening, seeded flood fill, hysteresis growth, and effective-mask assembly. - `BuildSizingFieldStep` links the finest-resolution combined topography (for the candidate fraction) as an additional input, builds the effective ocean mask and effective signed distance, and passes them (instead of the shared coastline fields) to `sizing_field_dataset()`. New diagnostic variables are added to `sizing_field.nc`: the effective and emulated ocean masks, the widened passages and the effective signed distance. - New config options in `[sizing_field]`: `enable_cull_emulation` (default `true`), `cull_emulation_grow_threshold` (0.35), `passage_widen_factor` (1.5), `passage_widen_factor_high_lat` (3.0) and `passage_widen_latitude_threshold` (43 degrees). - The base meshes change as a result; downstream cached products (sizing field, base mesh and `e3sm/init` topography products) are regenerated, while shared coastline caches are unaffected. Development takes place on the `fix-uoi30lr10-cull` branch; see `PLAN_fix_unified_mesh_cull_leak.md` there for the commit series. ## Testing ### Testing and Validation: dcEdge ratio diagnostic in the cull-mask step Date last modified: 2026/07/23 Contributors: Xylar Asay-Davis, Claude Unit tests in `tests/e3sm/init/topo/test_cull_mask.py` exercise the pure ratio-check function with small synthetic meshes and sizing fields: a passing case, a min-ratio failure, a max-ratio failure, correct edge selection (only edges with both cells kept), and the contents of the diagnostics file. Integration-wise, re-running only the mask step against the existing `test_20260721` work directories must fail on the current contaminated masks and pass after the meshes are regenerated with the fix. ### Testing and Validation: effective ocean mask via mesh-scale cull emulation Date last modified: 2026/07/23 Contributors: Xylar Asay-Davis, Claude Unit tests for `effective_ocean.py` construct synthetic topographies where the expected behavior is known: a thin-barrier lagoon that must be included at a coarse mesh scale and excluded at a fine one; hysteresis growth that adds threshold-ambiguous fringes connected to the ocean but not isolated inland depressions; passage widening whose swath width scales with the local background. `test_sizing_field.py` is extended to verify the integration (effective fields present in the output, ocean-background sizing on emulated-ocean cells). Final validation is the regeneration of all four unified meshes with the Part 1 diagnostic active, which must pass, plus spot checks of the former hotspots.