polaris.tasks.e3sm.init.topo.cull.consistency.check_cull_mask_consistency

polaris.tasks.e3sm.init.topo.cull.consistency.check_cull_mask_consistency(ocean_cull_mask, ocean_no_cavities_cull_mask, land_cull_mask, land_ice_mask, convention, logger, max_cells=20)[source]

Check that the cull masks describe a consistent set of domains.

The cull masks are expected to satisfy four invariants, and a fifth that applies only to the calving_front Antarctic boundary convention:

  1. The ocean without ice-shelf cavities is a subset of the ocean. Never the reverse.

  2. The land is exactly the complement of the ocean without cavities, so every cell on the globe is owned by exactly one of the two.

  3. The land-ice mask is zero at every cell the ocean without cavities retains. Equivalently, the ice-shelf cavity cells of the ocean mesh are exactly the cells the ocean retains and the ocean without cavities does not.

  4. Critical land blockages and critical ocean passages are applied identically to the ocean and to the ocean without cavities. This is enforced by construction in polaris.tasks.e3sm.init.topo.cull.CullMaskStep.refine_ocean_cull_mask() rather than checked here.

  5. The two ocean domains differ only by ice-shelf cavities: every cell in the ocean but not in the ocean without cavities carries land ice.

  6. Under calving_front no cell of the ocean carries land ice, since that convention ends the ocean at the calving front.

Invariants 1, 5 and 6 together mean the two ocean domains are identical under calving_front, without that equality having to be asserted directly: the cells they could differ by all carry land ice, and under that convention the ocean has none.

The grid criteria that decide which cells are usable at all – two active edges per ocean cell, an active vertex per sea-ice cell where sea ice forms – are checked separately by check_land_locked_criteria(), which needs the mesh.

Parameters:

  • ocean_cull_mask (xarray.DataArray or numpy.ndarray) – The ocean cull mask on base-mesh cells (1 where cells are culled, 0 where they are kept as ocean/sea-ice)

  • ocean_no_cavities_cull_mask (xarray.DataArray or numpy.ndarray) – The cull mask for the ocean without ice-shelf cavities

  • land_cull_mask (xarray.DataArray or numpy.ndarray) – The land cull mask

  • land_ice_mask (xarray.DataArray or numpy.ndarray) – The Antarctic land-ice mask (1 where land ice is present)

  • convention (str) – The Antarctic boundary convention the masks were built with, from spherical_mesh.antarctic_boundary_convention

  • logger (logging.Logger) – The logger for summary output

  • max_cells (int, optional) – The maximum number of offending cell indices to report per invariant

Raises:

ValueError – If any of the invariants is violated