Vector dot products
Compute a scalar similarity or inner product from two vectors.
PyTorch · Function
torch.matmul
torch.matmul computes tensor products whose behavior depends on operand dimensions, covering dot, matrix, vector, and batched matrix multiplication. Higher-rank batch dimensions broadcast when compatible.
How it works
torch.matmul selects the product according to operand dimensionality: dot product for two vectors, matrix products for two-dimensional tensors, vector-matrix or matrix-vector products for mixed ranks, and batched matrix multiplication for higher-rank operands. Higher-rank batch dimensions broadcast, while the final two dimensions perform the matrix product.
Syntax
torch.matmul(input, other, *, out=None) → TensorParameters
| Name | Type | Description |
|---|---|---|
input | Tensor | First tensor to multiply. |
other | Tensor | Second tensor to multiply. |
out | Tensor, optional | Optional destination tensor. |
Returns
Tensor
Key points
- torch.matmul computes a product between two tensors.
- Two one-dimensional inputs produce a scalar dot product.
- Two two-dimensional inputs use ordinary matrix-matrix multiplication.
- For vector–matrix multiplication, PyTorch temporarily treats the vector as having a leading singleton dimension and removes it afterward.
- A matrix followed by a vector returns a matrix-vector product.
- Operands involving a rank greater than two use batched matrix multiplication when both inputs have at least one dimension.
Common mistakes
- For batched operands, all batch dimensions must be broadcast-compatible; only the final two dimensions are treated as matrix dimensions.
- Sparse layouts are supported, but sparse and dense combinations or particular sparse formats may impose additional operator constraints.
- On supported hardware, TensorFloat32 execution may affect numerical precision.
Example: Vector and batched matrix products
import torch
vector = torch.tensor([1.0, 2.0, 3.0])
matrix = torch.tensor([[1.0, 0.0], [0.0, 1.0], [1.0, 1.0]])
print(torch.matmul(vector, matrix)) # tensor([4., 5.])
batch = torch.randn(2, 3, 4)
weights = torch.randn(4, 5)
print(torch.matmul(batch, weights).shape) # torch.Size([2, 3, 5])Multiplies a vector by a matrix and then applies a matrix to the last two dimensions of a batched tensor.
When to use it
Matrix products
Multiply conventional two-dimensional tensors in neural-network or linear-algebra code.
Batched linear algebra
Apply shared weights across leading batch dimensions.
Interview questions
QHow does torch.matmul differ across common tensor dimensionalities?
The result depends on the operands' ranks. Two vectors produce a scalar dot product, two matrices produce a matrix product, and a vector paired with a matrix or matrix paired with a vector produces the corresponding one-dimensional product.
Follow-up: What happens with higher-rank operands? Their leading batch dimensions are broadcast, and multiplication is performed over the final two dimensions.
QHow does torch.matmul handle batched matrix multiplication?
When at least one operand has more than two dimensions and both operands have at least one dimension, torch.matmul performs batched matrix multiplication. The leading dimensions are batch dimensions and must be broadcastable.
Follow-up: How is a one-dimensional operand handled in a batched product? A singleton dimension is temporarily added so it can participate in matrix multiplication, then removed from the result.
QWhat arguments does torch.matmul accept, and what does it return?
The function accepts input, other, and an optional out tensor. It returns a Tensor containing the selected dot, matrix, vector, or batched matrix product.
Follow-up: Which related operation should be considered when broadcasting is not wanted? torch.mm performs matrix multiplication but does not broadcast, whereas torch.matmul supports broadcasting matrix products.
Related
torch.mmtorch.bmmtorch.linalg