From e970388fe4269a69ad2223b28f6bb377feb99eff Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 14 Jan 2021 01:07:14 -0800 Subject: [PATCH 01/13] Add slogdet spec --- .../linear_algebra_functions.md | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index ba92aa7b0..250c9fcee 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -265,9 +265,25 @@ TODO TODO (function-slogdet)= -### slogdet() +### slogdet(x, /) -TODO +Returns the sign and the natural logarithm of the determinant of a square matrix (or stack of square matrices) `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. + +#### Returns + +- **out**: _Tuple\[ <array>, ... ]_ + + - if `x` is a two-dimensional array, a namedtuple (`sign`, `logabsdet`) whose first element must be zero-dimensional array containing a number representing the sign of the determinant and whose second element is a zero-dimensional array containing the determinant. Otherwise, a namedtuple (`sign`, `logabsdet`) whose first element must be a non-zero dimensional array containing the sign for each square matrix and whose second element must be a non-zero dimensional array containing the determinant for each square matrix. + + For a real matrix, the sign of the determinant must be either `1`, `0`, or `-1`. If a determinant is zero, then the corresponding `sign` must be `0` and `logabsdet` must be `-infinity`. In all cases, the determinant must be equal to `sign * exp(logsabsdet)`. + + The returned array must have a data type determined by {ref}`type-promotion` rules. (function-solve)= ### solve() From 65a628052fdb3e2905f537e96ef445d0f78dfae9 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 14 Jan 2021 01:12:34 -0800 Subject: [PATCH 02/13] Add note --- spec/API_specification/linear_algebra_functions.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 250c9fcee..6ce16a634 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -269,6 +269,11 @@ TODO Returns the sign and the natural logarithm of the determinant of a square matrix (or stack of square matrices) `x`. +```{note} + +The purpose of this function is to calculate the determinant more accurately when the determinant is either very small or very large, as calling `det` may overflow or underflow. +``` + #### Parameters - **x**: _<array>_ From 689e14f16e7f72d1a6e8619e1254d7e1d4f36615 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 14 Jan 2021 01:13:39 -0800 Subject: [PATCH 03/13] 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 6ce16a634..6caee1593 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -267,7 +267,7 @@ TODO (function-slogdet)= ### slogdet(x, /) -Returns the sign and the natural logarithm of the determinant of a square matrix (or stack of square matrices) `x`. +Returns the sign and the natural logarithm of the absolute value of the determinant of a square matrix (or stack of square matrices) `x`. ```{note} From 2bd17d72cfc2e49e54626542778e53d3550a2862 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 13:28:19 -0700 Subject: [PATCH 04/13] Reformat description and update return value type --- spec/API_specification/linear_algebra_functions.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 6caee1593..b06f5a812 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -282,9 +282,17 @@ The purpose of this function is to calculate the determinant more accurately whe #### Returns -- **out**: _Tuple\[ <array>, ... ]_ +- **out**: _Tuple\[ <array>, <array> ]_ - - if `x` is a two-dimensional array, a namedtuple (`sign`, `logabsdet`) whose first element must be zero-dimensional array containing a number representing the sign of the determinant and whose second element is a zero-dimensional array containing the determinant. Otherwise, a namedtuple (`sign`, `logabsdet`) whose first element must be a non-zero dimensional array containing the sign for each square matrix and whose second element must be a non-zero dimensional array containing the determinant for each square matrix. + - if `x` is a two-dimensional array, a namedtuple (`sign`, `logabsdet`) whose + + - first element must be zero-dimensional array containing a number representing the sign of the determinant. + - second element is a zero-dimensional array containing the determinant. + + Otherwise, a namedtuple (`sign`, `logabsdet`) whose + + - first element must be a non-zero dimensional array containing the sign for each square matrix. + - second element must be a non-zero dimensional array containing the determinant for each square matrix. For a real matrix, the sign of the determinant must be either `1`, `0`, or `-1`. If a determinant is zero, then the corresponding `sign` must be `0` and `logabsdet` must be `-infinity`. In all cases, the determinant must be equal to `sign * exp(logsabsdet)`. From c3c0c6645bfa8f8a69ff56d81a5f7826bfbfe832 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 13:34:45 -0700 Subject: [PATCH 05/13] Add article --- 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 b06f5a812..0c2c88a0c 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -267,7 +267,7 @@ TODO (function-slogdet)= ### slogdet(x, /) -Returns the sign and the natural logarithm of the absolute value of the determinant of a square matrix (or stack of square matrices) `x`. +Returns the sign and the natural logarithm of the absolute value of the determinant of a square matrix (or a stack of square matrices) `x`. ```{note} From c7a75efe6a96cca33d361b3fb0e7465388bbaa42 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 13:43:17 -0700 Subject: [PATCH 06/13] Simplify description --- spec/API_specification/linear_algebra_functions.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 0c2c88a0c..a099e0323 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -284,15 +284,10 @@ The purpose of this function is to calculate the determinant more accurately whe - **out**: _Tuple\[ <array>, <array> ]_ - - if `x` is a two-dimensional array, a namedtuple (`sign`, `logabsdet`) whose + - a namedtuple (`sign`, `logabsdet`) whose - - first element must be zero-dimensional array containing a number representing the sign of the determinant. - - second element is a zero-dimensional array containing the determinant. - - Otherwise, a namedtuple (`sign`, `logabsdet`) whose - - - first element must be a non-zero dimensional array containing the sign for each square matrix. - - second element must be a non-zero dimensional array containing the determinant for each square matrix. + - first element must be an array containing a number representing the sign of the determinant. Must have shape `shape(x)[:-2]`. + - second element must be an array containing the determinant. Must have shape `shape(x)[:-2]`. For a real matrix, the sign of the determinant must be either `1`, `0`, or `-1`. If a determinant is zero, then the corresponding `sign` must be `0` and `logabsdet` must be `-infinity`. In all cases, the determinant must be equal to `sign * exp(logsabsdet)`. From 838ec7370f235656d23d2d6ac099d0e3f02441d2 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 13:44:45 -0700 Subject: [PATCH 07/13] Update copy --- 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 a099e0323..213404985 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -286,12 +286,12 @@ The purpose of this function is to calculate the determinant more accurately whe - a namedtuple (`sign`, `logabsdet`) whose - - first element must be an array containing a number representing the sign of the determinant. Must have shape `shape(x)[:-2]`. - - second element must be an array containing the determinant. Must have shape `shape(x)[:-2]`. + - first element must be an array containing a number representing the sign of the determinant. + - second element must be an array containing the determinant. For a real matrix, the sign of the determinant must be either `1`, `0`, or `-1`. If a determinant is zero, then the corresponding `sign` must be `0` and `logabsdet` must be `-infinity`. In all cases, the determinant must be equal to `sign * exp(logsabsdet)`. - The returned array must have a data type determined by {ref}`type-promotion` rules. + Each returned array must have shape `shape(x)[:-2]` and a data type determined by {ref}`type-promotion` rules. (function-solve)= ### solve() From c72d24451898d54b13c2048c27b6f19f51939041 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 13:45:30 -0700 Subject: [PATCH 08/13] Update copy --- spec/API_specification/linear_algebra_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 213404985..cd16936d5 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -286,8 +286,8 @@ The purpose of this function is to calculate the determinant more accurately whe - a namedtuple (`sign`, `logabsdet`) whose - - first element must be an array containing a number representing the sign of the determinant. - - second element must be an array containing the determinant. + - first element must be an array containing a number representing the sign of the determinant for each square matrix. + - second element must be an array containing the determinant for each square matrix. For a real matrix, the sign of the determinant must be either `1`, `0`, or `-1`. If a determinant is zero, then the corresponding `sign` must be `0` and `logabsdet` must be `-infinity`. In all cases, the determinant must be equal to `sign * exp(logsabsdet)`. From 671f23effdd90586098ee2ccef589a4a31906f8c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 16:40:44 -0700 Subject: [PATCH 09/13] Update dtype requirements --- 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 22d61eda9..c651fda4e 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -278,7 +278,7 @@ The purpose of this function is to calculate the determinant more accurately whe - **x**: _<array>_ - - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Must have a data type of either `float32` or `float64`. + - input array having shape `(..., M, M)` and whose innermost two dimensions form square matrices. Should have a floating-point data type. #### Returns From 7be3c2a8cbd08deda17a677b7130c377f7bf9f64 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 16:43:24 -0700 Subject: [PATCH 10/13] Update dtype requirement for returned arrays --- 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 c651fda4e..a77e8938d 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -291,7 +291,7 @@ The purpose of this function is to calculate the determinant more accurately whe For a real matrix, the sign of the determinant must be either `1`, `0`, or `-1`. If a determinant is zero, then the corresponding `sign` must be `0` and `logabsdet` must be `-infinity`. In all cases, the determinant must be equal to `sign * exp(logsabsdet)`. - Each returned array must have shape `shape(x)[:-2]` and a data type determined by {ref}`type-promotion` rules. + Each returned array must have shape `shape(x)[:-2]` and a floating-point data type. (function-solve)= ### solve() From 409f254dd2f69b173dcd9d8a65085a56a74a9e13 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 16:44:33 -0700 Subject: [PATCH 11/13] 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 a77e8938d..cd1b7cbef 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -291,7 +291,7 @@ The purpose of this function is to calculate the determinant more accurately whe For a real matrix, the sign of the determinant must be either `1`, `0`, or `-1`. If a determinant is zero, then the corresponding `sign` must be `0` and `logabsdet` must be `-infinity`. In all cases, the determinant must be equal to `sign * exp(logsabsdet)`. - Each returned array must have shape `shape(x)[:-2]` and a floating-point data type. + Each returned array must have shape `shape(x)[:-2]` and a floating-point data type determined by {ref}`type-promotion` rules. (function-solve)= ### solve() From 6ac94c7c9d6ebf2da4b65a971312460ef0418cd4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 24 Mar 2021 17:35:47 -0700 Subject: [PATCH 12/13] 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 cd1b7cbef..e5fd89e59 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -291,7 +291,7 @@ The purpose of this function is to calculate the determinant more accurately whe For a real matrix, the sign of the determinant must be either `1`, `0`, or `-1`. If a determinant is zero, then the corresponding `sign` must be `0` and `logabsdet` must be `-infinity`. In all cases, the determinant must be equal to `sign * exp(logsabsdet)`. - Each returned array must have shape `shape(x)[:-2]` and a floating-point data type determined by {ref}`type-promotion` rules. + Each returned array must have shape `shape(x)[:-2]` and a floating-point data type determined by {ref}`type-promotion`. (function-solve)= ### solve() From 5278b605b5f1a2ad4ae96f4b84a43eb7274ee5a1 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 26 Apr 2021 02:34:51 -0700 Subject: [PATCH 13/13] Move API to submodule --- spec/API_specification/linear_algebra_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index e5fd89e59..2038ed14e 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -264,8 +264,8 @@ TODO TODO -(function-slogdet)= -### slogdet(x, /) +(function-linalg-slogdet)= +### linalg.slogdet(x, /) Returns the sign and the natural logarithm of the absolute value of the determinant of a square matrix (or a stack of square matrices) `x`.