From 88af11b289934b6da6032341b2f3300ec9a77d8d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 22 May 2022 23:27:48 -0700 Subject: [PATCH 1/7] Add equations --- spec/API_specification/array_api/linalg.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/spec/API_specification/array_api/linalg.py b/spec/API_specification/array_api/linalg.py index a8b6997b8..52af09894 100644 --- a/spec/API_specification/array_api/linalg.py +++ b/spec/API_specification/array_api/linalg.py @@ -3,13 +3,16 @@ def cholesky(x: array, /, *, upper: bool = False) -> array: """ - Returns the lower (upper) Cholesky decomposition x = LLᵀ (x = UᵀU) of a symmetric positive-definite matrix (or a stack of matrices) ``x``, where ``L`` is a lower-triangular matrix or a stack of matrices (``U`` is an upper-triangular matrix or a stack of matrices). + Returns the lower (upper) Cholesky decomposition of a complex Hermitian \\(x = LL^{H}\\) (\\(x = U^{H}U\\)) or real symmetric positive-definite matrix \\(x = LL^{T}\\) (\\(x = U^{T}U\\)) ``x``. - .. - NOTE: once complex numbers are supported, each square matrix must be Hermitian. + If ``x`` is real-valued, let \\(\mathbb{K}\\) be the set of real numbers \\(\mathbb{R}\\), and, if ``x`` is complex-valued, let \\(\mathbb{K}\\) be the set of complex numbers \\(\mathbb{C}\\). The *cholesky decomposition* of a complex Hermitian or real symmetric positive-definite matrix \\(A \exists \mathbb{K}^{n \times n}\\) is defined as + + \\[A = LL^{H} \quad \text{L \exists \mathbb{K}^{n \times n}}\\] + + TODO: add sentence on batching .. note:: - Whether an array library explicitly checks whether an input array is a symmetric positive-definite matrix (or a stack of matrices) is implementation-defined. + Whether an array library explicitly checks whether an input array is Hermitian or a symmetric positive-definite matrix (or a stack of matrices) is implementation-defined. Parameters ---------- From 2ebaa91e6eb69c5290cf3b456157d4ceff45beec Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 22 May 2022 23:32:35 -0700 Subject: [PATCH 2/7] Fix syntax --- spec/API_specification/array_api/linalg.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/API_specification/array_api/linalg.py b/spec/API_specification/array_api/linalg.py index 52af09894..a8c56056a 100644 --- a/spec/API_specification/array_api/linalg.py +++ b/spec/API_specification/array_api/linalg.py @@ -3,11 +3,11 @@ def cholesky(x: array, /, *, upper: bool = False) -> array: """ - Returns the lower (upper) Cholesky decomposition of a complex Hermitian \\(x = LL^{H}\\) (\\(x = U^{H}U\\)) or real symmetric positive-definite matrix \\(x = LL^{T}\\) (\\(x = U^{T}U\\)) ``x``. + Returns the lower (upper) Cholesky decomposition of a complex Hermitian or real symmetric positive-definite matrix ``x``. - If ``x`` is real-valued, let \\(\mathbb{K}\\) be the set of real numbers \\(\mathbb{R}\\), and, if ``x`` is complex-valued, let \\(\mathbb{K}\\) be the set of complex numbers \\(\mathbb{C}\\). The *cholesky decomposition* of a complex Hermitian or real symmetric positive-definite matrix \\(A \exists \mathbb{K}^{n \times n}\\) is defined as + If ``x`` is real-valued, let $\mathbb{K}$ be the set of real numbers $\mathbb{R}$, and, if ``x`` is complex-valued, let $\mathbb{K}$ be the set of complex numbers $\mathbb{C}$. The *cholesky decomposition* of a complex Hermitian or real symmetric positive-definite matrix $A \exists \mathbb{K}^{n \times n}$ is defined as - \\[A = LL^{H} \quad \text{L \exists \mathbb{K}^{n \times n}}\\] + $$A = LL^{H} \quad \text{L \exists \mathbb{K}^{n \times n}}$$ TODO: add sentence on batching From b0ce496af72f2a60c3ae5f1d619d3cb81ff04df8 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 May 2022 01:20:19 -0700 Subject: [PATCH 3/7] Update description and equations --- spec/API_specification/array_api/linalg.py | 24 ++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/spec/API_specification/array_api/linalg.py b/spec/API_specification/array_api/linalg.py index a8c56056a..7c0d76482 100644 --- a/spec/API_specification/array_api/linalg.py +++ b/spec/API_specification/array_api/linalg.py @@ -5,11 +5,23 @@ def cholesky(x: array, /, *, upper: bool = False) -> array: """ Returns the lower (upper) Cholesky decomposition of a complex Hermitian or real symmetric positive-definite matrix ``x``. - If ``x`` is real-valued, let $\mathbb{K}$ be the set of real numbers $\mathbb{R}$, and, if ``x`` is complex-valued, let $\mathbb{K}$ be the set of complex numbers $\mathbb{C}$. The *cholesky decomposition* of a complex Hermitian or real symmetric positive-definite matrix $A \exists \mathbb{K}^{n \times n}$ is defined as + If ``x`` is real-valued, let :math:`\\mathbb{K}` be the set of real numbers $\\mathbb{R}$, and, if ``x`` is complex-valued, let $\\mathbb{K}$ be the set of complex numbers $\\mathbb{C}$. - $$A = LL^{H} \quad \text{L \exists \mathbb{K}^{n \times n}}$$ + The lower **Cholesky decomposition** of a complex Hermitian or real symmetric positive-definite matrix :math:`x\\ \\in\\ \\mathbb{K}^{n \\times n}` is defined as - TODO: add sentence on batching + .. math:: + x = LL^{H} \\qquad \\text{L $\\in\\ \\mathbb{K}^{n \\times n}$} + + where :math:`L` is a lower triangular matrix and :math:`L^{H}` is the conjugate transpose when :math:`L` is complex-valued and the transpose when :math:`L` is real-valued. + + The upper Cholesky decomposition is defined similarly + + .. math:: + x = UU^{H} \\qquad \\text{U $\\in\\ \\mathbb{K}^{n \\times n}$} + + where :math:`U` is an upper triangular matrix. + + When ``x`` is a stack of matrices, the function must compute the Cholesky decomposition for each matrix in the stack. .. note:: Whether an array library explicitly checks whether an input array is Hermitian or a symmetric positive-definite matrix (or a stack of matrices) is implementation-defined. @@ -17,14 +29,14 @@ def cholesky(x: array, /, *, upper: bool = False) -> array: Parameters ---------- x: array - input array having shape ``(..., M, M)`` and whose innermost two dimensions form square symmetric positive-definite matrices. Should have a real-valued floating-point data type. + input array having shape ``(..., M, M)`` and whose innermost two dimensions form square complex Hermitian or real symmetric positive-definite matrices. Should have a floating-point data type. upper: bool - If ``True``, the result must be the upper-triangular Cholesky factor ``U``. If ``False``, the result must be the lower-triangular Cholesky factor ``L``. Default: ``False``. + If ``True``, the result must be the upper-triangular Cholesky factor :math:`U`. If ``False``, the result must be the lower-triangular Cholesky factor :math:`L`. Default: ``False``. Returns ------- out: array - an array containing the Cholesky factors for each square matrix. If ``upper`` is ``False``, the returned array must contain lower-triangular matrices; otherwise, the returned array must contain upper-triangular matrices. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion` and must have the same shape as ``x``. + an array containing the Cholesky factors for each square matrix. If ``upper`` is ``False``, the returned array must contain lower-triangular matrices; otherwise, the returned array must contain upper-triangular matrices. The returned array must have a floating-point data type determined by :ref:`type-promotion` and must have the same shape as ``x``. """ def cross(x1: array, x2: array, /, *, axis: int = -1) -> array: From 3e12ef1abe87d83eaa678f955373c1c3abd86ec2 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 May 2022 01:39:27 -0700 Subject: [PATCH 4/7] Comment out MathJax config --- spec/conf.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/conf.py b/spec/conf.py index 470900803..04712fe63 100644 --- a/spec/conf.py +++ b/spec/conf.py @@ -51,12 +51,12 @@ default_role = 'code' # Mathjax configuration -mathjax_config = { - 'tex2jax': { - 'inlineMath': [ ["\\(","\\)"] ], - 'displayMath': [["\\[","\\]"] ], - }, -} +# mathjax_config = { +# 'tex2jax': { +# 'inlineMath': [ ["\\(","\\)"] ], +# 'displayMath': [["\\[","\\]"] ], +# }, +# } mathjax3_config = { "tex": { From 9547875541e6ee92cf2b366b4706658714c75f42 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 May 2022 01:41:34 -0700 Subject: [PATCH 5/7] Remove config due to failing build This config does not seem to be needed. SymPy does not include it in its docs. Seems fine for us to omit, as well, given that it causes builds to fail. --- spec/conf.py | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/spec/conf.py b/spec/conf.py index 04712fe63..14ccf872b 100644 --- a/spec/conf.py +++ b/spec/conf.py @@ -50,14 +50,7 @@ napoleon_custom_sections = [('Returns', 'params_style')] default_role = 'code' -# Mathjax configuration -# mathjax_config = { -# 'tex2jax': { -# 'inlineMath': [ ["\\(","\\)"] ], -# 'displayMath': [["\\[","\\]"] ], -# }, -# } - +# Mathjax configuration: mathjax3_config = { "tex": { "inlineMath": [['\\(', '\\)']], From 01a614463c6e463b307e7d2fdbefcd6fa7a522e4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 May 2022 22:33:13 -0700 Subject: [PATCH 6/7] Use raw string --- spec/API_specification/array_api/linalg.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/API_specification/array_api/linalg.py b/spec/API_specification/array_api/linalg.py index 7c0d76482..1c867c1c8 100644 --- a/spec/API_specification/array_api/linalg.py +++ b/spec/API_specification/array_api/linalg.py @@ -2,22 +2,22 @@ from .constants import inf def cholesky(x: array, /, *, upper: bool = False) -> array: - """ + r""" Returns the lower (upper) Cholesky decomposition of a complex Hermitian or real symmetric positive-definite matrix ``x``. - If ``x`` is real-valued, let :math:`\\mathbb{K}` be the set of real numbers $\\mathbb{R}$, and, if ``x`` is complex-valued, let $\\mathbb{K}$ be the set of complex numbers $\\mathbb{C}$. + If ``x`` is real-valued, let :math:`\mathbb{K}` be the set of real numbers $\mathbb{R}$, and, if ``x`` is complex-valued, let $\mathbb{K}$ be the set of complex numbers $\mathbb{C}$. - The lower **Cholesky decomposition** of a complex Hermitian or real symmetric positive-definite matrix :math:`x\\ \\in\\ \\mathbb{K}^{n \\times n}` is defined as + The lower **Cholesky decomposition** of a complex Hermitian or real symmetric positive-definite matrix :math:`x\ \in\ \mathbb{K}^{n \times n}` is defined as .. math:: - x = LL^{H} \\qquad \\text{L $\\in\\ \\mathbb{K}^{n \\times n}$} + x = LL^{H} \qquad \text{L $\in\ \mathbb{K}^{n \times n}$} where :math:`L` is a lower triangular matrix and :math:`L^{H}` is the conjugate transpose when :math:`L` is complex-valued and the transpose when :math:`L` is real-valued. The upper Cholesky decomposition is defined similarly .. math:: - x = UU^{H} \\qquad \\text{U $\\in\\ \\mathbb{K}^{n \\times n}$} + x = UU^{H} \qquad \text{U $\in\ \mathbb{K}^{n \times n}$} where :math:`U` is an upper triangular matrix. From f58565ae3e08c4690eff7875b1e13c037c6a8285 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 23 May 2022 22:38:49 -0700 Subject: [PATCH 7/7] Remove backlash --- 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 1c867c1c8..483d12632 100644 --- a/spec/API_specification/array_api/linalg.py +++ b/spec/API_specification/array_api/linalg.py @@ -7,7 +7,7 @@ def cholesky(x: array, /, *, upper: bool = False) -> array: If ``x`` is real-valued, let :math:`\mathbb{K}` be the set of real numbers $\mathbb{R}$, and, if ``x`` is complex-valued, let $\mathbb{K}$ be the set of complex numbers $\mathbb{C}$. - The lower **Cholesky decomposition** of a complex Hermitian or real symmetric positive-definite matrix :math:`x\ \in\ \mathbb{K}^{n \times n}` is defined as + The lower **Cholesky decomposition** of a complex Hermitian or real symmetric positive-definite matrix :math:`x \in\ \mathbb{K}^{n \times n}` is defined as .. math:: x = LL^{H} \qquad \text{L $\in\ \mathbb{K}^{n \times n}$}