lassq(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

💅 lassq(3) — bestie's guide to lassq

okay so welcome to lassq(3), the manual page for the lassq family of routines ✨ and ngl the NAME line is doing a lot of heavy lifting here, so let's read it together:

lassq — sum-of-squares, avoiding over/underflow 🫶

that's the whole vibe. sum of squares. but make it safe so your numbers don't yeet themselves into overflow or underflow territory 😭 iconic behaviour honestly.

🌸 SYNOPSIS 🌸

✨ Functions ✨

okay so there's not one, not two, but four of these cuties — one for each flavour of Fortran real/complex ✨ same signature, different letter, no cap:

  • subroutine classq (n, x, incx, scale, sumsq) — CLASSQ updates a sum of squares represented in scaled form 💖
  • subroutine dlassq (n, x, incx, scale, sumsq) — DLASSQ updates a sum of squares represented in scaled form 💖
  • subroutine slassq (n, x, incx, scale, sumsq) — SLASSQ updates a sum of squares represented in scaled form 💖
  • subroutine zlassq (n, x, incx, scale, sumsq) — ZLASSQ updates a sum of squares represented in scaled form 💖

and like, yes, they all have the exact same argument list (n, x, incx, scale, sumsq) — that's the whole point, the naming convention is right there in the first letter, iykyk 👑

subroutine classq (n, x, incx, scale, sumsq)
subroutine dlassq (n, x, incx, scale, sumsq)
subroutine slassq (n, x, incx, scale, sumsq)
subroutine zlassq (n, x, incx, scale, sumsq)

🦋 Detailed Description 🦋

okay so lowkey this section is empty in this version of the page — the details are all up in the SYNOPSIS and in each routine's own entry 💀 no extra lore here, bestie, don't go looking for it.

fr fr if you want the actual argument-by-argument tea for each one, go pull up that specific routine — this page is just the family reunion 🎀

✨ FUNCTION DOCUMENTATION ✨

okay so this is where the actual subroutines live, bestie — and there are four of them, all doing the same iconic scaled-sum-of-squares thing but for different types. let's get into it 💅

🌟 classq — the complex one 🌟

subroutine classq (integer n, complex(wp), dimension(*) x, integer incx,
    real(wp) scale, real(wp) sumsq)

CLASSQ updates a sum of squares represented in scaled form. literally what it says on the tin, no cap.

Purpose

ok so CLASSQ returns the values scale_out and sumsq_out such that:

(scale_out**2)*sumsq_out = x( 1 )**2 +...+ x( n )**2 + (scale**2)*sumsq,

where x( i ) = X( 1 + ( i - 1 )*INCX ). The value of sumsq is assumed to be non-negative. (so don't come at it with negative sumsq, okay? it's assumed non-negative for a reason 😭)

scale and sumsq must be supplied in SCALE and SUMSQ and scale_out and sumsq_out are overwritten on SCALE and SUMSQ respectively. (it's an in-place glow-up, periodt 💅)

Parameters

  • N — N is INTEGER. the number of elements to be used from the vector x. (like how many besties are invited to the party 🎀)
  • X — X is COMPLEX array, dimension (1+(N-1)*abs(INCX)). the vector for which a scaled sum of squares is computed. and x( i ) = X( 1 + ( i - 1 )*INCX ), 1 <= i <= n. (so it's the guest list, basically 🦋)
  • INCX — INCX is INTEGER. the increment between successive values of the vector x. here's the tea:
    • if INCX > 0, X(1+(i-1)*INCX) = x(i) for 1 <= i <= n
    • if INCX < 0, X(1-(n-i)*INCX) = x(i) for 1 <= i <= n
    • if INCX = 0, x isn't a vector so there is no need to call this subroutine. if you call it anyway, it will count x(1) in the vector norm N times. (so like, why would you? but okay, it's your funeral 💀)
  • SCALE — SCALE is REAL. on entry, the value scale in the equation above. on exit, SCALE is overwritten by scale_out, the scaling factor for the sum of squares. (glow-up: it goes in as scale and comes out as scale_out ✨)
  • SUMSQ — SUMSQ is REAL. on entry, the value sumsq in the equation above. on exit, SUMSQ is overwritten by sumsq_out, the basic sum of squares from which scale_out has been factored out. (same deal, but for the sum of squares)

Author

Edward Anderson, Lockheed Martin (iconic 👑)

Contributors

Weslley Pereira, University of Colorado Denver, USA Nick Papior, Technical University of Denmark, DK (shoutout to the contributors, we love to see it 🫶)

Further Details

(these are the receipts, bestie — read them if you're curious about the math lore 📚)

Definition at line 123 of file classq.f90.

🌟 dlassq — the double-precision real one 🌟

subroutine dlassq (integer n, real(wp), dimension(*) x, integer incx,
    real(wp) scale, real(wp) sumsq)

DLASSQ updates a sum of squares represented in scaled form. same energy as classq but for DOUBLE PRECISION reals — lowkey the same vibe, highkey still important 🔥

Purpose

same deal: DLASSQ returns the values scale_out and sumsq_out such that:

(scale_out**2)*sumsq_out = x( 1 )**2 +...+ x( n )**2 + (scale**2)*sumsq,

where x( i ) = X( 1 + ( i - 1 )*INCX ). The value of sumsq is assumed to be non-negative. (still non-negative, still not playing around 😤)

scale and sumsq must be supplied in SCALE and SUMSQ and scale_out and sumsq_out are overwritten on SCALE and SUMSQ respectively.

Parameters

  • N — N is INTEGER. the number of elements to be used from the vector x.
  • X — X is DOUBLE PRECISION array, dimension (1+(N-1)*abs(INCX)). the vector for which a scaled sum of squares is computed. x( i ) = X( 1 + ( i - 1 )*INCX ), 1 <= i <= n.
  • INCX — INCX is INTEGER. the increment between successive values of the vector x.
    • if INCX > 0, X(1+(i-1)*INCX) = x(i) for 1 <= i <= n
    • if INCX < 0, X(1-(n-i)*INCX) = x(i) for 1 <= i <= n
    • if INCX = 0, x isn't a vector so there is no need to call this subroutine. if you call it anyway, it will count x(1) in the vector norm N times. (like, please don't, but if you do, it's gonna count that one element N times 💀)
  • SCALE — SCALE is DOUBLE PRECISION. on entry, the value scale in the equation above. on exit, SCALE is overwritten by scale_out, the scaling factor for the sum of squares.
  • SUMSQ — SUMSQ is DOUBLE PRECISION. on entry, the value sumsq in the equation above. on exit, SUMSQ is overwritten by sumsq_out, the basic sum of squares from which scale_out has been factored out.

Author

Edward Anderson, Lockheed Martin

Contributors

Weslley Pereira, University of Colorado Denver, USA Nick Papior, Technical University of Denmark, DK

Further Details

Definition at line 123 of file dlassq.f90.

okay so that's classq and dlassq covered — next up in part 3 we've got slassq and zlassq, which are literally the same but for REAL and DOUBLE COMPLEX. same vibe, different precision. stay tuned, bestie 💅✨

👑 AUTHOR 👑

Okay so nobody actually sat down and wrote this one, bestie — it says right here: Generated automatically by Doxygen for LAPACK from the source code. So the "author" is a robot that reads Fortran and spits out docs 💅 Not me getting emotional over an automated doc generator, but like... it ate. No cap.

So yeah — no human byline, no "written by ✨someone✨", just Doxygen doing its little auto-gen thing for LAPACK, pulling everything straight from the source code. That's the whole author section, fr fr. Short and iconic 🎀

And that's a wrap on lassq(3), bestie!! 🦋 This whole gorgeous little page comes to you courtesy of LAPACK, Version 3.12.0, with lassq(3) sitting pretty in the footer alongside its date stamp — the standard man-page send-off, just delivered with way more sparkle ✨ Go forth and sum those squares responsibly. Mwah 💖🌸

📦 where this page comes from