hypot¶
- hypot(x1: array, x2: array, /) array ¶
Computes the square root of the sum of squares for each element
x1_i
of the input arrayx1
with the respective elementx2_i
of the input arrayx2
.Note
The value computed by this function may be interpreted as the length of the hypotenuse of a right-angled triangle with sides of length
x1_i
andx2_i
, the distance of a point(x1_i, x2_i)
from the origin(0, 0)
, or the magnitude of a complex numberx1_i + x2_i * 1j
.- Parameters:
x1 (array) – first input array. Should have a real-valued floating-point data type.
x2 (array) – second input array. Must be compatible with
x1
(see Broadcasting). Should have a real-valued floating-point data type.
- Returns:
out (array) – an array containing the element-wise results. The returned array must have a real-valued floating-point data type determined by Type Promotion Rules.
Notes
The purpose of this function is to avoid underflow and overflow during intermediate stages of computation. Accordingly, conforming implementations should not use naive implementations.
Special Cases
For real-valued floating-point operands,
If
x1_i
is+infinity
or-infinity
andx2_i
is any value, includingNaN
, the result is+infinity
.If
x2_i
is+infinity
or-infinity
andx1_i
is any value, includingNaN
, the result is+infinity
.If
x1_i
is either+0
or-0
, the result is equivalent toabs(x2_i)
.If
x2_i
is either+0
or-0
, the result is equivalent toabs(x1_i)
.If
x1_i
is a finite number orNaN
andx2_i
isNaN
, the result isNaN
.If
x2_i
is a finite number orNaN
andx1_i
isNaN
, the result isNaN
.Underflow may only occur when both arguments are subnormal and the correct result is also subnormal.
For real-valued floating-point operands,
hypot(x1, x2)
must equalhypot(x2, x1)
,hypot(x1, -x2)
,hypot(-x1, x2)
, andhypot(-x1, -x2)
.Note
IEEE 754-2019 requires support for subnormal (a.k.a., denormal) numbers, which are useful for supporting gradual underflow. However, hardware support for subnormal numbers is not universal, and many platforms (e.g., accelerators) and compilers support toggling denormals-are-zero (DAZ) and/or flush-to-zero (FTZ) behavior to increase performance and to guard against timing attacks.
Accordingly, conforming implementations may vary in their support for subnormal numbers.
New in version 2023.12.