sgltrlyap - Man Page

subroutine sla_trlyap_dag (trans, m, a, lda, x, ldx, scale, work, info)
DAG Scheduled Bartels-Stewart Algorithm for the standard Lyapunov Equation.
subroutine sla_trstein_dag (trans, m, a, lda, x, ldx, scale, work, info)
Level-3 Bartels-Stewart Algorithm for the Stein equation.
subroutine sla_trlyap_kernel_44n (m, a, lda, x, ldx, scale, info)
Solver for a 4x4 standard Lyapunov equation (TRANS = N)
subroutine sla_trlyap_kernel_44t (m, a, lda, x, ldx, scale, info)
Solver for a 4x4 standard Lyapunov equation (TRANS = T)
subroutine sla_trlyap_l2 (transa, m, a, lda, x, ldx, scale, work, info)
Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation.
subroutine sla_trlyap_l2_opt (transa, m, a, lda, x, ldx, scale, work, info)
Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation (Optimized)
subroutine sla_trstein_l2 (trans, m, a, lda, x, ldx, scale, work, info)
Level-2 Bartels-Stewart Algorithm for the Stein equation.
subroutine sla_trlyap_l3 (trans, m, a, lda, x, ldx, scale, work, info)
Level-3 Bartels-Stewart Algorithm for the standard Lyapunov Equation.
subroutine sla_trlyap_l3_2s (trans, m, a, lda, x, ldx, scale, work, info)
Level-3 Bartels-Stewart Algorithm for the standard Lyapunov Equation with 2 stage blocking.
subroutine sla_trstein_l3 (trans, m, a, lda, x, ldx, scale, work, info)
Level-3 Bartels-Stewart Algorithm for the Stein equation.
subroutine sla_trstein_l3_2s (trans, m, a, lda, x, ldx, scale, work, info)
Level-3 Bartels-Stewart Algorithm for the Stein equation with 2 stage blocking.
recursive subroutine sla_trlyap_recursive (trans, m, a, lda, x, ldx, scale, work, info)
Level-3 Recursive Blocked Algorithm for the standard Lyapunov Equation.
recursive subroutine sla_trstein_recursive (trans, m, a, lda, x, ldx, scale, work, info)
Recursive Blocked Algorithm for the Stein equation.

DAG Scheduled Bartels-Stewart Algorithm for the standard Lyapunov Equation.

Purpose:

!> SLA_TRLYAP_DAG solves a Lyapunov equation of the following forms
!>
!>    A  * X  +  X * A**T = SCALE * Y                              (1)
!>
!> or
!>
!>    A ** T * X  +  X * A = SCALE * Y                              (2)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
!> is generated by SGEES from LAPACK.
!>

Remarks

The algorithm is implemented using DAG Scheduling

Parameters

TRANS

!>          TRANS is CHARACTER(1)
!>          Specifies the form of the system of equations with respect to A:
!>          == 'N':  op1(A) = A
!>          == 'T':  op1(A) = A**T
!>

M

!>          M is INTEGER
!>          The order of the matrices A and C.  M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          Right hand side Y and the solution X are symmetric M-by-M matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDB >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCALE <= 1 holds true.
!>

WORK

!>          WORK is REAL array, dimension LWORK
!>          Workspace for the algorithm.
!>          The workspace needs to queried before the running the computation.
!>          The query is performed by calling the subroutine with INFO == -1 on input.
!>          The required workspace is then returned in INFO.
!>

INFO

!>          INFO is INTEGER
!>
!>          On input:
!>            == -1 : Perform a workspace query
!>            <> -1: normal operation
!>
!>          On exit, workspace query:
!>            < 0 :  if INFO = -i, the i-th argument had an illegal value
!>            >= 0:  The value of INFO is the required number of elements in the workspace.
!>
!>          On exit, normal operation:
!>            == 0:  successful exit
!>            < 0:  if INFO = -i, the i-th argument had an illegal value
!>            > 0:  The equation is not solved correctly. One of the arising inner
!>                  system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 137 of file sla_trlyap_dag.f90.

Solver for a 4x4 standard Lyapunov equation (TRANS = N)

Purpose:

