From c68781a39dfbc1a2e6250d019632b61048a5317a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 8 Mar 2021 11:51:37 -0800 Subject: [PATCH 1/9] Add dot product specification --- .../linear_algebra_functions.md | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 209a2f787..d7e69eaee 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -98,9 +98,29 @@ Returns the specified diagonals. If `x` has more than two dimensions, then the a - if `x` is a two-dimensional array, a one-dimensional array containing the diagonal; otherwise, a multi-dimensional array containing the diagonals and whose shape is determined by removing `axis1` and `axis2` and appending a dimension equal to the size of the resulting diagonals. The returned array must have the same data type as `x`. (function-dot)= -### dot() +### dot(x1, x2, /, *, axis=0) -TODO +Computes the dot product of two arrays (or stacks of arrays). + +#### Parameters + +- **x1**: _<array>_ + + - first input array. Must have a data type of either `float32` or `float64`. + +- **x2**: _<array>_ + + - second input array. Must be compatible with `x1` (see {ref}`broadcasting`). Must have a data type of either `float32` or `float64`. + +- **axis**: _int_ + + - axis over which to compute the dot product. If `axis` is `0`, the dot product must be computed over the last axis (dimension). If `axis` is `1`, the dot product must be computed over the second-to-last axis (dimension). Default: `0`. + +#### Returns + +- **out**: _<array;>_ + + - an array containing the dot product(s). Must have shape `shape(x1)[:-1]`. The returned array must have a data type determined by {ref}`type-promotion`. (function-eig)= ### eig() From 4da639928afccc7c24dbebe99709a8f0d947c3f2 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 11 Mar 2021 08:28:06 -0800 Subject: [PATCH 2/9] Update specification --- spec/API_specification/linear_algebra_functions.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index d7e69eaee..c3bafb0a0 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -98,7 +98,7 @@ Returns the specified diagonals. If `x` has more than two dimensions, then the a - if `x` is a two-dimensional array, a one-dimensional array containing the diagonal; otherwise, a multi-dimensional array containing the diagonals and whose shape is determined by removing `axis1` and `axis2` and appending a dimension equal to the size of the resulting diagonals. The returned array must have the same data type as `x`. (function-dot)= -### dot(x1, x2, /, *, axis=0) +### dot(x1, x2, /, *, axis=None) Computes the dot product of two arrays (or stacks of arrays). @@ -106,21 +106,21 @@ Computes the dot product of two arrays (or stacks of arrays). - **x1**: _<array>_ - - first input array. Must have a data type of either `float32` or `float64`. + - first input array. Must have a numeric data type. - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see {ref}`broadcasting`). Must have a data type of either `float32` or `float64`. + - second input array. Must be compatible with `x1` (see {ref}`broadcasting`). Must have a numeric data type. -- **axis**: _int_ +- **axis**: _Optional\[ int ]_ - - axis over which to compute the dot product. If `axis` is `0`, the dot product must be computed over the last axis (dimension). If `axis` is `1`, the dot product must be computed over the second-to-last axis (dimension). Default: `0`. + - 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 perform a reduction by counting backward from the last dimension (where `-1` refers to the last dimension). If `None`, the function must compute the dot product over the last axis. If provided an invalid `axis`, the function must raise an exception. Default: `None`. #### Returns - **out**: _<array;>_ - - an array containing the dot product(s). Must have shape `shape(x1)[:-1]`. The returned array must have a data type determined by {ref}`type-promotion`. + - an array containing the dot product(s). Must have a shape determined according to {ref}`broadcasting`. Must have a data type determined by {ref}`type-promotion`. (function-eig)= ### eig() From 27a27bdcdc7f40b50114f75730560e3dbf4cd6e0 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 11 Mar 2021 08:52:16 -0800 Subject: [PATCH 3/9] Fix output shape --- spec/API_specification/linear_algebra_functions.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index c3bafb0a0..ef82028b9 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -114,13 +114,18 @@ Computes the dot product of two arrays (or stacks of arrays). - **axis**: _Optional\[ 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 perform a reduction by counting backward from the last dimension (where `-1` refers to the last dimension). If `None`, the function must compute the dot product over the last axis. If provided an invalid `axis`, the function must raise an exception. Default: `None`. + - 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 perform a reduction by counting backward from the last dimension (where `-1` refers to the last dimension). If `None`, the function must compute the dot product over the last axis. Default: `None`. #### Returns - **out**: _<array;>_ - - an array containing the dot product(s). Must have a shape determined according to {ref}`broadcasting`. Must have a data type determined by {ref}`type-promotion`. + - 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`. 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 inner product is not equal for both `x1` and `x2`. (function-eig)= ### eig() From ca52e0e1387c65426adef2c109cec4d7b9a6ae17 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 11 Mar 2021 08:53:15 -0800 Subject: [PATCH 4/9] Update description --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index ef82028b9..f92c602c8 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -100,7 +100,7 @@ Returns the specified diagonals. If `x` has more than two dimensions, then the a (function-dot)= ### dot(x1, x2, /, *, axis=None) -Computes the dot product of two arrays (or stacks of arrays). +Computes the dot product of two arrays. #### Parameters From 8acc5624dd76e396d40ed6eb736794d2c038810a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 11 Mar 2021 08:54:30 -0800 Subject: [PATCH 5/9] Update copy --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index f92c602c8..5150406c7 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -114,7 +114,7 @@ Computes the dot product of two arrays. - **axis**: _Optional\[ 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 perform a reduction by counting backward from the last dimension (where `-1` refers to the last dimension). If `None`, the function must compute the dot product over the last axis. Default: `None`. + - 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). If `None`, the function must compute the dot product over the last axis. Default: `None`. #### Returns From 6d4a58becf1af8eeed46971e17fd71e2642e246e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 11 Mar 2021 08:54:59 -0800 Subject: [PATCH 6/9] Update copy --- spec/API_specification/linear_algebra_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 5150406c7..14c41e7c7 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -125,7 +125,7 @@ Computes the dot product of two arrays. #### Raises - if provided an invalid `axis`. -- if the size of the axis over which to compute the inner product is not equal for both `x1` and `x2`. +- if the size of the axis over which to compute the inner product is not the same for both `x1` and `x2`. (function-eig)= ### eig() From 03d24429927a74c80eba13bc6c792a8e720034be Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 15:57:51 -0700 Subject: [PATCH 7/9] Rename to inner_dot --- .../linear_algebra_functions.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 14c41e7c7..c7fbaeaeb 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -97,8 +97,23 @@ Returns the specified diagonals. If `x` has more than two dimensions, then the a - if `x` is a two-dimensional array, a one-dimensional array containing the diagonal; otherwise, a multi-dimensional array containing the diagonals and whose shape is determined by removing `axis1` and `axis2` and appending a dimension equal to the size of the resulting diagonals. The returned array must have the same data type as `x`. -(function-dot)= -### dot(x1, x2, /, *, axis=None) +(function-eig)= +### eig() + +TODO + +(function-eigvalsh)= +### eigvalsh() + +TODO + +(function-einsum)= +### einsum() + +TODO + +(function-inner_dot)= +### inner_dot(x1, x2, /, *, axis=None) Computes the dot product of two arrays. @@ -127,21 +142,6 @@ Computes the dot product of two arrays. - if provided an invalid `axis`. - if the size of the axis over which to compute the inner product is not the same for both `x1` and `x2`. -(function-eig)= -### eig() - -TODO - -(function-eigvalsh)= -### eigvalsh() - -TODO - -(function-einsum)= -### einsum() - -TODO - (function-inv)= ### inv(x, /) From 647620b4845e324492f647a68eb2c834f910df4b Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:49:12 -0700 Subject: [PATCH 8/9] Update dtype requirements --- spec/API_specification/linear_algebra_functions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index c7fbaeaeb..13189e993 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -121,11 +121,11 @@ Computes the dot product of two arrays. - **x1**: _<array>_ - - first input array. Must have a numeric data type. + - first input array. Should have a numeric data type. - **x2**: _<array>_ - - second input array. Must be compatible with `x1` (see {ref}`broadcasting`). Must have a numeric data type. + - second input array. Must be compatible with `x1` (see {ref}`broadcasting`). Should have a numeric data type. - **axis**: _Optional\[ int ]_ @@ -135,7 +135,7 @@ Computes the dot product of two arrays. - **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`. Must have a data type determined by {ref}`type-promotion`. + - 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`. The returned array must have a data type determined by {ref}`type-promotion`. #### Raises From 959f82bc0f224384e27b67e28e0381cf10cb1d64 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 29 Mar 2021 12:30:50 -0700 Subject: [PATCH 9/9] Rename to vecdot --- .../linear_algebra_functions.md | 60 +++++++++---------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 13189e993..25a711d9c 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -112,36 +112,6 @@ TODO TODO -(function-inner_dot)= -### inner_dot(x1, x2, /, *, axis=None) - -Computes the dot product of two arrays. - -#### Parameters - -- **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**: _Optional\[ 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). If `None`, the function must compute the dot product over the last axis. Default: `None`. - -#### Returns - -- **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`. 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 inner product is not the same for both `x1` and `x2`. - (function-inv)= ### inv(x, /) @@ -367,3 +337,33 @@ Transposes (or permutes the axes (dimensions)) of an array `x`. - **out**: _<array>_ - an array containing the transpose. The returned array must have the same data type as `x`. + +(function-vecdot)= +### vecdot(x1, x2, /, *, axis=None) + +Computes the (vector) dot product of two arrays. + +#### Parameters + +- **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**: _Optional\[ 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). If `None`, the function must compute the dot product over the last axis. Default: `None`. + +#### Returns + +- **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`. 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 dot product is not the same for both `x1` and `x2`.