+
+ If the input matrix is not Hermitian, the output from this function
+ is undefined.
+
+ 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.T*A*P == L*D*L.T
+ 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: F = NumberField(x^2 +1, 'I')
+ sage: A = matrix.random(F, 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.transpose()*P.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.transpose()*P.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
+