DTGSYL(3)

🦋 DTGSYL — the generalized Sylvester equation solver, bestie edition 🦋

okay so real talk: this page is from dtgsyl.f, and the whole file lives at

/home/abuild/rpmbuild/BUILD/lapack-
static-3.12.0-build/lapack-3.12.0/SRC/dtgsyl.f

that's the NAME section, that's literally it, the name is the path, we love a self-titled queen 👑

✨ SYNOPSIS ✨

Functions/Subroutines

subroutine DTGSYL (trans, ijob, m, n, a, lda, b, ldb, c, ldc, d, ldd, e,
    lde, f, ldf, scale, dif, work, lwork, iwork, info)
    DTGSYL

like, that's the whole vibe right there. twenty-two arguments. no cap. 💅

🎀 Function/Subroutine Documentation 🎀

subroutine DTGSYL (character trans, integer ijob, integer m, integer n,
    double precision, dimension( lda, * ) a, integer lda, double precision,
    dimension( ldb, * ) b, integer ldb, double precision, dimension( ldc, *
    ) c, integer ldc, double precision, dimension( ldd, * ) d, integer ldd,
    double precision, dimension( lde, * ) e, integer lde, double precision,
    dimension( ldf, * ) f, integer ldf, double precision scale, double
    precision dif, double precision, dimension( * ) work, integer lwork,
    integer, dimension( * ) iwork, integer info)
DTGSYL

💖 Purpose 💖

okay bestie, deep breath, because DTGSYL is that girl. she solves the generalized Sylvester equation:

        A * R - L * B = scale * C                 (1)
        D * R - L * E = scale * F

where R and L are the unknown m-by-n matrices, and (A, D), (B, E) and (C, F) are given matrix pairs of size m-by-m, n-by-n and m-by-n respectively, with real entries. honestly? iconic.

(A, D) and (B, E) must be in generalized (real) Schur canonical form — that means A, B are upper quasi triangular and D, E are upper triangular. no exceptions, that's the dress code 🫶

the solution (R, L) overwrites (C, F). and 0 <= SCALE <= 1 is an output scaling factor chosen to avoid overflow. she's protective like that.

in matrix notation (1) is equivalent to solving Zx = scale b, where Z is defined as

           Z = [ kron(In, A)  -kron(B**T, Im) ]         (2)
               [ kron(In, D)  -kron(E**T, Im) ].

here Ik is the identity matrix of size k and X**T is the transpose of X. kron(X, Y) is the Kronecker product between the matrices X and Y. lowkey the Kronecker product is the main character of this whole equation ngl.

if TRANS = 'T', DTGSYL solves the transposed system Z**T*y = scale*b, which is equivalent to solving for R and L in

            A**T * R + D**T * L = scale * C           (3)
            R * B**T + L * E**T = scale * -F

this case (TRANS = 'T') is used to compute an one-norm-based estimate of Dif[(A,D), (B,E)], the separation between the matrix pairs (A,D) and (B,E), using DLACON. teamwork makes the dream work ✨

if IJOB >= 1, DTGSYL computes a Frobenius norm-based estimate of Dif[(A,D),(B,E)]. that is, the reciprocal of a lower bound on the reciprocal of the smallest singular value of Z. see [1-2] for more info, the receipts are in the references 💅

and finally — this is a level 3 BLAS algorithm. yes ma'am. 🔥

🌸 Parameters 🌸

