polaris.tasks.e3sm.init.topo.cull.dc_edge_diagnostics.check_ocean_dc_edge

polaris.tasks.e3sm.init.topo.cull.dc_edge_diagnostics.check_ocean_dc_edge(ds_base_mesh, ocean_cull_mask, ds_sizing, min_ratio, max_ratio, min_abs_ratio, logger, out_filename='ocean_dc_edge_diagnostics.nc', max_clusters=10)[source]

Check that dcEdge in the ocean/sea-ice domain stays within bounds relative to the local ocean background cell width.

Edges whose two adjacent cells are both kept by the ocean cull mask (the interior edges of the future culled ocean mesh) are compared against the ocean background cell width sampled from the unified sizing field at the edge location. A diagnostics file with the per-edge ratio and violation masks is written, and a ValueError is raised if any ratio falls below min_ratio or above max_ratio.

See the design document unified_mesh_cull_leak in the documentation for the motivation and the choice of thresholds.

Parameters:

  • ds_base_mesh (xarray.Dataset) – The base MPAS mesh, with dcEdge, latEdge, lonEdge and cellsOnEdge

  • 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)

  • ds_sizing (xarray.Dataset) – The unified sizing field, with ocean_background_cell_width (km) on lat/lon coordinates (degrees)

  • min_ratio (float) – The minimum allowed ratio of dcEdge to the local ocean background cell width. This guards against land/river resolution leaking into the ocean, which shows up as a locally anomalous ratio.

  • max_ratio (float) – The maximum allowed ratio of dcEdge to the local ocean background cell width

  • min_abs_ratio (float) – The minimum allowed ratio of the shortest dcEdge anywhere in the domain to the finest ocean background cell width anywhere in it. This is the CFL guard: the time step is set by the shortest edge globally, and a mesh is already sized for its finest intended resolution, so an edge that is short only relative to a coarse local background costs nothing.

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

  • out_filename (str, optional) – The name of the diagnostics file to write

  • max_clusters (int, optional) – The maximum number of violation clusters to report

Raises:

ValueError – If any ocean-interior edge violates the ratio bounds, or if the shortest edge violates the absolute bound