cggsylv(3)

📦

version 1.1.2 · 3 versions

1.1.2 · fedora 43 (latest)
1.1.1 · fedora 43
1.1.2 · fedora 44

, in fedora 43

🌸 cggsylv — the C-Interface, bestie 💅

okay so welcome to cggsylv(3) from MEPACK, and yes we're doing the whole thing, no skimming, periodt ✨

🎀 NAME 🎀

cggsylv — C-Interface

C-Interface for generalized Sylvester equations. 💖

✨ SYNOPSIS ✨

🫶 Functions

void mepack_double_ggcsylv (const char *FACTA, const char *FACTB, const char *TRANSA, const char *TRANSB, double SGN1, double SGN2, int M, int N, double *A, int LDA, double *B, int LDB, double *C, int LDC, double *D, int LDD, double *QA, int LDQA, double *ZA, int LDZA, double *QB, int LDQB, double *ZB, int LDZB, double *E, int LDE, double *F, int LDF, double *SCALE, double *WORK, size_t LDWORK, int *INFO)

Frontend for the solution of Coupled Generalized Sylvester Equations. 🔥

void mepack_single_ggcsylv (const char *FACTA, const char *FACTB, const char *TRANSA, const char *TRANSB, float SGN1, float SGN2, int M, int N, float *A, int LDA, float *B, int LDB, float *C, int LDC, float *D, int LDD, float *QA, int LDQA, float *ZA, int LDZA, float *QB, int LDQB, float *ZB, int LDZB, float *E, int LDE, float *F, int LDF, float *SCALE, float *WORK, size_t LDWORK, int *INFO)

Frontend for the solution of Coupled Generalized Sylvester Equations. 🔥

void mepack_double_ggcsylv_dual (const char *FACTA, const char *FACTB, const char *TRANSA, const char *TRANSB, double SGN1, double SGN2, int M, int N, double *A, int LDA, double *B, int LDB, double *C, int LDC, double *D, int LDD, double *QA, int LDQA, double *ZA, int LDZA, double *QB, int LDQB, double *ZB, int LDZB, double *E, int LDE, double *F, int LDF, double *SCALE, double *WORK, size_t LDWORK, int *INFO)

Frontend for the solution of the dual Coupled Generalized Sylvester Equations. 💜

void mepack_single_ggcsylv_dual (const char *FACTA, const char *FACTB, const char *TRANSA, const char *TRANSB, float SGN1, float SGN2, int M, int N, float *A, int LDA, float *B, int LDB, float *C, int LDC, float *D, int LDD, float *QA, int LDQA, float *ZA, int LDZA, float *QB, int LDQB, float *ZB, int LDZB, float *E, int LDE, float *F, int LDF, float *SCALE, float *WORK, size_t LDWORK, int *INFO)

Frontend for the solution of the dual Coupled Generalized Sylvester Equations. 💜

void mepack_double_ggsylv (const char *FACTA, const char *FACTB, const char *TRANSA, const char *TRANSB, double SGN, int M, int N, double *A, int LDA, double *B, int LDB, double *C, int LDC, double *D, int LDD, double *QA, int LDQA, double *ZA, int LDZA, double *QB, int LDQB, double *ZB, int LDZB, double *X, int LDX, double *SCALE, double *WORK, size_t LDWORK, int *INFO)

Frontend for the solution of Generalized Sylvester Equations. 🌈

void mepack_single_ggsylv (const char *FACTA, const char *FACTB, const char *TRANSA, const char *TRANSB, float SGN, int M, int N, float *A, int LDA, float *B, int LDB, float *C, int LDC, float *D, int LDD, float *QA, int LDQA, float *ZA, int LDZA, float *QB, int LDQB, float *ZB, int LDZB, float *X, int LDX, float *SCALE, float *WORK, size_t LDWORK, int *INFO)

Frontend for the solution of Generalized Sylvester Equations. 🌈

void mepack_double_ggcsylv_refine (const char *TRANSA, const char *TRANSB, const char *GUESS, double SGN1, double SGN2, int M, int N, double *A, int LDA, double *B, int LDB, double *C, int LDC, double *D, int LDD, double *R, int LDR, double *L, int LDL, double *E, int LDE, double *F, int LDF, double *AS, int LDAS, double *BS, int LDBS, double *CS, int LDCS, double *DS, int LDDS, double *Q, int LDQ, double *Z, int LDZ, double *U, int LDU, double *V, int LDV, int *MAXIT, double *TAU, double *CONVLOG, double *WORK, size_t LDWORK, int *INFO)

Iterative Refinement for the Coupled Generalized Sylvester Equations. ✨

void mepack_single_ggcsylv_refine (const char *TRANSA, const char *TRANSB, const char *GUESS, float SGN1, float SGN2, int M, int N, float *A, int LDA, float *B, int LDB, float *C, int LDC, float *D, int LDD, float *R, int LDR, float *L, int LDL, float *E, int LDE, float *F, int LDF, float *AS, int LDAS, float *BS, int LDBS, float *CS, int LDCS, float *DS, int LDDS, float *Q, int LDQ, float *Z, int LDZ, float *U, int LDU, float *V, int LDV, int *MAXIT, float *TAU, float *CONVLOG, float *WORK, size_t LDWORK, int *INFO)

Iterative Refinement for the Coupled Generalized Sylvester Equations. ✨

void mepack_double_ggcsylv_dual_refine (const char *TRANSA, const char *TRANSB, const char *GUESS, double SGN1, double SGN2, int M, int N, double *A, int LDA, double *B, int LDB, double *C, int LDC, double *D, int LDD, double *R, int LDR, double *L, int LDL, double *E, int LDE, double *F, int LDF, double *AS, int LDAS, double *BS, int LDBS, double *CS, int LDCS, double *DS, int LDDS, double *Q, int LDQ, double *Z, int LDZ, double *U, int LDU, double *V, int LDV, int *MAXIT, double *TAU, double *CONVLOG, double *WORK, size_t LDWORK, int *INFO)

Iterative Refinement for the dual Coupled Generalized Sylvester Equations. 💫

void mepack_single_ggcsylv_dual_refine (const char *TRANSA, const char *TRANSB, const char *GUESS, float SGN1, float SGN2, int M, int N, float *A, int LDA, float *B, int LDB, float *C, int LDC, float *D, int LDD, float *R, int LDR, float *L, int LDL, float *E, int LDE, float *F, int LDF, float *AS, int LDAS, float *BS, int LDBS, float *CS, int LDCS, float *DS, int LDDS, float *Q, int LDQ, float *Z, int LDZ, float *U, int LDU, float *V, int LDV, int *MAXIT, float *TAU, float *CONVLOG, float *WORK, size_t LDWORK, int *INFO)

Iterative Refinement for the dual Coupled Generalized Sylvester Equations. 💫

void mepack_double_ggsylv_refine (const char *TRANSA, const char *TRANSB, const char *GUESS, double SGN, int M, int N, double *A, int LDA, double *B, int LDB, double *C, int LDC, double *D, int LDD, double *X, int LDX, double *Y, int LDY, double *AS, int LDAS, double *BS, int LDBS, double *CS, int LDCS, double *DS, int LDDS, double *Q, int LDQ, double *Z, int LDZ, double *U, int LDU, double *V, int LDV, int *MAXIT, double *TAU, double *CONVLOG, double *WORK, size_t LDWORK, int *INFO)

Iterative Refinement for the Generalized Sylvester Equations. 🦋

void mepack_single_ggsylv_refine (const char *TRANSA, const char *TRANSB, const char *GUESS, float SGN, int M, int N, float *A, int LDA, float *B, int LDB, float *C, int LDC, float *D, int LDD, float *X, int LDX, float *Y, int LDY, float *AS, int LDAS, float *BS, int LDBS, float *CS, int LDCS, float *DS, int LDDS, float *Q, int LDQ, float *Z, int LDZ, float *U, int LDU, float *V, int LDV, int *MAXIT, float *TAU, float *CONVLOG, float *WORK, size_t LDWORK, int *INFO)

Iterative Refinement for the Generalized Sylvester Equations. 🦋

💖 Detailed Description 💖

C-Interface for generalized Sylvester equations.

So here's the tea ☕: the Fortran routines that solve the generalized Sylvester equation with arbitrary coefficients are wrapped in C so you can actually get to them without crying, bestie. The way that these wrapper routines work? Every single one of them is a direct wrapper to the corresponding Fortran subroutine, with no sanity checks — nope, not one. 🙈 Those checks are done by the Fortran routines themselves, so don't come for the wrappers.

