Linear Algebra¶

The following functions can be used for computing linear algebra operations with NDArray.

`matmul`(x1, x2, **kwargs)	Computes the matrix product between two Blosc2 NDArrays.
`tensordot`(x1, x2[, axes])	Returns a tensor contraction of x1 and x2 over specific axes.
`vecdot`(x1, x2[, axis])	Computes the (vector) dot product of two arrays.
`permute_dims`(arr[, axes])	Permutes the axes (dimensions) of an array.
`transpose`(x, **kwargs)	Returns a Blosc2 blosc2.NDArray with axes transposed.
`matrix_transpose`(arr, **kwargs)	Transposes a matrix (or a stack of matrices).
`diagonal`(x[, offset])	Returns the specified diagonals of a matrix (or a stack of matrices) x.
`outer`(x1, x2, **kwargs)	Returns the outer product of two vectors x1 and x2.

blosc2.linalg.matmul(x1: NDArray | ndarray, x2: NDArray, **kwargs: Any) → NDArray[source]¶

Computes the matrix product between two Blosc2 NDArrays.

Parameters:

x1¶ (NDArray | np.ndarray) – The first input array.
x2¶ (NDArray | np.ndarray) – The second input array.
kwargs¶ (Any, optional) – Keyword arguments that are supported by the empty() constructor.

Returns:

out – The matrix product of the inputs. This is a scalar only when both x1, x2 are 1-d vectors.

Return type:

NDArray

Raises:

ValueError –

If the last dimension of x1 is not the same size as the second-to-last dimension of x2.

If a scalar value is passed in.

References

numpy.matmul

Examples

For 2-D arrays it is the matrix product:

>>> import numpy as np
>>> import blosc2
>>> a = np.array([[1, 2],
...               [3, 4]])
>>> nd_a = blosc2.asarray(a)
>>> b = np.array([[2, 3],
...               [2, 1]])
>>> nd_b = blosc2.asarray(b)
>>> blosc2.matmul(nd_a, nd_b)
array([[ 6,  5],
       [14, 13]])

For 2-D mixed with 1-D, the result is the usual.

>>> a = np.array([[1, 3],
...               [0, 1]])
>>> nd_a = blosc2.asarray(a)
>>> v = np.array([1, 2])
>>> nd_v = blosc2.asarray(v)
>>> blosc2.matmul(nd_a, nd_v)
array([7, 2])
>>> blosc2.matmul(nd_v, nd_a)
array([1, 5])

blosc2.linalg.tensordot(x1: blosc2.NDArray, x2: blosc2.NDArray, axes: int | tuple[Sequence[int], Sequence[int]] = 2, **kwargs: Any) → blosc2.NDArray[source]¶

Returns a tensor contraction of x1 and x2 over specific axes. The tensordot function corresponds to the generalized matrix product. Note: Neither argument is complex-conjugated or transposed. If conjugation and/or transposition is desired, these operations should be explicitly performed prior to computing the generalized matrix product.

Parameters:

x1¶ (blosc2.NDArray) – First input array. Should have a numeric data type.
x2¶ (blosc2.NDArray) – Second input array. Should have a numeric data type. Corresponding contracted axes of x1 and x2 must be equal.
axes¶ (int | tuple[Sequence[int], Sequence[int]]) –
Number of axes (dimensions) to contract or explicit sequences of axis (dimension) indices for x1 and x2, respectively.
- If axes is an int equal to N, then contraction is performed over the last N axes of x1 and the first N axes of x2 in order. The size of each corresponding axis (dimension) must match. Must be nonnegative.
- If N equals 0, the result is the tensor (outer) product.
- If N equals 1, the result is the tensor dot product.
- If N equals 2, the result is the tensor double contraction (default).
- If axes is a tuple of two sequences (x1_axes, x2_axes), the first sequence applies to x1 and the second sequence to x2.
Both sequences must have the same length. Each axis (dimension) x1_axes[i] for x1 must have the same size as the respective axis (dimension) x2_axes[i] for x2. Each index referred to in a sequence must be unique. If x1 has rank (i.e, number of dimensions) N, a valid x1 axis must reside on the half-open interval [-N, N). If x2 has rank M, a valid x2 axis must reside on the half-open interval [-M, M).
kwargs¶ (Any, optional) – Keyword arguments that are supported by the empty() constructor.

Returns:

out – An array containing the tensor contraction whose shape consists of the non-contracted axes (dimensions) of the first array x1, followed by the non-contracted axes (dimensions) of the second array x2.

Return type:

blosc2.NDArray

blosc2.linalg.vecdot(x1: NDArray, x2: NDArray, axis: int = -1, **kwargs) → NDArray[source]¶

Computes the (vector) dot product of two arrays. Complex conjugates x1.

Parameters:

x1¶ (blosc2.NDArray) – First input array. Must have floating-point data type.
x2¶ (blosc2.NDArray) – Second input array. Must be compatible with x1 for all non-contracted axes (via broadcasting). The size of the axis over which to compute the dot product must be the same size as the respective axis in x1. Must have a floating-point data type.
axis¶ (int) – The axis (dimension) of x1 and x2 containing the vectors for which to compute the dot product. Should be an integer on the interval [-N, -1], where N is min(x1.ndim, x2.ndim). Default: -1.

