Unyt - Units for NumPy

Common errors

• unyt.exceptions.UnitConsistencyError: Cannot add quantities with incompatible dimensions

  cause Attempting to perform an arithmetic operation (e.g., addition, subtraction) between unyt_array objects that represent physically incompatible dimensions (e.g., adding mass to length).
  fix Ensure all operands in an arithmetic operation have compatible physical dimensions. If units are convertible, `unyt` will handle it, but if they are fundamentally different, this error will occur. For example, convert units before adding: `(length_in_meters + length_in_feet.to('m'))`.

• AttributeError: 'numpy.ndarray' object has no attribute 'to'

  cause Trying to use `unyt_array` methods like `.to()` or `.in_units()` on a plain `numpy.ndarray` object. This typically happens when a `unyt_array` has been unintentionally converted back to a `numpy.ndarray` (e.g., via `.value` or certain operations).
  fix Ensure the object is a `unyt_array` before attempting unit-aware operations. If you have the raw values, re-create a `unyt_array`: `my_unyt_array = unyt_array(my_numpy_array, 'unit')`.

• TypeError: '<' not supported between instances of 'unyt_quantity' and 'float'

  cause Attempting to compare a `unyt_quantity` or `unyt_array` directly with a bare Python `float` or `int` without explicitly converting the unyt object to a scalar value or defining the numeric value with units.
  fix To compare, either convert the `unyt_quantity` to its numerical value (`quantity.value`) or convert the bare number into a `unyt_quantity` with compatible units before comparison: `if quantity < unyt_array(10.0, quantity.units):`.

Warnings

• breaking unyt v3.1.0 dropped support for Python 3.9. Users on Python 3.9 must upgrade their Python version to 3.10 or newer, or stick to unyt versions older than 3.1.0.
  Fix: Upgrade Python to 3.10 or later, or pin unyt version to `<3.1.0` if 3.9 support is critical.
• gotcha Direct multiplication of a NumPy array by a unit symbol (e.g., `np.array([1,2,3]) * g`) was a common pattern but is discouraged or may behave unexpectedly in newer versions. The preferred method is explicit `unyt_array` creation.
  Fix: Always initialize `unyt_array` explicitly: `unyt_array([10, 20, 30], 'g')` or `unyt_array([10, 20, 30], g)`.
• gotcha Versions of unyt prior to 3.0.4 had known incompatibilities with NumPy 2.1. While fixes have been implemented, users might encounter issues if using an older unyt with a newer NumPy.
  Fix: Ensure `unyt` is version `3.0.4` or newer when using NumPy `2.1` or later.
• gotcha As of unyt v3.0.2, attempting destructive edits to the default unit registry (e.g., modifying existing units or constants globally) is explicitly forbidden and will raise errors.
  Fix: If custom unit behavior is needed, create a custom `UnitRegistry` instance and work with it locally, rather than modifying the global default registry.

Install

• pip install unyt Install stable version

Imports

• unyt_array
  wrong:

  import unyt_array # Directly importing from unyt_array submodule is not standard

  correct:

  from unyt import unyt_array

  Most common units and functions are exposed directly in the top-level 'unyt' namespace.
• Unit
  wrong:

  from unyt.units import Unit # Redundant, exposed at top level

  correct:

  from unyt import Unit

  Used for creating custom unit objects.
• G

  from unyt import G

  Example of importing a pre-defined constant with units (Gravitational constant).
• define_unit

  from unyt import define_unit

  Function to register new units into the registry.

Quickstart

This quickstart demonstrates how to create unyt_array objects, perform basic arithmetic while maintaining units, and convert quantities between different unit systems. It also shows how to access pre-defined physical constants.

from unyt import unyt_array, g, cm, s, G

# Create unyt_arrays with units
mass = unyt_array([10, 20, 30], 'g')
length = unyt_array(5, cm)
time = unyt_array(2, s)

print(f"Initial mass: {mass}")

# Perform arithmetic operations
density = mass / (length**3)
print(f"Calculated density: {density}")

# Convert to different units
density_kg_m3 = density.to('kg/m**3')
print(f"Density in kg/m^3: {density_kg_m3}")

# Access constants
print(f"Gravitational constant: {G}")