From d867a0af7be87267f7a591929438219d28759f3c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 18 Apr 2022 11:13:33 -0700 Subject: [PATCH 1/5] Make explicit that broadcasting only applies to non-compute dimensions in vecdot --- .../signatures/linear_algebra_functions.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/signatures/linear_algebra_functions.py b/spec/API_specification/signatures/linear_algebra_functions.py index d32245673..c631467d1 100644 --- a/spec/API_specification/signatures/linear_algebra_functions.py +++ b/spec/API_specification/signatures/linear_algebra_functions.py @@ -92,8 +92,8 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: x1: array first input array. Should have a numeric data type. x2: array - second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a numeric data type. - axis:int + second input array. Must be compatible with ``x1`` (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`` (i.e., broadcasting only applies to the non-compute axes). Should have a numeric data type. + axis: int axis over which to compute the dot product. Must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of the shape determined according to :ref:`broadcasting`. If specified as a negative integer, the function must determine the axis along which to compute the dot product by counting backward from the last dimension (where ``-1`` refers to the last dimension). By default, the function must compute the dot product over the last axis. Default: ``-1``. Returns @@ -105,7 +105,7 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: **Raises** - if provided an invalid ``axis``. - - if the size of the axis over which to compute the dot product is not the same for both ``x1`` and ``x2``. + - if the size of the axis over which to compute the dot product is not the same (before broadcasting) for both ``x1`` and ``x2``. """ __all__ = ['matmul', 'matrix_transpose', 'tensordot', 'vecdot'] From da4b4651cc645b030dfb1ca79d9950accc1317a7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 18 Apr 2022 11:23:11 -0700 Subject: [PATCH 2/5] Add support for broadcasting to `linalg.cross` --- spec/API_specification/signatures/linalg.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/signatures/linalg.py b/spec/API_specification/signatures/linalg.py index 275fa3158..77dcc7b41 100644 --- a/spec/API_specification/signatures/linalg.py +++ b/spec/API_specification/signatures/linalg.py @@ -26,16 +26,16 @@ def cholesky(x: array, /, *, upper: bool = False) -> array: def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: """ - Returns the cross product of 3-element vectors. If ``x1`` and ``x2`` are multi-dimensional arrays (i.e., both have a rank greater than ``1``), then the cross-product of each pair of corresponding 3-element vectors is independently computed. + Returns the cross product of 3-element vectors. If ``x1`` and/or ``x2`` are multi-dimensional arrays (i.e., the broadcasted result has a rank greater than ``1``), then the cross-product of each pair of corresponding 3-element vectors is independently computed. Parameters ---------- x1: array first input array. Should have a numeric data type. x2: array - second input array. Must have the same shape as ``x1``. Should have a numeric data type. + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). The size of the axis over which to compute the cross product must be the same size as the respective axis in ``x1`` (i.e., broadcasting only applies to the non-compute axes). Should have a numeric data type. axis: int - the axis (dimension) of ``x1`` and ``x2`` containing the vectors for which to compute the cross product. If set to ``-1``, the function computes the cross product for vectors defined by the last axis (dimension). Default: ``-1``. + the axis (dimension) of ``x1`` and ``x2`` containing the vectors for which to compute the cross product. Must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of the shape determined according to :ref:`broadcasting`. If specified as a negative integer, the function must determine the axis along which to compute the cross product by counting backward from the last dimension (where ``-1`` refers to the last dimension). By default, the function must compute the cross product over the last axis. Default: ``-1``. Returns ------- From 5cc9891927f0900cf406e3e671038d2a94a05c1a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 18 Apr 2022 11:30:53 -0700 Subject: [PATCH 3/5] Update copy --- spec/API_specification/signatures/linalg.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/spec/API_specification/signatures/linalg.py b/spec/API_specification/signatures/linalg.py index 77dcc7b41..5b27dc14c 100644 --- a/spec/API_specification/signatures/linalg.py +++ b/spec/API_specification/signatures/linalg.py @@ -41,6 +41,12 @@ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: ------- out: array an array containing the cross products. The returned array must have a data type determined by :ref:`type-promotion`. + + + **Raises** + + - if provided an invalid ``axis``. + - if the size of the axis over which to compute the cross product is not equal to ``3`` and is not the same (before broadcasting) for both ``x1`` and ``x2``. """ def det(x: array, /) -> array: From b462f3324be1f6d012acfa87b5c268c96bd131ed Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 18 Apr 2022 11:32:19 -0700 Subject: [PATCH 4/5] Update copy --- spec/API_specification/signatures/linalg.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/signatures/linalg.py b/spec/API_specification/signatures/linalg.py index 5b27dc14c..d252bca61 100644 --- a/spec/API_specification/signatures/linalg.py +++ b/spec/API_specification/signatures/linalg.py @@ -46,7 +46,8 @@ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: **Raises** - if provided an invalid ``axis``. - - if the size of the axis over which to compute the cross product is not equal to ``3`` and is not the same (before broadcasting) for both ``x1`` and ``x2``. + - if the size of the axis over which to compute the cross product is not equal to ``3``. + - if the size of the axis over which to compute the cross product is not the same (before broadcasting) for both ``x1`` and ``x2``. """ def det(x: array, /) -> array: From fd94112441cc51afac3fcff121e1d8172c95941b Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 19 Sep 2022 00:40:05 -0700 Subject: [PATCH 5/5] Fix spacing --- spec/API_specification/array_api/linalg.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_api/linalg.py b/spec/API_specification/array_api/linalg.py index 77ff912e2..5336d93c6 100644 --- a/spec/API_specification/array_api/linalg.py +++ b/spec/API_specification/array_api/linalg.py @@ -53,7 +53,7 @@ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: second input array. Must be compatible with ``x1`` for all non-compute axes (see :ref:`broadcasting`). The size of the axis over which to compute the cross product must be the same size as the respective axis in ``x1``. Should have a real-valued data type. .. note:: - The compute axis (dimension) must not be broadcasted. + The compute axis (dimension) must not be broadcasted. axis: int the axis (dimension) of ``x1`` and ``x2`` containing the vectors for which to compute the cross product. Must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of the shape determined according to :ref:`broadcasting`. If specified as a negative integer, the function must determine the axis along which to compute the cross product by counting backward from the last dimension (where ``-1`` refers to the last dimension). By default, the function must compute the cross product over the last axis. Default: ``-1``.