.addcmul()

MamtaWardhani's avatar
MamtaWardhani's avatar
MamtaWardhani
Published Mar 17, 2025
Contribute to Docs

.addcmul() is a PyTorch tensor operation that performs element-wise multiplication of two tensors and then adds a third tensor to the result, optionally scaled by a value. This operation combines multiplication and addition in a single efficient function call.

The function is particularly useful in tensor operations where there is a need to perform element-wise multiplication and addition in sequence. It provides a concise way to perform these operations without creating intermediate tensors, which can help optimize memory usage in PyTorch applications.

Syntax

torch.addcmul(input, tensor1, tensor2, value=1, out=None)

Parameters:

  • input (Tensor): The tensor to be added to the result
  • tensor1 (Tensor): The first tensor to be multiplied element-wise
  • tensor2 (Tensor): The second tensor to be multiplied element-wise
  • value (Number, optional): Multiplier for the product of tensor1 and tensor2. Default value is 1
  • out (Tensor, optional): The output tensor to store the result

Return value:

Returns a new tensor containing the result of the operation, or modifies the out tensor if provided.

Example 1: Basic usage of .addcmul() with PyTorch tensors

This example demonstrates the basic functionality of .addcmul() by applying it to random tensors to show how the element-wise multiplication and addition works:

import torch


# Create input tensor and two tensors to be multiplied
input_tensor = torch.tensor([1.0, 2.0, 3.0])
tensor1 = torch.tensor([2.0, 3.0, 4.0])
tensor2 = torch.tensor([3.0, 2.0, 1.0])


# Apply addcmul operation
# Formula: result = input + value * (tensor1 * tensor2)
result = torch.addcmul(input_tensor, tensor1, tensor2)


# Display the tensors and result
print("Input tensor:", input_tensor)
print("Tensor 1:", tensor1)
print("Tensor 2:", tensor2)
print("Result of addcmul (default value=1):", result)


# Try with a different value parameter
scaled_result = torch.addcmul(input_tensor, tensor1, tensor2, value=0.5)
print("Result of addcmul with value=0.5:", scaled_result)

This example results in the following output:

Input tensor: tensor([1., 2., 3.])
Tensor 1: tensor([2., 3., 4.])
Tensor 2: tensor([3., 2., 1.])
Result of addcmul (default value=1): tensor([7., 8., 7.])
Result of addcmul with value=0.5: tensor([4., 5., 5.])

Example 2: Using .addcmul() with different scale values

This example demonstrates how .addcmul() behaves with different scale values:

import torch


# Create three simple tensors
input_tensor = torch.tensor([1.0, 2.0, 3.0])
tensor1 = torch.tensor([2.0, 3.0, 4.0])
tensor2 = torch.tensor([3.0, 2.0, 1.0])


# Apply addcmul with different scale values
result1 = torch.addcmul(input_tensor, tensor1, tensor2, value=1.0)
result2 = torch.addcmul(input_tensor, tensor1, tensor2, value=0.5)
result3 = torch.addcmul(input_tensor, tensor1, tensor2, value=2.0)


# Print results
print("Input tensor:", input_tensor)
print("Tensor 1:", tensor1)
print("Tensor 2:", tensor2)
print("\naddcmul with value=1.0:", result1)
print("addcmul with value=0.5:", result2)
print("addcmul with value=2.0:", result3)


# Show the calculations step by step
print("\nCalculation steps for first element with value=1.0:")
print(f"input[0] + value * (tensor1[0] * tensor2[0]) = {input_tensor[0]} + 1.0 * ({tensor1[0]} * {tensor2[0]}) = {result1[0]}")

This example results in the following output:

Input tensor: tensor([1., 2., 3.])
Tensor 1: tensor([2., 3., 4.])
Tensor 2: tensor([3., 2., 1.])


addcmul with value=1.0: tensor([7., 8., 7.])
addcmul with value=0.5: tensor([4., 5., 5.])
addcmul with value=2.0: tensor([13., 14., 11.])


Calculation steps for first element with value=1.0:
input[0] + value * (tensor1[0] * tensor2[0]) = 1.0 + 1.0 * (2.0 * 3.0) = 7.0

Example 3: Combining .addcmul() with in-place operations

This example shows how to use .addcmul_() (the in-place version) to modify tensors directly:

import torch


# Create tensors
x = torch.tensor([1.0, 2.0, 3.0])
y = torch.tensor([0.1, 0.2, 0.3])
z = torch.tensor([1.5, 2.5, 3.5])


print("Original x:", x)
print("y:", y)
print("z:", z)


# Use addcmul with a new tensor to store results
result = torch.addcmul(x, y, z, value=2.0)
print("\nResult of torch.addcmul(x, y, z, value=2.0):", result)
print("Original x is unchanged:", x)


# Use the in-place version addcmul_
x.addcmul_(y, z, value=2.0)
print("\nAfter x.addcmul_(y, z, value=2.0), x is now:", x)


# Verify that x now has the same values as result
print("x now equals the previous result:", torch.equal(x, result))

This example results in the following output:

Original x: tensor([1., 2., 3.])
y: tensor([0.1, 0.2, 0.3])
z: tensor([1.5, 2.5, 3.5])


Result of torch.addcmul(x, y, z, value=2.0): tensor([1.3000, 3.0000, 5.1000])
Original x is unchanged: tensor([1., 2., 3.])


After x.addcmul_(y, z, value=2.0), x is now: tensor([1.3000, 3.0000, 5.1000])
x now equals the previous result: True

To learn more about how to create, train, and test neural networks, check out this Intro to PyTorch and Neural Networks course on Codecademy.

All contributors

Contribute to Docs

Learn PyTorch on Codecademy