The only difference is that the C interface does not allow LAPACK-like work_space queries. Not a vibe, I know. 😭 For that, you need to use the mepack_memory_frontend function. iykyk.

👑 Function Documentation 👑

`void mepack_double_ggcsylv (const char * FACTA, const char * FACTB, const char * TRANSA, const char * TRANSB, double SGN1, double SGN2, int M, int N, double * A, int LDA, double * B, int LDB, double * C, int LDC, double * D, int LDD, double * QA, int LDQA, double * ZA, int LDZA, double * QB, int LDQB, double * ZB, int LDZB, double * E, int LDE, double * F, int LDF, double * SCALE, double * WORK, size_t LDWORK, int * INFO)`

Frontend for the solution of Coupled Generalized Sylvester Equations. 🔥

🧚 Purpose

mepack_double_ggcsylv solves a 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 matrix 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. 💅

🍓 Remarks

This function is a wrapper for dla_ggcsylv.

🌸 See also

dla_ggcsylv

⭐ Parameters

FACTA — bestie, this one is a String, and it 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 — also a String 🎀, and it 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 — String again, she's consistent 💁♀️. Specifies the form of the system of equations with respect to A and C :
- == 'N': op1(A) = A
- == 'T': op1(A) = A**T
TRANSB — you guessed it, a String. ✨ 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 — a DOUBLE PRECISION array, dimension (LDA,M). bestie this one's whole personality depends on FACT, so listen up:
- If FACT == "N", the matrix A is a general matrix and it gets overwritten with the (quasi-) upper triangular factor S of the Schur decomposition of (A,C). bye original A 💀
- If FACT == "F", the matrix A already contains its (quasi-) upper triangular matrix S of the Schur decomposition of (A,C).
- If FACT == "H", 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). no cap.
B — DOUBLE PRECISION array, dimension (LDB,N). same energy, different letter:
- If FACT == "N", 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 == "F", the matrix B contains its (quasi-) upper triangular matrix U of the Schur decomposition of (B,D).
- If FACT == "H", 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 == "N", 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 == "F", the matrix C contains its upper triangular matrix R of the Schur decomposition of (A,C).
- If FACT == "H", 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 — DOUBLE PRECISION array, dimension (LDD,N):
- If FACT == "N", 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 == "F", the matrix D contains its upper triangular matrix V of the Schur decomposition of (B,D).
- If FACT == "H", 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 == "N", 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 == "F", the matrix QA contains the left Schur vectors of (A,C).
- If FACT == "H", 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 == "N", 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 == "F", the matrix ZA contains the right Schur vectors of (A,C).
- If FACT == "H", 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 == "N", 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 == "F", the matrix QB contains the left Schur vectors of (B,D).
- If FACT == "H", 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 == "N", 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 == "F", the matrix ZB contains the right Schur vectors of (B,D).
- If FACT == "H", 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. glow up moment fr ✨
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. she's the safety net bestie, respect her 🫶
WORK — DOUBLE PRECISION array, dimension (MAX(1,LDWORK)). Workspace for the algorithm. The optimal workspace is given by \ref mepack_memory_frontend.
LDWORK — INTEGER. Size of the workspace for the algorithm counted in floating point numbers of the actual precision. The C interface does not support the workspace query by setting LDWORK == -1 on input. In this case, the \ref mepack_memory_frontend function have to be used.
INFO — INTEGER, the receipts:
- == 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

🚨 Attention

The Fortran/LAPACK-like workspace query with setting LDWORK=-1 on input will not work in the C interface. One have to use the mepack_memory_frontend function for this purpose.

🌸 Author

Martin Koehler, MPI Magdeburg

📅 Date

October 2025

📍 Definition

At line 318 of file cgsylv.c.

👑 `mepack_double_ggcsylv_dual`

void mepack_double_ggcsylv_dual (const char * FACTA, const char * FACTB,
    const char * TRANSA, const char * TRANSB, double SGN1, double SGN2, int
    M, int N, double * A, int LDA, double * B, int LDB, double * C, int LDC,
    double * D, int LDD, double * QA, int LDQA, double * ZA, int LDZA,
    double * QB, int LDQB, double * ZB, int LDZB, double * E, int LDE,
    double * F, int LDF, double * SCALE, double * WORK, size_t LDWORK, int *
    INFO)

Frontend for the solution of the dual Coupled Generalized Sylvester Equations. yes she's the dual one, not to be confused, iykyk 💅

✨ Purpose

mepack_double_ggcsylv_dual 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). the way the transposes just flip the whole narrative 😭

💬 Remarks

This function is a wrapper for dla_ggcsylv_dual.

👀 See also

dla_ggcsylv_dual

🎀 Parameters

FACTA — String. 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 — String. 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 — String. Specifies the form of the system of equations with respect to A and C :
- == 'N': op1(A) = A
- == 'T': op1(A) = A**T
TRANSB — String

TRANSB

TRANSB is a String, bestie, and it tells us 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. It specifies the sign between in the first equation. That's the vibe — just a sign flip, but it changes everything. 💅

SGN2

SGN2 is DOUBLE PRECISION, allowed values: +/-1. It specifies the sign between in the second equation. Yes queen, second equation gets her own sign too. ✨

M

M is INTEGER. It's the order of the matrices A and C. And it has to be M >= 0, no cap.

N

N is INTEGER. It's the order of the matrices B and D. Also N >= 0. Iconic symmetry fr fr. 🦋

A

A is a DOUBLE PRECISION array, dimension (LDA,M). What she is depends on FACT, so pay attention bestie:

If FACT == "N", 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 == "F", the matrix A contains its (quasi-) upper triangular matrix S of the Schur decomposition of (A,C).
If FACT == "H", 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. Constraint: LDA >= max(1,M). Don't play with her. 🎀

B

B is a DOUBLE PRECISION array, dimension (LDB,N). Again, FACT decides her whole storyline:

If FACT == "N", 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 == "F", the matrix B contains its (quasi-) upper triangular matrix U of the Schur decomposition of (B,D).
If FACT == "H", 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. Constraint: LDB >= max(1,N). ⭐

C

C is a DOUBLE PRECISION array, dimension (LDC,M). Three moods, same matrix:

If FACT == "N", 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 == "F", the matrix C contains its upper triangular matrix R of the Schur decomposition of (A,C).
If FACT == "H", 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. Constraint: LDC >= max(1,M). 🌸

D

D is a DOUBLE PRECISION array, dimension (LDD,N). And yes, she's got range too:

If FACT == "N", 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 == "F", the matrix D contains its upper triangular matrix V of the Schur decomposition of (B,D).
If FACT == "H", 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. Constraint: LDD >= max(1,N). 💜

QA

QA is a DOUBLE PRECISION array, dimension (LDQA,M). She's all about the left Schur vectors of (A,C):

If FACT == "N", 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 == "F", the matrix QA contains the left Schur vectors of (A,C).
If FACT == "H", 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. Constraint: LDQA >= max(1,M). 🎀

ZA

ZA is a DOUBLE PRECISION array, dimension (LDZA,M). Now we're doing right Schur vectors of (A,C), okurrr:

If FACT == "N", 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 == "F", the matrix ZA contains the right Schur vectors of (A,C).
If FACT == "H", 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. Constraint: LDZA >= max(1,M). ✨

QB

QB is a DOUBLE PRECISION array, dimension (LDQB,N). Left Schur vectors of (B,D), bestie:

If FACT == "N", 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 == "F", the matrix QB contains the left Schur vectors of (B,D).
If FACT == "H", the matrix QB is an empty M-by-M matrix on input and contains the left Schur vectors of (B,D) on output.

⚠️ heads up: that last FACT == "H" line says M-by-M, not N-by-N. I'm not gonna "fix" it for her — that's literally what the page says, so it stays. 💀

LDQB

LDQB is INTEGER — the leading dimension of the array QB. Constraint: LDQB >= max(1,N). 🌈

ZB

ZB is a DOUBLE PRECISION array, dimension (LDZB,N). Right Schur vectors of (B,D), periodt:

If FACT == "N", 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 == "F", the matrix ZB contains the right Schur vectors of (B,D).
If FACT == "H", the matrix ZB is an empty M-by-M matrix on input and contains the right Schur vectors of (B,D) on output.

⚠️ same lil' quirk here: FACT == "H" says M-by-M. Copying the page exactly, no edits. 🙈

LDZB

