sglggsylv(3)

📦
version 1.1.2 · 3 versions
, in fedora 43

hey bestie 💖 welcome to sglggsylv(3) from MEPACK — this is the single precision page for generalized Sylvester equations. no cap, it's giving linear algebra main character energy. 🫶

✨ NAME ✨

sglggsylv — Single Precision — Single Precision routines for generalized Sylvester equations. 💅

🌸 SYNOPSIS 🌸

🧚 Functions 🧚

okay so here are the functions, bestie. signatures are exact, don't touch a character. 💖

subroutine sla_ggcsylv — Frontend for the solution of Coupled Generalized Sylvester Equations.

subroutine sla_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 sla_ggcsylv_dual — Frontend for the solution of the dual Coupled Generalized Sylvester Equations.

subroutine sla_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 sla_ggsylv — Frontend for the solution of Generalized Sylvester Equations.

subroutine sla_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 sla_ggcsylv_dual_refine — Iterative Refinement for the dual Coupled Generalized Sylvester Equations.

subroutine sla_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 sla_ggcsylv_refine — Iterative Refinement for the Coupled Generalized Sylvester Equations.

subroutine sla_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 sla_ggsylv_refine — Iterative Refinement for the Generalized Sylvester Equations.

subroutine sla_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 💅

Single Precision routines for generalized Sylvester equations.

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

🎀 Function Documentation 🎀

subroutine sla_ggcsylv — Frontend for the solution of Coupled Generalized Sylvester Equations

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

🦋 Purpose 🦋

SLA_GGCSYLV solves a coupled generalized Sylvester equation of the following forms:

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 REAL, allowed values: +/-1. Specifies the sign between in the first equation.
  • SGN2 — SGN2 is REAL, 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 REAL 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 REAL 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 REAL 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 REAL 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 REAL 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 REAL 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 is REAL 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 — and that's where part 1 wraps, bestie. part 2 is coming, don't worry. 💖
  • LDQB — LDQB is INTEGER. It's the leading dimension of the array QB, and the vibe check says LDQB >= max(1,N). Non-negotiable bestie 💅
  • ZB — ZB is a REAL array, dimension (LDZB,N). She's a shapeshifter depending on FACT, so pay attention:
    • 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 — LDZB is INTEGER. Leading dimension of the array ZB, and LDZB >= max(1,N). Periodt. 👑
  • E — E is a REAL array, dimension (LDE,N). On input, the matrix E contains the right hand side E. On output, the matrix E contains the solution R. Glow-up complete 💖
  • LDE — LDE is INTEGER. Leading dimension of the array E, and LDE >= max(1,M). No cap.
  • F — F is a REAL array, dimension (LDF,N). On input, the matrix F contains the right hand side F. On output, the matrix F contains the solution L. Main character arc fr fr 🎀
  • LDF — LDF is INTEGER. Leading dimension of the array F, and LDF >= max(1,M). 🫶
  • SCALE — SCALE is REAL. It's the scaling factor that keeps the result from overflowing — the bodyguard of this whole operation. 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 a REAL 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. Literally zero ✋
  • LDWORK — LDWORK is 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. She's just peeking, not touching 🙈
  • INFO — INFO is INTEGER, and she is the messenger:
    • == 0: successful exit 🎉
    • = 1: SHGGES failed 💀
    • = 2: SLA_SORT_GEV failed 💀
    • = 3: Inner solver failed 😵
    • < 0: if INFO = -i, the i-th argument had an illegal value 🚨

👀 See also

  • SLA_TGCSYLV_DAG
  • DLA_TGCSYLV_LEVEL3
  • SLA_TGCSYLV_L3_2S
  • SLA_TGCSYLV_L2_UNOPT
  • SLA_TGCSYLV_L2
  • SLA_TGCSYLV_L2_REORDER
  • SLA_TGCSYLV_L2_LOCAL_COPY_32
  • SLA_TGCSYLV_L2_LOCAL_COPY_64
  • SLA_TGCSYLV_L2_LOCAL_COPY_96
  • SLA_TGCSYLV_L2_LOCAL_COPY_128
  • SLA_TGCSYLV_L2_LOCAL_COPY

