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 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 is still evolving, but the stage-specific Polaris workflow pieces described here are now implemented:

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:

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 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 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 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.

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

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 https://github.com/E3SM-Project/polaris/pull/526.

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 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.

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 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.