LDZB is INTEGER — the leading dimension of the array ZB. Constraint: LDZB >= max(1,N). 🫶

E

E is a 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

LDE is INTEGER — the leading dimension of the array E. Constraint: LDE >= max(1,M). 🌸

F

F is a 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

LDF is INTEGER — the leading dimension of the array F. Constraint: LDF >= max(1,M). 💜

SCALE

SCALE is DOUBLE PRECISION. She's a scaling factor to prevent the overflow in the result. The tea: 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. So if SCALE is anything but 1, something was lowkey fighting for its life in there. 😭

WORK

WORK is a DOUBLE PRECISION array, dimension (MAX(1,LDWORK)). It's workspace for the algorithm. The optimal workspace is given by \ref mepack_memory_frontend. 👑

LDWORK

LDWORK is INTEGER — size of the workspace for the algorithm counted in floating point numbers of the actual precision.

🚨 real talk: the C interface does not support the workspace query by setting LDWORK == -1 on input. In that case, the \ref mepack_memory_frontend function have to be used. No shortcut, bestie.

INFO

INFO is INTEGER. Read her like a mood ring:

== 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

👀 Attention

The Fortran/LAPACK-like workspace query with setting LDWORK=-1 on input will not work in the C interface. One have to use the mepack_memory_frontend function for this purpose. Don't come for me, I'm just the messenger. 💅

✍️ Author

Martin Koehler, MPI Magdeburg

📅 Date

October 2025

Definition at line 335 of file cgsylv_dual.c.

💫 void mepack_double_ggcsylv_dual_refine

void mepack_double_ggcsylv_dual_refine (const char * TRANSA, const char * TRANSB, const char * GUESS, double SGN1, double SGN2, int M, int N, double * A, int LDA, double * B, int LDB, double * C, int LDC, double * D, int LDD, double * R, int LDR, double * L, int LDL, double * E, int LDE, double * F, int LDF, double * AS, int LDAS, double * BS, int LDBS, double * CS, int LDCS, double * DS, int LDDS, double * Q, int LDQ, double * Z, int LDZ, double * U, int LDU, double * V, int LDV, int * MAXIT, double * TAU, double * CONVLOG, double * WORK, size_t LDWORK, int * INFO)

Iterative Refinement for the dual Coupled Generalized Sylvester Equations. She's the glow-up pass, bestie. 🧚

Purpose:

mepack_double_ggcsylv_dual_refine 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). The way that the dual just is the transpose situation… she ate. 🔥

Remarks

This function is a wrapper for dla_ggcsylv_dual_refine.

Parameters

TRANSA

TRANSA is String. It 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 String. It 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 String. It specifies whether (R,L) contains an initial guess on input or not:

= 'I': (R,L) contains an initial guess for the solution
== 'N': No initial guess is provided. (R,L) are set to zero.

SGN1 — DOUBLE PRECISION, allowed values: +/-1. It specifies the sign between in the first equation. 🎀
SGN2 — DOUBLE PRECISION, allowed values: +/-1. It 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). ngl bestie, the page literally says A right there and not B — not me fixing it, we keep it exactly how it's written, periodt. 🙈
C — DOUBLE PRECISION 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 — DOUBLE PRECISION 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 — DOUBLE PRECISION array, dimension (LDR,N). On input, the array R contains the initial guess for the first solution. On output, the array R contains the solution R. 🫶
LDR — INTEGER. The leading dimension of the array R. LDR >= max(1,M). ✨
L — DOUBLE PRECISION array, dimension (LDL,N). On input, the array L contains the initial guess for the second solution. On output, the array L contains the second solution. 🫶
LDL — INTEGER. The leading dimension of the array L. LDL >= max(1,M). ✨
E — DOUBLE PRECISION array, dimension (LDE,N). On input, the array E contains the right hand side E. 🌸
LDE — INTEGER. The leading dimension of the array E. LDE >= max(1,M). ✨
F — DOUBLE PRECISION array, dimension (LDF,N). On input, the array F contains the right hand side F. 🌸
LDF — INTEGER. The leading dimension of the array F. LDF >= max(1,M). ✨
AS — DOUBLE PRECISION array, dimension (LDAS,M). The array AS contains the generalized Schur decomposition of the A. 🦋
LDAS — INTEGER. The leading dimension of the array AS. LDAS >= max(1,M). ✨
BS — DOUBLE PRECISION array, dimension (LDBS,N). The array BS contains the generalized Schur decomposition of the B. 🦋
LDBS — INTEGER. The leading dimension of the array BS. LDBS >= max(1,N). ✨
CS — DOUBLE PRECISION array, dimension (LDC,M). The array CS contains the generalized Schur decomposition of the C. 🦋
LDCS — INTEGER. The leading dimension of the array CS. LDCS >= max(1,M). ✨
DS — DOUBLE PRECISION array, dimension (LDDS,N). The array DS contains the generalized Schur decomposition of the D. 🦋
LDDS — INTEGER. The leading dimension of the array DS. LDDS >= max(1,N). ✨
Q — DOUBLE PRECISION array, dimension (LDQ,M). The array Q contains the left generalized Schur vectors for (A,C) as returned by DGGES. 👑
LDQ — INTEGER. The leading dimension of the array Q. LDQ >= max(1,M). ✨
Z — DOUBLE PRECISION array, dimension (LDZ,M). The array Z contains the right generalized Schur vectors for (A,C) as returned by DGGES. 👑
LDZ — INTEGER. The leading dimension of the array Z. LDZ >= max(1,M). ✨
U — DOUBLE PRECISION array, dimension (LDU,N). The array U contains the left generalized Schur vectors for (B,D) as returned by DGGES. 👑
LDU — INTEGER. The leading dimension of the array U. LDU >= max(1,N). ✨
V — DOUBLE PRECISION array, dimension (LDV,N). The array V contains the right generalized Schur vectors for (B,D) as returned by DGGES. 👑
LDV — INTEGER. The leading dimension of the array V. LDV >= max(1,N). ✨
MAXIT — INTEGER. On input, MAXIT contains the maximum number of iteration that are performed, MAXIT <= 100. On exit, MAXIT contains the number of iteration steps taken by the algorithm. 🔥
TAU — 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 — 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. 📈
WORK — DOUBLE PRECISION array, dimension (MAX(1,LDWORK)). Workspace for the algorithm. 🧰
LDWORK — INTEGER. Size of the workspace for the algorithm. This can be determined by a call \ref mepack_memory_frontend. 🧰
INFO — INTEGER. == 0: Success. > 0: Iteration failed in step INFO. < 0: if INFO == -i, the i-Th argument had an illegal value. 💀

🚨 Attention 🚨

The Fortran/LAPACK-like workspace query with setting LDWORK=-1 on input will not work in the C interface. One have to use the mepack_memory_frontend function for this purpose.

fr fr, do not try the LDWORK=-1 trick here, it's giving C interface and it simply does not go. 😭

✍️ Author

Martin Koehler, MPI Magdeburg 🌈

📅 Date

October 2025 🍓

Definition at line 374 of file cgsylv_dual.c.

🦋 `mepack_double_ggcsylv_refine` 💜

Iterative Refinement for the Coupled Generalized Sylvester Equations.

void mepack_double_ggcsylv_refine (const char * TRANSA, const char * TRANSB,
    const char * GUESS, double SGN1, double SGN2, int M, int N, double * A,
    int LDA, double * B, int LDB, double * C, int LDC, double * D, int LDD,
    double * R, int LDR, double * L, int LDL, double * E, int LDE, double *
    F, int LDF, double * AS, int LDAS, double * BS, int LDBS, double * CS,
    int LDCS, double * DS, int LDDS, double * Q, int LDQ, double * Z, int
    LDZ, double * U, int LDU, double * V, int LDV, int * MAXIT, double *
    TAU, double * CONVLOG, double * WORK, size_t LDWORK, int * INFO)

✨ Purpose ✨

mepack_double_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 matrix 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. 🌟

💅 Remarks 💅

This function is a wrapper for dla_ggcsylv_refine.

👀 See also 👀

dla_ggcsylv_refine

🎀 Parameters 🎀