💜 Author

Martin Koehler, MPI Magdeburg

🌈 Date

October 2025

Definition at line 333 of file sla_ggcsylv.f90.

🫶 sla_ggcsylv_dual 🫶

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

Frontend for the solution of the dual Coupled Generalized Sylvester Equations. Okay so she's the front desk of the dual operation, got it 💅

✨ Purpose ✨

SLA_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). iykyk 😌

🌸 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 REAL, allowed values: +/-1. Specifies the sign between in the first equation. ✨
  • SGN2 — SGN2 is REAL, 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 a REAL array, dimension (LDA,M). She's got three moods:
    • 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 a REAL array, dimension (LDB,N). Same energy, different pencil:
    • 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 a REAL 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 a REAL 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 — REAL array, dimension (LDQA,M). okay so bestie, what QA actually holds depends on what you told FACT to do:
    • If FACT == , then QA comes in as an empty M-by-M matrix, and on the way out it's holding the left Schur vectors of (A,C). 🦋
    • If FACT == , then QA already contains those left Schur vectors of (A,C).
    • If FACT == , then again: empty M-by-M on input, left Schur vectors of (A,C) on output. periodt.
  • LDQA — INTEGER. The leading dimension of the array QA. And it has rules, bestie: LDQA >= max(1,M). no negotiating 💅
  • ZA — REAL array, dimension (LDZA,M). Same energy, different matrix, the right Schur vectors this time:
    • If FACT == , ZA is an empty M-by-M matrix on input and on output it holds the right Schur vectors of (A,C).
    • If FACT == , ZA already contains those right Schur vectors of (A,C).
    • If FACT == , empty M-by-M going in, right Schur vectors of (A,C) coming out. ✨
  • LDZA — INTEGER. Leading dimension of the array ZA. LDZA >= max(1,M). iykyk.
  • QB — REAL array, dimension (LDQB,N). And now for the other pencil:
    • If FACT == , QB arrives as an empty N-by-N matrix and leaves holding the left Schur vectors of (B,D).
    • If FACT == , QB already contains the left Schur vectors of (B,D).
    • If FACT == , it's an empty M-by-M matrix on input and on output it holds the left Schur vectors of (B,D). 😭 (yes, M-by-M, that's literally what the manpage says, don't come for me)
  • LDQB — INTEGER. Leading dimension of the array QB. LDQB >= max(1,N). 🎀
  • ZB — REAL array, dimension (LDZB,N). The right Schur vectors of the second pencil, serving looks:
    • If FACT == , ZB is an empty N-by-N matrix on input, and on output it contains the right Schur vectors of (B,D).
    • If FACT == , ZB already contains the right Schur vectors of (B,D).
    • If FACT == , it comes in as an empty M-by-M matrix and leaves with the right Schur vectors of (B,D). 💀
  • LDZB — INTEGER. Leading dimension of the array ZB. LDZB >= max(1,N). lowkey essential.
  • E — REAL array, dimension (LDE,N).
    • On input: E is the right hand side E. 🍓
    • On output: E is the solution R. glow-up fr fr
  • LDE — INTEGER. Leading dimension of the array E. LDE >= max(1,M).
  • F — REAL array, dimension (LDF,N).
    • On input: F holds the right hand side F.
    • On output: F holds the solution L. slay 💖
  • LDF — INTEGER. Leading dimension of the array F. LDF >= max(1,M).
  • SCALE — REAL. The vibe-protection factor: SCALE keeps the result from overflowing. If INFO == 0 then SCALE is 1.0. Otherwise, if one of the inner systems couldn't be solved correctly, then 0 < SCALE <= 1 holds true. 🫶
  • WORK — REAL 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. (yes, that line is living in the WORK docs, we don't make the rules 🙈)
    • Also: workspace for the algorithm. The optmimal workspace is returned in LDWORK if LDWORK == -1 on input — and in that case, no computations are performed. just a lil size check, no math, no drama.
  • 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. it's giving "just tell me how much room you need" energy 🧚
  • INFO — INTEGER. The receipts:
    • == 0: successful exit. we ate. 👑
    • = 1: SHGGES failed.
    • = 2: SLA_SORT_GEV failed.
    • = 3: Inner solver failed.
    • < 0: if INFO = -i, the i-th argument had an illegal value. 🚨

👀 See also (the extended universe)

  • SLA_TGCSYLV_DUAL_DAG
  • DLA_TGCSYLV_DUAL_LEVEL3
  • SLA_TGCSYLV_DUAL_L3_2S
  • SLA_TGCSYLV_DUAL_L2
  • SLA_TGCSYLV_DUAL_L2_LOCAL_COPY_32
  • SLA_TGCSYLV_DUAL_L2_LOCAL_COPY_64
  • SLA_TGCSYLV_DUAL_L2_LOCAL_COPY_96
  • SLA_TGCSYLV_DUAL_L2_LOCAL_COPY_128
  • SLA_TGCSYLV_DUAL_L2_LOCAL_COPY

🫶 Author

Martin Koehler, MPI Magdeburg

🗓️ Date

October 2025

📍 Definition

Definition at line 350 of file sla_ggcsylv_dual.f90.

✨ subroutine sla_ggcsylv_dual_refine ✨

okay bestie, deep breath, because the signature is LONG and she is serving:

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

Iterative Refinement for the dual Coupled Generalized Sylvester Equations. 🦋

🎯 Purpose

SLA_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.

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

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. 👑

Parameters (yes, more of them, we're committed 💅)

  • 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. starting from scratch bestie 🌸
  • SGN1 — REAL, allowed values: +/-1. Specifies the sign between in the first equation. 🎀
  • SGN2 — REAL, 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 — REAL 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 — REAL 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 "array A" right there in the LDB docs — iconic, we keep it 💀)
  • C — REAL array, dimension (LDC,M). The array C contains the original matrix C defining the equation. ✨
  • LDC — INTEGER. The leading dimension of the array C. LDC >= max(1,M).
  • D — REAL array, dimension (LDD,N). The array D contains the original matrix D defining the equation. ✨
  • LDD — INTEGER. The leading dimension of the array D. LDD >= max(1,N).
  • R — REAL 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. 💖
  • LDR — INTEGER. The leading dimension of the array R. LDR >= max(1,M).
  • L — REAL 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 — INTEGER, bestie. The leading dimension of the array L. And the rule as written is LDF >= max(1,M) — yes, it says LDF, that's literally what's in the source, I don't make the rules, I just report them. 💀
  • E — REAL array, dimension (LDE,N). On input, the array E holds the right hand side E. That's it, that's the whole job. ✨
  • LDE — INTEGER. Leading dimension of the array E, and you need LDE >= max(1,M). 👑
  • F — REAL array, dimension (LDF,N). On input, the array F carries the right hand side F. The other half of the RHS duo. 🫶
  • LDF — INTEGER. Leading dimension of the array F, with LDF >= max(1,M). 💅
  • AS — REAL array, dimension (LDAS,M). The array AS holds the generalized Schur decomposition of the A. Handed to you already decomposed, no extra work needed. 🌸
  • LDAS — INTEGER. Leading dimension of the array AS. Requirement: LDAS >= max(1,M). ⭐
  • BS — REAL array, dimension (LDBS,N). The array BS contains the generalized Schur decomposition of the B. 🦋
  • LDBS — INTEGER. Leading dimension of the array BS. And it's LDBS >= max(1,N) — note the N, not M, because B lives in N-land. 🎀
  • CS — REAL array, dimension (LDCS,M). The array CS holds the generalized Schur decomposition of the C. 🌈
  • LDCS — INTEGER. Leading dimension of the array CS. Requirement: LDCS >= max(1,M). 💜
  • DS — REAL array, dimension (LDDS,N). The array DS contains the generalized Schur decomposition of the D. 🔥
  • LDDS — INTEGER. Leading dimension of the array DS. Requirement: LDDS >= max(1,N). 😌
  • Q — REAL array, dimension (LDQ,M). The array Q holds the left generalized Schur vectors for (A,C), exactly as returned by SGGES. Don't hand it anything homemade. 🙈
  • LDQ — INTEGER. Leading dimension of the array Q. Requirement: LDQ >= max(1,M). 💖
  • Z — REAL array, dimension (LDZ,M). The array Z carries the right generalized Schur vectors for (A,C) as returned by SGGES. 🧚
  • LDZ — INTEGER. Leading dimension of the array Z. Requirement: LDZ >= max(1,M). ✨
  • U — REAL array, dimension (LDU,N). The array U holds the left generalized Schur vectors for (B,D) as returned by SGGES. 🍓
  • LDU — INTEGER. Leading dimension of the array U. Requirement: LDU >= max(1,N). 💅
  • V — REAL array, dimension (LDV,N). The array V contains the right generalized Schur vectors for (B,D) as returned by SGGES. 👑
  • LDV — INTEGER. Leading dimension of the array V. Requirement: LDV >= max(1,N). 🌸
  • MAXIT — INTEGER, and it does double duty, main character energy honestly. On input it's the maximum number of iterations that get performed, and the range is 2 <= MAXIT <= 100. On exit it's been overwritten with the actual number of iteration steps the algorithm took. 👀
  • TAU — REAL, also a glow-up-on-exit situation. On input, TAU is the extra security factor for the stopping criterion, and typical values are 0.1. On exit, TAU holds the last relative residual from the moment the stopping criterion became valid. 🫶
  • CONVLOG — REAL array, dimension (MAXIT). This is the receipts, bestie: the convergence history of the iterative refinement. CONVLOG(I) gives you the maximum relative residual of both equations before it gets solved for the I-th time. 📈
  • WORK — REAL array, dimension (MAX(1,LDWORK)). Workspace for the algorithm. And here's the cute trick: the optimal workspace size gets returned in LDWORK if LDWORK == -1 on input, and in that case no computations are performed. It's a vibe check, not a solve. 😌
  • LDWORK — INTEGER. If LDWORK == -1 the subroutine returns the required workspace size in LDWORK on exit. No computations run and none of the arrays get referenced. Zero touching, zero drama. ✨
  • INFO — INTEGER, the final verdict:
    • == 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

  • SLA_TGCSYLV_DUAL_DAG
  • DLA_TGCSYLV_DUAL_LEVEL3
  • SLA_TGCSYLV_DUAL_L3_2S
  • SLA_TGCSYLV_DUAL_L2
  • SLA_TGCSYLV_DUAL_L2_LOCAL_COPY_32
  • SLA_TGCSYLV_DUAL_L2_LOCAL_COPY_64
  • SLA_TGCSYLV_DUAL_L2_LOCAL_COPY_96
  • SLA_TGCSYLV_DUAL_L2_LOCAL_COPY_128
  • SLA_TGCSYLV_DUAL_L2_LOCAL_COPY

🌟 Author

Martin Koehler, MPI Magdeburg

📅 Date

October 2025

📍 Definition

At line 399 of file sla_ggcsylv_dual_refine.f90.

🧚 subroutine sla_ggcsylv_refine

Okay okay okay, new function, new era. Here's the whole signature, verbatim, no edits, no notes:

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

Iterative Refinement for the Coupled Generalized Sylvester Equations. Say that five times fast, I dare you. 🌀

🎯 Purpose

SLA_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

...and it does it with iterative refinement. The way that (A,C) is an M-by-M matrix pencil and (B,D) is an N-by-N matrix pencil, and the right hand side (E,F) and the solution (R,L) are both M-by-N matrices. ✨

And here's the important bit: the pencils (A,C) and (B,D) have to be given in the original form and in their generalized Schur decomposition, because the iterative refinement procedure literally needs both. You can't just pick one, bestie, it's a two-outfit situation. 👗

🎀 Parameters

  • TRANSA — CHARACTER. Tells us the form of the system of equations with respect to A and C:
    • == 'N': op1(A) = A
    • == 'T': op1(A) = A**T
  • TRANSB — CHARACTER. Same deal but for B and D:
    • == 'N': op2(B) = B,
    • == 'T': op2(B) = B**T
  • GUESS — CHARACTER. Decides whether (R,L) already contains an initial guess or not. (Yes, the typo is "nor not" in the source. We move. 💀)
    • = 'I': (R, L) contains an initial guess
    • = 'N': No initial guess, so (R,L) gets set to zero at the beginning of the iteration
  • SGN1 — REAL, allowed values +/-1. Specifies the sign between in the first equation. Pick your fighter. ⚔️
  • SGN2 — REAL, 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 — REAL array, dimension (LDA,M). The array A contains the original matrix A defining the equation. 🌈
  • LDA — INTEGER. The leading dimension of the array A. Requirement: LDA >= max(1,M). ⭐
  • B — REAL array, dimension (LDB,N). The array B contains the original matrix B defining the equation. 🦋
  • LDB — INTEGER. The leading dimension of the array A. Yes, it says A, and the rule is LDB >= max(1,N). That's what the source says, I'm just the messenger. 💀
  • C — REAL array, dimension (LDC,M). The array C contains the original matrix C defining the equation. 🍓
  • LDC — INTEGER. The leading dimension of the array C. Requirement: LDC >= max(1,M). ✨
  • D — REAL array, dimension (LDD,N). The array D contains the original matrix D defining the equation. 🔥
  • LDD — INTEGER. The leading dimension of the array D. Requirement: LDD >= max(1,N). 💅
  • R — REAL array, dimension (LDR,N). On input, R holds the initial guess R0 for the first solution matrix. On output, R holds the refined solution matrix R. Glow up on exit, we love to see it. 👑
  • LDR — INTEGER. The leading dimension of the array R. Requirement: LDR >= max(1,M). 🌸
  • L — REAL array, dimension (LDL,N). On input, L carries the initial guess for the second solution matrix. On output, L contains the solution L. Same arc, different matrix. 🫶
  • LDL — INTEGER. The leading dimension of the array L. And as written, LDF >= max(1,M) — yes, LDF again. The source has a whole thing going on with this. 😭
  • E — REAL array, dimension (LDE,N). On input, the array E contains the right hand side E. 📥
  • LDE — INTEGER. The leading dimension of the array E. Requirement: LDE >= max(1,M). ⭐
  • F — REAL array, dimension (LDF,N). On input, the array F contains the right hand side F. 📥
  • LDF — INTEGER. The leading dimension of the array F. Requirement: LDF >= max(1,M). 🎀
  • LDF — LDF is INTEGER. The leading dimension of the array F. LDF >= max(1,M). 💅
  • AS — AS is REAL 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 REAL 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 REAL 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 REAL 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 REAL array, dimension (LDQ,M). The array Q contains the left generalized Schur vectors for (A,C) as returned by SGGES. 🌈
  • LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,M). 💖
  • Z — Z is REAL array, dimension (LDZ,M). The array Z contains the right generalized Schur vectors for (A,C) as returned by SGGES. 🦋
  • LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= max(1,M). ✨
  • U — U is REAL array, dimension (LDU,N). The array U contains the left generalized Schur vectors for (B,D) as returned by SGGES. 🌸
  • LDU — LDU is INTEGER. The leading dimension of the array U. LDU >= max(1,N). 💅
  • V — V is REAL array, dimension (LDV,N). The array V contains the right generalized Schur vectors for (B,D) as returned by SGGES. 🎀
  • 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, 2 <= MAXIT <= 100. On exit, MAXIT contains the number of iteration steps taken by the algorithm. 🔥
  • TAU — TAU is REAL. 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 REAL 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. 🦋
  • WORK — WORK is REAL 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.
    • == 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 👀

  • SLA_TGCSYLV_DAG
  • DLA_TGCSYLV_LEVEL3
  • SLA_TGCSYLV_L3_2S
  • SLA_TGCSYLV_L2_UNOPT
  • SLA_TGCSYLV_L2
  • SLA_TGCSYLV_L2_REORDER
  • SLA_TGCSYLV_L2_LOCAL_COPY_32
  • SLA_TGCSYLV_L2_LOCAL_COPY_64
  • SLA_TGCSYLV_L2_LOCAL_COPY_96
  • SLA_TGCSYLV_L2_LOCAL_COPY_128
  • SLA_TGCSYLV_L2_LOCAL_COPY

