# dblgglyap - Man Page

## Name

dblgglyap — Double Precision

— Double precision solvers for generalized Lyapunov and Stein equations with general coefficient matrices.

## Synopsis

### Functions

subroutine **dla_gglyap** (fact, trans, m, a, lda, b, ldb, q, ldq, z, ldz, x, ldx, scale, work, ldwork, info)

Frontend for the solution of Generalized Lyapunov Equations.

subroutine **dla_ggstein** (fact, trans, m, a, lda, b, ldb, q, ldq, z, ldz, x, ldx, scale, work, ldwork, info)

Frontend for the solution of Generalized Stein Equations.

subroutine **dla_gglyap_refine** (trans, guess, m, a, lda, b, ldb, x, ldx, y, ldy, as, ldas, bs, ldbs, q, ldq, z, ldz, maxit, tau, convlog, work, ldwork, info)

Iterative Refinement for the Generalized Lyapunov Equations.

## Detailed Description

Double precision solvers for generalized Lyapunov and Stein equations with general coefficient matrices.

## Function Documentation

### subroutine dla_gglyap (character, dimension(1) fact, character, dimension(1) trans, integer m, double precision, dimension(lda,*) a, integer lda, double precision, dimension(ldb,*) b, integer ldb, double precision, dimension(ldq, *) q, integer ldq, double precision, dimension(ldz,*) z, integer ldz, double precision, dimension(ldx, *) x, integer ldx, double precision scale, double precision, dimension(*) work, integer ldwork, integer info)

Frontend for the solution of Generalized Lyapunov Equations.

**Purpose:**

!> DLA_GGLYAP solves a generalized Lyapunov equation of the following forms !> !> A * X * B^T + B * X * A^T = SCALE * Y (1) !> !> or !> !> A^T * X * B + B^T * X * A = SCALE * Y (2) !> !> where (A,B) is a M-by-M matrix pencil. The right hand side Y and the solution X are !> M-by-M matrices. The matrix pencil (A,B) is either in general form, in generalized !> Hessenberg form, or in generalized Schur form where Q and Z also need to be provided. !> !>

**Parameters***FACT*!> FACT is CHARACTER !> Specifies how the matrix A is given. !> == 'N': The matrix pencil (A,B) is given as a general matrix pencil and its Schur decomposition !> A = Q*S*Z**T, B = Q*R*Z**T will be computed. !> == 'F': The matrix A is given as its Schur decomposition in terms of S and Q !> form A = Q*S*Q**T !> == 'H': The matrix pencil (A,B) is given in generalized Hessenberg form and its Schur decomposition !> A = Q*S*Z**T, B = Q*R*Z**T will be computed. !>

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

*M*!> M is INTEGER !> The order of the matrices A, B, Y and X. M >= 0. !>

*A*!> A is DOUBLE PRECISION array, dimension (LDA,M) !> If FACT == , the matrix A is a general matrix and it is overwritten with the !> quasi upper triangular matrix S of the generalized schur decomposition. !> If FACT == , the matrix A contains its (quasi-) upper triangular matrix S of the !> generalized Schur decomposition of (A,B). !> If FACT == , the matrix A is an upper Hessenberg matrix of the generalized !> Hessenberg form (A,B) and it is overwritten with the quasi upper triangular matrix S !> of the generalized Schur decomposition. !>

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

*B*!> B is DOUBLE PRECISION array, dimension (LDB,M) !> If FACT == , the matrix B a general matrix and it is overwritten with the upper triangular !> matrix of the generalized Schur decomposition. !> If FACT == , the matrix B contains its upper triangular matrix R of the generalized schur !> Schur decomposition of (A,B). !> If FACT == , the matrix B is the upper triangular matrix of the generalized Hessenberg form !> (A,B) and it is overwritten with the upper triangular matrix of the generalized Schur decomposition. !>

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

*Q*!> Q is DOUBLE PRECISION array, dimension (LDQ,M) !> If FACT == , the matrix Q is an empty M-by-M matrix on input and contains the !> left Schur vectors of (A,B) on output. !> If FACT == , the matrix Q contains the left Schur vectors of (A,B). !> If FACT == , the matrix Q is an empty M-by-M matrix on input and contains the !> left Schur vectors of (A,B) on output. !>

