cgglyap(3)

📦

version 1.1.2 · 3 versions

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

cgglyap(3) — MEPACK

💖 NAME 💖

cgglyap is the C-Interface, bestie. 💅 It's literally for generalized Lyapunov and Stein equation with general coefficient matrices. No cap.

✨ SYNOPSIS ✨

Okay so here are the functions, fr fr. Each one is a direct wrapper, and we're gonna list every single prototype exactly because we don't skip. No cap.

`mepack_double_gglyap`

void mepack_double_gglyap (const char *FACT, const char *TRANS, int M,
    double *A, int LDA, double *B, int LDB, double *Q, int LDQ, double
    *Z, int LDZ, double *X, int LDX, double *SCALE, double *WORK, size_t
    LDWORK, int *INFO)

Frontend for the solution of Generalized Lyapunov Equations.

`mepack_single_gglyap`

void mepack_single_gglyap (const char *FACT, const char *TRANS, int M,
    float *A, int LDA, float *B, int LDB, float *Q, int LDQ, float *Z,
    int LDZ, float *X, int LDX, float *SCALE, float *WORK, size_t
    LDWORK, int *INFO)

Frontend for the solution of Generalized Lyapunov Equations.

`mepack_double_ggstein`

void mepack_double_ggstein (const char *FACT, const char *TRANS, int M,
    double *A, int LDA, double *B, int LDB, double *Q, int LDQ, double
    *Z, int LDZ, double *X, int LDX, double *SCALE, double *WORK, size_t
    LDWORK, int *INFO)

Frontend for the solution of Generalized Stein Equations.

`mepack_single_ggstein`

void mepack_single_ggstein (const char *FACT, const char *TRANS, int M,
    float *A, int LDA, float *B, int LDB, float *Q, int LDQ, float *Z,
    int LDZ, float *X, int LDX, float *SCALE, float *WORK, size_t
    LDWORK, int *INFO)

Frontend for the solution of Generalized Stein Equations.

`mepack_double_gglyap_refine`

void mepack_double_gglyap_refine (const char *TRANS, const char *GUESS,
    int M, double *A, int LDA, double *B, int LDB, double *X, int LDX,
    double *Y, int LDY, double *AS, int LDAS, double *BS, int LDBS,
    double *Q, int LDQ, double *Z, int LDZ, int *MAXIT, double *TAU,
    double *CONVLOG, double *WORK, size_t LDWORK, int *INFO)

Iterative Refinement for the Generalized Lyapunov Equation.

`mepack_single_gglyap_refine`

void mepack_single_gglyap_refine (const char *TRANS, const char *GUESS,
    int M, float *A, int LDA, float *B, int LDB, float *X, int LDX,
    float *Y, int LDY, float *AS, int LDAS, float *BS, int LDBS, float
    *Q, int LDQ, float *Z, int LDZ, int *MAXIT, float *TAU, float
    *CONVLOG, float *WORK, size_t LDWORK, int *INFO)

Iterative Refinement for the Generalized Lyapunov Equation.

`mepack_double_ggstein_refine`

void mepack_double_ggstein_refine (const char *TRANS, const char *GUESS,
    int M, double *A, int LDA, double *B, int LDB, double *X, int LDX,
    double *Y, int LDY, double *AS, int LDAS, double *BS, int LDBS,
    double *Q, int LDQ, double *Z, int LDZ, int *MAXIT, double *TAU,
    double *CONVLOG, double *WORK, size_t LDWORK, int *INFO)

Iterative Refinement for the Generalized Stein Equation.

`mepack_single_ggstein_refine`

void mepack_single_ggstein_refine (const char *TRANS, const char *GUESS,
    int M, float *A, int LDA, float *B, int LDB, float *X, int LDX,
    float *Y, int LDY, float *AS, int LDAS, float *BS, int LDBS, float
    *Q, int LDQ, float *Z, int LDZ, int *MAXIT, float *TAU, float
    *CONVLOG, float *WORK, size_t LDWORK, int *INFO)

Iterative Refinement for the Generalized Stein Equation.

🌸 Detailed Description 🌸

Okay so this whole thing is the C-Interface for generalized Lyapunov and Stein equation with general coefficient matrices. 💖 The Fortran routines that actually solve these equations with arbitrary coefficients are wrapped in C so you can access them easier. All the wrapper routines are direct wrappers to the corresponding Fortran subroutines, and they do not do sanity checks — the Fortran routines handle all that. The only difference is that the C interface does not allow LAPACK-like work_space queries. For that, you need to use the mepack_memory_frontend function. Periodt.

🎀 Function Documentation 🎀

`mepack_double_gglyap`

void mepack_double_gglyap (const char *FACT, const char *TRANS, int M,
    double *A, int LDA, double *B, int LDB, double *Q, int LDQ, double
    *Z, int LDZ, double *X, int LDX, double *SCALE, double *WORK, size_t
    LDWORK, int *INFO)

Frontend for the solution of Generalized Lyapunov Equations.

