FieldComponent

class fields.components.FieldComponent(grid: GridBase, buffer: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], axes: Sequence[str], /, **kwargs)

A single buffer-aligned component of a geometric field.

FieldComponent represents a dense, spatially resolved data block associated with a single component of a geometric field. It couples a numerical buffer (e.g., NumPy array, unyt, or HDF5 dataset) with metadata about its spatial axes and the structured grid on which it resides.

This class provides the foundational storage and computation interface for fields such as DenseField and DenseTensorField. Each FieldComponent knows which axes it spans, how it aligns with a coordinate grid, and can interact seamlessly with NumPy operations through ufunc overrides and broadcasting.

Key Responsibilities

• Wrap a structured array-like buffer with grid-aware metadata.

• Track which grid axes the data aligns with and support broadcasting across compatible fields.

• Provide NumPy ufunc and array function compatibility.

• Serve as a backend-neutral data container for differential geometry operations.

• Support views into the underlying buffer in various formats (e.g., array, unyt, raw core).

Notes

Each field in the library is composed of one or more FieldComponent instances. Most dense fields only contain one, but multi-component or symbolic fields may combine many for blockwise decomposition or coordinate basis expansion.

Unlike higher-level field objects, FieldComponent does not track symbolic dependence, tensor variance, or units at the field level. It focuses purely on the aligned numerical representation of a single data block.

See also

DenseField

Field class that wraps a single FieldComponent.

DenseTensorField

Tensor-valued field with variance and signature tracking.

BufferBase

Underlying abstract buffer class used to store the field data.

GridBase

Structured grid object that defines spatial coordinates and chunking.

Methods

__init__(grid, buffer, axes, /, **kwargs)	Initialize a FieldComponent instance.
as_array()	Return the buffer as a standard NumPy array.
as_buffer_core()	Return the raw backend array (e.g., np.ndarray, unyt_array, h5py.Dataset).
as_buffer_repr()	Return a NumPy-compatible representation of the buffer.
as_unyt_array()	Return the buffer as a unit-aware unyt_array.
broadcast_buffer_to_axes(axes, *args[, ...])	Return a new buffer instance with data broadcasted to a specified set of axes.
broadcast_to_array_in_axes(axes, **kwargs)	Return the field data as a NumPy array broadcasted to a specified set of axes.
broadcast_to_buffer_core_in_axes(axes, **kwargs)	Return the core backend array (e.g., NumPy, HDF5) broadcasted to a specified set of axes.
broadcast_to_buffer_repr_in_axes(axes, **kwargs)	Return the NumPy-compatible buffer representation broadcasted to specified axes.
broadcast_to_unyt_array_in_axes(axes, **kwargs)	Return the field data as a unit-aware unyt_array broadcasted to specified axes.
convert_to_base([unit_system, equivalence])	Convert the buffer to base units of a given system (in-place).
convert_to_units(units[, equivalence])	Convert the component’s buffer to the specified units (in-place).
empty(grid, axes, *args[, element_shape, ...])	Create a component with an empty buffer.
empty_like(other, *args, **kwargs)	Create an empty component with the same grid, axes, and element shape as another.
expand_axes(axes, *args[, out, ...])	Broadcast and tile an existing FieldComponent to an expanded set of axes.
from_array(array_like, grid, axes, *args[, ...])	Construct a FieldComponent from an existing array-like object.
from_function(func, grid, axes, *args[, ...])	Construct a FieldComponent by evaluating a function on the grid.
full(grid, axes, *args[, fill_value, ...])	Create a component filled with a particular fill value.
full_like(other, *args, **kwargs)	Create a full-valued component with the same grid, axes, and element shape as another.
in_units(units, *args[, as_array, ...])	Return a version of this component in the specified physical units.
ones(grid, axes, *args[, element_shape, ...])	Create a component filled with ones.
ones_like(other, *args, **kwargs)	Create a one-filled component with the same grid, axes, and element shape as another.
reduce_axes(axes, indices, *args[, ...])	Reduce a component to a smaller set of axes by slicing.
reshape_element(new_element_shape, *args, ...)	Reshape the element-wise portion of the buffer (i.e., trailing dimensions) to a new shape.
to(units, *args[, equivalence, ...])	Alias for in_units.
to_value(units[, equivalence])	Return the buffer contents in the specified units, stripped of unit tags.
zeros(grid, axes, *args[, element_shape, ...])	Create a component filled with zeros.
zeros_like(other, *args, **kwargs)	Create a zero-filled component with the same grid, axes, and element shape as another.

Attributes

axes	The spatial axes along which this field component is defined.
buffer	The internal buffer storing this field’s data.
dtype	The data type of the elements stored in the buffer.
element_ndim	Number of trailing element-wise dimensions (e.g., vector or tensor structure).
element_shape	The shape of the element-wise structure (e.g., vector or tensor components).
element_size	Total number of element-wise components.
grid	The structured grid over which this field component is defined.
is_scalar	Return True if the field has no element-wise structure.
naxes	Number of spatial axes the field is defined over.
ndim	Total number of dimensions in the field buffer.
shape	The shape of the full data array, including spatial and element dimensions.
size	Total number of elements in the buffer.
spatial_ndim	Number of spatial dimensions (i.e., number of named axes).
spatial_shape	The shape of the field over the spatial axes (grid-aligned dimensions).
spatial_size	Total number of spatial elements (grid cells).
units	Physical units attached to the buffer data, if defined.