grids.core.GenericGrid.extract_subgrid#

GenericGrid.extract_subgrid(chunks: Sequence[int | Tuple[int, int] | slice], axes: Sequence[str] | None = None, include_ghosts: bool = True, halo_offsets=None, oob_behavior=None, **kwargs) → GenericGrid[source]#

Extract a subgrid (i.e., subdomain) from the current grid using a chunk specification.

This method returns a new grid object representing a subregion of the original domain, optionally including ghost zones and halo padding. The subgrid inherits coordinate properties and geometry from the parent grid.

Parameters:

  • chunks (sequence of int, tuple, or slice) –

    Specification of which chunks to extract along each axis. Each element can be:

    • int: selects a single chunk

    • tuple of int: (start, stop) range of chunk indices

    • slice: standard Python slice object for chunk indexing

    The number of entries must match the number of axes selected via axes, or the full grid dimensionality if axes is None.

  • axes (list of str, optional) – List of axis names to which the chunk specification applies. If None, the chunk specification is applied to all axes in order.

  • include_ghosts (bool, default True) – Whether to include ghost zones at the edges of the domain. If True, ghost cells will be added to the subgrid only on boundaries where the selected chunk touches the edge of the full grid.

  • halo_offsets (int, sequence of int, or np.ndarray of shape ``(2, naxes)``, optional) –

    Additional padding to include around the extracted region, applied in ghost-index space:

    • If a scalar is provided, it applies symmetrically to all axes and sides.

    • If a 1D list or array is provided, it applies symmetrically to each axis.

    • If a 2D array of shape (2, naxes) is provided, it gives explicit left and right padding per axis.

    This padding is applied in addition to any ghost zones included via include_ghosts.

  • oob_behavior ({"raise", "clip"}, default "raise") –

    Determines what to do when the requested region (including ghost zones and halos) exceeds the grid’s physical extent:

    • "raise": Raises an IndexError if the resulting slice would go out of bounds.

    • "clip": Truncates the region to stay within the valid bounds of the ghost-augmented domain.

    Note

    The "ignore" option is not supported — subgrid slices must remain within the grid’s valid ghost-augmented space.

  • kwargs (dict) – Additional keyword arguments passed through to the grid subclass’s __init__() method when constructing the subgrid.

Returns:

A new subgrid instance representing the selected region. This will be an instance of the same class as the original grid (e.g., GenericGrid).

Return type:

GridBase

Raises:

  • IndexError – If the region exceeds grid bounds and oob_behavior="raise".

  • ValueError – If inputs are invalid, malformed, or inconsistent with the grid axes.