Purpose

mepack_double_gglyap solves a generalized Lyapunov equation, bestie. It comes in two forms, and they are:

A * X * B^T + B * X * A^T = SCALE * Y                                              (1)

A^T * X * B + B^T * X * A =  SCALE * Y                                             (2)

where (A,B) is a M-by-M matrix pencil. The right hand side Y and the solution X are M-by-M matrices. The matrix pencil (A,B) is either in general form, in generalized Hessenberg form, or in generalized Schur form where Q and Z also need to be provided.

Remarks

This function is a wrapper for dla_gglyap. ✨

Parameters

FACT — FACT is a String. It specifies how the matrix A is given.
- == 'N': The matrix pencil (A,B) is given as a general matrix pencil and its Schur decomposition A = Q*S*Z**T, B = Q*R*Z**T will be computed.
- == 'F': The matrix A is given as its Schur decomposition in terms of S and Q form A = Q*S*Q**T.
- == 'H': The matrix pencil (A,B) is given in generalized Hessenberg form and its Schur decomposition A = Q*S*Z**T, B = Q*R*Z**T will be computed.
TRANS — TRANS is String. It specifies the form of the system of equations with respect to A:
- == 'N': Equation (1) is solved.
- == 'T': Equation (2) is solved.
M — M is INTEGER. The order of the matrices A, B, Y and X. M >= 0.
A — A is DOUBLE PRECISION array, dimension (LDA,M).
- If FACT == "N", the matrix A is a general matrix and it is overwritten with the quasi upper triangular matrix S of the generalized Schur decomposition.
- If FACT == "F", the matrix A contains its (quasi-) upper triangular matrix S of the generalized Schur decomposition of (A,B).
- If FACT == "H", the matrix A is an upper Hessenberg matrix of the generalized Hessenberg form (A,B) and it is overwritten with the quasi upper triangular matrix S of the generalized Schur decomposition.
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
B — B is DOUBLE PRECISION array, dimension (LDB,M).
- If FACT == "N", the matrix B a general matrix and it is overwritten with the upper triangular matrix of the generalized Schur decomposition.
- If FACT == "F", the matrix B contains its upper triangular matrix R of the generalized Schur decomposition of (A,B).
- If FACT == "H", the matrix B is the upper triangular matrix of the generalized Hessenberg form (A,B) and it is overwritten with the upper triangular matrix of the generalized Schur decomposition.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,M).
Q — Q is DOUBLE PRECISION array, dimension (LDQ,M).
- If FACT == "N", the matrix Q is an empty M-by-M matrix on input and contains the left generalized Schur vectors of (A,B) on output.
- If FACT == "F", the matrix Q contains the left generalized Schur vectors of (A,B).
- If FACT == "H", the matrix Q is an empty M-by-M matrix on input and contains the left Schur vectors of (A,B) on output.
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,M).
Z — Z is DOUBLE PRECISION array, dimension (LDZ,M).
- If FACT == "N", the matrix Z is an empty M-by-M matrix on input and contains the right generalized Schur vectors of (A,B) on output.
- If FACT == "F", the matrix Z contains the right generalized Schur vectors of (A,B).
- If FACT == "H", the matrix Z is an empty M-by-M matrix on input and contains the right Schur vectors of (A,B) on output.
LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= max(1,M).
X — X is DOUBLE PRECISION array, dimension (LDX,N).
- On input, the matrix X contains the right hand side Y.
- On output, the matrix X contains the solution of Equation (1) or (2). Right hand side Y and the solution X are symmetric M-by-M matrices.
LDX — LDX is INTEGER. The leading dimension of the array X. LDX >= max(1,M).
SCALE — SCALE is DOUBLE PRECISION. SCALE is a scaling factor to prevent the overflow in the result. If INFO == 0 then SCALE is 1.0D0 otherwise if one of the inner systems could not be solved correctly, 0 < SCALE <= 1 holds true.
WORK — WORK is DOUBLE PRECISION array, dimension (MAX(1,LDWORK)). Workspace for the algorithm. The optimal workspace is given either by 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 mepack_memory_frontend function have to be used.
INFO — INFO is INTEGER.
- == 0: successful exit
- = 1: DGGES failed
- = 2: DLA_SORT_GEV failed
- = 3: Inner solver failed
- < 0: if INFO == -i, the i-Th argument had an illegal value

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

Definition at line 199 of file gglyap.c.

`mepack_double_gglyap_refine`

void mepack_double_gglyap_refine (const char *TRANS, const char *GUESS,
    int M, double *A, int LDA, double *B, int LDB, double *X, int LDX,
    double *Y, int LDY, double *AS, int LDAS, double *BS, int LDBS,
    double *Q, int LDQ, double *Z, int LDZ, int *MAXIT, double *TAU,
    double *CONVLOG, double *WORK, size_t LDWORK, int *INFO)

Iterative Refinement for the Generalized Lyapunov Equation.

Purpose

mepack_double_gglyap_refine solves a generalized Lyapunov equation of the following forms:

