1*> \brief \b IPARMQ
2*
3*  =========== DOCUMENTATION ===========
4*
5* Online html documentation available at
6*            http://www.netlib.org/lapack/explore-html/
7*
8*> \htmlonly
9*> Download IPARMQ + dependencies
10*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.tgz?format=tgz&filename=/lapack/lapack_routine/iparmq.f">
11*> [TGZ]</a>
12*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.zip?format=zip&filename=/lapack/lapack_routine/iparmq.f">
13*> [ZIP]</a>
14*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.txt?format=txt&filename=/lapack/lapack_routine/iparmq.f">
15*> [TXT]</a>
16*> \endhtmlonly
17*
18*  Definition:
19*  ===========
20*
21*       INTEGER FUNCTION IPARMQ( ISPEC, NAME, OPTS, N, ILO, IHI, LWORK )
22*
23*       .. Scalar Arguments ..
24*       INTEGER            IHI, ILO, ISPEC, LWORK, N
25*       CHARACTER          NAME*( * ), OPTS*( * )
26*
27*
28*> \par Purpose:
29*  =============
30*>
31*> \verbatim
32*>
33*>      This program sets problem and machine dependent parameters
34*>      useful for xHSEQR and its subroutines. It is called whenever
35*>      ILAENV is called with 12 <= ISPEC <= 16
36*> \endverbatim
37*
38*  Arguments:
39*  ==========
40*
41*> \param[in] ISPEC
42*> \verbatim
43*>          ISPEC is integer scalar
44*>              ISPEC specifies which tunable parameter IPARMQ should
45*>              return.
46*>
47*>              ISPEC=12: (INMIN)  Matrices of order nmin or less
48*>                        are sent directly to xLAHQR, the implicit
49*>                        double shift QR algorithm.  NMIN must be
50*>                        at least 11.
51*>
52*>              ISPEC=13: (INWIN)  Size of the deflation window.
53*>                        This is best set greater than or equal to
54*>                        the number of simultaneous shifts NS.
55*>                        Larger matrices benefit from larger deflation
56*>                        windows.
57*>
58*>              ISPEC=14: (INIBL) Determines when to stop nibbling and
59*>                        invest in an (expensive) multi-shift QR sweep.
60*>                        If the aggressive early deflation subroutine
61*>                        finds LD converged eigenvalues from an order
62*>                        NW deflation window and LD.GT.(NW*NIBBLE)/100,
63*>                        then the next QR sweep is skipped and early
64*>                        deflation is applied immediately to the
65*>                        remaining active diagonal block.  Setting
66*>                        IPARMQ(ISPEC=14) = 0 causes TTQRE to skip a
67*>                        multi-shift QR sweep whenever early deflation
68*>                        finds a converged eigenvalue.  Setting
69*>                        IPARMQ(ISPEC=14) greater than or equal to 100
70*>                        prevents TTQRE from skipping a multi-shift
71*>                        QR sweep.
72*>
73*>              ISPEC=15: (NSHFTS) The number of simultaneous shifts in
74*>                        a multi-shift QR iteration.
75*>
76*>              ISPEC=16: (IACC22) IPARMQ is set to 0, 1 or 2 with the
77*>                        following meanings.
78*>                        0:  During the multi-shift QR sweep,
79*>                            xLAQR5 does not accumulate reflections and
80*>                            does not use matrix-matrix multiply to
81*>                            update the far-from-diagonal matrix
82*>                            entries.
83*>                        1:  During the multi-shift QR sweep,
84*>                            xLAQR5 and/or xLAQRaccumulates reflections and uses
85*>                            matrix-matrix multiply to update the
86*>                            far-from-diagonal matrix entries.
87*>                        2:  During the multi-shift QR sweep.
88*>                            xLAQR5 accumulates reflections and takes
89*>                            advantage of 2-by-2 block structure during
90*>                            matrix-matrix multiplies.
91*>                        (If xTRMM is slower than xGEMM, then
92*>                        IPARMQ(ISPEC=16)=1 may be more efficient than
93*>                        IPARMQ(ISPEC=16)=2 despite the greater level of
94*>                        arithmetic work implied by the latter choice.)
95*> \endverbatim
96*>
97*> \param[in] NAME
98*> \verbatim
99*>          NAME is character string
100*>               Name of the calling subroutine
101*> \endverbatim
102*>
103*> \param[in] OPTS
104*> \verbatim
105*>          OPTS is character string
106*>               This is a concatenation of the string arguments to
107*>               TTQRE.
108*> \endverbatim
109*>
110*> \param[in] N
111*> \verbatim
112*>          N is integer scalar
113*>               N is the order of the Hessenberg matrix H.
114*> \endverbatim
115*>
116*> \param[in] ILO
117*> \verbatim
118*>          ILO is INTEGER
119*> \endverbatim
120*>
121*> \param[in] IHI
122*> \verbatim
123*>          IHI is INTEGER
124*>               It is assumed that H is already upper triangular
125*>               in rows and columns 1:ILO-1 and IHI+1:N.
126*> \endverbatim
127*>
128*> \param[in] LWORK
129*> \verbatim
130*>          LWORK is integer scalar
131*>               The amount of workspace available.
132*> \endverbatim
133*
134*  Authors:
135*  ========
136*
137*> \author Univ. of Tennessee
138*> \author Univ. of California Berkeley
139*> \author Univ. of Colorado Denver
140*> \author NAG Ltd.
141*
142*> \date November 2011
143*
144*> \ingroup auxOTHERauxiliary
145*
146*> \par Further Details:
147*  =====================
148*>
149*> \verbatim
150*>
151*>       Little is known about how best to choose these parameters.
152*>       It is possible to use different values of the parameters
153*>       for each of CHSEQR, DHSEQR, SHSEQR and ZHSEQR.
154*>
155*>       It is probably best to choose different parameters for
156*>       different matrices and different parameters at different
157*>       times during the iteration, but this has not been
158*>       implemented --- yet.
159*>
160*>
161*>       The best choices of most of the parameters depend
162*>       in an ill-understood way on the relative execution
163*>       rate of xLAQR3 and xLAQR5 and on the nature of each
164*>       particular eigenvalue problem.  Experiment may be the
165*>       only practical way to determine which choices are most
166*>       effective.
167*>
168*>       Following is a list of default values supplied by IPARMQ.
169*>       These defaults may be adjusted in order to attain better
170*>       performance in any particular computational environment.
171*>
172*>       IPARMQ(ISPEC=12) The xLAHQR vs xLAQR0 crossover point.
173*>                        Default: 75. (Must be at least 11.)
174*>
175*>       IPARMQ(ISPEC=13) Recommended deflation window size.
176*>                        This depends on ILO, IHI and NS, the
177*>                        number of simultaneous shifts returned
178*>                        by IPARMQ(ISPEC=15).  The default for
179*>                        (IHI-ILO+1).LE.500 is NS.  The default
180*>                        for (IHI-ILO+1).GT.500 is 3*NS/2.
181*>
182*>       IPARMQ(ISPEC=14) Nibble crossover point.  Default: 14.
183*>
184*>       IPARMQ(ISPEC=15) Number of simultaneous shifts, NS.
185*>                        a multi-shift QR iteration.
186*>
187*>                        If IHI-ILO+1 is ...
188*>
189*>                        greater than      ...but less    ... the
190*>                        or equal to ...      than        default is
191*>
192*>                                0               30       NS =   2+
193*>                               30               60       NS =   4+
194*>                               60              150       NS =  10
195*>                              150              590       NS =  **
196*>                              590             3000       NS =  64
197*>                             3000             6000       NS = 128
198*>                             6000             infinity   NS = 256
199*>
200*>                    (+)  By default matrices of this order are
201*>                         passed to the implicit double shift routine
202*>                         xLAHQR.  See IPARMQ(ISPEC=12) above.   These
203*>                         values of NS are used only in case of a rare
204*>                         xLAHQR failure.
205*>
206*>                    (**) The asterisks (**) indicate an ad-hoc
207*>                         function increasing from 10 to 64.
208*>
209*>       IPARMQ(ISPEC=16) Select structured matrix multiply.
210*>                        (See ISPEC=16 above for details.)
211*>                        Default: 3.
212*> \endverbatim
213*>
214*  =====================================================================
215      INTEGER FUNCTION IPARMQ( ISPEC, NAME, OPTS, N, ILO, IHI, LWORK )
216*
217*  -- LAPACK auxiliary routine (version 3.4.0) --
218*  -- LAPACK is a software package provided by Univ. of Tennessee,    --
219*  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
220*     November 2011
221*
222*     .. Scalar Arguments ..
223      INTEGER            IHI, ILO, ISPEC, LWORK, N
224      CHARACTER          NAME*( * ), OPTS*( * )
225*
226*  ================================================================
227*     .. Parameters ..
228      INTEGER            INMIN, INWIN, INIBL, ISHFTS, IACC22
229      PARAMETER          ( INMIN = 12, INWIN = 13, INIBL = 14,
230     $                   ISHFTS = 15, IACC22 = 16 )
231      INTEGER            NMIN, K22MIN, KACMIN, NIBBLE, KNWSWP
232      PARAMETER          ( NMIN = 75, K22MIN = 14, KACMIN = 14,
233     $                   NIBBLE = 14, KNWSWP = 500 )
234      REAL               TWO
235      PARAMETER          ( TWO = 2.0 )
236*     ..
237*     .. Local Scalars ..
238      INTEGER            NH, NS
239*     ..
240*     .. Intrinsic Functions ..
241      INTRINSIC          LOG, MAX, MOD, NINT, REAL
242*     ..
243*     .. Executable Statements ..
244      IF( ( ISPEC.EQ.ISHFTS ) .OR. ( ISPEC.EQ.INWIN ) .OR.
245     $    ( ISPEC.EQ.IACC22 ) ) THEN
246*
247*        ==== Set the number simultaneous shifts ====
248*
249         NH = IHI - ILO + 1
250         NS = 2
251         IF( NH.GE.30 )
252     $      NS = 4
253         IF( NH.GE.60 )
254     $      NS = 10
255         IF( NH.GE.150 )
256     $      NS = MAX( 10, NH / NINT( LOG( REAL( NH ) ) / LOG( TWO ) ) )
257         IF( NH.GE.590 )
258     $      NS = 64
259         IF( NH.GE.3000 )
260     $      NS = 128
261         IF( NH.GE.6000 )
262     $      NS = 256
263         NS = MAX( 2, NS-MOD( NS, 2 ) )
264      END IF
265*
266      IF( ISPEC.EQ.INMIN ) THEN
267*
268*
269*        ===== Matrices of order smaller than NMIN get sent
270*        .     to xLAHQR, the classic double shift algorithm.
271*        .     This must be at least 11. ====
272*
273         IPARMQ = NMIN
274*
275      ELSE IF( ISPEC.EQ.INIBL ) THEN
276*
277*        ==== INIBL: skip a multi-shift qr iteration and
278*        .    whenever aggressive early deflation finds
279*        .    at least (NIBBLE*(window size)/100) deflations. ====
280*
281         IPARMQ = NIBBLE
282*
283      ELSE IF( ISPEC.EQ.ISHFTS ) THEN
284*
285*        ==== NSHFTS: The number of simultaneous shifts =====
286*
287         IPARMQ = NS
288*
289      ELSE IF( ISPEC.EQ.INWIN ) THEN
290*
291*        ==== NW: deflation window size.  ====
292*
293         IF( NH.LE.KNWSWP ) THEN
294            IPARMQ = NS
295         ELSE
296            IPARMQ = 3*NS / 2
297         END IF
298*
299      ELSE IF( ISPEC.EQ.IACC22 ) THEN
300*
301*        ==== IACC22: Whether to accumulate reflections
302*        .     before updating the far-from-diagonal elements
303*        .     and whether to use 2-by-2 block structure while
304*        .     doing it.  A small amount of work could be saved
305*        .     by making this choice dependent also upon the
306*        .     NH=IHI-ILO+1.
307*
308         IPARMQ = 0
309         IF( NS.GE.KACMIN )
310     $      IPARMQ = 1
311         IF( NS.GE.K22MIN )
312     $      IPARMQ = 2
313*
314      ELSE
315*        ===== invalid value of ispec =====
316         IPARMQ = -1
317*
318      END IF
319*
320*     ==== End of IPARMQ ====
321*
322      END
323