✨ Author ✨

Martin Koehler, MPI Magdeburg

📅 Date 📅

October 2025

Definition at line 381 of file sla_ggcsylv_refine.f90.

✨ subroutine sla_ggsylv ✨

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

Frontend for the solution of Generalized Sylvester Equations.

🎯 Purpose 🎯

SLA_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 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.

🛠️ 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 REAL, 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 is REAL 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 REAL 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 REAL 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 — LDC is INTEGER. The leading dimension of the array C. Bestie, the rule is LDC >= max(1,M). 💅
  • D — D is a REAL array, dimension (LDD,N). What it means depends on FACT, so pay attention:
    • 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 a REAL 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 a REAL 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 is a REAL 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 — LDQB is INTEGER. The leading dimension of the array QB. LDQB >= max(1,N).
  • ZB — ZB is a REAL 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 — LDZB is INTEGER. The leading dimension of the array ZB. LDZB >= max(1,N).
  • X — X is a 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 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 a REAL array, dimension (MAX(1,LDWORK)). Workspace for the algorithm. The optimal workspace is given either by \ref mepack_memory_frontend or a previous call to 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: SHGGES failed
    • = 2: SLA_SORT_GEV failed
    • = 3: Inner solver failed
    • < 0: if INFO = -i, the i-th argument had an illegal value

