DimArray¶
The core class for dimension-aware arrays.
Overview¶
DimArray wraps a NumPy array and tracks its physical dimensions through all operations. Operations between incompatible dimensions raise DimensionError immediately.
from dimtensor import DimArray, units
# Create a DimArray
velocity = DimArray([10, 20, 30], units.m / units.s)
API Reference¶
DimArray
¶
A numpy array with attached physical units.
DimArray wraps a numpy array and tracks its physical dimensions through all arithmetic operations. Operations between incompatible dimensions raise DimensionError immediately, catching physics errors early.
Examples:
>>> from dimtensor import DimArray, units
>>> v = DimArray([1.0, 2.0, 3.0], units.m / units.s)
>>> t = DimArray([0.5, 1.0, 1.5], units.s)
>>> d = v * t # distance in meters
>>> print(d)
[0.5 2.0 4.5] m
data: NDArray[Any]
property
¶
The underlying numpy array (read-only view).
unit: Unit
property
¶
The physical unit of this array.
dimension: Dimension
property
¶
The physical dimension of this array.
shape: tuple[int, ...]
property
¶
Shape of the underlying array.
ndim: int
property
¶
Number of dimensions.
size: int
property
¶
Total number of elements.
dtype: np.dtype[Any]
property
¶
Data type of the underlying array.
is_dimensionless: bool
property
¶
Check if this array is dimensionless.
__init__(data: ArrayLike, unit: Unit | None = None, dtype: DTypeLike = None, copy: bool = False, uncertainty: ArrayLike | None = None) -> None
¶
Create a DimArray.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
ArrayLike
|
Array-like data (list, tuple, numpy array, or scalar). |
required |
unit
|
Unit | None
|
Physical unit of the data. If None, assumes dimensionless. |
None
|
dtype
|
DTypeLike
|
Numpy dtype for the underlying array. |
None
|
copy
|
bool
|
If True, always copy the data. |
False
|
uncertainty
|
ArrayLike | None
|
Optional absolute uncertainty (same shape as data). |
None
|
to(unit: Unit) -> DimArray
¶
Convert to a different unit with the same dimension.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
unit
|
Unit
|
Target unit (must have same dimension). |
required |
Returns:
| Type | Description |
|---|---|
DimArray
|
New DimArray with converted values and new unit. |
DimArray
|
Uncertainty is scaled by the same conversion factor. |
Raises:
| Type | Description |
|---|---|
UnitConversionError
|
If dimensions don't match. |
to_base_units() -> DimArray
¶
Convert to SI base units.
Returns a DimArray with scale factor 1.0 (pure SI units). Uncertainty is scaled accordingly.
magnitude() -> NDArray[Any]
¶
Return the numerical magnitude (stripping units).
Use with caution - this loses dimensional safety.
sum(axis: int | None = None, keepdims: bool = False) -> DimArray
¶
Sum of array elements.
Uncertainty propagation: sigma_sum = sqrt(sum(sigma_i^2))
mean(axis: int | None = None, keepdims: bool = False) -> DimArray
¶
Mean of array elements.
Uncertainty propagation: sigma_mean = sqrt(sum(sigma_i^2)) / N
std(axis: int | None = None, keepdims: bool = False) -> DimArray
¶
Standard deviation of array elements.
Note: Uncertainty propagation through std is complex and not implemented. The result will have no uncertainty information.
var(axis: int | None = None, keepdims: bool = False) -> DimArray
¶
Variance of array elements.
Note: Variance has units squared (e.g., m -> m^2). Uncertainty propagation through variance is not implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
axis
|
int | None
|
Axis along which to compute variance. |
None
|
keepdims
|
bool
|
If True, reduced dimensions are kept with size 1. |
False
|
Returns:
| Type | Description |
|---|---|
DimArray
|
Variance with squared unit. |
min(axis: int | None = None, keepdims: bool = False) -> DimArray
¶
Minimum value.
Uncertainty: takes uncertainty of the minimum element.
max(axis: int | None = None, keepdims: bool = False) -> DimArray
¶
Maximum value.
Uncertainty: takes uncertainty of the maximum element.
argmin(axis: int | None = None) -> np.intp | NDArray[np.intp]
¶
Return indices of minimum values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
axis
|
int | None
|
Axis along which to find minimum. If None, returns index into flattened array. |
None
|
Returns:
| Type | Description |
|---|---|
intp | NDArray[intp]
|
Index or array of indices (dimensionless integers). |
argmax(axis: int | None = None) -> np.intp | NDArray[np.intp]
¶
Return indices of maximum values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
axis
|
int | None
|
Axis along which to find maximum. If None, returns index into flattened array. |
None
|
Returns:
| Type | Description |
|---|---|
intp | NDArray[intp]
|
Index or array of indices (dimensionless integers). |
reshape(shape: tuple[int, ...] | list[int]) -> DimArray
¶
Return a reshaped array with the same unit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
shape
|
tuple[int, ...] | list[int]
|
New shape. One dimension may be -1, which is inferred. |
required |
Returns:
| Type | Description |
|---|---|
DimArray
|
Reshaped DimArray with same unit and reshaped uncertainty. |
transpose(axes: tuple[int, ...] | list[int] | None = None) -> DimArray
¶
Permute the dimensions of the array.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
axes
|
tuple[int, ...] | list[int] | None
|
Permutation of dimensions. If None, reverses dimensions. |
None
|
Returns:
| Type | Description |
|---|---|
DimArray
|
Transposed DimArray with same unit. |
flatten() -> DimArray
¶
Return a 1D flattened copy of the array.
Returns:
| Type | Description |
|---|---|
DimArray
|
Flattened DimArray with same unit. |
sqrt() -> DimArray
¶
Square root (dimension exponents halve).