pm_matrixChol::setChoLow Interface Reference

[LEGACY code]
Return the lower-triangle of the Cholesky factorization \(L\) of the symmetric positive-definite real-valued matrix represented by the upper-triangle of the input argument \(\ms{mat} = L.L^T\).
More...

Detailed Description

[LEGACY code]
Return the lower-triangle of the Cholesky factorization \(L\) of the symmetric positive-definite real-valued matrix represented by the upper-triangle of the input argument \(\ms{mat} = L.L^T\).

On input, the upper triangle and diagonal of mat must be specified, which remains intact on output.

Parameters

[in,out]	mat	: The input array of shape (ndim, ndim) of type real of kind any supported by the processor (e.g., RK, RK32, RK64, or RK128). On input, the upper triangle and diagonals of mat contain the square symmetric positive-definite (covariance) matrix whose Cholesky factorization is to be computed. On output, the lower triangle of mat contains the lower triangle of the Cholesky factorization of the matrix, while the upper triangle and diagonals remain intact.
[out]	dia	: The output vector of the same type and kind as mat containing the diagonal elements of the lower triangle of the Cholesky factorization. If the Cholesky factorization fails, dia(1) = -idim will be set, where idim is the column index causing the singularity.
[in]	ndim	: The input integer of default kind IK representing the rank of the input square matrix (ndim,ndim).

Possible calling interfaces ⛓

use pm_matrixChol, only: setChoLow
 
call setChoLow(mat, dia, ndim) ! Explicit-shape dummy argument unsafe interface(for benchmarking purposes)

Warning

This generic interface with explicit-shape dummy arguments is not recommended for general usage.
It exists merely for benchmarking purposes against the alternative modern interface setMatChol.
However, if used, and the Cholesky factorization fails, dia(1) will be set to -idim where idim is the index of the column causing the singularity.

The pure procedure(s) documented herein become impure when the ParaMonte library is compiled with preprocessor macro CHECK_ENABLED=1.
By default, these procedures are pure in release build and impure in debug and testing builds.

Remarks

If ndim = 1, mat will not be touched, only sqrt(mat) will be written to the output dia.

See also

getMatChol
setMatChol

Example usage ⛓

program example
 
    use pm_kind, only: SK
    use pm_kind, only: IK, LK, RKS, RKD, RKH
    use pm_io, only: display_type
    use pm_matrixChol, only: setChoLow
 
    implicit none
 
    real(RKH), allocatable :: matrix_RKH(:,:), chodia_RKH(:)
    real(RKD), allocatable :: matrix_RKD(:,:), chodia_RKD(:)
    real(RKS), allocatable :: matrix_RKS(:,:), chodia_RKS(:)
 
    logical(LK) :: failed
    type(display_type) :: disp
 
    disp = display_type(file = "main.out.F90")
 
    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    ! Construct the Cholesky lower-triangle: RKH
    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
    matrix_RKH = reshape(   [ 1._RKH, 0._RKH, 0._RKH &
                            , 0._RKH, 4._RKH, 0._RKH &
                            , 2._RKH, 0._RKH, 8._RKH ], shape = [3,3])
 
    call disp%show("matrix Upper Triangle")
    call disp%show( matrix_RKH )
 
    allocate(chodia_RKH(size(matrix_RKH, dim = 1)))
    call setChoLow(matrix_RKH, chodia_RKH, size(chodia_RKH, 1, IK))
    if (chodia_RKH(1) <= 0) error stop
 
    call disp%show("matrix Upper Triangle / Cholesky Lower Triangle")
    call disp%show( matrix_RKH )
 
    call disp%show("Cholesky Diagonal")
    call disp%show( chodia_RKH )
 
    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    ! Construct the Cholesky lower-triangle: RKD
    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
    matrix_RKD = real(matrix_RKH, kind = RKD)
 
    call disp%skip()
    call disp%show("matrix Upper Triangle")
    call disp%show( matrix_RKD )
 
    allocate(chodia_RKD(size(matrix_RKD, dim = 1)))
    call setChoLow(matrix_RKD, chodia_RKD, size(chodia_RKD, 1, IK))
    if (chodia_RKD(1) <= 0) error stop
 
    call disp%show("matrix Upper Triangle / Cholesky Lower Triangle")
    call disp%show( matrix_RKD )
 
    call disp%show("Cholesky Diagonal")
    call disp%show( chodia_RKD )
 
    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    ! Construct the Cholesky lower-triangle: RKS
    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
    matrix_RKS = real(matrix_RKH, kind = RKS)
 
    call disp%skip()
    call disp%show("matrix Upper Triangle")
    call disp%show( matrix_RKS )
 
    allocate(chodia_RKS(size(matrix_RKS, dim = 1)))
    call setChoLow(matrix_RKS, chodia_RKS, size(chodia_RKS, 1, IK))
    if (chodia_RKS(1) <= 0) error stop
 
    call disp%show("matrix Upper Triangle / Cholesky Lower Triangle")
    call disp%show( matrix_RKS )
 
    call disp%show("Cholesky Diagonal")
    call disp%show( chodia_RKS )
 