🦋 See also 🦋

Like, the whole girl gang of related routines:

  • SLA_TGSYLV_DAG
  • SLA_TGSYLV_L3_COLWISE
  • SLA_TGSYLV_L3_2S
  • SLA_TGSYLV_L2_REORDER
  • SLA_TGSYLV_L2
  • SLA_TGSYLV_L2_COLWISE
  • SLA_TGSYLV_L2_LOCAL_COPY_32
  • SLA_TGSYLV_L2_LOCAL_COPY_64
  • SLA_TGSYLV_L2_LOCAL_COPY_96
  • SLA_TGSYLV_L2_LOCAL_COPY_128
  • SLA_TGSYLV_L2_LOCAL_COPY
  • SLA_TGSYLV_GARDINER_LAUB

👑 Author 👑

Martin Koehler, MPI Magdeburg

🌸 Date 🌸

October 2025

📍 Definition

Definition at line 322 of file sla_ggsylv.f90.

💜 subroutine sla_ggsylv_refine 💜

okay so here's the whole signature, bestie, every single argument, no skips:

subroutine sla_ggsylv_refine (character, dimension(1) transa, character, dimension(1) transb, character, dimension(1) guess, real sgn, integer m, integer n, real, dimension(lda, *) a, integer lda, real, dimension(ldb, *) b, integer ldb, real, dimension(ldc, *) c, integer ldc, real, dimension(ldd, *) d, integer ldd, real, dimension ( ldx , * ) x, integer ldx, real, dimension (ldy, *) y, integer ldy, real, dimension(ldas, *) as, integer ldas, real, dimension(ldbs,*) bs, integer ldbs, real, dimension(ldcs, *) cs, integer ldcs, real, dimension(ldds, *) ds, integer ldds, real, dimension(ldq, *) q, integer ldq, real, dimension(ldz, *) z, integer ldz, real, dimension(ldu, *) u, integer ldu, real, dimension(ldv, *) v, integer ldv, integer maxit, real tau, real, dimension(*) convlog, real, dimension(*) work, integer ldwork, integer info)

