fields.buffers.core.UnytArrayBuffer.convert_to_units#

UnytArrayBuffer.convert_to_units(units: str | Unit, equivalence=None, **kwargs)[source]#

Convert the buffer data to the specified physical units in-place.

This method performs an in-place conversion of the HDF5 dataset to the target physical units and updates the unit metadata stored in the HDF5 file. The conversion is only valid if the target units are dimensionally compatible with the current units.

The method preserves the structure and layout of the underlying dataset while modifying its numerical values according to the specified units. This is useful when standardizing units across datasets or applying unit-sensitive transformations in physical simulations or analysis pipelines.

Parameters:

  • units (str or Unit) – Target units to convert the buffer data to. Can be a unit string (e.g., “km”) or a unyt.unit_object.Unit instance.

  • equivalence (str, optional) – Optional unit equivalence (e.g., “mass_energy”) to use when converting between units that are not strictly dimensionally identical but are convertible under certain physical principles.

  • **kwargs – Additional keyword arguments forwarded to unyt’s unit conversion routines.

Raises:

UnitConversionError – If the target units are not compatible with the buffer’s existing units.