Integrating Doxygen in comments

1 files changed, 207 insertions, 141 deletions

diff --git a/SRC/iparmq.f b/SRC/iparmq.f
index 9ecca5d1..5b302e69 100644
--- a/SRC/iparmq.f
+++ b/SRC/iparmq.f
@@ -1,160 +1,226 @@
-      INTEGER FUNCTION IPARMQ( ISPEC, NAME, OPTS, N, ILO, IHI, LWORK )
+*> \brief \b IPARMQ
 *
-*  -- LAPACK auxiliary routine (version 3.2) --
-*  -- LAPACK is a software package provided by Univ. of Tennessee,    --
-*  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
-*     November 2006
-*     
-*     .. Scalar Arguments ..
-      INTEGER            IHI, ILO, ISPEC, LWORK, N
-      CHARACTER          NAME*( * ), OPTS*( * )
+*  =========== DOCUMENTATION ===========
+*
+* Online html documentation available at 
+*            http://www.netlib.org/lapack/explore-html/ 
 *
+*  Definition
+*  ==========
+*
+*       INTEGER FUNCTION IPARMQ( ISPEC, NAME, OPTS, N, ILO, IHI, LWORK )
+* 
+*       .. Scalar Arguments ..
+*       INTEGER            IHI, ILO, ISPEC, LWORK, N
+*       CHARACTER          NAME*( * ), OPTS*( * )
+*  
 *  Purpose
 *  =======
 *
-*       This program sets problem and machine dependent parameters
-*       useful for xHSEQR and its subroutines. It is called whenever 
-*       ILAENV is called with 12 <= ISPEC <= 16
+*>\details \b Purpose:
+*>\verbatim
+*>
+*>      This program sets problem and machine dependent parameters
+*>      useful for xHSEQR and its subroutines. It is called whenever 
+*>      ILAENV is called with 12 <= ISPEC <= 16
+*>
+*>\endverbatim
 *
 *  Arguments
 *  =========
 *
