UnitFloat

UnitFloat

UnitFloat(value: float, unit: Union[str, 'CompoundUnit'])

An exact scalar value with a physical unit.

Supports unit-safe arithmetic, conversion, and comparison. Dimensional compatibility is checked automatically on every operation that combines two UnitFloat instances.

Parameters:

Name	Type	Description	Default
value	float	Numeric value in the given unit. Must not be NaN.	required
unit	str or CompoundUnit	Unit expression string (e.g. 'kg·m/s^2', 'psia') or a :class:~quantia._compound.CompoundUnit instance.	required

Raises:

Type	Description
UnknownUnitError	If unit contains an unregistered symbol.
UnitParseError	If unit is a malformed expression string.
ValueError	If value is NaN.

Examples:

Basic arithmetic and conversion:

>>> import quantia as qu
>>> d = qu.Q(100.0, 'm')
>>> t = qu.Q(10.0, 's')
>>> v = d / t
>>> v.to('km/h')
UnitFloat(36.0, 'km/h')

Temperature conversion (affine):

>>> qu.Q(100.0, '°C').to('K')
UnitFloat(373.15, 'K')

Gauge to absolute pressure:

>>> qu.Q(0.0, 'psig').to('psia')
UnitFloat(14.695..., 'psia')

from_dict classmethod

from_dict(d: dict) -> 'UnitFloat'

Reconstruct from a dict produced by to_dict().

si_value

si_value() -> float

Return the numeric SI value as a plain float.

Equivalent to self.to_si().value. Use this when you need a dimensionless number for further computation or comparison.

Returns:

Type	Description
float	Numeric value in SI base units.

Examples:

>>> qu.Q(1.0, 'km').si_value()
1000.0

>>> qu.Q(1.0, 'bbl').si_value()
0.158987294928

>>> qu.Q(0.0, 'psig').si_value()
101325.0

to

to(target: Union[str, 'CompoundUnit']) -> 'UnitFloat'

Convert to a different unit of the same physical quantity.

Handles multiplicative units (m → km) and affine units (°C → K, psig → psia, psig → Pa).

Parameters:

Name	Type	Description	Default
target	str or CompoundUnit	Target unit. Must be dimensionally compatible with the current unit.	required

Returns:

Type	Description
UnitFloat	New instance with the value expressed in target.

Raises:

Type	Description
IncompatibleUnitsError	If target has different physical dimensions (e.g. pressure → length).
DimensionError	If mixing affine and non-affine units of incompatible quantities (e.g. psig → m).

Examples:

>>> qu.Q(1.0, 'km').to('m')
UnitFloat(1000.0, 'm')

>>> qu.Q(100.0, '°C').to('°F')
UnitFloat(212.0, '°F')

>>> qu.Q(100.0, 'psig').to('bara')
UnitFloat(7.895..., 'bara')

>>> qu.Q(1.0, 'bbl').to('L')
UnitFloat(158.987..., 'L')

to_dict

to_dict() -> dict

Return a plain dict that round-trips through UnitFloat.from_dict().

to_si

to_si() -> 'UnitFloat'

Convert to the SI base unit representation.

For affine units (temperature, gauge pressure) applies the full affine transformation including offset. For multiplicative units applies the scale factor only.

Returns:

Type	Description
UnitFloat	Value expressed in SI base units (e.g. K, Pa, m/s, m^3).

Examples:

>>> qu.Q(1.0, 'km').to_si()
UnitFloat(1000.0, 'm')

>>> qu.Q(100.0, '°C').to_si()
UnitFloat(373.15, 'K')

>>> qu.Q(0.0, 'psig').to_si()
UnitFloat(101325.0, 'Pa')