linalg::form_lu Interface Reference

Extracts the L and U matrices from the condensed [L\U] storage format used by the lu_factor. More...

Public Member Functions
	form_lu_all
	form_lu_all_cmplx
	form_lu_only
	form_lu_only_cmplx

Detailed Description

Extracts the L and U matrices from the condensed [L\U] storage format used by the lu_factor.

Syntax 1

subroutine form_lu(real(real64) lu(:,:), integer(int32) ipvt(:), real(real64) u(:,:), real(real64) p(:,:), optional class(errors) err)
subroutine form_lu(complex(real64) lu(:,:), integer(int32) ipvt(:), complex(real64) u(:,:), real(real64) p(:,:), optional class(errors) err)

Parameters

[in,out]	lu	On input, the N-by-N matrix as output by lu_factor. On output, the N-by-N lower triangular matrix L.
[in]	ipvt	The N-element pivot array as output by lu_factor.
[out]	u	An N-by-N matrix where the U matrix will be written.
[out]	p	An N-by-N matrix where the row permutation matrix will be written.
[in,out]	err	An optional errors-based object that if provided can be used to retrieve information relating to any errors encountered during execution. If not provided, a default implementation of the errors class is used internally to provide error handling. Possible errors and warning messages that may be encountered are as follows. LA_ARRAY_SIZE_ERROR: Occurs if any of the input array sizes are incorrect.

Syntax 2

subroutine form_lu(real(real64) lu(:,:), real(real64) u(:,:), optional class(errors) err)
subroutine form_lu(complex(real64) lu(:,:), complex(real64) u(:,:), optional class(errors) err)

Parameters

[in,out]	lu	On input, the N-by-N matrix as output by lu_factor. On output, the N-by-N lower triangular matrix L.
[out]	u	An N-by-N matrix where the U matrix will be written.
[in,out]	err	An optional errors-based object that if provided can be used to retrieve information relating to any errors encountered during execution. If not provided, a default implementation of the errors class is used internally to provide error handling. Possible errors and warning messages that may be encountered are as follows. LA_ARRAY_SIZE_ERROR: Occurs if any of the input array sizes are incorrect.

Remarks

This routine allows extraction of the actual "L", "U", and "P" matrices of the decomposition. To use these matrices to solve the system \( A X = B \), the following approach is used.

1. First, solve the linear system: \( L Y = P B \) for \( Y \).
2. Second, solve the linear system: \( U X = Y \) for \( X \).

Notice, as both L and U are triangular in structure, the above equations can be solved by forward and backward substitution.

See Also

• Wikipedia
• Wolfram MathWorld

Usage

The following example illustrates how to extract the L, U, and P matrices in order to solve a system of LU factored equations.

program example
    use iso_fortran_env, only : real64, int32
    use linalg
    implicit none
 
    ! Variables
    real(real64) :: a(3,3), b(3), u(3,3), p(3,3)
    integer(int32) :: i, pvt(3)
 
    ! Build the 3-by-3 matrix A.
    !     | 1   2   3 |
    ! A = | 4   5   6 |
    !     | 7   8   0 |
    a = reshape( &
        [1.0d0, 4.0d0, 7.0d0, 2.0d0, 5.0d0, 8.0d0, 3.0d0, 6.0d0, 0.0d0], &
        [3, 3])
 
    ! Build the right-hand-side vector B.
    !     | -1 |
    ! b = | -2 |
    !     | -3 |
    b = [-1.0d0, -2.0d0, -3.0d0]
 
    ! The solution is:
    !     |  1/3 |
    ! x = | -2/3 |
    !     |   0  |
 
    ! Compute the LU factorization
    call lu_factor(a, pvt)
 
    ! Extract the L and U matrices. A is overwritten with L.
    call form_lu(a, pvt, u, p)
 
    ! Solve the lower triangular system L * Y = P * B for Y, but first compute
    ! P * B, and store the results in B
    b = matmul(p, b)
 
    ! Now, compute the solution to the lower triangular system.  Store the
    ! result in B.  Remember, L is unit diagonal (ones on its diagonal)
    call solve_triangular_system(.false., .false., .false., a, b)
 
    ! Solve the upper triangular system U * X = Y for X.
    call solve_triangular_system(.true., .false., .true., u, b)
 
    ! Display the results.
    print '(A)', "LU Solution: X = "
    print '(F8.4)', (b(i), i = 1, size(b))
end program

The above program produces the following output.

LU Solution: X =
0.3333
-0.6667
0.0000

Definition at line 967 of file linalg.f90.

---

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

• D:/Code/linalg/src/linalg.f90