fields.buffers.base.buffer_from_array#

fields.buffers.base.buffer_from_array(obj: Any, *args, buffer_class: Type[BufferBase] | None = None, buffer_registry: BufferRegistry | None = None, **kwargs) → BufferBase[source]#

Construct a buffer from a raw array-like object.

This function performs the buffer resolution process (see Fields: Data Buffers) to determine a suitable buffer to wrap the provided object.

It is the recommended high-level interface for constructing buffers when the underlying storage format is not known in advance (e.g., NumPy, unyt, HDF5).

Parameters:

  • obj (array-like) –

    Input data to wrap (e.g., list, ndarray, unyt_array, Dataset, etc.).

    By default, the type of obj will be used in conjunction with registry to determine which buffer class is used to wrap the array. If buffer_class is explicitly provided, then an attempt will be made to wrap the array with that class instead (regardless of the registry).

  • buffer_registry (BufferRegistry, optional) – A custom buffer registry to use for automatic resolution. If None (default), uses the global __DEFAULT_BUFFER_REGISTRY__.

  • buffer_class (BufferBase, optional) – An explicit buffer class to use instead of registry resolution. If specified, the function bypasses registry lookup and directly calls from_array().

  • *args – Additional arguments forwarded to the from_array() method.

  • **kwargs – Additional arguments forwarded to the from_array() method.

Returns:

A fully constructed buffer instance wrapping the input data.

Return type:

BufferBase

Raises:

TypeError – If no compatible buffer type is found in the registry (when buffer_class is not specified), or if the input is not valid for the explicitly provided buffer_class.

Examples

By default, the correct buffer class is resolved vis-a-vis the registry. As such, if you simply support an array-like input, a valid buffer will be constructed:

  • A list, tuple, etc. will be interpreted as an array:

    >>> from pymetric.fields.buffers.core import ArrayBuffer, UnytArrayBuffer
>>> buffer_from_array([1, 2, 3])
ArrayBuffer(shape=(3,), dtype=int64)

  • A unyt_array will be interpreted as an UnytArrayBuffer:

    >>> from unyt import unyt_array
>>> from pymetric.fields.buffers.core import ArrayBuffer, UnytArrayBuffer
>>> buffer_from_array(unyt_array([1, 2, 3],units='keV'))
UnytArrayBuffer(shape=(3,), dtype=int64)

You can also enforce a particular buffer class by specifying the buffer_class:

>>> from pymetric.fields.buffers.core import ArrayBuffer, UnytArrayBuffer
>>> u = buffer_from_array([1, 2, 3],buffer_class=UnytArrayBuffer)
>>>
>>> # Let's look at the type and the units
>>> print(type(u), u.units)
<class 'pymetric.fields.buffers.core.UnytArrayBuffer'> dimensionless
>>>
>>> # The units can be specified in kwargs:
>>> u = buffer_from_array([1, 2, 3],buffer_class=UnytArrayBuffer, units='keV')
>>> print(type(u), u.units)
<class 'pymetric.fields.buffers.core.UnytArrayBuffer'> keV

Notes

  • If buffer_class is provided, the registry is ignored.

  • If buffer_class is not provided, resolution proceeds via the registry, honoring the __resolution_priority__ values of registered buffer classes.

  • This method is especially useful in backend-agnostic workflows, field initialization logic, or serialization pipelines.

See also

from_array()

Class-specific buffer creation method.

resolve

Resolve from a specific buffer registry.

On this page

This Page