Returns:

out – If x1 and x2 are both one-dimensional arrays, a zero-dimensional containing the dot product; otherwise, a non-zero-dimensional array containing the dot products and having rank N-1, where N is the rank (number of dimensions) of the shape determined according to broadcasting along the non-contracted axes.

Return type:

blosc2.NDArray

blosc2.linalg.permute_dims(arr: NDArray | ndarray, axes: tuple[int] | list[int] | None = None, **kwargs: Any) → NDArray[source]¶

Permutes the axes (dimensions) of an array.

Parameters:

arr¶ (blosc2.NDArray | np.ndarray) – The input array.
axes¶ (tuple[int], list[int], optional) – The desired permutation of axes. If None, the axes are reversed by default. If specified, axes must be a tuple or list representing a permutation of [0, 1, ..., N-1], where N is the number of dimensions of the input array. Negative indices are also supported. The i-th axis of the result will correspond to the axis numbered axes[i] of the input.
kwargs¶ (Any, optional) – Keyword arguments that are supported by the empty() constructor.

Returns:

out – A Blosc2 blosc2.NDArray with axes transposed.

Return type:

blosc2.NDArray

Raises:

ValueError – If axes is not a valid permutation of the dimensions of arr.

References

numpy.transpose

permute_dims

Examples

For 2-D arrays it is the matrix transposition as usual:

>>> import blosc2
>>> a = blosc2.arange(1, 10).reshape((3, 3))
>>> a[:]
array([[1, 2, 3],
       [4, 5, 6],
       [7, 8, 9]])
>>> at = blosc2.permute_dims(a)
>>> at[:]
array([[1, 4, 7],
       [2, 5, 8],
       [3, 6, 9]])

For 3-D arrays:

>>> import blosc2
>>> a = blosc2.arange(1, 25).reshape((2, 3, 4))
>>> a[:]
array([[[ 1,  2,  3,  4],
        [ 5,  6,  7,  8],
        [ 9, 10, 11, 12]],
       [[13, 14, 15, 16],
        [17, 18, 19, 20],
        [21, 22, 23, 24]]])

>>> at = blosc2.permute_dims(a, axes=(1, 0, 2))
>>> at[:]
array([[[ 1,  2,  3,  4],
        [13, 14, 15, 16]],
       [[ 5,  6,  7,  8],
        [17, 18, 19, 20]],
       [[ 9, 10, 11, 12],
        [21, 22, 23, 24]]])

blosc2.linalg.transpose(x, **kwargs: Any) → NDArray[source]¶

Returns a Blosc2 blosc2.NDArray with axes transposed.

Only 2D arrays are supported for now. Other dimensions raise an error.

Parameters:

x¶ (blosc2.NDArray) – The input array.
kwargs¶ (Any, optional) – Keyword arguments that are supported by the empty() constructor.

Returns:

out – The Blosc2 blosc2.NDArray with axes transposed.

Return type:

blosc2.NDArray

References

numpy.transpose

blosc2.linalg.matrix_transpose(arr: NDArray | ndarray, **kwargs: Any) → NDArray[source]¶

Transposes a matrix (or a stack of matrices).

Parameters:: arr¶ (blosc2.NDArray | np.ndarray) – The input blosc2.NDArray having shape (..., M, N) and whose innermost two dimensions form MxN matrices.
Returns:: out – A new blosc2.NDArray containing the transpose for each matrix and having shape (..., N, M).
Return type:: blosc2.NDArray

blosc2.linalg.diagonal(x: blosc2.blosc2.NDArray, offset: int = 0) → blosc2.blosc2.NDArray[source]¶

Returns the specified diagonals of a matrix (or a stack of matrices) x.

Parameters:

x¶ (blosc2.NDArray) – Input array having shape (…, M, N) and whose innermost two dimensions form MxN matrices.
offset¶ (int) –
Offset specifying the off-diagonal relative to the main diagonal.
- offset = 0: the main diagonal.
- offset > 0: off-diagonal above the main diagonal.
- offset < 0: off-diagonal below the main diagonal.
Default: 0.

Returns:

out (blosc2.NDArray) – An array containing the diagonals and whose shape is determined by removing the last two dimensions and appending a dimension equal to the size of the resulting diagonals.
Reference (https://data-apis.org/array-api/latest/extensions/generated/array_api.linalg.diag.html#diag)

blosc2.linalg.outer(x1: blosc2.blosc2.NDArray, x2: blosc2.blosc2.NDArray, **kwargs: Any) → blosc2.blosc2.NDArray[source]¶

Returns the outer product of two vectors x1 and x2.

Parameters:

x1¶ (blosc2.NDArray) – First one-dimensional input array of size N. Must have a numeric data type.
x2¶ (blosc2.NDArray) – Second one-dimensional input array of size M. Must have a numeric data type.
kwargs¶ (Any, optional) – Keyword arguments that are supported by the empty() constructor.

Returns:

out – A two-dimensional array containing the outer product and whose shape is (N, M).

Return type:

blosc2.NDArray