TRANSA — String. Specifies the form of the system of equations with respect to A and C:
- == 'N': op1(A) = A
- == 'T': op1(A) = A**T
TRANSB — String. Specifies the form of the system of equations with respect to B and D:
- == 'N': op2(B) = B,
- == 'T': op2(B) = B**T
GUESS — String. Specifies whether (R,L) contains an initial guess on input or not.
- = 'I': (R,L) contains an initial guess for the solution
- == 'N': No initial guess is provided. (R,L) are set to zero.
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 bestie, again it says A — same energy as before, we are NOT editing it, iykyk) 🙈
C — DOUBLE PRECISION 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 — DOUBLE PRECISION 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 — DOUBLE PRECISION array, dimension (LDR,N). On input, the array R contains the initial guess for the first solution. On output, the array R contains the solution R. 🫶
LDR — INTEGER. The leading dimension of the array R. LDR >= max(1,M). ✨
L
L (DOUBLE PRECISION array, dimension (LDL,N)) — on the way in, L is carrying your initial guess for the second solution 🫶. on the way out? it's carrying the actual second solution. character development fr.
LDL (INTEGER) — the leading dimension of L. rule of the land: LDL >= max(1,M). no exceptions bestie 💅
E (DOUBLE PRECISION array, dimension (LDE,N)) — on input, E holds the right hand side E. that's it, that's the vibe ✨
LDE (INTEGER) — leading dimension of E. you need LDE >= max(1,M).
F (DOUBLE PRECISION array, dimension (LDF,N)) — on input, F holds the right hand side F. iconic, no notes 🌸
LDF (INTEGER) — leading dimension of F, and LDF >= max(1,M).
AS (DOUBLE PRECISION array, dimension (LDAS,M)) — AS contains the generalized Schur decomposition of the A. it's giving structured 💜
LDAS (INTEGER) — leading dimension of AS. LDAS >= max(1,M).
BS (DOUBLE PRECISION array, dimension (LDBS,N)) — BS contains the generalized Schur decomposition of the B.
LDBS (INTEGER) — leading dimension of BS. LDBS >= max(1,N).
CS (DOUBLE PRECISION array, dimension (LDCS,M)) — CS contains the generalized Schur decomposition of the C.
LDCS (INTEGER) — leading dimension of CS. LDCS >= max(1,M).
DS (DOUBLE PRECISION array, dimension (LDDS,N)) — DS contains the generalized Schur decomposition of the D.
LDDS (INTEGER) — leading dimension of DS. LDDS >= max(1,N).
Q (DOUBLE PRECISION array, dimension (LDQ,M)) — Q contains the left generalized Schur vectors for (A,C) as returned by DGGES. 💫
LDQ (INTEGER) — leading dimension of Q. LDQ >= max(1,M).
Z (DOUBLE PRECISION array, dimension (LDZ,M)) — Z contains the right generalized Schur vectors for (A,C) as returned by DGGES.
LDZ (INTEGER) — leading dimension of Z. LDZ >= max(1,M).
U (DOUBLE PRECISION array, dimension (LDU,N)) — U contains the left generalized Schur vectors for (B,D) as returned by DGGES.
LDU (INTEGER) — leading dimension of U. LDU >= max(1,N).
V (DOUBLE PRECISION array, dimension (LDV,N)) — V contains the right generalized Schur vectors for (B,D) as returned by DGGES. 🌈
LDV (INTEGER) — leading dimension of V. LDV >= max(1,N).
MAXIT (INTEGER) — okay so on input, MAXIT is the maximum number of iterations that get performed, and heads up: MAXIT <= 100 🚨. on exit, MAXIT becomes the number of iteration steps the algorithm actually took. glow-up AND a receipt.
TAU (DOUBLE PRECISION) — on input, TAU is the additional security factor for the stopping criterion, and typical values are 0.1. on exit, TAU is the last relative residual from when the stopping criterion got valid. it tells on itself, we love that 🙈
CONVLOG (DOUBLE PRECISION array, dimension (MAXIT)) — the CONVLOG array holds the convergence history of the iterative refinement, like a lil diary 📓. CONVLOG(I) contains the maximum relative residual of both equations before it is solved for the I-Th time.
WORK (DOUBLE PRECISION array, dimension (MAX(1,LDWORK))) — workspace for the algorithm. the behind-the-scenes bestie.
LDWORK (INTEGER) — the size of the workspace for the algorithm. you can figure this out with a call to mepack_memory_frontend.
INFO (INTEGER) — the verdict ✨
- == 0: Success 🎉
- > 0: Iteration failed in step INFO 💀
- < 0: if INFO == -i, the i-Th argument had an illegal value

🚨 Attention 🚨

The Fortran/LAPACK-like workspace query with setting LDWORK=-1 on input will not work in the C interface. One have to use the mepack_memory_frontend function for this purpose.

bestie listen. the LDWORK=-1 trick? it does NOT work here. do not try it. call mepack_memory_frontend instead. periodt 💅

🌸 Author 🌸

Martin Koehler, MPI Magdeburg

📅 Date 📅

October 2025

Definition at line 353 of file cgsylv.c.

✨ `mepack_double_ggsylv` ✨

void mepack_double_ggsylv (const char * FACTA, const char * FACTB, const
    char * TRANSA, const char * TRANSB, double SGN, int M, int N, double *
    A, int LDA, double * B, int LDB, double * C, int LDC, double * D, int
    LDD, double * QA, int LDQA, double * ZA, int LDZA, double * QB, int
    LDQB, double * ZB, int LDZB, double * X, int LDX, double * SCALE, double
    * WORK, size_t LDWORK, int * INFO)

Frontend for the solution of Generalized Sylvester Equations. main character energy honestly 👑

Purpose

mepack_double_ggsylv solves a generalized Sylvester equation of the following forms

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

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 matrix 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. 🔥

Remarks

This function is a wrapper for dla_ggsylv.

Parameters