!>
!> SLA_TRLYAP_KERNEL_44N solves a Lyapunov  equation of the following form
!>
!>    A * X  + X * A**T = SCALE * Y                              (1)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> The right hand side Y and the solution X M-by-M matrices.
!> Typically the matrix  A is created by SGEES from LAPACK.
!> The algorithm is implemented without BLAS level 2
!> operations. Thereby the order of M and N is at most 4. Furthermore, for fast execution
!> the function does not check the input arguments.
!>
!>

Parameters

M

!>          M is INTEGER
!>          The order of the matrices A and C.  4 >= M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          as selected by TRANSA, TRANSB, and SGN.
!>          Right hand side Y and the solution X are M-by-N matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDB >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCAL <= 1 holds true.
!>

INFO

!>          INFO is INTEGER
!>          On output:
!>          == 0:  successful exit
!>          < 0:  if INFO = -i, the i-th argument had an illegal value
!>          > 0:  The equation is not solved correctly. One of the arising inner
!>                system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 109 of file sla_trlyap_kernel_44_n.f90.

Solver for a 4x4 standard Lyapunov equation (TRANS = T)

Purpose:

!>
!> SLA_TRLYAP_KERNEL_44T solves a Lyapunov  equation of the following form
!>
!>    A **T * X  + X * A = SCALE * Y                              (1)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> The right hand side Y and the solution X M-by-M matrices.
!> Typically the matrix  A is created by SGEES from LAPACK.
!> The algorithm is implemented without BLAS level 2
!> operations. Thereby the order of M and N is at most 4. Furthermore, for fast execution
!> the function does not check the input arguments.
!>
!>

Parameters

M

!>          M is INTEGER
!>          The order of the matrices A and C.  4 >= M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          as selected by TRANSA, TRANSB, and SGN.
!>          Right hand side Y and the solution X are M-by-N matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDB >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCAL <= 1 holds true.
!>

INFO

!>          INFO is INTEGER
!>          On output:
!>          == 0:  successful exit
!>          < 0:  if INFO = -i, the i-th argument had an illegal value
!>          > 0:  The equation is not solved correctly. One of the arising inner
!>                system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 109 of file sla_trlyap_kernel_44_t.f90.

Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation.

Purpose:

!>
!> SLA_TRLYAP_L2 solves a Lyapunov equation of the following forms
!>
!>    A * X  +  X * A**T = SCALE * Y                              (1)
!>
!> or
!>
!>    A **T * X  -  X * A = SCALE * Y                              (2)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
!> is generated by SGEES from LAPACK.
!>

Remarks

The algorithm is implemented using BLAS level 2 operations.

The transposed case (2) is optimized w.r.t. to the usage of the SSYR2 operation.

Parameters

TRANSA

!>          TRANSA is CHARACTER(1)
!>          Specifies the form of the system of equations with respect to A:
!>          == 'N':  op1(A) = A
!>          == 'T':  op1(A) = A**T
!>

M

!>          M is INTEGER
!>          The order of the matrices A and C.  M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          Right hand side Y and the solution X are symmetric M-by-M matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDB >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCALE <= 1 holds true.
!>

WORK

!>          WORK is REAL array, dimension LWORK
!>          Workspace for the algorithm.
!>          The workspace needs to queried before the running the computation.
!>          The query is performed by calling the subroutine with INFO == -1 on input.
!>          The required workspace is then returned in INFO.
!>

INFO

!>          INFO is INTEGER
!>
!>          On input:
!>            == -1 : Perform a workspace query
!>            <> -1: normal operation
!>
!>          On exit, workspace query:
!>            < 0 :  if INFO = -i, the i-th argument had an illegal value
!>            >= 0:  The value of INFO is the required number of elements in the workspace.
!>
!>          On exit, normal operation:
!>            == 0:  successful exit
!>            < 0:  if INFO = -i, the i-th argument had an illegal value
!>            > 0:  The equation is not solved correctly. One of the arising inner
!>                  system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 138 of file sla_trlyap_l2.f90.

Level-2 Bartels-Stewart Algorithm for the Lyapunov Equation (Optimized)

Purpose:

