From e172e94f5e162397401144b6b2c61760d4b9a726 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Sun, 4 Oct 2020 12:37:08 -0400 Subject: [PATCH] mjo/ldlt.py: refactor into user-(un)friendly portions. --- mjo/ldlt.py | 358 ++++++++++++++++++++++++++++------------------------ 1 file changed, 193 insertions(+), 165 deletions(-) diff --git a/mjo/ldlt.py b/mjo/ldlt.py index 6f3a628..682eecf 100644 --- a/mjo/ldlt.py +++ b/mjo/ldlt.py @@ -26,166 +26,27 @@ def is_positive_semidefinite_naive(A): return A.is_hermitian() and all( v >= 0 for v in A.eigenvalues() ) -def block_ldlt(A): +def _block_ldlt(A): r""" - Perform a block-`LDL^{T}` factorization of the Hermitian - matrix `A`. - - The standard `LDL^{T}` factorization of a positive-definite matrix - `A` factors it as `A = LDL^{T}` where `L` is unit-lower-triangular - and `D` is diagonal. If one allows row/column swaps via a - permutation matrix `P`, then this factorization can be extended to - some positive-semidefinite matrices `A` via the factorization - `P^{T}AP = LDL^{T}` that places the zeros at the bottom of `D` to - avoid division by zero. These factorizations extend easily to - complex Hermitian matrices when one replaces the transpose by the - conjugate-transpose. - - However, we can go one step further. If, in addition, we allow `D` - to potentially contain `2 \times 2` blocks on its diagonal, then - every real or complex Hermitian matrix `A` can be factored as `A = - PLDL^{*}P^{T}`. When the row/column swaps are made intelligently, - this process is numerically stable over inexact rings like ``RDF``. - Bunch and Kaufman describe such a "pivot" scheme that is suitable - for the solution of Hermitian systems, and that is how we choose - our row and column swaps. - - OUTPUT: - - If the input matrix is Hermitian, we return a triple `(P,L,D)` - such that `A = PLDL^{*}P^{T}` and - - * `P` is a permutation matrix, - * `L` is unit lower-triangular, - * `D` is a block-diagonal matrix whose blocks are of size - one or two. - - If the input matrix is not Hermitian, the output from this function - is undefined. - - SETUP:: - - sage: from mjo.ldlt import block_ldlt - - EXAMPLES: - - This three-by-three real symmetric matrix has one positive, one - negative, and one zero eigenvalue -- so it is not any flavor of - (semi)definite, yet we can still factor it:: - - sage: A = matrix(QQ, [[0, 1, 0], - ....: [1, 1, 2], - ....: [0, 2, 0]]) - sage: P,L,D = block_ldlt(A) - sage: P - [0 0 1] - [1 0 0] - [0 1 0] - sage: L - [ 1 0 0] - [ 2 1 0] - [ 1 1/2 1] - sage: D - [ 1| 0| 0] - [--+--+--] - [ 0|-4| 0] - [--+--+--] - [ 0| 0| 0] - sage: P.transpose()*A*P == L*D*L.transpose() - True - - This two-by-two matrix has no standard factorization, but it - constitutes its own block-factorization:: - - sage: A = matrix(QQ, [ [0,1], - ....: [1,0] ]) - sage: block_ldlt(A) - ( - [1 0] [1 0] [0 1] - [0 1], [0 1], [1 0] - ) - - The same is true of the following complex Hermitian matrix:: - - sage: A = matrix(QQbar, [ [ 0,I], - ....: [-I,0] ]) - sage: block_ldlt(A) - ( - [1 0] [1 0] [ 0 I] - [0 1], [0 1], [-I 0] - ) - - TESTS: - - All three factors should be the identity when the original matrix is:: - - sage: set_random_seed() - sage: n = ZZ.random_element(6) - sage: I = matrix.identity(QQ,n) - sage: P,L,D = block_ldlt(I) - sage: P == I and L == I and D == I - True - - Ensure that a "random" real symmetric matrix is factored correctly:: - - sage: set_random_seed() - sage: n = ZZ.random_element(6) - sage: A = matrix.random(QQ, n) - sage: A = A + A.transpose() - sage: P,L,D = block_ldlt(A) - sage: A == P*L*D*L.transpose()*P.transpose() - True - - Ensure that a "random" complex Hermitian matrix is factored correctly:: - - sage: set_random_seed() - sage: n = ZZ.random_element(6) - sage: F = NumberField(x^2 +1, 'I') - sage: A = matrix.random(F, n) - sage: A = A + A.conjugate_transpose() - sage: P,L,D = block_ldlt(A) - sage: A == P*L*D*L.conjugate_transpose()*P.conjugate_transpose() - True - - Ensure that a "random" complex positive-semidefinite matrix is - factored correctly and that the resulting block-diagonal matrix is - in fact diagonal:: - - sage: set_random_seed() - sage: n = ZZ.random_element(6) - sage: F = NumberField(x^2 +1, 'I') - sage: A = matrix.random(F, n) - sage: A = A*A.conjugate_transpose() - sage: P,L,D = block_ldlt(A) - sage: A == P*L*D*L.conjugate_transpose()*P.conjugate_transpose() - True - sage: diagonal_matrix(D.diagonal()) == D - True - - The factorization should be a no-op on diagonal matrices:: - - sage: set_random_seed() - sage: n = ZZ.random_element(6) - sage: A = matrix.diagonal(random_vector(QQ, n)) - sage: I = matrix.identity(QQ,n) - sage: P,L,D = block_ldlt(A) - sage: P == I and L == I and A == D - True - + Perform a user-unfriendly block-`LDL^{T}` factorization of the + Hermitian matrix `A` + + This function is used internally to compute the factorization for + the user-friendly ``block_ldlt`` function. Whereas that function + returns three nice matrices, this one returns + + * A list ``p`` of the first ``n`` natural numbers, permuted. + * A matrix whose lower-triangular portion is ``L``, but whose + * (strict) upper-triangular portion is junk. + * A list of the block-diagonal entries of ``D`` + + This is mainly useful to avoid havinf to "undo" the construction + of the matrix ``D`` when we don't need it. For example, it's much + easier to compute the inertia of a matrix from the list of blocks + than it is from the block-diagonal matrix itself, because given a + block-diagonal matrix, you first have to figure out where the + blocks are! """ - - # We have to make at least one copy of the input matrix so that we - # can change the base ring to its fraction field. Both "L" and the - # intermediate Schur complements will potentially have entries in - # the fraction field. However, we don't need to make *two* copies. - # We can't store the entries of "D" and "L" in the same matrix if - # "D" will contain any 2x2 blocks; but we can still store the - # entries of "L" in the copy of "A" that we're going to make. - # Contrast this with the non-block LDL^T factorization where the - # entries of both "L" and "D" overwrite the lower-left half of "A". - # - # This grants us an additional speedup, since we don't have to - # permute the rows/columns of "L" *and* "A" at each iteration. ring = A.base_ring().fraction_field() A = A.change_ring(ring) MS = A.matrix_space() @@ -381,7 +242,175 @@ def block_ldlt(A): k += 2 - MS = A.matrix_space() + for i in range(n): + # We skipped this during the main loop, but it's necessary for + # correctness. + A[i,i] = 1 + + return (p,A,d) + +def block_ldlt(A): + r""" + Perform a block-`LDL^{T}` factorization of the Hermitian + matrix `A`. + + The standard `LDL^{T}` factorization of a positive-definite matrix + `A` factors it as `A = LDL^{T}` where `L` is unit-lower-triangular + and `D` is diagonal. If one allows row/column swaps via a + permutation matrix `P`, then this factorization can be extended to + some positive-semidefinite matrices `A` via the factorization + `P^{T}AP = LDL^{T}` that places the zeros at the bottom of `D` to + avoid division by zero. These factorizations extend easily to + complex Hermitian matrices when one replaces the transpose by the + conjugate-transpose. + + However, we can go one step further. If, in addition, we allow `D` + to potentially contain `2 \times 2` blocks on its diagonal, then + every real or complex Hermitian matrix `A` can be factored as `A = + PLDL^{*}P^{T}`. When the row/column swaps are made intelligently, + this process is numerically stable over inexact rings like ``RDF``. + Bunch and Kaufman describe such a "pivot" scheme that is suitable + for the solution of Hermitian systems, and that is how we choose + our row and column swaps. + + OUTPUT: + + If the input matrix is Hermitian, we return a triple `(P,L,D)` + such that `A = PLDL^{*}P^{T}` and + + * `P` is a permutation matrix, + * `L` is unit lower-triangular, + * `D` is a block-diagonal matrix whose blocks are of size + one or two. + + If the input matrix is not Hermitian, the output from this function + is undefined. + + SETUP:: + + sage: from mjo.ldlt import block_ldlt + + EXAMPLES: + + This three-by-three real symmetric matrix has one positive, one + negative, and one zero eigenvalue -- so it is not any flavor of + (semi)definite, yet we can still factor it:: + + sage: A = matrix(QQ, [[0, 1, 0], + ....: [1, 1, 2], + ....: [0, 2, 0]]) + sage: P,L,D = block_ldlt(A) + sage: P + [0 0 1] + [1 0 0] + [0 1 0] + sage: L + [ 1 0 0] + [ 2 1 0] + [ 1 1/2 1] + sage: D + [ 1| 0| 0] + [--+--+--] + [ 0|-4| 0] + [--+--+--] + [ 0| 0| 0] + sage: P.transpose()*A*P == L*D*L.transpose() + True + + This two-by-two matrix has no standard factorization, but it + constitutes its own block-factorization:: + + sage: A = matrix(QQ, [ [0,1], + ....: [1,0] ]) + sage: block_ldlt(A) + ( + [1 0] [1 0] [0 1] + [0 1], [0 1], [1 0] + ) + + The same is true of the following complex Hermitian matrix:: + + sage: A = matrix(QQbar, [ [ 0,I], + ....: [-I,0] ]) + sage: block_ldlt(A) + ( + [1 0] [1 0] [ 0 I] + [0 1], [0 1], [-I 0] + ) + + TESTS: + + All three factors should be the identity when the original matrix is:: + + sage: set_random_seed() + sage: n = ZZ.random_element(6) + sage: I = matrix.identity(QQ,n) + sage: P,L,D = block_ldlt(I) + sage: P == I and L == I and D == I + True + + Ensure that a "random" real symmetric matrix is factored correctly:: + + sage: set_random_seed() + sage: n = ZZ.random_element(6) + sage: A = matrix.random(QQ, n) + sage: A = A + A.transpose() + sage: P,L,D = block_ldlt(A) + sage: A == P*L*D*L.transpose()*P.transpose() + True + + Ensure that a "random" complex Hermitian matrix is factored correctly:: + + sage: set_random_seed() + sage: n = ZZ.random_element(6) + sage: F = NumberField(x^2 +1, 'I') + sage: A = matrix.random(F, n) + sage: A = A + A.conjugate_transpose() + sage: P,L,D = block_ldlt(A) + sage: A == P*L*D*L.conjugate_transpose()*P.conjugate_transpose() + True + + Ensure that a "random" complex positive-semidefinite matrix is + factored correctly and that the resulting block-diagonal matrix is + in fact diagonal:: + + sage: set_random_seed() + sage: n = ZZ.random_element(6) + sage: F = NumberField(x^2 +1, 'I') + sage: A = matrix.random(F, n) + sage: A = A*A.conjugate_transpose() + sage: P,L,D = block_ldlt(A) + sage: A == P*L*D*L.conjugate_transpose()*P.conjugate_transpose() + True + sage: diagonal_matrix(D.diagonal()) == D + True + + The factorization should be a no-op on diagonal matrices:: + + sage: set_random_seed() + sage: n = ZZ.random_element(6) + sage: A = matrix.diagonal(random_vector(QQ, n)) + sage: I = matrix.identity(QQ,n) + sage: P,L,D = block_ldlt(A) + sage: P == I and L == I and A == D + True + + """ + + # We have to make at least one copy of the input matrix so that we + # can change the base ring to its fraction field. Both "L" and the + # intermediate Schur complements will potentially have entries in + # the fraction field. However, we don't need to make *two* copies. + # We can't store the entries of "D" and "L" in the same matrix if + # "D" will contain any 2x2 blocks; but we can still store the + # entries of "L" in the copy of "A" that we're going to make. + # Contrast this with the non-block LDL^T factorization where the + # entries of both "L" and "D" overwrite the lower-left half of "A". + # + # This grants us an additional speedup, since we don't have to + # permute the rows/columns of "L" *and* "A" at each iteration. + p,L,d = _block_ldlt(A) + MS = L.matrix_space() P = MS.matrix(lambda i,j: p[j] == i) # Warning: when n == 0, this works, but returns a matrix @@ -389,12 +418,11 @@ def block_ldlt(A): # the base ring of P and L. D = block_diagonal_matrix(d) - # Overwrite the diagonal and upper-right half of "A", - # since we're about to return it as the unit-lower- - # triangular "L". + # Overwrite the (strict) upper-triangular part of "L", since a + # priori it contains the same entries as "A" did after _block_ldlt(). + n = L.nrows() for i in range(n): - A[i,i] = 1 for j in range(i+1,n): - A[i,j] = 0 + L[i,j] = 0 - return (P,A,D) + return (P,L,D) -- 2.44.2