add¶
- add(x1: array, x2: array, /) array ¶
Calculates the sum for each element
x1_i
of the input arrayx1
with the respective elementx2_i
of the input arrayx2
.- Parameters:
x1 (array) – first input array. Should have a numeric data type.
x2 (array) – 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
Special cases
For real-valued floating-point operands,
If either
x1_i
orx2_i
isNaN
, the result isNaN
.If
x1_i
is+infinity
andx2_i
is-infinity
, the result isNaN
.If
x1_i
is-infinity
andx2_i
is+infinity
, the result isNaN
.If
x1_i
is+infinity
andx2_i
is+infinity
, the result is+infinity
.If
x1_i
is-infinity
andx2_i
is-infinity
, the result is-infinity
.If
x1_i
is+infinity
andx2_i
is a finite number, the result is+infinity
.If
x1_i
is-infinity
andx2_i
is a finite number, the result is-infinity
.If
x1_i
is a finite number andx2_i
is+infinity
, the result is+infinity
.If
x1_i
is a finite number andx2_i
is-infinity
, the result is-infinity
.If
x1_i
is-0
andx2_i
is-0
, the result is-0
.If
x1_i
is-0
andx2_i
is+0
, the result is+0
.If
x1_i
is+0
andx2_i
is-0
, the result is+0
.If
x1_i
is+0
andx2_i
is+0
, the result is+0
.If
x1_i
is either+0
or-0
andx2_i
is a nonzero finite number, the result isx2_i
.If
x1_i
is a nonzero finite number andx2_i
is either+0
or-0
, the result isx1_i
.If
x1_i
is a nonzero finite number andx2_i
is-x1_i
, the result is+0
.In the remaining cases, when neither
infinity
,+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 components
a
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, let
a = real(x1_i)
,b = imag(x1_i)
,c = real(x2_i)
,d = imag(x2_i)
, andIf
a
is-0
andc
is-0
, the real component of the result is-0
.Similarly, if
b
is+0
andd
is-0
, the imaginary component of the result is+0
.
Hence, if
z1 = 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.