Skip to content

Functions

Module-level functions for array operations.

Array Manipulation

concatenate

Join arrays along an existing axis.

from dimtensor import DimArray, units, concatenate

a = DimArray([1, 2], units.m)
b = DimArray([3, 4], units.m)
result = concatenate([a, b])  # [1 2 3 4] m

All arrays must have the same dimension. Arrays with compatible units are converted to the first array's unit.

concatenate(arrays: Sequence[DimArray], axis: int = 0) -> DimArray

Join a sequence of DimArrays along an existing axis.

All arrays must have the same unit dimension. Arrays with compatible units (e.g., km and m) will be converted to the first array's unit.

If any arrays have uncertainty, the uncertainties are concatenated. Arrays without uncertainty are treated as having zero uncertainty.

Parameters:

Name Type Description Default
arrays Sequence[DimArray]

Sequence of DimArrays to concatenate.

 required
axis int

The axis along which to concatenate (default: 0).

 0

Returns:

Type Description
DimArray

Concatenated DimArray with the same unit as the first input array.

Raises:

Type Description
DimensionError

If arrays have incompatible dimensions.
ValueError

If arrays sequence is empty.

Examples:

>>> a = DimArray([1.0, 2.0], units.m)
>>> b = DimArray([3.0, 4.0], units.m)
>>> concatenate([a, b])
DimArray([1. 2. 3. 4.], unit='m')

stack

Stack arrays along a new axis.

from dimtensor import DimArray, units, stack

a = DimArray([1, 2], units.m)
b = DimArray([3, 4], units.m)
result = stack([a, b])  # [[1 2] [3 4]] m

stack(arrays: Sequence[DimArray], axis: int = 0) -> DimArray

Stack a sequence of DimArrays along a new axis.

All arrays must have the same unit dimension. Arrays with compatible units (e.g., km and m) will be converted to the first array's unit.

If any arrays have uncertainty, the uncertainties are stacked. Arrays without uncertainty are treated as having zero uncertainty.

Parameters:

Name Type Description Default
arrays Sequence[DimArray]

Sequence of DimArrays to stack.

 required
axis int

The axis along which to stack (default: 0).

 0

Returns:

Type Description
DimArray

Stacked DimArray with the same unit as the first input array.

Raises:

Type Description
DimensionError

If arrays have incompatible dimensions.
ValueError

If arrays sequence is empty.

Examples:

>>> a = DimArray([1.0, 2.0], units.m)
>>> b = DimArray([3.0, 4.0], units.m)
>>> stack([a, b])
DimArray([[1. 2.] [3. 4.]], unit='m')

split

Split an array into sub-arrays.

from dimtensor import DimArray, units, split

arr = DimArray([1, 2, 3, 4], units.m)
parts = split(arr, 2)  # [[1 2] m, [3 4] m]

split(array: DimArray, indices_or_sections: int | Sequence[int], axis: int = 0) -> list[DimArray]

Split a DimArray into sub-arrays.

Parameters:

Name Type Description Default
array DimArray

The DimArray to split.

 required
indices_or_sections int | Sequence[int]

If an integer N, split into N equal parts. If a sequence of integers, split at those indices.

 required
axis int

The axis along which to split (default: 0).

 0

Returns:

Type Description
list[DimArray]

List of DimArrays, all with the same unit and uncertainty as the input.

Examples:

>>> arr = DimArray([1.0, 2.0, 3.0, 4.0], units.m)
>>> parts = split(arr, 2)
>>> len(parts)
2

Linear Algebra

dot

Dot product of two arrays. Dimensions multiply.

from dimtensor import DimArray, units, dot

# Work = Force . Displacement
force = DimArray([10, 0, 0], units.N)
displacement = DimArray([5, 0, 0], units.m)
work = dot(force, displacement)  # [50] J

dot(a: DimArray, b: DimArray) -> DimArray

Dot product of two DimArrays.

Dimensions multiply: if a has dimension D1 and b has dimension D2, the result has dimension D1 * D2.

Note: Uncertainty propagation through dot product is complex and not implemented. The result will have no uncertainty information.

Parameters:

Name Type Description Default
a DimArray

First array.

 required
b DimArray

Second array.

 required

Returns:

Type Description
DimArray

Dot product with multiplied dimensions.

Examples:

>>> length = DimArray([1.0, 2.0, 3.0], units.m)
>>> force = DimArray([4.0, 5.0, 6.0], units.N)
>>> work = dot(length, force)  # Result has dimension of energy (J)

matmul

Matrix multiplication. Dimensions multiply.

from dimtensor import DimArray, units, matmul

A = DimArray([[1, 2], [3, 4]], units.m)
B = DimArray([[5, 6], [7, 8]], units.s)
C = matmul(A, B)  # Result has unit m*s

matmul(a: DimArray, b: DimArray) -> DimArray

Matrix multiplication of two DimArrays.

Dimensions multiply: if a has dimension D1 and b has dimension D2, the result has dimension D1 * D2.

Note: Uncertainty propagation through matrix multiplication is complex and not implemented. The result will have no uncertainty information.

Parameters:

Name Type Description Default
a DimArray

First array (must be at least 1D).

 required
b DimArray

Second array (must be at least 1D).

 required

Returns:

Type Description
DimArray

Matrix product with multiplied dimensions.

Examples:

>>> A = DimArray([[1, 2], [3, 4]], units.m)
>>> B = DimArray([[5, 6], [7, 8]], units.s)
>>> C = matmul(A, B)  # Result has dimension m*s

norm

Compute the norm of an array. Preserves the original unit.

from dimtensor import DimArray, units, norm

velocity = DimArray([3, 4], units.m / units.s)
speed = norm(velocity)  # [5] m/s

norm(array: DimArray, ord: float | None = None, axis: int | None = None, keepdims: bool = False) -> DimArray

Compute the norm of a DimArray.

The result preserves the original unit (norm of meters is meters).

Note: Uncertainty propagation through norm is complex and not implemented. The result will have no uncertainty information.

Parameters:

Name Type Description Default
array DimArray

Input array.

 required
ord float | None

Order of the norm (see numpy.linalg.norm). None = 2-norm for vectors, Frobenius for matrices. Other values: 1, 2, inf, -inf, etc.

 None
axis int | None

Axis along which to compute the norm. If None, computes norm of flattened array.

 None
keepdims bool

If True, the reduced axes are kept with size 1.

 False

Returns:

Type Description
DimArray

Norm with the same unit as the input array.

Examples:

>>> v = DimArray([3.0, 4.0], units.m)
>>> norm(v)  # 5.0 m
DimArray([5.], unit='m')

Exceptions

DimensionError

Raised when dimensions are incompatible for an operation.

from dimtensor import DimArray, DimensionError, units

try:
    a = DimArray([1], units.m)
    b = DimArray([1], units.s)
    a + b  # Cannot add m to s
except DimensionError as e:
    print(e)  # "Cannot add quantities with dimensions L and T"

DimensionError

Bases: DimTensorError

Raised when dimensions are incompatible for an operation.

incompatible(left: Dimension, right: Dimension, operation: str) -> DimensionError classmethod

Create an error for incompatible dimensions.

UnitConversionError

Raised when unit conversion is not possible.

from dimtensor import DimArray, UnitConversionError, units

try:
    distance = DimArray([1], units.m)
    distance.to(units.s)  # Cannot convert m to s
except UnitConversionError as e:
    print(e)

UnitConversionError

Bases: DimTensorError

Raised when unit conversion is not possible.

incompatible(from_unit: str, to_unit: str) -> UnitConversionError classmethod

Create an error for incompatible unit conversion.