Least Square Auxiliary Routines APIs#

LAIC1#

group laic1

Functions

template<typename T>
void laic1(integer *job, integer *j, T *x, T *sest, T *w, T *gamma, T *sestpr, T *s, T *c__)#

LAIC1 applies one step of incremental condition estimation.

Purpose:

 LAIC1 applies one step of incremental condition estimation in
 its simplest version:

 Let x, twonorm(x) = 1, be an approximate singular vector of an j-by-j
 lower triangular matrix L, such that
          twonorm(L*x) = sest
 Then SLAIC1 computes sestpr, s, c such that
 the vector
                 [ s*x ]
          xhat = [  c  ]
 is an approximate singular vector of
                 [ L      0  ]
          Lhat = [ w**T gamma ]
 in the sense that
          twonorm(Lhat*xhat) = sestpr.

 Depending on JOB, an estimate for the largest or smallest singular
 value is computed.

 Note that [s c]**T and sestpr**2 is an eigenpair of the system

     diag(sest*sest, 0) + [alpha  gamma] * [ alpha ]
                                           [ gamma ]

 where  alpha =  x**T*w.

Parameters:
  • JOB – [in]

    JOB is INTEGER

    = 1: an estimate for the largest singular value is computed.

    = 2: an estimate for the smallest singular value is computed.

  • J – [in]

    J is INTEGER

    Length of X and W

  • X – [in]

    X is REAL array, dimension (J)

    The j-vector x.

  • SEST – [in]

    SEST is REAL

    Estimated singular value of j by j matrix L

  • W – [in]

    W is REAL array, dimension (J)

    The j-vector w.

  • GAMMA – [in]

    GAMMA is REAL

    The diagonal element gamma.

  • SESTPR – [out]

    SESTPR is REAL

    Estimated singular value of (j+1) by (j+1) matrix Lhat.

  • S – [out]

    S is REAL

    Sine needed in forming xhat.

  • C – [out]

    C is REAL

    Cosine needed in forming xhat.

template<typename T, typename Ta>
void laic1(integer *job, integer *j, T *x, Ta *sest, T *w, T *gamma, Ta *sestpr, T *s, T *c__)#

LALS0#

group lals0

Functions

template<typename T>
void lals0(integer *icompq, integer *nl, integer *nr, integer *sqre, integer *nrhs, T *b, integer *ldb, T *bx, integer *ldbx, integer *perm, integer *givptr, integer *givcol, integer *ldgcol, T *givnum, integer *ldgnum, T *poles, T *difl, T *difr, T *z, integer *k, T *c, T *s, T *work, integer *info)#

LALS0 applies back multiplying factors in solving the least squares problem

using divide and conquer SVD approach. Used by sgelsd.

Purpose:

   LALS0 applies back the multiplying factors of either the left or the
   right singular vector matrix of a diagonal matrix appended by a row
   to the right hand side matrix B in solving the least squares problem
   using the divide-and-conquer SVD approach.

   For the left singular vector matrix, three types of orthogonal
   matrices are involved:

   (1L) Givens rotations: the number of such rotations is GIVPTR; the
        pairs of columns/rows they were applied to are stored in GIVCOL;
        and the C- and S-values of these rotations are stored in GIVNUM.

   (2L) Permutation. The (NL+1)-st row of B is to be moved to the first
        row, and for J=2:N, PERM(J)-th row of B is to be moved to the
        J-th row.

   (3L) The left singular vector matrix of the remaining matrix.

   For the right singular vector matrix, four types of orthogonal
   matrices are involved:

   (1R) The right singular vector matrix of the remaining matrix.

   (2R) If SQRE = 1, one extra Givens rotation to generate the right
        null space.

   (3R) The inverse transformation of (2L).

   (4R) The inverse transformation of (1L).

