derivkit.utils.tensors module#

Tensor algebra utilities.

derivkit.utils.tensors.contract_tensor_with_vector(tensor: NDArray[float64], vector: NDArray[float64], n_axes: int = 1) → NDArray[float64]#

Contracts trailing tensor axes with repeated copies of a vector.

Parameters:

  • tensor – Tensor whose trailing axes are contracted.

  • vector – One-dimensional vector of shape (d,).

  • n_axes – Number of trailing tensor axes to contract.

Returns:

Tensor with the contracted axes removed and leading tensor axes preserved. If n_axes=0, the tensor is unchanged.

Raises:

  • TypeError – If n_axes is not an integer.

  • ValueError – If vector is not one-dimensional, n_axes is invalid, or the contracted dimensions do not match the vector dimension.

derivkit.utils.tensors.contract_tensor_with_vector_batch(tensor: NDArray[float64], vectors: NDArray[float64], n_axes: int = 1) → NDArray[float64]#

Contracts trailing tensor axes independently with a batch of vectors.

Each vector in the batch is independently contracted with the same tensor along n_axes trailing axes. Leading batch dimensions are preserved.

Parameters:

  • tensor – Tensor whose trailing axes are contracted.

  • vectors – Batch of vectors of shape (..., d).

  • n_axes – Number of trailing tensor axes to contract.

Returns:

Tensor with the contracted axes removed and leading vector batch dimensions preserved. If n_axes=0, the tensor is unchanged apart from broadcasting over the batch dimensions.

Raises:

  • TypeError – If n_axes is not an integer.

  • ValueError – If vectors has fewer than two dimensions, n_axes is invalid, or the contracted dimensions do not match the vector dimension.

derivkit.utils.tensors.gaussian_fourth_moment(cov: NDArray[float64]) → NDArray[float64]#

Computes the centered fourth moment of a multivariate Gaussian.

Parameters:

cov – Gaussian covariance matrix.

Returns:

Rank-four tensor containing the centered Gaussian fourth moment.

Raises:

ValueError – If cov is not a square matrix.

derivkit.utils.tensors.symmetrize_tensor(tensor: NDArray[float64]) → NDArray[float64]#

Symmetrizes a tensor over all axes.

Parameters:

tensor – Tensor to symmetrize.

Returns:

Tensor averaged over all permutations of its axes.

Raises:

ValueError – If the tensor axes do not all have equal size.