From c077ca9e1a1e9cf2040593081e82b977d8e5c9cf Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Fri, 10 Apr 2026 17:03:18 +0200 Subject: [PATCH 01/11] Add a draft design for the unified base mesh This mesh is intended to work for the E3SM land, river, ocean and sea-ice components --- docs/design_docs/index.md | 1 + docs/design_docs/unified_base_mesh.md | 544 ++++++++++++++++++++++++++ 2 files changed, 545 insertions(+) create mode 100644 docs/design_docs/unified_base_mesh.md diff --git a/docs/design_docs/index.md b/docs/design_docs/index.md index 525594c31d..bbe87bb77a 100644 --- a/docs/design_docs/index.md +++ b/docs/design_docs/index.md @@ -6,6 +6,7 @@ :titlesonly: true shared_steps +unified_base_mesh vector_reconstruction template ``` diff --git a/docs/design_docs/unified_base_mesh.md b/docs/design_docs/unified_base_mesh.md new file mode 100644 index 0000000000..25125f00ef --- /dev/null +++ b/docs/design_docs/unified_base_mesh.md @@ -0,0 +1,544 @@ +# Unified Global Base Mesh Workflow + +date: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +## Summary + +This design proposes a Polaris workflow for creating a global, spherical MPAS +base mesh for the E3SM land, river, ocean and sea-ice models using JIGSAW. The +starting point is the work-in-progress `mpas_land_mesh` package, +which currently combines geospatial preprocessing, JSON-based configuration, +JIGSAW setup, mesh generation and ad hoc job creation in a single standalone +workflow. + +The Polaris implementation should preserve the relevant parts of that workflow +while translating them into shared steps, Polaris configuration files and +existing MPAS/JIGSAW infrastructure. In particular, the design should reuse +existing functionality in `polaris.mesh`, `mpas_tools` and the existing +`e3sm/init` topography remap and cull tasks wherever practical, rather than carrying +forward the standalone workflow's JSON configuration system or broad utility +modules. + +The initial focus is a feature-aware global base mesh whose resolution can be +informed by coastline and river-network data and whose output is directly +usable by downstream Polaris tasks such as `e3sm/init` topography remapping and mesh +culling. This design is intentionally a first draft because `mpas_land_mesh` +is still evolving. The document therefore emphasizes interfaces, workflow +decomposition and reuse strategy more than it fixes every implementation +detail. In particular, the exact component boundary between generic mesh work +and land/river-specific preprocessing remains an open design choice. + +This document should be treated as an umbrella design for the overall workflow. +As the work is refined, we expect to add more focused design documents for +stages such as `prepare_coastline`, `prepare_river_network`, +`build_sizing_field`, and possibly `unified_base_mesh` if that stage proves +complex enough to warrant its own design. These stage names are only working +names for now and should not be treated as final task, step, class or +component names. + +Success means that Polaris gains a documented path to build a global MPAS base +mesh with feature-aware resolution controls, using Polaris-native setup and run +machinery, and that the resulting mesh can be consumed by existing downstream +E3SM workflows without an extra conversion stage. + +## Requirements + +### Requirement: Global Spherical MPAS Base Mesh + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Polaris shall support creation of a global, spherical MPAS base mesh suitable +for the needs of the E3SM land, river, ocean and sea-ice models. + +The workflow shall support meshes whose resolution varies spatially in response +to model needs rather than being limited to quasi-uniform meshes. + +The primary output of the workflow shall be an MPAS mesh in standard MPAS form. + +### Requirement: Downstream E3SM Interoperability + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The generated base mesh shall be usable as input to downstream E3SM and +Polaris tools, including the existing topography remap and cull workflows. + +The workflow shall not require a separate ad hoc conversion step before the +mesh can be passed to those downstream tools. + +### Requirement: Feature-Aware Resolution Control + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The workflow shall support resolution control based on geospatial features that +are important for a unified land-river-ocean mesh. At a minimum, the first +implementation shall support coastline and river-network information. + +The design shall allow additional feature classes such as watershed +boundaries, lakes or dams to be added later without redesigning the full +workflow. + +### Requirement: Polaris-Native Configuration and Execution + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The workflow shall be expressed as Polaris steps and tasks and configured with +Polaris' ini-style configuration files. + +The workflow shall support standard Polaris setup, shared-step reuse, +provenance and machine execution patterns. + +### Requirement: Selective Migration and Maintainability + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The Polaris implementation shall prefer existing Polaris, `mpas_tools`, +JIGSAW and conda-forge capabilities wherever practical. + +Migration from `mpas_land_mesh` shall focus on the specific algorithms and +helpers needed for the Polaris workflow rather than wholesale reuse of general +utility modules or standalone workflow infrastructure. + +## Algorithm Design + +### Algorithm Design: Global Spherical MPAS Base Mesh + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The existing spherical JIGSAW workflow in `polaris.mesh` should be the starting +point for the new capability. The current `SphericalBaseStep` already handles +the parts of the workflow that are generic to MPAS spherical mesh generation: +writing the JIGSAW inputs, invoking JIGSAW, converting the JIGSAW triangles to +an MPAS mesh, updating MPAS fields such as `cellWidth`, and creating +`graph.info`. + +The unified base-mesh workflow should therefore focus on creating the +feature-aware mesh-spacing description rather than replacing the existing +JIGSAW-to-MPAS path. In the simplest formulation, the workflow builds a +global lon/lat-based sizing field and then reuses the existing spherical mesh +step to convert that sizing field into a JIGSAW mesh and finally into MPAS +form. + +This keeps the core mesh-generation algorithm close to existing Polaris +patterns and minimizes the amount of new meshing infrastructure that must be +maintained on the E3SM timeline. + +### Algorithm Design: Downstream E3SM Interoperability + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The output contract for the workflow should be aligned with what downstream +Polaris tasks already consume. The immediate target is the standard MPAS base +mesh plus associated graph file used by the existing E3SM topography remap and +cull tasks. + +Because the remap and cull tasks already operate on `base_mesh.nc`, the design +should treat that file as the primary authoritative output. Any additional +intermediate products needed for land or river workflows, such as cleaned +feature vectors or rasterized masks, should remain separate artifacts rather +than becoming a replacement mesh format. + +This requirement argues for producing a standard base mesh first and layering +additional land/river products around it, not embedding workflow-specific +assumptions into the base-mesh format. + +### Algorithm Design: Feature-Aware Resolution Control + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The feature-aware part of the workflow should be decomposed into two stages: +feature preprocessing and sizing-field construction. + +Feature preprocessing converts raw source datasets into cleaned global inputs +that are stable enough to drive mesh sizing. Based on the current +`mpas_land_mesh` workflow, the first supported sources should be: + +- a coastline mask derived first from the existing `e3sm/init/topo` + topography product and its land/ocean masking logic, so the unified mesh + uses the same coastline interpretation as downstream topography remap and + cull workflows. A Natural Earth-derived coastline should remain available as + a fallback if the topo-derived coastline proves unsuitable, and +- a simplified global river network derived from HydroRIVERS or an equivalent + source. + +Sizing-field construction then combines a baseline resolution with local +refinement targets derived from those preprocessed features. The precise blend +function can evolve, but the first implementation should be framed as a global +sizing field on a regular lon/lat grid because that matches the existing +Polaris spherical JIGSAW workflow. + +For coastline-driven refinement, a signed-distance formulation on the sphere +should be considered the preferred first approach. If a coastline curve or +region can be derived cleanly from the `e3sm/init/topo` land/ocean +interpretation, `mpas_tools.mesh.creation.signed_distance` or a closely +related method can be used to build smooth coastal transition zones and inland +or oceanward buffers directly from spherical geometry. This approach is +promising because it matches existing Polaris mesh patterns and may avoid some +of the raster-buffer and antimeridian-complexity present in the standalone +workflow. + +The design should assume that coastline and river controls are modular inputs +to the sizing-field builder. Additional controls for watersheds, lakes or dams +should enter through the same interface rather than through new one-off mesh +builders. + +### Algorithm Design: Polaris-Native Configuration and Execution + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The standalone workflow currently uses JSON templates, repeated key mutation +and explicit HPC-script generation. Polaris already has suitable +abstractions: config sections, shared steps, cached outputs, work-directory +layout and machine-aware job submission. + +The algorithmic structure of the new workflow should therefore be a dependency +graph of Polaris steps, not a mutable configuration file plus a generated +driver script. A natural decomposition is: + +1. preprocess coastline inputs; +2. preprocess river-network inputs; +3. assemble a unified sizing field; +4. generate the spherical JIGSAW mesh and convert it to MPAS form; and +5. optionally pass the base mesh into downstream remap and cull tasks. + +This step decomposition matches Polaris' execution model and supports reuse of +shared expensive products across multiple tasks. + +### Algorithm Design: Selective Migration and Maintainability + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The migration strategy should begin with an audit of `mpas_land_mesh` +capabilities grouped into three categories: + +- functionality already available in Polaris or `mpas_tools`, +- functionality available from direct use of conda-forge packages, and +- functionality that truly requires targeted extraction or reimplementation. + +The current standalone package includes broad helper modules such as +`utilities/vector.py`, JSON configuration managers and job-script generators. +Those are useful in the standalone context but should not be treated as the +default implementation strategy in Polaris. + +Instead, new shared helpers should be introduced only when a focused algorithm +cannot be expressed clearly with existing package APIs or current Polaris +utilities. This keeps the eventual Polaris implementation smaller, easier to +review and more adaptable as `mpas_land_mesh` continues to change. + +## Implementation + +### Implementation: Global Spherical MPAS Base Mesh + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The recommended implementation is a new feature-aware spherical base-mesh step +in `polaris.mesh` that builds on `SphericalBaseStep` rather than replacing it. +Two implementation paths both appear reasonable: + +- a subclass of `QuasiUniformSphericalMeshStep` that overrides construction of + the global `cellWidth` field, or +- a new sibling class whose responsibility is explicitly a feature-driven + spherical sizing field. + +In either case, the step should continue to rely on the existing +`SphericalBaseStep.run()` logic for JIGSAW invocation, conversion to MPAS form +and graph-file creation. + +The output naming should match existing Polaris conventions, with +`base_mesh.nc` as the primary mesh product and `graph.info` produced alongside +it. + +### Implementation: Downstream E3SM Interoperability + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The new unified base-mesh step should be shaped so it can be passed directly to +existing E3SM tasks that expect a `SphericalBaseStep`-like dependency. In +practice, this means keeping the same mesh and graph-file outputs and the same +basic interface expected by the current remap and cull tasks. + +The design should avoid introducing a special mesh post-processing task whose +only purpose is to translate the new workflow back into the format already +expected by `polaris.tasks.e3sm.init.topo.remap` and +`polaris.tasks.e3sm.init.topo.cull`. + +For validation and adoption, the first Polaris task that exercises the new +workflow should likely connect the generated base mesh to one or both of those +existing downstream tasks. + +### Implementation: Feature-Aware Resolution Control + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The likely first-pass step decomposition is: + +- `prepare_coastline`: derive a coastline representation suitable for mesh + refinement, using the `e3sm/init/topo` coastline as the first-choice source + and Natural Earth as a fallback; +- `prepare_river_network`: simplify and filter a global river dataset into a + refinement-ready product; +- `build_sizing_field`: combine baseline ocean and land resolution choices with + coastline and river refinement controls on a global lon/lat grid, ideally + using signed-distance fields where that simplifies the definition of + transition zones and buffers; and +- `unified_base_mesh`: consume the sizing field and create the MPAS base mesh. + +These names are intentionally provisional. They are useful labels for the +current design discussion but should not yet be interpreted as final public +interfaces or directory names in Polaris. + +As this workflow matures, more targeted design documents should be added for +the stage-level algorithms and interfaces, especially `prepare_coastline`, +`prepare_river_network`, and `build_sizing_field`. A separate design for +`unified_base_mesh` may or may not be needed depending on how much new logic +remains after reuse of the existing spherical JIGSAW infrastructure. + +The preprocessing steps should write clear intermediate products that are +useful for debugging and caching, such as cleaned GeoJSON or raster files. +However, those products should be internal workflow artifacts, not new required +external interfaces for downstream users. + +For coastline processing, the first implementation should attempt to derive the +coastline from the same topography inputs used in `e3sm/init/topo`, because +that gives the strongest consistency with downstream masking and culling. The +preferred next step would then be to construct a signed-distance field on the +sphere from that coastline and use it to define smooth resolution transitions, +including inland coastal buffers where the coastal or ocean resolution is +preserved for a configurable distance from shore. A fallback path based on +Natural Earth should be retained in case the topo-derived coastline is too +noisy, too expensive to generate, or otherwise unsuitable for driving mesh +refinement. + +The first implementation should target coastline and river inputs only. The +configuration and internal APIs should nonetheless leave room for later steps +that prepare watershed boundaries, lake boundaries or dam data if those prove +necessary. + +### Implementation: Polaris-Native Configuration and Execution + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The standalone JSON configuration files should be translated into Polaris +config sections, for example: + +- `[unified_mesh]` for overall workflow choices and supported feature toggles; +- `[coastline]` for coastline-source selection, fallback behavior and any + thresholds related to coastline cleaning or simplification, as well as + signed-distance transition and buffer parameters; +- `[river_network]` for river simplification and filtering controls; and +- `[spherical_mesh]` for the final JIGSAW and MPAS mesh settings already used + by Polaris. + +The workflow should rely on Polaris work directories and machine support rather +than carrying forward `jigsawcase`, `change_json_key_value()` or generated +standalone job scripts. + +Generic mesh-generation logic belongs naturally in the existing `mesh` +component. Dataset-specific preprocessing for river and coastline products may +fit better in a new component such as `land` or `river`. This first draft does +not force that final naming decision, but it recommends keeping the interface +between feature preprocessing and generic mesh creation clean enough that the +component split can be adjusted later with limited churn. + +### Implementation: Selective Migration and Maintainability + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The implementation effort should begin with a short function-by-function audit +of `mpas_land_mesh` to decide what should be: + +- reused from Polaris or `mpas_tools`, +- replaced with direct use of external packages, or +- extracted into small Polaris helpers. + +The following parts of `mpas_land_mesh` appear unlikely to be appropriate for +direct migration: + +- JSON configuration management in `utilities/config_manager.py`; +- standalone case and job infrastructure in `classes/jigsawcase.py`; and +- broad general-purpose utility layers such as + `mpas_land_mesh/utilities/vector.py`. + +Candidate targeted extractions may still be needed for items such as +geographic buffering, antimeridian-safe geometry handling or specific river +network simplification logic if those capabilities are not already available in +the chosen package stack. If helper code is brought over, it should remain +small, step-focused and colocated with the consuming workflow unless it quickly +proves reusable. + +## Testing + +### Testing and Validation: Global Spherical MPAS Base Mesh + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The workflow should include an integration test that creates a coarse unified +global mesh and verifies that `base_mesh.nc` and `graph.info` are produced. + +Validation should confirm that the resulting file is a valid MPAS mesh and that +the feature-aware step reuses the standard JIGSAW-to-MPAS conversion path. + +### Testing and Validation: Downstream E3SM Interoperability + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +At least one regression-style task should pass the generated base mesh into the +existing topography remap workflow, and ideally also the cull workflow, without +any manual conversion or edits in the work directory. + +Success for this requirement is not that the unified mesh produces final tuned +science results on the first attempt, but that the mesh product is accepted by +the existing downstream infrastructure as a standard MPAS base mesh. + +Because coastline consistency is a key motivation for the preferred source, +validation should also check that the coastline product used for refinement is +derived from the same topography interpretation used downstream when the +first-choice path is selected. + +### Testing and Validation: Feature-Aware Resolution Control + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Tests should verify that the sizing-field builder responds to coastline and +river inputs as configured and that it behaves sensibly across the +antimeridian. + +Where practical, unit or small-integration tests should be added for any new +geometry or raster helper functions that are extracted from the standalone +workflow, especially for antimeridian handling and feature buffering. + +Tests should also cover coastline-source selection, including the preferred +topography-derived coastline path and the Natural Earth fallback path. + +If a signed-distance coastline path is adopted, tests should verify that the +distance field and resulting coastal buffers behave as expected on both sides +of the coastline and across the antimeridian. + +### Testing and Validation: Polaris-Native Configuration and Execution + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The new workflow should be validated through standard Polaris setup and run +commands, showing that configuration is expressed entirely through Polaris +config files and that shared preprocessing steps can be reused by dependent +tasks. + +If the workflow is split across multiple components, tests should also verify +that the dependency chain remains clear to users through `polaris list +--verbose` and standard work-directory links. + +### Testing and Validation: Selective Migration and Maintainability + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Any helper code extracted from `mpas_land_mesh` should receive targeted tests +that protect the specific behavior Polaris depends on. + +The first implementation should also document which external conda-forge +packages were chosen in place of direct code migration so future contributors +can understand why a given helper was or was not carried over from the +standalone workflow. From f6c2dfb20649c5c524ec6819938582739d8d6fb3 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Fri, 10 Apr 2026 22:46:19 +0200 Subject: [PATCH 02/11] Add details on lat/lon resolutions (coarse, medium, fine) --- docs/design_docs/unified_base_mesh.md | 111 +++++++++++++++++++++++++- 1 file changed, 110 insertions(+), 1 deletion(-) diff --git a/docs/design_docs/unified_base_mesh.md b/docs/design_docs/unified_base_mesh.md index 25125f00ef..f24c16b565 100644 --- a/docs/design_docs/unified_base_mesh.md +++ b/docs/design_docs/unified_base_mesh.md @@ -41,6 +41,12 @@ complex enough to warrant its own design. These stage names are only working names for now and should not be treated as final task, step, class or component names. +The stage-level shared products should be built on a small set of supported +regular lon/lat target grids rather than on arbitrary default resolutions. A +short list of supported target-grid tiers is likely important for caching and +reuse of expensive shared steps such as coastline preparation, +river-network preparation, and topography remapping. + Success means that Polaris gains a documented path to build a global MPAS base mesh with feature-aware resolution controls, using Polaris-native setup and run machinery, and that the resulting mesh can be consumed by existing downstream @@ -97,6 +103,26 @@ The design shall allow additional feature classes such as watershed boundaries, lakes or dams to be added later without redesigning the full workflow. +### Requirement: Shared Target-Grid Tiers and Cacheable Preprocessing + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The shared preprocessing stages of the workflow shall operate on a small +discrete set of supported regular lon/lat target grids rather than on an +arbitrary default resolution. + +Within a given workflow instance, the same selected target-grid tier shall be +used consistently by `prepare_coastline`, `prepare_river_network`, and +`build_sizing_field`. + +The first design should favor a short supported list, likely two or three +tiers, so shared-step outputs can be cached and reused effectively. + ### Requirement: Polaris-Native Configuration and Execution Date last modified: 2026/04/10 @@ -226,6 +252,39 @@ to the sizing-field builder. Additional controls for watersheds, lakes or dams should enter through the same interface rather than through new one-off mesh builders. +### Algorithm Design: Shared Target-Grid Tiers and Cacheable Preprocessing + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The workflow should standardize on a small set of named target-grid tiers for +all shared preprocessing products. A reasonable first set is: + +- `coarse`: 1.0 degree; +- `medium`: 0.25 degree; and +- `fine`: 1/16 degree, or 0.0625 degree. + +These choices balance several competing needs. A 1-degree grid is inexpensive +and suitable for exploratory or coarse products. A 0.25-degree grid is already +useful for other E3SM preprocessing such as WOA 2023 extrapolation work. A +1/16-degree grid is fine enough to support mesh-resolution choices down to +roughly 5 km or so without making every workflow pay that cost by default. + +The selected target-grid tier should be a cross-cutting workflow choice. It +should control the resolution used for shared `e3sm/init/topo/combine` +lat/lon products, coastline preprocessing, river-network preprocessing, and +the final sizing field. This avoids mismatched products between stages and +makes cache reuse straightforward. + +The design should not prevent future support for custom target-grid +resolutions. However, arbitrary resolutions should not be the default +workflow path until there is a clear need, because they weaken cache reuse and +make the shared-step product space harder to manage. + ### Algorithm Design: Polaris-Native Configuration and Execution Date last modified: 2026/04/10 @@ -279,6 +338,12 @@ cannot be expressed clearly with existing package APIs or current Polaris utilities. This keeps the eventual Polaris implementation smaller, easier to review and more adaptable as `mpas_land_mesh` continues to change. +River-network simplification and river-driven meshing deserve special caution +in this migration strategy. Because that part of the workflow is the least +well-understood, the first Polaris design should preserve the corresponding +`mpas_land_mesh` algorithms more closely than the coastline path whenever +practical. + ## Implementation ### Implementation: Global Spherical MPAS Base Mesh @@ -383,6 +448,10 @@ configuration and internal APIs should nonetheless leave room for later steps that prepare watershed boundaries, lake boundaries or dam data if those prove necessary. +The selected target-grid tier should be treated as part of this interface. The +preprocessing and sizing-field steps should exchange products on one shared +grid, not on independently chosen grids. + ### Implementation: Polaris-Native Configuration and Execution Date last modified: 2026/04/10 @@ -395,11 +464,14 @@ Contributors: The standalone JSON configuration files should be translated into Polaris config sections, for example: -- `[unified_mesh]` for overall workflow choices and supported feature toggles; +- `[unified_mesh]` for overall workflow choices, target-grid-tier selection, + and supported feature toggles; - `[coastline]` for coastline-source selection, fallback behavior and any thresholds related to coastline cleaning or simplification, as well as signed-distance transition and buffer parameters; - `[river_network]` for river simplification and filtering controls; and +- `[sizing_field]` for background resolutions and feature-composition + parameters; and - `[spherical_mesh]` for the final JIGSAW and MPAS mesh settings already used by Polaris. @@ -414,6 +486,23 @@ not force that final naming decision, but it recommends keeping the interface between feature preprocessing and generic mesh creation clean enough that the component split can be adjusted later with limited churn. +### Implementation: Shared Target-Grid Tiers and Cacheable Preprocessing + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation should expose target-grid choice through a small +enumerated option such as `target_grid_tier = coarse`, `medium`, or `fine` +rather than by encouraging arbitrary floating-point defaults in every task. + +Each tier should map to a specific regular lon/lat resolution and should be +used consistently in work-directory layout, shared-step cache keys, and output +file naming so it is obvious which products can be reused together. + ### Implementation: Selective Migration and Maintainability Date last modified: 2026/04/10 @@ -445,6 +534,10 @@ the chosen package stack. If helper code is brought over, it should remain small, step-focused and colocated with the consuming workflow unless it quickly proves reusable. +For the river-network path in particular, targeted extraction or close +reimplementation is likely preferable to an early redesign of the underlying +algorithm. + ## Testing ### Testing and Validation: Global Spherical MPAS Base Mesh @@ -508,6 +601,22 @@ If a signed-distance coastline path is adopted, tests should verify that the distance field and resulting coastal buffers behave as expected on both sides of the coastline and across the antimeridian. +### Testing and Validation: Shared Target-Grid Tiers and Cacheable Preprocessing + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Tests should verify that the supported target-grid tiers produce the expected +lon/lat dimensions and that dependent shared steps reuse cached outputs when +the same tier is selected. + +They should also verify that switching tiers produces separate products rather +than silently reusing incompatible cached artifacts. + ### Testing and Validation: Polaris-Native Configuration and Execution Date last modified: 2026/04/10 From 65b3f776df007a75d07fe531a1c666c19570afbc Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Fri, 10 Apr 2026 23:24:13 +0200 Subject: [PATCH 03/11] Suggest organization of the shared steps Also, clarify a bit what the scope of build_sizing_field actually is. --- docs/design_docs/unified_base_mesh.md | 54 ++++++++++++++++++++++++--- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/docs/design_docs/unified_base_mesh.md b/docs/design_docs/unified_base_mesh.md index f24c16b565..7533a4570b 100644 --- a/docs/design_docs/unified_base_mesh.md +++ b/docs/design_docs/unified_base_mesh.md @@ -421,6 +421,16 @@ These names are intentionally provisional. They are useful labels for the current design discussion but should not yet be interpreted as final public interfaces or directory names in Polaris. +Even if the final implementation uses several shared steps, Polaris should +present them as one coherent workflow rather than as unrelated utilities. The +cleanest first implementation is to keep the shared steps together under the +`mesh` component in one common subtree such as +`mesh/spherical/unified/...`. That mirrors existing Polaris practice where a +shared base-mesh step lives in the `mesh` component and tasks provide a thin +wrapper around it. A separate `river` component would make more sense only if +Polaris later grows river-focused workflows that stand on their own apart from +base-mesh generation. + As this workflow matures, more targeted design documents should be added for the stage-level algorithms and interfaces, especially `prepare_coastline`, `prepare_river_network`, and `build_sizing_field`. A separate design for @@ -432,6 +442,28 @@ useful for debugging and caching, such as cleaned GeoJSON or raster files. However, those products should be internal workflow artifacts, not new required external interfaces for downstream users. +`build_sizing_field` needs a tighter contract than its working name suggests. +It should be defined as the step that takes: + +- the selected target-grid tier; +- the background land and ocean resolution choices for the mesh; +- the outputs of `prepare_coastline`, such as coastline geometry, masks or + signed-distance fields; +- the outputs of `prepare_river_network`, such as simplified flowlines, + drainage-area filters or rasterized distance products; and +- configuration controlling how these refinement signals are blended, + including minimum and maximum cell widths, transition distances and optional + feature toggles. + +Its output should be a single regular lon/lat `cellWidth` field in the format +already expected by the spherical JIGSAW workflow. Framing it this way makes +clear that `build_sizing_field` is not another ad hoc resolution option like +the current quasi-uniform mesh choices. Instead, it is the integration point +between shared feature preprocessing and the existing `SphericalBaseStep` +machinery. The downstream mesh-generation step should consume the resulting +`cellWidth` field without needing to know whether refinement came from +coastlines, rivers or later feature classes. + For coastline processing, the first implementation should attempt to derive the coastline from the same topography inputs used in `e3sm/init/topo`, because that gives the strongest consistency with downstream masking and culling. The @@ -479,12 +511,22 @@ The workflow should rely on Polaris work directories and machine support rather than carrying forward `jigsawcase`, `change_json_key_value()` or generated standalone job scripts. -Generic mesh-generation logic belongs naturally in the existing `mesh` -component. Dataset-specific preprocessing for river and coastline products may -fit better in a new component such as `land` or `river`. This first draft does -not force that final naming decision, but it recommends keeping the interface -between feature preprocessing and generic mesh creation clean enough that the -component split can be adjusted later with limited churn. +For the first implementation, the full shared-step chain should live in the +existing `mesh` component, because the workflow's primary public product is a +base mesh and because Polaris shared steps are organized most clearly when +their directories live at the highest common level where all consuming tasks +can find them. In practice, the task that exposes the workflow should be a +thin wrapper that links together shared steps such as `prepare_coastline`, +`prepare_river_network`, `build_sizing_field`, and the final +`unified_base_mesh` step, all under one mesh-oriented subtree. + +This recommendation does not rule out a later `river` or `land` component. +If Polaris eventually adds reusable river preprocessing, diagnostics or +standalone river-data products outside this mesh workflow, those could justify +a separate component. Even in that case, the interface should still make the +unified base-mesh workflow look like one pipeline, with `build_sizing_field` +remaining the explicit handoff from feature products to the generic spherical +mesh generator. ### Implementation: Shared Target-Grid Tiers and Cacheable Preprocessing From 175a6d25d83c990b451c3fe709ad50c4528cf383 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Fri, 10 Apr 2026 22:47:55 +0200 Subject: [PATCH 04/11] Add a draft design for prepare_coastline --- docs/design_docs/prepare_coastline.md | 370 ++++++++++++++++++++++++++ 1 file changed, 370 insertions(+) create mode 100644 docs/design_docs/prepare_coastline.md diff --git a/docs/design_docs/prepare_coastline.md b/docs/design_docs/prepare_coastline.md new file mode 100644 index 0000000000..126a567ce5 --- /dev/null +++ b/docs/design_docs/prepare_coastline.md @@ -0,0 +1,370 @@ +# Coastline Preparation for Unified Base Mesh Workflow + +date: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +## Summary + +This design proposes a shared `prepare_coastline` step and an associated task +that can run that shared step on its own for the unified global base-mesh +workflow. The purpose of the step is to create a single coastline +interpretation that downstream steps can reuse, especially +`prepare_river_network` and `build_sizing_field`. + +The preferred first source for coastline information is the combined +topography already used in `e3sm/init/topo`, because that gives the strongest +consistency with downstream topography remapping and culling. The resulting +coastline products should be defined on the same regular lon/lat grid that +`build_sizing_field` will consume. + +This document intentionally emphasizes requirements and algorithm design more +than implementation or testing. A key design choice is to keep the shared +coastline interface raster-first if possible. In particular, the public output +contract should prefer target-grid masks and coastal-distance fields over a +persisted polygonal coastline product. If temporary contour extraction is ever +needed internally, it should remain an implementation detail rather than the +main workflow artifact. + +Success means that Polaris gains a documented, reusable coastline-preparation +workflow whose outputs can be consumed directly by downstream steps and whose +standalone task makes it practical to inspect and iterate on coastline choices +without running the full unified mesh workflow. + +## Requirements + +### Requirement: Raster-First Coastline Products for Downstream Steps + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +`prepare_coastline` shall provide a shared coastline representation that can +be consumed directly by both `prepare_river_network` and +`build_sizing_field`. + +The shared product shall retain both land/ocean classification and coastal +proximity information over the global domain. + +The downstream steps shall not need to reinterpret raw coastline or raw +topography source datasets independently. + +### Requirement: Topography-Consistent and Explicit Coastline Definition + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The preferred coastline definition shall be consistent with the combined +topography interpretation already used by the existing `e3sm/init/topo` +workflow. + +The treatment of floating Antarctic ice shall be explicit and reproducible, +rather than being left implicit in overlapping land and ocean masks. + +If the topography-derived coastline proves unsuitable for some workflows, the +design shall allow an alternate source such as Natural Earth without changing +the downstream interface. + +### Requirement: Global Coastal Distance on the Sphere + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The coastline product shall support smooth coastal transition zones for mesh +sizing on the sphere, including across the antimeridian. + +The coastal-distance definition shall be suitable for the regular lon/lat grid +used by `build_sizing_field`. + +The first design shall avoid assuming that planar buffering or planar +Euclidean distance is adequate on a periodic global grid. + +### Requirement: Standalone Coastline Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Polaris shall provide a task that runs the shared `prepare_coastline` step and +the shared steps it depends on (e.g. `e3sm/init/topo/combine`). + +The standalone task shall make it practical to inspect coastline outputs and +compare coastline options without running the full unified mesh workflow. + +The same shared step and configuration shall be reusable from the full unified +workflow when settings match. + +## Algorithm Design + +### Algorithm Design: Raster-First Coastline Products for Downstream Steps + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The authoritative coastline products should be defined on the same regular +lon/lat grid that `build_sizing_field` will use. This implies that target-grid +selection should happen once in shared configuration, not independently inside +each downstream step. + +The preferred upstream source is the existing `e3sm/init/topo/combine` +workflow, because `CombineStep` already supports `target_grid = lat_lon`. +Rather than inventing a separate remap path, the coastline workflow should +reuse that capability to obtain combined topography on the target grid. + +The shared output contract should remain raster-first. The first design should +assume outputs such as: + +- combined topography on the target grid, either as a direct dependency or as + a shared input artifact, not necessarily a new coastline output; +- an exclusive land/ocean mask on that grid; +- a coastline-edge indicator on that grid or its cell edges; and +- a signed coastal-distance field on that grid. + +With this contract, `prepare_river_network` can use the mask or coastline-edge +information for outlet and coastline-consistency checks, while +`build_sizing_field` can consume the signed-distance field directly. + +This approach avoids making a polygonal coastline product part of the public +interface. If temporary contour extraction is ever needed for an internal +experiment, it should not become the required downstream artifact. + +### Algorithm Design: Topography-Consistent and Explicit Coastline Definition + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The preferred coastline definition should start from the combined topography +fields already used downstream, especially `base_elevation`, `ice_mask`, and +`grounded_mask`. + +Outside Antarctica, or more generally where floating ice is absent, the coast +can be interpreted as the zero contour of `base_elevation` after remapping to +the target lon/lat grid. + +Around Antarctica, the existing topography masking logic does not define a +single exclusive coastline by itself because floating ice contributes to the +land interpretation while the water below it may still contribute to the ocean +interpretation. The coastline workflow should therefore define an explicit +Antarctic convention instead of inheriting that ambiguity. + +The first design should allow at least two Antarctic conventions: + +- `calving_front`, where floating ice is treated as land for coastline + purposes, so the coastline follows the seaward edge of ice shelves; and +- `grounding_line`, where floating ice is treated as ocean for coastline + purposes, so the coastline follows the grounding line. + +If one default must be chosen early, `calving_front` appears to be the safer +first choice for a shared coastline product because it gives a single +land-ocean partition that is more naturally aligned with land and river outlet +logic. However, the standalone task should make it easy to compare that choice +with `grounding_line` before the full workflow commits to one default. + +If the topography-derived coastline proves too noisy, too expensive, or +otherwise unsuitable, a fallback source such as Natural Earth should be +rasterized onto the same target grid and normalized into the same output +contract. In this way, downstream steps can remain agnostic about the +coastline source. + +### Algorithm Design: Global Coastal Distance on the Sphere + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The preferred first algorithm is to compute coastal distance directly from the +exclusive raster mask on the periodic lon/lat grid, rather than requiring a +persisted vector geometry product. + +The basic formulation should be: + +1. Construct an exclusive land/ocean mask on the target grid using the chosen + coastline convention. +2. Identify coastline transitions wherever neighboring grid cells switch + between land and ocean, wrapping in longitude across the antimeridian. +3. Represent each coastline transition by one or more boundary samples located + on the corresponding grid-cell edges. +4. Convert the boundary samples and all target-grid points to Cartesian + coordinates on the sphere. +5. Use nearest-neighbor search in Cartesian space to estimate the unsigned + distance from each grid point to the nearest coastline sample. +6. Apply the sign from the exclusive land/ocean mask. + +This formulation has two advantages for the present design. First, it keeps +the public interface raster-based. Second, it turns antimeridian handling into +a periodic-neighbor problem on the target grid rather than a vector-topology +problem. + +The initial distance estimate can follow the same boundary-sample and KD-tree +style already used in `mpas_tools.mesh.creation.signed_distance`, but with the +boundary samples extracted from raster coastline transitions instead of from +vector geometry. If later testing shows that this approximation is too noisy +or too inaccurate, we can refine the boundary sampling or temporarily extract +contours internally without changing the external workflow contract. + +The sign convention should be recorded explicitly. For example, the workflow +can define negative distance over land and positive distance over ocean, or the +reverse, as long as `build_sizing_field` interprets it consistently. + +### Algorithm Design: Standalone Coastline Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The standalone task should be a thin wrapper around the shared +`prepare_coastline` step rather than a separate implementation path. + +The task will likely depend on a shared target-grid topography product, ideally +reused from the existing `combine_topo` capability on a lat/lon grid. From +there, the task can run the shared coastline step and any lightweight +diagnostic or visualization steps that prove useful. + +This standalone task is important for design iteration. It provides a place to +compare topography-derived and fallback coastlines, to compare Antarctic +conventions, and to inspect the target-grid mask and signed-distance products +without also running river preprocessing, sizing-field construction, or mesh +generation. + +Because the task wraps the shared step, the same outputs can later be reused +by the full unified workflow when configuration choices match. + +## Implementation + +### Implementation: Raster-First Coastline Products for Downstream Steps + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Detailed class layout, file naming, and output caching strategy should be +deferred until the requirements and algorithm design settle further. The first +implementation should favor a small raster-based output contract over a broad +set of derived artifacts. + +### Implementation: Topography-Consistent and Explicit Coastline Definition + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation should keep the Antarctic convention configurable and +record the chosen convention in output metadata. A fallback coastline source +should be normalized into the same raster-based interface as the preferred +topography-derived path. + +### Implementation: Global Coastal Distance on the Sphere + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation should prototype raster-boundary sampling and +spherical nearest-neighbor distance before introducing any custom vector +workflow or custom spherical distance library. + +### Implementation: Standalone Coastline Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation should add a lightweight task wrapper around the +shared step and should avoid a separate task-specific code path. + +## Testing + +### Testing and Validation: Raster-First Coastline Products for Downstream Steps + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Detailed validation criteria should be added once the implementation plan is +more concrete. The main early check will be that downstream steps can consume +the shared coastline outputs without reinterpreting source data. + +### Testing and Validation: Topography-Consistent and Explicit Coastline Definition + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Early validation should compare the preferred topography-derived coastline +against fallback products and should make Antarctic convention differences +explicit in diagnostics. + +### Testing and Validation: Global Coastal Distance on the Sphere + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Early validation should focus on antimeridian behavior, sign convention, and +whether the raster-based spherical distance is smooth enough to drive mesh +sizing. + +### Testing and Validation: Standalone Coastline Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The standalone task should eventually be validated as the primary place to +inspect and compare coastline choices before they are used in the full unified +workflow. From ede31c69e6472e1ed359f3f4f213088a9427ba81 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Fri, 10 Apr 2026 23:04:07 +0200 Subject: [PATCH 05/11] Add a design for the prepare_river_network step --- docs/design_docs/prepare_river_network.md | 357 ++++++++++++++++++++++ 1 file changed, 357 insertions(+) create mode 100644 docs/design_docs/prepare_river_network.md diff --git a/docs/design_docs/prepare_river_network.md b/docs/design_docs/prepare_river_network.md new file mode 100644 index 0000000000..e43456afa0 --- /dev/null +++ b/docs/design_docs/prepare_river_network.md @@ -0,0 +1,357 @@ +# River Network Preparation for Unified Base Mesh Workflow + +date: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +## Summary + +This design proposes a shared `prepare_river_network` step and an associated +task that can run that shared step on its own for the unified global +base-mesh workflow. The purpose of the step is to simplify a global river +dataset into products that can be consumed directly by `build_sizing_field` +without re-reading or reinterpreting the raw source data. + +The preferred first source is HydroRIVERS or an equivalent global flowline +dataset. Unlike the standalone `mpas_land_mesh` workflow, the Polaris design +should make the downstream interface explicit. In particular, the workflow +should distinguish between the authoritative simplified river network and the +target-grid products needed by `build_sizing_field`, rather than overloading a +single raster with mixed semantics. + +Because river-network simplification and river-driven meshing are the parts of +the workflow where Xylar's design intuition is currently weakest, the first Polaris +design should preserve the `mpas_land_mesh` river algorithms as closely as is +practical. + +This document intentionally emphasizes requirements and algorithm design more +than implementation or testing. It also assumes that `prepare_river_network` +will be aligned with the shared target-grid tier and coastline interpretation +chosen for the workflow, so that river outlets and coastal refinement can be +made consistent. + +Success means that Polaris gains a documented, reusable river-network +preprocessing workflow that preserves the major hydrographic controls relevant +for mesh generation and makes its outputs easy to inspect and easy for +downstream steps to consume. + +## Requirements + +### Requirement: Downstream-Ready River Network Products + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +`prepare_river_network` shall provide products that can be consumed directly by +`build_sizing_field`. + +The shared products shall retain the major river-network information needed for +mesh refinement, including channel locations and outlet locations. + +The downstream sizing-field step shall not need to rerun HydroRIVERS +filtering, network reconstruction, or outlet discovery. + +### Requirement: Hydrologically Meaningful Simplification + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation shall preserve the dominant global river outlets, +main stems, and major tributaries needed to inform mesh resolution. + +The design shall support filtering by drainage area and by proximity so the +retained network reflects the target mesh scale rather than the full source +dataset density. + +The simplification shall preserve connectivity and confluence structure rather +than reducing the product to disconnected local segments. + +Where practical, the first Polaris design shall preserve the existing +`mpas_land_mesh` river-network algorithms rather than redesigning them. + +### Requirement: Coastline-Consistent Outlets and Explicit Inland Sinks + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +River outlets that drain to the ocean shall be made consistent with the +coastline interpretation selected in `prepare_coastline`. + +Endorheic basins and other inland sinks shall remain explicit rather than +being folded into the ocean-outlet logic. + +The workflow shall not assume that raw river-source outlet locations are +already perfectly consistent with the preferred coastline source. + +### Requirement: Standalone River-Network Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Polaris shall provide a task that runs the shared `prepare_river_network` step +and the shared steps it depends on (e.g. `prepare_coastline`). + +The standalone task shall make it practical to inspect retained basins, +outlets, and target-grid river products without running the full unified mesh +workflow. + +The same shared step and configuration shall be reusable from the full unified +workflow when settings match. + +## Algorithm Design + +### Algorithm Design: Downstream-Ready River Network Products + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The step should consume a global river-flowline source together with the shared +coastline products and target-grid tier selected for the workflow. The output +contract should then separate authoritative hydrographic products from the +grid-specific products needed by `build_sizing_field`. + +The authoritative hydrographic product should be a simplified vector river +network with attributes such as drainage area, stream segment, stream order, +downstream segment, and outlet type. + +That simplified vector product should remain a first-class workflow artifact, +not just an intermediate used to create rasters. In particular, it is needed +both by `build_sizing_field` and by the final mesh step because the first +Polaris design intends to retain the current standalone use of river geometry +to influence cell placement. + +For direct use by `build_sizing_field`, the workflow should also produce +target-grid river products on the same regular lon/lat grid used by +`prepare_coastline` and `build_sizing_field`, most likely: + +- a river-channel mask; +- a river-outlet mask; +- outlet metadata or outlet points with drainage area and outlet type; and +- optionally other diagnostic rasters such as stream-order or basin IDs if + they prove useful. + +This is intentionally clearer than the current standalone workflow, which uses +one raster and a special outlet value. In Polaris, separate masks should be +preferred so the downstream contract is easy to interpret and extend. + +### Algorithm Design: Hydrologically Meaningful Simplification + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The current `mpas_land_mesh` workflow provides a useful starting point. It +uses HydroRIVERS attributes such as `HYRIV_ID`, `MAIN_RIV`, `ORD_STRA`, +`UPLAND_SKM`, `NEXT_DOWN`, and `ENDORHEIC` to identify outlets, build basin +topology, and simplify the network with proximity and drainage-area criteria. + +The first Polaris design should preserve that overall logic as directly as is +practical, while documenting it in a clearer staged form. For example: + +1. Filter source flowlines by a minimum drainage-area threshold tied to the + intended river-refinement scale. +2. Identify candidate outlets for both ocean-draining and endorheic basins. +3. Merge or suppress nearby candidate outlets based on a geodesic separation + tolerance, generally keeping the larger drainage area when two outlets are + too close. +4. For each retained outlet, reconstruct upstream topology and assign stream + segments and stream order. +5. Simplify upstream reaches recursively, preserving the main stem and major + tributaries while dropping small, redundant, or too-close reaches. + +The key point is that simplification should be basin-aware and topology-aware. +The Polaris design should preserve connectivity and confluences, not just apply +independent Douglas-Peucker style simplification to each source feature. + +The current standalone code uses `pyrivergraph`, R-trees, and drainage-area +ratios to decide when a nearby tributary should still be kept. Because this is +the least well-understood part of the workflow by Polaris developers, Polaris +should preferentially preserve these river-specific algorithms through targeted +extraction or close reimplementation, rather than treating them as the first +place to simplify the overall design. + +### Algorithm Design: Coastline-Consistent Outlets and Explicit Inland Sinks + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The simplified network should not be finalized independently of the coastline +step. Instead, the retained outlets should be checked against the land/ocean +mask and coastline-edge products from `prepare_coastline`. + +For basins that drain to the ocean, the outlet should be matched to a +compatible coastline location on the shared target grid. If the river source +and coastline source disagree slightly, the workflow should reconcile them +through a controlled snapping or matching procedure and record the resulting +outlet location and any applied displacement. + +Endorheic basins should bypass coastline matching and retain an explicit inland +sink classification. This distinction is important because downstream mesh +refinement may wish to treat inland sinks differently from ocean outlets. + +If an ocean-draining outlet cannot be matched to a compatible coastline +location within a configured tolerance, the workflow should flag that basin for +diagnostics rather than silently leaving the inconsistency unresolved. + +Once outlet reconciliation is complete, the simplified river network can be +rasterized onto the shared target grid. Rasterization should produce separate +channel and outlet masks rather than a single overloaded integer raster. + +### Algorithm Design: Standalone River-Network Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The standalone task should be a thin wrapper around the shared +`prepare_river_network` step rather than a separate implementation path. + +The task will depend on the selected coastline and target-grid products +because outlet reconciliation requires a coastline interpretation. Beyond that, +the standalone task should focus on diagnostics and iteration: comparing +drainage-area thresholds, outlet-separation tolerances, and the resulting +retained basins and outlet masks. + +Because the task wraps the shared step, the same simplified river products can +later be reused by `build_sizing_field` and the full unified workflow when +configuration choices match. + +## Implementation + +### Implementation: Downstream-Ready River Network Products + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Detailed file naming and class layout should be deferred until the interface is +settled further. The first implementation should prioritize a clean output +contract over carrying forward the standalone workflow's mixed raster +conventions. + +### Implementation: Hydrologically Meaningful Simplification + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation should preserve the basin-aware simplification logic +from `mpas_land_mesh` as directly as is practical while favoring smaller +focused helpers over broad utility-layer migration. + +### Implementation: Coastline-Consistent Outlets and Explicit Inland Sinks + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation should keep coastline matching and inland-sink +classification explicit in metadata and diagnostics so outlet treatment is easy +to audit. + +### Implementation: Standalone River-Network Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation should add a lightweight task wrapper around the +shared step and should avoid a separate task-specific code path. + +## Testing + +### Testing and Validation: Downstream-Ready River Network Products + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Detailed validation criteria should be added once the implementation plan is +more concrete. The main early check will be that `build_sizing_field` can +consume the shared river products without rerunning source-data processing. + +### Testing and Validation: Hydrologically Meaningful Simplification + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Early validation should focus on whether major outlets, main stems, and major +tributaries are retained in a way that scales sensibly with the chosen +thresholds. + +### Testing and Validation: Coastline-Consistent Outlets and Explicit Inland Sinks + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Early validation should make outlet matching diagnostics explicit and should +show that endorheic basins remain distinct from ocean outlets. + +### Testing and Validation: Standalone River-Network Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The standalone task should eventually be validated as the primary place to +inspect river simplification choices before those products are used in the full +unified workflow. From 0b6993a3449ee6f71d9d31b76bc6c12f40ffe85b Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Fri, 10 Apr 2026 23:11:47 +0200 Subject: [PATCH 06/11] Add draft design doc for build_sizing_field --- docs/design_docs/build_sizing_field.md | 400 +++++++++++++++++++++++++ docs/design_docs/index.md | 3 + 2 files changed, 403 insertions(+) create mode 100644 docs/design_docs/build_sizing_field.md diff --git a/docs/design_docs/build_sizing_field.md b/docs/design_docs/build_sizing_field.md new file mode 100644 index 0000000000..ebd66352a0 --- /dev/null +++ b/docs/design_docs/build_sizing_field.md @@ -0,0 +1,400 @@ +# Sizing-Field Construction for Unified Base Mesh Workflow + +date: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +## Summary + +This design proposes a shared `build_sizing_field` step and an associated task +that can run that shared step on its own for the unified global base-mesh +workflow. The purpose of the step is to combine baseline mesh-resolution +choices with coastline and river controls into a single global lon/lat sizing +field that can be passed directly to the final spherical JIGSAW mesh step. + +The design assumes that `prepare_coastline` and `prepare_river_network` have +already converted raw source datasets into shared products with explicit +interfaces. `build_sizing_field` should consume those products directly rather +than mixing raw-data interpretation, feature preprocessing, and mesh-sizing +logic in one place. + +This document intentionally emphasizes requirements and algorithm design more +than implementation or testing. A key design choice is that feature refinement +should be expressed as clearly as practical in the sizing field itself. For +coastline refinement, this points strongly toward explicit raster candidate +fields. For rivers, the first Polaris design should use the combination of +raster products and direct use of river geometry to guide mesh cell placement +to preserve the meshing behavior in the standalone reference implementation in +`mpas_land_mesh`. + +Success means that Polaris gains a documented, reusable sizing-field workflow +whose inputs from earlier steps are clear, whose outputs are directly usable by +the final mesh step, and whose diagnostics make it easy to see why a given +region is refined. + +## Requirements + +### Requirement: JIGSAW-Ready Global Sizing Field + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +`build_sizing_field` shall produce a global sizing field on a regular lon/lat +grid that can be consumed directly by the final spherical mesh-generation +step. + +The sizing field shall encode the raster part of the requested spatial +variation in target mesh resolution and shall interoperate cleanly with any +retained feature geometry that the final mesh step uses directly. + +### Requirement: Explicit Consumption of Shared Coastline and River Products + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +`build_sizing_field` shall consume the outputs of `prepare_coastline` and +`prepare_river_network` through explicit interfaces. + +The sizing-field step shall not need to re-read raw coastline, raw topography, +or raw HydroRIVERS source datasets in the standard workflow. + +### Requirement: Composable Feature-Based Resolution Controls + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The workflow shall support a baseline resolution pattern together with local +refinement controls for coastline and river features. + +The first design shall support separate control of at least: + +- background ocean resolution; +- background land resolution; +- coastline refinement and transition zones; and +- river-channel and river-outlet refinement. + +The design shall allow additional feature classes such as watershed +boundaries, lakes, or dams to be added later without redesigning the full +sizing-field logic. + +### Requirement: Compatibility with Shared Target-Grid Tiers + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The sizing field shall be defined on the same supported target-grid tier used +by the upstream shared preprocessing steps. + +The first design shall work with a small discrete set of supported target-grid +resolutions rather than assuming arbitrary default resolutions. + +### Requirement: Standalone Sizing-Field Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Polaris shall provide a task that runs the shared `build_sizing_field` step +and the shared steps it depends on (e.g. `prepare_coastline` and +`prepare_river_network`). + +The standalone task shall make it practical to inspect candidate refinement +fields and the final sizing field without running the full unified mesh +workflow. + +The same shared step and configuration shall be reusable from the full unified +workflow when settings match. + +## Algorithm Design + +### Algorithm Design: JIGSAW-Ready Global Sizing Field + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The sizing field should be built on a regular lon/lat grid using the shared +target-grid tier selected for the workflow. The resulting field should be in +the same basic form already expected by Polaris spherical mesh generation: +`cellWidth(lat, lon)` or an equivalent gridded `h(x)` product. + +The output should therefore be a directly inspectable and cacheable artifact +rather than an implicit side effect of JIGSAW geometry handling. This makes +the final `unified_base_mesh` step simpler because it only needs to consume the +finished sizing field and convert it into a JIGSAW mesh and then an MPAS mesh. + +### Algorithm Design: Explicit Consumption of Shared Coastline and River Products + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The intended input contract should be explicit: + +- from `prepare_coastline`: a land/ocean mask on the selected target grid and + a signed coastal-distance field, together with any needed coastline-edge + diagnostics; and +- from `prepare_river_network`: a simplified vector river network suitable for + downstream geometry use, plus target-grid river-channel and river-outlet + masks, together with outlet metadata. + +With this contract, `build_sizing_field` can focus on mesh-resolution logic +rather than source-data interpretation. + +The first design should avoid making `prepare_river_network` responsible for +the full river-refinement policy. If `build_sizing_field` needs a river +distance field, it can derive that distance from the simplified river products +it consumes. At the same time, the first Polaris design should explicitly +retain the existing standalone use of river geometry in the final mesh step. + +### Algorithm Design: Composable Feature-Based Resolution Controls + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first sizing-field algorithm should be framed as a set of candidate fields +combined into a final mesh-spacing field. + +The background field should be constructed first. A reasonable first design is +to use the land/ocean mask from `prepare_coastline` to choose between: + +- an ocean background, which may be constant or may reuse existing Polaris + latitude-dependent functions such as `EC_CellWidthVsLat()` or + `RRS_CellWidthVsLat()`; and +- a land background, which may be constant at first. + +Feature refinement should then be expressed as additional candidate fields: + +- a coastline candidate derived from the signed coastal-distance field, with + configurable transition widths and potentially different treatment on the + land and ocean sides; +- a river candidate derived from distance to the simplified river-channel + network or, in the simplest first pass, from the channel mask itself; and +- an outlet candidate derived from the river-outlet mask, since outlets may + merit stronger or separate refinement. + +The final sizing field should be the pointwise minimum of the background field +and all active feature candidates. This is a clearer design than sequential +overwrites because it makes each contribution explicit and guarantees that +adding a new feature control cannot accidentally coarsen the mesh. + +For coastline refinement, this is also where the Polaris design can diverge +most clearly from the current standalone workflow by favoring explicit raster +candidate fields. For rivers, however, the first Polaris design should be more +conservative. In `mpas_land_mesh`, river influence is split between raster +products and separate geometry handling. Because that behavior is the least +well-understood part of the workflow, Polaris should preserve that division of +labor as much as practical in the early implementation. + +In that formulation, `build_sizing_field` still owns the raster candidate +fields associated with rivers and outlets, and the final +`unified_base_mesh` step should additionally pass the simplified river +geometry to JIGSAW to preserve existing cell-placement behavior. + +If abrupt changes remain after candidate-field composition, the first design +may include a light regularization or smoothing stage, but that should be a +small post-processing step on the final field, not a substitute for clear +feature definitions. + +### Algorithm Design: Compatibility with Shared Target-Grid Tiers + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +`build_sizing_field` should not choose its own grid resolution independently. +Instead, it should consume the selected workflow target-grid tier and produce +its output on that same grid. + +The first design should therefore support a small discrete set of target-grid +tiers shared with `prepare_coastline` and `prepare_river_network`. This keeps +the interfaces between stages simple and makes cached reuse of expensive +preprocessing products practical. + +### Algorithm Design: Standalone Sizing-Field Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The standalone task should be a thin wrapper around the shared +`build_sizing_field` step rather than a separate implementation path. + +The task should depend on the selected coastline and river products and should +write diagnostics that make the sizing-field composition easy to inspect, for +example the background field, coastline candidate, river candidate, outlet +candidate, and final field. + +Because the task wraps the shared step, the same sizing-field products can +later be reused by the final mesh step and the full unified workflow when +configuration choices match. + +## Implementation + +### Implementation: JIGSAW-Ready Global Sizing Field + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Detailed file naming and class layout should be deferred until the algorithmic +contract is settled further. The first implementation should prioritize a +clear gridded output that can be inspected independently of the final mesh +step. + +### Implementation: Explicit Consumption of Shared Coastline and River Products + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation should keep step interfaces explicit and should avoid +reintroducing raw-dataset dependencies inside `build_sizing_field`. + +### Implementation: Composable Feature-Based Resolution Controls + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation should write intermediate diagnostic fields whenever +practical so the effect of each refinement control can be inspected +independently. + +### Implementation: Compatibility with Shared Target-Grid Tiers + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation should use the shared target-grid tier directly in +file naming, work-directory layout, and cache keys so reuse across tasks is +predictable. + +### Implementation: Standalone Sizing-Field Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The first implementation should add a lightweight task wrapper around the +shared step and should avoid a separate task-specific code path. + +## Testing + +### Testing and Validation: JIGSAW-Ready Global Sizing Field + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Detailed validation criteria should be added once the implementation plan is +more concrete. The main early check will be that the final mesh step can +consume the sizing field directly. + +### Testing and Validation: Explicit Consumption of Shared Coastline and River Products + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Early validation should show that `build_sizing_field` can run entirely from +shared preprocessing products without rereading raw topography or HydroRIVERS +inputs. + +### Testing and Validation: Composable Feature-Based Resolution Controls + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Early validation should focus on whether coastline, river-channel, and outlet +controls influence the sizing field in the intended locations and with the +intended relative strengths. + +### Testing and Validation: Compatibility with Shared Target-Grid Tiers + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +Early validation should confirm that the supported target-grid tiers produce +consistent dimensions and are reused correctly by dependent steps. + +### Testing and Validation: Standalone Sizing-Field Task + +Date last modified: 2026/04/10 + +Contributors: + +- Xylar Asay-Davis +- Codex + +The standalone task should eventually be validated as the primary place to +inspect the component refinement fields and the final sizing field before they +are used in the full unified workflow. diff --git a/docs/design_docs/index.md b/docs/design_docs/index.md index bbe87bb77a..65c13c3dd8 100644 --- a/docs/design_docs/index.md +++ b/docs/design_docs/index.md @@ -5,6 +5,9 @@ ```{toctree} :titlesonly: true +build_sizing_field +prepare_coastline +prepare_river_network shared_steps unified_base_mesh vector_reconstruction From 14ad3755b7d26647a2d84d280dd7b93028718ef0 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Fri, 10 Apr 2026 23:47:11 +0200 Subject: [PATCH 07/11] Rename 3 files for clarity --- docs/design_docs/index.md | 6 +++--- ...d_sizing_field.md => unified_mesh_build_sizing_field.md} | 0 ...epare_coastline.md => unified_mesh_prepare_coastline.md} | 0 ...ver_network.md => unified_mesh_prepare_river_network.md} | 0 4 files changed, 3 insertions(+), 3 deletions(-) rename docs/design_docs/{build_sizing_field.md => unified_mesh_build_sizing_field.md} (100%) rename docs/design_docs/{prepare_coastline.md => unified_mesh_prepare_coastline.md} (100%) rename docs/design_docs/{prepare_river_network.md => unified_mesh_prepare_river_network.md} (100%) diff --git a/docs/design_docs/index.md b/docs/design_docs/index.md index 65c13c3dd8..37501674e1 100644 --- a/docs/design_docs/index.md +++ b/docs/design_docs/index.md @@ -5,11 +5,11 @@ ```{toctree} :titlesonly: true -build_sizing_field -prepare_coastline -prepare_river_network shared_steps unified_base_mesh +unified_mesh_build_sizing_field +unified_mesh_prepare_coastline +unified_mesh_prepare_river_network vector_reconstruction template ``` diff --git a/docs/design_docs/build_sizing_field.md b/docs/design_docs/unified_mesh_build_sizing_field.md similarity index 100% rename from docs/design_docs/build_sizing_field.md rename to docs/design_docs/unified_mesh_build_sizing_field.md diff --git a/docs/design_docs/prepare_coastline.md b/docs/design_docs/unified_mesh_prepare_coastline.md similarity index 100% rename from docs/design_docs/prepare_coastline.md rename to docs/design_docs/unified_mesh_prepare_coastline.md diff --git a/docs/design_docs/prepare_river_network.md b/docs/design_docs/unified_mesh_prepare_river_network.md similarity index 100% rename from docs/design_docs/prepare_river_network.md rename to docs/design_docs/unified_mesh_prepare_river_network.md From 2a8cc8f4310efc5ba165a25d1fe3500d44095f35 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Mon, 13 Apr 2026 16:23:04 +0200 Subject: [PATCH 08/11] Update designs to point to add-lat-lon-topo-combine branch --- docs/design_docs/unified_base_mesh.md | 12 ++++++++++-- docs/design_docs/unified_mesh_build_sizing_field.md | 11 +++++++++-- docs/design_docs/unified_mesh_prepare_coastline.md | 12 ++++++++++-- .../unified_mesh_prepare_river_network.md | 11 +++++++++-- 4 files changed, 38 insertions(+), 8 deletions(-) diff --git a/docs/design_docs/unified_base_mesh.md b/docs/design_docs/unified_base_mesh.md index 7533a4570b..9cdcebb08c 100644 --- a/docs/design_docs/unified_base_mesh.md +++ b/docs/design_docs/unified_base_mesh.md @@ -1,6 +1,6 @@ # Unified Global Base Mesh Workflow -date: 2026/04/10 +date: 2026/04/13 Contributors: @@ -397,7 +397,7 @@ existing downstream tasks. ### Implementation: Feature-Aware Resolution Control -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -417,6 +417,14 @@ The likely first-pass step decomposition is: transition zones and buffers; and - `unified_base_mesh`: consume the sizing field and create the MPAS base mesh. +Related enabling work is already in place on the sibling +`add-lat-lon-topo-combine` branch, which adds three lat-lon +`e3sm/init/topo/combine` tasks at 0.0625, 0.25 and 1.0 degree and extends +`CombineStep` accordingly. That branch does not implement the unified-mesh +workflow itself, but it reduces risk for the shared target-grid preprocessing +described here. See Polaris pull request +. + These names are intentionally provisional. They are useful labels for the current design discussion but should not yet be interpreted as final public interfaces or directory names in Polaris. diff --git a/docs/design_docs/unified_mesh_build_sizing_field.md b/docs/design_docs/unified_mesh_build_sizing_field.md index ebd66352a0..eb453e2f3e 100644 --- a/docs/design_docs/unified_mesh_build_sizing_field.md +++ b/docs/design_docs/unified_mesh_build_sizing_field.md @@ -1,6 +1,6 @@ # Sizing-Field Construction for Unified Base Mesh Workflow -date: 2026/04/10 +date: 2026/04/13 Contributors: @@ -285,7 +285,7 @@ step. ### Implementation: Explicit Consumption of Shared Coastline and River Products -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -295,6 +295,13 @@ Contributors: The first implementation should keep step interfaces explicit and should avoid reintroducing raw-dataset dependencies inside `build_sizing_field`. +The sibling `add-lat-lon-topo-combine` branch already implements the shared +lat-lon `e3sm/init/topo/combine` tasks at 0.0625, 0.25 and 1.0 degree and the +associated `CombineStep` support. That does not yet build the sizing field, +but it provides the upstream target-grid topography path assumed by this +design. See Polaris pull request +. + ### Implementation: Composable Feature-Based Resolution Controls Date last modified: 2026/04/10 diff --git a/docs/design_docs/unified_mesh_prepare_coastline.md b/docs/design_docs/unified_mesh_prepare_coastline.md index 126a567ce5..10de53eb69 100644 --- a/docs/design_docs/unified_mesh_prepare_coastline.md +++ b/docs/design_docs/unified_mesh_prepare_coastline.md @@ -1,6 +1,6 @@ # Coastline Preparation for Unified Base Mesh Workflow -date: 2026/04/10 +date: 2026/04/13 Contributors: @@ -264,7 +264,7 @@ by the full unified workflow when configuration choices match. ### Implementation: Raster-First Coastline Products for Downstream Steps -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -276,6 +276,14 @@ deferred until the requirements and algorithm design settle further. The first implementation should favor a small raster-based output contract over a broad set of derived artifacts. +One enabling dependency is already implemented on the sibling +`add-lat-lon-topo-combine` branch: three lat-lon +`e3sm/init/topo/combine` tasks at 0.0625, 0.25 and 1.0 degree, together with +the `CombineStep` changes needed to support `target_grid = lat_lon`. That +work does not yet implement `prepare_coastline`, but it directly supports the +preferred upstream source described in this design. See Polaris pull request +. + ### Implementation: Topography-Consistent and Explicit Coastline Definition Date last modified: 2026/04/10 diff --git a/docs/design_docs/unified_mesh_prepare_river_network.md b/docs/design_docs/unified_mesh_prepare_river_network.md index e43456afa0..15d4c43ffc 100644 --- a/docs/design_docs/unified_mesh_prepare_river_network.md +++ b/docs/design_docs/unified_mesh_prepare_river_network.md @@ -1,6 +1,6 @@ # River Network Preparation for Unified Base Mesh Workflow -date: 2026/04/10 +date: 2026/04/13 Contributors: @@ -253,7 +253,7 @@ configuration choices match. ### Implementation: Downstream-Ready River Network Products -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -265,6 +265,13 @@ settled further. The first implementation should prioritize a clean output contract over carrying forward the standalone workflow's mixed raster conventions. +The sibling `add-lat-lon-topo-combine` branch already adds the shared lat-lon +`e3sm/init/topo/combine` tasks and `CombineStep` support that underpin the +preferred topo-driven coastline path in this design. That is enabling work +rather than a river-network implementation, but it reduces risk for aligning +outlets with shared target-grid coastline products. See Polaris pull request +. + ### Implementation: Hydrologically Meaningful Simplification Date last modified: 2026/04/10 From a26a602bc7fffbcb5ed5342efb79ab55bc6afd89 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Mon, 13 Apr 2026 21:07:55 +0200 Subject: [PATCH 09/11] Update prepare_costline design Here, we add more considerations about lat-lon resolution that is sufficient for defining a reasonable coastline. We also add a flood fill to make sure the ocean is contiguous. Finally, we add 3 different masks for the coastline in Antarctica: calving front, grounding line or zero bedrock elevation (for wetting-and-drying). --- .../unified_mesh_prepare_coastline.md | 116 +++++++++++++----- 1 file changed, 88 insertions(+), 28 deletions(-) diff --git a/docs/design_docs/unified_mesh_prepare_coastline.md b/docs/design_docs/unified_mesh_prepare_coastline.md index 10de53eb69..ad74c2518c 100644 --- a/docs/design_docs/unified_mesh_prepare_coastline.md +++ b/docs/design_docs/unified_mesh_prepare_coastline.md @@ -38,7 +38,7 @@ without running the full unified mesh workflow. ### Requirement: Raster-First Coastline Products for Downstream Steps -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -52,12 +52,19 @@ be consumed directly by both `prepare_river_network` and The shared product shall retain both land/ocean classification and coastal proximity information over the global domain. +The target-grid topography and any coastline-derived sizing inputs shall be +finer than the local destination mesh resolution whenever coastline fidelity +matters, rather than merely matching it. In particular, coarse remapped +topography can produce an unacceptably degraded coastline because of bilinear +interpolation, so a 1-degree product should not be treated as generally +adequate for coastline preparation. + The downstream steps shall not need to reinterpret raw coastline or raw topography source datasets independently. ### Requirement: Topography-Consistent and Explicit Coastline Definition -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -71,6 +78,16 @@ workflow. The treatment of floating Antarctic ice shall be explicit and reproducible, rather than being left implicit in overlapping land and ocean masks. +The coastline workflow shall derive an exclusive ocean mask by starting from +the ocean side and flood filling connected ocean regions, so the ocean +interpretation remains contiguous and disconnected depressions are not +misidentified as ocean simply because their remapped topography falls below +sea level. + +The coastline workflow shall support multiple explicit Antarctic coastline +definitions within the shared design rather than baking in only the first +consumer's needs. + If the topography-derived coastline proves unsuitable for some workflows, the design shall allow an alternate source such as Natural Earth without changing the downstream interface. @@ -115,7 +132,7 @@ workflow when settings match. ### Algorithm Design: Raster-First Coastline Products for Downstream Steps -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -132,12 +149,22 @@ workflow, because `CombineStep` already supports `target_grid = lat_lon`. Rather than inventing a separate remap path, the coastline workflow should reuse that capability to obtain combined topography on the target grid. +The target-grid choice should be constrained by coastline fidelity, not only +by downstream convenience. Because the coastline is inferred from remapped +topography, the remapped product and any derived sizing array should be +meaningfully finer than the local destination mesh spacing. A 0.25-degree +product may be adequate for fairly coarse meshes, but it becomes a marginal +choice as the target mesh approaches roughly 30 km. The 1-degree product is +valuable for some coarse shared preprocessing, but it should not be the +expected choice for high-fidelity coastline preparation. + The shared output contract should remain raster-first. The first design should assume outputs such as: - combined topography on the target grid, either as a direct dependency or as a shared input artifact, not necessarily a new coastline output; -- an exclusive land/ocean mask on that grid; +- one or more exclusive land/ocean masks on that grid, including the primary + ocean-connected mask used by downstream steps; - a coastline-edge indicator on that grid or its cell edges; and - a signed coastal-distance field on that grid. @@ -151,7 +178,7 @@ experiment, it should not become the required downstream artifact. ### Algorithm Design: Topography-Consistent and Explicit Coastline Definition -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -172,18 +199,39 @@ land interpretation while the water below it may still contribute to the ocean interpretation. The coastline workflow should therefore define an explicit Antarctic convention instead of inheriting that ambiguity. -The first design should allow at least two Antarctic conventions: +The first design should produce three related Antarctic coastline products from +the same remapped topography inputs and mask-building logic: - `calving_front`, where floating ice is treated as land for coastline - purposes, so the coastline follows the seaward edge of ice shelves; and + purposes, so the ocean excludes Antarctic ice-shelf cavities and the + coastline follows the calving front; - `grounding_line`, where floating ice is treated as ocean for coastline - purposes, so the coastline follows the grounding line. - -If one default must be chosen early, `calving_front` appears to be the safer -first choice for a shared coastline product because it gives a single -land-ocean partition that is more naturally aligned with land and river outlet -logic. However, the standalone task should make it easy to compare that choice -with `grounding_line` before the full workflow commits to one default. + purposes, so the ocean includes Antarctic ice-shelf cavities and the + coastline follows the grounding line; and +- `bedrock_zero`, where ocean additionally includes grounded Antarctic ice + below sea level, so the coastline follows the zero contour of bedrock. + +These three products should be generated together and cached together rather +than treated as separate future workflow branches. Omega may initially consume +only `calving_front`, but the unified mesh design should preserve the other two +because static cavities, wetting-and-drying, and dynamic grounding-line work +are expected downstream use cases. + +An exclusive ocean mask should not be inferred solely from a local threshold +such as `base_elevation < 0`. Instead, each Antarctic convention should first +define a candidate ocean mask and then perform a flood fill from trusted +ocean-side seed cells to determine the connected ocean region. Cells that are +below sea level but disconnected from the global ocean should remain on the +land side of the partition unless a later workflow explicitly decides +otherwise. This flood-fill step is important both in Antarctica and elsewhere +for preserving a contiguous ocean interpretation. + +If one default must be chosen early for existing downstream workflows, +`calving_front` appears to be the safer first shared product because it gives a +single land-ocean partition that is more naturally aligned with land and river +outlet logic. However, the standalone task should make it easy to compare that +default with the other two shared products before the full workflow commits to +consumer-specific assumptions. If the topography-derived coastline proves too noisy, too expensive, or otherwise unsuitable, a fallback source such as Natural Earth should be @@ -193,7 +241,7 @@ coastline source. ### Algorithm Design: Global Coastal Distance on the Sphere -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -206,17 +254,19 @@ persisted vector geometry product. The basic formulation should be: -1. Construct an exclusive land/ocean mask on the target grid using the chosen - coastline convention. -2. Identify coastline transitions wherever neighboring grid cells switch +1. For each requested coastline convention, construct a candidate ocean mask + on the target grid from the remapped topography fields. +2. Flood fill from trusted ocean-side seed cells to obtain an exclusive, + ocean-connected land/ocean mask. +3. Identify coastline transitions wherever neighboring grid cells switch between land and ocean, wrapping in longitude across the antimeridian. -3. Represent each coastline transition by one or more boundary samples located +4. Represent each coastline transition by one or more boundary samples located on the corresponding grid-cell edges. -4. Convert the boundary samples and all target-grid points to Cartesian +5. Convert the boundary samples and all target-grid points to Cartesian coordinates on the sphere. -5. Use nearest-neighbor search in Cartesian space to estimate the unsigned +6. Use nearest-neighbor search in Cartesian space to estimate the unsigned distance from each grid point to the nearest coastline sample. -6. Apply the sign from the exclusive land/ocean mask. +7. Apply the sign from the exclusive land/ocean mask. This formulation has two advantages for the present design. First, it keeps the public interface raster-based. Second, it turns antimeridian handling into @@ -286,7 +336,7 @@ preferred upstream source described in this design. See Polaris pull request ### Implementation: Topography-Consistent and Explicit Coastline Definition -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -294,9 +344,11 @@ Contributors: - Codex The first implementation should keep the Antarctic convention configurable and -record the chosen convention in output metadata. A fallback coastline source -should be normalized into the same raster-based interface as the preferred -topography-derived path. +record the chosen convention in output metadata. It should also be structured +so the three Antarctic coastline products can be generated in one run and +cached for downstream reuse even if the first consumer uses only one of them. +A fallback coastline source should be normalized into the same raster-based +interface as the preferred topography-derived path. ### Implementation: Global Coastal Distance on the Sphere @@ -327,7 +379,7 @@ shared step and should avoid a separate task-specific code path. ### Testing and Validation: Raster-First Coastline Products for Downstream Steps -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -338,9 +390,13 @@ Detailed validation criteria should be added once the implementation plan is more concrete. The main early check will be that downstream steps can consume the shared coastline outputs without reinterpreting source data. +Validation should also compare supported target-grid tiers and confirm that the +chosen remapped topography resolution is sufficiently finer than the intended +mesh resolution to preserve coastline fidelity in the resulting sizing field. + ### Testing and Validation: Topography-Consistent and Explicit Coastline Definition -Date last modified: 2026/04/10 +Date last modified: 2026/04/13 Contributors: @@ -351,6 +407,10 @@ Early validation should compare the preferred topography-derived coastline against fallback products and should make Antarctic convention differences explicit in diagnostics. +Validation should also confirm that the flood-fill step produces a contiguous +ocean mask for each Antarctic convention and that disconnected below-sea-level +regions do not leak into the ocean classification. + ### Testing and Validation: Global Coastal Distance on the Sphere Date last modified: 2026/04/10 From 1ca827a04ba2cb3dc135a217d541f871fd2e5595 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Tue, 14 Apr 2026 11:30:31 +0200 Subject: [PATCH 10/11] Flesh out prepare_coastline design --- .../unified_mesh_prepare_coastline.md | 277 ++++++++++++++---- 1 file changed, 227 insertions(+), 50 deletions(-) diff --git a/docs/design_docs/unified_mesh_prepare_coastline.md b/docs/design_docs/unified_mesh_prepare_coastline.md index ad74c2518c..5225b289b9 100644 --- a/docs/design_docs/unified_mesh_prepare_coastline.md +++ b/docs/design_docs/unified_mesh_prepare_coastline.md @@ -132,7 +132,7 @@ workflow when settings match. ### Algorithm Design: Raster-First Coastline Products for Downstream Steps -Date last modified: 2026/04/13 +Date last modified: 2026/04/14 Contributors: @@ -155,22 +155,25 @@ topography, the remapped product and any derived sizing array should be meaningfully finer than the local destination mesh spacing. A 0.25-degree product may be adequate for fairly coarse meshes, but it becomes a marginal choice as the target mesh approaches roughly 30 km. The 1-degree product is -valuable for some coarse shared preprocessing, but it should not be the -expected choice for high-fidelity coastline preparation. +valuable mainly for very coarse mesh workflows such as smoke-test meshes near +240 km, but `prepare_coastline` should support all three shared target-grid +tiers from the lat-lon combine workflow: 1.0, 0.25, and 0.0625 degree. The shared output contract should remain raster-first. The first design should assume outputs such as: - combined topography on the target grid, either as a direct dependency or as a shared input artifact, not necessarily a new coastline output; -- one or more exclusive land/ocean masks on that grid, including the primary - ocean-connected mask used by downstream steps; -- a coastline-edge indicator on that grid or its cell edges; and -- a signed coastal-distance field on that grid. +- one multi-variant coastline product containing exclusive land/ocean masks + for the supported Antarctic conventions; +- coastline-cell or coastline-edge indicators for those conventions, plus any + lightweight boundary-sample diagnostics needed by downstream steps; and +- signed coastal-distance fields for those conventions. With this contract, `prepare_river_network` can use the mask or coastline-edge -information for outlet and coastline-consistency checks, while -`build_sizing_field` can consume the signed-distance field directly. +information for the convention chosen by workflow config, while +`build_sizing_field` can consume the corresponding signed-distance field +directly. This approach avoids making a polygonal coastline product part of the public interface. If temporary contour extraction is ever needed for an internal @@ -178,7 +181,7 @@ experiment, it should not become the required downstream artifact. ### Algorithm Design: Topography-Consistent and Explicit Coastline Definition -Date last modified: 2026/04/13 +Date last modified: 2026/04/14 Contributors: @@ -217,14 +220,21 @@ only `calving_front`, but the unified mesh design should preserve the other two because static cavities, wetting-and-drying, and dynamic grounding-line work are expected downstream use cases. +The coastline step should expose these variants through one multi-variant +product, and downstream steps should explicitly choose which convention to +consume through workflow configuration. This is expected to align naturally +with different unified-mesh variants, such as meshes that exclude Antarctic +ice-shelf cavities and meshes that include them. + An exclusive ocean mask should not be inferred solely from a local threshold such as `base_elevation < 0`. Instead, each Antarctic convention should first define a candidate ocean mask and then perform a flood fill from trusted -ocean-side seed cells to determine the connected ocean region. Cells that are -below sea level but disconnected from the global ocean should remain on the -land side of the partition unless a later workflow explicitly decides -otherwise. This flood-fill step is important both in Antarctica and elsewhere -for preserving a contiguous ocean interpretation. +ocean-side seed cells to determine the connected ocean region. The first design +should seed from all candidate-ocean cells on the northernmost latitude row. +Cells that are below sea level but disconnected from the global ocean should +remain on the land side of the partition unless a later workflow explicitly +decides otherwise. This flood-fill step is important both in Antarctica and +elsewhere for preserving a contiguous ocean interpretation. If one default must be chosen early for existing downstream workflows, `calving_front` appears to be the safer first shared product because it gives a @@ -241,7 +251,7 @@ coastline source. ### Algorithm Design: Global Coastal Distance on the Sphere -Date last modified: 2026/04/13 +Date last modified: 2026/04/14 Contributors: @@ -314,58 +324,147 @@ by the full unified workflow when configuration choices match. ### Implementation: Raster-First Coastline Products for Downstream Steps -Date last modified: 2026/04/13 +Date last modified: 2026/04/14 Contributors: - Xylar Asay-Davis - Codex -Detailed class layout, file naming, and output caching strategy should be -deferred until the requirements and algorithm design settle further. The first -implementation should favor a small raster-based output contract over a broad -set of derived artifacts. - -One enabling dependency is already implemented on the sibling -`add-lat-lon-topo-combine` branch: three lat-lon -`e3sm/init/topo/combine` tasks at 0.0625, 0.25 and 1.0 degree, together with -the `CombineStep` changes needed to support `target_grid = lat_lon`. That -work does not yet implement `prepare_coastline`, but it directly supports the -preferred upstream source described in this design. See Polaris pull request -. +The first implementation should add a shared coastline-preparation step that +depends on the shared lat-lon combined-topography steps from the sibling +`add-lat-lon-topo-combine` branch, most likely through a helper such as +`get_lat_lon_topo_steps()` rather than through an ad hoc local remap path. + +That enabling branch already provides lat-lon combined-topography tasks and +shared steps at 0.0625, 0.25 and 1.0 degree, with combined outputs including +`base_elevation`, `ice_draft`, `ice_thickness`, `ice_mask`, and +`grounded_mask`. `prepare_coastline` should treat those fields as the +authoritative upstream inputs for the preferred topo-derived path. See Polaris +pull request . + +The first implementation should support all three of these target-grid tiers +for coastline preparation. In practice, 1.0 degree is likely to be used only +for very coarse or smoke-test meshes, while 0.25 and 0.0625 degree are the +expected production tiers. + +The shared coastline step should produce a multi-variant coastline product with +at least: + +- land masks, ocean masks, coastline-cell masks, coastline-edge diagnostics, + and signed coastal-distance fields for `calving_front`, + `grounding_line`, and `bedrock_zero`; and +- metadata that records how downstream steps should identify the convention + they intend to use. + +The first implementation should also write lightweight metadata and diagnostic +artifacts that record the selected target-grid tier, selected Antarctic +convention names available in the product, source type, mask thresholds, +flood-fill seed strategy, and sign convention. If boundary samples are +generated for signed distance, the step should consider writing them to a +small diagnostic dataset so `prepare_river_network` can reuse them for outlet +snapping if that proves useful. ### Implementation: Topography-Consistent and Explicit Coastline Definition -Date last modified: 2026/04/13 +Date last modified: 2026/04/14 Contributors: - Xylar Asay-Davis - Codex -The first implementation should keep the Antarctic convention configurable and -record the chosen convention in output metadata. It should also be structured -so the three Antarctic coastline products can be generated in one run and -cached for downstream reuse even if the first consumer uses only one of them. -A fallback coastline source should be normalized into the same raster-based -interface as the preferred topography-derived path. +The first implementation should always generate all three Antarctic coastline +products in one run and cache them together for downstream reuse. The +configuration choice should be which convention downstream steps consume from +the multi-variant product, not which convention `prepare_coastline` produces. + +The topo-derived path should likely be organized around a small set of +explicit helpers: + +1. load the shared combined-topography dataset and normalize its coordinate and + metadata handling; +2. threshold remapped `ice_mask` and `grounded_mask` fields into binary masks, + with a configurable threshold whose default is 0.5; +3. build candidate ocean masks for `calving_front`, `grounding_line`, and + `bedrock_zero`; +4. flood fill from trusted ocean-side seed cells to derive an exclusive, + ocean-connected ocean mask for each convention; +5. derive complementary land masks and coastline-edge diagnostics; and +6. write all three conventions into one multi-variant output in a form that + downstream steps can select from explicitly. + +The initial candidate-mask definitions should be straightforward and explicit: + +- `calving_front`: below sea level and not covered by Antarctic ice; +- `grounding_line`: below sea level and not under grounded Antarctic ice; and +- `bedrock_zero`: below sea level, regardless of Antarctic ice state. + +Outside Antarctica, where `ice_mask` is effectively zero, these definitions +reduce to the same open-ocean interpretation. + +The flood-fill implementation should operate on the periodic lon/lat grid with +longitude wraparound and explicit treatment of the two latitude boundaries. +The first implementation should seed from candidate-ocean cells on the +northernmost latitude row. + +Natural Earth fallback behavior does not need to be finalized in the first +implementation plan. The initial implementation should focus on the +topography-derived path and leave detailed fallback design work until a real +need arises. + +The first implementation should write diagnostics that make the mask-building +process auditable. Useful examples include candidate-ocean masks, connected +ocean masks after flood fill, difference masks between Antarctic conventions, +and source-comparison masks when the fallback path is enabled. ### Implementation: Global Coastal Distance on the Sphere -Date last modified: 2026/04/10 +Date last modified: 2026/04/14 Contributors: - Xylar Asay-Davis - Codex -The first implementation should prototype raster-boundary sampling and -spherical nearest-neighbor distance before introducing any custom vector -workflow or custom spherical distance library. +The first implementation should start from the raster land/ocean masks, +identify coastline locations where neighboring cells switch between land and +ocean, and compute spherical distance from each target-grid cell to the +nearest such coastline sample. This should be done before introducing any +custom vector-coastline workflow or custom spherical distance library. + +In practice, that implementation should likely: + +1. derive coastline transitions directly from the exclusive ocean and land + masks for each supported convention; +2. emit a coastline-cell mask indicating cells adjacent to a land-ocean + transition; +3. generate one or more boundary samples on the corresponding cell edges; +4. convert target-grid cell centers and boundary samples to 3D Cartesian + coordinates on the unit sphere; +5. use a KD-tree or closely related nearest-neighbor method to compute + unsigned distance; and +6. apply a recorded sign convention, preferably negative over land and + positive over ocean unless downstream needs suggest the opposite. + +The first implementation should generate and cache signed-distance fields for +all three Antarctic conventions so downstream steps can choose the convention +they need through configuration rather than by rerunning the coastline step. + +The first implementation should include a `viz` step that runs by default and +writes high-resolution PNG diagnostics focused on the coastline itself rather +than on broader cartographic context. In particular, these plots should avoid +adding continents or other background features that would obscure close +inspection of the coastline. The first required plot set should include: + +- three global coastline plots, one each for `calving_front`, + `grounding_line`, and `bedrock_zero`; and +- three Antarctic stereographic coastline plots, again one for each of the + three conventions. ### Implementation: Standalone Coastline Task -Date last modified: 2026/04/10 +Date last modified: 2026/04/14 Contributors: @@ -375,58 +474,125 @@ Contributors: The first implementation should add a lightweight task wrapper around the shared step and should avoid a separate task-specific code path. +The standalone task should depend on the selected shared lat-lon +combined-topography step and then run the shared coastline step plus a `viz` +step by default. + +The `viz` step should write high-resolution PNG plots designed specifically to +inspect the coastline without distracting overlays. The first required plot set +should be: + +- a global plot of the `calving_front` coastline; +- a global plot of the `grounding_line` coastline; +- a global plot of the `bedrock_zero` coastline; +- an Antarctic stereographic plot of the `calving_front` coastline; +- an Antarctic stereographic plot of the `grounding_line` coastline; and +- an Antarctic stereographic plot of the `bedrock_zero` coastline. + +Additional plots such as land/ocean masks, coastline-cell indicators, or +signed-distance fields may still be useful, but they should be treated as +secondary diagnostics after the six coastline plots above. + +This task should be the main place to inspect whether a target-grid tier is +adequate for a given intended mesh resolution before using the product in the +full unified workflow. + ## Testing ### Testing and Validation: Raster-First Coastline Products for Downstream Steps -Date last modified: 2026/04/13 +Date last modified: 2026/04/14 Contributors: - Xylar Asay-Davis - Codex -Detailed validation criteria should be added once the implementation plan is -more concrete. The main early check will be that downstream steps can consume -the shared coastline outputs without reinterpreting source data. +The first automated tests should verify the public output contract directly. +At a minimum, they should confirm that the multi-variant coastline product +exposes the variables and metadata required by downstream steps, including the +land/ocean masks, coastline-edge diagnostics, signed-distance fields, +available Antarctic conventions, target-grid tier, source type, flood-fill +seed strategy, and mask threshold. Validation should also compare supported target-grid tiers and confirm that the chosen remapped topography resolution is sufficiently finer than the intended mesh resolution to preserve coastline fidelity in the resulting sizing field. +This should likely be done first through manual or baseline diagnostic +comparisons at 0.25 and 0.0625 degree rather than through a brittle numerical +threshold alone. + +The first downstream contract checks should confirm that: + +- `prepare_river_network` can consume the land/ocean mask and coastline-edge + diagnostics for a chosen convention without rereading raw topography; and +- `build_sizing_field` can consume the land/ocean mask and signed + coastal-distance field for a chosen convention without reconstructing + coastline geometry itself. ### Testing and Validation: Topography-Consistent and Explicit Coastline Definition -Date last modified: 2026/04/13 +Date last modified: 2026/04/14 Contributors: - Xylar Asay-Davis - Codex +The first automated tests in this area should be unit tests on synthetic +target-grid datasets rather than full global products. Small synthetic cases +should cover at least: + +- a simple non-Antarctic coastline where all conventions agree; +- an Antarctic cavity case where `calving_front` and `grounding_line` differ; +- a grounded-below-sea-level Antarctic case where `grounding_line` and + `bedrock_zero` differ; and +- a disconnected below-sea-level basin that should remain on the land side + after flood fill. + Early validation should compare the preferred topography-derived coastline -against fallback products and should make Antarctic convention differences -explicit in diagnostics. +and should make Antarctic convention differences explicit in diagnostics. Validation should also confirm that the flood-fill step produces a contiguous ocean mask for each Antarctic convention and that disconnected below-sea-level regions do not leak into the ocean classification. +Where practical, synthetic tests should also exercise threshold sensitivity by +perturbing remapped `ice_mask` and `grounded_mask` values around the default +threshold and confirming that the resulting behavior is at least predictable +and metadata-tracked. + ### Testing and Validation: Global Coastal Distance on the Sphere -Date last modified: 2026/04/10 +Date last modified: 2026/04/14 Contributors: - Xylar Asay-Davis - Codex +The first automated tests should focus on the distance helper functions using +small synthetic masks where expected answers are easy to reason about. At a +minimum, tests should cover: + +- a straight coastline on a regular lat-lon grid, where the sign and ordering + of distances should be obvious; +- a coastline crossing the antimeridian, to confirm that longitude wraparound + works correctly; and +- a compact island or cavity example, to confirm that boundary sampling works + sensibly for closed shapes. + Early validation should focus on antimeridian behavior, sign convention, and whether the raster-based spherical distance is smooth enough to drive mesh sizing. +For manual or baseline validation on realistic datasets, the signed-distance +field should also be inspected for artifacts such as stair-stepping, isolated +distance spikes, or convention-dependent discontinuities around Antarctica. + ### Testing and Validation: Standalone Coastline Task -Date last modified: 2026/04/10 +Date last modified: 2026/04/14 Contributors: @@ -436,3 +602,14 @@ Contributors: The standalone task should eventually be validated as the primary place to inspect and compare coastline choices before they are used in the full unified workflow. + +The first task-level validation should be a smoke test that confirms the task +can set up shared dependencies and write the expected coastline products and +the default `viz` outputs for at least one supported target-grid tier. + +Beyond that smoke test, the task should be used for manual comparison of: + +- 1.0, 0.25, and 0.0625 degree coastline fidelity; +- the three Antarctic coastline conventions; +- the resulting global and Antarctic stereographic coastline plots; and +- the resulting signed-distance fields used by downstream sizing. From 018d14e3e08238bb700065cf80b81bc6735ab2a8 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Tue, 14 Apr 2026 12:42:39 +0200 Subject: [PATCH 11/11] Update prepare_coastline design based on actual implementation --- .../unified_mesh_prepare_coastline.md | 65 ++++++++++--------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/docs/design_docs/unified_mesh_prepare_coastline.md b/docs/design_docs/unified_mesh_prepare_coastline.md index 5225b289b9..ca7accdf6d 100644 --- a/docs/design_docs/unified_mesh_prepare_coastline.md +++ b/docs/design_docs/unified_mesh_prepare_coastline.md @@ -164,8 +164,9 @@ assume outputs such as: - combined topography on the target grid, either as a direct dependency or as a shared input artifact, not necessarily a new coastline output; -- one multi-variant coastline product containing exclusive land/ocean masks - for the supported Antarctic conventions; +- one convention-specific coastline product per supported Antarctic + convention, each containing exclusive land/ocean masks on the shared target + grid; - coastline-cell or coastline-edge indicators for those conventions, plus any lightweight boundary-sample diagnostics needed by downstream steps; and - signed coastal-distance fields for those conventions. @@ -220,11 +221,11 @@ only `calving_front`, but the unified mesh design should preserve the other two because static cavities, wetting-and-drying, and dynamic grounding-line work are expected downstream use cases. -The coastline step should expose these variants through one multi-variant -product, and downstream steps should explicitly choose which convention to -consume through workflow configuration. This is expected to align naturally -with different unified-mesh variants, such as meshes that exclude Antarctic -ice-shelf cavities and meshes that include them. +The coastline step should expose these variants through separate but +simultaneously generated products, and downstream steps should explicitly +choose which convention to consume through workflow configuration. This is +expected to align naturally with different unified-mesh variants, such as +meshes that exclude Antarctic ice-shelf cavities and meshes that include them. An exclusive ocean mask should not be inferred solely from a local threshold such as `base_elevation < 0`. Instead, each Antarctic convention should first @@ -333,7 +334,7 @@ Contributors: The first implementation should add a shared coastline-preparation step that depends on the shared lat-lon combined-topography steps from the sibling -`add-lat-lon-topo-combine` branch, most likely through a helper such as +`add-lat-lon-topo-combine` branch through `get_lat_lon_topo_steps()` rather than through an ad hoc local remap path. That enabling branch already provides lat-lon combined-topography tasks and @@ -344,26 +345,26 @@ authoritative upstream inputs for the preferred topo-derived path. See Polaris pull request . The first implementation should support all three of these target-grid tiers -for coastline preparation. In practice, 1.0 degree is likely to be used only +for coastline preparation. In practice, 1.0 degree is expected to be used only for very coarse or smoke-test meshes, while 0.25 and 0.0625 degree are the expected production tiers. -The shared coastline step should produce a multi-variant coastline product with -at least: +The shared coastline step should produce three convention-specific coastline +products, one each for `calving_front`, `grounding_line`, and +`bedrock_zero`, each with at least: -- land masks, ocean masks, coastline-cell masks, coastline-edge diagnostics, - and signed coastal-distance fields for `calving_front`, - `grounding_line`, and `bedrock_zero`; and +- `candidate_ocean_mask`, `ocean_mask`, `land_mask`, `coastline_mask`, + `coastline_edge_east`, `coastline_edge_north`, and `signed_distance` + variables; and - metadata that records how downstream steps should identify the convention they intend to use. The first implementation should also write lightweight metadata and diagnostic artifacts that record the selected target-grid tier, selected Antarctic convention names available in the product, source type, mask thresholds, -flood-fill seed strategy, and sign convention. If boundary samples are -generated for signed distance, the step should consider writing them to a -small diagnostic dataset so `prepare_river_network` can reuse them for outlet -snapping if that proves useful. +flood-fill seed strategy, and sign convention. The first implementation does +not write boundary samples as part of the public product yet, so any later +reuse of those samples by `prepare_river_network` remains future work. ### Implementation: Topography-Consistent and Explicit Coastline Definition @@ -377,9 +378,9 @@ Contributors: The first implementation should always generate all three Antarctic coastline products in one run and cache them together for downstream reuse. The configuration choice should be which convention downstream steps consume from -the multi-variant product, not which convention `prepare_coastline` produces. +the generated files, not which convention `prepare_coastline` produces. -The topo-derived path should likely be organized around a small set of +The topo-derived path is organized around a small set of explicit helpers: 1. load the shared combined-topography dataset and normalize its coordinate and @@ -389,10 +390,11 @@ explicit helpers: 3. build candidate ocean masks for `calving_front`, `grounding_line`, and `bedrock_zero`; 4. flood fill from trusted ocean-side seed cells to derive an exclusive, - ocean-connected ocean mask for each convention; + ocean-connected ocean mask for each convention, implemented with connected + component labeling plus explicit longitude-wrap merging; 5. derive complementary land masks and coastline-edge diagnostics; and -6. write all three conventions into one multi-variant output in a form that - downstream steps can select from explicitly. +6. write one output file per convention in a form that downstream steps can + select from explicitly. The initial candidate-mask definitions should be straightforward and explicit: @@ -433,7 +435,7 @@ ocean, and compute spherical distance from each target-grid cell to the nearest such coastline sample. This should be done before introducing any custom vector-coastline workflow or custom spherical distance library. -In practice, that implementation should likely: +In practice, that implementation does: 1. derive coastline transitions directly from the exclusive ocean and land masks for each supported convention; @@ -444,8 +446,8 @@ In practice, that implementation should likely: coordinates on the unit sphere; 5. use a KD-tree or closely related nearest-neighbor method to compute unsigned distance; and -6. apply a recorded sign convention, preferably negative over land and - positive over ocean unless downstream needs suggest the opposite. +6. apply the recorded sign convention of negative over land and positive over + ocean. The first implementation should generate and cache signed-distance fields for all three Antarctic conventions so downstream steps can choose the convention @@ -476,7 +478,8 @@ shared step and should avoid a separate task-specific code path. The standalone task should depend on the selected shared lat-lon combined-topography step and then run the shared coastline step plus a `viz` -step by default. +step by default. The shared-step helper for this path is +`get_lat_lon_coastline_steps()`. The `viz` step should write high-resolution PNG plots designed specifically to inspect the coastline without distracting overlays. The first required plot set @@ -509,10 +512,10 @@ Contributors: - Codex The first automated tests should verify the public output contract directly. -At a minimum, they should confirm that the multi-variant coastline product -exposes the variables and metadata required by downstream steps, including the -land/ocean masks, coastline-edge diagnostics, signed-distance fields, -available Antarctic conventions, target-grid tier, source type, flood-fill +At a minimum, they should confirm that each convention-specific coastline +product exposes the variables and metadata required by downstream steps, +including the land/ocean masks, coastline-edge diagnostics, signed-distance +fields, coastline convention name, target-grid tier, source type, flood-fill seed strategy, and mask threshold. Validation should also compare supported target-grid tiers and confirm that the