dblggsylv(3)

📦
version 1.1.2 · 3 versions
, in fedora 43

💖 dblggsylv 💖

okay bestie, buckle up — this is the dblggsylv(3) page from MEPACK, and it's giving "double precision, but make it fancy" 💅

✨ NAME ✨

dblggsylv — Double Precision

  • Double Precision routines for standard Sylvester equations.

🦋 SYNOPSIS 🦋

🌸 Functions 🌸

  • subroutine dla_ggcsylv — Frontend for the solution of Coupled Generalized Sylvester Equations.
  • subroutine dla_ggcsylv_dual — Frontend for the solution of the dual Coupled Generalized Sylvester Equations.
  • subroutine dla_ggsylv — Frontend for the solution of Generalized Sylvester Equations.
  • subroutine dla_ggcsylv_dual_refine — Iterative Refinement for the dual Coupled Generalized Sylvester Equations.
  • subroutine dla_ggcsylv_refine — Iterative Refinement for the Coupled Generalized Sylvester Equations.
  • subroutine dla_ggsylv_refine — Iterative Refinement for the Generalized Sylvester Equations.

🎀 the actual signatures, verbatim, no notes 🎀

subroutine dla_ggcsylv (facta, factb, transa, transb, sgn1, sgn2, m, n,
    a, lda, b, ldb, c, ldc, d, ldd, qa, ldqa, za, ldza, qb, ldqb, zb,
    ldzb, e, lde, f, ldf, scale, work, ldwork, info)
subroutine dla_ggcsylv_dual (facta, factb, transa, transb, sgn1, sgn2,
    m, n, a, lda, b, ldb, c, ldc, d, ldd, qa, ldqa, za, ldza, qb, ldqb,
    zb, ldzb, e, lde, f, ldf, scale, work, ldwork, info)
subroutine dla_ggsylv (facta, factb, transa, transb, sgn, m, n, a, lda,
    b, ldb, c, ldc, d, ldd, qa, ldqa, za, ldza, qb, ldqb, zb, ldzb, x,
    ldx, scale, work, ldwork, info)
subroutine dla_ggcsylv_dual_refine (transa, transb, guess, sgn1, sgn2,
    m, n, a, lda, b, ldb, c, ldc, d, ldd, r, ldr, l, ldl, e, lde, f,
    ldf, as, ldas, bs, ldbs, cs, ldcs, ds, ldds, q, ldq, z, ldz, u, ldu,
    v, ldv, maxit, tau, convlog, work, ldwork, info)
subroutine dla_ggcsylv_refine (transa, transb, guess, sgn1, sgn2, m, n,
    a, lda, b, ldb, c, ldc, d, ldd, r, ldr, l, ldl, e, lde, f, ldf, as,
    ldas, bs, ldbs, cs, ldcs, ds, ldds, q, ldq, z, ldz, u, ldu, v, ldv,
    maxit, tau, convlog, work, ldwork, info)
subroutine dla_ggsylv_refine (transa, transb, guess, sgn, m, n, a, lda,
    b, ldb, c, ldc, d, ldd, x, ldx, y, ldy, as, ldas, bs, ldbs, cs,
    ldcs, ds, ldds, q, ldq, z, ldz, u, ldu, v, ldv, maxit, tau, convlog,
    work, ldwork, info)

🌈 Detailed Description 🌈

Double Precision routines for standard Sylvester equations.

This subsection contains the solvers for generalized Sylvester equations with general coefficient matrices in double precision arithmetic. The generalized Schur decompositions are computed in double precision with the help of LAPACK. ✨

👑 Function Documentation 👑

💜 subroutine dla_ggcsylv 💜

subroutine dla_ggcsylv (character, dimension(1) facta, character,
    dimension(1) factb, character, dimension(1) transa, character,
    dimension(1) transb, double precision sgn1, double precision sgn2,
    integer m, integer n, double precision, dimension(lda,*) a, integer lda,
    double precision, dimension(ldb, *) b, integer ldb, double precision,
    dimension(ldc, *) c, integer ldc, double precision, dimension(ldd,*) d,
    integer ldd, double precision, dimension(ldqa, *) qa, integer ldqa,
    double precision, dimension(ldza, *) za, integer ldza, double precision,
    dimension(ldqb, *) qb, integer ldqb, double precision, dimension(ldzb,
    *) zb, integer ldzb, double precision, dimension(lde, *) e, integer lde,
    double precision, dimension(ldf,*) f, integer ldf, double precision
    scale, double precision, dimension(*) work, integer ldwork, integer
    info)

Frontend for the solution of Coupled Generalized Sylvester Equations.

⭐ Purpose ⭐

okay so bestie, DLA_GGCSYLV solves a coupled generalized Sylvester equation, and there are two flavors of it:

op1(A) * R  + SGN1 * L  * op2(B) = SCALE * E                              (1)
op1(C) * R  + SGN2 * L  * op2(D) = SCALE * F

where (A,C) is a M-by-M matrix pencil and (B,D) is a N-by-N matrix pencil. The right hand side (E,F) and the solution (R,L) are M-by-N matrix pencils. The pencils (A,C) and (B,D) can be either given as general unreduced matrices, as generalized Hessenberg form, or in terms of their generalized Schur decomposition. If they are given as general matrices or as a generalized Hessenberg form their generalized Schur decomposition will be computed. 💅

🌸 Parameters 🌸

FACTA

FACTA is CHARACTER. Specifies how the matrix pencil (A,C) is given.

  • 'N' — The matrix pencil (A,C) is given as a general matrices and its Schur decomposition A = QA*S*ZA**T, C = QA*R*ZA**T will be computed.
  • 'F' — The matrix pencil (A,C) is already in generalized Schur form and S, R, QA, and ZA are given.
  • 'H' — The matrix pencil (A,C) is given in generalized Hessenberg form and its Schur decomposition A = QA*S*ZA**T, C = QA*R*ZA**T will be computed.

FACTB

FACTB is CHARACTER. Specifies how the matrix pencil (B,D) is given.

  • 'N' — The matrix pencil (B,D) is given as a general matrices and its Schur decomposition B = QB*U*ZB**T, D = QB*V*ZB**T will be computed.
  • 'F' — The matrix pencil (B,D) is already in generalized Schur form and U, V, QB, and ZB are given.
  • 'H' — The matrix pencil (B,D) is given in generalized Hessenberg form and its Schur decomposition B = QB*U*ZB**T, D = QB*V*ZB**T will be computed.

TRANSA

TRANSA is CHARACTER. Specifies the form of the system of equations with respect to A and C:

  • 'N' — op1(A) = A
  • 'T' — op1(A) = A**T

TRANSB

TRANSB is CHARACTER. Specifies the form of the system of equations with respect to B and D:

  • 'N' — op2(B) = B,
  • 'T' — op2(B) = B**T

SGN1

SGN1 is DOUBLE PRECISION, allowed values: +/-1. Specifies the sign between in the first equation. 🫶

SGN2

SGN2 is DOUBLE PRECISION, allowed values: +/-1. Specifies the sign between in the second equation. 🫶

M

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

N

N is INTEGER. The order of the matrices B and D. N >= 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 factor S of the Schur decomposition of (A,C).
  • If FACT == , the matrix A contains its (quasi-) upper triangular matrix S of the Schur decomposition of (A,C).
  • If FACT == , the matrix A is an upper Hessenberg matrix of the generalized Hessenberg form (A,C) and it is overwritten with the (quasi-) upper triangular factor S of the Schur decomposition of (A,C).

LDA

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

B

