GenericGrid

class grids.core.GenericGrid(coordinate_system: _CoordinateSystemBase, coordinates: Sequence[ndarray], /, ghost_zones: Sequence[Sequence[float]] | None = None, chunk_size: Sequence[int] | None = None, *args, units: Dict[str, str | Unit] | None = None, center: Literal['vertex', 'cell'] = 'vertex', bbox: BoundingBox | None = None, **kwargs)

Generic coordinate grid with arbitrary, non-uniform spacing.

The GenericGrid class represents a general-purpose structured grid in which the coordinate values along each axis are explicitly specified via user-provided 1D arrays. This allows for arbitrarily non-uniform grids, such as those used in mapped or curvilinear coordinate systems.

When initializing the class, the coordinates argument takes a set of \(N\) arrays of increasing coordinate values \(x_i^k\). The grid is then constructed as the Cartesian product of these \(N\) arrays:

\[G_{ijk...} = (x_1^i,x_2^j,x_3^k,\ldots).\]

Notes

The provided coordinates are interpreted as either vertices or cell centers depending on the center= argument to __init__.

Examples

Construct a uniformly spaced grid in Cartesian coordinates:

>>> from pymetric.coordinates import CartesianCoordinateSystem3D
>>> import numpy as np
>>>
>>> # Create the coordinate system.
>>>
>>> u = CartesianCoordinateSystem3D()
>>>
>>> # Construct the coordinates using
>>> # NumPy arrays.
>>> coords = [np.linspace(0, 1, 10), np.linspace(0, 1, 20), np.linspace(0, 1, 30)]
>>>
>>> # Now build the grid.
>>> # In this case, 2 of the cells are assigned to ghost regions
>>> # on each axis.
>>> grid = GenericGrid(u, coords, ghost_zones=[[1, 1, 1],[1, 1, 1]])
>>>
>>> # Inspect the bounding box and the ghost bounding box.
>>> print(grid.bbox)
[[0.11111111 0.05263158 0.03448276]
 [0.88888889 0.94736842 0.96551724]]
>>> print(grid.gbbox)
[[0. 0. 0.]
 [1. 1. 1.]]
>>>
>>> # Inspect the number of cells in the
>>> # grid (ghost and no ghost).
>>> print(grid.dd)
[ 8 18 28]
>>> print(grid.gdd)
[10 20 30]

See also

UniformGrid

Grid with uniform spacing and analytically defined coordinate structure.

GenericField

Field defined on a grid.

Methods