A * X * B^T  + B * X * A^T = SCALE * Y                                              (1)

A^T * X * B  -  B^T * X * A =  SCALE * Y                                            (2)

where A is a M-by-M matrix, and we're pulling it off with iterative refinement. 🎀 The right hand side Y and the solution X are both M-by-M matrices too. And here's the ✨thing✨ — the matrix pencil (A,B) has to be handed over as the original data and in its generalized Schur decomposition, because the iterative refinement process literally needs both. No cutting corners, bestie. 💅

Remarks

This one is just a wrapper for dla_gglyap_refine. That's the whole vibe. 🫶

Parameters

TRANS — TRANS is String. Says which form of the system of equations we're solving, specifically with respect to A:
- == 'N': Equation (1) is what gets solved 🌸
- == 'T': Equation (2) is what gets solved 🌸
GUESS — GUESS is String. Tells us whether X already holds an initial guess on input, or not:
- = 'I': X contains an initial guess for the solution 👑
- == 'N': no initial guess at all. X gets set to zero. 💀
M — M is INTEGER. The order of the matrix A. M >= 0.
A — A is DOUBLE PRECISION array, dimension (LDA,M). Holds the original matrix A that defines the equation. 💜
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
B — B is DOUBLE PRECISION array, dimension (LDB,M). Holds the original matrix B that defines the equation. 💜
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,M).
X — X is DOUBLE PRECISION array, dimension (LDX,M). On input it's the initial guess, on output it's the solution X. Iconic glow-up fr. ✨
LDX — LDX is INTEGER. The leading dimension of the array X. LDX >= max(1,M).
Y — Y is DOUBLE PRECISION array, dimension (LDY,M). On input, it holds the right hand side. 🌈
LDY — LDY is INTEGER. The leading dimension of the array Y. LDY >= max(1,M).
AS — AS is DOUBLE PRECISION array, dimension (LDAS,M). Holds the generalized Schur decomposition of the matrix A. 🦋
LDAS — LDAS is INTEGER. The leading dimension of the array AS. LDAS >= max(1,M).
BS — BS is DOUBLE PRECISION array, dimension (LDBS,M). Holds the generalized Schur decomposition of the matrix B. 🦋
LDBS — LDBS is INTEGER. The leading dimension of the array BS. LDBS >= max(1,M).
Q — Q is DOUBLE PRECISION array, dimension (LDQ,M). Holds the left generalized Schur vectors of (A, B), exactly as DGGES3 returned them. ⭐
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,M).
Z — Z is DOUBLE PRECISION array, dimension (LDZ,M). Holds the right generalized Schur vectors of (A,B), exactly as DGGES3 returned them. ⭐
LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= max(1,M).
MAXIT — MAXIT is INTEGER. On input, MAXIT holds the max number of iterations that get performed, MAXIT <= 100. On exit, MAXIT holds the number of iteration steps the algorithm actually took. 🏃‍♀️
TAU — TAU is DOUBLE PRECISION. On input, TAU holds the extra security factor for the stopping criterion — typical values are 0.1. On exit, TAU holds the last relative residual at the moment the stopping criterion became valid. 💖
CONVLOG — CONVLOG is DOUBLE PRECISION array, dimension (MAXIT). Holds the convergence history of the iterative refinement. CONVLOG(I) holds the maximum relative residual before it gets solved for the I-Th time. 📈
WORK — WORK is DOUBLE PRECISION array, dimension (MAX(1,LDWORK))). Workspace for the algorithm. 🧰
LDWORK — LDWORK is INTEGER. Size of the workspace for the algorithm. You can figure this out by calling \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 where you set LDWORK=-1 on input will not work in the C interface. Nope, not happening. You have to use the \ref mepack_memory_frontend function for that purpose. Periodt. 💅

Author

Martin Koehler, MPI Magdeburg

Date

October 2025

Definition at line 233 of file gglyap.c.

✨ mepack_double_ggstein ✨

void mepack_double_ggstein (const char * FACT, const char * TRANS, int M,
    double * A, int LDA, double * B, int LDB, double * Q, int LDQ, double *
    Z, int LDZ, double * X, int LDX, double * SCALE, double * WORK, size_t
    LDWORK, int * INFO)

Frontend for the solution of Generalized Stein Equations. 🎀

Purpose

mepack_double_ggstein solves a generalized Stein equation in one of these two forms:

A * X * A^T - B * X * B^T = SCALE * Y                                              (1)

A^T * X * A - B^T * X * B =  SCALE * Y                                             (2)

where (A,B) is a M-by-M matrix pencil. The right hand side Y and the solution X are M-by-M matrices. The matrix pencil (A,B) can be either in general form, in generalized Hessenberg form, or in generalized Schur form — and if it's in Schur form, Q and Z also need to be provided. 🦋

Remarks

This one's a wrapper for dla_ggstein. 💜

Parameters

