NumPy arctan2() – Inverse Tangent of Ratio of Two Numbers

NumPy arctan2()

The numpy.arctan2() function computes the element-wise arc tangent of x1/x2 while correctly determining the quadrant of the angle. The result is given in radians within the range [-π, π].

Syntax

numpy.arctan2(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True)

Parameters

Parameter	Type	Description
x1	array_like, real-valued	Y-coordinates of the points.
x2	array_like, real-valued	X-coordinates of the points. If x1.shape != x2.shape, they must be broadcastable to a common shape.
out	ndarray, None, or tuple of ndarray and None, optional	Optional output array where the result is stored. If None, a new array is created.
where	array_like, optional	Boolean mask specifying where to compute values. Elements where where=False retain their original value.
casting	str, optional	Defines the casting behavior when computing arctan2.
order	str, optional	Memory layout order of the output array.
dtype	data-type, optional	Defines the data type of the output array.
subok	bool, optional	Determines if subclasses of ndarray are preserved in the output.

Return Value

Returns an array of angles in radians within the range [-π, π]. If both x1 and x2 are scalars, the output is a scalar.

---

Examples

1. Computing the Angle for a Single Point

Here, we calculate the angle formed by a point (x2, x1) relative to the positive x-axis.

import numpy as np

# Define x and y coordinates
x1 = 1  # y-coordinate
x2 = 1  # x-coordinate

# Compute the angle in radians
angle = np.arctan2(x1, x2)

# Print the result
print("Angle in radians:", angle)
print("Angle in degrees:", np.degrees(angle))

Output:

Angle in radians: 0.7853981633974483
Angle in degrees: 45.0

2. Computing Angles for an Array of Points

We calculate the angles for multiple points.

import numpy as np

# Define arrays of x and y coordinates
x1 = np.array([1, -1, 1, -1])  # y-coordinates
x2 = np.array([1, 1, -1, -1])  # x-coordinates

# Compute the angles in radians
angles = np.arctan2(x1, x2)

# Convert radians to degrees for better understanding
angles_degrees = np.degrees(angles)

# Print the results
print("Angles in radians:", angles)
print("Angles in degrees:", angles_degrees)

Output:

Angles in radians: [ 0.78539816 -0.78539816  2.35619449 -2.35619449]
Angles in degrees: [  45.  -45.  135. -135.]

3. Using the out Parameter

Storing results in a pre-allocated output array.

import numpy as np

# Define input values
x1 = np.array([1, 0, -1, 0])
x2 = np.array([0, 1, 0, -1])

# Pre-allocate an output array
output_array = np.ndarray(x1.shape)

# Compute angles and store them in the output array
np.arctan2(x1, x2, out=output_array)

# Print the results
print("Stored angles in radians:", output_array)

Output:

Stored angles in radians: [ 1.57079633  0.         -1.57079633  3.14159265]

4. Using the where Parameter

Computing angles only for selected elements using a condition.

import numpy as np

# Define input values
x1 = np.array([1, 0, -1, 0])
x2 = np.array([1, 1, 0, -1])

# Define a mask (compute angles only where mask is True)
mask = np.array([True, False, True, False])

# Compute angles where mask is True
result = np.arctan2(x1, x2, where=mask)

# Print the results
print("Computed angles with mask:", result)

Output:

Computed angles with mask: [ 0.78539816  0.         -1.57079633  0.        ]

Angles are computed only where mask=True.