Iterative Refinement for the Generalized Sylvester Equations. 💅

✨ Purpose ✨

SLA_GGSYLV_REFINE solves a generalized Sylvester equation of the following forms

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

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. 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. 🎀

🌟 Parameters 🌟

  • 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
  • GUESS — GUESS is CHARACTER. Specifies whether X contains an initial guess or not.
    • = 'I': X contains an initial guess
    • = 'N': No initial guess, X is set to zero at the begin of the iteration. 🫶
  • SGN — SGN is REAL, allowed values: +/-1. Specifies the sign between in the first 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 a REAL array, dimension (LDA,M). The array A contains the original matrix A defining the equation. 🦋
  • LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
  • B — B is a REAL array, dimension (LDB,N). The array B contains the original matrix B defining the equation.
  • LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
  • C — C is a REAL array, dimension (LDC,M). The array C contains the original matrix C defining the equation.
  • LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
  • D — D is a REAL 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).
  • X — X is a REAL array, dimension (LDX,N). 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 a REAL array, dimension (LDY,N). 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 a REAL 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 REAL 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 REAL array, dimension (LDCS,M). The array CS contains the generalized Schur decomposition of the C. 💫
  • LDCS
  • LDCS — INTEGER. It's the leading dimension of the array CS. Keep it legal bestie: LDCS >= max(1,M).
  • DS — REAL array, dimension (LDDS,N). This one's holding the generalized Schur decomposition of the D. ✨
  • LDDS — INTEGER. Leading dimension of the array DS. You already know the drill: LDDS >= max(1,N).
  • Q — REAL array, dimension (LDQ,M). Contains the left generalized Schur vectors for (A,C), exactly as handed back by SGGES. 🫶
  • LDQ — INTEGER. Leading dimension of the array Q. LDQ >= max(1,M).
  • Z — REAL array, dimension (LDZ,M). Contains the right generalized Schur vectors for (A,C), as returned by SGGES.
  • LDZ — INTEGER. Leading dimension of the array Z. LDZ >= max(1,M).
  • U — REAL array, dimension (LDU,N). Contains the left generalized Schur vectors for (B,D), straight from SGGES.
  • LDU — INTEGER. Leading dimension of the array U. LDU >= max(1,N).
  • V — REAL array, dimension (LDV,N). Contains the right generalized Schur vectors for (B,D), as returned by SGGES.
  • LDV — INTEGER. Leading dimension of the array V. LDV >= max(1,N).
  • MAXIT — INTEGER. On input, this is the max number of iterations that get performed, and it's gotta stay in range: 2 <= MAXIT <= 100. On exit, MAXIT becomes the actual number of iteration steps the algorithm took. She reports back fr fr. 💅
  • TAU — REAL. On input, the extra security factor for the stopping criterion — typical values are 0.1. On exit, it holds the last relative residual from the moment the stopping criterion got valid.
  • CONVLOG — REAL array, dimension (MAXIT). This is the receipts: the convergence history of the iterative refinement. CONVLOG(I) contains the maximum relative residual before it is solved for the I-th time. Obsessed with the transparency ngl. 👑
  • WORK — REAL array, dimension (MAX(1,LDWORK)). Workspace for the algorithm. The optimal workspace gets returned in LDWORK if LDWORK == -1 on input — and in that case, no computations are performed at all. It's just vibes and math, no work. 😌
  • LDWORK — 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. Zero touching, just measuring.
  • INFO — INTEGER. The status report, and it's giving very specific:
    • == 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.