!>
!> SLA_TRLYAP_L2 solves a Lyapunov equation of the following forms
!>
!>    A * X  +  X * A**T = SCALE * Y                              (1)
!>
!> or
!>
!>    A **T * X  -  X * A = SCALE * Y                              (2)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
!> is generated by SGEES from LAPACK.
!>

Remarks

The algorithm is implemented using BLAS level 2 operations.

The transposed case (2) is optimized w.r.t. to the usage of the SSYR2 operation.

Parameters

TRANSA

!>          TRANSA is CHARACTER(1)
!>          Specifies the form of the system of equations with respect to A:
!>          == 'N':  op1(A) = A
!>          == 'T':  op1(A) = A**T
!>

M

!>          M is INTEGER
!>          The order of the matrices A and C.  M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          Right hand side Y and the solution X are symmetric M-by-M matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDB >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCALE <= 1 holds true.
!>

WORK

!>          WORK is REAL array, dimension LWORK
!>          Workspace for the algorithm.
!>          The workspace needs to queried before the running the computation.
!>          The query is performed by calling the subroutine with INFO == -1 on input.
!>          The required workspace is then returned in INFO.
!>

INFO

!>          INFO is INTEGER
!>
!>          On input:
!>            == -1 : Perform a workspace query
!>            <> -1: normal operation
!>
!>          On exit, workspace query:
!>            < 0 :  if INFO = -i, the i-th argument had an illegal value
!>            >= 0:  The value of INFO is the required number of elements in the workspace.
!>
!>          On exit, normal operation:
!>            == 0:  successful exit
!>            < 0:  if INFO = -i, the i-th argument had an illegal value
!>            > 0:  The equation is not solved correctly. One of the arising inner
!>                  system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 138 of file sla_trlyap_l2_opt.f90.

Level-3 Bartels-Stewart Algorithm for the standard Lyapunov Equation.

Purpose:

!> SLA_TRLYAP_L3 solves a Lyapunov equation of the following forms
!>
!>    A  * X  +  X * A**T = SCALE * Y                              (1)
!>
!> or
!>
!>    A ** T * X  +  X * A = SCALE * Y                              (2)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
!> is generated by SGEES from LAPACK.
!>

Remarks

The algorithm is implemented using BLAS level 3 operations.

Parameters

TRANS

!>          TRANS is CHARACTER
!>          Specifies the form of the system of equations with respect to A:
!>          == 'N':  op1(A) = A
!>          == 'T':  op1(A) = A**T
!>

M

!>          M is INTEGER
!>          The order of the matrices A and C.  M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          Right hand side Y and the solution X are symmetric M-by-M matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDB >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCALE <= 1 holds true.
!>

WORK

!>          WORK is REAL array, dimension LWORK
!>          Workspace for the algorithm.
!>          The workspace needs to queried before the running the computation.
!>          The query is performed by calling the subroutine with INFO == -1 on input.
!>          The required workspace is then returned in INFO.
!>

INFO

!>          INFO is INTEGER
!>
!>          On input:
!>            == -1 : Perform a workspace query
!>            <> -1: normal operation
!>
!>          On exit, workspace query:
!>            < 0 :  if INFO = -i, the i-th argument had an illegal value
!>            >= 0:  The value of INFO is the required number of elements in the workspace.
!>
!>          On exit, normal operation:
!>            == 0:  successful exit
!>            < 0:  if INFO = -i, the i-th argument had an illegal value
!>            > 0:  The equation is not solved correctly. One of the arising inner
!>                  system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 137 of file sla_trlyap_l3.f90.

Level-3 Bartels-Stewart Algorithm for the standard Lyapunov Equation with 2 stage blocking.

Purpose:

!> SLA_TRLYAP_L3_2S solves a Lyapunov equation of the following forms
!>
!>    A  * X  +  X * A**T = SCALE * Y                              (1)
!>
!> or
!>
!>    A ** T * X  +  X * A = SCALE * Y                              (2)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
!> is generated by SGEES from LAPACK.
!>

Remarks

The algorithm is implemented using BLAS level 3 operations and DAG schedule block solves.

Parameters

TRANS

!>          TRANS is CHARACTER
!>          Specifies the form of the system of equations with respect to A:
!>          == 'N':  op1(A) = A
!>          == 'T':  op1(A) = A**T
!>