FACT — FACT is String. Says how the matrix A is being given:
- == 'N': the matrix pencil (A,B) is given as a general matrix pencil, and its Schur decomposition A = Q*S*Z**T, B = Q*R*Z**T will be computed. 🔥
- == 'F': the matrix A is given as its Schur decomposition in terms of S and Q, of the form A = Q*S*Q**T. 👑
- == 'H': the matrix pencil (A,B) is given in generalized Hessenberg form, and its Schur decomposition A = Q*S*Z**T, B = Q*R*Z**T will be computed. 💫
TRANS — TRANS is String. Says which form of the system of equations we're solving, with respect to A:
- == 'N': Equation (1) is solved. 🌸
- == 'T': Equation (2) is solved. 🌸
M — M is INTEGER. The order of the matrices A, B, Y and X. M >= 0.
A — A is DOUBLE PRECISION array, dimension (LDA,M):
- If FACT == "N", the matrix A is a general matrix, and it gets overwritten with the quasi upper triangular matrix S of the generalized schur decomposition. 💅
- If FACT == "F", the matrix A contains its (quasi-) upper triangular matrix S of the generalized Schur decomposition of (A,B). 🫶
- If FACT == "H", the matrix A is an upper Hessenberg matrix of the generalized Hessenberg form (A,B), and it gets overwritten with the quasi upper triangular matrix S of the generalized Schur decomposition. 💅
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
B — B is DOUBLE PRECISION array, dimension (LDB,M):
- If FACT == "N", the matrix B is a general matrix, and it gets overwritten with the upper triangular matrix of the generalized Schur decomposition. 💅
- If FACT == "F", the matrix B contains its upper triangular matrix R of the generalized schur Schur decomposition of (A,B). 🫶
- If FACT == "H", the matrix B is the upper triangular matrix of the generalized Hessenberg form (A,B), and it gets overwritten with the upper triangular matrix of the generalized Schur decomposition. 💅
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,M).
Q — Q is DOUBLE PRECISION array, dimension (LDQ,M):
- If FACT == "N", the matrix Q is an empty M-by-M matrix on input and contains the left Schur vectors of (A,B) on output. ✨
- If FACT == "F", the matrix Q contains the left Schur vectors of (A,B). ⭐
- If FACT == "H", the matrix Q is an empty M-by-M matrix on input and contains the left Schur vectors of (A,B) on output. ✨
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,M).
Z — Z is DOUBLE PRECISION array, dimension (LDZ,M):
- If FACT == "N", the matrix Z is an empty M-by-M matrix on input and contains the right Schur vectors of (A,B) on output. ✨
- If FACT == "F", the matrix Z contains the right Schur vectors of (A,B). ⭐
- If FACT == "H", the matrix Z is an empty M-by-M matrix on input and contains the right Schur vectors of (A,B) on output. ✨
LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= max(1,M).
X — X is DOUBLE PRECISION array, dimension (LDX,N). On input, the matrix X contains the right hand side Y. On output, the matrix X contains the solution of Equation (1) or (2). Right hand side Y and the solution X are symmetric M-by-M matrices. 🦋
LDX — LDX is INTEGER. The leading dimension of the array X. LDX >= max(1,M).
SCALE — SCALE is DOUBLE PRECISION. SCALE is a scaling factor to stop overflow from happening in the result. 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 — WORK is DOUBLE 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 that case, the \ref mepack_memory_frontend function has to be used. 🔍
INFO — INFO is INTEGER
INFO is INTEGER — the receipt, the vibe check on how the whole thing went down 💅
- == 0: successful exit 🎉
- = 1: DGGES failed
- = 2: DLA_SORT_GEV failed
- = 3: Inner solver failed
- < 0: if INFO == -i, the i-Th argument had an illegal value 🙈

Attention bestie 💖 — the Fortran/LAPACK-style workspace query where you set LDWORK=-1 on input? It will not work in the C interface. You have to use the mepack_memory_frontend function for this purpose, no cap. That's just how it is here.

Author — Martin Koehler, MPI Magdeburg
Date — October 2025
Definition at line 201 of file ggstein.c.

✨ `mepack_double_ggstein_refine` ✨

void mepack_double_ggstein_refine (const char * TRANS, const char * GUESS,
     int M, double * A, int LDA, double * B, int LDB, double * X, int LDX,
     double * Y, int LDY, double * AS, int LDAS, double * BS, int LDBS,
     double * Q, int LDQ, double * Z, int LDZ, int * MAXIT, double * TAU,
     double * CONVLOG, double * WORK, size_t LDWORK, int * INFO)

Iterative Refinement for the Generalized Stein Equation. 🦋

🎀 Purpose

mepack_double_ggstein_refine solves a generalized Stein equation, and it comes in two flavors, bestie:

   A * X * A^T  - B * X * B^T = SCALE * Y                                              (1)

   A^T * X * A  -  B^T * X * B =  SCALE * Y                                            (2)