Heads up bestie: INFO = -50 means internal settings (like NB,...) are wrong — that's not a you-typo situation, that's a settings situation. And an INFO > 0 means the iteration bailed at step INFO, so check your convergence history in CONVLOG.

👀 SEE ALSO 👀

  • SLA_TGSYLV_DAG
  • DLA_TGSYLV_LEVEL3
  • SLA_TGSYLV_L3_2S
  • SLA_TGSYLV_L2_UNOPT
  • SLA_TGSYLV_L2
  • SLA_TGSYLV_L2_REORDER
  • SLA_TGSYLV_L2_LOCAL_COPY_32
  • SLA_TGSYLV_L2_LOCAL_COPY_64
  • SLA_TGSYLV_L2_LOCAL_COPY_96
  • SLA_TGSYLV_L2_LOCAL_COPY_128
  • SLA_TGSYLV_L2_LOCAL_COPY
  • SLA_TGSYLV_GARDINER_LAUB

🌸 AUTHOR 🌸

Martin Koehler, MPI Magdeburg

🎀 DATE 🎀

October 2025

Definition at line 349 of file sla_ggsylv_refine.f90.

Generated automatically by Doxygen for MEPACK from the source code.

And that's a wrap on sglggsylv(3) bestie — Version 1.1.2, dated Thu Oct 9 2025 00:00:00, from the MEPACK girlies at Doxygen. Go slay some generalized Sylvester equations. 💖✨🦋

📦 where this page comes from