add — Python array API standard 2024.12 documentation (original) (raw)

add(x1: array | int | float | complex, x2: array | int | float | complex, /) → array¶

Calculates the sum for each element x1_i of the input array x1 with the respective element x2_i of the input array x2.

Parameters:

• x1 (Union [ array , int , float , complex ]) – first input array. Should have a numeric data type.
• x2 (Union [ array , int , float , complex ]) – second input array. Must be compatible with x1 (see Broadcasting). Should have a numeric data type.

Returns:

out (array) – an array containing the element-wise sums. The returned array must have a data type determined by Type Promotion Rules.

Notes

• At least one of x1 or x2 must be an array.

Special cases

For real-valued floating-point operands,

• If either x1_i or x2_i is NaN, the result is NaN.
• If x1_i is +infinity and x2_i is -infinity, the result is NaN.
• If x1_i is -infinity and x2_i is +infinity, the result is NaN.
• If x1_i is +infinity and x2_i is +infinity, the result is +infinity.
• If x1_i is -infinity and x2_i is -infinity, the result is -infinity.
• If x1_i is +infinity and x2_i is a finite number, the result is +infinity.
• If x1_i is -infinity and x2_i is a finite number, the result is -infinity.
• If x1_i is a finite number and x2_i is +infinity, the result is +infinity.
• If x1_i is a finite number and x2_i is -infinity, the result is -infinity.
• If x1_i is -0 and x2_i is -0, the result is -0.
• If x1_i is -0 and x2_i is +0, the result is +0.
• If x1_i is +0 and x2_i is -0, the result is +0.
• If x1_i is +0 and x2_i is +0, the result is +0.
• If x1_i is either +0 or -0 and x2_i is a nonzero finite number, the result is x2_i.
• If x1_i is a nonzero finite number and x2_i is either +0 or -0, the result is x1_i.
• If x1_i is a nonzero finite number and x2_i is -x1_i, the result is +0.
• In the remaining cases, when neither infinity, +0, -0, nor a NaN is involved, and the operands have the same mathematical sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an infinity of appropriate mathematical sign.

Note

Floating-point addition is a commutative operation, but not always associative.

For complex floating-point operands, addition is defined according to the following table. For real components a and c and imaginary components b and d,

For complex floating-point operands, real-valued floating-point special cases must independently apply to the real and imaginary component operations involving real numbers as described in the above table. For example, let a = real(x1_i), b = imag(x1_i), c = real(x2_i), d = imag(x2_i), and

• If a is -0 and c is -0, the real component of the result is -0.
• Similarly, if b is +0 and d is -0, the imaginary component of the result is +0.

Hence, if z1 = a + bj = -0 + 0j and z2 = c + dj = -0 - 0j, the result of z1 + z2 is -0 + 0j.

Changed in version 2022.12: Added complex data type support.

Changed in version 2024.12: Added scalar argument support.