B is DOUBLE PRECISION array, dimension (LDB,N).

  • If FACT == , the matrix B is a general matrix and it is overwritten with the (quasi-) upper triangular factor U of the Schur decomposition of (B,D).
  • If FACT == , the matrix B contains its (quasi-) upper triangular matrix U of the Schur decomposition of (B,D).
  • If FACT == , the matrix B is an upper Hessenberg matrix of the generalized Hessenberg form (B,D) and it is overwritten with the (quasi-) upper triangular factor U of the Schur decomposition of (B,D).

LDB

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

C

C is DOUBLE PRECISION array, dimension (LDC,M).

  • If FACT == , the matrix C is a general matrix and it is overwritten with the upper triangular factor R of the Schur decomposition of (A,C).
  • If FACT == , the matrix C contains its upper triangular matrix R of the Schur decomposition of (A,C).
  • If FACT == , the matrix C is the upper triangular matrix of the generalized Hessenberg form (A,C) and it is overwritten with the upper triangular factor R of the Schur decomposition of (A,C).

LDC

LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).

D

D is DOUBLE PRECISION array, dimension (LDD,N).

  • If FACT == , the matrix D is a general matrix and it is overwritten with the upper triangular factor V of the Schur decomposition of (B,D).
  • If FACT == , the matrix D contains its upper triangular matrix V of the Schur decomposition of (B,D).
  • If FACT == , the matrix D is the upper triangular matrix of the generalized Hessenberg form (B,D) and it is overwritten with the upper triangular factor V of the Schur decomposition of (B,D).

LDD

LDD is INTEGER. The leading dimension of the array D. LDD >= max(1,N).

QA

QA is DOUBLE PRECISION array, dimension (LDQA,M).

  • If FACT == , the matrix QA is an empty M-by-M matrix on input and contains the left Schur vectors of (A,C) on output.
  • If FACT == , the matrix QA contains the left Schur vectors of (A,C).
  • If FACT == , the matrix QA is an empty M-by-M matrix on input and contains the left Schur vectors of (A,C) on output.

LDQA

LDQA is INTEGER. The leading dimension of the array QA. LDQA >= max(1,M).

ZA

ZA is DOUBLE PRECISION array, dimension (LDZA,M).

  • If FACT == , the matrix ZA is an empty M-by-M matrix on input and contains the right Schur vectors of (A,C) on output.
  • If FACT == , the matrix ZA contains the right Schur vectors of (A,C).
  • If FACT == , the matrix ZA is an empty M-by-M matrix on input and contains the right Schur vectors of (A,C) on output.

LDZA

LDZA is INTEGER. The leading dimension of the array ZA. LDZA >= max(1,M).

QB

  • QB — DOUBLE PRECISION array, dimension (LDQB,N). If FACT == , the matrix QB is an empty N-by-N matrix on input and contains the left Schur vectors of (B,D) on output. If FACT == , the matrix QB contains the left Schur vectors of (B,D). If FACT == , the matrix QB is an empty M-by-M matrix on input and contains the left Schur vectors of (B,D) on output.
  • LDQB — INTEGER. The leading dimension of the array QB. LDQB >= max(1,N).
  • ZB — DOUBLE PRECISION array, dimension (LDZB,N). If FACT == , the matrix ZB is an empty N-by-N matrix on input and contains the right Schur vectors of (B,D) on output. If FACT == , the matrix ZB contains the right Schur vectors of (B,D). If FACT == , the matrix ZB is an empty M-by-M matrix on input and contains the right Schur vectors of (B,D) on output.
  • LDZB — INTEGER. The leading dimension of the array ZB. LDZB >= max(1,N).
  • E — DOUBLE PRECISION array, dimension (LDE,N). On input, the matrix E contains the right hand side E. On output, the matrix E contains the solution R.
  • LDE — INTEGER. The leading dimension of the array E. LDE >= max(1,M).
  • F — DOUBLE PRECISION array, dimension (LDF,N). On input, the matrix F contains the right hand side F. On output, the matrix F contains the solution L.
  • LDF — INTEGER. The leading dimension of the array F. LDF >= max(1,M).
  • SCALE — 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 — 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 — INTEGER. If LDWORK == -1 on input 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 — INTEGER.
    • == 0: successful exit
    • = 1: DHGGES 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_TGCSYLV_DAG
  • DLA_TGCSYLV_LEVEL3
  • DLA_TGCSYLV_L3_2S
  • DLA_TGCSYLV_L2_UNOPT
  • DLA_TGCSYLV_L2
  • DLA_TGCSYLV_L2_REORDER
  • DLA_TGCSYLV_L2_LOCAL_COPY_32
  • DLA_TGCSYLV_L2_LOCAL_COPY_64
  • DLA_TGCSYLV_L2_LOCAL_COPY_96
  • DLA_TGCSYLV_L2_LOCAL_COPY_128
  • DLA_TGCSYLV_L2_LOCAL_COPY

Author ✨

Martin Koehler, MPI Magdeburg

Date 🗓️

October 2025

Definition at line 333 of file dla_ggcsylv.f90.

🦋 subroutine dla_ggcsylv_dual 🦋

subroutine dla_ggcsylv_dual (character, dimension(1) facta, character,
    dimension(1) factb, character, dimension(1) transa, character,
    dimension(1) transb, double precision sgn1, double precision sgn2,
    integer m, integer n, double precision, dimension(lda,*) a, integer lda,
    double precision, dimension(ldb, *) b, integer ldb, double precision,
    dimension(ldc, *) c, integer ldc, double precision, dimension(ldd,*) d,
    integer ldd, double precision, dimension(ldqa, *) qa, integer ldqa,
    double precision, dimension(ldza, *) za, integer ldza, double precision,
    dimension(ldqb, *) qb, integer ldqb, double precision, dimension(ldzb,
    *) zb, integer ldzb, double precision, dimension(lde, *) e, integer lde,
    double precision, dimension(ldf,*) f, integer ldf, double precision
    scale, double precision, dimension(*) work, integer ldwork, integer
    info)

Frontend for the solution of the dual Coupled Generalized Sylvester Equations. bestie, this is the glow-up you asked for 💅

Purpose 🌟

DLA_GGCSYLV_DUAL_L3 solves a generalized coupled Sylvester equation of the following form:

   op1(A)**T * R  + op1(C)**T * L               = SCALE * E                             (1)
   SGN1 * R * op2(B)**T + SGN2 * L * op2(D)** T = SCALE * F

where A and C are M-by-M matrices and B and D are N-by-N matrices. The right hand sides E, F and the solutions R, L are M-by-N matrices. The equation (1) is the dual to the generalized coupled Sylvester equation

   op1(A) * R + SGN1 * L * op2(B)  = SCALE * E                                          (2)
   op1(C) * R + SGN2 * L * op2(D)  = SCALE * F

The equation (1) is the dual one to equation (2) with respect to the underlying linear system. Let Z be the matrix formed by rewriting (2) into its Kronecker form. This yields

         | kron(I, op1(A))   SGN1*kron(op2(B)**T, I) | | Vec R |   | Vec E |
   Z X = |                                           |*|       | = |       |
         | kron(I, op1(C))   SGN2*kron(op2(D)**T, I) | | Vec L |   | Vec F |

Regarding Z**T one obtains

            | kron(I, op1(A)**T )    kron(I, op1(C)**T)   | | Vec R |   | Vec E |
   Z**T X = |                                             |*|       | = |       |
            | SGN1*kron(op2(B), I)   SGN2*kron(op2(D), I) | | Vec L |   | Vec F |

which belongs to the Sylvester equation (1). For this reason the parameters TRANSA and TRANSB are expressed in terms of the Sylvester equation (2).