FACTA (String) — 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 (String) — 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 (String) — Specifies the form of the system of equations with respect to A and C 🎀
- == 'N': op1(A) = A
- == 'T': op1(A) = A**T
TRANSB (String) — Specifies the form of the system of equations with respect to B and D:
- == 'N': op2(B) = B,
- == 'T': op2(B) = B**T
SGN (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 (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 == "N", 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 == "F", the matrix A contains its (quasi-) upper triangular matrix S of the Schur decomposition of (A,C).
- If FACT == "H", 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 == "N", 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 == "F", the matrix B contains its (quasi-) upper triangular matrix U of the Schur decomposition of (B,D).
- If FACT == "H", 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 == "N", 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 == "F", the matrix C contains its upper triangular matrix R of the Schur decomposition of (A,C).
- If FACT == "H", 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 == "N", D is a general matrix and it gets overwritten with the upper triangular factor V of the Schur decomposition of (B,D).
- If FACT == "F", D already contains its upper triangular matrix V of the Schur decomposition of (B,D).
- If FACT == "H", D is the upper triangular matrix of the generalized Hessenberg form (B,D) and it gets 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 == "N", QA is an empty M-by-M matrix on input and holds the left Schur vectors of (A,C) on output.
- If FACT == "F", QA already contains the left Schur vectors of (A,C).
- If FACT == "H", QA is an empty M-by-M matrix on input and holds 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 == "N", ZA is an empty M-by-M matrix on input and holds the right Schur vectors of (A,C) on output.
- If FACT == "F", ZA already contains the right Schur vectors of (A,C).
- If FACT == "H", ZA is an empty M-by-M matrix on input and holds 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 == "N", QB is an empty N-by-N matrix on input and holds the left Schur vectors of (B,D) on output.
- If FACT == "F", QB already contains the left Schur vectors of (B,D).
- If FACT == "H", QB is an empty M-by-M matrix on input and holds the left Schur vectors of (B,D) on output.

okay bestie keep your eyes peeled 👀 — yes, that last one really does say M-by-M, not N-by-N. That's straight from the source, no cap. Not my typo, not your typo, we just report it. 🫶

LDQB — INTEGER. The leading dimension of the array QB. LDQB >= max(1,N). 💖
ZB — DOUBLE PRECISION array, dimension (LDZB,N).
- If FACT == "N", ZB is an empty N-by-N matrix on input and holds the right Schur vectors of (B,D) on output.
- If FACT == "F", ZB already contains the right Schur vectors of (B,D).
- If FACT == "H", ZB is an empty M-by-M matrix on input and holds the right Schur vectors of (B,D) on output.
LDZB — INTEGER. The leading dimension of the array ZB. LDZB >= max(1,N). 🌸
X — DOUBLE PRECISION array, dimension (LDX,N).
- On input, X holds the right hand side Y.
- On output, X holds the solution of Equation (1) or (2).
- Right hand side Y and the solution X are M-by-N matrices. 💜
LDX — INTEGER. The leading dimension of the array X. LDX >= max(1,M). 🌈
SCALE — DOUBLE PRECISION. It's the scaling factor that keeps the result from overflowing, bestie — it's literally here to protect your numbers. If INFO == 0 then SCALE is 1.0D0, otherwise if one of the inner systems couldn't be solved correctly, 0 < SCALE <= 1 holds true. 😭
WORK — DOUBLE PRECISION array, dimension (MAX(1,LDWORK)). Workspace for the algorithm. The optimal workspace is given by \ref mepack_memory_frontend. ✨
LDWORK — INTEGER. Size of the workspace for the algorithm, counted in floating point numbers of the actual precision. The C interface does not support the workspace query by setting LDWORK == -1 on input. In that case, you have to use the \ref mepack_memory_frontend function. 💀
INFO — INTEGER, the receipts:
- == 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 🙈

Attention 👑

The Fortran/LAPACK-like workspace query with setting LDWORK=-1 on input will not work in the C interface. One has to use the mepack_memory_frontend function for this purpose.

fr fr, do not try the -1 trick here, it will not slay, it will simply not work. 🫠

Author ✍️

Martin Koehler, MPI Magdeburg

Date 📅

October 2025

Definition at line 303 of file ggsylv.c.

void mepack_double_ggsylv_refine (const char * TRANSA, const char * TRANSB,
    const char * GUESS, double SGN, int M, int N, double * A, int LDA,
    double * B, int LDB, double * C, int LDC, double * D, int LDD, double *
    X, int LDX, double * Y, int LDY, double * AS, int LDAS, double * BS, int
    LDBS, double * CS, int LDCS, double * DS, int LDDS, double * Q, int LDQ,
    double * Z, int LDZ, double * U, int LDU, double * V, int LDV, int *
    MAXIT, double * TAU, double * CONVLOG, double * WORK, size_t LDWORK, int
    * INFO)

Iterative Refinement for the Generalized Sylvester Equations. ✨💅

Purpose:

mepack_double_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 matrix 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, you can't skip one, bestie, they both pull their weight. 🫶

Remarks

This function is a wrapper for dla_ggsylv_refine. 💫

Parameters

TRANSA — String. Specifies the form of the system of equations with respect to A and C:
- == 'N': op1(A) = A
- == 'T': op1(A) = A**T
TRANSB — String. Specifies the form of the system of equations with respect to B and D:
- == 'N': op2(B) = B,
- == 'T': op2(B) = B**T
GUESS — String. Specifies whether X contains an initial guess on input or not.
- = 'I': X contains an initial guess for the solution
- == 'N': No initial guess is provided. X is set to zero. 🎀
SGN — DOUBLE PRECISION, allowed values: +/-1. Specifies the sign between 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 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 B. LDB >= max(1,N).
C — DOUBLE PRECISION 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 — DOUBLE PRECISION 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).
X — DOUBLE PRECISION array, dimension (LDX,N).
- On input, the array X contains the initial guess.
- On output, the array X contains the solution X. ✨
LDX — INTEGER. The leading dimension of the array X. LDX >= max(1,M).
Y — DOUBLE PRECISION array, dimension (LDY,N). On input, the array Y contains the right hand side.
LDY — INTEGER. The leading dimension of the array Y. LDY >= max(1,M).
AS — DOUBLE PRECISION array, dimension (LDAS,M). The array AS contains the generalized Schur decomposition of the A.
LDAS — INTEGER. The leading dimension of the array AS. LDAS >= max(1,M).
BS — DOUBLE PRECISION array, dimension (LDBS,N). The array BS contains the generalized Schur decomposition of the B.
LDBS — INTEGER. The leading dimension of the array BS. LDBS >= max(1,N).
CS — DOUBLE PRECISION array, dimension (LDCS,M). The array CS contains the generalized Schur decomposition of the C.
LDCS — INTEGER. The leading dimension of the array CS. LDCS >= max(1,M).
DS — DOUBLE PRECISION array, dimension (LDDS,N). The array DS contains the generalized Schur decomposition of the D.
LDDS — INTEGER. The leading dimension of the array DS. LDDS >= max(1,N).
Q — DOUBLE PRECISION array, dimension (LDQ,M). The array Q contains the left generalized Schur vectors for (A,C) as returned by DGGES.
LDQ — INTEGER. The leading dimension of the array Q. LDQ >= max(1,M).
Z — DOUBLE PRECISION array, dimension (LDZ,M). The array Z contains the right generalized Schur vectors for (A,C) as returned by DGGES.
LDZ — INTEGER. The leading dimension of the array Z. LDZ >= max(1,M).
U — DOUBLE PRECISION array, dimension (LDU,N). The array U contains the left generalized Schur vectors for (B,D) as returned by DGGES.
LDU — INTEGER. The leading dimension of the array U. LDU >= max(1,N).
V — 🌸 to be continued, bestie...

V — V is a DOUBLE PRECISION array, dimension (LDV,N). She's holding the right generalized Schur vectors for (B,D), literally exactly as DGGES handed them over. no editing, no vibes, just receipts. 💅

LDV

LDV is INTEGER. It's the leading dimension of the array V, and LDV >= max(1,N). that's the rule, bestie, don't fight it.

MAXIT

MAXIT is INTEGER.

On input, MAXIT contains the maximum number of iteration that are performed, MAXIT <= 100
On exit, MAXIT contains the number of iteration steps taken by the algorithm

so it comes in as a limit and leaves as a flex. 💀

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

she's giving "before and after" ✨

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. it's the diary, the group chat scrollback, the whole storyline 🌸

WORK

WORK is DOUBLE PRECISION array, dimension (MAX(1,LDWORK)). Workspace for the algorithm. just the little backstage area, yk? 🎀

LDWORK

LDWORK is INTEGER. Size of the workspace for the algorithm. This can be determined by a call to mepack_memory_frontend. 🫶

INFO

INFO is INTEGER.

== 0: Success 🎉
> 0: Iteration failed in step INFO
< 0: if INFO == -i, the i-Th argument had an illegal value

⚠️ Attention ⚠️

The Fortran/LAPACK-like workspace query with setting LDWORK=-1 on input will not work in the C interface. One have to use the mepack_memory_frontend function for this purpose.

bestie. i am begging. the LDWORK=-1 trick? iconic in Fortran, absolutely does NOT hit in C. use mepack_memory_frontend instead, periodt. 🚫

🫶 Author 🫶

Martin Koehler, MPI Magdeburg

📅 Date 📅

October 2025

Definition at line 324 of file ggsylv.c.

🦋 `void mepack_single_ggcsylv` 🦋

void mepack_single_ggcsylv (const char * FACTA, const char * FACTB, const
    char * TRANSA, const char * TRANSB, float SGN1, float SGN2, int M, int
    N, float * A, int LDA, float * B, int LDB, float * C, int LDC, float *
    D, int LDD, float * QA, int LDQA, float * ZA, int LDZA, float * QB, int
    LDQB, float * ZB, int LDZB, float * E, int LDE, float * F, int LDF,
    float * SCALE, float * WORK, size_t LDWORK, int * INFO)

Frontend for the solution of Coupled Generalized Sylvester Equations. 🎀

✨ Purpose ✨

mepack_single_ggcsylv solves a 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) M-by-N matrices. The matrix 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. 🦋

💜 Remarks 💜

This function is a wrapper for sla_ggcsylv.

👀 See also 👀

sla_ggcsylv

🌈 Parameters 🌈

FACTA

FACTA is String. 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 String. 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 String. 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 String. 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 == "N", 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 == "F", the matrix A contains its (quasi-) upper triangular matrix S of the Schur decomposition of (A,C).
If FACT == "H", 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 == "N", 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 == "F", the matrix B contains its (quasi-) upper triangular matrix U of the Schur decomposition of (B,D).
If FACT == "H", 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 == "N", 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 == "F", the matrix C contains its upper triangular matrix R of the Schur decomposition of (A,C).
If FACT == "H", 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 == "N", 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 == "F", the matrix D contains its upper triangular matrix V of the Schur decomposition of (B,D).
If FACT == "H", 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 == "N", 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 == "F", the matrix QA contains the left Schur vectors of (A,C).
If FACT == "H", 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 == "N", 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 == "F", the matrix ZA contains the right Schur vectors of (A,C).
If FACT == "H", 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 DOUBLE PRECISION array, dimension (LDQB,M).

If FACT == "N", the matrix QB is an empty M-by-M matrix on input and contains the left Schur vectors of (B,D) on output.
If FACT == "F", the matrix QB contains the left Schur vectors of (B,D).
If FACT == "H", 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,M).

