SRC/iparmq.f(3)

📦
version 3.12.1 · 4 versions
, in arch rolling

🌸 SRC/iparmq.f(3) — IPARMQ 🌸

okay so bestie, this is the Library Functions Manual page for SRC/iparmq.f(3) — manual name folded in near the top like a lil name tag 🫶. It’s the IPARMQ page, and yes she has main character energy in the eigenvalue-parameter department.

🌸 NAME 🌸

SRC/iparmq.f — that’s the name, no extra lore, periodt 💅.

✨ SYNOPSIS ✨

🎀 Functions/Subroutines 🎀

integer function iparmq (ispec, name, opts, n, ilo, ihi, lwork)
    IPARMQ

💅 Function/Subroutine Documentation 💅

Here’s the full signature the docs show, bestie:

integer function iparmq (integer ispec, character, dimension( * ) name,
       character, dimension( * ) opts, integer n, integer ilo, integer ihi,
       integer lwork)
    IPARMQ

🔥 Purpose 🔥

This program sets problem- and machine-dependent parameters that are useful for xHSEQR and related subroutines for eigenvalue problems. It is called whenever IPARMQ is called with 12 <= ISPEC <= 16.

and yes, the Purpose block literally says 12 <= ISPEC <= 16 while the parameter list below rolls out ISPEC=17 — the source is giving plot twist, I’m just reporting it 💀.

🌈 Parameters 🌈

Every parameter below was wearing !> doc-comment markers in the source; I’ve peeled those off for readability but kept the tea exactly 🫶.

  • ISPEC — ISPEC is INTEGER; it specifies which tunable parameter IPARMQ should return.
    • ISPEC=12 — (INMIN) Matrices of order nmin or less are sent directly to xLAHQR, the implicit double shift QR algorithm. NMIN must be at least 11.
    • ISPEC=13 — (INWIN) Size of the deflation window. This is best set greater than or equal to the number of simultaneous shifts NS. Larger matrices benefit from larger deflation windows.
    • ISPEC=14 — (INIBL) Determines when to stop nibbling and invest in an (expensive) multi-shift QR sweep. If the aggressive early deflation subroutine finds LD converged eigenvalues from an order NW deflation window and LD > (NW*NIBBLE)/100, then the next QR sweep is skipped and early deflation is applied immediately to the remaining active diagonal block. Setting IPARMQ(ISPEC=14) = 0 causes TTQRE to skip a multi-shift QR sweep whenever early deflation finds a converged eigenvalue. Setting IPARMQ(ISPEC=14) greater than or equal to 100 prevents TTQRE from skipping a multi-shift QR sweep.
    • ISPEC=15 — (NSHFTS) The number of simultaneous shifts in a multi-shift QR iteration.
    • ISPEC=16 — (IACC22) IPARMQ is set to 0, 1 or 2 with the following meanings.
      • 0: During the multi-shift QR/QZ sweep, blocked eigenvalue reordering, blocked Hessenberg-triangular reduction, reflections and/or rotations are not accumulated when updating the far-from-diagonal matrix entries.
      • 1: During the multi-shift QR/QZ sweep, blocked eigenvalue reordering, blocked Hessenberg-triangular reduction, reflections and/or rotations are accumulated, and matrix-matrix multiplication is used to update the far-from-diagonal matrix entries.
      • 2: During the multi-shift QR/QZ sweep, blocked eigenvalue reordering, blocked Hessenberg-triangular reduction, reflections and/or rotations are accumulated, and 2-by-2 block structure is exploited during matrix-matrix multiplies.
      • (If xTRMM is slower than xGEMM, then IPARMQ(ISPEC=16)=1 may be more efficient than IPARMQ(ISPEC=16)=2 despite the greater level of arithmetic work implied by the latter choice.)
    • ISPEC=17 — (ICOST) An estimate of the relative cost of flops within the near-the-diagonal shift chase compared to flops within the BLAS calls of a QZ sweep.
  • NAME — NAME is a CHARACTER string; name of the calling subroutine.
  • OPTS — OPTS is a CHARACTER string; this is a concatenation of the string arguments to TTQRE.
  • N — N is INTEGER; N is the order of the Hessenberg matrix H.
  • ILO — ILO is INTEGER.
  • IHI — IHI is INTEGER; it is assumed that H is already upper triangular in rows and columns 1:ILO-1 and IHI+1:N.
  • LWORK — LWORK is INTEGER; the amount of workspace available.

👑 Author 👑

  • Univ. of Tennessee
  • Univ. of California Berkeley
  • Univ. of Colorado Denver
  • NAG Ltd.

🦋 Further Details 🦋

Little is known about how best to choose these parameters. It is possible to use different values of the parameters for each of CHSEQR, DHSEQR, SHSEQR and ZHSEQR.

It is probably best to choose different parameters for different matrices and different parameters at different times during the iteration, but this has not been implemented --- yet.

The best choices of most of the parameters depend in an ill-understood way on the relative execution rate of xLAQR3 and xLAQR5 and on the nature of each particular eigenvalue problem. Experiment may be the only practical way to determine which choices are most effective.

Following is a list of default values supplied by IPARMQ. These defaults may be adjusted in order to attain better performance in any particular computational environment.

  • IPARMQ(ISPEC=12) — The xLAHQR vs xLAQR0 crossover point. Default: 75. (Must be at least 11.)
  • IPARMQ(ISPEC=13) — Recommended deflation window size. This depends on ILO, IHI and NS, the number of simultaneous shifts returned by IPARMQ(ISPEC=15). The default for (IHI-ILO+1) <= 500 is NS. The default for (IHI-ILO+1) > 500 is 3*NS/2.
  • IPARMQ(ISPEC=14) — Nibble crossover point. Default: 14.
  • IPARMQ(ISPEC=15) — Number of simultaneous shifts, NS. The source literally follows that with a multi-shift QR iteration. 🫠

If IHI-ILO+1 is ... greater than or equal to ... but less than ... the default is:

  • greater than or equal to 0 but less than 30 → NS = 2+
  • greater than or equal to 30 but less than 60 → NS = 4+
  • greater than or equal to 60 but less than 150 → NS = 10
  • greater than or equal to 150 but less than 590 → NS = **
  • greater than or equal to 590 but less than 3000 → NS = 64
  • greater than or equal to 3000 but less than 6000 → NS = 128
  • greater than or equal to 6000 but less than infinity → NS = 256
  • (+) By default matrices of this order are passed to the implicit double shift routine xLAHQR. See IPARMQ(ISPEC=12) above. These values of NS are used only in case of a rare xLAHQR failure.
  • ()** The asterisks (**) indicate an ad-hoc function increasing from 10 to 64.
  • IPARMQ(ISPEC=16) — Select structured matrix multiply. (See ISPEC=16 above for details.) Default: 3.
yes, the default here literally says 3 even though ISPEC=16 above lists 0, 1, and 2 — I’m not fixing the source, I’m just reading it out loud 😭.
  • IPARMQ(ISPEC=17) — Relative cost heuristic for blocksize selection. Expressed as a percentage. Default: 10.

Definition at line 229 of file iparmq.f.

👑 Author 👑 (Doxygen edition)

Generated automatically by Doxygen for LAPACK from the source code.

💖 cute sign-off: this footer says LAPACK, Version 3.12.0, page SRC/iparmq.f(3) — and there is no date in the original footer, so I’m not inventing one, bestie. 💖

📦 where this page comes from