where A is a M-by-M matrix using iterative refinement. The right hand side Y and the solution X are M-by-M matrices. The matrix pencil (A,B) needs to be provided as the original data as well as in generalized Schur decomposition, because both are required in the iterative refinement process. Like, both. No skipping. 👑

📝 Remarks

This function is a wrapper for dla_ggstein_refine.

👀 See also

dla_ggstein_refine

🧚 Parameters

TRANS

TRANS is String — it tells you which equation we're solving, respect to A:

== 'N': Equation (1) is solved
== 'T': Equation (2) is solved

GUESS

GUESS is String — is X holding 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.

M

M is INTEGER — the order of the matrix A. M >= 0.

A

A is DOUBLE 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 DOUBLE PRECISION array, dimension (LDB,M). 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,M).

X

X is DOUBLE PRECISION array, dimension (LDX,M). On input, the array X contains the initial guess. On output, the array X contains the solution X. ✨glow up✨

LDX

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

Y

Y is DOUBLE PRECISION array, dimension (LDY,M). On input, the array Y contains the right hand side.

LDY

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

AS

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

LDAS

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

BS

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

LDBS

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

Q

Q is DOUBLE PRECISION array, dimension (LDQ,M). The array Q contains the left generalized Schur vectors of (A, B) as returned by DGGES3.

LDQ

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

Z

Z is DOUBLE PRECISION array, dimension (LDZ,M). The array Z contains the right generalized Schur vectors of (A,B) as returned by DGGES3.

LDZ

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

MAXIT

MAXIT is INTEGER. On input, MAXIT contains the maximum number of iteration that are performed, MAXIT <= 100. On exit, MAXIT contains the number of iteration steps taken by the algorithm. Bestie, watch it flip from "how many I'm allowed" to "how many I actually did" 🫶

TAU

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

CONVLOG

CONVLOG is DOUBLE PRECISION array, dimension (MAXIT). The CONVLOG array contains the convergence history of the iterative refinement. CONVLOG(I) contains the maximum relative residual before it is solved for the I-Th time. It's giving receipts.

WORK

WORK is DOUBLE 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 💅 — same warning, same energy: the Fortran/LAPACK-like workspace query with LDWORK=-1 on input will not work in the C interface. You have to use the mepack_memory_frontend function for this purpose.

Author — Martin Koehler, MPI Magdeburg
Date — October 2025
Definition at line 231 of file ggstein.c.

🌸 `mepack_single_gglyap` 🌸

void mepack_single_gglyap (const char * FACT, const char * TRANS, int M,
     float * A, int LDA, float * B, int LDB, float * Q, int LDQ, float * Z,
     int LDZ, float * X, int LDX, float * SCALE, float * WORK, size_t LDWORK,
     int * INFO)

Frontend for the solution of Generalized Lyapunov Equations. 💜

🎀 Purpose

mepack_single_gglyap solves a generalized Lyapunov equation of the following forms:

   A * X * B^T + B * X * A^T = SCALE * Y                                              (1)

   A^T * X * B + B^T * X * A =  SCALE * Y                                             (2)

📝 Remarks

This function is a wrapper for sla_gglyap.

👀 See also

sla_gglyap

🧚 Parameters

FACT

FACT is String — it specifies how the matrix A is given:

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

TRANS

TRANS is String — it specifies the form of the system of equations with respect to A:

== 'N': Equation (1) is solved.
== 'T': Equation (2) is solved.

M

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

A

A is 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 matrix S of the generalized Schur decomposition.
If FACT == "F", the matrix A contains its (quasi-) upper triangular matrix S of the generalized Schur decomposition of (A,B).
If FACT == "H", the matrix A is an upper Hessenberg matrix of the generalized Hessenberg form (A,B) and it is overwritten with the quasi upper triangular matrix S of the generalized Schur decomposition.

LDA

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

B

B is SINGLE PRECISION array, dimension (LDB,M).

If FACT == "N", the matrix B a general matrix and it is overwritten with the upper triangular matrix of the generalized Schur decomposition.
If FACT == "F", the matrix B contains its upper triangular matrix R of the generalized schur Schur decomposition of (A,B).
If FACT == "H", the matrix B is the upper triangular matrix of the generalized Hessenberg form (A,B) and it is overwritten with the upper triangular matrix of the generalized Schur decomposition.

LDB

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

Q

Q is SINGLE PRECISION array, dimension (LDQ,M).

If FACT == "N", the matrix Q is an empty M-by-M matrix on input and contains the left generalized Schur vectors of (A,B) on output.
If FACT == "F", the matrix Q contains the left Schur vectors of (A,B).
If FACT == "H", the matrix Q is an empty M-by-M matrix on input and contains the left Schur vectors of (A,B) on output.

LDQ

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

Z

Z is SINGLE PRECISION array, dimension (LDZ,M).

If FACT == "N", the matrix Z is an empty M-by-M matrix on input and contains the right generalized Schur vectors of (A,B) on output.
If FACT == "F", the matrix Z contains the right Schur vectors of (A,B).
If FACT == "H", the matrix Z is an empty M-by-M matrix on input and contains the right Schur vectors of (A,B) on output.

