From 57ee1fe227c71392e269c07ffda1f0b6d388b872 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Thu, 17 Nov 2022 12:44:14 +0100 Subject: [PATCH 01/10] Add complex number support to `vecdot` Closes gh-356 (where the definition x1^H x2 was decided). --- .../API_specification/array_api/linear_algebra_functions.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index f8f15e5b0..6f7b13fac 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -90,9 +90,9 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: Parameters ---------- x1: array - first input array. Should have a real-valued data type. + first input array. Should have a floating-point data type. x2: array - second input array. Must be compatible with ``x1`` for all non-contracted axes (see :ref:`broadcasting`). The size of the axis over which to compute the dot product must be the same size as the respective axis in ``x1``. Should have a real-valued data type. + second input array. Must be compatible with ``x1`` for all non-contracted axes (see :ref:`broadcasting`). The size of the axis over which to compute the dot product must be the same size as the respective axis in ``x1``. Should have a floating-point data type. .. note:: The contracted axis (dimension) must not be broadcasted. @@ -105,6 +105,8 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: out: array if ``x1`` and ``x2`` are both one-dimensional arrays, a zero-dimensional containing the dot product; otherwise, a non-zero-dimensional array containing the dot products and having rank ``N-1``, where ``N`` is the rank (number of dimensions) of the shape determined according to :ref:`broadcasting` along the non-contracted axes. The returned array must have a data type determined by :ref:`type-promotion`. + For complex-valued input arrays, this function computes :math:`x_1^H \cdot x_2`. + **Raises** From f473a67e28276af30a683481ea3a69a6aa118063 Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 14 Dec 2022 12:18:17 -0800 Subject: [PATCH 02/10] Move operation description to extended intro --- .../array_api/linear_algebra_functions.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index 6f7b13fac..40acf9166 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -86,6 +86,13 @@ def tensordot(x1: array, x2: array, /, *, axes: Union[int, Tuple[Sequence[int], def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: """ Computes the (vector) dot product of two arrays. + + The dot product is defined as + + .. math:: + \sum_{i=1}^{n} = \overline{x1_i}x2_i + + over the dimension specified by ``axis`` and where :math:`\overline{x1_i}` denotes the complex conjugate if ``x1`` is complex and the identity if ``x1`` is real-valued. Parameters ---------- From 34b6599eecf052195291216a68d351c9c7f9cae6 Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 14 Dec 2022 12:20:31 -0800 Subject: [PATCH 03/10] Fix equation --- spec/API_specification/array_api/linear_algebra_functions.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index 40acf9166..b5b61f213 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -90,9 +90,9 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: The dot product is defined as .. math:: - \sum_{i=1}^{n} = \overline{x1_i}x2_i + \sum_{i=1}^{n} = x1_i\overline{x2_i} - over the dimension specified by ``axis`` and where :math:`\overline{x1_i}` denotes the complex conjugate if ``x1`` is complex and the identity if ``x1`` is real-valued. + over the dimension specified by ``axis`` and where :math:`\overline{x2_i}` denotes the complex conjugate if ``x2`` is complex and the identity if ``x2`` is real-valued. Parameters ---------- From c70fa75289fcd14b1a0aff94fcef42dd25f872c6 Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 14 Dec 2022 12:22:48 -0800 Subject: [PATCH 04/10] Update equation --- spec/API_specification/array_api/linear_algebra_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index b5b61f213..76074989c 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -90,7 +90,7 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: The dot product is defined as .. math:: - \sum_{i=1}^{n} = x1_i\overline{x2_i} + \textbf{x1} \cdot \textbf{x2} = \sum_{i=1}^{n} = x1_i\overline{x2_i} over the dimension specified by ``axis`` and where :math:`\overline{x2_i}` denotes the complex conjugate if ``x2`` is complex and the identity if ``x2`` is real-valued. From 40e3a68a0db9d4dd19f8ba393029dd6e1c73d67e Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 14 Dec 2022 12:24:12 -0800 Subject: [PATCH 05/10] Update copy --- spec/API_specification/array_api/linear_algebra_functions.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index 76074989c..b15439eac 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -90,9 +90,9 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: The dot product is defined as .. math:: - \textbf{x1} \cdot \textbf{x2} = \sum_{i=1}^{n} = x1_i\overline{x2_i} + \textbf{x1} \cdot \textbf{x2} = \sum_{i=0}^{n-1} = x1_i\overline{x2_i} - over the dimension specified by ``axis`` and where :math:`\overline{x2_i}` denotes the complex conjugate if ``x2`` is complex and the identity if ``x2`` is real-valued. + over the dimension specified by ``axis`` and where :math:`n` is the dimension size and :math:`\overline{x2_i}` denotes the complex conjugate if ``x2`` is complex and the identity if ``x2`` is real-valued. Parameters ---------- From f79cfcad915d5b48d3618a7f5f84963f47ec9bf2 Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 14 Dec 2022 12:29:21 -0800 Subject: [PATCH 06/10] Fix equation --- .../API_specification/array_api/linear_algebra_functions.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index b15439eac..8416697ff 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -87,12 +87,12 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: """ Computes the (vector) dot product of two arrays. - The dot product is defined as + Let ``x1`` equal :math:`a` and ``x2`` equal :math:`b`. The dot product is defined as .. math:: - \textbf{x1} \cdot \textbf{x2} = \sum_{i=0}^{n-1} = x1_i\overline{x2_i} + \mathbf{a} \cdot \mathbf{b} = \sum_{i=0}^{n-1} = a_i\overline{b_i} - over the dimension specified by ``axis`` and where :math:`n` is the dimension size and :math:`\overline{x2_i}` denotes the complex conjugate if ``x2`` is complex and the identity if ``x2`` is real-valued. + over the dimension specified by ``axis`` and where :math:`n` is the dimension size and :math:`\overline{b_i}` denotes the complex conjugate if :math:`b_i` is complex and the identity if :math:`b_i` is real-valued. Parameters ---------- From ebb688e149cbbfd9024866c5e2003c65ffec123b Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 14 Dec 2022 12:33:14 -0800 Subject: [PATCH 07/10] Fix equation --- spec/API_specification/array_api/linear_algebra_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index 8416697ff..5601dff50 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -90,7 +90,7 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: Let ``x1`` equal :math:`a` and ``x2`` equal :math:`b`. The dot product is defined as .. math:: - \mathbf{a} \cdot \mathbf{b} = \sum_{i=0}^{n-1} = a_i\overline{b_i} + \mathbf{a} \cdot \mathbf{b} = \sum_{i=0}^{n-1} a_i\overline{b_i} over the dimension specified by ``axis`` and where :math:`n` is the dimension size and :math:`\overline{b_i}` denotes the complex conjugate if :math:`b_i` is complex and the identity if :math:`b_i` is real-valued. From 2c8f60b88b376588937b733508bfde025634629a Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 14 Dec 2022 12:34:22 -0800 Subject: [PATCH 08/10] Remove note --- spec/API_specification/array_api/linear_algebra_functions.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index 5601dff50..4a0f163b4 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -112,9 +112,6 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: out: array if ``x1`` and ``x2`` are both one-dimensional arrays, a zero-dimensional containing the dot product; otherwise, a non-zero-dimensional array containing the dot products and having rank ``N-1``, where ``N`` is the rank (number of dimensions) of the shape determined according to :ref:`broadcasting` along the non-contracted axes. The returned array must have a data type determined by :ref:`type-promotion`. - For complex-valued input arrays, this function computes :math:`x_1^H \cdot x_2`. - - **Raises** - if provided an invalid ``axis``. From 48d1d4c37fa8c40a6895c1cfe2bddb137c77bb39 Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 14 Dec 2022 12:34:48 -0800 Subject: [PATCH 09/10] Add linebreak --- spec/API_specification/array_api/linear_algebra_functions.py | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index 4a0f163b4..a8f9cbfbb 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -112,6 +112,7 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: out: array if ``x1`` and ``x2`` are both one-dimensional arrays, a zero-dimensional containing the dot product; otherwise, a non-zero-dimensional array containing the dot products and having rank ``N-1``, where ``N`` is the rank (number of dimensions) of the shape determined according to :ref:`broadcasting` along the non-contracted axes. The returned array must have a data type determined by :ref:`type-promotion`. + **Raises** - if provided an invalid ``axis``. From 2931a8c9170c201a7a2faf5fb7fe0ff5800eb923 Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 14 Dec 2022 12:38:49 -0800 Subject: [PATCH 10/10] Update copy --- spec/API_specification/array_api/linear_algebra_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/linear_algebra_functions.py b/spec/API_specification/array_api/linear_algebra_functions.py index a8f9cbfbb..321c66668 100644 --- a/spec/API_specification/array_api/linear_algebra_functions.py +++ b/spec/API_specification/array_api/linear_algebra_functions.py @@ -87,7 +87,7 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: """ Computes the (vector) dot product of two arrays. - Let ``x1`` equal :math:`a` and ``x2`` equal :math:`b`. The dot product is defined as + Let :math:`\mathbf{a}` be a vector in ``x1`` and :math:`\mathbf{b}` be a corresponding vector in ``x2``. The dot product is defined as .. math:: \mathbf{a} \cdot \mathbf{b} = \sum_{i=0}^{n-1} a_i\overline{b_i}