Skip to content

Add complex number support to atan #523

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 5, 2022
Merged

Add complex number support to atan #523

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 25 additions & 5 deletions spec/API_specification/array_api/elementwise_functions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,28 +167,48 @@ def asinh(x: array, /) -> array:
"""

def atan(x: array, /) -> array:
"""
Calculates an implementation-dependent approximation of the principal value of the inverse tangent, having domain ``[-infinity, +infinity]`` and codomain ``[-π/2, +π/2]``, for each element ``x_i`` of the input array ``x``. Each element-wise result is expressed in radians.
r"""
Calculates an implementation-dependent approximation of the principal value of the inverse tangent for each element ``x_i`` of the input array ``x``.

Each element-wise result is expressed in radians.

**Special cases**

For floating-point operands,
For real-valued floating-point operands,

- If ``x_i`` is ``NaN``, the result is ``NaN``.
- If ``x_i`` is ``+0``, the result is ``+0``.
- If ``x_i`` is ``-0``, the result is ``-0``.
- If ``x_i`` is ``+infinity``, the result is an implementation-dependent approximation to ``+π/2``.
- If ``x_i`` is ``-infinity``, the result is an implementation-dependent approximation to ``-π/2``.

For complex floating-point operands, special cases must be handled as if the operation is implemented as ``-1j * atanh(x*1j)``.

.. note::
The principal value of the inverse tangent of a complex number :math:`z` is

.. math::
\operatorname{atan}(z) = -\frac{\ln(1 - zj) - \ln(1 + zj)}{2}j

.. note::
For complex floating-point operands, ``atan(conj(x))`` must equal ``conj(atan(x))``.

.. note::
The inverse tangent (or arc tangent) is a multi-valued function and requires a branch on the complex plane. By convention, a branch cut is placed at the line segments :math:`(-\infty j, -j)` and :math:`(+j, \infty j)` of the imaginary axis.

Accordingly, for complex arguments, the function returns the inverse tangent in the range of a strip unbounded along the imaginary axis and in the interval :math:`[-\pi/2, +\pi/2]` along the real axis.

*Note: branch cuts have provisional status* (see :ref:`branch-cuts`).

Parameters
----------
x: array
input array. Should have a real-valued floating-point data type.
input array. Should have a floating-point data type.

Returns
-------
out: array
an array containing the inverse tangent of each element in ``x``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`.
an array containing the inverse tangent of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`.
"""

def atan2(x1: array, x2: array, /) -> array:
Expand Down