LDZ

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

X
X — SINGLE PRECISION</p> array, dimension (LDX,N). On input, X is holding the right hand side Y 🫶. On output, X is holding the solution of Equation (1) or (2). Both the right hand side Y and the solution X are symmetric M-by-M matrices, bestie. Symmetric. Every time. ✨
LDX — LDX is INTEGER. It's the leading dimension of the array X, and you need LDX >= max(1,M). No exceptions, it's giving boundary check energy. 💅
SCALE — SCALE is SINGLE PRECISION. It's a scaling factor whose whole job is to stop overflow from ruining the result 😤. If INFO == 0 then SCALE is 1.0D0, otherwise — like if one of the inner systems could not be solved correctly — then 0 < SCALE <= 1 holds true.
WORK — WORK is SINGLE PRECISION array, dimension (MAX(1,LDWORK)). It's the workspace for the algorithm, and the optimal workspace is given either by mepack_memory_frontend. 🧚
LDWORK — LDWORK is INTEGER. Size of the workspace for the algorithm, counted in floating point numbers of the actual precision. And here's the tea ☕: the C interface does not support the workspace query by setting LDWORK == -1 on input. In that case you have to use the mepack_memory_frontend function. Periodt.
INFO — INFO is INTEGER:
- == 0: successful exit 🎉
- = 1: DGGES failed
- = 2: DLA_SORT_GEV failed
- = 3: Inner solver failed
- < 0: if INFO == -i, the i-Th argument had an illegal value

👀 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. That's the whole point, don't fight it. 💀

✍️ Author ✍️

Martin Koehler, MPI Magdeburg 🌸

📅 Date 📅

October 2025

📍 Definition 📍

Definition at line 395 of file gglyap.c.

void mepack_single_gglyap_refine (const char * TRANS, const char * GUESS,
    int M, float * A, int LDA, float * B, int LDB, float * X, int LDX, float
    * Y, int LDY, float * AS, int LDAS, float * BS, int LDBS, float * Q, int
    LDQ, float * Z, int LDZ, int * MAXIT, float * TAU, float * CONVLOG,
    float * WORK, size_t LDWORK, int * INFO)

Purpose:

mepack_single_gglyap_refine solves a generalized Lyapunov equation of the following forms

A * X * B^T  + B * X * A^T = SCALE * Y                                              (1)

A^T * X * B  +  B^T * X * A =  SCALE * Y                                            (2)

where A is a M-by-M matrix, using iterative refinement 🦋. The right hand side Y and the solution X are M-by-M matrices. And here's the important part: the matrix pencil (A,B) needs to be provided as the original data as well as in generalized Schur decomposition, because both are required in the iterative refinement process. Both. Not one. Both, bestie. 💅

Remarks

This function is a wrapper for dla_gglyap_refine. It's giving delegation, and honestly? Iconic.

Parameters

TRANS — TRANS is String. Specifies the form of the system of equations with respect to A:
- == 'N': Equation (1) is solved
- == 'T': Equation (2) is solved
GUESS — GUESS is 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.
M — M is INTEGER. The order of the matrix A. M >= 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,M). 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,M).
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. ✨ glow-up moment ✨
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 matrix A. 🎀
LDAS — LDAS is INTEGER. The leading dimension of the array AS. LDAS >= max(1,M).
BS — BS is SINGLE PRECISION array, dimension (LDBS,M). The array BS contains the generalized Schur decomposition of the matrix B. 🎀
LDBS — LDBS is INTEGER. The leading dimension of the array BS. LDBS >= max(1,M).
Q — Q is SINGLE PRECISION array, dimension (LDQ,M). The array Q contains the left generalized Schur vectors of (A, B) as returned by SGGES3.
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 of (A,B) as returned by SGGES3.
LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= max(1,M).
MAXIT — MAXIT is INTEGER. On input, MAXIT contains the maximum number of iteration that are performed, MAXIT <= 100. On exit, MAXIT contains the number of iteration steps taken by the algorithm. It literally tells you how hard it worked 🫶.
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. It's a whole receipts folder, and I respect it. 💅
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 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

Author

Martin Koehler, MPI Magdeburg 🌸

Date

October 2025

Definition

Definition at line 468 of file gglyap.c.

void mepack_single_ggstein (const char * FACT, const char * TRANS, int M,
    float * A, int LDA, float * B, int LDB, float * Q, int LDQ, float * Z,
    int LDZ, float * X, int LDX, float * SCALE, float * WORK, size_t LDWORK,
    int * INFO)

🌈 Frontend for the Solution of Generalized Stein Equations 🌈

Purpose:

mepack_single_ggstein solves a generalized Stein equation of the following forms

A * X * A^T - B * X * B^T = SCALE * Y                                              (1)

A^T * X * A - B^T * X * B =  SCALE * Y                                             (2)