M

!>          M is INTEGER
!>          The order of the matrices A and C.  M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          Right hand side Y and the solution X are symmetric M-by-M matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDB >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCALE <= 1 holds true.
!>

WORK

!>          WORK is REAL array, dimension LWORK
!>          Workspace for the algorithm.
!>          The workspace needs to queried before the running the computation.
!>          The query is performed by calling the subroutine with INFO == -1 on input.
!>          The required workspace is then returned in INFO.
!>

INFO

!>          INFO is INTEGER
!>
!>          On input:
!>            == -1 : Perform a workspace query
!>            <> -1: normal operation
!>
!>          On exit, workspace query:
!>            < 0 :  if INFO = -i, the i-th argument had an illegal value
!>            >= 0:  The value of INFO is the required number of elements in the workspace.
!>
!>          On exit, normal operation:
!>            == 0:  successful exit
!>            < 0:  if INFO = -i, the i-th argument had an illegal value
!>            > 0:  The equation is not solved correctly. One of the arising inner
!>                  system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 137 of file sla_trlyap_l3_2stage.f90.

Level-3 Recursive Blocked Algorithm for the standard Lyapunov Equation.

Purpose:

!> SLA_TRLYAP_RECURSIVE solves a Lyapunov equation of the following forms
!>
!>    A  * X  +  X * A**T = SCALE * Y                              (1)
!>
!> or
!>
!>    A ** T * X  +  X * A = SCALE * Y                              (2)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> The right hand side Y and the solution X are M-by-N matrices.  Typically the matrix A
!> is generated by SGEES from LAPACK.
!>

Remarks

The algorithm is implemented using BLAS level 3 operations and recursive blocking.

Parameters

TRANS

!>          TRANS is CHARACTER(1)
!>          Specifies the form of the system of equations with respect to A:
!>          == 'N':  op1(A) = A
!>          == 'T':  op1(A) = A**T
!>

M

!>          M is INTEGER
!>          The order of the matrices A and C.  M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          Right hand side Y and the solution X are symmetric M-by-M matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDB >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCALE <= 1 holds true.
!>

WORK

!>          WORK is REAL array, dimension 1
!>          Workspace for the algorithm
!>

INFO

!>          INFO is INTEGER
!>          == 0:  successful exit
!>          < 0:  if INFO = -i, the i-th argument had an illegal value
!>          > 0:  The equation is not solved correctly. One of the arising inner
!>                system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 125 of file sla_trlyap_recursive.f90.

Level-3 Bartels-Stewart Algorithm for the Stein equation.

Purpose:

!>
!> SLA_TRSTEIN_DAG solves a Stein equation of the following forms
!>
!>    A * X * A^T - X  = SCALE * Y                                              (2)
!>
!> or
!>
!>    A^T * X * A - X  =  SCALE * Y                                             (1)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> and X and Y are symmetric  M-by-M matrices.
!> Typically the matrix A is created by SGEES from LAPACK.
!>

Attention

The algorithm is implemented using BLAS level 3 operations.

Remarks

The algorithm is implemented using DAG Scheduling

Parameters

TRANS

!>          TRANS is CHARACTER(1)
!>          Specifies the form of the system of equations with respect to A and C:
!>          == 'N':  Equation (1) is solved.
!>          == 'T':  Equation (2) is solved.
!>

M

!>          M is INTEGER
!>          The order of the matrices A and C.  M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          as selected by TRANSA, TRANSB, and SGN.
!>          Right hand side Y and the solution X are M-by-N matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDX >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCALE <= 1 holds true.
!>

WORK

!>          WORK is REAL array, dimension LWORK
!>          Workspace for the algorithm.
!>          The workspace needs to queried before the running the computation.
!>          The query is performed by calling the subroutine with INFO == -1 on input.
!>          The required workspace is then returned in INFO.
!>

INFO

!>          INFO is INTEGER
!>
!>          On input:
!>            == -1 : Perform a workspace query
!>            <> -1: normal operation
!>
!>          On exit, workspace query:
!>            < 0 :  if INFO = -i, the i-th argument had an illegal value
!>            >= 0:  The value of INFO is the required number of elements in the workspace.
!>
!>          On exit, normal operation:
!>            == 0:  successful exit
!>            < 0:  if INFO = -i, the i-th argument had an illegal value
!>            > 0:  The equation is not solved correctly. One of the arising inner
!>                  system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 142 of file sla_trstein_dag.f90.

