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.