Parameters:
  • ICOMPQ – [in]

    ICOMPQ is INTEGER

    Specifies whether singular vectors are to be computed in factored form:

    = 0: Left singular vector matrix.

    = 1: Right singular vector matrix.

  • NL – [in]

    NL is INTEGER

    The row dimension of the upper block. NL >= 1.

  • NR – [in]

    NR is INTEGER

    The row dimension of the lower block. NR >= 1.

  • SQRE – [in]

    SQRE is INTEGER

    = 0: the lower block is an NR-by-NR square matrix.

    = 1: the lower block is an NR-by-(NR+1) rectangular matrix.

    The bidiagonal matrix has row dimension N = NL + NR + 1, and column dimension M = N + SQRE.

  • NRHS – [in]

    NRHS is INTEGER

    The number of columns of B and BX. NRHS must be at least 1.

  • B – [inout]

    B is REAL array, dimension (LDB, NRHS)

    On input, B contains the right hand sides of the least squares problem in rows 1 through M. On output, B contains the solution X in rows 1 through N.

  • LDB – [in]

    LDB is INTEGER

    The leading dimension of B. LDB must be at least fla_max(1,MAX(M, N)).

  • BX – [out] BX is REAL array, dimension (LDBX, NRHS)

  • LDBX – [in]

    LDBX is INTEGER

    The leading dimension of BX.

  • PERM – [in]

    PERM is INTEGER array, dimension (N)

    The permutations (from deflation and sorting) applied to the two blocks.

  • GIVPTR – [in]

    GIVPTR is INTEGER

    The number of Givens rotations which took place in this subproblem.

  • GIVCOL – [in]

    GIVCOL is INTEGER array, dimension (LDGCOL, 2)

    Each pair of numbers indicates a pair of rows/columns involved in a Givens rotation.

  • LDGCOL – [in]

    LDGCOL is INTEGER

    The leading dimension of GIVCOL, must be at least N.

  • GIVNUM – [in]

    GIVNUM is REAL array, dimension (LDGNUM, 2)

    Each number indicates the C or S value used in the corresponding Givens rotation.

  • LDGNUM – [in]

    LDGNUM is INTEGER

    The leading dimension of arrays DIFR, POLES and GIVNUM, must be at least K.

  • POLES – [in]

    POLES is REAL array, dimension (LDGNUM, 2)

    On entry, POLES(1:K, 1) contains the new singular values obtained from solving the secular equation, and POLES(1:K, 2) is an array containing the poles in the secular equation.

  • DIFL – [in]

    DIFL is REAL array, dimension (K).

    On entry, DIFL(I) is the distance between I-th updated (undeflated) singular value and the I-th (undeflated) old singular value.

  • DIFR – [in]

    DIFR is REAL array, dimension (LDGNUM, 2).

    On entry, DIFR(I, 1) contains the distances between I-th updated (undeflated) singular value and the I+1-th (undeflated) old singular value. And DIFR(I, 2) is the normalizing factor for the I-th right singular vector.

  • Z – [in]

    Z is REAL array, dimension (K)

    Contain the components of the deflation-adjusted updating row vector.

  • K – [in]

    K is INTEGER

    Contains the dimension of the non-deflated matrix, This is the order of the related secular equation. 1 <= K <=N.

  • C – [in]

    C is REAL

    C contains garbage if SQRE =0 and the C-value of a Givens rotation related to the right null space if SQRE = 1.

  • S – [in]

    S is REAL

    S contains garbage if SQRE =0 and the S-value of a Givens rotation related to the right null space if SQRE = 1.

  • WORK – [out] WORK is REAL array, dimension (K)

  • INFO – [out]

    INFO is INTEGER

    = 0: successful exit.

    < 0: if INFO = -i, the i-th argument had an illegal value.

template<typename T, typename Ta>
void lals0(integer *icompq, integer *nl, integer *nr, integer *sqre, integer *nrhs, T *b, integer *ldb, T *bx, integer *ldbx, integer *perm, integer *givptr, integer *givcol, integer *ldgcol, Ta *givnum, integer *ldgnum, Ta *poles, Ta *difl, Ta *difr, Ta *z, integer *k, Ta *c, Ta *s, Ta *work, integer *info)#

LALSA#

group lalsa

Functions

template<typename T>
void lalsa(integer *icompq, integer *smlsiz, integer *n, integer *nrhs, T *b, integer *ldb, T *bx, integer *ldbx, T *u, integer *ldu, T *vt, integer *k, T *difl, T *difr, T *z, T *poles, integer *givptr, integer *givcol, integer *ldgcol, integer *perm, T *givnum, T *c, T *s, T *work, integer *iwork, integer *info)#

LALSA computes the SVD of the coefficient matrix in compact form. Used by sgelsd.

Purpose:

 LALSA is an itermediate step in solving the least squares problem
 by computing the SVD of the coefficient matrix in compact form (The
 singular vectors are computed as products of simple orthorgonal
 matrices.).

 If ICOMPQ = 0, SLALSA applies the inverse of the left singular vector
 matrix of an upper bidiagonal matrix to the right hand side; and if
 ICOMPQ = 1, SLALSA applies the right singular vector matrix to the
 right hand side. The singular vector matrices were generated in
 compact form by SLALSA.