*LDQ*!> LDQ is INTEGER !> The leading dimension of the array Q. LDQ >= max(1,M). !>

*Z*!> Z is DOUBLE PRECISION array, dimension (LDZ,M) !> If FACT == , the matrix Z is an empty M-by-M matrix on input and contains the !> right Schur vectors of (A,B) on output. !> If FACT == , the matrix Z contains the right Schur vectors of (A,B). !> If FACT == , the matrix Z is an empty M-by-M matrix on input and contains the !> right Schur vectors of (A,B) on output. !>

*LDZ*!> LDZ is INTEGER !> The leading dimension of the array Z. LDZ >= max(1,M). !>

*X*!> X is DOUBLE PRECISION 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. LDX >= max(1,M). !>

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

*WORK*!> WORK is DOUBLE PRECISION array, dimension (MAX(1,LDWORK)) !> Workspace for the algorithm. The optmimal workspace is given either by \ref mepack_memory_frontend !> or a previous call to the this routine with LDWORK === -1. !>

*LDWORK*!> LDWORK is INTEGER !> Size of the workspace for the algorithm. This can be determined by a call \ref mepack_memory_frontend . !> Alternatively, if LDWORK == -1 on input, the subroutine will return the required size of the workspace in LDWORK !> without performing any computations. !>

*INFO*!> INFO is INTEGER !> == 0: successful exit !> = 1: DGGES failed !> = 2: DLA_SORT_GEV failed !> = 3: Inner solver failed !> < 0: if INFO = -i, the i-th argument had an illegal value !>

**See also**DLA_TGLYAP_L3

DLA_TGLYAP_L3_2S

DLA_TGLYAP_DAG

DLA_TGLYAP_L2

DLA_TGLYAP_RECURSIVE

**Author**Martin Koehler, MPI Magdeburg

**Date**January 2024

Definition at line **207** of file **dla_gglyap.f90**.

### subroutine dla_gglyap_refine (character, dimension(1) trans, character, dimension(1) guess, integer m, double precision, dimension(lda, *) a, integer lda, double precision, dimension(ldb, *) b, integer ldb, double precision, dimension( ldx, *) x, integer ldx, double precision, dimension(ldy, *) y, integer ldy, double precision, dimension(ldas, *) as, integer ldas, double precision, dimension(ldbs,*) bs, integer ldbs, double precision, dimension(ldq, *) q, integer ldq, double precision, dimension(ldz, *) z, integer ldz, integer maxit, double precision tau, double precision, dimension(*) convlog, double precision, dimension(*) work, integer ldwork, integer info)

Iterative Refinement for the Generalized Lyapunov Equations.

**Purpose:**

!> DLA_GGLYAP_REFINE solves a generalized Lyapunov equation of the following forms !> !> A * X * B^T + B * X * A^T = SCALE * Y (1) !> !> or !> !> A^T * X * B + B^T * X * A = SCALE * Y (2) !> !> where (A,B) is a M-by-M matrix pencil using iterative refinement. !> The right hand side Y and the solution X are !> M-by-M matrices. The matrix pencil (A,B) needs to provide as the original data !> as well as in generalized Schur decomposition since both are required in the !> iterative refinement process. !> !>

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

*GUESS*!> GUESS is CHARACTER !> Specifies whether X contains an initial guess or nor not. !> = 'I': X contains an initial guess !> = 'N': No initial guess, X is set to zero at the begin of the iteration. !>

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

*A*!> A is DOUBLE PRECISION array, dimension (LDA,M) !> The array A contains the original matrix A defining the eqaution. !>

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

*B*!> B is DOUBLE PRECISION array, dimension (LDB,M) !> The array B contains the original matrix B defining the eqaution. !>

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

*X*!> X is DOUBLE PRECISION array, dimension (LDX,M) !> On input, the array X contains the initial guess, if GUESS = 'I'. !> On output, the array X contains the solution X. !>

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

*Y*!> Y is DOUBLE PRECISION array, dimension (LDY,M) !> On input, the array Y contains the right hand side Y. !> The array stays unchanged during the iteration. !>

