From 7409a1c007b7773544223f0e0a2d8aaee4a45172 Mon Sep 17 00:00:00 2001
From: Milan Bouchet-Valat <nalimilan@club.fr>
Date: Tue, 6 Jul 2021 20:13:14 +0200
Subject: [PATCH] Fix pivoted cholesky docstrings (#41298)

---
 stdlib/LinearAlgebra/src/cholesky.jl | 68 +++++++++++++++-------------
 1 file changed, 37 insertions(+), 31 deletions(-)

diff --git a/stdlib/LinearAlgebra/src/cholesky.jl b/stdlib/LinearAlgebra/src/cholesky.jl
index 2ad2135da5d9c..bf738d5d203ec 100644
--- a/stdlib/LinearAlgebra/src/cholesky.jl
+++ b/stdlib/LinearAlgebra/src/cholesky.jl
@@ -110,8 +110,10 @@ positive semi-definite matrix `A`. This is the return type of [`cholesky(_, Val(
 the corresponding matrix factorization function.
 
 The triangular Cholesky factor can be obtained from the factorization `F::CholeskyPivoted`
-via `F.L` and `F.U`, and the permutation via `F.p`, where `A[F.p, F.p] ≈ F.U' * F.U ≈ F.L * F.L'`,
-or alternatively `A ≈ F.U[:, F.p]' * F.U[:, F.p] ≈ F.L[F.p, :] * F.L[F.p, :]'`.
+via `F.L` and `F.U`, and the permutation via `F.p`, where `A[F.p, F.p] ≈ Ur' * Ur ≈ Lr * Lr'`
+with `Ur = F.U[1:F.rank, :]` and `Lr = F.L[:, 1:F.rank]`, or alternatively
+`A ≈ Up' * Up ≈ Lp * Lp'` with `Up = F.U[1:F.rank, invperm(F.p)]` and
+`Lp = F.L[invperm(F.p), 1:F.rank]`.
 
 The following functions are available for `CholeskyPivoted` objects:
 [`size`](@ref), [`\\`](@ref), [`inv`](@ref), [`det`](@ref), and [`rank`](@ref).
@@ -120,25 +122,28 @@ Iterating the decomposition produces the components `L` and `U`.
 
 # Examples
 ```jldoctest
-julia> A = [4. 12. -16.; 12. 37. -43.; -16. -43. 98.]
-3×3 Matrix{Float64}:
-   4.0   12.0  -16.0
-  12.0   37.0  -43.0
- -16.0  -43.0   98.0
+julia> X = [1.0, 2.0, 3.0, 4.0];
 
-julia> C = cholesky(A, Val(true))
+julia> A = X * X';
+
+julia> C = cholesky(A, Val(true), check = false)
 CholeskyPivoted{Float64, Matrix{Float64}}
-U factor with rank 3:
-3×3 UpperTriangular{Float64, Matrix{Float64}}:
- 9.89949  -4.34366  -1.61624
-  ⋅        4.25825   1.1694
-  ⋅         ⋅        0.142334
+U factor with rank 1:
+4×4 UpperTriangular{Float64, Matrix{Float64}}:
+ 4.0  2.0  3.0  1.0
+  ⋅   0.0  6.0  2.0
+  ⋅    ⋅   9.0  3.0
+  ⋅    ⋅    ⋅   1.0
 permutation:
-3-element Vector{Int64}:
- 3
+4-element Vector{Int64}:
+ 4
  2
+ 3
  1
 
+julia> C.U[1:C.rank, :]' * C.U[1:C.rank, :] ≈ A[C.p, C.p]
+true
+
 julia> l, u = C; # destructuring via iteration
 
 julia> l == C.L && u == C.U
@@ -403,8 +408,9 @@ and return a [`CholeskyPivoted`](@ref) factorization. The matrix `A` can either
 or [`Hermitian`](@ref) [`StridedMatrix`](@ref) or a *perfectly* symmetric or Hermitian `StridedMatrix`.
 
 The triangular Cholesky factor can be obtained from the factorization `F` via `F.L` and `F.U`,
-and the permutation via `F.p`, where `A[F.p, F.p] ≈ F.U' * F.U ≈ F.L * F.L'`, or alternatively
-`A ≈ F.U[:, F.p]' * F.U[:, F.p] ≈ F.L[F.p, :] * F.L[F.p, :]'`.
+and the permutation via `F.p`, where `A[F.p, F.p] ≈ Ur' * Ur ≈ Lr * Lr'` with `Ur = F.U[1:F.rank, :]`
+and `Lr = F.L[:, 1:F.rank]`, or alternatively `A ≈ Up' * Up ≈ Lp * Lp'` with
+`Up = F.U[1:F.rank, invperm(F.p)]` and `Lp = F.L[invperm(F.p), 1:F.rank]`.
 
 The following functions are available for `CholeskyPivoted` objects:
 [`size`](@ref), [`\\`](@ref), [`inv`](@ref), [`det`](@ref), and [`rank`](@ref).
@@ -421,26 +427,26 @@ validity (via [`issuccess`](@ref)) lies with the user.
 
 # Examples
 ```jldoctest
-julia> A = [4. 12. -16.; 12. 37. -43.; -16. -43. 98.]
-3×3 Matrix{Float64}:
-   4.0   12.0  -16.0
-  12.0   37.0  -43.0
- -16.0  -43.0   98.0
+julia> X = [1.0, 2.0, 3.0, 4.0];
+
+julia> A = X * X';
 
-julia> C = cholesky(A, Val(true))
+julia> C = cholesky(A, Val(true), check = false)
 CholeskyPivoted{Float64, Matrix{Float64}}
-U factor with rank 3:
-3×3 UpperTriangular{Float64, Matrix{Float64}}:
- 9.89949  -4.34366  -1.61624
-  ⋅        4.25825   1.1694
-  ⋅         ⋅        0.142334
+U factor with rank 1:
+4×4 UpperTriangular{Float64, Matrix{Float64}}:
+ 4.0  2.0  3.0  1.0
+  ⋅   0.0  6.0  2.0
+  ⋅    ⋅   9.0  3.0
+  ⋅    ⋅    ⋅   1.0
 permutation:
-3-element Vector{Int64}:
- 3
+4-element Vector{Int64}:
+ 4
  2
+ 3
  1
 
-julia> C.U[:, C.p]' * C.U[:, C.p] ≈ A
+julia> C.U[1:C.rank, :]' * C.U[1:C.rank, :] ≈ A[C.p, C.p]
 true
 
 julia> l, u = C; # destructuring via iteration