-*       ISPEC  (input) integer scalar
-*              ISPEC specifies which tunable parameter IPARMQ should
-*              return.
-*
-*              ISPEC=12: (INMIN)  Matrices of order nmin or less
-*                        are sent directly to xLAHQR, the implicit
-*                        double shift QR algorithm.  NMIN must be
-*                        at least 11.
-*
-*              ISPEC=13: (INWIN)  Size of the deflation window.
-*                        This is best set greater than or equal to
-*                        the number of simultaneous shifts NS.
-*                        Larger matrices benefit from larger deflation
-*                        windows.
-*
-*              ISPEC=14: (INIBL) Determines when to stop nibbling and
-*                        invest in an (expensive) multi-shift QR sweep.
-*                        If the aggressive early deflation subroutine
-*                        finds LD converged eigenvalues from an order
-*                        NW deflation window and LD.GT.(NW*NIBBLE)/100,
-*                        then the next QR sweep is skipped and early
-*                        deflation is applied immediately to the
-*                        remaining active diagonal block.  Setting
-*                        IPARMQ(ISPEC=14) = 0 causes TTQRE to skip a
-*                        multi-shift QR sweep whenever early deflation
-*                        finds a converged eigenvalue.  Setting
-*                        IPARMQ(ISPEC=14) greater than or equal to 100
-*                        prevents TTQRE from skipping a multi-shift
-*                        QR sweep.
-*
-*              ISPEC=15: (NSHFTS) The number of simultaneous shifts in
-*                        a multi-shift QR iteration.
-*
-*              ISPEC=16: (IACC22) IPARMQ is set to 0, 1 or 2 with the
-*                        following meanings.
-*                        0:  During the multi-shift QR sweep,
-*                            xLAQR5 does not accumulate reflections and
-*                            does not use matrix-matrix multiply to
-*                            update the far-from-diagonal matrix
-*                            entries.
-*                        1:  During the multi-shift QR sweep,
-*                            xLAQR5 and/or xLAQRaccumulates reflections and uses
-*                            matrix-matrix multiply to update the
-*                            far-from-diagonal matrix entries.
-*                        2:  During the multi-shift QR sweep.
-*                            xLAQR5 accumulates reflections and takes
-*                            advantage of 2-by-2 block structure during
-*                            matrix-matrix multiplies.
-*                        (If xTRMM is slower than xGEMM, then
-*                        IPARMQ(ISPEC=16)=1 may be more efficient than
-*                        IPARMQ(ISPEC=16)=2 despite the greater level of
-*                        arithmetic work implied by the latter choice.)
-*
-*       NAME    (input) character string
-*               Name of the calling subroutine
-*
-*       OPTS    (input) character string
-*               This is a concatenation of the string arguments to
-*               TTQRE.
-*
-*       N       (input) integer scalar
-*               N is the order of the Hessenberg matrix H.
-*
-*       ILO     (input) INTEGER
-*
-*       IHI     (input) INTEGER
-*               It is assumed that H is already upper triangular
-*               in rows and columns 1:ILO-1 and IHI+1:N.
-*
-*       LWORK   (input) integer scalar
-*               The amount of workspace available.
-*
-*  Further Details
-*  ===============
-*
-*       Little is known about how best to choose these parameters.
-*       It is possible to use different values of the parameters
-*       for each of CHSEQR, DHSEQR, SHSEQR and ZHSEQR.
-*
-*       It is probably best to choose different parameters for
-*       different matrices and different parameters at different
-*       times during the iteration, but this has not been
-*       implemented --- yet.
-*
-*
-*       The best choices of most of the parameters depend
-*       in an ill-understood way on the relative execution
-*       rate of xLAQR3 and xLAQR5 and on the nature of each
-*       particular eigenvalue problem.  Experiment may be the
-*       only practical way to determine which choices are most
-*       effective.
-*
-*       Following is a list of default values supplied by IPARMQ.
-*       These defaults may be adjusted in order to attain better
-*       performance in any particular computational environment.
-*
-*       IPARMQ(ISPEC=12) The xLAHQR vs xLAQR0 crossover point.
-*                        Default: 75. (Must be at least 11.)
-*
-*       IPARMQ(ISPEC=13) Recommended deflation window size.
-*                        This depends on ILO, IHI and NS, the
-*                        number of simultaneous shifts returned
-*                        by IPARMQ(ISPEC=15).  The default for
-*                        (IHI-ILO+1).LE.500 is NS.  The default
-*                        for (IHI-ILO+1).GT.500 is 3*NS/2.
-*
-*       IPARMQ(ISPEC=14) Nibble crossover point.  Default: 14.
+*> \param[in] ISPEC
+*> \verbatim
+*>          ISPEC is integer scalar
+*>              ISPEC specifies which tunable parameter IPARMQ should
+*>              return.
+*> \endverbatim
+*> \verbatim
+*>              ISPEC=12: (INMIN)  Matrices of order nmin or less
+*>                        are sent directly to xLAHQR, the implicit
+*>                        double shift QR algorithm.  NMIN must be
+*>                        at least 11.
+*> \endverbatim
+*> \verbatim
+*>              ISPEC=13: (INWIN)  Size of the deflation window.
+*>                        This is best set greater than or equal to
+*>                        the number of simultaneous shifts NS.
+*>                        Larger matrices benefit from larger deflation
+*>                        windows.
+*> \endverbatim
+*> \verbatim
+*>              ISPEC=14: (INIBL) Determines when to stop nibbling and
+*>                        invest in an (expensive) multi-shift QR sweep.
+*>                        If the aggressive early deflation subroutine
+*>                        finds LD converged eigenvalues from an order
+*>                        NW deflation window and LD.GT.(NW*NIBBLE)/100,
+*>                        then the next QR sweep is skipped and early
+*>                        deflation is applied immediately to the
+*>                        remaining active diagonal block.  Setting
+*>                        IPARMQ(ISPEC=14) = 0 causes TTQRE to skip a
+*>                        multi-shift QR sweep whenever early deflation
+*>                        finds a converged eigenvalue.  Setting
+*>                        IPARMQ(ISPEC=14) greater than or equal to 100
+*>                        prevents TTQRE from skipping a multi-shift
+*>                        QR sweep.
+*> \endverbatim
+*> \verbatim
+*>              ISPEC=15: (NSHFTS) The number of simultaneous shifts in
+*>                        a multi-shift QR iteration.
+*> \endverbatim
+*> \verbatim
+*>              ISPEC=16: (IACC22) IPARMQ is set to 0, 1 or 2 with the
+*>                        following meanings.
+*>                        0:  During the multi-shift QR sweep,
+*>                            xLAQR5 does not accumulate reflections and
+*>                            does not use matrix-matrix multiply to
+*>                            update the far-from-diagonal matrix
+*>                            entries.
+*>                        1:  During the multi-shift QR sweep,
+*>                            xLAQR5 and/or xLAQRaccumulates reflections and uses
+*>                            matrix-matrix multiply to update the
+*>                            far-from-diagonal matrix entries.
+*>                        2:  During the multi-shift QR sweep.
+*>                            xLAQR5 accumulates reflections and takes
+*>                            advantage of 2-by-2 block structure during
+*>                            matrix-matrix multiplies.
+*>                        (If xTRMM is slower than xGEMM, then
+*>                        IPARMQ(ISPEC=16)=1 may be more efficient than
+*>                        IPARMQ(ISPEC=16)=2 despite the greater level of
+*>                        arithmetic work implied by the latter choice.)
+*> \endverbatim
+*>
+*> \param[in] NAME
+*> \verbatim
+*>          NAME is character string
+*>               Name of the calling subroutine
+*> \endverbatim
+*>
+*> \param[in] OPTS
+*> \verbatim
+*>          OPTS is character string
+*>               This is a concatenation of the string arguments to
+*>               TTQRE.
+*> \endverbatim
+*>
+*> \param[in] N
+*> \verbatim
+*>          N is integer scalar
+*>               N is the order of the Hessenberg matrix H.
+*> \endverbatim
+*>
+*> \param[in] ILO
+*> \verbatim
+*>          ILO is INTEGER
+*> \endverbatim
+*>
+*> \param[in] IHI
+*> \verbatim
+*>          IHI is INTEGER
+*>               It is assumed that H is already upper triangular
+*>               in rows and columns 1:ILO-1 and IHI+1:N.
+*> \endverbatim
+*>
+*> \param[in] LWORK
+*> \verbatim
+*>          LWORK is integer scalar
+*>               The amount of workspace available.
+*> \endverbatim
+*>
+*
+*  Authors
+*  =======
 *