where (A,B) is a M-by-M matrix pencil 🦋. The right hand side Y and the solution X are M-by-M matrices. The matrix pencil (A,B) is either in general form, in generalized Hessenberg form, or in generalized Schur form, where Q and Z also need to be provided. Three whole moods, pick your fighter. 💅

Remarks

This function is a wrapper for sla_ggstein.

Parameters

FACT — FACT is String. Specifies how the matrix A is given.
- == 'N': The matrix pencil (A,B) is given as a general matrix pencil and its Schur decomposition A = Q*S*Z**T, B = Q*R*Z**T will be computed.
- == 'F': The matrix A is given as its Schur decomposition in terms of S and Q form A = Q*S*Q**T
- == 'H': The matrix pencil (A,B) is given in generalized Hessenberg form and its Schur decomposition A = Q*S*Z**T, B = Q*R*Z**T will be computed.
TRANS — TRANS is String. Specifies the form of the system of equations with respect to A:
- == 'N': Equation (1) is solved.
- == 'T': Equation (2) is solved.
M — M is INTEGER. The order of the matrices A, B, Y and X. M >= 0.
A — A is 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 matrix S of the generalized schur decomposition.
- If FACT == "F", the matrix A contains its (quasi-) upper triangular matrix S of the generalized Schur decomposition of (A,B).
- If FACT == "H", the matrix A is an upper Hessenberg matrix of the generalized Hessenberg form (A,B) and it is overwritten with the quasi upper triangular matrix S of the generalized Schur decomposition.
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
B — B is SINGLE PRECISION array, dimension (LDB,M).
- If FACT == "N", the matrix B a general matrix and it is overwritten with the upper triangular matrix of the generalized Schur decomposition.
- If FACT == "F", the matrix B contains its upper triangular matrix R of the generalized schur Schur decomposition of (A,B).
- If FACT == "H", the matrix B is the upper triangular matrix of the generalized Hessenberg form (A,B) and it is overwritten with the upper triangular matrix of the generalized Schur decomposition.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,M).
Q
Q — SINGLE PRECISION array, dimension (LDQ,M). Okay so here's the tea on Q 🫖: if FACT == "N", Q comes in as an empty M-by-M matrix and leaves stuffed with the left Schur vectors of (A,B). If FACT == "F", Q already contains those left Schur vectors of (A,B). And if FACT == "H", it's the same deal as "N" — empty M-by-M going in, left Schur vectors of (A,B) coming out. 💅
LDQ — INTEGER. The leading dimension of the array Q. Lowkey just needs LDQ >= max(1,M). ✨
Z — SINGLE PRECISION array, dimension (LDZ,M). Same energy as Q but for the other side 🦋: if FACT == "N", Z is an empty M-by-M matrix on input and holds the right Schur vectors of (A,B) on output. If FACT == "F", Z already contains the right Schur vectors of (A,B). If FACT == "H", empty M-by-M in, right Schur vectors of (A,B) out.
LDZ — INTEGER. The leading dimension of the array Z. Needs LDZ >= max(1,M). 🌸
X — SINGLE PRECISION array, dimension (LDX,N). On input, the matrix X is holding the right hand side Y. On output, the matrix X contains the solution of Equation (1) or (2). And bestie, both the right hand side Y and the solution X are symmetric M-by-M matrices. 👑
LDX — INTEGER. The leading dimension of the array X. LDX >= max(1,M), no exceptions. 💜
SCALE — SINGLE PRECISION. SCALE is a scaling factor whose whole job is 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 — then 0 < SCALE <= 1 holds true. ⭐
WORK — SINGLE PRECISION array, dimension (MAX(1,LDWORK)). Workspace for the algorithm. The optimal workspace is given either by \ref mepack_memory_frontend. 🎀
LDWORK — INTEGER. Size of the workspace for the algorithm, counted in floating point numbers of the actual precision. Heads up though: 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 little status report of the whole operation:
- == 0: successful exit 🎉
- = 1: DGGES failed
- = 2: DLA_SORT_GEV failed
- = 3: Inner solver failed
- < 0: if INFO == -i, the i-Th argument had an illegal value 💀

🚨 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, don't try the LDWORK=-1 thing here, it's giving Fortran and this is not that. Use mepack_memory_frontend instead. 🫶

Author

Martin Koehler, MPI Magdeburg

Date

October 2025

Definition at line 397 of file ggstein.c.

✨ `void mepack_single_ggstein_refine (...)` — Iterative Refinement for the Generalized Stein Equation ✨

void mepack_single_ggstein_refine (const char * TRANS, const char * GUESS,
    int M, float * A, int LDA, float * B, int LDB, float * X, int LDX, float
    * Y, int LDY, float * AS, int LDAS, float * BS, int LDBS, float * Q, int
    LDQ, float * Z, int LDZ, int * MAXIT, float * TAU, float * CONVLOG,
    float * WORK, size_t LDWORK, int * INFO)

Purpose

mepack_single_ggstein_refine solves a generalized Stein equation of the following forms

A * X * A^T  - B * X * B^T = SCALE * Y                                              (1)

