From 7fe9b3aa96ad6c5a54d4c260cb7597ee448f73a7 Mon Sep 17 00:00:00 2001 From: Federico Perini Date: Fri, 12 Apr 2024 15:39:30 +0200 Subject: [PATCH] cleanup `rotmg`, `rotm` documentation rotmg rotm fix MathJax --- src/stdlib_linalg_blas.fypp | 47 ++++++++++++++++----------------- src/stdlib_linalg_blas_d.fypp | 49 +++++++++++++++++------------------ src/stdlib_linalg_blas_q.fypp | 47 ++++++++++++++++----------------- src/stdlib_linalg_blas_s.fypp | 47 ++++++++++++++++----------------- 4 files changed, 93 insertions(+), 97 deletions(-) diff --git a/src/stdlib_linalg_blas.fypp b/src/stdlib_linalg_blas.fypp index 0bec4e6d3..e1bd5b76e 100644 --- a/src/stdlib_linalg_blas.fypp +++ b/src/stdlib_linalg_blas.fypp @@ -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 @@ -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 diff --git a/src/stdlib_linalg_blas_d.fypp b/src/stdlib_linalg_blas_d.fypp index 13942ba09..463dfd954 100644 --- a/src/stdlib_linalg_blas_d.fypp +++ b/src/stdlib_linalg_blas_d.fypp @@ -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..-- @@ -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..-- diff --git a/src/stdlib_linalg_blas_q.fypp b/src/stdlib_linalg_blas_q.fypp index 647636ef0..bf8dd91d0 100644 --- a/src/stdlib_linalg_blas_q.fypp +++ b/src/stdlib_linalg_blas_q.fypp @@ -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..-- @@ -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..-- diff --git a/src/stdlib_linalg_blas_s.fypp b/src/stdlib_linalg_blas_s.fypp index 9270500b1..f595a01d7 100644 --- a/src/stdlib_linalg_blas_s.fypp +++ b/src/stdlib_linalg_blas_s.fypp @@ -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..-- @@ -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..--