API Reference

Full API reference for the Quantity class.

class quantium.core.quantity.Quantity(value: float, unit: Unit)

Bases: object

Represents a physical quantity with magnitude, dimension, and unit, supporting arithmetic operations and unit conversions while maintaining dimensional consistency.

Attributes

_mag_sifloat

The magnitude of the quantity expressed in SI base units.

dimdict or custom dimension object

The physical dimension of the quantity (e.g., length, time, mass).

unitUnit

The unit in which the quantity is currently represented.

as_key(precision: int = 12) → tuple

Returns a hashable, discretized key for this quantity.

This is the recommended way to use Quantities in dictionaries or sets, as it forces the user to choose a precision level for “fuzzy” hashing.

The standard __hash__ is not implemented because __eq__ uses isclose, which would violate the Python hash contract.

Usage: >>> my_dict = {} >>> q1 = (1.0 + 1e-13) * u.m >>> q2 = (1.0 - 1e-13) * u.m >>> >>> # q1 and q2 are “equal” but not hash-equal >>> q1 == q2 # True >>> >>> # Using as_key forces them to be hash-equal >>> my_dict[q1.as_key(precision=9)] = “value” >>> print(my_dict[q2.as_key(precision=9)]) “value”

Parameters

precisionint, optional

The number of decimal places to round the SI magnitude to for hashing, by default 12 (which is typically near 64-bit float precision limits).

Returns

tuple

A hashable tuple of (dimension, rounded_si_magnitude).

dim

property si: Quantity

to(new_unit: Unit | str) → Quantity

to_si() → Quantity

Return an equivalent Quantity expressed in SI with a preferred symbol when possible. Strategy: 1) If the current unit clearly belongs to a specific SI family (atomic symbol with

scale 1, or a prefixed form of one), keep that family in SI (e.g., kBq → Bq).

2. Otherwise, use the dimension’s preferred symbol (A, N, W, Pa, Hz, …).

3. If no preferred symbol exists, compose the base-SI name from the dimension.

unit

property value: float