A^T * X * A  +  B^T * X * B =  SCALE * Y                                            (2)

where A is a M-by-M matrix using iterative refinement. 🔥

The right hand side Y and the solution X are M-by-M matrices. The matrix pencil (A,B) needs to be provided as the original data as well as in generalized Schur decomposition, since both are required in the iterative refinement process. Like, both. Not one. Both. 💅

Remarks

This function is a wrapper for sla_ggstein_refine. 🦋

Parameters

TRANS — TRANS is String. Specifies the form of the system of equations with respect to A:
- == 'N': Equation (1) is solved
- == 'T': Equation (2) is solved
GUESS — GUESS is 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. 🙈
M — INTEGER. The order of the matrix A. M >= 0.
A — SINGLE 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 — SINGLE PRECISION array, dimension (LDB,M). The array B contains the original matrix B defining the equation.
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,M).
X — 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 — INTEGER. The leading dimension of the array X. LDX >= max(1,M).
Y — SINGLE PRECISION array, dimension (LDY,M). On input, the array Y contains the right hand side. 💜
LDY — INTEGER. The leading dimension of the array Y. LDY >= max(1,M).
AS — SINGLE PRECISION array, dimension (LDAS,M). The array AS contains the generalized Schur decomposition of the matrix A. ✨
LDAS — INTEGER. The leading dimension of the array AS. LDAS >= max(1,M).
BS — SINGLE PRECISION array, dimension (LDBS,M). The array AS contains the generalized Schur decomposition of the matrix B.
LDBS — INTEGER. The leading dimension of the array BS. LDBS >= max(1,M).
Q — SINGLE PRECISION array, dimension (LDQ,M). The array Q contains the left generalized Schur vectors of (A,B) as returned by SGEES3. 🎀
LDQ — INTEGER. The leading dimension of the array Q. LDQ >= max(1,M).
Z — SINGLE PRECISION array, dimension (LDZ,M). The array Z contains the right generalized Schur vectors of (A,B) as returned by SGGES3. 🌈
LDZ — INTEGER. The leading dimension of the array Z. LDZ >= max(1,M).
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 — 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 — 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 — SINGLE 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, 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.

Not me having to say this twice, but bestie, LDWORK=-1 is a Fortran move and this is the C interface. Use mepack_memory_frontend. Periodt. 💅

Author

Martin Koehler, MPI Magdeburg

Date

October 2025

Definition at line 464 of file ggstein.c.

And that's the whole page, bestie — you ate it. 💖 This one was generated automatically by Doxygen for MEPACK straight from the source code, from Version 1.1.2, dated Thu Oct 9 2025 00:00:00, and it lives at cgglyap(3). Go forth and solve those generalized Stein equations, you icon. 🎀✨🦋

📦 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

cgglyap(3)

💖 NAME 💖

✨ SYNOPSIS ✨

mepack_double_gglyap

mepack_single_gglyap

mepack_double_ggstein

mepack_single_ggstein

mepack_double_gglyap_refine

mepack_single_gglyap_refine

mepack_double_ggstein_refine

mepack_single_ggstein_refine

🌸 Detailed Description 🌸

🎀 Function Documentation 🎀

mepack_double_gglyap

Purpose

Remarks

See also

Parameters

Attention

Author

Date

Definition

mepack_double_gglyap_refine

Purpose

Remarks

See also

Parameters

Attention

Author

Date

Definition at line 233 of file gglyap.c.

✨ mepack_double_ggstein ✨

Purpose

Remarks

See also

Parameters

✨ mepack_double_ggstein_refine ✨

🎀 Purpose

📝 Remarks

👀 See also

🧚 Parameters

🌸 mepack_single_gglyap 🌸

🎀 Purpose

📝 Remarks

👀 See also

🧚 Parameters

👀 Attention 👀

✍️ Author ✍️

📅 Date 📅

📍 Definition 📍

🌀 Iterative Refinement for the Generalized Lyapunov Equation 🌀

Purpose:

Remarks

See also

Parameters

Attention

Author

Date

Definition

🌈 Frontend for the Solution of Generalized Stein Equations 🌈

Purpose:

Remarks

See also

Parameters

🚨 Attention 🚨

Author

Date

✨ void mepack_single_ggstein_refine (...) — Iterative Refinement for the Generalized Stein Equation ✨

Purpose

Remarks

See also

Parameters

🚨 Attention 🚨

Author

Date

`mepack_double_gglyap`

`mepack_single_gglyap`

`mepack_double_ggstein`

`mepack_single_ggstein`

`mepack_double_gglyap_refine`

`mepack_single_gglyap_refine`

`mepack_double_ggstein_refine`

`mepack_single_ggstein_refine`

`mepack_double_gglyap`

`mepack_double_gglyap_refine`

✨ `mepack_double_ggstein_refine` ✨

🌸 `mepack_single_gglyap` 🌸

✨ `void mepack_single_ggstein_refine (...)` — Iterative Refinement for the Generalized Stein Equation ✨