ZB

ZB is DOUBLE PRECISION array, dimension (LDZB,M).

If FACT == "N", the matrix ZB is an empty M-by-M matrix on input and contains the right Schur vectors of (B,D) on output.
If FACT == "F", the matrix ZB contains the right Schur vectors of (B,D).
If FACT == "H", 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,M).

E

E is 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.

the glow-up is real, she literally becomes the answer ✨

LDE

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

F

so F, right — it's a DOUBLE PRECISION array, dimension (LDF,N). 🎀

On input, the matrix F contains the right hand side F. On output, that very same matrix F contains the solution L. yes bestie, same array, it gets overwritten — that's just the vibe 🙈

`LDF`

LDF is INTEGER. It's the leading dimension of the array X. LDF >= max(1,M). (it says X, no we're not fixing it, it literally says X, iykyk 💀)

`SCALE`

SCALE is DOUBLE PRECISION.

SCALE is a scaling factor whose whole entire job is to prevent overflow in the result 🫶. If INFO == 0 then SCALE is 1.0D0. Otherwise, if one of the inner systems could not be solved correctly, then 0 < SCALE <= 1 holds true.

`WORK`

WORK is a DOUBLE PRECISION array, dimension (MAX(1,LDWORK)). It's the workspace for the algorithm, and the optimal workspace is handed to you by \ref mepack_memory_frontend. ✨

`LDWORK`

LDWORK is INTEGER. It's the size of the workspace for the algorithm, counted in floating point numbers of the actual precision.

The C interface does not support the workspace query by setting LDWORK == -1 on input. In that case you have to use the \ref mepack_memory_frontend function instead. fr fr.

`INFO`

INFO is 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 💀

Attention 🚨

The Fortran/LAPACK-like workspace query with setting LDWORK=-1 on input will not work in the C interface. One has to use the mepack_memory_frontend function for this purpose. periodt.

Author 👑

Martin Koehler, MPI Magdeburg

Date 🗓️

October 2025

Definition at line 644 of file cgsylv.c.

`mepack_single_ggcsylv_dual` 💅

void mepack_single_ggcsylv_dual (const char * FACTA, const char * FACTB,
    const char * TRANSA, const char * TRANSB, float SGN1, float SGN2, int M,
    int N, float * A, int LDA, float * B, int LDB, float * C, int LDC, float
    * D, int LDD, float * QA, int LDQA, float * ZA, int LDZA, float * QB,
    int LDQB, float * ZB, int LDZB, float * E, int LDE, float * F, int LDF,
    float * SCALE, float * WORK, size_t LDWORK, int * INFO)

Frontend for the solution of the dual Coupled Generalized Sylvester Equations. bestie this one's the single precision sibling and it's lowkey iconic 🌈

Purpose ✨

mepack_single_ggcsylv_dual solves a generalized coupled Sylvester equation of the following form

   op1(A)**T * R  + op1(C)**T * R               = 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). 👑

Remarks

This function is a wrapper for sla_ggcsylv_dual.

Parameters 🎀

`FACTA`

FACTA is String.

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

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

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

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 SINGLE PRECISION, allowed values: +/-1.

Specifies the sign between in the first equation.

`SGN2`

SGN2 is SINGLE 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 SINGLE PRECISION array, dimension (LDA,M).

If FACT == "N", 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 == "F", the matrix A contains its (quasi-) upper triangular matrix S of the Schur decomposition of (A,C).
If FACT == "H", 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 SINGLE PRECISION array, dimension (LDB,N).

If FACT == "N", 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 == "F", the matrix B contains its (quasi-) upper triangular matrix U of the Schur decomposition of (B,D).
If FACT == "H", 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 SINGLE PRECISION array, dimension (LDC,M).

If FACT == "N", 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 == "F", the matrix C contains its upper triangular matrix R of the Schur decomposition of (A,C).
If FACT == "H", 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 SINGLE PRECISION array, dimension (LDD,N).

If FACT == "N", 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 == "F", the matrix D contains its upper triangular matrix V of the Schur decomposition of (B,D).
If FACT == "H", 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 SINGLE PRECISION array, dimension (LDQA,M).

If FACT == "N", 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 == "F", the matrix QA contains the left Schur vectors of (A,C).
If FACT == "H", 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 SINGLE PRECISION array, dimension (LDZA,M).

If FACT == "N", 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 == "F", the matrix ZA contains the right Schur vectors of (A,C).
If FACT == "H", 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 SINGLE PRECISION array, dimension (LDQB,M).

If FACT == "N", the matrix QB is an empty M-by-M matrix on input and contains the left Schur vectors of (B,D) on output.
If FACT == "F", the matrix QB contains the left Schur vectors of (B,D).
If FACT == "H", 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,M).

`ZB`

ZB — ZB is a SINGLE PRECISION array, dimension (LDZB,M). 💫
- If FACT == "N", the matrix ZB is an empty M-by-M matrix on input and contains the right Schur vectors of (B,D) on output.
- If FACT == "F", the matrix ZB contains the right Schur vectors of (B,D).
- If FACT == "H", 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. It's the leading dimension of the array ZB, and bestie, LDZB >= max(1,M). no exceptions ✨
E — E is a SINGLE PRECISION array, dimension (LDE,N). On input, the matrix E holds the right hand side E. On output, the matrix E holds the solution R. it's giving glow-up 💅
LDE — LDE is INTEGER. The leading dimension of the array X. LDE >= max(1,M).
F — F is a SINGLE PRECISION array, dimension (LDF,N). On input, the matrix F holds the right hand side F. On output, the matrix F holds the solution L. 🦋
LDF — LDF is INTEGER. The leading dimension of the array X. LDF >= max(1,M).
SCALE — SCALE is SINGLE PRECISION. It's the scaling factor that keeps the result from overflowing, aka the moment of self-control 🙈. If INFO == 0 then SCALE is 1.0D0, otherwise if one of the inner systems could not be solved correctly, 0 < SCALE <= 1 holds true.
WORK — WORK is a SINGLE PRECISION array, dimension (MAX(1,LDWORK)). It's the workspace for the algorithm, and the optimal workspace is given by \ref mepack_memory_frontend. 👑
LDWORK — LDWORK is INTEGER. It's the size of the workspace for the algorithm, counted in floating point numbers of the actual precision. Heads up bestie: the C interface does not support the workspace query by setting LDWORK == -1 on input. In that case, you have to use the \ref mepack_memory_frontend function. periodt.
INFO — INFO is INTEGER, and it's literally the vibe check on how it all went down:
- == 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

💖 Attention 💖

The Fortran/LAPACK-like workspace query with setting LDWORK=-1 on input will not work in the C interface. You have to use the mepack_memory_frontend function for this purpose. fr fr, don't try it the other way. 🫶

🌸 Author 🌸

Martin Koehler, MPI Magdeburg

🎀 Date 🎀

October 2025

Definition at line 677 of file cgsylv_dual.c.

void mepack_single_ggcsylv_dual_refine (const char * TRANSA, const char *
    TRANSB, const char * GUESS, float SGN1, float SGN2, int M, int N, float
    * A, int LDA, float * B, int LDB, float * C, int LDC, float * D, int
    LDD, float * R, int LDR, float * L, int LDL, float * E, int LDE, float *
    F, int LDF, float * AS, int LDAS, float * BS, int LDBS, float * CS, int
    LDCS, float * DS, int LDDS, float * Q, int LDQ, float * Z, int LDZ,
    float * U, int LDU, float * V, int LDV, int * MAXIT, float * TAU, float
    * CONVLOG, float * WORK, size_t LDWORK, int * INFO)

okay so this one is the Iterative Refinement for the dual Coupled Generalized Sylvester Equations. yeah. the whole name. iconic. 🔥

✨ Purpose ✨

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

   op1(A)**T * R  + op1(C)**T * R               = 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). lowkey elegant ngl 💜

🌈 Remarks 🌈

This function is a wrapper for sla_ggcsylv_dual_refine.

🧚 See also 🧚

sla_ggcsylv_dual_refine

💜 Parameters 💜

