Sizing-field tasks

The mesh/spherical/unified/<mesh_name>/sizing_field tasks build a cell-width map on a shared latitude-longitude grid for each named unified mesh. The sizing field combines the coastline and river products from the upstream workflows into a single target cell-width dataset that the downstream base-mesh step (see Unified base-mesh tasks) passes to the JIGSAW mesh generator.

Running these tasks is most useful when you want to inspect or tune the sizing field without committing to a full mesh generation.

Available tasks

Polaris registers one sizing-field task for each named unified mesh:

  • mesh/spherical/unified/<mesh_name>/sizing_field/task

Supported mesh_name values are:

  • u.oi240.lr240

  • u.oi30.lr10

  • u.oi6to18.lr6to10

  • u.oi.so12to30.lr10

The task work directory contains symlinks to all upstream coastline and river shared steps, plus:

  • sizing_field, the step that builds sizing_field.nc; and

  • sizing_field_viz, a diagnostic step that writes cell-width overview plots and a summary text file.

What the sizing field contains

sizing_field.nc stores a cell_width variable on the mesh’s lat-lon target grid. Each grid cell holds the target MPAS cell width in km. The field is built by combining:

  • the ocean background (a 2-D cell-width array derived from the mesh family configuration, e.g. constant or RRS latitude-dependent);

  • the land background (land_background_km); and

  • optional refinement controls derived from the coastline and river masks.

Refinement controls

Two optional refinements can be enabled independently:

Coastline refinement (enable_coastline_refinement) Sets the target cell width at the coastline raster edge to the finest cell width between ocean and land backgrounds. A linear transition of width coastline_transition_land_km can be applied on the land side of the coastline to smooth the transition back to the land background.

River-channel refinement (enable_river_channel_refinement) Reduces the target cell width to river_channel_km on rasterized river channels. This aligns mesh edges with river centerlines in the final JIGSAW mesh.

Configuration

The sizing-field task shares the mesh’s sizing_field.cfg file. The relevant options are in the [sizing_field] section:

  • ocean_background_mode: background ocean resolution mode. Options are constant (one cell width everywhere) and rrs_latitude (latitude- dependent). The so_region mesh family uses an additional mode for Southern Ocean refinement.

  • ocean_background_min_km: minimum ocean background cell width in km. For constant mode, set equal to ocean_background_max_km.

  • ocean_background_max_km: maximum ocean background cell width in km. For rrs_latitude, this is the equatorial resolution. For so_region, this is the coarse background.

  • land_background_km: background land cell width in km.

  • enable_coastline_refinement: whether to apply coastline-proximity refinement.

  • coastline_transition_land_km: width in km of the linear-transition zone on the land side of the coastline. Set to 0 to apply only at the raster edge.

  • enable_river_channel_refinement: whether to refine cells on the river-channel mask.

  • river_channel_km: target cell width in km along river channels.

Visualization options are in [sizing_field_viz]:

  • dpi: output resolution for diagnostic plots.

  • cell_width_cmap: colormap for cell-width plots.

Running a task

polaris setup -t \
    mesh/spherical/unified/u.oi30.lr10/sizing_field/task \
    -w sizing_field_30km

The sizing_field_viz step writes sizing_field_overview.png (a global cell-width map), an active-control diagnostic map (showing which refinement control dominates at each grid cell), and debug_summary.txt with min/max cell widths and count statistics.