Quantities

0.16.4 · active · verified Thu Apr 16

Quantities is a Python library designed to provide support for physical quantities with units, building on the popular NumPy library. It handles arithmetic and conversions of physical quantities, including magnitude, dimensionality, and uncertainty. The current version is 0.16.4. While actively developed with a stable API, test coverage is incomplete, and it is not recommended for mission-critical or production applications. It has an irregular, but active, release cadence.

Common errors

```
ValueError: Unable to convert between units of "dimensionless" and "m/s"
```
cause Attempting to perform an arithmetic operation (e.g., addition) between a quantity with units and a dimensionless number without explicitly providing units for the number.

fix Ensure all operands in an arithmetic expression have compatible units. For example, `velocity + 3 * pq.meter / pq.second` or perform the operation on magnitudes: `velocity.magnitude + 3`.
```
AttributeError: can not modify protected units
```
cause Attempting to modify the `units` attribute of a fundamental unit directly (e.g., `pq.meter.units = 'feet'`). Fundamental units are immutable.

fix You cannot modify the definition of a base unit. To change the units of a `Quantity` object, assign a new unit string or `Unit` object to the `units` attribute of the `Quantity` instance, e.g., `q.units = 'feet'` or `q.units = pq.foot` (note the singular form for `pq.foot`).
```
TypeError: only dimensionless scalar quantities can be converted to Python scalars
```
cause Attempting to convert a quantity with units or a non-scalar quantity directly into a Python scalar (e.g., `float()`) without first removing its units or extracting its magnitude.

fix To get a scalar numerical value from a quantity, use `.magnitude` to access the underlying NumPy array (which might be a 0-d array for scalars) or `.item()` for a Python scalar from a 0-d array. Ensure the quantity is dimensionless if directly converting to a scalar without unit stripping.

Warnings

gotcha Quantities is not suggested for mission-critical or production applications due to incomplete test coverage, despite having a stable API.
Fix: Use with caution in critical systems; thoroughly test specific use cases or consider more mature alternatives like 'Pint' for production environments.
gotcha Directly adding a dimensionless number to a quantity with units will raise a ValueError due to unit incompatibility.
Fix: Ensure that both operands have compatible units. If adding a scalar, it must either be multiplied by a unit or the quantity's magnitude extracted first. Example: `velocity + 3*pq.m/pq.s` or `velocity.magnitude + 3`.
gotcha Quantities only treats temperatures as temperature differences and does not support absolute temperature scales or conversions between them.
Fix: Be aware that temperature quantities represent differences (e.g., a change of 20 degC) rather than absolute points (e.g., 20 degC on the Celsius scale). Calculations involving absolute temperatures might require manual handling or a different library.
gotcha Many NumPy ufuncs (e.g., `np.sin`, `np.exp`) may ignore the dimensions of quantities, treating them as normal arrays and potentially raising 'not implemented' warnings.
Fix: For mathematical functions that expect dimensionless inputs (like trigonometric functions), ensure the quantity is dimensionless or extract its magnitude before passing it. For functions where unit-aware behavior is expected, verify the outcome carefully and consider wrapping the function to handle units explicitly.
breaking Older versions (prior to 0.16.4) had issues with `deepcopy` and in-place arithmetic when used with NumPy 2.x.
Fix: Upgrade to `quantities` version 0.16.4 or newer to resolve these compatibility issues with NumPy 2.x.

Install

pip install quantities Install latest version

Imports

quantities
```
import quantities as pq
```
It is strongly suggested to import quantities to its own namespace to avoid accidental overwrites of unit and constant variables. 'pq' stands for 'physical quantities' or 'python quantities'.

Quickstart

This quickstart demonstrates creating quantities with units, performing basic arithmetic, and converting between different units. The recommended practice is to import the library as `pq`.

import quantities as pq

distance = 42 * pq.meter
time = 17 * pq.second
velocity = distance / time

print(f"Velocity: {velocity:.3f} {velocity.dimensionality}")

# Unit conversion
velocity_kmh = velocity.rescale(pq.km / pq.hour)
print(f"Velocity in km/h: {velocity_kmh:.3f} {velocity_kmh.dimensionality}")

view raw JSON →