end program example

Example Unix compile command via Intel ifort compiler ⛓

#!/usr/bin/env sh
rm main.exe
ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
./main.exe

Example Windows Batch compile command via Intel ifort compiler ⛓

del main.exe
set PATH=..\..\..\lib;%PATH%
ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
main.exe

Example Unix / MinGW compile command via GNU gfortran compiler ⛓

#!/usr/bin/env sh
rm main.exe
gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
./main.exe

Example output ⛓

matrix Upper Triangle
+1.00000000000000000000000000000000000, +0.00000000000000000000000000000000000, +2.00000000000000000000000000000000000
+0.00000000000000000000000000000000000, +4.00000000000000000000000000000000000, +0.00000000000000000000000000000000000
+0.00000000000000000000000000000000000, +0.00000000000000000000000000000000000, +8.00000000000000000000000000000000000
matrix Upper Triangle / Cholesky Lower Triangle
+1.00000000000000000000000000000000000, +0.00000000000000000000000000000000000, +2.00000000000000000000000000000000000
+0.00000000000000000000000000000000000, +4.00000000000000000000000000000000000, +0.00000000000000000000000000000000000
+2.00000000000000000000000000000000000, +0.00000000000000000000000000000000000, +8.00000000000000000000000000000000000
Cholesky Diagonal
+1.00000000000000000000000000000000000, +2.00000000000000000000000000000000000, +2.00000000000000000000000000000000000
 
matrix Upper Triangle
+1.0000000000000000, +0.0000000000000000, +2.0000000000000000
+0.0000000000000000, +4.0000000000000000, +0.0000000000000000
+2.0000000000000000, +0.0000000000000000, +8.0000000000000000
matrix Upper Triangle / Cholesky Lower Triangle
+1.0000000000000000, +0.0000000000000000, +2.0000000000000000
+0.0000000000000000, +4.0000000000000000, +0.0000000000000000
+2.0000000000000000, +0.0000000000000000, +8.0000000000000000
Cholesky Diagonal
+1.0000000000000000, +2.0000000000000000, +2.0000000000000000
 
matrix Upper Triangle
+1.00000000, +0.00000000, +2.00000000
+0.00000000, +4.00000000, +0.00000000
+2.00000000, +0.00000000, +8.00000000
matrix Upper Triangle / Cholesky Lower Triangle
+1.00000000, +0.00000000, +2.00000000
+0.00000000, +4.00000000, +0.00000000
+2.00000000, +0.00000000, +8.00000000
Cholesky Diagonal
+1.00000000, +2.00000000, +2.00000000
 

Test:

test_pm_matrixChol

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Apr 21, 2017, 1:54 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 209 of file pm_matrixChol.F90.

---

The documentation for this interface was generated from the following file:

• src/fortran/main/pm_matrixChol.F90