__init__(coordinate_system, coordinates, /)	Construct a generic grid on a particular coordinate system.
broadcast_array_to_axes(array, axes_in, ...)	Reshape and broadcast an array aligned with axes_in so it is compatible with axes_out.
broadcast_arrays_to_axes(arrays, axes_in, ...)	Broadcast multiple arrays aligned to axes_in so they are compatible with axes_out.
broadcast_shape_to_axes(shape, axes_in, axes_out)	Expand an input shape aligned to axes_in so it is broadcastable against axes_out.
broadcast_shapes_to_axes(shapes, axes_in, ...)	Broadcast multiple input shapes aligned to axes_in so they are compatible with axes_out.
check_field_shape(array_shape[, axes, ...])	Validate that a field array shape is compatible with the grid over the specified axes.
compute_chunk_centers(chunks[, axes, ...])	Return coordinate center arrays for a specific chunk along the selected axes.
compute_chunk_coords(chunks[, axes, ...])	Compute physical coordinate arrays for a selected chunk region.
compute_chunk_edges(chunks[, axes, ...])	Return coordinate edge arrays for a specific chunk along the selected axes.
compute_chunk_mesh(chunks[, axes, ...])	Compute a meshgrid of physical coordinates over a selected chunk region.
compute_chunk_slice(chunks[, axes, ...])	Compute a global index-space slice corresponding to one or more chunks along selected axes, with optional ghost zones and halo padding.
compute_coords_from_index(index, /[, axes, ...])	Compute the physical coordinates at a specific grid index.
compute_coords_from_slices(slices, /[, ...])	Compute coordinate arrays over a region of the grid specified by slice objects.
compute_domain_centers([axes, origin, ...])	Return coordinate center arrays along each axis.
compute_domain_coords([axes, origin, ...])	Compute the 1D coordinate arrays for the full extent of the grid domain along the selected axes.
compute_domain_edges([axes, origin, ...])	Return coordinate edge arrays along each axis.
compute_domain_mesh([axes, origin, __validate__])	Compute a meshgrid of coordinate arrays spanning the full domain of the grid.
compute_domain_slice([axes, include_ghosts, ...])	Compute a slice representing the entire grid domain with some set of axes, halo offsets, and ghost zone behavior.
compute_function_on_grid(func, /[, ...])	Evaluate a coordinate-based function over the grid domain.
compute_mesh_from_slices(slices, /[, axes, ...])	Compute coordinate arrays over a region of the grid specified by slice objects.
construct_chunk_interpolator(field, ...[, ...])	Construct an interpolator for a specific chunk using SciPy's RegularGridInterpolator.
construct_domain_interpolator(field, field_axes)	Construct an interpolator object over the entire grid domain on a particular subset of axes.
dense_adjust_tensor_signature(tensor_field, ...)	Adjust the index signature of a tensor field by raising or lowering multiple indices.
dense_contract_with_metric(tensor_field, ...)	Contract a tensor index with the metric tensor or its inverse.
dense_contravariant_gradient(tensor_field, ...)	Compute the contravariant gradient of a dense-representation tensor field on a grid.
dense_covariant_gradient(tensor_field, ...)	Compute the covariant gradient of a dense-representation tensor field on a grid.
dense_element_wise_laplacian(field, ...[, ...])	Compute the element-wise Laplacian of an array-valued field on the grid.
dense_element_wise_partial_derivatives(...)	Compute the element-wise partial derivatives of an array-valued field over the grid.
dense_gradient(tensor_field, field_axes, /)	Compute the element-wise gradient of a tensor field over a grid.
dense_lower_index(tensor_field, field_axes, ...)	Lower a single contravariant index of a tensor field.
dense_raise_index(tensor_field, field_axes, ...)	Raise a single covariant index of a tensor field.
dense_scalar_laplacian(field, field_axes, /)	Compute the element-wise Laplacian of a tensor field.
dense_vector_divergence(vector_field, ...[, ...])	Compute the divergence of a vector field, with automatic basis dispatching.
dense_vector_divergence_contravariant(...[, ...])	Compute the divergence of a contravariant vector field on a grid.
dense_vector_divergence_covariant(...[, ...])	Compute the divergence of a covariant vector field on a grid.
determine_domain_shape([axes, ...])	Compute the shape of the domain along specified axes, including ghost zones and optional halo padding.
empty([element_shape, axes, include_ghosts, ...])	Return an uninitialized array shaped to match a domain-aligned region of the grid.
empty_like_chunks(chunks, /[, ...])	Return an uninitialized array shaped to match a domain-aligned region of the grid.
extract_subgrid(chunks[, axes, ...])	Extract a subgrid (i.e., subdomain) from the current grid using a chunk specification.
from_hdf5(filename[, group_name])	Load a grid instance from an HDF5 file.
full(fill_value, /[, element_shape, axes, ...])	Return a constant-valued array shaped to match a domain-aligned region of the grid.
full_like_chunks(chunks, fill_value, /[, ...])	Return a constant-valued array shaped to match a domain-aligned region of the grid.
get_chunk_bbox(chunks[, axes, ...])	Return the physical bounding box (lower, upper) of a given chunk.
get_chunk_shape(chunks[, axes, ...])	Compute the shape of the buffer corresponding to a given chunk, including optional ghost zones and halo padding.
iter_chunk_coords([axes, include_ghosts, ...])	Efficiently iterate over physical coordinates for each chunk in the grid.
iter_chunk_indices([axes, pbar, pbar_kwargs])	Iterate over chunk indices for the grid along specified axes.
iter_chunk_slices([axes, include_ghosts, ...])	Efficiently iterate over chunk-wise slices in global index space.
ones([element_shape, axes, include_ghosts, ...])	Return an array of ones shaped to match a domain-aligned region of the grid.
ones_like_chunks(chunks, /[, element_shape, ...])	Return an array of ones shaped to match a domain-aligned region of the grid.
plot_chunk_lines([grid_axes, ax, include_ghosts])	Plot chunk boundaries along the specified 2D projection of the domain.
plot_ghost_zone_shading([grid_axes, ax, ...])	Shade the ghost zones in a 2D grid projection.
plot_grid_lines([grid_axes, ax, include_ghosts])	Plot coordinate grid lines along the specified 2D slice of the domain.
show()	Alias for summary() to allow interactive/quick display.
standardize_axes([axes])	Standardize the axes provided.
summary()	Print a summary of the grid structure, including domain shape, chunking, coordinate system, and ghost zone information.
tile_array_to_axes(array, axes_in, axes_out, ...)	Tile a lower-dimensional array across the full domain of the grid defined by axes_out.
to_hdf5(filename[, group_name, overwrite])	Save this grid object as / in an HDF5 file.
zeros([element_shape, axes, include_ghosts, ...])	Return an array of zeros shaped to match a domain-aligned region of the grid.
zeros_like_chunks(chunks, /[, ...])	Return an array of zeros shaped to match a domain-aligned region of the grid.

Attributes

axes	The names of the coordinate axes in this grid.
axes_units	Units corresponding to each coordinate axis in the grid.
bbox	The physical bounding box of the grid (excluding ghost zones).
cdd	The shape of a single chunk, expressed in grid points.
centering	Returns whether the grid is cell- or vertex-centered.
chunk_size	The size of each chunk along every axis, if chunking is enabled.
chunking	Whether chunking is enabled for this grid.
coordinate_system	The coordinate system (e.g. a subclass of OrthogonalCoordinateSystem) which underlies this grid.
dd	The shape of the active grid (excluding ghost cells), expressed in grid points.
fill_values	Dictionary of default fill values for each axis.
gbbox	The full bounding box of the grid, including ghost regions.
gdd	The full grid dimensions, including ghost cells.
ghost_zones	Number of ghost cells on either side of each axis.
ncells	Number of computational cells (excluding ghost zones).
ndim	The number of spatial dimensions in the grid.
nvertices	Number of grid vertices (excluding ghost zones).
shape	The shape of the grid (excluding ghost cells), as a tuple of point counts.
unit_system	The unit system associated with the grid.