Parameters:
  • ICOMPQ – [in]

    ICOMPQ is INTEGER

    Specifies whether the left or the right singular vector matrix is involved.

    = 0: Left singular vector matrix

    = 1: Right singular vector matrix

  • SMLSIZ – [in]

    SMLSIZ is INTEGER

    The maximum size of the subproblems at the bottom of the computation tree.

  • N – [in]

    N is INTEGER

    The row and column dimensions of the upper bidiagonal matrix.

  • NRHS – [in]

    NRHS is INTEGER

    The number of columns of B and BX. NRHS must be at least 1.

  • B – [inout]

    B is REAL array, dimension (LDB, NRHS)

    On input, B contains the right hand sides of the least squares problem in rows 1 through M.

    On output, B contains the solution X in rows 1 through N.

  • LDB – [in]

    LDB is INTEGER

    The leading dimension of B in the calling subprogram. LDB must be at least fla_max(1,MAX(M, N)).

  • BX – [out]

    BX is REAL array, dimension (LDBX, NRHS)

    On exit, the result of applying the left or right singular vector matrix to B.

  • LDBX – [in]

    LDBX is INTEGER

    The leading dimension of BX.

  • U – [in]

    U is REAL array, dimension (LDU, SMLSIZ).

    On entry, U contains the left singular vector matrices of all subproblems at the bottom level.

  • LDU – [in]

    LDU is INTEGER, LDU = > N.

    The leading dimension of arrays U, VT, DIFL, DIFR, POLES, GIVNUM, and Z.

  • VT – [in]

    VT is REAL array, dimension (LDU, SMLSIZ+1).

    On entry, VT**T contains the right singular vector matrices of all subproblems at the bottom level.

  • K – [in] K is INTEGER array, dimension (N).

  • DIFL – [in]

    DIFL is REAL array, dimension (LDU, NLVL).

    where NLVL = INT(log_2 (N/(SMLSIZ+1))) + 1.

  • DIFR – [in]

    DIFR is REAL array, dimension (LDU, 2 * NLVL).

    On entry, DIFL(*, I) and DIFR(*, 2 * I -1) record distances between singular values on the I-th level and singular values on the (I -1)-th level, and DIFR(*, 2 * I) record the normalizing factors of the right singular vectors matrices of subproblems on I-th level.

  • Z – [in]

    Z is REAL array, dimension (LDU, NLVL).

    On entry, Z(1, I) contains the components of the deflation- adjusted updating row vector for subproblems on the I-th level.

  • POLES – [in]

    POLES is REAL array, dimension (LDU, 2 * NLVL).

    On entry, POLES(*, 2 * I -1: 2 * I) contains the new and old singular values involved in the secular equations on the I-th level.

  • GIVPTR – [in]

    GIVPTR is INTEGER array, dimension (N).

    On entry, GIVPTR(I) records the number of Givens rotations performed on the I-th problem on the computation tree.

  • GIVCOL – [in]

    GIVCOL is INTEGER array, dimension (LDGCOL, 2 * NLVL).

    On entry, for each I, GIVCOL(*, 2 * I - 1: 2 * I) records the locations of Givens rotations performed on the I-th level on the computation tree.

  • LDGCOL – [in]

    LDGCOL is INTEGER, LDGCOL = > N.

    The leading dimension of arrays GIVCOL and PERM.

  • PERM – [in]

    PERM is INTEGER array, dimension (LDGCOL, NLVL).

    On entry, PERM(*, I) records permutations done on the I-th level of the computation tree.

  • GIVNUM – [in]

    GIVNUM is REAL array, dimension (LDU, 2 * NLVL).

    On entry, GIVNUM(*, 2 *I -1 : 2 * I) records the C- and S- values of Givens rotations performed on the I-th level on the computation tree.

  • C – [in]

    C is REAL array, dimension (N).

    On entry, if the I-th subproblem is not square, C(I) contains the C-value of a Givens rotation related to the right null space of the I-th subproblem.

  • S – [in]

    S is REAL array, dimension (N).

    On entry, if the I-th subproblem is not square, S(I) contains the S-value of a Givens rotation related to the right null space of the I-th subproblem.

  • WORK – [out] WORK is REAL array, dimension (N)

  • IWORK – [out] IWORK is INTEGER array, dimension (3*N)

  • INFO – [out]

    INFO is INTEGER

    = 0: successful exit.

    < 0: if INFO = -i, the i-th argument had an illegal value.

