fields.buffers.utilities.buffer#

fields.buffers.utilities.buffer(array: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], *args, buffer_class: Type[BufferBase] | None = None, buffer_registry: BufferRegistry | None = None, **kwargs) → BufferBase[source]#

Wrap an array-like object in a Pisces buffer instance.

This is the high-level constructor for buffer creation, analogous to np.array(...). It resolves the appropriate buffer backend (e.g., NumPy, unyt, HDF5) and returns a fully initialized buffer instance from the input array.

This is the recommended entry point for turning arbitrary user data into a structured buffer within the Pisces field system.

Parameters:

  • array (array-like) – Any object that can be converted into a backend-compatible array, such as a list, tuple, numpy.ndarray, unyt_array, or other supported type.

  • *args – Additional positional arguments forwarded to the resolved buffer class’s from_array() method.

  • buffer_class (BufferBase, optional) – Explicit buffer class to use for wrapping. If provided, from_array() is called on this class.

  • buffer_registry (BufferRegistry, optional) – Registry to use when resolving array into a buffer class. Defaults to the global registry.

  • **kwargs – Additional keyword arguments forwarded to the buffer class’s from_array() method. This includes things like dtype, units, copy, order, or HDF5-specific parameters.

Returns:

A fully constructed buffer instance containing the wrapped array.

Return type:

BufferBase

Raises:

  • TypeError – If the input cannot be resolved into a supported buffer class.

  • ValueError – If resolution fails due to misconfiguration of buffer class or registry.

See also

buffer_zeros, buffer_ones, buffer_full, buffer_empty

Examples

Convert a list to an ArrayBuffer:

>>> from pymetric.fields.buffers.utilities import buffer
>>> import numpy as np
>>>
>>> b = buffer([1, 2, 3])
>>> type(b).__name__
'ArrayBuffer'
>>> b.as_array()
array([1, 2, 3])

Creating an HDF5 buffer from a list:

>>> b = buffer([1, 2, 3],file='test.hdf5',path='test',overwrite=True,buffer_class='HDF5Buffer')
>>> type(b).__name__
'HDF5Buffer'
>>> b.as_array()
array([1, 2, 3])
>>> np.add(b,b,out=b)
>>> b.as_array()
On this page

This Page