TRANS — TRANS is CHARACTER*1
- = 'N': solve the generalized Sylvester equation (1).
- = 'T': solve the 'transposed' system (3).
IJOB — IJOB is INTEGER. specifies what kind of functionality to be performed:
- = 0: solve (1) only.
- = 1: The functionality of 0 and 3.
- = 2: The functionality of 0 and 4.
- = 3: Only an estimate of Dif[(A,D), (B,E)] is computed. (look ahead strategy IJOB = 1 is used).
- = 4: Only an estimate of Dif[(A,D), (B,E)] is computed. ( DGECON on sub-systems is used ).
- Not referenced if TRANS = 'T'. like, at all. she's not even looking at it 🙈
M — M is INTEGER. the order of the matrices A and D, and the row dimension of the matrices C, F, R and L.
N — N is INTEGER. the order of the matrices B and E, and the column dimension of the matrices C, F, R and L.
A — A is DOUBLE PRECISION array, dimension (LDA, M). the upper quasi triangular matrix A.
LDA — LDA is INTEGER. the leading dimension of the array A. LDA >= max(1, M).
B — B is DOUBLE PRECISION array, dimension (LDB, N). the upper quasi triangular matrix B.
LDB — LDB is INTEGER. the leading dimension of the array B. LDB >= max(1, N).
C — C is DOUBLE PRECISION array, dimension (LDC, N).
- On entry, C contains the right-hand-side of the first matrix equation in (1) or (3).
- On exit, if IJOB = 0, 1 or 2, C has been overwritten by the solution R. if IJOB = 3 or 4 and TRANS = 'N', C holds R, the solution achieved during the computation of the Dif-estimate.
LDC — LDC is INTEGER. the leading dimension of the array C. LDC >= max(1, M).
D — D is DOUBLE PRECISION array, dimension (LDD, M). the upper triangular matrix D.
LDD — LDD is INTEGER. the leading dimension of the array D. LDD >= max(1, M).
E — E is DOUBLE PRECISION array, dimension (LDE, N). the upper triangular matrix E.
LDE — LDE is INTEGER. the leading dimension of the array E. LDE >= max(1, N).
F — F is DOUBLE PRECISION array, dimension (LDF, N).
- On entry, F contains the right-hand-side of the second matrix equation in (1) or (3).
- On exit, if IJOB = 0, 1 or 2, F has been overwritten by the solution L. if IJOB = 3 or 4 and TRANS = 'N', F holds L, the solution achieved during the computation of the Dif-estimate.
LDF — LDF is INTEGER. the leading dimension of the array F. LDF >= max(1, M).
DIF — DIF is DOUBLE PRECISION.
- On exit DIF is the reciprocal of a lower bound of the reciprocal of the Dif-function, i.e. DIF is an upper bound of Dif[(A,D), (B,E)] = sigma_min(Z), where Z as in (2).
- IF IJOB = 0 or TRANS = 'T', DIF is not touched. hands off. don't perceive her 🫣
SCALE — SCALE is DOUBLE PRECISION.
- On exit SCALE is the scaling factor in (1) or (3).
- If 0 < SCALE < 1, C and F hold the solutions R and L, resp., to a slightly perturbed system but the input matrices A, B, D and E have not been changed. (good, we'd never let her touch your inputs 💖)
- If SCALE = 0, C and F hold the solutions R and L, respectively, to the homogeneous system with C = F = 0.
- Normally, SCALE = 1.
WORK — WORK is DOUBLE PRECISION array, dimension (MAX(1,LWORK)). on exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. the dimension of the array WORK. LWORK > = 1.
- If IJOB = 1 or 2 and TRANS = 'N', LWORK >= max(1,2*M*N).
- If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. sneak peek mode, we stan a queen who shows you the size before committing 💅✨
IWORK — IWORK is INTEGER array, dimension (M+N+6).
INFO — INFO is INTEGER. the gossip:
- =0: successful exit (slay)
- <0: If INFO = -i, the i-th argument had an illegal value.
- >0: (A, D) and (B, E) have common or close eigenvalues. 😬 that's not a good sign bestie, that's literally the "there's overlap" text message

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

four institutions and they all showed up. group project but everyone actually did the work 🌈

🧚 Contributors: 🧚

Bo Kagstrom and Peter Poromaa, Department of Computing Science, Umea University, S-901 87 Umea, Sweden.

give them their flowers, fr fr 🏵️

🍓 References: 🍓

 [1] B. Kagstrom and P. Poromaa, LAPACK-Style Algorithms and Software
     for Solving the Generalized Sylvester Equation and Estimating the
     Separation between Regular Matrix Pairs, Report UMINF - 93.23,
     Department of Computing Science, Umea University, S-901 87 Umea,
     Sweden, December 1993, Revised April 1994, Also as LAPACK Working
     Note 75.  To appear in ACM Trans. on Math. Software, Vol 22,
     No 1, 1996.

 [2] B. Kagstrom, A Perturbation Analysis of the Generalized Sylvester
     Equation (AR - LB, DR - LE ) = (C, F), SIAM J. Matrix Anal.
     Appl., 15(4):1045-1060, 1994

 [3] B. Kagstrom and L. Westin, Generalized Schur Methods with
     Condition Estimators for Solving the Generalized Sylvester
     Equation, IEEE Transactions on Automatic Control, Vol. 34, No. 7,
     July 1989, pp 745-751.

three whole papers, they really did the reading so we don't have to 💀📚

Definition at line 296 of file dtgsyl.f.

okay one lil warning to keep the whole vibe honest: TRANS = 'T' means IJOB is not referenced and DIF is not touched — so don't go reading either of those and expecting tea that was never poured 🙈

💜 SEE ALSO-ish / meta 💜

Author of this page: Generated automatically by Doxygen for LAPACK from the source code. yes, a robot wrote the original. she's got range.

and that's the whole page, bestie — written for LAPACK, Version 3.12.0, for the file at /home/abui...RC/dtgsyl.f(3). go forth and solve that generalized Sylvester equation, you absolute icon 🎀✨💅🦋

📦 where this page comes from

opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms