Skip to content

Commit

Permalink
Improve rotm, rotmg documentation (#795)
Browse files Browse the repository at this point in the history
  • Loading branch information
@perazz
perazz authored Apr 12, 2024
2 parents c673e3b + 7fe9b3a commit c26253a
Show file tree
Hide file tree
Showing 4 changed files with 93 additions and 97 deletions.
47 changes: 23 additions & 24 deletions src/stdlib_linalg_blas.fypp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1019,17 +1019,17 @@ module stdlib_linalg_blas
interface rotm
!! APPLY THE MODIFIED GIVENS TRANSFORMATION, H, TO THE 2 BY N MATRIX
!! (DX**T) , WHERE **T INDICATES TRANSPOSE. THE ELEMENTS OF DX ARE IN
!! (DY**T)
!! DX(LX+I*INCX), I = 0 TO N-1, WHERE LX = 1 IF INCX >= 0, ELSE
!! LX = (-INCX)*N, AND SIMILARLY FOR SY USING LY AND INCY.
!! WITH DPARAM(1)=DFLAG, H HAS ONE OF THE FOLLOWING FORMS..
!! DFLAG=-1._dp DFLAG=0._dp DFLAG=1._dp DFLAG=-2.D0
!! (DH11 DH12) (1._dp DH12) (DH11 1._dp) (1._dp 0._dp)
!! H=( ) ( ) ( ) ( )
!! (DH21 DH22), (DH21 1._dp), (-1._dp DH22), (0._dp 1._dp).
!! SEE ROTMG FOR A DESCRIPTION OF DATA STORAGE IN DPARAM.
!! ROTM applies the modified Givens transformation, \(H\), to the 2-by-N matrix
!! $$ \left[ \begin{array}{c}DX^T\\DY^T\\ \end{array} \right], $$
!! where \(^T\) indicates transpose. The elements of \(DX\) are in
!! DX(LX+I*INCX), I = 0:N-1, where LX = 1 if INCX >= 0, else LX = (-INCX)*N,
!! and similarly for DY using LY and INCY.
!! With DPARAM(1)=DFLAG, \(H\) has one of the following forms:
!! $$ H=\underbrace{\begin{bmatrix}DH_{11} & DH_{12}\\DH_{21} & DH_{22}\end{bmatrix}}_{DFLAG=-1},
!! \underbrace{\begin{bmatrix}1 & DH_{12}\\DH_{21} & 1\end{bmatrix}}_{DFLAG=0},
!! \underbrace{\begin{bmatrix}DH_{11} & 1\\-1 & DH_{22}\end{bmatrix}}_{DFLAG=1},
!! \underbrace{\begin{bmatrix}1 & 0\\0 & 1\end{bmatrix}}_{DFLAG=-2}. $$
!! See ROTMG for a description of data storage in DPARAM.
#ifdef STDLIB_EXTERNAL_BLAS
pure subroutine drotm(n,dx,incx,dy,incy,dparam)
import sp,dp,qp,ilp,lk
Expand Down Expand Up @@ -1060,19 +1060,18 @@ module stdlib_linalg_blas
interface rotmg
!! CONSTRUCT THE MODIFIED GIVENS TRANSFORMATION MATRIX H WHICH ZEROS
!! THE SECOND COMPONENT OF THE 2-VECTOR (SQRT(DD1)*DX1,SQRT(DD2) DY2)**T.
!! WITH DPARAM(1)=DFLAG, H HAS ONE OF THE FOLLOWING FORMS..
!! DFLAG=-1._dp DFLAG=0._dp DFLAG=1._dp DFLAG=-2.D0
!! (DH11 DH12) (1._dp DH12) (DH11 1._dp) (1._dp 0._dp)
!! H=( ) ( ) ( ) ( )
!! (DH21 DH22), (DH21 1._dp), (-1._dp DH22), (0._dp 1._dp).
!! LOCATIONS 2-4 OF DPARAM CONTAIN DH11, DH21, DH12, AND DH22
!! RESPECTIVELY. (VALUES OF 1._dp, -1._dp, OR 0._dp IMPLIED BY THE
!! VALUE OF DPARAM(1) ARE NOT STORED IN DPARAM.)
!! THE VALUES OF GAMSQ AND RGAMSQ SET IN THE DATA STATEMENT MAY BE
!! INEXACT. THIS IS OK AS THEY ARE ONLY USED FOR TESTING THE SIZE
!! OF DD1 AND DD2. ALL ACTUAL SCALING OF DATA IS DONE USING GAM.
!! ROTMG Constructs the modified Givens transformation matrix \(H\) which zeros the
!! second component of the 2-vector
!! $$ \left[ {\sqrt{DD_1}\cdot DX_1,\sqrt{DD_2}\cdot DY_2} \right]^T. $$
!! With DPARAM(1)=DFLAG, \(H\) has one of the following forms:
!! $$ H=\underbrace{\begin{bmatrix}DH_{11} & DH_{12}\\DH_{21} & DH_{22}\end{bmatrix}}_{DFLAG=-1},
!! \underbrace{\begin{bmatrix}1 & DH_{12}\\DH_{21} & 1\end{bmatrix}}_{DFLAG=0},
!! \underbrace{\begin{bmatrix}DH_{11} & 1\\-1 & DH_{22}\end{bmatrix}}_{DFLAG=1},
!! \underbrace{\begin{bmatrix}1 & 0\\0 & 1\end{bmatrix}}_{DFLAG=-2}. $$
!! Locations 2-4 of DPARAM contain DH11, DH21, DH12 and DH22 respectively.
!! (Values of 1.0, -1.0, or 0.0 implied by the value of DPARAM(1) are not stored in DPARAM.)
!! The values of parameters GAMSQ and RGAMSQ may be inexact. This is OK as they are only
!! used for testing the size of DD1 and DD2. All actual scaling of data is done using GAM.
#ifdef STDLIB_EXTERNAL_BLAS
pure subroutine drotmg(dd1,dd2,dx1,dy1,dparam)
import sp,dp,qp,ilp,lk
Expand Down
49 changes: 24 additions & 25 deletions src/stdlib_linalg_blas_d.fypp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1028,18 +1028,18 @@ module stdlib_linalg_blas_d
end subroutine stdlib_drotg
pure subroutine stdlib_drotm(n,dx,incx,dy,incy,dparam)
!! APPLY THE MODIFIED GIVENS TRANSFORMATION, H, TO THE 2 BY N MATRIX
!! (DX**T) , WHERE **T INDICATES TRANSPOSE. THE ELEMENTS OF DX ARE IN
!! (DY**T)
!! DX(LX+I*INCX), I = 0 TO N-1, WHERE LX = 1 IF INCX >= 0, ELSE
!! LX = (-INCX)*N, AND SIMILARLY FOR SY USING LY AND INCY.
!! WITH DPARAM(1)=DFLAG, H HAS ONE OF THE FOLLOWING FORMS..
!! DFLAG=-1._dp DFLAG=0._dp DFLAG=1._dp DFLAG=-2.D0
!! (DH11 DH12) (1._dp DH12) (DH11 1._dp) (1._dp 0._dp)
!! H=( ) ( ) ( ) ( )
!! (DH21 DH22), (DH21 1._dp), (-1._dp DH22), (0._dp 1._dp).
!! SEE DROTMG FOR A DESCRIPTION OF DATA STORAGE IN DPARAM.
pure subroutine stdlib_drotm(n,dx,incx,dy,incy,dparam)
!! DROTM applies the modified Givens transformation, \(H\), to the 2-by-N matrix
!! $$ \left[ \begin{array}{c}DX^T\\DY^T\\ \end{array} \right], $$
!! where \(^T\) indicates transpose. The elements of \(DX\) are in
!! DX(LX+I*INCX), I = 0:N-1, where LX = 1 if INCX >= 0, else LX = (-INCX)*N,
!! and similarly for DY using LY and INCY.
!! With DPARAM(1)=DFLAG, \(H\) has one of the following forms:
!! $$ H=\underbrace{\begin{bmatrix}DH_{11} & DH_{12}\\DH_{21} & DH_{22}\end{bmatrix}}_{DFLAG=-1},
!! \underbrace{\begin{bmatrix}1 & DH_{12}\\DH_{21} & 1\end{bmatrix}}_{DFLAG=0},
!! \underbrace{\begin{bmatrix}DH_{11} & 1\\-1 & DH_{22}\end{bmatrix}}_{DFLAG=1},
!! \underbrace{\begin{bmatrix}1 & 0\\0 & 1\end{bmatrix}}_{DFLAG=-2}. $$
!! See DROTMG for a description of data storage in DPARAM.
! -- reference blas level1 routine --
! -- reference blas is a software package provided by univ. of tennessee, --
! -- univ. of california berkeley, univ. of colorado denver and nag ltd..--
Expand Down Expand Up @@ -1136,19 +1136,18 @@ module stdlib_linalg_blas_d
pure subroutine stdlib_drotmg(dd1,dd2,dx1,dy1,dparam)
!! CONSTRUCT THE MODIFIED GIVENS TRANSFORMATION MATRIX H WHICH ZEROS
!! THE SECOND COMPONENT OF THE 2-VECTOR (SQRT(DD1)*DX1,SQRT(DD2) DY2)**T.
!! WITH DPARAM(1)=DFLAG, H HAS ONE OF THE FOLLOWING FORMS..
!! DFLAG=-1._dp DFLAG=0._dp DFLAG=1._dp DFLAG=-2.D0
!! (DH11 DH12) (1._dp DH12) (DH11 1._dp) (1._dp 0._dp)
!! H=( ) ( ) ( ) ( )
!! (DH21 DH22), (DH21 1._dp), (-1._dp DH22), (0._dp 1._dp).
!! LOCATIONS 2-4 OF DPARAM CONTAIN DH11, DH21, DH12, AND DH22
!! RESPECTIVELY. (VALUES OF 1._dp, -1._dp, OR 0._dp IMPLIED BY THE
!! VALUE OF DPARAM(1) ARE NOT STORED IN DPARAM.)
!! THE VALUES OF GAMSQ AND RGAMSQ SET IN THE DATA STATEMENT MAY BE
!! INEXACT. THIS IS OK AS THEY ARE ONLY USED FOR TESTING THE SIZE
!! OF DD1 AND DD2. ALL ACTUAL SCALING OF DATA IS DONE USING GAM.
!! DROTMG Constructs the modified Givens transformation matrix \(H\) which zeros the
!! second component of the 2-vector
!! $$ \left[ {\sqrt{DD_1}\cdot DX_1,\sqrt{DD_2}\cdot DY_2} \right]^T. $$
!! With DPARAM(1)=DFLAG, \(H\) has one of the following forms:
!! $$ H=\underbrace{\begin{bmatrix}DH_{11} & DH_{12}\\DH_{21} & DH_{22}\end{bmatrix}}_{DFLAG=-1},
!! \underbrace{\begin{bmatrix}1 & DH_{12}\\DH_{21} & 1\end{bmatrix}}_{DFLAG=0},
!! \underbrace{\begin{bmatrix}DH_{11} & 1\\-1 & DH_{22}\end{bmatrix}}_{DFLAG=1},
!! \underbrace{\begin{bmatrix}1 & 0\\0 & 1\end{bmatrix}}_{DFLAG=-2}. $$
!! Locations 2-4 of DPARAM contain DH11, DH21, DH12 and DH22 respectively.
!! (Values of 1.0, -1.0, or 0.0 implied by the value of DPARAM(1) are not stored in DPARAM.)
!! The values of parameters GAMSQ and RGAMSQ may be inexact. This is OK as they are only
!! used for testing the size of DD1 and DD2. All actual scaling of data is done using GAM.
! -- reference blas level1 routine --
! -- reference blas is a software package provided by univ. of tennessee, --
! -- univ. of california berkeley, univ. of colorado denver and nag ltd..--
Expand Down
47 changes: 23 additions & 24 deletions src/stdlib_linalg_blas_q.fypp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1032,17 +1032,17 @@ module stdlib_linalg_blas_q
pure subroutine stdlib_qrotm(n,dx,incx,dy,incy,dparam)
!! APPLY THE MODIFIED GIVENS TRANSFORMATION, H, TO THE 2 BY N MATRIX
!! (DX**T) , WHERE **T INDICATES TRANSPOSE. THE ELEMENTS OF DX ARE IN
!! (DY**T)
!! DX(LX+I*INCX), I = 0 TO N-1, WHERE LX = 1 IF INCX >= 0, ELSE
!! LX = (-INCX)*N, AND SIMILARLY FOR SY USING LY AND INCY.
!! WITH DPARAM(1)=DFLAG, H HAS ONE OF THE FOLLOWING FORMS..
!! DFLAG=-1._qp DFLAG=0._qp DFLAG=1._qp DFLAG=-2.D0
!! (DH11 DH12) (1._qp DH12) (DH11 1._qp) (1._qp 0._qp)
!! H=( ) ( ) ( ) ( )
!! (DH21 DH22), (DH21 1._qp), (-1._qp DH22), (0._qp 1._qp).
!! SEE DROTMG FOR A DESCRIPTION OF DATA STORAGE IN DPARAM.
!! QROTM applies the modified Givens transformation, \(H\), to the 2-by-N matrix
!! $$ \left[ \begin{array}{c}DX^T\\DY^T\\ \end{array} \right], $$
!! where \(^T\) indicates transpose. The elements of \(DX\) are in
!! DX(LX+I*INCX), I = 0:N-1, where LX = 1 if INCX >= 0, else LX = (-INCX)*N,
!! and similarly for DY using LY and INCY.
!! With DPARAM(1)=DFLAG, \(H\) has one of the following forms:
!! $$ H=\underbrace{\begin{bmatrix}DH_{11} & DH_{12}\\DH_{21} & DH_{22}\end{bmatrix}}_{DFLAG=-1},
!! \underbrace{\begin{bmatrix}1 & DH_{12}\\DH_{21} & 1\end{bmatrix}}_{DFLAG=0},
!! \underbrace{\begin{bmatrix}DH_{11} & 1\\-1 & DH_{22}\end{bmatrix}}_{DFLAG=1},
!! \underbrace{\begin{bmatrix}1 & 0\\0 & 1\end{bmatrix}}_{DFLAG=-2}. $$
!! See QROTMG for a description of data storage in DPARAM.
! -- reference blas level1 routine --
! -- reference blas is a software package provided by univ. of tennessee, --
! -- univ. of california berkeley, univ. of colorado denver and nag ltd..--
Expand Down Expand Up @@ -1139,19 +1139,18 @@ module stdlib_linalg_blas_q
pure subroutine stdlib_qrotmg(dd1,dd2,dx1,dy1,dparam)
!! CONSTRUCT THE MODIFIED GIVENS TRANSFORMATION MATRIX H WHICH ZEROS
!! THE SECOND COMPONENT OF THE 2-VECTOR (SQRT(DD1)*DX1,SQRT(DD2) DY2)**T.
!! WITH DPARAM(1)=DFLAG, H HAS ONE OF THE FOLLOWING FORMS..
!! DFLAG=-1._qp DFLAG=0._qp DFLAG=1._qp DFLAG=-2.D0
!! (DH11 DH12) (1._qp DH12) (DH11 1._qp) (1._qp 0._qp)
!! H=( ) ( ) ( ) ( )
!! (DH21 DH22), (DH21 1._qp), (-1._qp DH22), (0._qp 1._qp).
!! LOCATIONS 2-4 OF DPARAM CONTAIN DH11, DH21, DH12, AND DH22
!! RESPECTIVELY. (VALUES OF 1._qp, -1._qp, OR 0._qp IMPLIED BY THE
!! VALUE OF DPARAM(1) ARE NOT STORED IN DPARAM.)
!! THE VALUES OF GAMSQ AND RGAMSQ SET IN THE DATA STATEMENT MAY BE
!! INEXACT. THIS IS OK AS THEY ARE ONLY USED FOR TESTING THE SIZE
!! OF DD1 AND DD2. ALL ACTUAL SCALING OF DATA IS DONE USING GAM.
!! QROTMG Constructs the modified Givens transformation matrix \(H\) which zeros the
!! second component of the 2-vector
!! $$ \left[ {\sqrt{DD_1}\cdot DX_1,\sqrt{DD_2}\cdot DY_2} \right]^T. $$
!! With DPARAM(1)=DFLAG, \(H\) has one of the following forms:
!! $$ H=\underbrace{\begin{bmatrix}DH_{11} & DH_{12}\\DH_{21} & DH_{22}\end{bmatrix}}_{DFLAG=-1},
!! \underbrace{\begin{bmatrix}1 & DH_{12}\\DH_{21} & 1\end{bmatrix}}_{DFLAG=0},
!! \underbrace{\begin{bmatrix}DH_{11} & 1\\-1 & DH_{22}\end{bmatrix}}_{DFLAG=1},
!! \underbrace{\begin{bmatrix}1 & 0\\0 & 1\end{bmatrix}}_{DFLAG=-2}. $$
!! Locations 2-4 of DPARAM contain DH11, DH21, DH12 and DH22 respectively.
!! (Values of 1.0, -1.0, or 0.0 implied by the value of DPARAM(1) are not stored in DPARAM.)
!! The values of parameters GAMSQ and RGAMSQ may be inexact. This is OK as they are only
!! used for testing the size of DD1 and DD2. All actual scaling of data is done using GAM.
! -- reference blas level1 routine --
! -- reference blas is a software package provided by univ. of tennessee, --
! -- univ. of california berkeley, univ. of colorado denver and nag ltd..--
Expand Down
47 changes: 23 additions & 24 deletions src/stdlib_linalg_blas_s.fypp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1209,17 +1209,17 @@ module stdlib_linalg_blas_s
pure subroutine stdlib_srotm(n,sx,incx,sy,incy,sparam)
!! APPLY THE MODIFIED GIVENS TRANSFORMATION, H, TO THE 2 BY N MATRIX
!! (SX**T) , WHERE **T INDICATES TRANSPOSE. THE ELEMENTS OF SX ARE IN
!! (SX**T)
!! SX(LX+I*INCX), I = 0 TO N-1, WHERE LX = 1 IF INCX >= 0, ELSE
!! LX = (-INCX)*N, AND SIMILARLY FOR SY USING USING LY AND INCY.
!! WITH SPARAM(1)=SFLAG, H HAS ONE OF THE FOLLOWING FORMS..
!! SFLAG=-1._sp SFLAG=0._sp SFLAG=1._sp SFLAG=-2.E0
!! (SH11 SH12) (1._sp SH12) (SH11 1._sp) (1._sp 0._sp)
!! H=( ) ( ) ( ) ( )
!! (SH21 SH22), (SH21 1._sp), (-1._sp SH22), (0._sp 1._sp).
!! SEE SROTMG FOR A DESCRIPTION OF DATA STORAGE IN SPARAM.
!! SROTM applies the modified Givens transformation, \(H\), to the 2-by-N matrix
!! $$ \left[ \begin{array}{c}SX^T\\SY^T\\ \end{array} \right], $$
!! where \(^T\) indicates transpose. The elements of \(SX\) are in
!! SX(LX+I*INCX), I = 0:N-1, where LX = 1 if INCX >= 0, else LX = (-INCX)*N,
!! and similarly for SY using LY and INCY.
!! With SPARAM(1)=SFLAG, \(H\) has one of the following forms:
!! $$ H=\underbrace{\begin{bmatrix}SH_{11} & SH_{12}\\SH_{21} & SH_{22}\end{bmatrix}}_{SFLAG=-1},
!! \underbrace{\begin{bmatrix}1 & SH_{12}\\SH_{21} & 1\end{bmatrix}}_{SFLAG=0},
!! \underbrace{\begin{bmatrix}SH_{11} & 1\\-1 & SH_{22}\end{bmatrix}}_{SFLAG=1},
!! \underbrace{\begin{bmatrix}1 & 0\\0 & 1\end{bmatrix}}_{SFLAG=-2}. $$
!! See SROTMG for a description of data storage in SPARAM.
! -- reference blas level1 routine --
! -- reference blas is a software package provided by univ. of tennessee, --
! -- univ. of california berkeley, univ. of colorado denver and nag ltd..--
Expand Down Expand Up @@ -1316,19 +1316,18 @@ module stdlib_linalg_blas_s
pure subroutine stdlib_srotmg(sd1,sd2,sx1,sy1,sparam)
!! CONSTRUCT THE MODIFIED GIVENS TRANSFORMATION MATRIX H WHICH ZEROS
!! THE SECOND COMPONENT OF THE 2-VECTOR (SQRT(SD1)*SX1,SQRT(SD2) SY2)**T.
!! WITH SPARAM(1)=SFLAG, H HAS ONE OF THE FOLLOWING FORMS..
!! SFLAG=-1._sp SFLAG=0._sp SFLAG=1._sp SFLAG=-2.E0
!! (SH11 SH12) (1._sp SH12) (SH11 1._sp) (1._sp 0._sp)
!! H=( ) ( ) ( ) ( )
!! (SH21 SH22), (SH21 1._sp), (-1._sp SH22), (0._sp 1._sp).
!! LOCATIONS 2-4 OF SPARAM CONTAIN SH11,SH21,SH12, AND SH22
!! RESPECTIVELY. (VALUES OF 1._sp, -1._sp, OR 0._sp IMPLIED BY THE
!! VALUE OF SPARAM(1) ARE NOT STORED IN SPARAM.)
!! THE VALUES OF GAMSQ AND RGAMSQ SET IN THE DATA STATEMENT MAY BE
!! INEXACT. THIS IS OK AS THEY ARE ONLY USED FOR TESTING THE SIZE
!! OF SD1 AND SD2. ALL ACTUAL SCALING OF DATA IS DONE USING GAM.
!! SROTMG Constructs the modified Givens transformation matrix \(H\) which zeros the
!! second component of the 2-vector
!! $$ \left[ {\sqrt{SD_1}\cdot SX_1,\sqrt{SD_2}\cdot SY_2} \right]^T. $$
!! With SPARAM(1)=SFLAG, \(H\) has one of the following forms:
!! $$ H=\underbrace{\begin{bmatrix}SH_{11} & SD_{12}\\SH_{21} & SH_{22}\end{bmatrix}}_{SFLAG=-1},
!! \underbrace{\begin{bmatrix}1 & SH_{12}\\SH_{21} & 1\end{bmatrix}}_{SFLAG=0},
!! \underbrace{\begin{bmatrix}SH_{11} & 1\\-1 & SH_{22}\end{bmatrix}}_{SFLAG=1},
!! \underbrace{\begin{bmatrix}1 & 0\\0 & 1\end{bmatrix}}_{SFLAG=2}. $$
!! Locations 2-4 of SPARAM contain SH11, SH21, SH12 and SH22 respectively.
!! (Values of 1.0, -1.0, or 0.0 implied by the value of SPARAM(1) are not stored in SPARAM.)
!! The values of parameters GAMSQ and RGAMSQ may be inexact. This is OK as they are only
!! used for testing the size of DD1 and DD2. All actual scaling of data is done using GAM.
! -- reference blas level1 routine --
! -- reference blas is a software package provided by univ. of tennessee, --
! -- univ. of california berkeley, univ. of colorado denver and nag ltd..--
Expand Down

0 comments on commit c26253a

Please sign in to comment.