Level-2 Bartels-Stewart Algorithm for the Stein equation.

Purpose:

!>
!> SLA_TRSTEIN_L2 solves a generalized Lyapunov  equation of the following forms
!>
!>    A * X * A^T - X  = SCALE * Y                                              (2)
!>
!> or
!>
!>    A^T * X * A - X  =  SCALE * Y                                             (1)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> and X and Y are symmetric  M-by-M matrices.
!> Typically the matrix A is created by SGEES from LAPACK.
!>

Attention

The algorithm is implemented using BLAS level 2 operations.

Parameters

TRANS

!>          TRANS is CHARACTER(1)
!>          Specifies the form of the system of equations with respect to A and C:
!>          == 'N':  Equation (1) is solved.
!>          == 'T':  Equation (2) is solved.
!>

M

!>          M is INTEGER
!>          The order of the matrices A and C.  M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          as selected by TRANSA, TRANSB, and SGN.
!>          Right hand side Y and the solution X are M-by-N matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDX >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCALE <= 1 holds true.
!>

WORK

!>          WORK is REAL array, dimension LWORK
!>          Workspace for the algorithm.
!>          The workspace needs to queried before the running the computation.
!>          The query is performed by calling the subroutine with INFO == -1 on input.
!>          The required workspace is then returned in INFO.
!>

INFO

!>          INFO is INTEGER
!>
!>          On input:
!>            == -1 : Perform a workspace query
!>            <> -1: normal operation
!>
!>          On exit, workspace query:
!>            < 0 :  if INFO = -i, the i-th argument had an illegal value
!>            >= 0:  The value of INFO is the required number of elements in the workspace.
!>
!>          On exit, normal operation:
!>            == 0:  successful exit
!>            < 0:  if INFO = -i, the i-th argument had an illegal value
!>            > 0:  The equation is not solved correctly. One of the arising inner
!>                  system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 143 of file sla_trstein_l2.f90.

Level-3 Bartels-Stewart Algorithm for the Stein equation.

Purpose:

!>
!> SLA_TRSTEIN_L3 solves a standard Stein  equation of the following forms
!>
!>    A * X * A^T - X  = SCALE * Y                                              (2)
!>
!> or
!>
!>    A^T * X * A - X  =  SCALE * Y                                             (1)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> and X and Y are symmetric  M-by-M matrices.
!> Typically the matrix A is created by SGEES from LAPACK.
!>

Attention

The algorithm is implemented using BLAS level 3 operations.

Parameters

TRANS

!>          TRANS is CHARACTER
!>          Specifies the form of the system of equations with respect to A and C:
!>          == 'N':  Equation (1) is solved.
!>          == 'T':  Equation (2) is solved.
!>

M

!>          M is INTEGER
!>          The order of the matrices A and C.  M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          as selected by TRANSA, TRANSB, and SGN.
!>          Right hand side Y and the solution X are M-by-N matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDX >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCALE <= 1 holds true.
!>

WORK

!>          WORK is REAL array, dimension LWORK
!>          Workspace for the algorithm.
!>          The workspace needs to queried before the running the computation.
!>          The query is performed by calling the subroutine with INFO == -1 on input.
!>          The required workspace is then returned in INFO.
!>

INFO

!>          INFO is INTEGER
!>
!>          On input:
!>            == -1 : Perform a workspace query
!>            <> -1: normal operation
!>
!>          On exit, workspace query:
!>            < 0 :  if INFO = -i, the i-th argument had an illegal value
!>            >= 0:  The value of INFO is the required number of elements in the workspace.
!>
!>          On exit, normal operation:
!>            == 0:  successful exit
!>            < 0:  if INFO = -i, the i-th argument had an illegal value
!>            > 0:  The equation is not solved correctly. One of the arising inner
!>                  system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 141 of file sla_trstein_l3.f90.

Level-3 Bartels-Stewart Algorithm for the Stein equation with 2 stage blocking.

