lartg(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

💅 lartg — the glow-up page (lartg(3), Library Functions Manual)

okay so bestie, welcome to lartg(3) from the Library Functions Manual — this is the whole LAPACK family of plane-rotation generators, and they are that girl. Not me explaining lartg in a cute way and then dropping half the flags — no ma'am, every single subroutine, parameter, author and line number is coming with us. Let's go. 🎀

✨ NAME ✨

lartg - lartg: generate plane rotation, more accurate than BLAS rot

🌸 SYNOPSIS 🌸

Functions

  • subroutine clartg (f, g, c, s, r) — CLARTG generates a plane rotation with real cosine and complex sine.
  • subroutine dlartg (f, g, c, s, r) — DLARTG generates a plane rotation with real cosine and real sine.
  • subroutine slartg (f, g, c, s, r) — SLARTG generates a plane rotation with real cosine and real sine.
  • subroutine zlartg (f, g, c, s, r) — ZLARTG generates a plane rotation with real cosine and complex sine.

🦋 DETAILED DESCRIPTION 🦋

bestie. the "Detailed Description" section of this page is literally empty. not a single word under it. the heading is standing there alone, main character energy, serving absolutely nothing. 😭 so we're moving straight to the function docs, which are where the actual tea is. 💅

🔥 FUNCTION DOCUMENTATION 🔥

subroutine clartg (complex(wp) f, complex(wp) g, real(wp) c, complex(wp) s, complex(wp) r)

CLARTG generates a plane rotation with real cosine and complex sine — the complex-girlie edition, for single precision (that's the sp one). 🫶

Purpose

okay so CLARTG generates a plane rotation so that

[  C         S  ] . [ F ]  =  [ R ]
[ -conjg(S)  C  ]   [ G ]     [ 0 ]

where C is real and C**2 + |S|**2 = 1. slay.

the mathematical formulas used for C and S are

sgn(x) = {  x / |x|,   x != 0
          {  1,         x  = 0

R = sgn(F) * sqrt(|F|**2 + |G|**2)

C = |F| / sqrt(|F|**2 + |G|**2)

S = sgn(F) * conjg(G) / sqrt(|F|**2 + |G|**2)

special conditions, and these are important:

  • If G=0, then C=1 and S=0.
  • If F=0, then C=0 and S is chosen so that R is real.

when F and G are real, the formulas simplify to C = F/R and S = G/R, and the returned values of C, S, and R should be identical to those returned by SLARTG. (crossover episode, we love to see it ✨)

the algorithm used to compute these quantities incorporates scaling to avoid overflow or underflow in computing the square root of the sum of squares. so it's not out here sweating about overflow — it's got range, literally.

this is the same routine CROTG fom BLAS1, except that F and G are unchanged on return. 👑 (yes, "fom" — that's the original page's spelling, we do not fix, we preserve.)

below, wp=>sp stands for single precision from LA_CONSTANTS module.

Parameters

  • F — F is COMPLEX(wp). the first component of vector to be rotated.
  • G — G is COMPLEX(wp). the second component of vector to be rotated.
  • C — C is REAL(wp). the cosine of the rotation.
  • S — S is COMPLEX(wp). the sine of the rotation.
  • R — R is COMPLEX(wp). the nonzero component of the rotated vector.

Author

Weslley Pereira, University of Colorado Denver, USA

Date

December 2021

Further Details

based on the algorithm from

Anderson E. (2017)
Algorithm 978: Safe Scaling in the Level 1 BLAS
ACM Trans Math Softw 44:1--28
https://doi.org/10.1145/3061665

Definition at line 115 of file clartg.f90.

subroutine dlartg (real(wp) f, real(wp) g, real(wp) c, real(wp) s, real(wp) r)

DLARTG generates a plane rotation with real cosine and real sine — all-real everything, double precision (dp). 🧚

Purpose

okay so DLARTG generates a plane rotation so that

[  C  S  ]  .  [ F ]  =  [ R ]
[ -S  C  ]     [ G ]     [ 0 ]

where C**2 + S**2 = 1.

the mathematical formulas used for C and S are

R = sign(F) * sqrt(F**2 + G**2)
C = F / R
S = G / R

hence C >= 0. the algorithm used to compute these quantities incorporates scaling to avoid overflow or underflow in computing the square root of the sum of squares. yes, again — same safety-scaling flex, we stan a consistent icon. 💅

this version is discontinuous in R at F = 0 but it returns the same C and S as ZLARTG for complex inputs (F,0) and (G,0).

this is a more accurate version of the BLAS1 routine DROTG, with the following other differences:

  • F and G are unchanged on return.
  • If G=0, then C=1 and S=0.
  • If F=0 and (G .ne. 0), then C=0 and S=sign(1,G) without doing any floating point operations (saves work in DBDSQR when there are zeros on the diagonal).

below, wp=>dp stands for double precision from LA_CONSTANTS module.

Parameters

  • F — F is REAL(wp). the first component of vector to be rotated.
  • G — G is REAL(wp). the second component of vector to be rotated.
  • C — C is REAL(wp). the cosine of the rotation.
  • S — S is REAL(wp). the sine of the rotation.
  • R — R is REAL(wp). the nonzero component of the rotated vector.

Author

Edward Anderson, Lockheed Martin

Date

July 2016

Contributors

Weslley Pereira, University of Colorado Denver, USA

Further Details

Anderson E. (2017)
Algorithm 978: Safe Scaling in the Level 1 BLAS
ACM Trans Math Softw 44:1--28
https://doi.org/10.1145/3061665

Definition at line 110 of file dlartg.f90.

subroutine slartg (real(wp) f, real(wp) g, real(wp) c, real(wp) s, real(wp) r)

SLARTG generates a plane rotation with real cosine and real sine — the single-precision twin of DLARTG, same vibe, smaller floats. 🍓

Purpose

okay so SLARTG generates a plane rotation so that

[  C  S  ]  .  [ F ]  =  [ R ]
[ -S  C  ]     [ G ]     [ 0 ]

where C**2 + S**2 = 1.

the mathematical formulas used for C and S are

R = sign(F) * sqrt(F**2 + G**2)
C = F / R
S = G / R

hence C >= 0. the algorithm used to compute these quantities incorporates scaling to avoid overflow or underflow in computing the square root of the sum of squares.

this version is discontinuous in R at F = 0 but it returns the same C and S as CLARTG for complex inputs (F,0) and (G,0).

this is a more accurate version of the BLAS1 routine SROTG, with the following other differences:

  • F and G are unchanged on return.
  • If G=0, then C=1 and S=0.
  • If F=0 and (G .ne. 0), then C=0 and S=sign(1,G) without doing any floating point operations (saves work in SBDSQR when there are zeros on the diagonal).

below, wp=>sp stands for single precision from LA_CONSTANTS module.

Parameters

  • F — F is REAL(wp). the first component of vector to be rotated.
  • G — G is REAL(wp). the second component of vector to be rotated.
  • C — C is REAL(wp). the cosine of the rotation.
  • S — S is REAL(wp). the sine of the rotation.
  • R — R is REAL(wp). the nonzero component of the rotated vector.

Author

Edward Anderson, Lockheed Martin

Date

July 2016

Contributors

Weslley Pereira, University of Colorado Denver, USA

Further Details

Anderson E. (2017)
Algorithm 978: Safe Scaling in the Level 1 BLAS
ACM Trans Math Softw 44:1--28
https://doi.org/10.1145/3061665

Definition at line 110 of file slartg.f90.

subroutine zlartg (complex(wp) f, complex(wp) g, real(wp) c, complex(wp) s, complex(wp) r)

ZLARTG generates a plane rotation with real cosine and complex sine — the double-precision complex one, the big sister of CLARTG. 👑

Purpose

okay so ZLARTG generates a plane rotation so that

[  C         S  ] . [ F ]  =  [ R ]
[ -conjg(S)  C  ]   [ G ]     [ 0 ]

where C is real and C**2 + |S|**2 = 1.

the mathematical formulas used for C and S are

sgn(x) = {  x / |x|,   x != 0
          {  1,         x  = 0

R = sgn(F) * sqrt(|F|**2 + |G|**2)

C = |F| / sqrt(|F|**2 + |G|**2)

S = sgn(F) * conjg(G) / sqrt(|F|**2 + |G|**2)

special conditions:

  • If G=0, then C=1 and S=0.
  • If F=0, then C=0 and S is chosen so that R is real.

when F and G are real, the formulas simplify to C = F/R and S = G/R, and the returned values of C, S, and R should be identical to those returned by DLARTG.

the algorithm used to compute these quantities incorporates scaling to avoid overflow or underflow in computing the square root of the sum of squares. icon behaviour, honestly.

this is the same routine ZROTG fom BLAS1, except that F and G are unchanged on return.

below, wp=>dp stands for double precision from LA_CONSTANTS module.

Parameters

  • F — F is COMPLEX(wp). the first component of vector to be rotated.
  • G — G is COMPLEX(wp). the second component of vector to be rotated.
  • C — C is REAL(wp). the cosine of the rotation.
  • S — S is COMPLEX(wp). the sine of the rotation.
  • R — R is COMPLEX(wp). the nonzero component of the rotated vector.

Author

Weslley Pereira, University of Colorado Denver, USA

Date

December 2021

Further Details

based on the algorithm from

Anderson E. (2017)
Algorithm 978: Safe Scaling in the Level 1 BLAS
ACM Trans Math Softw 44:1--28
https://doi.org/10.1145/3061665

Definition at line 115 of file zlartg.f90.

🫶 AUTHOR 🫶

Generated automatically by Doxygen for LAPACK from the source code.

no cap bestie, that's the whole page — nothing skipped, nothing invented, every subroutine accounted for. 💖

and that's the wrap: LAPACK Version 3.12.0, page lartg(3), mwah 💋 — go rotate something pretty. 🌈⭐

📦 where this page comes from