-*       IPARMQ(ISPEC=15) Number of simultaneous shifts, NS.
-*                        a multi-shift QR iteration.
+*> \author Univ. of Tennessee 
+*> \author Univ. of California Berkeley 
+*> \author Univ. of Colorado Denver 
+*> \author NAG Ltd. 
 *
-*                        If IHI-ILO+1 is ...
+*> \date November 2011
 *
-*                        greater than      ...but less    ... the
-*                        or equal to ...      than        default is
+*> \ingroup auxOTHERauxiliary
 *
-*                                0               30       NS =   2+
-*                               30               60       NS =   4+
-*                               60              150       NS =  10
-*                              150              590       NS =  **
-*                              590             3000       NS =  64
-*                             3000             6000       NS = 128
-*                             6000             infinity   NS = 256
 *
-*                    (+)  By default matrices of this order are
-*                         passed to the implicit double shift routine
-*                         xLAHQR.  See IPARMQ(ISPEC=12) above.   These
-*                         values of NS are used only in case of a rare
-*                         xLAHQR failure.
+*  Further Details
+*  ===============
+*>\details \b Further \b Details
+*> \verbatim
+*>
+*>       Little is known about how best to choose these parameters.
+*>       It is possible to use different values of the parameters
+*>       for each of CHSEQR, DHSEQR, SHSEQR and ZHSEQR.
+*>
+*>       It is probably best to choose different parameters for
+*>       different matrices and different parameters at different
+*>       times during the iteration, but this has not been
+*>       implemented --- yet.
+*>
+*>
+*>       The best choices of most of the parameters depend
+*>       in an ill-understood way on the relative execution
+*>       rate of xLAQR3 and xLAQR5 and on the nature of each
+*>       particular eigenvalue problem.  Experiment may be the
+*>       only practical way to determine which choices are most
+*>       effective.
+*>
+*>       Following is a list of default values supplied by IPARMQ.
+*>       These defaults may be adjusted in order to attain better
+*>       performance in any particular computational environment.
+*>
+*>       IPARMQ(ISPEC=12) The xLAHQR vs xLAQR0 crossover point.
+*>                        Default: 75. (Must be at least 11.)
+*>
+*>       IPARMQ(ISPEC=13) Recommended deflation window size.
+*>                        This depends on ILO, IHI and NS, the
+*>                        number of simultaneous shifts returned
+*>                        by IPARMQ(ISPEC=15).  The default for
+*>                        (IHI-ILO+1).LE.500 is NS.  The default
+*>                        for (IHI-ILO+1).GT.500 is 3*NS/2.
+*>
+*>       IPARMQ(ISPEC=14) Nibble crossover point.  Default: 14.
+*>
+*>       IPARMQ(ISPEC=15) Number of simultaneous shifts, NS.
+*>                        a multi-shift QR iteration.
+*>
+*>                        If IHI-ILO+1 is ...
+*>
+*>                        greater than      ...but less    ... the
+*>                        or equal to ...      than        default is
+*>
+*>                                0               30       NS =   2+
+*>                               30               60       NS =   4+
+*>                               60              150       NS =  10
+*>                              150              590       NS =  **
+*>                              590             3000       NS =  64
+*>                             3000             6000       NS = 128
+*>                             6000             infinity   NS = 256
+*>
+*>                    (+)  By default matrices of this order are
+*>                         passed to the implicit double shift routine
+*>                         xLAHQR.  See IPARMQ(ISPEC=12) above.   These
+*>                         values of NS are used only in case of a rare
+*>                         xLAHQR failure.
+*>
+*>                    (**) The asterisks (**) indicate an ad-hoc
+*>                         function increasing from 10 to 64.
+*>
+*>       IPARMQ(ISPEC=16) Select structured matrix multiply.
+*>                        (See ISPEC=16 above for details.)
+*>                        Default: 3.
+*>
+*> \endverbatim
+*>
+*  =====================================================================
+      INTEGER FUNCTION IPARMQ( ISPEC, NAME, OPTS, N, ILO, IHI, LWORK )
 *
-*                    (**) The asterisks (**) indicate an ad-hoc
-*                         function increasing from 10 to 64.
+*  -- LAPACK auxiliary routine (version 3.2) --
+*  -- LAPACK is a software package provided by Univ. of Tennessee,    --
+*  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
+*     November 2011
 *
-*       IPARMQ(ISPEC=16) Select structured matrix multiply.
-*                        (See ISPEC=16 above for details.)
-*                        Default: 3.
+*     .. Scalar Arguments ..
+      INTEGER            IHI, ILO, ISPEC, LWORK, N
+      CHARACTER          NAME*( * ), OPTS*( * )
 *
 *  ================================================================
 *     .. Parameters ..