add¶

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

Calculates the sum for each elementx1_i of the input arrayx1 with the respective elementx2_i of the input arrayx2.

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 withx1 (seeBroadcasting). 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 byType Promotion Rules.

Notes

• At least one ofx1 orx2 must be an array.

Special cases

For real-valued floating-point operands,

• If eitherx1_i orx2_i isNaN, the result isNaN.

• Ifx1_i is+infinity andx2_i is-infinity, the result isNaN.

• Ifx1_i is-infinity andx2_i is+infinity, the result isNaN.

• Ifx1_i is+infinity andx2_i is+infinity, the result is+infinity.

• Ifx1_i is-infinity andx2_i is-infinity, the result is-infinity.

• Ifx1_i is+infinity andx2_i is a finite number, the result is+infinity.

• Ifx1_i is-infinity andx2_i is a finite number, the result is-infinity.

• Ifx1_i is a finite number andx2_i is+infinity, the result is+infinity.

• Ifx1_i is a finite number andx2_i is-infinity, the result is-infinity.

• Ifx1_i is-0 andx2_i is-0, the result is-0.

• Ifx1_i is-0 andx2_i is+0, the result is+0.

• Ifx1_i is+0 andx2_i is-0, the result is+0.

• Ifx1_i is+0 andx2_i is+0, the result is+0.

• Ifx1_i is either+0 or-0 andx2_i is a nonzero finite number, the result isx2_i.

• Ifx1_i is a nonzero finite number andx2_i is either+0 or-0, the result isx1_i.

• Ifx1_i is a nonzero finite number andx2_i is-x1_i, the result is+0.

• In the remaining cases, when neitherinfinity,+0,-0, nor aNaN 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 aninfinity 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 componentsa andc and imaginary componentsb andd,

	c	dj	c + dj
a	a + c	a + dj	(a+c) + dj
bj	c + bj	(b+d)j	c + (b+d)j
a + bj	(a+c) + bj	a + (b+d)j	(a+c) + (b+d)j

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, leta=real(x1_i),b=imag(x1_i),c=real(x2_i),d=imag(x2_i), and

• Ifa is-0 andc is-0, the real component of the result is-0.

• Similarly, ifb is+0 andd is-0, the imaginary component of the result is+0.

Hence, ifz1=a+bj=-0+0j andz2=c+dj=-0-0j, the result ofz1+z2 is-0+0j.

Changed in version 2022.12:Added complex data type support.

Changed in version 2024.12:Added scalar argument support.