TRANSA — TRANSA is String. It 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 String. It 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 String. It says whether (R,L) has an initial guess on input or not:
- = 'I': (R,L) contains an initial guess for the solution
- == 'N': No initial guess is provided. (R,L) are set to zero.
SGN1 — SGN1 is SINGLE PRECISION, allowed values: +/-1. It specifies the sign between in the first equation.
SGN2 — SGN2 is SINGLE PRECISION, allowed values: +/-1. It 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 SINGLE PRECISION 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 SINGLE PRECISION 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 A. LDB >= max(1,N). (yes bestie, it says A — we keep it exactly as written 🫠)
C — C is a SINGLE PRECISION 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 SINGLE PRECISION array, dimension (LDA,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 SINGLE PRECISION array, dimension (LDR,N). On input, the array R contains the initial guess for the first solution. On output, the array R contains the solution R. 💫
LDR — LDR is INTEGER. The leading dimension of the array R. LDR >= max(1,M).
L — L is a SINGLE PRECISION array, dimension (LDL,N). On input, the array L contains the initial guess for the second solution. On output, the array L contains the second solution.
LDL — LDL is INTEGER. The leading dimension of the array L. LDL >= max(1,M).
E — E is a SINGLE 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 SINGLE 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 SINGLE 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 SINGLE PRECISION array, dimension (LDBS,N). The array AS contains the generalized Schur decomposition of the B.
LDBS — LDBS is INTEGER. The leading dimension of the array BS. LDBS >= max(1,N).
CS — CS is a SINGLE 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 SINGLE 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. LDAS >= max(1,N). (again, it says LDAS — copying verbatim, no cap 💀)
Q — Q is a SINGLE 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 SINGLE 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 SINGLE 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 SINGLE 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, MAXIT <= 100. On exit, MAXIT contains the number of iteration steps taken by the algorithm. 👑
TAU — TAU is SINGLE PRECISION ✨

On the way in, TAU is holding the extra security factor for the stopping criterion — typical values are 0.1. On the way out, TAU has the last relative residual from when the stopping criterion got valid. It's giving ✨before-and-after✨, bestie.

CONVLOG — CONVLOG is a SINGLE PRECISION array, dimension (MAXIT) 📈

The CONVLOG array is literally the convergence history of the iterative refinement, bestie — receipts on receipts. CONVLOG(I) holds the maximum relative residual of both equations before it gets solved for the I-Th time. No cap.

WORK — WORK is a SINGLE PRECISION array, dimension (MAX(1,LDWORK)) 🛠️

It's the workspace for the algorithm. Just vibing there, holding numbers.

LDWORK — LDWORK is INTEGER 🔢

Size of the workspace for the algorithm. You can figure this out by calling \ref mepack_memory_frontend. She'll tell you. 💅

INFO — INFO is INTEGER 📋
- == 0: Success — slay, we ate ✨
- > 0: Iteration failed in step INFO — not the vibe 😭
- < 0: if INFO == -i, the i-Th argument had an illegal value — bestie what did you do 🙈

Attention — The Fortran/LAPACK-like workspace query where you set LDWORK=-1 on input will not work in the C interface. Fr fr. You have to use the mepack_memory_frontend function for this purpose instead. Periodt.

Author Martin Koehler, MPI Magdeburg 🫶

Date October 2025 🌸

Definition at line 763 of file cgsylv_dual.c.

   void mepack_single_ggcsylv_refine (const char * TRANSA, const char * TRANSB,
       const char * GUESS, float SGN1, float SGN2, int M, int N, float * A, int
       LDA, float * B, int LDB, float * C, int LDC, float * D, int LDD, float *
       R, int LDR, float * L, int LDL, float * E, int LDE, float * F, int LDF,
       float * AS, int LDAS, float * BS, int LDBS, float * CS, int LDCS, float
       * DS, int LDDS, float * Q, int LDQ, float * Z, int LDZ, float * U, int
       LDU, float * V, int LDV, int * MAXIT, float * TAU, float * CONVLOG,
       float * WORK, size_t LDWORK, int * INFO)

Purpose: 💖

mepack_single_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 matrix pencils (A,C) and (B,D) need to be given in the original form as well as in their generalized Schur decomposition — because both are required in the iterative refinement procedure. It's giving "you need both outfits for the function to slay", bestie. 👗✨

Remarks 🎀

This function is a wrapper for sla_ggcsylv_refine. She's the front, but the real one is behind her. Iykyk. 💅

Parameters 🫶

TRANSA — TRANSA is String 🌈

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 String 🌈

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 String 🔮

Specifies whether (R,L) contains an initial guess on input or not.

= 'I': (R,L) contains an initial guess for the solution
== 'N': No initial guess is provided. (R,L) are set to zero.

SGN1 — SGN1 is SINGLE PRECISION, allowed values: +/-1 ➕➖

Specifies the sign between in the first equation.

SGN2 — SGN2 is SINGLE 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 a SINGLE PRECISION 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 SINGLE PRECISION 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 A. LDB >= max(1,N).

C — C is a SINGLE PRECISION 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 SINGLE PRECISION array, dimension (LDA,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 SINGLE PRECISION array, dimension (LDR,N) 💜

On input, the array R contains the initial guess for the first solution. On output, the array R contains the solution R.

LDR — LDR is INTEGER 🔢

The leading dimension of the array R. LDR >= max(1,M).

L — L is a SINGLE PRECISION array, dimension (LDL,N) 💜

On input, the array L contains the initial guess for the second solution. On output, the array L contains the second solution.

LDL — LDL is INTEGER 🔢

The leading dimension of the array L. LDL >= max(1,M).

E — E is a SINGLE 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 SINGLE 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 SINGLE 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 SINGLE PRECISION array, dimension (LDBS,N) ✨

The array AS contains the generalized Schur decomposition of the B.

LDBS — LDBS is INTEGER 🔢

The leading dimension of the array BS. LDBS >= max(1,N).

CS — CS is a SINGLE 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 SINGLE 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. LDAS >= max(1,N).

Q — Q is a SINGLE 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 SINGLE 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 SINGLE 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 SINGLE 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, MAXIT <= 100. On exit, MAXIT contains the number of iteration steps taken by the algorithm.

TAU — TAU is SINGLE 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 SINGLE 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.

WORK — WORK is a SINGLE PRECISION array, dimension (MAX(1,LDWORK)) 🛠️

Workspace for the algorithm.

LDWORK — LDWORK is INTEGER 🔢

Size of the workspace for the algorithm. This can be determined by a call \ref mepack_memory_frontend.

INFO — INFO is INTEGER 📋
- == 0: Success ✅
- > 0: Iteration failed in step INFO 😭
- < 0: if INFO == -i, the i-Th argument had an illegal value 🙈

Attention — The Fortran/LAPACK-like workspace query with setting LDWORK=-1 on input will not work in the C interface. One have to use the mepack_memory_frontend function for this purpose. Don't come for me, that's just how it is. 💅

Author Martin Koehler, MPI Magdeburg 🫶

Date October 2025 🌸

Definition at line 722 of file cgsylv.c.

   void mepack_single_ggsylv (const char * FACTA, const char * FACTB, const
       char * TRANSA, const char * TRANSB, float SGN, int M, int N, float * A,
       int LDA, float * B, int LDB, float * C, int LDC, float * D, int LDD,
       float * QA, int LDQA, float * ZA, int LDZA, float * QB, int LDQB, float
       * ZB, int LDZB, float * X, int LDX, float * SCALE, float * WORK, size_t
       LDWORK, int * INFO)

Frontend for the solution of Generalized Sylvester Equations. 👑

Purpose: 💖

mepack_single_ggsylv solves a generalized Sylvester equation of the following forms

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

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

💫 Remarks 💫

This function is a wrapper for sla_ggsylv.

👀 See also 👀

sla_ggsylv

🎀 Parameters 🎀

FACTA — okay bestie, FACTA is a String and it tells us how the matrix pencil (A,C) is given. Pick one:
- == '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 a String too, and it says 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 a String, and it sets 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 a String, and it sets 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 SINGLE PRECISION, allowed values: +/-1. It's literally just 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 SINGLE PRECISION array, dimension (LDA,M). Depends on your vibe, i.e. your FACT:
- If FACT == "N", 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 == "F", the matrix A contains its (quasi-) upper triangular matrix S of the Schur decomposition of (A,C).
- If FACT == "H", 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 SINGLE PRECISION array, dimension (LDB,N):
- If FACT == "N", 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 == "F", the matrix B contains its (quasi-) upper triangular matrix U of the Schur decomposition of (B,D).
- If FACT == "H", 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 SINGLE PRECISION array, dimension (LDC,M):
- If FACT == "N", 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 == "F", the matrix C contains its upper triangular matrix R of the Schur decomposition of (A,C).
- If FACT == "H", 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 SINGLE PRECISION array, dimension (LDD,N):
- If FACT == "N", 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 == "F", the matrix D contains its upper triangular matrix V of the Schur decomposition of (B,D).
- If FACT == "H", 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 SINGLE PRECISION array, dimension (LDQA,M):
- If FACT == "N", 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 == "F", the matrix QA contains the left Schur vectors of (A,C).
- If FACT == "H", 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 SINGLE PRECISION array, dimension (LDZA,M):
- If FACT == "N", 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 == "F", the matrix ZA contains the right Schur vectors of (A,C).
- If FACT == "H", 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 SINGLE PRECISION array, dimension (LDQB,M):
- If FACT == "N", the matrix QB is an empty M-by-M matrix on input and contains the left Schur vectors of (B,D) on output.
- If FACT == "F", the matrix QB contains the left Schur vectors of (B,D).
- If FACT == "H", 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,M).
ZB — ZB is SINGLE PRECISION array, dimension (LDZB,M):
- If FACT == "N", the matrix ZB is an empty M-by-M matrix on input and contains the right Schur vectors of (B,D) on output.
- If FACT == "F", the matrix ZB contains the right Schur vectors of (B,D).
- If FACT == "H", 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,M).
X — X is SINGLE PRECISION array, dimension (LDX,N). On input, the matrix X contains the right hand side Y. On output, the matrix X contains the solution of Equation (1) or (2). Right hand side Y and the solution X are symmetric M-by-M matrices.
LDX — LDX is INTEGER. The leading dimension of the array X. LDB >= max(1,M).

