NumPy integration#

With NumPy installed, Quantity objects work directly with NumPy functions and universal functions. The result is a Quantity with the correct units, and operations that don’t make sense for the units raise an error.

Units in NumPy functions#

Functions that keep the units of their input, such as np.mean, np.max, or np.sort, return a Quantity in the same units. Functions that combine operands, such as np.maximum or np.concatenate, first convert all operands to the units of the first one:

import numpy as np
from ansys.units import Quantity

lengths = Quantity(np.array([1.0, 2.0, 3.0, 6.0]), "m")

np.mean(lengths)  # Quantity (3.0, "m")
np.sum(lengths)  # Quantity (12.0, "m")
np.std(lengths)  # Quantity (1.87..., "m")
np.var(lengths)  # Quantity (3.5, "m^2")
np.diff(lengths)  # Quantity ([1. 1. 3.], "m")

np.concatenate([lengths, Quantity([300.0], "cm")])  # Quantity ([1. 2. 3. 6. 3.], "m")
np.maximum(lengths, Quantity(250.0, "cm"))  # Quantity ([2.5 2.5 3. 6.], "m")

# Quantity ([1.5 2. 3. 4.], "m")
np.clip(lengths, Quantity(150.0, "cm"), Quantity(4.0, "m"))

Arithmetic functions combine units in the same way as the arithmetic operators:

import numpy as np
from ansys.units import Quantity

np.sqrt(Quantity(9.0, "m^2"))  # Quantity (3.0, "m")
np.multiply(Quantity(2.0, "m"), Quantity(3.0, "s"))  # Quantity (6.0, "m s")
np.power(Quantity(2.0, "m"), 3)  # Quantity (8.0, "m^3")

Plain NumPy arrays combined with quantities are treated as dimensionless:

import numpy as np
from ansys.units import Quantity

np.array([1.0, 2.0]) * Quantity(2.0, "m")  # Quantity ([2. 4.], "m")
np.array([2.0, 4.0]) / Quantity(2.0, "s")  # Quantity ([1. 2.], "s^-1")

Trigonometric, exponential, and logarithmic functions#

np.sin, np.cos, and np.tan accept angles in any angle unit, or dimensionless values. np.exp, np.log, and the hyperbolic functions accept only dimensionless values. Inverse trigonometric functions return radians. Other units raise a DimensionlessArgumentRequired error:

import numpy as np
from ansys.units import Quantity

np.sin(Quantity(90.0, "degree"))  # Quantity (1.0, "")
np.arccos(Quantity(0.0, ""))  # Quantity (1.5707..., "radian")
np.arctan2(Quantity(1.0, "m"), Quantity(100.0, "cm"))  # Quantity (0.785..., "radian")
np.exp(Quantity(1.0, ""))  # Quantity (2.718..., "")

np.sin(Quantity(1.0, "m"))  # raises DimensionlessArgumentRequired

Matrix multiplication#

The @ operator and np.matmul multiply the units of their operands:

import numpy as np
from ansys.units import Quantity

matrix = Quantity(np.array([[1.0, 2.0], [3.0, 4.0]]), "m")
vector = Quantity(np.array([1.0, 1.0]), "N")

matrix @ vector  # Quantity ([3. 7.], "m N")
matrix @ [1.0, 2.0]  # Quantity ([5. 11.], "m")
np.dot(matrix[0], vector)  # Quantity (3.0, "m N")

Temperatures#

NumPy functions follow the same temperature rules as the arithmetic operators. See Temperature and temperature difference:

  • Absolute temperatures can’t be summed, so np.sum and np.cumsum raise a ProhibitedTemperatureOperation error. np.mean, np.min, and np.max are allowed.

  • Spreads of absolute temperatures, such as np.ptp, np.diff, and np.std, return temperature differences.

  • Multiplicative functions, such as np.multiply, np.sqrt, or @, raise a ProhibitedOffsetUnitOperation error for C and F.

import numpy as np
from ansys.units import Quantity

temperatures = Quantity(np.array([10.0, 20.0, 40.0]), "C")

np.mean(temperatures)  # Quantity (23.33..., "C")
np.ptp(temperatures)  # Quantity (30.0, "delta_C")
np.sum(temperatures)  # raises ProhibitedTemperatureOperation

Limitations#

  • Functions that aren’t supported, such as np.prod, raise a TypeError instead of guessing the units of the result.

  • The out argument isn’t supported.

  • np.asarray(quantity) doesn’t remove the units. Use quantity.value to get the plain array.