Purpose:

!>
!> SLA_TRSTEIN_L3_2S solves a generalized Lyapunov  equation of the following forms
!>
!>    A * X * A^T - X  = SCALE * Y                                              (1)
!>
!> or
!>
!>    A^T * X * A - X  =  SCALE * Y                                             (2)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> and X and Y are symmetric  M-by-M matrices.
!> Typically the matrix A is created by SGEES from LAPACK.
!>

Attention

The algorithm is implemented using BLAS level 3 operations and a DAG scheduled inner solver.

Parameters

TRANS

!>          TRANS is CHARACTER(1)
!>          Specifies the form of the system of equations with respect to A and C:
!>          == 'N':  Equation (1) is solved.
!>          == 'T':  Equation (2) is solved.
!>

M

!>          M is INTEGER
!>          The order of the matrices A and C.  M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          as selected by TRANSA, TRANSB, and SGN.
!>          Right hand side Y and the solution X are M-by-N matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDX >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCALE <= 1 holds true.
!>

WORK

!>          WORK is REAL array, dimension LWORK
!>          Workspace for the algorithm.
!>          The workspace needs to queried before the running the computation.
!>          The query is performed by calling the subroutine with INFO == -1 on input.
!>          The required workspace is then returned in INFO.
!>

INFO

!>          INFO is INTEGER
!>
!>          On input:
!>            == -1 : Perform a workspace query
!>            <> -1: normal operation
!>
!>          On exit, workspace query:
!>            < 0 :  if INFO = -i, the i-th argument had an illegal value
!>            >= 0:  The value of INFO is the required number of elements in the workspace.
!>
!>          On exit, normal operation:
!>            == 0:  successful exit
!>            < 0:  if INFO = -i, the i-th argument had an illegal value
!>            > 0:  The equation is not solved correctly. One of the arising inner
!>                  system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 141 of file sla_trstein_l3_2stage.f90.

Recursive Blocked Algorithm for the Stein equation.

Purpose:

!>
!> SLA_TRSTEIN_RECURSIVE solves a generalized Lyapunov  equation of the following forms
!>
!>    A * X * A^T - X  = SCALE * Y                                              (2)
!>
!> or
!>
!>    A^T * X * A - X  =  SCALE * Y                                             (1)
!>
!> where A is a M-by-M quasi upper triangular matrix.
!> and X and Y are symmetric  M-by-M matrices.
!> Typically the matrix A is created by SGEES from LAPACK.
!>

Attention

The algorithm is implemented using recursive blocking.

Parameters

TRANS

!>          TRANS is CHARACTER(1)
!>          Specifies the form of the system of equations with respect to A and C:
!>          == 'N':  Equation (1) is solved.
!>          == 'T':  Equation (2) is solved.
!>

M

!>          M is INTEGER
!>          The order of the matrices A and C.  M >= 0.
!>

A

!>          A is REAL array, dimension (LDA,M)
!>          The matrix A must be (quasi-) upper triangular.
!>

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,M).
!>

X

!>          X is REAL array, dimension (LDX,N)
!>          On input, the matrix X contains the right hand side Y.
!>          On output, the matrix X contains the solution of Equation (1) or (2)
!>          as selected by TRANSA, TRANSB, and SGN.
!>          Right hand side Y and the solution X are M-by-N matrices.
!>

LDX

!>          LDX is INTEGER
!>          The leading dimension of the array X.  LDX >= max(1,M).
!>

SCALE

!>          SCALE is REAL
!>          SCALE is a scaling factor to prevent the overflow in the result.
!>          If INFO == 0 then SCALE is 1.0 otherwise if one of the inner systems
!>          could not be solved correctly, 0 < SCALE <= 1 holds true.
!>

WORK

!>          WORK is REAL array, dimension M*N
!>          Workspace for the algorithm.
!>

INFO

!>          INFO is INTEGER
!>          == 0:  successful exit
!>          < 0:  if INFO = -i, the i-th argument had an illegal value
!>          > 0:  The equation is not solved correctly. One of the arising inner
!>                system got singular.
!>

Author

Martin Koehler, MPI Magdeburg

Date

January 2024

Definition at line 129 of file sla_trstein_recursive.f90.