polaris.tasks.e3sm.init.component_inputs.maps.map_base_to_culled

polaris.tasks.e3sm.init.component_inputs.maps.map_base_to_culled(ds_map_culled_to_base: Dataset, prefix: str, sizes: dict[str, int]) → Dataset

Invert one culled mesh’s forward map into base-to-culled index fields.

The result is dimensioned by the base mesh and is one-based, with zero meaning “this element is not on that culled mesh”. That matches cellsOnCell and the other MPAS index fields, and differs from the zero-based upstream mapCulledToBase*, which is why each field’s long_name records the convention.

Two properties of the input are checked rather than trusted: every value is a valid base index, and no base index appears twice. Both hold for a map genuinely derived from this base mesh, so a violation means a stale file from a different mesh – which would otherwise scatter into a plausible-looking wrong answer instead of failing.

Parameters:

• ds_map_culled_to_base (xarray.Dataset) – The cull step’s {prefix}_map_culled_to_base.nc, with mapCulledToBase{Cell,Edge,Vertex}.

• prefix (str) – The culled-mesh prefix, one of CULLED_MESH_SUFFIXES.

• sizes (dict of {str: int}) – The nCells, nEdges and nVertices of the base mesh.

Returns:

xarray.Dataset – The three mapBaseTo<Mesh>{Cell,Edge,Vertex} fields.

Raises:

ValueError – If prefix is not a culled mesh, or if a forward map contains an index outside the base mesh or maps two culled elements onto the same base element.