Parameters 🎀

  • FACTA — CHARACTER. Specifies how the matrix pencil (A,C) is given.
    • == 'N': The matrix pencil (A,C) is given as a general matrices and its Schur decomposition A = QA*S*ZA**T, C = QA*R*ZA**T will be computed.
    • == 'F': The matrix pencil (A,C) is already in generalized Schur form and S, R, QA, and ZA are given.
    • == 'H': The matrix pencil (A,C) is given in generalized Hessenberg form and its Schur decomposition A = QA*S*ZA**T, C = QA*R*ZA**T will be computed.
  • FACTB — CHARACTER. Specifies how the matrix pencil (B,D) is given.
    • == 'N': The matrix pencil (B,D) is given as a general matrices and its Schur decomposition B = QB*U*ZB**T, D = QB*V*ZB**T will be computed.
    • == 'F': The matrix pencil (B,D) is already in generalized Schur form and U, V, QB, and ZB are given.
    • == 'H': The matrix pencil (B,D) is given in generalized Hessenberg form and its Schur decomposition B = QB*U*ZB**T, D = QB*V*ZB**T will be computed.
  • TRANSA — CHARACTER. Specifies the form of the system of equations with respect to A and C:
    • == 'N': op1(A) = A
    • == 'T': op1(A) = A**T
  • TRANSB — CHARACTER. Specifies the form of the system of equations with respect to B and D:
    • == 'N': op2(B) = B,
    • == 'T': op2(B) = B**T
  • SGN1 — DOUBLE PRECISION, allowed values: +/-1. Specifies the sign between in the first equation.
  • SGN2 — DOUBLE PRECISION, allowed values: +/-1. Specifies the sign between in the second equation.
  • M — INTEGER. The order of the matrices A and C. M >= 0.
  • N — INTEGER. The order of the matrices B and D. N >= 0.
  • A — DOUBLE PRECISION array, dimension (LDA,M). If FACT == , the matrix A is a general matrix and it is overwritten with the (quasi-) upper triangular factor S of the Schur decomposition of (A,C). If FACT == , the matrix A contains its (quasi-) upper triangular matrix S of the Schur decomposition of (A,C). If FACT == , the matrix A is an upper Hessenberg matrix of the generalized Hessenberg form (A,C) and it is overwritten with the (quasi-) upper triangular factor S of the Schur decomposition of (A,C).
  • LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,M).
  • B — DOUBLE PRECISION array, dimension (LDB,N). If FACT == , the matrix B is a general matrix and it is overwritten with the (quasi-) upper triangular factor U of the Schur decomposition of (B,D). If FACT == , the matrix B contains its (quasi-) upper triangular matrix U of the Schur decomposition of (B,D). If FACT == , the matrix B is an upper Hessenberg matrix of the generalized Hessenberg form (B,D) and it is overwritten with the (quasi-) upper triangular factor U of the Schur decomposition of (B,D).
  • LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
  • C — DOUBLE PRECISION array, dimension (LDC,M). If FACT == , the matrix C is a general matrix and it is overwritten with the upper triangular factor R of the Schur decomposition of (A,C). If FACT == , the matrix C contains its upper triangular matrix R of the Schur decomposition of (A,C). If FACT == , the matrix C is the upper triangular matrix of the generalized Hessenberg form (A,C) and it is overwritten with the upper triangular factor R of the Schur decomposition of (A,C).
  • LDC — INTEGER. The leading dimension of the array C. LDC >= max(1,M).
  • D —
  • D — DOUBLE PRECISION array, dimension (LDD,N).
    • If FACT == , the matrix D is a general matrix and it is overwritten with the upper triangular factor V of the Schur decomposition of (B,D).
    • If FACT == , the matrix D contains its upper triangular matrix V of the Schur decomposition of (B,D).
    • If FACT == , the matrix D is the upper triangular matrix of the generalized Hessenberg form (B,D) and it is overwritten with the upper triangular factor V of the Schur decomposition of (B,D).
  • LDD — INTEGER. The leading dimension of the array D. LDD >= max(1,N). 💅
  • QA — DOUBLE PRECISION array, dimension (LDQA,M).
    • If FACT == , the matrix QA is an empty M-by-M matrix on input and contains the left Schur vectors of (A,C) on output.
    • If FACT == , the matrix QA contains the left Schur vectors of (A,C).
    • If FACT == , the matrix QA is an empty M-by-M matrix on input and contains the left Schur vectors of (A,C) on output.
  • LDQA — INTEGER. The leading dimension of the array QA. LDQA >= max(1,M). ✨
  • ZA — DOUBLE PRECISION array, dimension (LDZA,M).
    • If FACT == , the matrix ZA is an empty M-by-M matrix on input and contains the right Schur vectors of (A,C) on output.
    • If FACT == , the matrix ZA contains the right Schur vectors of (A,C).
    • If FACT == , the matrix ZA is an empty M-by-M matrix on input and contains the right Schur vectors of (A,C) on output.
  • LDZA — INTEGER. The leading dimension of the array ZA. LDZA >= max(1,M). 🎀
  • QB — DOUBLE PRECISION array, dimension (LDQB,N).
    • If FACT == , the matrix QB is an empty N-by-N matrix on input and contains the left Schur vectors of (B,D) on output.
    • If FACT == , the matrix QB contains the left Schur vectors of (B,D).
    • If FACT == , the matrix QB is an empty M-by-M matrix on input and contains the left Schur vectors of (B,D) on output. (yes bestie, it literally says M-by-M there, we're not touching it, the original said it and we said it 💀)
  • LDQB — INTEGER. The leading dimension of the array QB. LDQB >= max(1,N). 🦋
  • ZB — DOUBLE PRECISION array, dimension (LDZB,N).
    • If FACT == , the matrix ZB is an empty N-by-N matrix on input and contains the right Schur vectors of (B,D) on output.
    • If FACT == , the matrix ZB contains the right Schur vectors of (B,D).
    • If FACT == , the matrix ZB is an empty M-by-M matrix on input and contains the right Schur vectors of (B,D) on output. (same situation as QB, M-by-M and all, we keep it exactly as written 🙈)
  • LDZB — INTEGER. The leading dimension of the array ZB. LDZB >= max(1,N). 🌸
  • E — DOUBLE PRECISION array, dimension (LDE,N). On input, the matrix E contains the right hand side E. On output, the matrix E contains the solution R. 💖
  • LDE — INTEGER. The leading dimension of the array E. LDE >= max(1,M).
  • F — DOUBLE PRECISION array, dimension (LDF,N). On input, the matrix F contains the right hand side F. On output, the matrix F contains the solution L. ✨
  • LDF — INTEGER. The leading dimension of the array F. LDF >= max(1,M).
  • SCALE — 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 — DOUBLE PRECISION array, dimension (MAX(1,LDWORK)). If FACT == , the matrix ZB is an empty M-by-M matrix on input and contains the right Schur vectors of (B,D) on output. Workspace for the algorithm. The optmimal workspace is returned in LDWORK, if LDWORK == -1 on input. In this case no computations are performed. 😭 (and yes, that first sentence is verbatim copy-paste energy from ZB up there, we're just reporting what the page says, not judging 💅)
  • LDWORK — INTEGER. If LDWORK == -1 on input, 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 — INTEGER.
    • == 0: successful exit 🎉
    • = 1: DHGGES 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_TGCSYLV_DUAL_DAG
  • DLA_TGCSYLV_DUAL_LEVEL3
  • DLA_TGCSYLV_DUAL_L3_2S
  • DLA_TGCSYLV_DUAL_L2
  • DLA_TGCSYLV_DUAL_L2_LOCAL_COPY_32
  • DLA_TGCSYLV_DUAL_L2_LOCAL_COPY_64
  • DLA_TGCSYLV_DUAL_L2_LOCAL_COPY_96
  • DLA_TGCSYLV_DUAL_L2_LOCAL_COPY_128
  • DLA_TGCSYLV_DUAL_L2_LOCAL_COPY

Author 💜

Martin Koehler, MPI Magdeburg

Date 🗓️

October 2025

Definition 📍

Definition at line 350 of file dla_ggcsylv_dual.f90.

subroutine dla_ggcsylv_dual_refine 🧚

okay bestie, deep breath, this signature is long long. Here it is exactly, no cap:

subroutine dla_ggcsylv_dual_refine (character, dimension(1) transa,
    character, dimension(1) transb, character, dimension(1) guess, double
    precision sgn1, double precision sgn2, integer m, integer n, double
    precision, dimension(lda, *) a, integer lda, double precision,
    dimension(ldb, *) b, integer ldb, double precision, dimension(ldc, *) c,
    integer ldc, double precision, dimension(ldd, *) d, integer ldd, double
    precision, dimension(ldr, *) r, integer ldr, double precision,
    dimension(ldl, *) l, integer ldl, double precision, dimension ( lde , *
    ) e, integer lde, double precision, dimension( ldf, *) f, integer ldf,
    double precision, dimension(ldas, *) as, integer ldas, double precision,
    dimension(ldbs,*) bs, integer ldbs, double precision, dimension(ldcs, *)
    cs, integer ldcs, double precision, dimension(ldds, *) ds, integer ldds,
    double precision, dimension(ldq, *) q, integer ldq, double precision,
    dimension(ldz, *) z, integer ldz, double precision, dimension(ldu, *) u,
    integer ldu, double precision, dimension(ldv, *) v, integer ldv, integer
    maxit, double precision tau, double precision, dimension(*) convlog,
    double precision, dimension(*) work, integer ldwork, integer info)

Iterative Refinement for the dual Coupled Generalized Sylvester Equations. 💅

Purpose 🎯

!> DLA_GGCSYLV_DUAL_REFINE solves a coupled generalized Sylvester equation of the following forms
!>
!>    op1(A)**T * R  + op1(C)**T * L               = SCALE * E                             (1)
!>    SGN1 * R * op2(B)**T + SGN2 * L * op2(D)** T = SCALE * F
!>
!> where A and C are M-by-M matrices and B and D are N-by-N matrices.
!> The right hand sides E, F  and the solutions R, L are  M-by-N matrices.
!> The equation (1) is the dual to the generalized coupled Sylvester equation
!>
!>    op1(A) * R + SGN1 * L * op2(B)  = SCALE * E                                          (2)
!>    op1(C) * R + SGN2 * L * op2(D)  = SCALE * F
!>
!> The equation (1) is the dual one to equation (2) with respect to the underlying linear system.
!> Let Z be the matrix formed by rewriting (2) into its Kronecker form. This yields
!>
!>         | kron(I, op1(A))   SGN1*kron(op2(B)**T, I) | | Vec R |   | Vec E |
!>   Z X = |                                           |*|       | = |       |
!>         | kron(I, op1(C))   SGN2*kron(op2(D)**T, I) | | Vec L |   | Vec F |
!>
!> Regarding Z**T one obtains
!>
!>            | kron(I, op1(A)**T )    kron(I, op1(C)**T)   | | Vec R |   | Vec E |
!>   Z**T X = |                                             |*|       | = |       |
!>            | SGN1*kron(op2(B), I)   SGN2*kron(op2(D), I) | | Vec L |   | Vec F |
!>
!> which belongs to the Sylvester equation (1). For this reason the parameters TRANSA and TRANSB
!> are expressed in terms of the Sylvester equation (2).
!> The pencils (A,C) and (B,D) need to be given in the original form as well
!> as in their generalized Schur decomposition since both are required in the
!> iterative refinement procedure.
!>

like, the duality is doing main character energy here fr fr — one equation is the transpose-flavored twin of the other, and the Kronecker blocks are literally how you see it. 🌈

Parameters 🧮

  • TRANSA — CHARACTER. Specifies the form of the system of equations with respect to A and C:
    • == 'N': op1(A) = A
    • == 'T': op1(A) = A**T
  • TRANSB — CHARACTER. Specifies the form of the system of equations with respect to B and D:
    • == 'N': op2(B) = B,
    • == 'T': op2(B) = B**T
  • GUESS — CHARACTER. Specifies whether (R,L) contains an initial guess or nor not. 😌
    • = 'I': (R, L) contains an initial guess
    • = 'N': No initial guess, (R,L) is set to zero at the begin of the iteration.
  • SGN1 — DOUBLE PRECISION, allowed values: +/-1. Specifies the sign between in the first equation. 🔥
  • SGN2 — DOUBLE PRECISION, allowed values: +/-1. Specifies the sign between in the second equation. 🔥
  • M — INTEGER. The order of the matrices A and C. M >= 0.
  • N — INTEGER. The order of the matrices B and D. N >= 0.
  • A — DOUBLE PRECISION array, dimension (LDA,M). The array A contains the original matrix A defining the equation. ✨
  • LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,M).
  • B — DOUBLE PRECISION array, dimension (LDB,N). The array B contains the original matrix B defining the equation. 🦋
  • LDB — INTEGER. The leading dimension of the array A. LDB >= max(1,N). (yes, it says "of the array A" — that's what the page says, we keep it, no edits bestie 💀)
  • C —
  • C — C</p> is DOUBLE PRECISION array, dimension (LDC,M). It's holding the original matrix C that defines the equation, bestie. No cap.
  • LDC — LDC</p> is INTEGER. The leading dimension of the array C. Constraint: LDC >= max(1,M). Respect it 💅
  • D — D</p> is DOUBLE PRECISION array, dimension (LDD,N). The array D contains the original matrix D defining the equation. She's the blueprint, okay?
  • LDD — LDD</p> is INTEGER. The leading dimension of the array D. LDD >= max(1,N) 🫶
  • R — R</p> is DOUBLE PRECISION array, dimension (LDR,N). On input, R holds the initial guess R0 for the first solution matrix. On output, R holds the refine solution matrix R. Glow-up arc fr fr ✨
  • LDR — LDR</p> is INTEGER. The leading dimension of the array R. LDR >= max(1,M)
  • L — L</p> is DOUBLE PRECISION array, dimension (LDL,N). On input, L contains the initial guess for the second solution matrix. On output, L contains the solution L. She evolved 💖
  • LDL — LDL</p> is INTEGER. The leading dimension of the array L. LDF >= max(1,M).
WAIT — that's literally what the original says. It says LDF >= max(1,M) right there in the LDL entry. I am not touching it, I am not "fixing" it, I'm just telling you bestie: yes, that's what's written. 🙈
  • E — E</p> is DOUBLE PRECISION array, dimension (LDE,N). On input, E contains the right hand side E.
  • LDE — LDE</p> is INTEGER. The leading dimension of the array E. LDE >= max(1,M)
  • F — F</p> is DOUBLE PRECISION array, dimension (LDF,N). On input, F contains the right hand side F.
  • LDF — LDF</p> is INTEGER. The leading dimension of the array F. LDF >= max(1,M)
  • AS — AS</p> is DOUBLE PRECISION array, dimension (LDAS,M). It holds the generalized Schur decomposition of the A. Iconic behavior.
  • LDAS — LDAS</p> is INTEGER. The leading dimension of the array AS. LDAS >= max(1,M)
  • BS — BS</p> is DOUBLE PRECISION array, dimension (LDBS,N). It holds the generalized Schur decomposition of the B.
  • LDBS — LDBS</p> is INTEGER. The leading dimension of the array BS. LDBS >= max(1,N)
  • CS — CS</p> is DOUBLE PRECISION array, dimension (LDCS,M). It holds the generalized Schur decomposition of the C.
  • LDCS — LDCS</p> is INTEGER. The leading dimension of the array CS. LDCS >= max(1,M)
  • DS — DS</p> is DOUBLE PRECISION array, dimension (LDDS,N). It holds the generalized Schur decomposition of the D.
  • LDDS — LDDS</p> is INTEGER. The leading dimension of the array DS. LDDS >= max(1,N)
  • Q — Q</p> is DOUBLE PRECISION array, dimension (LDQ,M). It's carrying the left generalized Schur vectors for (A,C) as returned by DGGES. Periodt.
  • LDQ — LDQ</p> is INTEGER. The leading dimension of the array Q. LDQ >= max(1,M)
  • Z — Z</p> is DOUBLE PRECISION array, dimension (LDZ,M). It's carrying the right generalized Schur vectors for (A,C) as returned by DGGES. The duo 🫶
  • LDZ — LDZ</p> is INTEGER. The leading dimension of the array Z. LDZ >= max(1,M)
  • U — U</p> is DOUBLE PRECISION array, dimension (LDU,N). It's carrying the left generalized Schur vectors for (B,D) as returned by DGGES.
  • LDU — LDU</p> is INTEGER. The leading dimension of the array U. LDU >= max(1,N)
  • V — V</p> is DOUBLE PRECISION array, dimension (LDV,N). It's carrying the right generalized Schur vectors for (B,D) as returned by DGGES.
  • LDV — LDV</p> is INTEGER. The leading dimension of the array V. LDV >= max(1,N)
  • MAXIT — MAXIT</p> is INTEGER. On input, MAXIT is the maximum number of iteration that are performed, 2 <= MAXIT <= 100. On exit, MAXIT holds the number of iteration steps taken by the algorithm. She's reporting back 📋
  • TAU — TAU</p> is DOUBLE PRECISION. On input, TAU is the additional security factor for the stopping criterion, typical values are 0.1. On exit, TAU is the last relative residual when the stopping criterion got valid. Safety first bestie 🛡️
  • CONVLOG — CONVLOG</p> is DOUBLE PRECISION array, dimension (MAXIT). It's the convergence history of the iterative refinement. CONVLOG(I) contains the maximum relative residual of both equations before it is solved for the I-th time. It's literally the algorithm's diary 🌸
  • WORK — WORK</p> is DOUBLE PRECISION array, dimension (MAX(1,LDWORK)). Workspace for the algorithm. The optimal workspace is returned in LDWORK if LDWORK == -1 on input. In this case no computations are performed.
  • LDWORK — LDWORK</p> 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. It's just a vibe check, nothing more 😌
  • INFO — INFO</p> is INTEGER. The whole tea:
    • == 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 👀

Bestie, if you liked this one, you will be obsessed with her sisters:

  • DLA_TGCSYLV_DUAL_DAG
  • DLA_TGCSYLV_DUAL_LEVEL3
  • DLA_TGCSYLV_DUAL_L3_2S
  • DLA_TGCSYLV_DUAL_L2
  • DLA_TGCSYLV_DUAL_L2_LOCAL_COPY_32
  • DLA_TGCSYLV_DUAL_L2_LOCAL_COPY_64
  • DLA_TGCSYLV_DUAL_L2_LOCAL_COPY_96
  • DLA_TGCSYLV_DUAL_L2_LOCAL_COPY_128
  • DLA_TGCSYLV_DUAL_L2_LOCAL_COPY

💖 AUTHOR 💖

Martin Koehler, MPI Magdeburg 👑

📅 DATE 📅

October 2025

Definition at line 399 of file dla_ggcsylv_dual_refine.f90.

🦋 dla_ggcsylv_refine 🦋

The actual signature, verbatim, no notes:

   subroutine dla_ggcsylv_refine (character, dimension(1) transa, character,
       dimension(1) transb, character, dimension(1) guess, double precision
       sgn1, double precision sgn2, integer m, integer n, double precision,
       dimension(lda, *) a, integer lda, double precision, dimension(ldb, *) b,
       integer ldb, double precision, dimension(ldc, *) c, integer ldc, double
       precision, dimension(ldd, *) d, integer ldd, double precision,
       dimension(ldr, *) r, integer ldr, double precision, dimension(ldl, *) l,
       integer ldl, double precision, dimension ( lde , * ) e, integer lde,
       double precision, dimension( ldf, *) f, integer ldf, double precision,
       dimension(ldas, *) as, integer ldas, double precision, dimension(ldbs,*)
       bs, integer ldbs, double precision, dimension(ldcs, *) cs, integer ldcs,
       double precision, dimension(ldds, *) ds, integer ldds, double precision,
       dimension(ldq, *) q, integer ldq, double precision, dimension(ldz, *) z,
       integer ldz, double precision, dimension(ldu, *) u, integer ldu, double
       precision, dimension(ldv, *) v, integer ldv, integer maxit, double
       precision tau, double precision, dimension(*) convlog, double precision,
       dimension(*) work, integer ldwork, integer info)

Iterative Refinement for the Coupled Generalized Sylvester Equations.

✨ Purpose ✨

!> DLA_GGCSYLV_REFINE solves a coupled generalized Sylvester equation of the following forms
!>
!>    op1(A) * R  + SGN1 * L  * op2(B) =  E                              (1)
!>    op1(C) * R  + SGN2 * L  * op2(D) =  F
!>
!> with iterative refinement, Thereby  (A,C) is a M-by-M matrix pencil and
!> (B,D) is a N-by-N matrix pencil.
!> The right hand side (E,F) and the solution (R,L) are M-by-N matrices.
!> The pencils (A,C) and (B,D) need to be given in the original form as well
!> as in their generalized Schur decomposition since both are required in the
!> iterative refinement procedure.
!>

Okay so real talk: (A,C) is an M-by-M matrix pencil, (B,D) is an N-by-N matrix pencil, the right hand side (E,F) and the solution (R,L) are M-by-N matrices. And both pencils gotta show up twice — original form and generalized Schur decomposition — because the iterative refinement needs both. She's demanding but she's worth it 💅

🎀 Parameters 🎀

  • TRANSA — TRANSA</p> is CHARACTER. Specifies the form of the system of equations with respect to A and C:
    • == 'N': op1(A) = A
    • == 'T': op1(A) = A**T
  • TRANSB — TRANSB</p> is CHARACTER. Specifies the form of the system of equations with respect to B and D:
    • == 'N': op2(B) = B,
    • == 'T': op2(B) = B**T
  • GUESS — GUESS</p> is CHARACTER. Tells us whether (R,L) already contains an initial guess or not.
    • = 'I': (R, L) contains an initial guess
    • = 'N': No initial guess, (R,L) is set to zero at the begin of the iteration.
  • SGN1 — SGN1</p> is DOUBLE PRECISION, allowed values: +/-1. Specifies the sign between in the first equation.
  • SGN2 — SGN2</p> is DOUBLE PRECISION, allowed values: +/-1. Specifies the sign between in the second equation.
  • M — M</p> is INTEGER. The order of the matrices A and C. M >= 0.
  • N — N</p> is INTEGER. The order of the matrices B and D. N >= 0.
  • A — A</p> is DOUBLE PRECISION array, dimension (LDA,M). The array A contains the original matrix A defining the equation.
  • LDA — LDA</p> is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
  • B — B</p> is DOUBLE PRECISION array, dimension (LDB,N). The array B contains the original matrix B defining the equation.
  • LDB — LDB</p> is INTEGER. The leading dimension of the array A. LDB >= max(1,N).
Yes bestie, the LDB entry says "leading dimension of the array A". That's the original wording. I'm keeping it exactly, don't come for me 🙈
  • C — C</p> is DOUBLE PRECISION array, dimension (LDC,M). The array C contains the original matrix C defining the equation.
  • LDC —
  • C — okay so C is a DOUBLE PRECISION array, dimension (LDC,N), and the array C contains the original matrix C defining the equation. 💖
  • LDC — LDC is INTEGER, the leading dimension of the array C. And bestie, LDC >= max(1,M) or we simply do not go. ✨
  • D — D is a DOUBLE PRECISION array, dimension (LDD,N). The array D contains the original matrix D defining the equation. 🦋
  • LDD — LDD is INTEGER, the leading dimension of the array D. LDD >= max(1,N). 🌸
  • R — R is a DOUBLE PRECISION array, dimension (LDR,N). On input, the array R contains the initial guess R0 for the first solution matrix. On output, the array R contains the refine solution matrix R. She's evolving, we love that for her. 💅
  • LDR — LDR is INTEGER, the leading dimension of the array R. LDR >= max(1,M). 🎀
  • L — L is a DOUBLE PRECISION array, dimension (LDL,N). On input, the array L contains the initial guess for the second solution matrix. On output, the array L contains the solution L. ✨
  • LDL — LDL is INTEGER, the leading dimension of the array L. And then the page says LDF >= max(1,M) — yes, LDF, right there under the LDL entry. Not my typo, not my problem, that is literally what it says 💀.
  • E — E is a DOUBLE PRECISION array, dimension (LDE,N). On input, the array E contains the right hand side E. 🫶
  • LDE — LDE is INTEGER, the leading dimension of the array E. LDE >= max(1,M). 🌈
  • F — F is a DOUBLE PRECISION array, dimension (LDF,N). On input, the array F contains the right hand side F. 🍓
  • LDF — LDF is INTEGER, the leading dimension of the array F. LDF >= max(1,M). 💜
  • AS — AS is a 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 a DOUBLE PRECISION array, dimension (LDBS,N). The array BS contains the generalized Schur decomposition of the B. 🦋
  • LDBS — LDBS is INTEGER, the leading dimension of the array BS. LDBS >= max(1,N). 🌸
  • CS — CS is a DOUBLE PRECISION array, dimension (LDCS,M). The array CS contains the generalized Schur decomposition of the C. 💖
  • LDCS — LDCS is INTEGER, the leading dimension of the array CS. LDCS >= max(1,M). 🎀
  • DS — DS is a DOUBLE PRECISION array, dimension (LDDS,N). The array DS contains the generalized Schur decomposition of the D. 🌈
  • LDDS — LDDS is INTEGER, the leading dimension of the array DS. LDDS >= max(1,N). ⭐
  • Q — Q is a DOUBLE PRECISION array, dimension (LDQ,M). The array Q contains the left generalized Schur vectors for (A,C) as returned by DGGES. 👀
  • LDQ — LDQ is INTEGER, the leading dimension of the array Q. LDQ >= max(1,M). 💅
  • Z — Z is a DOUBLE PRECISION array, dimension (LDZ,M). The array Z contains the right generalized Schur vectors for (A,C) as returned by DGGES. ✨
  • LDZ — LDZ is INTEGER, the leading dimension of the array Z. LDZ >= max(1,M). 🎀
  • U — U is a DOUBLE PRECISION array, dimension (LDU,N). The array U contains the left generalized Schur vectors for (B,D) as returned by DGGES. 🦋
  • LDU — LDU is INTEGER, the leading dimension of the array U. LDU >= max(1,N). 🌸
  • V — V is a DOUBLE PRECISION array, dimension (LDV,N). The array V contains the right generalized Schur vectors for (B,D) as returned by DGGES. 💜
  • LDV — LDV is INTEGER, the leading dimension of the array V. LDV >= max(1,N). ⭐
  • MAXIT — MAXIT is INTEGER. On input, MAXIT contains the maximum number of iteration that are performed, and 2 <= MAXIT <= 100 okay, that's the range, respect it. On exit, MAXIT contains the number of iteration steps taken by the algorithm. Receipts! 🧾
  • 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 a DOUBLE PRECISION array, dimension (MAXIT). The CONVLOG array contains the convergence history of the iterative refinement. CONVLOG(I) contains the maximum relative residual of both equations before it is solved for the I-th time. It's giving ✨character development arc✨ fr fr.
  • WORK — WORK is a 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, and here's the whole mood board:
    • == 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_TGCSYLV_DAG
  • DLA_TGCSYLV_LEVEL3
  • DLA_TGCSYLV_L3_2S
  • DLA_TGCSYLV_L2_UNOPT
  • DLA_TGCSYLV_L2
  • DLA_TGCSYLV_L2_REORDER
  • DLA_TGCSYLV_L2_LOCAL_COPY_32
  • DLA_TGCSYLV_L2_LOCAL_COPY_64
  • DLA_TGCSYLV_L2_LOCAL_COPY_96
  • DLA_TGCSYLV_L2_LOCAL_COPY_128
  • DLA_TGCSYLV_L2_LOCAL_COPY

✍️ Author ✍️

Martin Koehler, MPI Magdeburg

📅 Date 📅

October 2025

Definition at line 381 of file dla_ggcsylv_refine.f90.

🌈 subroutine dla_ggsylv 🌈

subroutine dla_ggsylv (character, dimension(1) facta, character,
    dimension(1) factb, character, dimension(1) transa, character,
    dimension(1) transb, double precision sgn, integer m, integer n, double
    precision, dimension(lda,*) a, integer lda, double precision,
    dimension(ldb, *) b, integer ldb, double precision, dimension(ldc, *) c,
    integer ldc, double precision, dimension(ldd,*) d, integer ldd, double
    precision, dimension(ldqa, *) qa, integer ldqa, double precision,
    dimension(ldza, *) za, integer ldza, double precision, dimension(ldqb,
    *) qb, integer ldqb, double precision, dimension(ldzb, *) zb, integer
    ldzb, double precision, dimension(ldx, *) x, integer ldx, double
    precision scale, double precision, dimension(*) work, integer ldwork,
    integer info)

Frontend for the solution of Generalized Sylvester Equations. 💅

🎯 Purpose 🎯

Okay bestie, listen up, because DLA_GGSYLV solves a generalized Sylvester equation of the following forms:

op1(A) * X * op2(B) + op1(C) * X * op2(D) = SCALE * Y                              (1)

or

op1(A) * X * op2(B) - op1(C) * X * op2(D) = SCALE * Y                              (2)

where (A,C) is a M-by-M matrix pencil and (B,D) is a N-by-N matrix pencil. The right hand side Y and the solution X are M-by-N matrices. The pencils (A,C) and (B,D) can be either given as general unreduced matrices, as generalized Hessenberg form, or in terms of their generalized Schur decomposition. If they are given as general matrices or as a generalized Hessenberg form their generalized Schur decomposition will be computed. 🦋

Not me reading that three times to make sure I got the pencil sizes right — M-by-M for (A,C), N-by-N for (B,D), X and Y are M-by-N. Write it down. 💖

🎀 Parameters 🎀

  • FACTA — FACTA is CHARACTER. Specifies how the matrix pencil (A,C) is given. 👑
    • == 'N': The matrix pencil (A,C) is given as a general matrices and its Schur decomposition A = QA*S*ZA**T, C = QA*R*ZA**T will be computed.
    • == 'F': The matrix pencil (A,C) is already in generalized Schur form and S, R, QA, and ZA are given.
    • == 'H': The matrix pencil (A,C) is given in generalized Hessenberg form and its Schur decomposition A = QA*S*ZA**T, C = QA*R*ZA**T will be computed.
  • FACTB — FACTB is CHARACTER. Specifies how the matrix pencil (B,D) is given. ✨
    • == 'N': The matrix pencil (B,D) is given as a general matrices and its Schur decomposition B = QB*U*ZB**T, D = QB*V*ZB**T will be computed.
    • == 'F': The matrix pencil (B,D) is already in generalized Schur form and U, V, QB, and ZB are given.
    • == 'H': The matrix pencil (B,D) is given in generalized Hessenberg form and its Schur decomposition B = QB*U*ZB**T, D = QB*V*ZB**T will be computed.
  • TRANSA — TRANSA is CHARACTER. Specifies the form of the system of equations with respect to A and C: 🌸
    • == 'N': op1(A) = A
    • == 'T': op1(A) = A**T
  • TRANSB — TRANSB is CHARACTER. Specifies the form of the system of equations with respect to B and D: 🌸
    • == 'N': op2(B) = B,
    • == 'T': op2(B) = B**T
  • SGN — SGN is DOUBLE PRECISION, allowed values: +/-1. Specifies the sign between the two parts of the Sylvester equation. 💅
    • = 1: Solve Equation (1)
    • == -1: Solve Equation (2)
  • M — M is INTEGER. The order of the matrices A and C. M >= 0. 🎀
  • N — N is INTEGER. The order of the matrices B and D. N >= 0. 🎀
  • A —
  • A — DOUBLE PRECISION array, dimension (LDA,M) — okay so this is the moment, bestie 🫶 here's what A is doing in each case:
    • If FACT == , then A is a general matrix, and it gets overwritten with the (quasi-) upper triangular factor S of the Schur decomposition of (A,C). 💅
    • If FACT == , then A already contains its (quasi-) upper triangular matrix S of the Schur decomposition of (A,C).
    • If FACT == , then A is an upper Hessenberg matrix of the generalized Hessenberg form (A,C), and it gets overwritten with the (quasi-) upper triangular factor S of the Schur decomposition of (A,C). 🔥
Real talk: the value that belongs after each FACT == is blank in the source, and I am not out here inventing values. 🙈 Left exactly as-is, no cap.
  • LDA — INTEGER — the leading dimension of the array A, and the rule is LDA >= max(1,M). That's it, that's the law. ✨
  • B — DOUBLE PRECISION array, dimension (LDB,N) — same energy as A, but for the (B,D) pencil:
    • If FACT == , then B is a general matrix, and it is overwritten with the (quasi-) upper triangular factor U of the Schur decomposition of (B,D). 💖
    • If FACT == , then B contains its (quasi-) upper triangular matrix U of the Schur decomposition of (B,D).
    • If FACT == , then B is an upper Hessenberg matrix of the generalized Hessenberg form (B,D), and it is overwritten with the (quasi-) upper triangular factor U of the Schur decomposition of (B,D). 🔥
  • LDB — INTEGER — leading dimension of B, and LDB >= max(1,N). Periodt. 💅
  • C — DOUBLE PRECISION array, dimension (LDC,M) — note this one gives you a plain upper triangular factor, not a quasi one, iykyk:
    • If FACT == , then C is a general matrix, and it is overwritten with the upper triangular factor R of the Schur decomposition of (A,C). 🎀
    • If FACT == , then C contains its upper triangular matrix R of the Schur decomposition of (A,C).
    • If FACT == , then C is the upper triangular matrix of the generalized Hessenberg form (A,C), and it is overwritten with the upper triangular factor R of the Schur decomposition of (A,C). ✨
  • LDC — INTEGER — leading dimension of C, and LDC >= max(1,M). 💅
  • D — DOUBLE PRECISION array, dimension (LDD,N) — the (B,D) twin of C:
    • If FACT == , then D is a general matrix, and it is overwritten with the upper triangular factor V of the Schur decomposition of (B,D). 🦋
    • If FACT == , then D contains its upper triangular matrix V of the Schur decomposition of (B,D).
    • If FACT == , then D is the upper triangular matrix of the generalized Hessenberg form (B,D), and it is overwritten with the upper triangular factor V of the Schur decomposition of (B,D). ✨
  • LDD — INTEGER — leading dimension of D, and LDD >= max(1,N). 💅
  • QA — DOUBLE PRECISION array, dimension (LDQA,M) — left Schur vectors of (A,C) live here:
    • If FACT == , then QA is an empty M-by-M matrix on input, and on output it contains the left Schur vectors of (A,C). 🌸
    • If FACT == , then QA contains the left Schur vectors of (A,C).
    • If FACT == , then QA is an empty M-by-M matrix on input, and on output it contains the left Schur vectors of (A,C). 🌸
  • LDQA — INTEGER — leading dimension of QA, and LDQA >= max(1,M). ✨
  • ZA — DOUBLE PRECISION array, dimension (LDZA,M) — right Schur vectors of (A,C), coming through:
    • If FACT == , then ZA is an empty M-by-M matrix on input, and on output it contains the right Schur vectors of (A,C). 🦋
    • If FACT == , then ZA contains the right Schur vectors of (A,C).
    • If FACT == , then ZA is an empty M-by-M matrix on input, and on output it contains the right Schur vectors of (A,C). 🦋
  • LDZA — INTEGER — leading dimension of ZA, and LDZA >= max(1,M). ✨
  • QB — DOUBLE PRECISION array, dimension (LDQB,N) — left Schur vectors of (B,D):
    • If FACT == , then QB is an empty N-by-N matrix on input, and on output it contains the left Schur vectors of (B,D). 💖
    • If FACT == , then QB contains the left Schur vectors of (B,D).
    • If FACT == , then QB is an empty M-by-M matrix on input, and on output it contains the left Schur vectors of (B,D). 😭 (yes it really says M-by-M in that last one, I'm not the one who wrote it, I'm just the messenger)
  • LDQB — INTEGER — leading dimension of QB, and LDQB >= max(1,N). ✨
  • ZB — DOUBLE PRECISION array, dimension (LDZB,N) — right Schur vectors of (B,D):
    • If FACT == , then ZB is an empty N-by-N matrix on input, and on output it contains the right Schur vectors of (B,D). 💜
    • If FACT == , then ZB contains the right Schur vectors of (B,D).
    • If FACT == , then ZB is an empty M-by-M matrix on input, and on output it contains the right Schur vectors of (B,D). 😭 (again with the M-by-M, ok)
  • LDZB — INTEGER — leading dimension of ZB, and LDZB >= max(1,N). ✨
  • X — DOUBLE PRECISION array, dimension (LDX,N) — she's the main character, the solution goes here:
    • On input, X holds the right hand side Y. 🫶
    • On output, X holds the solution of Equation (1) or (2).
    • Both the right hand side Y and the solution X are M-by-N matrices. 💅
  • LDX — INTEGER — leading dimension of X, and LDX >= max(1,M). ✨
  • SCALE — DOUBLE PRECISION — a scaling factor whose whole job is keeping the result from overflowing. 🌊
    • 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 — DOUBLE PRECISION array, dimension (MAX(1,LDWORK)) — the workspace for the algorithm. The optimal workspace is handed to you either by \ref mepack_memory_frontend or by a previous call to this routine with LDWORK === -1. 🧰
  • LDWORK — INTEGER — the size of the workspace for the algorithm. You can figure it out with a call to \ref mepack_memory_frontend . Alternatively, if LDWORK == -1 on input, the subroutine just returns the required workspace size in LDWORK and performs zero computations. Not a single one. 💀
  • INFO — INTEGER — the vibe check at the end:
    • == 0: successful exit 🎉
    • = 1: DHGGES 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_TGSYLV_DAG
  • DLA_TGSYLV_L3_COLWISE
  • DLA_TGSYLV_L3_2S
  • DLA_TGSYLV_L2_REORDER
  • DLA_TGSYLV_L2
  • DLA_TGSYLV_L2_COLWISE
  • DLA_TGSYLV_L2_LOCAL_COPY_32
  • DLA_TGSYLV_L2_LOCAL_COPY_64
  • DLA_TGSYLV_L2_LOCAL_COPY_96
  • DLA_TGSYLV_L2_LOCAL_COPY_128
  • DLA_TGSYLV_L2_LOCAL_COPY
  • DLA_TGSYLV_GARDINER_LAUB

✍️ Author

Martin Koehler, MPI Magdeburg 🌈

📅 Date

October 2025 🗓️

Definition at line 322 of file dla_ggsylv.f90. 📍

🌀 dla_ggsylv_refine

Okay bestie, deep breath, because this signature is long and I love her for it. 💅

subroutine dla_ggsylv_refine (character, dimension(1) transa, character,
    dimension(1) transb, character, dimension(1) guess, double precision
    sgn, integer m, integer n, double precision, dimension(lda, *) a,
    integer lda, double precision, dimension(ldb, *) b, integer ldb, double
    precision, dimension(ldc, *) c, integer ldc, double precision,
    dimension(ldd, *) d, integer ldd, 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(ldcs, *)
    cs, integer ldcs, double precision, dimension(ldds, *) ds, integer ldds,
    double precision, dimension(ldq, *) q, integer ldq, double precision,
    dimension(ldz, *) z, integer ldz, double precision, dimension(ldu, *) u,
    integer ldu, double precision, dimension(ldv, *) v, integer ldv, integer
    maxit, double precision tau, double precision, dimension(*) convlog,
    double precision, dimension(*) work, integer ldwork, integer info)

Iterative Refinement for the Generalized Sylvester Equations. 🫶

🎯 Purpose

DLA_GGSYLV_REFINE solves a generalized Sylvester equation that looks like this:

op1(A) * X * op2(B) + SGN * op1(C) * X * op2(D) = Y                    (1)

...and it does it with iterative refinement. 👑

Thereby (A,C) is a M-by-M matrix pencil and (B,D) is a N-by-N matrix pencil. The right hand side Y and the solution X are M-by-N matrices. And here's the tea: the pencils (A,C) and (B,D) need to be given in the original form as well as in their generalized Schur decomposition, because the iterative refinement procedure needs both. Both. No skipping. 😭

🧩 Parameters

  • TRANSA — CHARACTER — specifies the form of the system of equations with respect to A and C:
    • == 'N': op1(A) = A
    • == 'T': op1(A) = A**T
  • TRANSB — CHARACTER — specifies the form of the system of equations with respect to B and D:
    • == 'N': op2(B) = B,
    • == 'T': op2(B) = B**T
  • GUESS — CHARACTER — tells us whether X is coming in with an initial guess or not:
    • = 'I': X contains an initial guess 🎁
    • = 'N': no initial guess, so X gets set to zero at the beginning of the iteration. 💀
  • SGN — DOUBLE PRECISION, allowed values: +/-1 — specifies the sign in the first equation. ➕➖
  • M — INTEGER — the order of the matrices A and C. M >= 0. ✨
  • N — INTEGER — the order of the matrices B and D. N >= 0. ✨
  • A — DOUBLE PRECISION array, dimension (LDA,M) — the array A contains the original matrix A defining the eqaution. 🌸
  • LDA
  • LDA — LDA is INTEGER. Leading dimension of array A. LDA >= max(1,M) or it's a no. 💅
  • B — B is DOUBLE PRECISION array, dimension (LDB,N). This array holds the original matrix B defining the equation. ✨
  • LDB — LDB is INTEGER. Leading dimension of B. LDB >= max(1,N). 🫶
  • C — C is DOUBLE PRECISION array, dimension (LDC,M). It contains the original matrix C defining the equation. 🌸
  • LDC — LDC is INTEGER. Leading dimension of C. LDC >= max(1,M). 🎀
  • D — D is DOUBLE PRECISION array, dimension (LDD,N). It contains the original matrix D defining the equation. 💜
  • LDD — LDD is INTEGER. Leading dimension of D. LDD >= max(1,N). 🦋
  • X — X is DOUBLE PRECISION array, dimension (LDX,N).
    • On input, X holds the initial guess, if GUESS = 'I'.
    • On output, X holds the solution X. 💖
  • LDX — LDX is INTEGER. Leading dimension of X. LDX >= max(1,M). 🌈
  • Y — Y is DOUBLE PRECISION array, dimension (LDY,N).
    • On input, Y holds the right hand side Y.
    • The array stays unchanged during the iteration. 🙈
  • LDY — LDY is INTEGER. Leading dimension of Y. LDY >= max(1,M). ⭐
  • AS — AS is DOUBLE PRECISION array, dimension (LDAS,M). The array AS contains the generalized Schur decomposition of A. 🔥
  • LDAS — LDAS is INTEGER. Leading dimension of AS. LDAS >= max(1,M). 👑
  • BS — BS is DOUBLE PRECISION array, dimension (LDBS,N). The array BS contains the generalized Schur decomposition of B. ✨
  • LDBS — LDBS is INTEGER. Leading dimension of BS. LDBS >= max(1,N). 💅
  • CS — CS is DOUBLE PRECISION array, dimension (LDCS,M). The array CS contains the generalized Schur decomposition of C. 🌸
  • LDCS — LDCS is INTEGER. Leading dimension of CS. LDCS >= max(1,M). 🎀
  • DS — DS is DOUBLE PRECISION array, dimension (LDDS,N). The array DS contains the generalized Schur decomposition of D. 💜
  • LDDS — LDDS is INTEGER. Leading dimension of DS. LDDS >= max(1,N). 🦋
  • Q — Q is DOUBLE PRECISION array, dimension (LDQ,M). The array Q contains the left generalized Schur vectors for (A,C) as returned by DGGES. 🔥
  • LDQ — LDQ is INTEGER. Leading dimension of 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,C) as returned by DGGES. 💖
  • LDZ — LDZ is INTEGER. Leading dimension of Z. LDZ >= max(1,M). 🌈
  • U — U is DOUBLE PRECISION array, dimension (LDU,N). The array U contains the left generalized Schur vectors for (B,D) as returned by DGGES. 🔥
  • LDU — LDU is INTEGER. Leading dimension of U. LDU >= max(1,N). 👑
  • V — V is DOUBLE PRECISION array, dimension (LDV,N). The array V contains the right generalized Schur vectors for (B,D) as returned by DGGES. ✨
  • LDV — LDV is INTEGER. Leading dimension of V. LDV >= max(1,N). 💅
  • MAXIT — MAXIT is INTEGER.
    • On input, MAXIT holds the maximum number of iteration that are performed, 2 <= MAXIT <= 100.
    • On exit, MAXIT holds the number of iteration steps taken by the algorithm. 🫶
  • TAU — TAU is DOUBLE PRECISION.
    • On input, TAU holds the additional security factor for the stopping criterion, typical values are 0.1.
    • On exit, TAU holds 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 optimal 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. Here's the tea:
    • == 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_TGSYLV_DAG
  • DLA_TGSYLV_LEVEL3
  • DLA_TGSYLV_L3_2S
  • DLA_TGSYLV_L2_UNOPT
  • DLA_TGSYLV_L2
  • DLA_TGSYLV_L2_REORDER
  • DLA_TGSYLV_L2_LOCAL_COPY_32
  • DLA_TGSYLV_L2_LOCAL_COPY_64
  • DLA_TGSYLV_L2_LOCAL_COPY_96
  • DLA_TGSYLV_L2_LOCAL_COPY_128
  • DLA_TGSYLV_L2_LOCAL_COPY
  • DLA_TGSYLV_GARDINER_LAUB

✨ Author ✨

Martin Koehler, MPI Magdeburg

📅 Date 📅

October 2025

Definition at line 349 of file dla_ggsylv_refine.f90.

🧚 Author 🧚

Generated automatically by Doxygen for MEPACK from the source code.

Okay bestie, that's the whole vibe. This page is version 1.1.2, dated Thu Oct 9 2025 00:00:00, and it's dblggsylv(3). Slay. 💖✨

📦 where this page comes from