fields.buffers.core.UnytArrayBuffer.in_units

UnytArrayBuffer.in_units(units, *args, equivalence=None, buffer_class=None, buffer_registry=None, as_array: bool = False, equiv_kw: dict | None = None, **kwargs)

Return a new copy of this buffer cast to the specified physical units.

This method is non-destructive and returns either a new buffer or a raw unit-tagged unyt_array. It is the preferred way to convert units for downstream usage or manipulation.

Parameters:

• units (str or unyt.Unit) – Target physical units to cast to.

• equivalence (str, optional) – Name of a supported unyt equivalence scheme (e.g., “mass_energy”).

• buffer_class (type, optional) – If provided, explicitly wrap result in this buffer class.

• buffer_registry (BufferRegistry, optional) – If resolving from array, use this registry.

• as_array (bool, default False) – If True, return a unyt_array instead of re-wrapping as a buffer.

• equiv_kw (dict, optional) – Keyword arguments for the equivalence function.

• *args – Passed to the buffer constructor if wrapping is performed.

• **kwargs – Passed to the buffer constructor if wrapping is performed.

Returns:

Either a raw unit-tagged array or a new buffer with the requested units.

Return type:

unyt_array or BufferBase

Raises:

UnitConversionError – If the units are incompatible.