tensordot

tensordot(x1: array, x2: array, /, *, axes: int | Tuple[Sequence[int], Sequence[int]] = 2) → array

Returns a tensor contraction of x1 and x2 over specific axes.

Parameters:

  • x1 (array) – first input array. Should have a numeric data type.

  • x2 (array) – second input array. Should have a numeric data type. Corresponding contracted axes of x1 and x2 must be equal.

  • axes (Union[int, Tuple[Sequence[int], Sequence[int]]]) –

    number of axes to contract or explicit sequences of axis indices for x1 and x2, respectively.

    If axes is an int equal to N, then contraction must be performed over the last N axes of x1 and the first N axes of x2 in order. The size of each corresponding axis must match. An integer axes value must be nonnegative.

    • If N equals 0, the result must be the tensor (outer) product.

    • If N equals 1, the result must be the tensor dot product.

    • If N equals 2, the result must be the tensor double contraction (default).

    If axes is a tuple of two sequences (x1_axes, x2_axes), the first sequence must apply to x1 and the second sequence must apply to x2. Both sequences must have the same length. Each axis x1_axes[i] for x1 must have the same size as the respective axis x2_axes[i] for x2. Each index referred to in a sequence must be unique. A valid axis must be an integer on the interval [-S, S), where S is the number of axes in respective array. Hence, if x1 has N axes, a valid x1 axes must be an integer on the interval [-N, N). If x2 has M axes, a valid x2 axes must be an integer on the interval [-M, M). If an axis is specified as a negative integer, the function must determine the axis along which to perform the operation by counting backward from the last axis (where -1 refers to the last axis). If provided an invalid axis, the function must raise an exception.

Returns:

out (array) – an array containing the tensor contraction. The returned array must have a shape which consists of the non-contracted axes of the first array x1, followed by the non-contracted axes of the second array x2. The returned array must have a data type determined by Type Promotion Rules.

Notes

  • The tensordot function corresponds to the generalized matrix product.

  • Contracted axes must not be broadcasted.

  • If either x1 or x2 has a complex floating-point data type, the function must not complex-conjugate or transpose either argument. If conjugation and/or transposition is desired, a user can explicitly perform these operations prior to computing the generalized matrix product.

Changed in version 2022.12: Added complex data type support.

Changed in version 2023.12: Allow negative axes.