001:       SUBROUTINE SLASD6( ICOMPQ, NL, NR, SQRE, D, VF, VL, ALPHA, BETA,
002:      $                   IDXQ, PERM, GIVPTR, GIVCOL, LDGCOL, GIVNUM,
003:      $                   LDGNUM, POLES, DIFL, DIFR, Z, K, C, S, WORK,
004:      $                   IWORK, INFO )
005: *
006: *  -- LAPACK auxiliary routine (version 3.2) --
007: *  -- LAPACK is a software package provided by Univ. of Tennessee,    --
008: *  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
009: *     November 2006
010: *
011: *     .. Scalar Arguments ..
012:       INTEGER            GIVPTR, ICOMPQ, INFO, K, LDGCOL, LDGNUM, NL,
013:      $                   NR, SQRE
014:       REAL               ALPHA, BETA, C, S
015: *     ..
016: *     .. Array Arguments ..
017:       INTEGER            GIVCOL( LDGCOL, * ), IDXQ( * ), IWORK( * ),
018:      $                   PERM( * )
019:       REAL               D( * ), DIFL( * ), DIFR( * ),
020:      $                   GIVNUM( LDGNUM, * ), POLES( LDGNUM, * ),
021:      $                   VF( * ), VL( * ), WORK( * ), Z( * )
022: *     ..
023: *
024: *  Purpose
025: *  =======
026: *
027: *  SLASD6 computes the SVD of an updated upper bidiagonal matrix B
028: *  obtained by merging two smaller ones by appending a row. This
029: *  routine is used only for the problem which requires all singular
030: *  values and optionally singular vector matrices in factored form.
031: *  B is an N-by-M matrix with N = NL + NR + 1 and M = N + SQRE.
032: *  A related subroutine, SLASD1, handles the case in which all singular
033: *  values and singular vectors of the bidiagonal matrix are desired.
034: *
035: *  SLASD6 computes the SVD as follows:
036: *
037: *                ( D1(in)  0    0     0 )
038: *    B = U(in) * (   Z1'   a   Z2'    b ) * VT(in)
039: *                (   0     0   D2(in) 0 )
040: *
041: *      = U(out) * ( D(out) 0) * VT(out)
042: *
043: *  where Z' = (Z1' a Z2' b) = u' VT', and u is a vector of dimension M
044: *  with ALPHA and BETA in the NL+1 and NL+2 th entries and zeros
045: *  elsewhere; and the entry b is empty if SQRE = 0.
046: *
047: *  The singular values of B can be computed using D1, D2, the first
048: *  components of all the right singular vectors of the lower block, and
049: *  the last components of all the right singular vectors of the upper
050: *  block. These components are stored and updated in VF and VL,
051: *  respectively, in SLASD6. Hence U and VT are not explicitly
052: *  referenced.
053: *
054: *  The singular values are stored in D. The algorithm consists of two
055: *  stages:
056: *
057: *        The first stage consists of deflating the size of the problem
058: *        when there are multiple singular values or if there is a zero
059: *        in the Z vector. For each such occurence the dimension of the
060: *        secular equation problem is reduced by one. This stage is
061: *        performed by the routine SLASD7.
062: *
063: *        The second stage consists of calculating the updated
064: *        singular values. This is done by finding the roots of the
065: *        secular equation via the routine SLASD4 (as called by SLASD8).
066: *        This routine also updates VF and VL and computes the distances
067: *        between the updated singular values and the old singular
068: *        values.
069: *
070: *  SLASD6 is called from SLASDA.
071: *
072: *  Arguments
073: *  =========
074: *
075: *  ICOMPQ (input) INTEGER
076: *         Specifies whether singular vectors are to be computed in
077: *         factored form:
078: *         = 0: Compute singular values only.
079: *         = 1: Compute singular vectors in factored form as well.
080: *
081: *  NL     (input) INTEGER
082: *         The row dimension of the upper block.  NL >= 1.
083: *
084: *  NR     (input) INTEGER
085: *         The row dimension of the lower block.  NR >= 1.
086: *
087: *  SQRE   (input) INTEGER
088: *         = 0: the lower block is an NR-by-NR square matrix.
089: *         = 1: the lower block is an NR-by-(NR+1) rectangular matrix.
090: *
091: *         The bidiagonal matrix has row dimension N = NL + NR + 1,
092: *         and column dimension M = N + SQRE.
093: *
094: *  D      (input/output) REAL array, dimension (NL+NR+1).
095: *         On entry D(1:NL,1:NL) contains the singular values of the
096: *         upper block, and D(NL+2:N) contains the singular values
097: *         of the lower block. On exit D(1:N) contains the singular
098: *         values of the modified matrix.
099: *
100: *  VF     (input/output) REAL array, dimension (M)
101: *         On entry, VF(1:NL+1) contains the first components of all
102: *         right singular vectors of the upper block; and VF(NL+2:M)
103: *         contains the first components of all right singular vectors
104: *         of the lower block. On exit, VF contains the first components
105: *         of all right singular vectors of the bidiagonal matrix.
106: *
107: *  VL     (input/output) REAL array, dimension (M)
108: *         On entry, VL(1:NL+1) contains the  last components of all
109: *         right singular vectors of the upper block; and VL(NL+2:M)
110: *         contains the last components of all right singular vectors of
111: *         the lower block. On exit, VL contains the last components of
112: *         all right singular vectors of the bidiagonal matrix.
113: *
114: *  ALPHA  (input/output) REAL
115: *         Contains the diagonal element associated with the added row.
116: *
117: *  BETA   (input/output) REAL
118: *         Contains the off-diagonal element associated with the added
119: *         row.
120: *
121: *  IDXQ   (output) INTEGER array, dimension (N)
122: *         This contains the permutation which will reintegrate the
123: *         subproblem just solved back into sorted order, i.e.
124: *         D( IDXQ( I = 1, N ) ) will be in ascending order.
125: *
126: *  PERM   (output) INTEGER array, dimension ( N )
127: *         The permutations (from deflation and sorting) to be applied
128: *         to each block. Not referenced if ICOMPQ = 0.
129: *
130: *  GIVPTR (output) INTEGER
131: *         The number of Givens rotations which took place in this
132: *         subproblem. Not referenced if ICOMPQ = 0.
133: *
134: *  GIVCOL (output) INTEGER array, dimension ( LDGCOL, 2 )
135: *         Each pair of numbers indicates a pair of columns to take place
136: *         in a Givens rotation. Not referenced if ICOMPQ = 0.
137: *
138: *  LDGCOL (input) INTEGER
139: *         leading dimension of GIVCOL, must be at least N.
140: *
141: *  GIVNUM (output) REAL array, dimension ( LDGNUM, 2 )
142: *         Each number indicates the C or S value to be used in the
143: *         corresponding Givens rotation. Not referenced if ICOMPQ = 0.
144: *
145: *  LDGNUM (input) INTEGER
146: *         The leading dimension of GIVNUM and POLES, must be at least N.
147: *
148: *  POLES  (output) REAL array, dimension ( LDGNUM, 2 )
149: *         On exit, POLES(1,*) is an array containing the new singular
150: *         values obtained from solving the secular equation, and
151: *         POLES(2,*) is an array containing the poles in the secular
152: *         equation. Not referenced if ICOMPQ = 0.
153: *
154: *  DIFL   (output) REAL array, dimension ( N )
155: *         On exit, DIFL(I) is the distance between I-th updated
156: *         (undeflated) singular value and the I-th (undeflated) old
157: *         singular value.
158: *
159: *  DIFR   (output) REAL array,
160: *                  dimension ( LDGNUM, 2 ) if ICOMPQ = 1 and
161: *                  dimension ( N ) if ICOMPQ = 0.
162: *         On exit, DIFR(I, 1) is the distance between I-th updated
163: *         (undeflated) singular value and the I+1-th (undeflated) old
164: *         singular value.
165: *
166: *         If ICOMPQ = 1, DIFR(1:K,2) is an array containing the
167: *         normalizing factors for the right singular vector matrix.
168: *
169: *         See SLASD8 for details on DIFL and DIFR.
170: *
171: *  Z      (output) REAL array, dimension ( M )
172: *         The first elements of this array contain the components
173: *         of the deflation-adjusted updating row vector.
174: *
175: *  K      (output) INTEGER
176: *         Contains the dimension of the non-deflated matrix,
177: *         This is the order of the related secular equation. 1 <= K <=N.
178: *
179: *  C      (output) REAL
180: *         C contains garbage if SQRE =0 and the C-value of a Givens
181: *         rotation related to the right null space if SQRE = 1.
182: *
183: *  S      (output) REAL
184: *         S contains garbage if SQRE =0 and the S-value of a Givens
185: *         rotation related to the right null space if SQRE = 1.
186: *
187: *  WORK   (workspace) REAL array, dimension ( 4 * M )
188: *
189: *  IWORK  (workspace) INTEGER array, dimension ( 3 * N )
190: *
191: *  INFO   (output) INTEGER
192: *          = 0:  successful exit.
193: *          < 0:  if INFO = -i, the i-th argument had an illegal value.
194: *          > 0:  if INFO = 1, an singular value did not converge
195: *
196: *  Further Details
197: *  ===============
198: *
199: *  Based on contributions by
200: *     Ming Gu and Huan Ren, Computer Science Division, University of
201: *     California at Berkeley, USA
202: *
203: *  =====================================================================
204: *
205: *     .. Parameters ..
206:       REAL               ONE, ZERO
207:       PARAMETER          ( ONE = 1.0E+0, ZERO = 0.0E+0 )
208: *     ..
209: *     .. Local Scalars ..
210:       INTEGER            I, IDX, IDXC, IDXP, ISIGMA, IVFW, IVLW, IW, M,
211:      $                   N, N1, N2
212:       REAL               ORGNRM
213: *     ..
214: *     .. External Subroutines ..
215:       EXTERNAL           SCOPY, SLAMRG, SLASCL, SLASD7, SLASD8, XERBLA
216: *     ..
217: *     .. Intrinsic Functions ..
218:       INTRINSIC          ABS, MAX
219: *     ..
220: *     .. Executable Statements ..
221: *
222: *     Test the input parameters.
223: *
224:       INFO = 0
225:       N = NL + NR + 1
226:       M = N + SQRE
227: *
228:       IF( ( ICOMPQ.LT.0 ) .OR. ( ICOMPQ.GT.1 ) ) THEN
229:          INFO = -1
230:       ELSE IF( NL.LT.1 ) THEN
231:          INFO = -2
232:       ELSE IF( NR.LT.1 ) THEN
233:          INFO = -3
234:       ELSE IF( ( SQRE.LT.0 ) .OR. ( SQRE.GT.1 ) ) THEN
235:          INFO = -4
236:       ELSE IF( LDGCOL.LT.N ) THEN
237:          INFO = -14
238:       ELSE IF( LDGNUM.LT.N ) THEN
239:          INFO = -16
240:       END IF
241:       IF( INFO.NE.0 ) THEN
242:          CALL XERBLA( 'SLASD6', -INFO )
243:          RETURN
244:       END IF
245: *
246: *     The following values are for bookkeeping purposes only.  They are
247: *     integer pointers which indicate the portion of the workspace
248: *     used by a particular array in SLASD7 and SLASD8.
249: *
250:       ISIGMA = 1
251:       IW = ISIGMA + N
252:       IVFW = IW + M
253:       IVLW = IVFW + M
254: *
255:       IDX = 1
256:       IDXC = IDX + N
257:       IDXP = IDXC + N
258: *
259: *     Scale.
260: *
261:       ORGNRM = MAX( ABS( ALPHA ), ABS( BETA ) )
262:       D( NL+1 ) = ZERO
263:       DO 10 I = 1, N
264:          IF( ABS( D( I ) ).GT.ORGNRM ) THEN
265:             ORGNRM = ABS( D( I ) )
266:          END IF
267:    10 CONTINUE
268:       CALL SLASCL( 'G', 0, 0, ORGNRM, ONE, N, 1, D, N, INFO )
269:       ALPHA = ALPHA / ORGNRM
270:       BETA = BETA / ORGNRM
271: *
272: *     Sort and Deflate singular values.
273: *
274:       CALL SLASD7( ICOMPQ, NL, NR, SQRE, K, D, Z, WORK( IW ), VF,
275:      $             WORK( IVFW ), VL, WORK( IVLW ), ALPHA, BETA,
276:      $             WORK( ISIGMA ), IWORK( IDX ), IWORK( IDXP ), IDXQ,
277:      $             PERM, GIVPTR, GIVCOL, LDGCOL, GIVNUM, LDGNUM, C, S,
278:      $             INFO )
279: *
280: *     Solve Secular Equation, compute DIFL, DIFR, and update VF, VL.
281: *
282:       CALL SLASD8( ICOMPQ, K, D, Z, VF, VL, DIFL, DIFR, LDGNUM,
283:      $             WORK( ISIGMA ), WORK( IW ), INFO )
284: *
285: *     Save the poles if ICOMPQ = 1.
286: *
287:       IF( ICOMPQ.EQ.1 ) THEN
288:          CALL SCOPY( K, D, 1, POLES( 1, 1 ), 1 )
289:          CALL SCOPY( K, WORK( ISIGMA ), 1, POLES( 1, 2 ), 1 )
290:       END IF
291: *
292: *     Unscale.
293: *
294:       CALL SLASCL( 'G', 0, 0, ONE, ORGNRM, N, 1, D, N, INFO )
295: *
296: *     Prepare the IDXQ sorting permutation.
297: *
298:       N1 = K
299:       N2 = N - K
300:       CALL SLAMRG( N1, N2, D, 1, -1, IDXQ )
301: *
302:       RETURN
303: *
304: *     End of SLASD6
305: *
306:       END
307: