UnitArray

UnitArray

UnitArray(
    values: Iterable[float],
    unit: Union[str, "CompoundUnit"],
)

An exact array of values sharing a single physical unit.

All elements carry the same unit. Arithmetic operations between two UnitArray instances check dimensional compatibility and handle unit conversion automatically.

Parameters:

Name	Type	Description	Default
values	iterable of float	Numeric values, all in the given unit.	required
unit	str or CompoundUnit	Physical unit shared by all elements.	required

Raises:

Type	Description
TypeError	If any element of values is not numeric.

Examples:

>>> import quantia as qu
>>> heights = qu.QA([1.75, 1.80, 1.65], 'm')
>>> heights.mean()
UnitFloat(1.7333..., 'm')

>>> heights.to('cm')
UnitArray([175.0, 180.0, 165.0], 'cm')

Boolean mask filtering:

>>> tall = heights[heights > qu.Q(1.78, 'm')]
>>> list(tall.values)
[1.8]

dot

dot(o: 'UnitArray') -> 'UnitFloat'

Compute the dot product with another array.

Parameters:

Name	Type	Description	Default
o	UnitArray	Second operand. Must have the same length.	required

Returns:

Type	Description
UnitFloat	Scalar result with the product unit.

Raises:

Type	Description
ValueError	If arrays have different lengths.

Examples:

>>> a = qu.QA([1.0, 2.0, 3.0], 'N')
>>> b = qu.QA([4.0, 5.0, 6.0], 'm')
>>> a.dot(b)
UnitFloat(32.0, 'J')

max

max() -> 'UnitFloat'

Return the maximum element.

Returns:

Type	Description
UnitFloat	Maximum value in the array's unit.

mean

mean() -> 'UnitFloat'

Return the arithmetic mean of all elements.

Returns:

Type	Description
UnitFloat	Mean in the array's unit.

Examples:

>>> qu.QA([10.0, 20.0, 30.0], 'm').mean()
UnitFloat(20.0, 'm')

min

min() -> 'UnitFloat'

Return the minimum element.

Returns:

Type	Description
UnitFloat	Minimum value in the array's unit.

sum

sum() -> 'UnitFloat'

Return the sum of all elements.

Returns:

Type	Description
UnitFloat	Sum in the array's unit.

Examples:

>>> qu.QA([1.0, 2.0, 3.0], 'm').sum()
UnitFloat(6.0, 'm')

to

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

Convert all elements to a different unit of the same quantity.

Parameters:

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

Returns:

Type	Description
UnitArray	New array with all values expressed in target.

Raises:

Type	Description
IncompatibleUnitsError	If target has different physical dimensions.

Examples:

>>> qu.QA([1.0, 2.0, 3.0], 'km').to('m')
UnitArray([1000.0, 2000.0, 3000.0], 'm')

to_csv

to_csv(
    path: Union[str, "Path"], header: str | None = None
) -> None

Write values to a single-column CSV file.

Parameters:

Name	Type	Description	Default
path	Union[str, 'Path']		required
header	str, optional. Defaults to "value [<unit>]".		None

to_si

to_si() -> 'UnitArray'

Convert all elements to the SI base unit representation.

Returns:

Type	Description
UnitArray	New array with values in SI base units.

Examples:

>>> qu.QA([1.0, 2.0], 'km').to_si()
UnitArray([1000.0, 2000.0], 'm')