# Unified Mesh: Global Base Mesh Workflow date: 2026/04/13 Contributors: - Xylar Asay-Davis - Codex - Claude ## 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`](https://github.com/changliao1025/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 began as a first draft because [`mpas_land_mesh`](https://github.com/changliao1025/mpas_land_mesh) is still evolving, but the stage-specific Polaris workflow pieces described here are now implemented: - coastline preparation, Polaris pull request ; - river-network preparation, Polaris pull request ; and - sizing-field construction, Polaris pull request . The document therefore records both the intended workflow interfaces and the current implementation state. Polaris now has shared coastline, river-network, sizing-field, and base-mesh steps together with standalone unified base-mesh tasks and explicit downstream remap and cull task variants. 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 the final base-mesh stage. 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 E3SM workflows without an extra conversion stage. ## Detailed Stage Designs The four stage-specific unified-mesh design documents provide the detailed workflow design that this umbrella document summarizes: - [Unified Mesh: Coastline Preparation](unified_mesh_prepare_coastline.md) describes the shared coastline-preparation workflow. - [Unified Mesh: River Network Preparation](unified_mesh_prepare_river_network.md) describes the shared river-network preprocessing workflow. - [Unified Mesh: Sizing-Field Construction](unified_mesh_build_sizing_field.md) describes how the upstream shared products are combined into the raster sizing field used for final mesh generation. - [Unified Mesh: Base-Mesh Creation and Downstream Integration](unified_mesh_create_base_mesh.md) describes the final base-mesh stage together with downstream topography remap and land or ocean culling variants. ## 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: 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 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`](https://github.com/changliao1025/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`](https://github.com/changliao1025/mpas_land_mesh) workflow, the first supported sources should be: - a coastline mask derived 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; 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: Shared Target-Grid Tiers and Cacheable Preprocessing Date last modified: 2026/04/22 Contributors: - Xylar Asay-Davis - Codex The workflow should standardize on a small set of supported regular lon/lat target-grid resolutions for all shared preprocessing products. These are: - 0.25 degree; - 0.125 degree; - 0.0625 degree; and - 0.03125 degree. This range is expected to cover needs from quick testing that is not scientifically validated (unified meshes with coarser than ~120 km resolution) to our highest resolutions (finer than ~5 km). 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 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`](https://github.com/changliao1025/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`](https://github.com/changliao1025/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`](https://github.com/changliao1025/mpas_land_mesh) algorithms more closely than the coastline path whenever practical. ## Implementation ### Implementation: Global Spherical MPAS Base Mesh Date last modified: 2026/04/27 Contributors: - Xylar Asay-Davis - Codex The current implementation uses `UnifiedBaseMeshStep` in `polaris.mesh.spherical.unified.base_mesh`. This subclass of `QuasiUniformSphericalMeshStep` overrides `build_cell_width_lat_lon()` to read `cellWidth`, `lon`, and `lat` directly from `sizing_field.nc`, and it links the upstream `clipped_river_network.geojson` product for direct JIGSAW geometry constraints. This keeps the implementation on the existing `SphericalBaseStep.run()` path for JIGSAW invocation, conversion to MPAS form and graph-file creation. The expected output naming remains `base_mesh.nc` as the primary mesh product and `graph.info` produced alongside it. The task wiring is also now implemented. `get_unified_base_mesh_steps()` builds the full shared-step chain for one named unified mesh, and `BaseMeshTask` provides the standalone task wrapper that runs that chain end to end. ### Implementation: Downstream E3SM Interoperability Date last modified: 2026/04/27 Contributors: - Xylar Asay-Davis - Codex The new unified base-mesh step is 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`. That connection is now implemented. The `add_remap_topo_tasks()` and `add_cull_topo_tasks()` factories iterate over the named unified meshes, retrieve the shared unified base-mesh steps, and register explicit remap and cull tasks without an extra mesh translation stage. ### Implementation: Feature-Aware Resolution Control Date last modified: 2026/05/11 Contributors: - Xylar Asay-Davis - Codex - Claude The current step decomposition is now implemented: - `prepare_coastline`: derive a coastline representation suitable for mesh refinement, using the `e3sm/init/topo` coastline as the source; - `prepare_river_network`: simplify and filter a global river dataset into source-level products, target-grid-ready products, and mesh-conditioned river products for final cell-placement control; - `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 the mesh-conditioned river geometry and create the MPAS base mesh. Related enabling work is already in place on the sibling `add-lat-lon-topo-combine` branch, which adds shared lat-lon `e3sm/init/topo/combine` support 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 . The stage-level implementations now make the intended sequence concrete. The coastline workflow provides shared lat-lon coastline products on the supported target-grid resolutions. The river workflow provides shared source-level, target-grid, and mesh-conditioned preprocessing products that can be coordinated with those coastline products. The sizing-field workflow consumes the target-grid coastline and river products for each named unified mesh and writes a JIGSAW-ready `sizing_field.nc`. The base-mesh workflow then consumes that sizing field together with the mesh-conditioned river geometry. This makes the implemented sequence: 1. build or reuse shared lat-lon topography products; 2. derive coastline products on the selected shared target grid; 3. prepare river-network products that use the same shared target grid and a consistent coastline interpretation, including mesh-conditioned river geometry for the final stage; 4. combine coastline and river refinement signals into a unified sizing field; and 5. read that sizing field through `UnifiedBaseMeshStep` while passing the conditioned river geometry into the final spherical base-mesh generation. Coastline, river and sizing-field preprocessing now fit the same shared-step pattern and exchange products on a common target grid. 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`. The final stage is now covered by the separate `unified_mesh_create_base_mesh.md` design, which describes final mesh creation, standalone visualization, and downstream remap and culling integration. The preprocessing steps write clear intermediate products that are useful for debugging and caching, including both source-level vector products and lat-lon target-grid products. These intermediate products are explicit enough to support shared reuse between stages while still keeping `build_sizing_field` as the main integration point. `build_sizing_field` now has a concrete contract. It is 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 retained flowlines, outlet information, masks, or other river-refinement products; and - configuration controlling how these refinement signals are blended, including background cell widths, transition distances and optional feature toggles. Its output is a single regular lon/lat `cellWidth` field in `sizing_field.nc`, together with diagnostic candidate fields and active-control metadata. 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 can consume the resulting `cellWidth` field without needing to know whether refinement came from coastlines, rivers or later feature classes. For coastline processing, the current implementation derives the coastline from the same topography inputs used in `e3sm/init/topo`, because that gives the strongest consistency with downstream masking and culling. It constructs a signed-distance field on the sphere from raster coastline transitions and uses that field to define smooth resolution transitions. The implementation also applies shared critical passages and land blockages before flood filling the candidate ocean mask, which is necessary to keep important connected seas in the ocean domain and to close known artificial openings. The first implementation targets 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. The selected target-grid resolution is now treated as part of this interface. The preprocessing and sizing-field steps exchange products on one shared grid, not on independently chosen grids. ### 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, 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. 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. 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 Date last modified: 2026/04/22 Contributors: - Xylar Asay-Davis - Codex The current shared implementation exposes target-grid choice through the supported lat-lon resolutions in `polaris.mesh.spherical.unified.LAT_LON_TARGET_GRID_RESOLUTIONS`, currently `0.25`, `0.125`, `0.0625`, and `0.03125` degrees. The standalone coastline and river task families both iterate over that same tuple when constructing per-resolution tasks, and the shared step subdirectory layout includes the formatted resolution name. In practice, this means the resolution itself is already part of the cache key and of the work-directory layout, which is exactly the behavior the design intended. ### 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`](https://github.com/changliao1025/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`](https://github.com/changliao1025/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`](https://github.com/changliao1025/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. 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 Date last modified: 2026/05/23 Contributors: - Xylar Asay-Davis - Codex - Claude In `tests/mesh/spherical/unified/test_base_mesh.py`, `test_unified_base_mesh_step_writes_river_geometry` and `test_unified_base_mesh_step_uses_prepared_clipped_river_geometry` verify that `UnifiedBaseMeshStep` correctly reads the sizing field and links river geometry. `test_read_geojson_line_mesh_deduplicates_shared_endpoints` and `test_read_geojson_line_mesh_drops_degenerate_edges_after_dedup` verify the `_read_geojson_line_mesh()` helper used by the step. In `tests/mesh/spherical/unified/test_base_mesh_tasks.py`, `test_add_unified_base_mesh_tasks_registers_named_meshes` verifies one standalone task per named mesh, and `test_add_unified_base_mesh_task_includes_dependencies` verifies the expected full step chain. Standalone base-mesh tasks have been run for all four named unified meshes, producing `base_mesh.nc` and `graph.info` via JIGSAW. The resulting meshes were inspected visually and verified to be consistent with the requested resolution designs. ### Testing and Validation: Downstream E3SM Interoperability Date last modified: 2026/05/23 Contributors: - Xylar Asay-Davis - Codex - Claude In `tests/e3sm/init/topo/test_unified_tasks.py`: - `test_add_remap_topo_tasks_includes_unified_meshes` and `test_add_cull_topo_tasks_includes_unified_meshes` verify that explicit unified-mesh remap and cull task variants are registered for each named mesh. - `test_get_remap_topo_steps_includes_upstream_base_mesh_steps` and `test_get_cull_topo_steps_includes_full_remap_workflow` verify step ordering. - `test_get_remap_topo_steps_reuses_shared_config_for_viz` verifies config reuse across multiple requests. - `test_get_remap_topo_steps_uses_mesh_max_cell_width_for_source_topography` and `test_coarse_unified_mesh_uses_ne120_topography` verify that the coarsest unified mesh selects the low-resolution topography path. - `test_unified_remap_topo_task_includes_base_mesh_dependencies` and `test_unified_cull_topo_task_includes_base_mesh_dependencies` verify that remap and cull tasks include upstream base mesh steps. End-to-end execution through `e3sm/init/topo/cull` has been performed for all four supported unified meshes. The resulting culled ocean and land meshes were inspected and verified to look reasonable, with no ocean cells showing `dcEdge` substantially smaller than the finest requested ocean resolution. ### Testing and Validation: Feature-Aware Resolution Control Date last modified: 2026/05/23 Contributors: - Xylar Asay-Davis - Codex - Claude Current automated coverage for feature-aware preprocessing spans all four stages. Detailed test function lists appear in the per-stage design documents; a high-level summary follows here. In `tests/mesh/spherical/unified/test_coastline.py` and `test_remap_coastline.py`, tests verify the coastline output contract (`ocean_mask`, `signed_distance`), Antarctic convention differences, disconnected basin flood-fill, northernmost-row seeding, critical land blockage and passage handling, and the `get_unified_mesh_coastline_steps()` factory wiring. In `tests/mesh/spherical/unified/test_river.py`, tests verify the channel-only river mask (`river_channel_mask`), coastline-aware clipping, and `UnifiedRiverNetworkTask` registration per mesh name. In `tests/mesh/spherical/unified/test_sizing_field.py`, tests verify that `build_sizing_field_dataset()` composes constant and latitude-dependent ocean backgrounds with land, coastline, and river-channel controls, that mesh-specific subdirectories and config reuse are correct, and that `UnifiedBaseMeshStep` can read `sizing_field.nc`. In `tests/mesh/spherical/unified/test_base_mesh.py` and `test_base_mesh_tasks.py`, tests verify that conditioned river geometry is converted to JIGSAW line constraints and that one standalone base-mesh task is registered per named unified mesh. Standalone tasks for all four stages have been run for all four named unified meshes. Visual inspection of the sizing-field diagnostics, base-mesh plots, river overlays, and culled ocean and land meshes confirmed the expected behavior at each stage. ### Testing and Validation: Shared Target-Grid Tiers and Cacheable Preprocessing Date last modified: 2026/05/23 Contributors: - Xylar Asay-Davis - Codex - Claude Current unit tests verify several parts of this contract. In `tests/mesh/spherical/unified/test_base_mesh_tasks.py` and `tests/mesh/spherical/unified/test_sizing_field.py`: - `test_sizing_field_step_factory_uses_mesh_subdir`, `test_base_mesh_step_factory_uses_mesh_subdir_and_viz`, and related tests verify that the river and sizing-field setup helpers use mesh-specific shared subdirectories. - `test_sizing_field_step_factory_reuses_shared_config_for_viz` and `test_base_mesh_step_factory_reuses_shared_config_for_viz` verify that shared configs are reused when the same product is requested more than once. - `test_add_sizing_field_tasks_registers_named_meshes` verifies that the named mesh configs provide the required configuration. Standalone tasks for all four named unified meshes have been run, exercising all four supported target-grid tiers (0.25, 0.125, 0.0625, and 0.03125 degree) end to end. ### Testing and Validation: Polaris-Native Configuration and Execution Date last modified: 2026/05/23 Contributors: - Xylar Asay-Davis - Codex - Claude The `test_base_mesh_step_factory_includes_dependencies` and `test_sizing_field_step_factory_uses_mesh_family` tests in `tests/mesh/spherical/unified/test_base_mesh_tasks.py` and `test_sizing_field.py` verify that configuration is expressed through Polaris config files and that shared steps are linked by the factory functions. Standalone tasks for all four named unified meshes have been set up and run through standard Polaris setup and run commands, confirming the expected work-directory layout and shared-step reuse. ### Testing and Validation: Selective Migration and Maintainability Date last modified: 2026/05/11 Contributors: - Xylar Asay-Davis - Codex - Claude The implemented coastline, river, sizing-field, and base-mesh unit tests each cover specific helper functions extracted from [`mpas_land_mesh`](https://github.com/changliao1025/mpas_land_mesh) or reimplemented for Polaris. The stage-specific design documents list the precise test functions covering each extracted behavior. The first implementation chose `scipy`, `shapely`, `networkx`, and `rasterio` in place of direct code migration from the standalone utility modules.