deb-python-pint/docs/numpy.rst

NumPy support

The magnitude of a Pint quantity can be of any numerical type and you are free to choose it according to your needs. In numerical applications, it is quite convenient to use NumPy ndarray and therefore they are supported by Pint.

First, we import the relevant packages:

>>> import numpy as np >>> from pint import UnitRegistry >>> ureg = UnitRegistry() >>> Q = ureg.Quantity

import numpy as np from pint import UnitRegistry ureg = UnitRegistry() Q = ureg.Quantity

and then we create a quantity the standard way

>>> legs1 = Q(np.asarray([3., 4.]), 'meter') >>> print(legs1) [ 3. 4.] meter

or we use the property that Pint converts iterables into NumPy ndarrays to simply write:

>>> legs1 = [3., 4.] * ureg.meter >>> print(legs1) [ 3. 4.] meter

All usual Pint methods can be used with this quantity. For example:

>>> print(legs1.to('kilometer')) [ 0.003 0.004] kilometer >>> print(legs1.dimensionality) [length] >>> legs1.to('joule') Traceback (most recent call last): ... pint.errors.DimensionalityError: Cannot convert from 'meter' ([length]) to 'joule' ([length] ** 2 * [mass] / [time] ** 2)

NumPy functions are supported by Pint. For example if we define:

>>> legs2 = [400., 300.] * ureg.centimeter >>> print(legs2) [ 400. 300.] centimeter

we can calculate the hypotenuse of the right triangles with legs1 and legs2.

>>> hyps = np.hypot(legs1, legs2) >>> print(hyps) [ 5. 5.] meter

Notice that before the np.hypot was used, the numerical value of legs2 was internally converted to the units of legs1 as expected.

Similarly, when you apply a function that expects angles in radians, a conversion is applied before the requested calculation:

>>> angles = np.arccos(legs2/hyps) >>> print(angles) [ 0.64350111 0.92729522] radian

You can convert the result to degrees using the corresponding NumPy function:

>>> print(np.rad2deg(angles)) [ 36.86989765 53.13010235] degree

Applying a function that expects angles to a quantity with a different dimensionality results in an error:

>>> np.arccos(legs2) Traceback (most recent call last): ... pint.errors.DimensionalityError: Cannot convert from 'centimeter' ([length]) to 'dimensionless' (dimensionless)

Support

The following ufuncs can be applied to a Quantity object:

• Math operations: add, subtract, multiply, divide, logaddexp, logaddexp2, true_divide, floor_divide, negative, remainder mod, fmod, absolute, rint, sign, conj, exp, exp2, log, log2, log10, expm1, log1p, sqrt, square, reciprocal
• Trigonometric functions: sin, cos, tan, arcsin, arccos, arctan, arctan2, hypot, sinh, cosh, tanh, arcsinh, arccosh, arctanh, deg2rad, rad2deg
• Comparison functions: greater, greater_equal, less, less_equal, not_equal, equal
• Floating functions: isreal,iscomplex, isfinite, isinf, isnan, signbit, copysign, nextafter, modf, ldexp, frexp, fmod, floor, ceil, trunc

And the following ndarrays methods and functions:

• sum, fill, reshape, transpose, flatten, ravel, squeeze, take, put, repeat, sort, argsort, diagonal, compress, nonzero, searchsorted, max, argmax, min, argmin, ptp, clip, round, trace, cumsum, mean, var, std, prod, cumprod, conj, conjugate, flatten

Quantity is not a subclass of ndarray. This might change in the future, but for this reason functions that call numpy.asanyarray are currently not supported. These functions are:

• unwrap, trapz, diff, ediff1d, fix, gradient, cross, ones_like

Comments

What follows is a short discussion about how NumPy support is implemented in Pint's Quantity Object.

For the supported functions, Pint expects certain units and attempts to convert the input (or inputs). For example, the argument of the exponential function (numpy.exp) must be dimensionless. Units will be simplified (converting the magnitude appropriately) and numpy.exp will be applied to the resulting magnitude. If the input is not dimensionless, a DimensionalityError exception will be raised.

In some functions that take 2 or more arguments (e.g. arctan2), the second argument is converted to the units of the first. Again, a DimensionalityError exception will be raised if this is not possible.

This behaviour introduces some performance penalties and increased memory usage. Quantities that must be converted to other units require additional memory and CPU cycles. On top of this, all ufuncs are implemented in the Quantity class by overriding __array_wrap__, a NumPy hook that is executed after the calculation and before returning the value. To our knowledge, there is no way to signal back to NumPy that our code will take care of the calculation. For this reason the calculation is actually done twice: first in the original ndarray and then in then in the one that has been converted to the right units. Therefore, for numerically intensive code, you might want to convert the objects first and then use directly the magnitude.