*LDY*!> LDY is INTEGER !> The leading dimension of the array Y. LDY >= max(1,M). !>

*AS*!> AS is DOUBLE PRECISION array, dimension (LDAS,M) !> The array AS contains the generalized Schur decomposition of the !> A. !>

*LDAS*!> LDAS is INTEGER !> The leading dimension of the array AS. LDAS >= max(1,M). !>

*BS*!> BS is DOUBLE PRECISION array, dimension (LDBS,M) !> The array AS contains the generalized Schur decomposition of the !> B. !>

*LDBS*!> LDBS is INTEGER !> The leading dimension of the array BS. LDBS >= max(1,M). !>

*Q*!> Q is DOUBLE PRECISION array, dimension (LDQ,M) !> The array Q contains the left generalized Schur vectors for (A,B) as returned by DGGES. !>

*LDQ*!> LDQ is INTEGER !> The leading dimension of the array Q. LDQ >= max(1,M). !>

*Z*!> Z is DOUBLE PRECISION array, dimension (LDZ,M) !> The array Z contains the right generalized Schur vectors for (A,B) as returned by DGGES. !>

*LDZ*!> LDZ is INTEGER !> The leading dimension of the array Z. LDZ >= max(1,M). !>

*MAXIT*!> MAXIT is INTEGER !> On input, MAXIT contains the maximum number of iteration that are performed, 2 <= MAXIT <= 100 !> On exit, MAXIT contains the number of iteration steps taken by the algorithm. !>

*TAU*!> TAU is DOUBLE PRECISION !> On input, TAU contains the additional security factor for the stopping criterion, typical values are 0.1 !> On exit, TAU contains the last relative residual when the stopping criterion got valid. !>

*CONVLOG*!> CONVLOG is DOUBLE PRECISION array, dimension (MAXIT) !> The CONVLOG array contains the convergence history of the iterative refinement. CONVLOG(I) contains the maximum !> relative residual before it is solved for the I-th time. !>

*WORK*!> WORK is DOUBLE PRECISION array, dimension (MAX(1,LDWORK)) !> Workspace for the algorithm. The optmimal workspace is returned in LDWORK, if LDWORK == -1 on input. In this !> case no computations are performed. !>

*LDWORK*!> LDWORK is INTEGER !> If LDWORK == -1 the subroutine will return the required size of the workspace in LDWORK on exit. No computations are !> performed and none of the arrays are referenced. !>

*INFO*!> INFO is INTEGER !> == 0: Success !> > 0: Iteration failed in step INFO !> < 0: if INFO = -i, the i-th argument had an illegal value !> = -50: Some of the internal settings like NB,... are incorrect. !>

**See also**DLA_TGLYAP_L3

DLA_TGLYAP_L2

DLA_TGLYAP_L3_2S

DLA_TGLYAP_DAG

DLA_TGLYAP_RECURSIVE

**Author**Martin Koehler, MPI Magdeburg

**Date**January 2024

Definition at line **244** of file **dla_gglyap_refine.f90**.

### subroutine dla_ggstein (character, dimension(1) fact, character, dimension(1) trans, integer m, double precision, dimension(lda,*) a, integer lda, double precision, dimension(ldb,*) b, integer ldb, double precision, dimension(ldq, *) q, integer ldq, double precision, dimension(ldz,*) z, integer ldz, double precision, dimension(ldx, *) x, integer ldx, double precision scale, double precision, dimension(*) work, integer ldwork, integer info)

Frontend for the solution of Generalized Stein Equations.

**Purpose:**

!> DLA_GGSTEIN solves a generalized Stein equation of the following forms !> !> A * X * A^T - B * X * B^T = SCALE * Y (1) !> !> or !> !> A^T * X * A - B^T * X * B = SCALE * Y (2) !> !> where (A,B) is a M-by-M matrix pencil. The right hand side Y and the solution X !> M-by-M matrices. The matrix pencil (A,B) is either in general form, in generalized !> Hessenberg form, or in generalized Schur form where Q and Z also need to be provided. !> !>

