Sizing-Field Steps and Tasks

This section of the Developer’s guide covers the code for the unified-mesh sizing-field workflow. The Sizing-field tasks section describes the user-facing behavior, configuration options, and output products.

The polaris.tasks.mesh.spherical.unified.sizing_field package assembles a cell-width map on a shared lat-lon target grid from the coastline and river products produced by the upstream workflows. The sizing-field dataset is the key input to the JIGSAW mesh generator in the downstream base-mesh step.

Available tasks

The helper polaris.tasks.mesh.spherical.unified.sizing_field.add_sizing_field_tasks() registers one standalone task for each mesh name in polaris.mesh.spherical.unified.UNIFIED_MESH_NAMES:

Task structure and shared steps

SizingFieldTask calls polaris.tasks.mesh.spherical.unified.sizing_field.get_unified_mesh_sizing_field_steps() with include_viz=True, which in turn calls the river step factory (see River-Network Steps and Tasks) to obtain all upstream steps and then creates polaris.tasks.mesh.spherical.unified.sizing_field.BuildSizingFieldStep.

The task workdir contains symlinks for all upstream coastline and river steps plus:

  • sizing_field — the shared BuildSizingFieldStep

  • sizing_field_viz — the shared VizSizingFieldStep (when include_viz=True)

Implementation map

build.py

BuildSizingFieldStep.setup() links the coastline convention file from the upstream coastline step, river_network.nc from the upstream lat-lon rasterize step, and topography_finest.nc from the finest-resolution combined-topography step (used for cull emulation). It also calls the mesh-family hook setup_sizing_field_step() so family-specific inputs (e.g. the Southern Ocean high-resolution region GeoJSON for so_region meshes) can be registered.

BuildSizingFieldStep.run() opens coastline.nc and river_network.nc, delegates ocean-background construction to the mesh family via build_ocean_background(), and calls the public helper polaris.tasks.mesh.spherical.unified.sizing_field.sizing_field_dataset() to compose the full sizing field. The resulting dataset is written to sizing_field.nc.

When enable_cull_emulation is true (the default), the shared coastline ocean_mask and signed_distance are first replaced by effective fields built with the helpers in polaris.mesh.spherical.unified.effective_ocean (mesh-scale averaging of the candidate-ocean fraction, critical-transect handling with resolution-proportional passage widening, a seeded flood fill and hysteresis growth) and polaris.mesh.spherical.coastline.signed_distance_from_ocean_mask(). Diagnostic variables (effective_ocean_mask, emulated_ocean_mask, mesh_scale_ocean_fraction, passages_widened) are stored in sizing_field.nc. The rationale and validation are in the unified_mesh_cull_leak design doc.

The public helper sizing_field_dataset() combines:

  • the ocean background from the mesh family (a 2-D cell-width array on the lat-lon grid);

  • the land background (land_background_km);

  • an optional coastline-proximity refinement controlled by enable_coastline_refinement and coastline_transition_land_km; and

  • optional river-channel refinement controlled by enable_river_channel_refinement and river_channel_km.

The result is a cell_width variable on the lat-lon grid, together with provenance attributes recording the source coastline and river steps.

viz.py

VizSizingFieldStep reads sizing_field.nc and writes a global overview plot, an active-control diagnostic map (showing which refinement control dominates at each grid cell), and a plain-text debug_summary.txt with min/max cell widths and count statistics.

Configuration plumbing

All sizing-field steps use mesh-specific configs built through get_sizing_field_config(mesh_name), which layers:

  • the generic unified_mesh.cfg defaults;

  • the shared river_network.cfg file;

  • the family-specific config (e.g. default.cfg or so_region.cfg); and

  • the mesh-specific config file (e.g. u.oi30.lr10.cfg).

BuildSizingFieldStep consumes the [sizing_field] section:

  • ocean_background_mode — 'constant' or 'rrs_latitude' (or delegated to the mesh family)

  • ocean_background_min_km and ocean_background_max_km — cell-width bounds for the ocean background

  • land_background_km — cell width for land cells

  • enable_coastline_refinement — toggle coastline-proximity refinement

  • coastline_transition_land_km — width of the land-side transition zone

  • enable_river_channel_refinement — toggle river-channel refinement

  • river_channel_km — target cell width along river channels

  • enable_cull_emulation — toggle the effective ocean mask built by emulating the MPAS cull at mesh scale

  • cull_emulation_grow_threshold — hysteresis lower bound on the mesh-scale candidate fraction

  • passage_widen_factor, passage_widen_factor_high_lat and passage_widen_latitude_threshold — width of the passage swath that receives ocean-background sizing, relative to the local background

VizSizingFieldStep consumes the [sizing_field_viz] section:

  • dpi — output resolution for diagnostic plots

  • cell_width_cmap — colormap for cell-width plots

The Sizing-field tasks page explains how these options affect the user-visible behavior of the workflow.

Extension points

Common extension paths for future development are:

  • Adding a new named mesh. Create a new .cfg file under polaris.mesh.spherical.unified. Task registration discovers mesh names from those config files automatically.

  • Adding a new ocean-background mode. Implement the mode in polaris.mesh.spherical.unified.base_mesh (or a new mesh family) and handle it in build_ocean_background().

  • Adding a new refinement control. Add parameters to sizing_field_dataset() and the [sizing_field] config section, then update the visualization step and the associated tests.

Test coverage

Unit tests in tests/mesh/spherical/unified/test_sizing_field.py validate the public sizing_field_dataset() helper, the ocean-background construction for each supported mode, and that get_unified_mesh_sizing_field_steps creates the expected shared steps for each named mesh.