--- rpl/lapack/lapack/dlartgs.f 2010/12/21 13:53:32 1.2
+++ rpl/lapack/lapack/dlartgs.f 2023/08/07 08:38:58 1.15
@@ -1,50 +1,101 @@
- SUBROUTINE DLARTGS( X, Y, SIGMA, CS, SN )
- IMPLICIT NONE
+*> \brief \b DLARTGS generates a plane rotation designed to introduce a bulge in implicit QR iteration for the bidiagonal SVD problem.
+*
+* =========== DOCUMENTATION ===========
+*
+* Online html documentation available at
+* http://www.netlib.org/lapack/explore-html/
+*
+*> \htmlonly
+*> Download DLARTGS + dependencies
+*>
+*> [TGZ]
+*>
+*> [ZIP]
+*>
+*> [TXT]
+*> \endhtmlonly
+*
+* Definition:
+* ===========
+*
+* SUBROUTINE DLARTGS( X, Y, SIGMA, CS, SN )
+*
+* .. Scalar Arguments ..
+* DOUBLE PRECISION CS, SIGMA, SN, X, Y
+* ..
+*
+*
+*> \par Purpose:
+* =============
+*>
+*> \verbatim
+*>
+*> DLARTGS generates a plane rotation designed to introduce a bulge in
+*> Golub-Reinsch-style implicit QR iteration for the bidiagonal SVD
+*> problem. X and Y are the top-row entries, and SIGMA is the shift.
+*> The computed CS and SN define a plane rotation satisfying
+*>
+*> [ CS SN ] . [ X^2 - SIGMA ] = [ R ],
+*> [ -SN CS ] [ X * Y ] [ 0 ]
+*>
+*> with R nonnegative. If X^2 - SIGMA and X * Y are 0, then the
+*> rotation is by PI/2.
+*> \endverbatim
+*
+* Arguments:
+* ==========
+*
+*> \param[in] X
+*> \verbatim
+*> X is DOUBLE PRECISION
+*> The (1,1) entry of an upper bidiagonal matrix.
+*> \endverbatim
+*>
+*> \param[in] Y
+*> \verbatim
+*> Y is DOUBLE PRECISION
+*> The (1,2) entry of an upper bidiagonal matrix.
+*> \endverbatim
+*>
+*> \param[in] SIGMA
+*> \verbatim
+*> SIGMA is DOUBLE PRECISION
+*> The shift.
+*> \endverbatim
+*>
+*> \param[out] CS
+*> \verbatim
+*> CS is DOUBLE PRECISION
+*> The cosine of the rotation.
+*> \endverbatim
+*>
+*> \param[out] SN
+*> \verbatim
+*> SN is DOUBLE PRECISION
+*> The sine of the rotation.
+*> \endverbatim
+*
+* Authors:
+* ========
+*
+*> \author Univ. of Tennessee
+*> \author Univ. of California Berkeley
+*> \author Univ. of Colorado Denver
+*> \author NAG Ltd.
*
-* -- LAPACK routine (version 3.3.0) --
+*> \ingroup auxOTHERcomputational
*
-* -- Contributed by Brian Sutton of the Randolph-Macon College --
-* -- November 2010
+* =====================================================================
+ SUBROUTINE DLARTGS( X, Y, SIGMA, CS, SN )
*
+* -- LAPACK computational routine --
* -- LAPACK is a software package provided by Univ. of Tennessee, --
-* -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
+* -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
*
* .. Scalar Arguments ..
DOUBLE PRECISION CS, SIGMA, SN, X, Y
* ..
*
-* Purpose
-* =======
-*
-* DLARTGS generates a plane rotation designed to introduce a bulge in
-* Golub-Reinsch-style implicit QR iteration for the bidiagonal SVD
-* problem. X and Y are the top-row entries, and SIGMA is the shift.
-* The computed CS and SN define a plane rotation satisfying
-*
-* [ CS SN ] . [ X^2 - SIGMA ] = [ R ],
-* [ -SN CS ] [ X * Y ] [ 0 ]
-*
-* with R nonnegative. If X^2 - SIGMA and X * Y are 0, then the
-* rotation is by PI/2.
-*
-* Arguments
-* =========
-*
-* X (input) DOUBLE PRECISION
-* The (1,1) entry of an upper bidiagonal matrix.
-*
-* Y (input) DOUBLE PRECISION
-* The (1,2) entry of an upper bidiagonal matrix.
-*
-* SIGMA (input) DOUBLE PRECISION
-* The shift.
-*
-* CS (output) DOUBLE PRECISION
-* The cosine of the rotation.
-*
-* SN (output) DOUBLE PRECISION
-* The sine of the rotation.
-*
* ===================================================================
*
* .. Parameters ..
@@ -54,6 +105,9 @@
* .. Local Scalars ..
DOUBLE PRECISION R, S, THRESH, W, Z
* ..
+* .. External Subroutines ..
+ EXTERNAL DLARTGP
+* ..
* .. External Functions ..
DOUBLE PRECISION DLAMCH
EXTERNAL DLAMCH
@@ -61,7 +115,7 @@
*
THRESH = DLAMCH('E')
*
-* Compute the first column of B'*B - SIGMA^2*I, up to a scale
+* Compute the first column of B**T*B - SIGMA^2*I, up to a scale
* factor.
*
IF( (SIGMA .EQ. ZERO .AND. ABS(X) .LT. THRESH) .OR.