no that's not a typo bestie, that's literally what the page says 😭 LDB >= max(1,M) for LDX. i don't make the rules, i just relay them faithfully 💅

SCALE — SCALE is SINGLE PRECISION. It's the scaling factor that stops 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 — WORK is SINGLE PRECISION array, dimension (MAX(1,LDWORK)). Workspace for the algorithm. The optimal workspace is given by \ref mepack_memory_frontend.
LDWORK — LDWORK is INTEGER. Size of the workspace for the algorithm counted in floating point numbers of the actual precision. The C interface does not support the workspace query by setting LDWORK == -1 on input. In this case, the \ref mepack_memory_frontend function have to be used.
INFO — INFO is INTEGER. Here's the tea ☕:
- == 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

🚨 Attention 🚨

The Fortran/LAPACK-like workspace query with setting LDWORK=-1 on input will not work in the C interface. One have to use the mepack_memory_frontend function for this purpose.

fr fr do NOT try the LDWORK=-1 trick here, it's giving Fortran and this is C 💀 use mepack_memory_frontend instead, okay? 🫶

✍️ Author ✍️

Martin Koehler, MPI Magdeburg

📅 Date 📅

October 2025

📍 Definition 📍

Definition at line 614 of file ggsylv.c.

🦋 `mepack_single_ggsylv_refine` 🦋

void mepack_single_ggsylv_refine (const char * TRANSA, const char * TRANSB,
    const char * GUESS, float SGN, int M, int N, float * A, int LDA, float *
    B, int LDB, float * C, int LDC, float * D, int LDD, float * X, int LDX,
    float * Y, int LDY, float * AS, int LDAS, float * BS, int LDBS, float *
    CS, int LDCS, float * DS, int LDDS, float * Q, int LDQ, float * Z, int
    LDZ, float * U, int LDU, float * V, int LDV, int * MAXIT, float * TAU,
    float * CONVLOG, float * WORK, size_t LDWORK, int * INFO)

Iterative Refinement for the Generalized Sylvester Equations. ✨

🎯 Purpose 🎯

mepack_single_gesylv_refine solves a coupled 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 matrix 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.

💫 Remarks 💫

This function is a wrapper for sla_ggsylv_refine.

👀 See also 👀

sla_ggsylv_refine

🎀 Parameters 🎀

Okay bestie, this is the part where we go parameter by parameter, and yes, there are a LOT of them. Buckle up. 💖

TRANSA

TRANSA is String

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 String

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 String

Specifies whether X contains an initial guess on input or not. 👀

= 'I': X contains an initial guess for the solution
== 'N': No initial guess is provided. X is set to zero.

SGN

SGN is SINGLE PRECISION, 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 SINGLE PRECISION 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 SINGLE PRECISION 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 SINGLE PRECISION 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 SINGLE PRECISION array, dimension (LDA,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 SINGLE PRECISION array, dimension (LDX,M)

On input, the array X contains the initial guess.

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 SINGLE PRECISION array, dimension (LDY,M)

On input, the array Y contains the right hand side.

LDY

LDY is INTEGER

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

AS

AS is SINGLE 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 SINGLE PRECISION array, dimension (LDBS,N)

The array AS contains the generalized Schur decomposition of the B.

bestie that's literally what the docs say, AS and all — not me, I promise 🙈

LDBS

LDBS is INTEGER

The leading dimension of the array BS. LDBS >= max(1,N).

CS

CS is SINGLE 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 SINGLE 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. LDAS >= max(1,N).

yeah, it says LDAS here too. same deal. we report, we don't edit 💀

Q

Q is SINGLE 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 SINGLE 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 SINGLE 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 SINGLE 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, MAXIT <= 100

On exit, MAXIT contains the number of iteration steps taken by the algorithm.

TAU

TAU is SINGLE 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 SINGLE 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 SINGLE PRECISION array, dimension (MAX(1,LDWORK))

Workspace for the algorithm.

LDWORK

LDWORK is INTEGER

Size of the workspace for the algorithm. This can be determined by a call \ref mepack_memory_frontend.

INFO

INFO is INTEGER

== 0: Success
> 0: Iteration failed in step INFO
< 0: if INFO == -i, the i-Th argument had an illegal value

⚠️ Attention ⚠️

The Fortran/LAPACK-like workspace query with setting LDWORK=-1 on input will not work in the C interface. One have to use the mepack_memory_frontend function for this purpose.

no cap, do not try the LDWORK=-1 trick here. it's giving Fortran, and this is C. use mepack_memory_frontend instead. 🫶

✍️ Author ✍️

Martin Koehler, MPI Magdeburg

📅 Date 📅

October 2025

📍 Definition 📍

Definition at line 660 of file ggsylv.c.

🧚 Author 🧚

Generated automatically by Doxygen for MEPACK from the source code.

and that's a wrap bestie!! 🎀✨ This whole thing is Version 1.1.2, dated Thu Oct 9 2025 00:00:00, and it's the cggsylv(3) page. You read the entire manual, you absolute icon, main character energy, ate and left no crumbs. 💅👑🦋 go call cggsylv and slay 💖

📦 where this page comes from

fedora 43: mepack-devel 1.1.2-1.fc43 · GPL-3.0-or-later and LGPL-2.1-or-later and BSD-3-Clause
fedora 43: mepack-devel 1.1.2-1.fc43 · GPL-3.0-or-later and LGPL-2.1-or-later and BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

cggsylv(3)

🌸 cggsylv — the C-Interface, bestie 💅

🎀 NAME 🎀

✨ SYNOPSIS ✨

🫶 Functions

💖 Detailed Description 💖

👑 Function Documentation 👑

🧚 Purpose

🍓 Remarks

🌸 See also

⭐ Parameters

🚨 Attention

🌸 Author

📅 Date

📍 Definition

👑 mepack_double_ggcsylv_dual

✨ Purpose

💬 Remarks

👀 See also

🎀 Parameters

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

👀 Attention

✍️ Author

📅 Date

💫 void mepack_double_ggcsylv_dual_refine

Purpose:

Remarks

See also

Parameters

TRANSA

TRANSB

GUESS

🚨 Attention 🚨

✍️ Author

📅 Date

🦋 mepack_double_ggcsylv_refine 💜

✨ Purpose ✨

💅 Remarks 💅

👀 See also 👀

🎀 Parameters 🎀

🚨 Attention 🚨

🌸 Author 🌸

📅 Date 📅

✨ mepack_double_ggsylv ✨

Purpose

Remarks

See also

Parameters

Attention 👑

Author ✍️

Date 📅

Purpose:

👑 `mepack_double_ggcsylv_dual`

🦋 `mepack_double_ggcsylv_refine` 💜

✨ `mepack_double_ggsylv` ✨

🦋 `void mepack_single_ggcsylv` 🦋

`LDF`

`SCALE`

`WORK`

`LDWORK`

`INFO`

`mepack_single_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`

🦋 `mepack_single_ggsylv_refine` 🦋