template<typename T, typename Ta>
void lalsa(integer *icompq, integer *smlsiz, integer *n, integer *nrhs, T *b, integer *ldb, T *bx, integer *ldbx, Ta *u, integer *ldu, Ta *vt, integer *k, Ta *difl, Ta *difr, Ta *z, Ta *poles, integer *givptr, integer *givcol, integer *ldgcol, integer *perm, Ta *givnum, Ta *c, Ta *s, Ta *work, integer *iwork, integer *info)#

LALSD#

group lalsd

Functions

template<typename T>
void lalsd(char *uplo, integer *smlsiz, integer *n, integer *nrhs, T *d, T *e, T *b, integer *ldb, T *rcond, integer *rank, T *work, integer *iwork, integer *info)#

LALSD uses the singular value decomposition of A to solve the least squares problem.

Purpose:

 LALSD uses the singular value decomposition of A to solve the least
 squares problem of finding X to minimize the Euclidean norm of each
 column of A*X-B, where A is N-by-N upper bidiagonal, and X and B
 are N-by-NRHS. The solution X overwrites B.

 The singular values of A smaller than RCOND times the largest
 singular value are treated as zero in solving the least squares
 problem; in this case a minimum norm solution is   returned.
 The actual singular values are   returned in D in ascending order.

 This code makes very mild assumptions about floating point
 arithmetic. It will work on machines with a guard digit in
 add/subtract, or on those binary machines without guard digits
 which subtract like the Cray XMP, Cray YMP, Cray C 90, or Cray 2.
 It could conceivably fail on hexadecimal or decimal machines
 without guard digits, but we know of none.

Parameters:
  • UPLO – [in]

    UPLO is CHARACTER*1

    = ‘U’: D and E define an upper bidiagonal matrix.

    = ‘L’: D and E define a lower bidiagonal matrix.

  • SMLSIZ – [in]

    SMLSIZ is INTEGER

    The maximum size of the subproblems at the bottom of the computation tree.

  • N – [in]

    N is INTEGER

    The dimension of the bidiagonal matrix. N >= 0.

  • NRHS – [in]

    NRHS is INTEGER

    The number of columns of B. NRHS must be at least 1.

  • D – [inout]

    D is REAL array, dimension (N)

    On entry D contains the main diagonal of the bidiagonal matrix. On exit, if INFO = 0, D contains its singular values.

  • E – [inout]

    E is REAL array, dimension (N-1)

    Contains the super-diagonal entries of the bidiagonal matrix. On exit, E has been destroyed.

  • B – [inout]

    B is REAL array, dimension (LDB,NRHS)

    On input, B contains the right hand sides of the least squares problem. On output, B contains the solution X.

  • LDB – [in]

    LDB is INTEGER

    The leading dimension of B in the calling subprogram. LDB must be at least fla_max(1,N).

  • RCOND – [in]

    RCOND is REAL

    The singular values of A less than or equal to RCOND times the largest singular value are treated as zero in solving the least squares problem. If RCOND is negative, machine precision is used instead.

    For example, if diag(S)*X=B were the least squares problem, where diag(S) is a diagonal matrix of singular values, the solution would be X(i) = B(i) / S(i) if S(i) is greater than RCOND*max(S), and X(i) = 0 if S(i) is less than or equal to RCOND*max(S).

  • RANK – [out]

    RANK is INTEGER

    The number of singular values of A greater than RCOND times the largest singular value.

  • WORK – [out]

    WORK is REAL array, dimension at least

    (9*N + 2*N*SMLSIZ + 8*N*NLVL + N*NRHS + (SMLSIZ+1)**2),

    where NLVL = fla_max(0, INT(log_2 (N/(SMLSIZ+1))) + 1).

  • IWORK – [out] IWORK is INTEGER array, dimension at least (3*N*NLVL + 11*N)

  • INFO – [out]

    INFO is INTEGER

    = 0: successful exit.

    < 0: if INFO = -i, the i-th argument had an illegal value.

    > 0: The algorithm failed to compute a singular value while working on the submatrix lying in rows and columns INFO/(N+1) through MOD(INFO,N+1).

template<typename T, typename Ta>
void lalsd(char *uplo, integer *smlsiz, integer *n, integer *nrhs, Ta *d, Ta *e, T *b, integer *ldb, Ta *rcond, integer *rank, T *work, Ta *rwork, integer *iwork, integer *info)#