**Parameters***FACT*!> FACT is CHARACTER !> Specifies how the matrix A is given. !> == 'N': The matrix pencil (A,B) is given as a general matrix pencil and its Schur decomposition !> A = Q*S*Z**T, B = Q*R*Z**T will be computed. !> == 'F': The matrix A is given as its Schur decomposition in terms of S and Q !> form A = Q*S*Q**T !> == 'H': The matrix pencil (A,B) is given in generalized Hessenberg form and its Schur decomposition !> A = Q*S*Z**T, B = Q*R*Z**T will be computed. !>

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

*M*!> M is INTEGER !> The order of the matrices A, B, Y and X. M >= 0. !>

*A*!> A is DOUBLE PRECISION array, dimension (LDA,M) !> If FACT == , the matrix A is a general matrix and it is overwritten with the !> quasi upper triangular matrix S of the generalized schur decomposition. !> If FACT == , the matrix A contains its (quasi-) upper triangular matrix S of the !> generalized Schur decomposition of (A,B). !> If FACT == , the matrix A is an upper Hessenberg matrix of the generalized !> Hessenberg form (A,B) and it is overwritten with the quasi upper triangular matrix S !> of the generalized Schur decomposition. !>

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

*B*!> B is DOUBLE PRECISION array, dimension (LDB,M) !> If FACT == , the matrix B a general matrix and it is overwritten with the upper triangular !> matrix of the generalized Schur decomposition. !> If FACT == , the matrix B contains its upper triangular matrix R of the generalized schur !> Schur decomposition of (A,B). !> If FACT == , the matrix B is the upper triangular matrix of the generalized Hessenberg form !> (A,B) and it is overwritten with the upper triangular matrix of the generalized Schur decomposition. !>

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

*Q*!> Q is DOUBLE PRECISION array, dimension (LDQ,M) !> If FACT == , the matrix Q is an empty M-by-M matrix on input and contains the !> left Schur vectors of (A,B) on output. !> If FACT == , the matrix Q contains the left Schur vectors of (A,B). !> If FACT == , the matrix Q is an empty M-by-M matrix on input and contains the !> left Schur vectors of (A,B) on output. !>

*LDQ*!> LDQ is INTEGER !> The leading dimension of the array Q. LDQ >= max(1,M). !>

*Z*!> Z is DOUBLE PRECISION array, dimension (LDZ,M) !> If FACT == , the matrix Z is an empty M-by-M matrix on input and contains the !> right Schur vectors of (A,B) on output. !> If FACT == , the matrix Z contains the right Schur vectors of (A,B). !> If FACT == , the matrix Z is an empty M-by-M matrix on input and contains the !> right Schur vectors of (A,B) on output. !>

*LDZ*!> LDZ is INTEGER !> The leading dimension of the array Z. LDZ >= max(1,M). !>

*X*!> X is DOUBLE PRECISION 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. LDX >= max(1,M). !>

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

*WORK*!> WORK is DOUBLE PRECISION array, dimension (MAX(1,LDWORK)) !> Workspace for the algorithm. The optmimal workspace is given either by \ref mepack_memory_frontend !> or a previous call to the this routine with LDWORK === -1. !>

*LDWORK*!> LDWORK is INTEGER !> Size of the workspace for the algorithm. This can be determined by a call \ref mepack_memory_frontend . !> Alternatively, if LDWORK == -1 on input the subroutine will return the required size of the workspace in LDWORK !> without performing any computations. !>

*INFO*!> INFO is INTEGER !> == 0: successful exit !> = 1: DGGES failed !> = 2: DLA_SORT_GEV failed !> = 3: Inner solver failed !> < 0: if INFO = -i, the i-th argument had an illegal value !>

**See also**DLA_TGSTEIN_L3

DLA_TGSTEIN_L3_2S

DLA_TGSTEIN_DAG

DLA_TGSTEIN_L2

DLA_TGSTEIN_RECURSIVE

**Author**Martin Koehler, MPI Magdeburg

**Date**January 2024

Definition at line **208** of file **dla_ggstein.f90**.

## Author

Generated automatically by Doxygen for MEPACK from the source code.