more doxygen

.github/workflows/developer.yml

@@ -39,6 +39,12 @@ jobs:
         cmake -DOPENMP=ON -DCMAKE_PREFIX_PATH="~/" -DENABLE_DOCS=ON -DCMAKE_Fortran_FLAGS="-g -fprofile-arcs -ftest-coverage -O0 -fsanitize=address" -DCMAKE_BUILD_TYPE=Debug ..
         make -j2 VERBOSE=1
 
+    - uses: actions/upload-artifact@v2
+      with:
+        name: docs
+        path: |
+          sp/build/docs/html
+
     - name: test-sp
       run: |
         cd sp/build

src/fftpack.F

@@ -1,5 +1,15 @@
 C> @file
-C> @brief fftpack.
+C> @brief A concatination of the (FFTPACK)[https://netlib.org/fftpack/] library code.
+C>      
+C> FFTPACK is a package of Fortran subprograms for the fast Fourier
+C> transform of periodic and other symmetric sequences. It includes
+C> complex, real, sine, cosine, and quarter-wave transforms.
+C>      
+C>Reference:
+C>- P.N. Swarztrauber, Vectorizing the FFTs, in Parallel Computations
+C>(G. Rodrigue, ed.), Academic Press, 1982, pp. 51--83.
+C> 
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
 
 C> dcrft
 C>
@@ -18,6 +28,7 @@
 C> @param n2
 C> @param z
 C> @param nz
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE dcrft(init,x,ldx,y,ldy,n,m,isign,scale,
      &                 table,n1,wrk,n2,z,nz)
 
@@ -61,6 +72,9 @@ SUBROUTINE dcrft(init,x,ldx,y,ldy,n,m,isign,scale,
 C> @param n2
 C> @param z
 C> @param nz
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
+
       SUBROUTINE scrft(init,x,ldx,y,ldy,n,m,isign,scale,
      &                 table,n1,wrk,n2,z,nz)
 
@@ -97,6 +111,8 @@ SUBROUTINE scrft(init,x,ldx,y,ldy,n,m,isign,scale,
 C> @param table
 C> @param work
 C> @param isys
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE csfft(isign,n,scale,x,y,table,work,isys)
 
       implicit none
@@ -137,6 +153,8 @@ SUBROUTINE csfft(isign,n,scale,x,y,table,work,isys)
 C> @param n2
 C> @param z
 C> @param nz
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE drcft(init,x,ldx,y,ldy,n,m,isign,scale,
      &                 table,n1,wrk,n2,z,nz)
 
@@ -184,6 +202,8 @@ SUBROUTINE drcft(init,x,ldx,y,ldy,n,m,isign,scale,
 C> @param n2
 C> @param z
 C> @param nz
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE srcft(init,x,ldx,y,ldy,n,m,isign,scale,
      &                 table,n1,wrk,n2,z,nz)
 
@@ -224,6 +244,8 @@ SUBROUTINE srcft(init,x,ldx,y,ldy,n,m,isign,scale,
 C> @param table
 C> @param work
 C> @param isys
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE scfft(isign,n,scale,x,y,table,work,isys)
 
       implicit none
@@ -255,6 +277,8 @@ SUBROUTINE scfft(isign,n,scale,x,y,table,work,isys)
 C> @param N
 C> @param R
 C> @param WSAVE
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RFFTF (N,R,WSAVE)
       DIMENSION       R(1)       ,WSAVE(1)
       IF (N .EQ. 1) RETURN
@@ -267,6 +291,8 @@ SUBROUTINE RFFTF (N,R,WSAVE)
 C> @param N
 C> @param R
 C> @param WSAVE
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RFFTB (N,R,WSAVE)
       DIMENSION       R(1)       ,WSAVE(1)
       IF (N .EQ. 1) RETURN
@@ -278,6 +304,8 @@ SUBROUTINE RFFTB (N,R,WSAVE)
 C>      
 C> @param N
 C> @param WSAVE
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RFFTI (N,WSAVE)
       DIMENSION       WSAVE(1)
       IF (N .EQ. 1) RETURN
@@ -292,6 +320,8 @@ SUBROUTINE RFFTI (N,WSAVE)
 C> @param CH
 C> @param WA
 C> @param IFAC
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RFFTB1 (N,C,CH,WA,IFAC)
       DIMENSION       CH(1)      ,C(1)       ,WA(1)      ,IFAC(*)
       NF = IFAC(2)
@@ -359,6 +389,8 @@ SUBROUTINE RFFTB1 (N,C,CH,WA,IFAC)
 C> @param CH
 C> @param WA
 C> @param IFAC
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RFFTF1 (N,C,CH,WA,IFAC)
       DIMENSION       CH(1)      ,C(1)       ,WA(1)      ,IFAC(*)
       NF = IFAC(2)
@@ -424,6 +456,8 @@ SUBROUTINE RFFTF1 (N,C,CH,WA,IFAC)
 C> @param N
 C> @param WA
 C> @param IFAC
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RFFTI1 (N,WA,IFAC)
       DIMENSION       WA(1)      ,IFAC(*)    ,NTRYH(4)
       DATA NTRYH(1),NTRYH(2),NTRYH(3),NTRYH(4)/4,2,3,5/
@@ -491,6 +525,8 @@ SUBROUTINE RFFTI1 (N,WA,IFAC)
 C> @param CC
 C> @param CH
 C> @param WA1
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RADB2 (IDO,L1,CC,CH,WA1)
       DIMENSION       CC(IDO,2,L1)           ,CH(IDO,L1,2)           ,
      1                WA1(1)
@@ -528,6 +564,8 @@ SUBROUTINE RADB2 (IDO,L1,CC,CH,WA1)
 C> @param CH
 C> @param WA1
 C> @param WA2
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RADB3 (IDO,L1,CC,CH,WA1,WA2)
       DIMENSION       CC(IDO,3,L1)           ,CH(IDO,L1,3)           ,
      1                WA1(1)     ,WA2(1)
@@ -576,6 +614,8 @@ SUBROUTINE RADB3 (IDO,L1,CC,CH,WA1,WA2)
 C> @param WA1
 C> @param WA2
 C> @param WA3
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RADB4 (IDO,L1,CC,CH,WA1,WA2,WA3)
       DIMENSION       CC(IDO,4,L1)           ,CH(IDO,L1,4)           ,
      1                WA1(1)     ,WA2(1)     ,WA3(1)
@@ -645,6 +685,8 @@ SUBROUTINE RADB4 (IDO,L1,CC,CH,WA1,WA2,WA3)
 C> @param WA2
 C> @param WA3
 C> @param WA4
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RADB5 (IDO,L1,CC,CH,WA1,WA2,WA3,WA4)
       DIMENSION       CC(IDO,5,L1)           ,CH(IDO,L1,5)           ,
      1                WA1(1)     ,WA2(1)     ,WA3(1)     ,WA4(1)
@@ -721,6 +763,8 @@ SUBROUTINE RADB5 (IDO,L1,CC,CH,WA1,WA2,WA3,WA4)
 C> @param CH
 C> @param CH2
 C> @param WA
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RADBG (IDO,IP,L1,IDL1,CC,C1,C2,CH,CH2,WA)
       DIMENSION       CH(IDO,L1,IP)          ,CC(IDO,IP,L1)          ,
      1                C1(IDO,L1,IP)          ,C2(IDL1,IP),
@@ -897,6 +941,8 @@ SUBROUTINE RADBG (IDO,IP,L1,IDL1,CC,C1,C2,CH,CH2,WA)
 C> @param CC
 C> @param CH
 C> @param WA1
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RADF2 (IDO,L1,CC,CH,WA1)
       DIMENSION       CH(IDO,2,L1)           ,CC(IDO,L1,2)           ,
      1                WA1(1)
@@ -933,6 +979,8 @@ SUBROUTINE RADF2 (IDO,L1,CC,CH,WA1)
 C> @param CH
 C> @param WA1
 C> @param WA2
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RADF3 (IDO,L1,CC,CH,WA1,WA2)
       DIMENSION       CH(IDO,3,L1)           ,CC(IDO,L1,3)           ,
      1                WA1(1)     ,WA2(1)
@@ -978,6 +1026,8 @@ SUBROUTINE RADF3 (IDO,L1,CC,CH,WA1,WA2)
 C> @param WA1
 C> @param WA2
 C> @param WA3
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RADF4 (IDO,L1,CC,CH,WA1,WA2,WA3)
       DIMENSION       CC(IDO,L1,4)           ,CH(IDO,4,L1)           ,
      1                WA1(1)     ,WA2(1)     ,WA3(1)
@@ -1043,6 +1093,8 @@ SUBROUTINE RADF4 (IDO,L1,CC,CH,WA1,WA2,WA3)
 C> @param WA2
 C> @param WA3
 C> @param WA4
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RADF5 (IDO,L1,CC,CH,WA1,WA2,WA3,WA4)
       DIMENSION       CC(IDO,L1,5)           ,CH(IDO,5,L1)           ,
      1                WA1(1)     ,WA2(1)     ,WA3(1)     ,WA4(1)
@@ -1115,6 +1167,8 @@ SUBROUTINE RADF5 (IDO,L1,CC,CH,WA1,WA2,WA3,WA4)
 C> @param CH
 C> @param CH2
 C> @param WA
+C>
+C> @author Paul N. Swarztrauber, National Center for Atmospheric Research, Boulder, CO
       SUBROUTINE RADFG (IDO,IP,L1,IDL1,CC,C1,C2,CH,CH2,WA)
       DIMENSION       CH(IDO,L1,IP)          ,CC(IDO,IP,L1)          ,
      1                C1(IDO,L1,IP)          ,C2(IDL1,IP),

src/spanaly.f

@@ -1,5 +1,5 @@
 C> @file
-C> Analyze spectral from fourier
+C> @brief Analyze spectral from Fourier.
 C>
 C> ### Program History Log
 C> Date | Programmer | Comments
@@ -10,25 +10,26 @@
 C>
 C> @author IREDELL @date 91-10-31
 
-C> Analyzes spectral coefficients from fourier coefficients
-C> for a latitude pair (northern and southern hemispheres).
+C> Analyzes spectral coefficients from Fourier coefficients
+C> for a latitude pair (Northern and Southern hemispheres).
+C>
 C> Vector components are multiplied by cosine of latitude.
 C>
-C> @param I SPECTRAL DOMAIN SHAPE (0 FOR TRIANGULAR, 1 FOR RHOMBOIDAL)
-C> @param M  SPECTRAL TRUNCATION
-C> @param IM EVEN NUMBER OF FOURIER COEFFICIENTS
-C> @param IX DIMENSION OF FOURIER COEFFICIENTS (IX>=IM+2)
-C> @param NC DIMENSION OF SPECTRAL COEFFICIENTS (NC>=(M+1)*((I+1)*M+2))
-C> @param NCTOP  DIMENSION OF SPECTRAL COEFFICIENTS OVER TOP (NCTOP>=2*(M+1))
-C> @param KM NUMBER OF FIELDS
-C> @param WGT GAUSSIAN WEIGHT
-C> @param CLAT COSINE OF LATITUDE
-C> @param PLN ((M+1)*((I+1)*M+2)/2) LEGENDRE POLYNOMIALS
-C> @param PLNTOP (M+1) LEGENDRE POLYNOMIAL OVER TOP
-C> @param MP (KM) IDENTIFIERS (0 FOR SCALAR, 1 FOR VECTOR)
-C> @param F (IX,2,KM) FOURIER COEFFICIENTS COMBINED
-C> @param SPC (NC,KM) SPECTRAL COEFFICIENTS
-C> @param SPCTOP (NCTOP,KM) SPECTRAL COEFFICIENTS OVER TOP
+C> @param I spectral domain shape (0 for triangular, 1 for rhomboidal)
+C> @param M  spectral truncation
+C> @param IM even number of Fourier coefficients
+C> @param IX dimension of Fourier coefficients (IX>=IM+2)
+C> @param NC dimension of spectral coefficients (NC>=(M+1)*((I+1)*M+2))
+C> @param NCTOP dimension of spectral coefficients over top (NCTOP>=2*(M+1))
+C> @param KM number of fields
+C> @param WGT Gaussian weight
+C> @param CLAT cosine of latitude
+C> @param PLN Legendre polynomials
+C> @param PLNTOP Legendre polynomial over top
+C> @param MP identifiers (0 for scalar, 1 for vector)
+C> @param F Fourier coefficients combined
+C> @param SPC spectral coefficients
+C> @param SPCTOP spectral coefficients over top
 C>
 C> @author IREDELL @date 91-10-31
       SUBROUTINE SPANALY(I,M,IM,IX,NC,NCTOP,KM,WGT,CLAT,PLN,PLNTOP,MP,

src/spfft.f

@@ -1,44 +1,42 @@
 C> @file
-C>
-C> Perform multiple fast fourier transforms.
-C> @author IREDELL ORG: W/NMC23 @date 96-02-20
+C> @brief Perform multiple fast fourier transforms.
+C> @author IREDELL @date 96-02-20
 
 C> This subprogram performs multiple fast fourier transforms
 C> between complex amplitudes in fourier space and real values
 C> in cyclic physical space.
+C>
 C> Subprogram spfft must be invoked first with idir=0
 C> to initialize trigonemetric data. Use subprogram spfft1
 C> to perform an fft without previous initialization.
 C> This version invokes the ibm essl fft.
 C>
-C>   the restrictions on imax are that it must be a multiple
-C>   of 1 to 25 factors of two, up to 2 factors of three,
-C>   and up to 1 factor of five, seven and eleven.
+C> The restrictions on imax are that it must be a multiple
+C> of 1 to 25 factors of two, up to 2 factors of three,
+C> and up to 1 factor of five, seven and eleven.
 C>
-C>   If IDIR=0, then W and G need not contain any valid data.
-C>   the other parameters must be supplied and cannot change
-C>   in succeeding calls until the next time it is called with IDIR=0.
+C> If IDIR=0, then W and G need not contain any valid data.
+C> the other parameters must be supplied and cannot change
+C> in succeeding calls until the next time it is called with IDIR=0.
 C>
-C>   This subprogram is not thread-safe when IDIR=0. On the other hand,
-C>   when IDIR is not zero, it can be called from a threaded region.
+C> This subprogram is not thread-safe when IDIR=0. On the other hand,
+C> when IDIR is not zero, it can be called from a threaded region.
 C>
-C> @param IMAX     - INTEGER NUMBER OF VALUES IN THE CYCLIC PHYSICAL SPACE
-C>                (SEE LIMITATIONS ON IMAX IN REMARKS BELOW.)
-C> @param INCW     - INTEGER FIRST DIMENSION OF THE COMPLEX AMPLITUDE ARRAY
-C>                (INCW >= IMAX/2+1)
-C> @param INCG     - INTEGER FIRST DIMENSION OF THE REAL VALUE ARRAY
-C>                (INCG >= IMAX)
-C> @param KMAX     - INTEGER NUMBER OF TRANSFORMS TO PERFORM
-C> @param[out] W   - COMPLEX(INCW,KMAX) COMPLEX AMPLITUDES IF IDIR>0
-C> @param[out] G   - REAL(INCG,KMAX) REAL VALUES IF IDIR<0
-C> @param IDIR     - INTEGER DIRECTION FLAG
-C>                IDIR=0 TO INITIALIZE INTERNAL TRIGONOMETRIC DATA
-C>                IDIR>0 TO TRANSFORM FROM FOURIER TO PHYSICAL SPACE
-C>                IDIR<0 TO TRANSFORM FROM PHYSICAL TO FOURIER SPACE
+C> @param IMAX NUMBER OF VALUES IN THE CYCLIC PHYSICAL SPACE
+C> (SEE LIMITATIONS ON IMAX IN REMARKS BELOW.)
+C> @param INCW FIRST DIMENSION OF THE COMPLEX AMPLITUDE ARRAY
+C> (INCW >= IMAX/2+1)
+C> @param INCG FIRST DIMENSION OF THE REAL VALUE ARRAY
+C> (INCG >= IMAX)
+C> @param KMAX NUMBER OF TRANSFORMS TO PERFORM
+C> @param[out] W COMPLEX AMPLITUDES IF IDIR>0
+C> @param[out] G REAL VALUES IF IDIR<0
+C> @param IDIR DIRECTION FLAG
+C> - IDIR=0 TO INITIALIZE INTERNAL TRIGONOMETRIC DATA
+C> - IDIR>0 TO TRANSFORM FROM FOURIER TO PHYSICAL SPACE
+C> - IDIR<0 TO TRANSFORM FROM PHYSICAL TO FOURIER SPACE
 C>
-C>    CALLED:
-C>   - SCRFT()        IBM ESSL COMPLEX TO REAL FOURIER TRANSFORM
-C>   - SRCFT()        IBM ESSL REAL TO COMPLEX FOURIER TRANSFORM
+C> @author IREDELL @date 96-02-20
       SUBROUTINE SPFFT(IMAX,INCW,INCG,KMAX,W,G,IDIR)
 
         IMPLICIT NONE
@@ -49,9 +47,9 @@ SUBROUTINE SPFFT(IMAX,INCW,INCG,KMAX,W,G,IDIR)
         REAL,SAVE,ALLOCATABLE:: AUX1CR(:),AUX1RC(:)
         INTEGER:: NAUX2
         REAL:: AUX2(20000+INT(0.57*IMAX))
-C - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
         NAUX2=20000+INT(0.57*IMAX)
-C - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
 C  INITIALIZATION.
 C  ALLOCATE AND FILL AUXILIARY ARRAYS WITH TRIGONOMETRIC DATA
         SELECT CASE(IDIR)
@@ -63,12 +61,12 @@ SUBROUTINE SPFFT(IMAX,INCW,INCG,KMAX,W,G,IDIR)
      &                 AUX1CR,NAUX1,AUX2,NAUX2,0.,0)
             CALL SRCFT(1,G,INCG,W,INCW,IMAX,KMAX,+1,1./IMAX,
      &                 AUX1RC,NAUX1,AUX2,NAUX2,0.,0)
-C - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
 C  FOURIER TO PHYSICAL TRANSFORM.
           CASE(1:)
             CALL SCRFT(0,W,INCW,G,INCG,IMAX,KMAX,-1,1.,
      &                 AUX1CR,NAUX1,AUX2,NAUX2,0.,0)
-C - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
 C  PHYSICAL TO FOURIER TRANSFORM.
           CASE(:-1)
             CALL SRCFT(0,G,INCG,W,INCW,IMAX,KMAX,+1,1./IMAX,