From 14fbbbebb3b39ffe1902a101f4708a04eb0d0a2a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sat, 26 Nov 2022 16:02:49 -0800 Subject: [PATCH 1/6] Add complex number support to `acos` --- .../array_api/elementwise_functions.py | 40 ++++++++++++++++--- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/spec/API_specification/array_api/elementwise_functions.py b/spec/API_specification/array_api/elementwise_functions.py index 78a60de9c..3aa946283 100644 --- a/spec/API_specification/array_api/elementwise_functions.py +++ b/spec/API_specification/array_api/elementwise_functions.py @@ -27,27 +27,57 @@ def abs(x: array, /) -> array: """ def acos(x: array, /) -> array: - """ - Calculates an implementation-dependent approximation of the principal value of the inverse cosine, having domain ``[-1, +1]`` and codomain ``[+0, +π]``, 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 cosine 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 greater than ``1``, the result is ``NaN``. - If ``x_i`` is less than ``-1``, the result is ``NaN``. - If ``x_i`` is ``1``, the result is ``+0``. + For complex floating-point operands, let ``a = real(x_i)``, ``b = imag(x_i)``, and + + - If ``a`` is either ``+0`` or ``-0`` and ``b`` is ``+0``, the result is ``π/2 - 0j``. + - If ``a`` is either ``+0`` or ``-0`` and ``b`` is ``NaN``, the result is ``π/2 + NaN j``. + - If ``a`` is a finite number and ``b`` is ``+infinity``, the result is ``π/2 - infinity j``. + - If ``a`` is a nonzero finite number and ``b`` is ``NaN``, the result is ``NaN + NaN j``. + - If ``a`` is ``-infinity`` and ``b`` is a positive (i.e., greater than ``0``) finite number, the result is ``π - infinity j``. + - If ``a`` is ``+infinity`` and ``b`` is a positive (i.e., greater than ``0``) finite number, the result is ``+0 - infinity j``. + - If ``a`` is ``-infinity`` and ``b`` is ``+infinity``, the result is ``3π/4 - infinity j``. + - If ``a`` is ``+infinity`` and ``b`` is ``+infinity``, the result is ``π/4 - infinity j``. + - If ``a`` is either ``+infinity`` or ``-infinity`` and ``b`` is ``NaN``, the result is ``NaN ± infinity j`` (sign of the imaginary component is unspecified). + - If ``a`` is NaN`` and ``b`` is a finite number, the result is ``NaN + NaN j``. + - If ``a`` is ``NaN`` and ``b`` is ``+infinity``, the result is ``NaN - infinity j``. + - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. + + .. note:: + The principal value of the arc cosine of a complex number :math:`z` is :math:`\operatorname{acos}(z) = \frac{1}{2}\pi + j\ \ln(zj + \sqrt{1-z^2})`. + + For any :math:`z`, :math:`\operatorname{acos}(z) = \pi - \operatorname{acos}(-z)`. + + .. note:: + For complex floating-point operands, ``acos(conj(x))`` must equal ``conj(acos(x))``. + + .. note:: + The inverse cosine (or arc cosine) is a multi-valued function and requires a branch cut on the complex plane. By convention, the branch cut is placed at the line segments :math:`(\infty, 1)` and :math:`(1, \infty)` of 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 cosine 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 cosine of each element in ``x``. The returned array must have a floating-point data type determined by :ref:`type-promotion`. """ def acosh(x: array, /) -> array: From e7ae71c02391ca39af4655fe917037693f62bf21 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sat, 26 Nov 2022 16:07:40 -0800 Subject: [PATCH 2/6] Fix sign --- spec/API_specification/array_api/elementwise_functions.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/array_api/elementwise_functions.py b/spec/API_specification/array_api/elementwise_functions.py index 3aa946283..ade92e430 100644 --- a/spec/API_specification/array_api/elementwise_functions.py +++ b/spec/API_specification/array_api/elementwise_functions.py @@ -65,8 +65,8 @@ def acos(x: array, /) -> array: For complex floating-point operands, ``acos(conj(x))`` must equal ``conj(acos(x))``. .. note:: - The inverse cosine (or arc cosine) is a multi-valued function and requires a branch cut on the complex plane. By convention, the branch cut is placed at the line segments :math:`(\infty, 1)` and :math:`(1, \infty)` of the real axis. - + The inverse cosine (or arc cosine) is a multi-valued function and requires a branch cut on the complex plane. By convention, the branch cut is placed at the line segments :math:`(-\infty, 1)` and :math:`(1, \infty)` of the real axis. + *Note: branch cuts have provisional status* (see :ref:`branch-cuts`). Parameters From c40293305e1573e90d7d3dde366e54cb02abe369 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sat, 26 Nov 2022 16:09:21 -0800 Subject: [PATCH 3/6] Fix missing backticks --- spec/API_specification/array_api/elementwise_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/elementwise_functions.py b/spec/API_specification/array_api/elementwise_functions.py index ade92e430..96adfa9c4 100644 --- a/spec/API_specification/array_api/elementwise_functions.py +++ b/spec/API_specification/array_api/elementwise_functions.py @@ -52,7 +52,7 @@ def acos(x: array, /) -> array: - If ``a`` is ``-infinity`` and ``b`` is ``+infinity``, the result is ``3π/4 - infinity j``. - If ``a`` is ``+infinity`` and ``b`` is ``+infinity``, the result is ``π/4 - infinity j``. - If ``a`` is either ``+infinity`` or ``-infinity`` and ``b`` is ``NaN``, the result is ``NaN ± infinity j`` (sign of the imaginary component is unspecified). - - If ``a`` is NaN`` and ``b`` is a finite number, the result is ``NaN + NaN j``. + - If ``a`` is ``NaN`` and ``b`` is a finite number, the result is ``NaN + NaN j``. - If ``a`` is ``NaN`` and ``b`` is ``+infinity``, the result is ``NaN - infinity j``. - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. From fc29106c38bb3589e964b36fc002825b5f7b65d3 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sat, 26 Nov 2022 17:27:14 -0800 Subject: [PATCH 4/6] Update note --- spec/API_specification/array_api/elementwise_functions.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/elementwise_functions.py b/spec/API_specification/array_api/elementwise_functions.py index c8f8bb428..290c20336 100644 --- a/spec/API_specification/array_api/elementwise_functions.py +++ b/spec/API_specification/array_api/elementwise_functions.py @@ -65,7 +65,9 @@ def acos(x: array, /) -> array: For complex floating-point operands, ``acos(conj(x))`` must equal ``conj(acos(x))``. .. note:: - The inverse cosine (or arc cosine) is a multi-valued function and requires a branch cut on the complex plane. By convention, the branch cut is placed at the line segments :math:`(-\infty, 1)` and :math:`(1, \infty)` of the real axis. + The inverse cosine (or arc cosine) is a multi-valued function and requires a branch cut on the complex plane. By convention, a branch cut is placed at the line segments :math:`(-\infty, 1)` and :math:`(1, \infty)` of the real axis. + + Accordingly, for complex arguments, the function returns the inverse cosine in the range of a strip unbounded along the imaginary axis and in the interval :math:`[0, \pi]` along the real axis. *Note: branch cuts have provisional status* (see :ref:`branch-cuts`). From 4b26389789f6781aa429fe6aeebcac8fd99adb75 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 27 Nov 2022 00:15:11 -0800 Subject: [PATCH 5/6] Fix branch cut --- spec/API_specification/array_api/elementwise_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/elementwise_functions.py b/spec/API_specification/array_api/elementwise_functions.py index 290c20336..7106495a6 100644 --- a/spec/API_specification/array_api/elementwise_functions.py +++ b/spec/API_specification/array_api/elementwise_functions.py @@ -65,7 +65,7 @@ def acos(x: array, /) -> array: For complex floating-point operands, ``acos(conj(x))`` must equal ``conj(acos(x))``. .. note:: - The inverse cosine (or arc cosine) is a multi-valued function and requires a branch cut on the complex plane. By convention, a branch cut is placed at the line segments :math:`(-\infty, 1)` and :math:`(1, \infty)` of the real axis. + The inverse cosine (or arc cosine) is a multi-valued function and requires a branch cut on the complex plane. By convention, a branch cut is placed at the line segments :math:`(-\infty, -1)` and :math:`(1, \infty)` of the real axis. Accordingly, for complex arguments, the function returns the inverse cosine in the range of a strip unbounded along the imaginary axis and in the interval :math:`[0, \pi]` along the real axis. From 5f3c28f719e2af33e767ad398b039a2930be69f9 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 27 Nov 2022 00:58:10 -0800 Subject: [PATCH 6/6] Update eqns --- .../array_api/elementwise_functions.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/array_api/elementwise_functions.py b/spec/API_specification/array_api/elementwise_functions.py index 7106495a6..fa5df8dbc 100644 --- a/spec/API_specification/array_api/elementwise_functions.py +++ b/spec/API_specification/array_api/elementwise_functions.py @@ -57,9 +57,15 @@ def acos(x: array, /) -> array: - If ``a`` is ``NaN`` and ``b`` is ``NaN``, the result is ``NaN + NaN j``. .. note:: - The principal value of the arc cosine of a complex number :math:`z` is :math:`\operatorname{acos}(z) = \frac{1}{2}\pi + j\ \ln(zj + \sqrt{1-z^2})`. + The principal value of the arc cosine of a complex number :math:`z` is - For any :math:`z`, :math:`\operatorname{acos}(z) = \pi - \operatorname{acos}(-z)`. + .. math:: + \operatorname{acos}(z) = \frac{1}{2}\pi + j\ \ln(zj + \sqrt{1-z^2}) + + For any :math:`z`, + + .. math:: + \operatorname{acos}(z) = \pi - \operatorname{acos}(-z) .. note:: For complex floating-point operands, ``acos(conj(x))`` must equal ``conj(acos(x))``.