amino
Lightweight Robot Utility Library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
/home/ntd/git/amino/lapack_doc.c File Reference

Go to the source code of this file.

Functions

AA_API void dgetri_ (const int *N, double *A, const int *LDA, const int *IPIV, double *WORK, const int *LWORK, int *INFO)
 type for operations More...
 
AA_API void dgetrf_ (const int *M, const int *N, double *A, const int *LDA, int *IPIV, int *INFO)
 Computes an LU factorization of a general M-by-N matrix A using partial pivoting with row interchanges. More...
 
AA_API void dgeqrf_ (const int *M, const int *N, double *A, const int *LDA, double *TAU, double *WORK, int *LWORK, int *INFO)
 DGEQRF computes a QR factorization of a real M-by-N matrix A: A = Q * R. More...
 
AA_API void dorgqr_ (const int *M, const int *N, const int *K, double *A, const int *LDA, const double *TAU, double *WORK, const int *LWORK, int *INFO)
 Generates an M-by-N real matrix Q with orthonormal columns, which is defined as the first N columns of a product of K elementary reflectors of order M. More...
 
AA_API void dposv_ (const char UPLO[1], const int *N, const int *NRHS, double *A, const int *LDA, double *B, const int *LDB, int *INFO)
 
AA_API void dgesvd_ (const char jobu[1], const char jobvt[1], const int *m, const int *n, double *A, const int *lda, double *S, double *U, const int *ldu, double *Vt, const int *ldvt, double *work, const int *lwork, int *info)
 Compute SVD. More...
 
AA_API void dgesdd_ (const char *JOBZ, const int *M, const int *N, double *A, const int *LDA, double *S, double *U, const int *LDU, double *VT, const int *LDVT, double *WORK, const int *LWORK, int *IWORK, int *INFO)
 
AA_API int dgeev_ (const char *jobvl, const char *jobvr, int *n, double *a, int *lda, double *wr, double *wi, double *vl, int *ldvl, double *vr, int *ldvr, double *work, int *lwork, int *info)
 
AA_API void dgelsd_ (const int *M, const int *N, const int *NRHS, double *A, const int *LDA, double *B, const int *LDB, double *S, const double *RCOND, int *RANK, double *WORK, int *LWORK, int *IWORK, int *INFO)
 DGELSD computes the minimum-norm solution to a real linear least squares problem. More...
 
AA_API void dgebal_ (const char JOB[1], int *N, double *A, const int *LDA, int *ILO, int *IHI, double *SCALE, int *INFO)
 Balances a general real matrix A. More...
 
AA_API void dgees_ (const char JOBVS[1], const char SORT[1], int(*SELECT)(const double *, const double *), const int *N, double *A, const int *LDA, int *SDIM, double *WR, double *WI, double *VS, const int *LDVS, double *WORK, const int *LWORK, int *BWORK, int *INFO)
 Computes for an N-by-N real nonsymmetric matrix A, the eigenvalues, the real Schur form T, and, optionally, the matrix of Schur vectors Z. More...
 
AA_API void dgels_ (const char TRANS[1], const int *M, const int *N, const int *NRHS, double *A, const int *LDA, double *B, const int *LDB, double *WORK, const int *LWORK, int *INFO)
 Solves overdetermined or underdetermined real linear systems involving an M-by-N matrix A, or its transpose, using a QR or LQ factorization of A. More...
 
AA_API void dpotrf_ (const char UPLO[1], const int *N, double *A, const int *LDA, int *INFO)
 
AA_API void dpotrs_ (const char UPLO[1], const int *N, const int *nrhs, double *A, const int *LDA, double *B, const int *LDB, int *INFO)
 
AA_API void dlacpy_ (const char UPLO[1], const int *M, const int *N, const double *A, const int *LDA, double *B, const int *LDB)
 Copies all or part of a two-dimensional matrix A to another matrix B. More...
 
AA_API double dlapy2_ (const double *x, const double *y)
 Returns sqrt(x**2+y**2), taking care not to cause unnecessary overflow.
 
AA_API double dlapy3_ (const double *x, const double *y, const double *z)
 Returns sqrt(x**2+y**2+z**2), taking care not to cause unnecessary overflow.
 
AA_API void dlaruv_ (int ISEED[4], const int *N, double *X)
 Returns a vector of n random real numbers from a uniform (0,1) distribution (n <= 128). More...
 
AA_API void dlarnv_ (const int *IDIST, int ISEED[4], const int *N, double *X)
 Returns a vector of n random real numbers from a uniform or normal distribution. More...
 
AA_API void dlascl_ (const char TYPE[1], const int *KL, const int *KU, const double *CFROM, const double *CTO, const int *M, const int *N, double *A, const int *LDA, int *INFO)
 Multiplies the M by N real matrix A by the real scalar CTO/CFROM. More...
 
AA_API void dlaset_ (const char UPLO[1], const int *M, const int *N, const double *ALPHA, const double *BETA, double *A, const int *LDA)
 initializes an m-by-n matrix A to BETA on the diagonal and ALPHA on the offdiagonals. More...
 
AA_API void dlag2s_ (const int *M, const int *N, double *A, const int *LDA, float *SA, const int *LDSA, const int *INFO)
 Converts a DOUBLE PRECISION matrix, SA, to a SINGLE PRECISION matrix, A. More...
 
AA_API void slag2d_ (const int *M, const int *N, float *SA, const int *LDSA, double *A, const int *LDA, const int *INFO)
 Converts a SINGLE PRECISION matrix, SA, to a DOUBLE PRECISION matrix, A. More...
 
AA_API void sgetri_ (const int *N, float *A, const int *LDA, const int *IPIV, float *WORK, const int *LWORK, int *INFO)
 type for operations More...
 
AA_API void sgetrf_ (const int *M, const int *N, float *A, const int *LDA, int *IPIV, int *INFO)
 Computes an LU factorization of a general M-by-N matrix A using partial pivoting with row interchanges. More...
 
AA_API void sgeqrf_ (const int *M, const int *N, float *A, const int *LDA, float *TAU, float *WORK, int *LWORK, int *INFO)
 DGEQRF computes a QR factorization of a real M-by-N matrix A: A = Q * R. More...
 
AA_API void sorgqr_ (const int *M, const int *N, const int *K, float *A, const int *LDA, const float *TAU, float *WORK, const int *LWORK, int *INFO)
 Generates an M-by-N real matrix Q with orthonormal columns, which is defined as the first N columns of a product of K elementary reflectors of order M. More...
 
AA_API void sposv_ (const char UPLO[1], const int *N, const int *NRHS, float *A, const int *LDA, float *B, const int *LDB, int *INFO)
 
AA_API void sgesvd_ (const char jobu[1], const char jobvt[1], const int *m, const int *n, float *A, const int *lda, float *S, float *U, const int *ldu, float *Vt, const int *ldvt, float *work, const int *lwork, int *info)
 Compute SVD. More...
 
AA_API void sgesdd_ (const char *JOBZ, const int *M, const int *N, float *A, const int *LDA, float *S, float *U, const int *LDU, float *VT, const int *LDVT, float *WORK, const int *LWORK, int *IWORK, int *INFO)
 
AA_API int sgeev_ (const char *jobvl, const char *jobvr, int *n, float *a, int *lda, float *wr, float *wi, float *vl, int *ldvl, float *vr, int *ldvr, float *work, int *lwork, int *info)
 
AA_API void sgelsd_ (const int *M, const int *N, const int *NRHS, float *A, const int *LDA, float *B, const int *LDB, float *S, const float *RCOND, int *RANK, float *WORK, int *LWORK, int *IWORK, int *INFO)
 DGELSD computes the minimum-norm solution to a real linear least squares problem. More...
 
AA_API void sgebal_ (const char JOB[1], int *N, float *A, const int *LDA, int *ILO, int *IHI, float *SCALE, int *INFO)
 Balances a general real matrix A. More...
 
AA_API void sgees_ (const char JOBVS[1], const char SORT[1], int(*SELECT)(const float *, const float *), const int *N, float *A, const int *LDA, int *SDIM, float *WR, float *WI, float *VS, const int *LDVS, float *WORK, const int *LWORK, int *BWORK, int *INFO)
 Computes for an N-by-N real nonsymmetric matrix A, the eigenvalues, the real Schur form T, and, optionally, the matrix of Schur vectors Z. More...
 
AA_API void sgels_ (const char TRANS[1], const int *M, const int *N, const int *NRHS, float *A, const int *LDA, float *B, const int *LDB, float *WORK, const int *LWORK, int *INFO)
 Solves overdetermined or underdetermined real linear systems involving an M-by-N matrix A, or its transpose, using a QR or LQ factorization of A. More...
 
AA_API void spotrf_ (const char UPLO[1], const int *N, float *A, const int *LDA, int *INFO)
 
AA_API void spotrs_ (const char UPLO[1], const int *N, const int *nrhs, float *A, const int *LDA, float *B, const int *LDB, int *INFO)
 
AA_API void slacpy_ (const char UPLO[1], const int *M, const int *N, const float *A, const int *LDA, float *B, const int *LDB)
 Copies all or part of a two-dimensional matrix A to another matrix B. More...
 
AA_API float slapy2_ (const float *x, const float *y)
 Returns sqrt(x**2+y**2), taking care not to cause unnecessary overflow.
 
AA_API float slapy3_ (const float *x, const float *y, const float *z)
 Returns sqrt(x**2+y**2+z**2), taking care not to cause unnecessary overflow.
 
AA_API void slaruv_ (int ISEED[4], const int *N, float *X)
 Returns a vector of n random real numbers from a uniform (0,1) distribution (n <= 128). More...
 
AA_API void slarnv_ (const int *IDIST, int ISEED[4], const int *N, float *X)
 Returns a vector of n random real numbers from a uniform or normal distribution. More...
 
AA_API void slascl_ (const char TYPE[1], const int *KL, const int *KU, const float *CFROM, const float *CTO, const int *M, const int *N, float *A, const int *LDA, int *INFO)
 Multiplies the M by N real matrix A by the real scalar CTO/CFROM. More...
 
AA_API void slaset_ (const char UPLO[1], const int *M, const int *N, const float *ALPHA, const float *BETA, float *A, const int *LDA)
 initializes an m-by-n matrix A to BETA on the diagonal and ALPHA on the offdiagonals. More...
 
AA_API int ilaenv_ (const int *ispec, const char *name, const char *opts, const int *n1, const int *n2, const int *n3, const int *n4, int name_length, int opts_length)
 ILAENV is called from the LAPACK routines to choose problem-dependent parameters for the local environment. More...
 

Function Documentation

AA_API void dgebal_ ( const char  JOB[1],
int *  N,
double *  A,
const int *  LDA,
int *  ILO,
int *  IHI,
double *  SCALE,
int *  INFO 
)

Balances a general real matrix A.

This involves, first, permuting A by a similarity transformation to isolate eigenvalues in the first 1 to ILO-1 and last IHI+1 to N elements on the diagonal; and second, applying a diagonal similarity transformation to rows and columns ILO to IHI to make the rows and columns as close in norm as possible. Both steps are optional.

Balancing may reduce the 1-norm of the matrix, and improve the accuracy of the computed eigenvalues and/or eigenvectors.

Parameters
[in]JOBSpecifies the operations to be performed on A:
  • = 'N': none: simply set ILO = 1, IHI = N, SCALE(I) = 1.0 for i = 1,...,N;
  • = 'P': permute only;
  • = 'S': scale only;
  • = 'B': both permute and scale.
[in]NThe order of the matrix A. N >= 0.
[in,out]Adimension (LDA,N) On entry, the input matrix A. On exit, A is overwritten by the balanced matrix. If JOB = 'N', A is not referenced. See Further Details.
[in]LDAThe leading dimension of the array A. LDA >= max(1,N).
[out]ILO
[out]IHIILO and IHI are set to integers such that on exit A(i,j) = 0 if i > j and j = 1,...,ILO-1 or I = IHI+1,...,N. If JOB = 'N' or 'S', ILO = 1 and IHI = N.
[out]SCALEdimension (N) Details of the permutations and scaling factors applied to A. If P(j) is the index of the row and column interchanged with row and column j and D(j) is the scaling factor applied to row and column j, then SCALE(j) = P(j) for j = 1,...,ILO-1 = D(j) for j = ILO,...,IHI = P(j) for j = IHI+1,...,N. The order in which the interchanges are made is N to IHI+1, then 1 to ILO-1.
[out]INFO
  • = 0: successful exit.
  • < 0: if INFO = -i, the i-th argument had an illegal value.
AA_API void dgees_ ( const char  JOBVS[1],
const char  SORT[1],
int(*)(const double *, const double *)  SELECT,
const int *  N,
double *  A,
const int *  LDA,
int *  SDIM,
double *  WR,
double *  WI,
double *  VS,
const int *  LDVS,
double *  WORK,
const int *  LWORK,
int *  BWORK,
int *  INFO 
)

Computes for an N-by-N real nonsymmetric matrix A, the eigenvalues, the real Schur form T, and, optionally, the matrix of Schur vectors Z.

This gives the Schur factorization A = Z*T*(Z**T).

Optionally, it also orders the eigenvalues on the diagonal of the real Schur form so that selected eigenvalues are at the top left. The leading columns of Z then form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues.

A matrix is in real Schur form if it is upper quasi-triangular with 1-by-1 and 2-by-2 blocks. 2-by-2 blocks will be standardized in the form [ a b ] [ c a ]

where b*c < 0. The eigenvalues of such a block are a +- sqrt(bc).

Parameters
[in]JOBVS
  • = 'N': Schur vectors are not computed;
  • = 'V': Schur vectors are computed.
[in]SORTSpecifies whether or not to order the eigenvalues on the diagonal of the Schur form.
  • = 'N': Eigenvalues are not ordered;
  • = 'S': Eigenvalues are ordered (see SELECT).
[in]SELECTSELECT must be declared EXTERNAL in the calling subroutine. If SORT = 'S', SELECT is used to select eigenvalues to sort to the top left of the Schur form. If SORT = 'N', SELECT is not referenced. An eigenvalue WR(j)+sqrt(-1)*WI(j) is selected if SELECT(WR(j),WI(j)) is true; i.e., if either one of a complex conjugate pair of eigenvalues is selected, then both complex eigenvalues are selected. Note that a selected complex eigenvalue may no longer satisfy SELECT(WR(j),WI(j)) = .TRUE. after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case INFO is set to N+2 (see INFO below).
[in]NThe order of the matrix A. N >= 0.
[in,out]Adimension (LDA,N) On entry, the N-by-N matrix A. On exit, A has been overwritten by its real Schur form T.
[in]LDAThe leading dimension of the array A. LDA >= max(1,N).
[out]SDIM
  • If SORT = 'N', SDIM = 0.
  • If SORT = 'S', SDIM = number of eigenvalues (after sorting) for which SELECT is true. (Complex conjugate pairs for which SELECT is true for either eigenvalue count as 2.)
[out]WRdimension (N)
[out]WIdimension (N) WR and WI contain the real and imaginary parts, respectively, of the computed eigenvalues in the same order that they appear on the diagonal of the output Schur form T. Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first.
[out]VSdimension (LDVS,N)
  • If JOBVS = 'V', VS contains the orthogonal matrix Z of Schur vectors.
  • If JOBVS = 'N', VS is not referenced.
[in]LDVSThe leading dimension of the array VS. LDVS >= 1; if JOBVS = 'V', LDVS >= N.
[out]WORKdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) contains the optimal LWORK.
[in]LWORKThe dimension of the array WORK. LWORK >= max(1,3*N). For good performance, LWORK must generally be larger.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.

Parameters
BWORKdimension (N) Not referenced if SORT = 'N'.
[out]INFO
  • = 0: successful exit
  • < 0: if INFO = -i, the i-th argument had an illegal value.
  • > 0: if INFO = i, and i is <= N: the QR algorithm failed to compute all the eigenvalues; elements 1:ILO-1 and i+1:N of WR and WI contain those eigenvalues which have converged; if JOBVS = 'V', VS contains the matrix which reduces A to its partially converged Schur form. = N+1: the eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned); = N+2: after reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy SELECT=.TRUE. This could also be caused by underflow due to scaling.
AA_API void dgels_ ( const char  TRANS[1],
const int *  M,
const int *  N,
const int *  NRHS,
double *  A,
const int *  LDA,
double *  B,
const int *  LDB,
double *  WORK,
const int *  LWORK,
int *  INFO 
)

Solves overdetermined or underdetermined real linear systems involving an M-by-N matrix A, or its transpose, using a QR or LQ factorization of A.

It is assumed that A has full rank.

The following options are provided:

  • 1. If TRANS = 'N' and m >= n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem minimize || B - A*X ||.
  • 2. If TRANS = 'N' and m < n: find the minimum norm solution of an underdetermined system A * X = B.
  • 3. If TRANS = 'T' and m >= n: find the minimum norm solution of an undetermined system A**T * X = B.
  • 4. If TRANS = 'T' and m < n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem minimize || B - A**T * X ||.

Several right hand side vectors b and solution vectors x can be handled in a single call; they are stored as the columns of the M-by-NRHS right hand side matrix B and the N-by-NRHS solution matrix X.

Parameters
[in]TRANS
  • = 'N': the linear system involves A;
  • = 'T': the linear system involves A**T.
[in]MThe number of rows of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[in]NRHSThe number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >=0.
[in,out]Adimension (LDA,N) On entry, the M-by-N matrix A. On exit,
  • if M >= N, A is overwritten by details of its QR factorization as returned by DGEQRF;
  • if M < N, A is overwritten by details of its LQ factorization as returned by DGELQF.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[in,out]Bdimension (LDB,NRHS) On entry, the matrix B of right hand side vectors, stored columnwise; B is M-by-NRHS if TRANS = 'N', or N-by-NRHS
  • if TRANS = 'T'. On exit, if INFO = 0, B is overwritten by the solution vectors, stored columnwise:
  • if TRANS = 'N' and m >= n, rows 1 to n of B contain the least squares solution vectors; the residual sum of squares for the solution in each column is given by the sum of squares of elements N+1 to M in that column;
  • if TRANS = 'N' and m < n, rows 1 to N of B contain the minimum norm solution vectors;
  • if TRANS = 'T' and m >= n, rows 1 to M of B contain the minimum norm solution vectors;
  • if TRANS = 'T' and m < n, rows 1 to M of B contain the least squares solution vectors; the residual sum of squares for the solution in each column is given by the sum of squares of elements M+1 to N in that column.
[in]LDBThe leading dimension of the array B. LDB >= MAX(1,M,N).
WORKdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
[in]LWORKThe dimension of the array WORK. LWORK >= max( 1, MN + max( MN, NRHS ) ). For optimal performance, LWORK >= max( 1, MN + max( MN, NRHS )*NB ). where MN = min(M,N) and NB is the optimum block size. If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.
[out]INFO
  • = 0: successful exit
  • < 0: if INFO = -i, the i-th argument had an illegal value
  • > 0: if INFO = i, the i-th diagonal element of the triangular factor of A is zero, so that A does not have full rank; the least squares solution could not be computed.
AA_API void dgelsd_ ( const int *  M,
const int *  N,
const int *  NRHS,
double *  A,
const int *  LDA,
double *  B,
const int *  LDB,
double *  S,
const double *  RCOND,
int *  RANK,
double *  WORK,
int *  LWORK,
int *  IWORK,
int *  INFO 
)

DGELSD computes the minimum-norm solution to a real linear least squares problem.

Minimizes \(| b - A*x |\) using the singular value decomposition (SVD) of A. A is an M-by-N matrix which may be rank-deficient.

Several right hand side vectors b and solution vectors x can be handled in a single call; they are stored as the columns of the M-by-NRHS right hand side matrix B and the N-by-NRHS solution matrix X.

The problem is solved in three steps:

  • (1) Reduce the coefficient matrix A to bidiagonal form with Householder transformations, reducing the original problem into a "bidiagonal least squares problem" (BLS)
  • (2) Solve the BLS using a divide and conquer approach.
  • (3) Apply back all the Householder tranformations to solve the original least squares problem.

The effective rank of A is determined by treating as zero those singular values which are less than RCOND times the largest singular value.

The divide and conquer algorithm 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 X-MP, Cray Y-MP, Cray C-90, or Cray-2. It could conceivably fail on hexadecimal or decimal machines without guard digits, but we know of none.

Parameters
[in]MThe number of rows of A. M >= 0.
[in]NThe number of columns of A. N >= 0.
[in]NRHSThe number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
[in]Adimension (LDA,N) On entry, the M-by-N matrix A. On exit, A has been destroyed.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[in,out]Bdimension (LDB,NRHS) On entry, the M-by-NRHS right hand side matrix B. On exit, B is overwritten by the N-by-NRHS solution matrix X. If m >= n and RANK = n, the residual sum-of-squares for the solution in the i-th column is given by the sum of squares of elements n+1:m in that column.
[in]LDBThe leading dimension of the array B. LDB >= max(1,max(M,N)).
[out]Sdimension (min(M,N)) The singular values of A in decreasing order. The condition number of A in the 2-norm = S(1)/S(min(m,n)).
[in]RCONDRCOND is used to determine the effective rank of A. Singular values S(i) <= RCOND*S(1) are treated as zero. If RCOND < 0, machine precision is used instead.
[out]RANKThe effective rank of A, i.e., the number of singular values which are greater than RCOND*S(1).
[out]WORKdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
[in]LWORKThe dimension of the array WORK. LWORK must be at least 1. The exact minimum amount of workspace needed depends on M, N and NRHS. As long as LWORK is at least 12*N + 2*N*SMLSIZ + 8*N*NLVL + N*NRHS + (SMLSIZ+1)**2, if M is greater than or equal to N or 12*M + 2*M*SMLSIZ + 8*M*NLVL + M*NRHS + (SMLSIZ+1)**2, if M is less than N, the code will execute correctly. SMLSIZ is returned by ILAENV and is equal to the maximum size of the subproblems at the bottom of the computation tree (usually about 25), and NLVL = MAX( 0, INT( LOG_2( MIN( M,N )/(SMLSIZ+1) ) ) + 1 ) For good performance, LWORK should generally be larger. If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.
[out]IWORKdimension (MAX(1,LIWORK)) LIWORK >= max(1, 3 * MINMN * NLVL + 11 * MINMN), where MINMN = MIN( M,N ). On exit, if INFO = 0, IWORK(1) returns the minimum LIWORK.
[out]INFO
  • = 0: successful exit
  • < 0: if INFO = -i, the i-th argument had an illegal value.
  • > 0: the algorithm for computing the SVD failed to converge; if INFO = i, i off-diagonal elements of an intermediate bidiagonal form did not converge to zero.
AA_API void dgeqrf_ ( const int *  M,
const int *  N,
double *  A,
const int *  LDA,
double *  TAU,
double *  WORK,
int *  LWORK,
int *  INFO 
)

DGEQRF computes a QR factorization of a real M-by-N matrix A: A = Q * R.

Arguments

Parameters
[in]MThe number of rows of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[in,out]Adimension (LDA,N) On entry, the M-by-N matrix A. On exit, the elements on and above the diagonal of the array contain the min(M,N)-by-N upper trapezoidal matrix R (R is upper triangular if m >= n); the elements below the diagonal, with the array TAU, represent the orthogonal matrix Q as a product of min(m,n) elementary reflectors (see Further Details).
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[out]TAUdimension (min(M,N)) The scalar factors of the elementary reflectors (see Further Details).
[out]WORKdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
[in]LWORKThe dimension of the array WORK. LWORK >= max(1,N). For optimum performance LWORK >= N*NB, where NB is the optimal blocksize.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.

Parameters
[out]INFO= 0: successful exit

Further Details

The matrix Q is represented as a product of elementary reflectors

Q = H(1) H(2) . . . H(k), where k = min(m,n).

Each H(i) has the form

H(i) = I - tau * v * v'

where tau is a real scalar, and v is a real vector with v(1:i-1) = 0 and v(i) = 1; v(i+1:m) is stored on exit in A(i+1:m,i), and tau in TAU(i).

AA_API void dgesvd_ ( const char  jobu[1],
const char  jobvt[1],
const int *  m,
const int *  n,
double *  A,
const int *  lda,
double *  S,
double *  U,
const int *  ldu,
double *  Vt,
const int *  ldvt,
double *  work,
const int *  lwork,
int *  info 
)

Compute SVD.

Parameters
[in]jobuSpecifies options for computing all or part of the matrix U:
  • = 'A': all M columns of U are returned in array U:
  • = 'S': the first min(m,n) columns of U (the left singular vectors) are returned in the array U;
  • = 'O': the first min(m,n) columns of U (the left singular vectors) are overwritten on the array A;
  • = 'N': no columns of U (no left singular vectors) are computed.
[in]jobvtSpecifies options for computing all or part of the matrix V**T:
  • = 'A': all N rows of V**T are returned in the array VT;
  • = 'S': the first min(m,n) rows of V**T (the right singular vectors) are returned in the array VT;
  • = 'O': the first min(m,n) rows of V**T (the right singular vectors) are overwritten on the array A;
  • = 'N': no rows of V**T (no right singular vectors) are computed. JOBVT and JOBU cannot both be 'O'.
[in]mThe number of rows of the input matrix A. M >= 0.
[in]nThe number of columns of the input matrix A. N >= 0.
[in,out]AOn entry, the M-by-N matrix A. On exit,
  • if JOBU = 'O', A is overwritten with the first min(m,n) columns of U (the left singular vectors, stored columnwise);
  • if JOBVT = 'O', A is overwritten with the first min(m,n) rows of V**T (the right singular vectors, stored rowwise);
  • if JOBU .ne. 'O' and JOBVT .ne. 'O', the contents of A are destroyed.
[in]ldaThe leading dimension of the array A. LDA >= max(1,M).
[out]SThe singular values of A, sorted so that S(i) >= S(i+1). dimension (min(M,N))
[out]Udimension (LDU,UCOL) (LDU,M) if JOBU = 'A' or (LDU,min(M,N)) if JOBU = 'S'.
  • If JOBU = 'A', U contains the M-by-M orthogonal matrix U;
  • if JOBU = 'S', U contains the first min(m,n) columns of U (the left singular vectors, stored columnwise);
  • if JOBU = 'N' or 'O', U is not referenced.
[in]lduThe leading dimension of the array U. LDU >= 1; if JOBU = 'S' or 'A', LDU >= M.
[out]Vtdimension (LDVT,N)
  • If JOBVT = 'A', VT contains the N-by-N orthogonal matrix V**T;
  • if JOBVT = 'S', VT contains the first min(m,n) rows of V**T (the right singular vectors, stored rowwise);
  • if JOBVT = 'N' or 'O', VT is not referenced.
[in]ldvtThe leading dimension of the array VT. LDVT >= 1; if JOBVT = 'A', LDVT >= N; if JOBVT = 'S', LDVT >= min(M,N).
[out]workdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK; if INFO > 0, WORK(2:MIN(M,N)) contains the unconverged superdiagonal elements of an upper bidiagonal matrix B whose diagonal is in S (not necessarily sorted). B satisfies A = U * B * VT, so it has the same singular values as A, and singular vectors related by U and VT.
[in]lworkThe dimension of the array WORK. LWORK >= MAX(1,3*MIN(M,N)+MAX(M,N),5*MIN(M,N)). For good performance, LWORK should generally be larger. If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.
[out]info
  • = 0: successful exit.
  • < 0: if INFO = -i, the i-th argument had an illegal value.
  • > 0: if DBDSQR did not converge, INFO specifies how many superdiagonals of an intermediate bidiagonal form B did not converge to zero. See the description of WORK above for details.
AA_API void dgetrf_ ( const int *  M,
const int *  N,
double *  A,
const int *  LDA,
int *  IPIV,
int *  INFO 
)

Computes an LU factorization of a general M-by-N matrix A using partial pivoting with row interchanges.

The factorization has the form

\[ A = P * L * U \]

where P is a permutation matrix, L is lower triangular with unit diagonal elements (lower trapezoidal if m > n), and U is upper triangular (upper trapezoidal if m < n).

This is the right-looking Level 3 BLAS version of the algorithm.

Parameters
[in]MThe number of rows of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[in,out]AOn entry, the M-by-N matrix to be factored. On exit, the factors L and U from the factorization A = P*L*U; the unit diagonal elements of L are not stored.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[out]IPIVarray, dimension (min(M,N)) The pivot indices; for 1 <= i <= min(M,N), row i of the matrix was interchanged with row IPIV(i).
[out]INFO
  • = 0: successful exit
  • < 0: if INFO = -i, the i-th argument had an illegal value
  • > 0: if INFO = i, U(i,i) is exactly zero. The factorization has been completed, but the factor U is exactly singular, and division by zero will occur if it is used to solve a system of equations.
AA_API void dgetri_ ( const int *  N,
double *  A,
const int *  LDA,
const int *  IPIV,
double *  WORK,
const int *  LWORK,
int *  INFO 
)

type for operations

Inverse of matrix using LU factorization by *getrf.

You must call *getrf before you call *getri.

Parameters
[in]NOrder of the matrix A
[in,out]Aon entry the L and U factors from *getrf, on exit the inverse of the original A
[in]LDAnumber of rows in A
[in]IPIVpivot indices from sgetrf
WORKworkspace array
[in]LWORKlength of work, optimally > n*nb where nb is the optimal blocksize return by ilaenv_
[out]INFOoutput. info==0 for success, info<zero for illegal argument, info > 0 for singular matrix
AA_API void dlacpy_ ( const char  UPLO[1],
const int *  M,
const int *  N,
const double *  A,
const int *  LDA,
double *  B,
const int *  LDB 
)

Copies all or part of a two-dimensional matrix A to another matrix B.

Parameters
[in]UPLOSpecifies the part of the matrix A to be copied to B.
  • = 'U': Upper triangular part
  • = 'L': Lower triangular part
  • Otherwise: All of the matrix A
[in]MThe number of rows of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[in]Adimension (LDA,N) The m by n matrix A. If UPLO = 'U', only the upper triangle or trapezoid is accessed; if UPLO = 'L', only the lower triangle or trapezoid is accessed.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[out]Bdimension (LDB,N) On exit, B = A in the locations specified by UPLO.
[in]LDBThe leading dimension of the array B. LDB >= max(1,M).
AA_API void dlag2s_ ( const int *  M,
const int *  N,
double *  A,
const int *  LDA,
float *  SA,
const int *  LDSA,
const int *  INFO 
)

Converts a DOUBLE PRECISION matrix, SA, to a SINGLE PRECISION matrix, A.

This is a helper routine so there is no argument checking.

Parameters
[in]MThe number of lines of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[in]AOn entry, the M-by-N coefficient matrix A.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[out]SAOn exit, if INFO=0, the M-by-N coefficient matrix SA.
[in]LDSAThe leading dimension of the array SA. LDSA >= max(1,M).
[out]INFO
  • = 0: successful exit
  • > 0: if INFO = k, the (i,j) entry of the matrix A has overflowed when moving from DOUBLE PRECISION to SINGLE k is given by k = (i-1)*LDA+j
AA_API void dlarnv_ ( const int *  IDIST,
int  ISEED[4],
const int *  N,
double *  X 
)

Returns a vector of n random real numbers from a uniform or normal distribution.

Parameters
[in]IDISTSpecifies the distribution of the random numbers:
  • = 1: uniform (0,1)
  • = 2: uniform (-1,1)
  • = 3: normal (0,1)
[in,out]ISEEDOn entry, the seed of the random number generator; the array elements must be between 0 and 4095, and ISEED(4) must be odd. On exit, the seed is updated.
[in]NThe number of random numbers to be generated.
[out]XThe generated random numbers.

This routine calls the auxiliary routine DLARUV to generate random real numbers from a uniform (0,1) distribution, in batches of up to 128 using vectorisable code. The Box-Muller method is used to transform numbers from a uniform to a normal distribution.

AA_API void dlaruv_ ( int  ISEED[4],
const int *  N,
double *  X 
)

Returns a vector of n random real numbers from a uniform (0,1) distribution (n <= 128).

This is an auxiliary routine called by DLARNV and ZLARNV.

Parameters
[in,out]ISEEDISEED is INTEGER array, dimension (4) On entry, the seed of the random number generator; the array elements must be between 0 and 4095, and ISEED(4) must be odd. On exit, the seed is updated.
[in]NN is INTEGER The number of random numbers to be generated. N <= 128.
[out]XX is AA_TYPE PRECISION array, dimension (N) The generated random numbers.
Author
Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.
Date
November 2011

This routine uses a multiplicative congruential method with modulus 2**48 and multiplier 33952834046453 (see G.S.Fishman, 'Multiplicative congruential random number generators with modulus 2**b: an exhaustive analysis for b = 32 and a partial analysis for b = 48', Math. Comp. 189, pp 331-344, 1990).

48-bit integers are stored in 4 integer array elements with 12 bits per element. Hence the routine is portable across machines with integers of 32 bits or more.

AA_API void dlascl_ ( const char  TYPE[1],
const int *  KL,
const int *  KU,
const double *  CFROM,
const double *  CTO,
const int *  M,
const int *  N,
double *  A,
const int *  LDA,
int *  INFO 
)

Multiplies the M by N real matrix A by the real scalar CTO/CFROM.

k This is done without over/underflow as long as the final result CTO*A(I,J)/CFROM does not over/underflow. TYPE specifies that A may be full, upper triangular, lower triangular, upper Hessenberg, or banded.

Parameters
[in]TYPETYPE indices the storage type of the input matrix.
  • = 'G': A is a full matrix.
  • = 'L': A is a lower triangular matrix.
  • = 'U': A is an upper triangular matrix.
  • = 'H': A is an upper Hessenberg matrix.
  • = 'B': A is a symmetric band matrix with lower bandwidth KL and upper bandwidth KU and with the only the lower half stored.
  • = 'Q': A is a symmetric band matrix with lower bandwidth KL and upper bandwidth KU and with the only the upper half stored.
  • = 'Z': A is a band matrix with lower bandwidth KL and upper bandwidth KU.
[in]KLThe lower bandwidth of A. Referenced only if TYPE = 'B', 'Q' or 'Z'.
[in]KUThe upper bandwidth of A. Referenced only if TYPE = 'B', 'Q' or 'Z'.
[in]CFROM
[in]CTOThe matrix A is multiplied by CTO/CFROM. A(I,J) is computed without over/underflow if the final result CTO*A(I,J)/CFROM can be represented without over/underflow. CFROM must be nonzero.
[in]MThe number of rows of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[in,out]AThe matrix to be multiplied by CTO/CFROM. See TYPE for the storage type.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[out]INFO(output) INTEGER
  • 0 - successful exit
  • <0 - if INFO = -i, the i-th argument had an illegal value.
AA_API void dlaset_ ( const char  UPLO[1],
const int *  M,
const int *  N,
const double *  ALPHA,
const double *  BETA,
double *  A,
const int *  LDA 
)

initializes an m-by-n matrix A to BETA on the diagonal and ALPHA on the offdiagonals.

Parameters
[in]UPLOUPLO is CHARACTER*1. Specifies the part of the matrix A to be set.
  • = 'U': Upper triangular part is set; the strictly lower triangular part of A is not changed.
  • = 'L': Lower triangular part is set; the strictly upper triangular part of A is not changed.
  • Otherwise: All of the matrix A is set.
[in]MM is INTEGER. The number of rows of the matrix A. M >= 0.
[in]NN is INTEGER. The number of columns of the matrix A. N >= 0.
[in]ALPHAALPHA is DOUBLE PRECISION. The constant to which the offdiagonal elements are to be set.
[in]BETABETA is DOUBLE PRECISION. The constant to which the diagonal elements are to be set.
[in,out]AA is DOUBLE PRECISION array, dimension (LDA,N). On exit, the leading m-by-n submatrix of A is set as follows:
  • if UPLO = 'U', A(i,j) = ALPHA, 1<=i<=j-1, 1<=j<=n,
  • if UPLO = 'L', A(i,j) = ALPHA, j+1<=i<=m, 1<=j<=n,
  • otherwise, A(i,j) = ALPHA, 1<=i<=m, 1<=j<=n, i.ne.j, and, for all UPLO, A(i,i) = BETA, 1<=i<=min(m,n).
[in]LDALDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
Author
Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.
Date
November 2011
AA_API void dorgqr_ ( const int *  M,
const int *  N,
const int *  K,
double *  A,
const int *  LDA,
const double *  TAU,
double *  WORK,
const int *  LWORK,
int *  INFO 
)

Generates an M-by-N real matrix Q with orthonormal columns, which is defined as the first N columns of a product of K elementary reflectors of order M.

Q = H(1) H(2) . . . H(k)

as returned by xGEQRF.

Parameters
[in]MThe number of rows of the matrix Q. M >= 0.
[in]NThe number of columns of the matrix Q. M >= N >= 0.
[in]KThe number of elementary reflectors whose product defines the matrix Q. N >= K >= 0.
[in,out]Adimension (LDA,N) On entry, the i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by DGEQRF in the first k columns of its array argument A. On exit, the M-by-N matrix Q.
[in]LDAThe first dimension of the array A. LDA >= max(1,M).
[in]TAUdimension (K) TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by DGEQRF.
[out]WORKdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
[in]LWORKThe dimension of the array WORK. LWORK >= max(1,N). For optimum performance LWORK >= N*NB, where NB is the optimal blocksize.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.

Parameters
[out]INFO= 0: successful exit < 0: if INFO = -i, the i-th argument has an illegal value
AA_API int ilaenv_ ( const int *  ispec,
const char *  name,
const char *  opts,
const int *  n1,
const int *  n2,
const int *  n3,
const int *  n4,
int  name_length,
int  opts_length 
)

ILAENV is called from the LAPACK routines to choose problem-dependent parameters for the local environment.

Parameters
ispecSpecifies the parameter to be returned as the value of ILAENV.
  • = 1: the optimal blocksize; if this value is 1, an unblocked algorithm will give the best performance.
  • = 2: the minimum block size for which the block routine should be used; if the usable block size is less than this value, an unblocked routine should be used.
  • = 3: the crossover point (in a block routine, for N less than this value, an unblocked routine should be used)
  • = 4: the number of shifts, used in the nonsymmetric eigenvalue routines (DEPRECATED)
  • = 5: the minimum column dimension for blocking to be used; rectangular blocks must have dimension at least k by m, where k is given by ILAENV(2,...) and m by ILAENV(5,...)
  • = 6: the crossover point for the SVD (when reducing an m by n matrix to bidiagonal form, if max(m,n)/min(m,n) exceeds this value, a QR factorization is used first to reduce the matrix to a triangular form.)
  • = 7: the number of processors
  • = 8: the crossover point for the multishift QR method for nonsymmetric eigenvalue problems (DEPRECATED)
  • = 9: maximum size of the subproblems at the bottom of the computation tree in the divide-and-conquer algorithm (used by xGELSD and xGESDD)
  • =10: ieee NaN arithmetic can be trusted not to trap
  • =11: infinity arithmetic can be trusted not to trap
  • 12 <= ISPEC <= 16: xHSEQR or one of its subroutines, see IPARMQ for detailed explanation
nameThe name of the calling subroutine, in either upper case or lower case.
optsThe character options to the subroutine NAME, concatenated into a single character string. For example, UPLO = 'U', TRANS = 'T', and DIAG = 'N' for a triangular routine would be specified as OPTS = 'UTN'.
n1(input) INTEGER
n2(input) INTEGER
n3(input) INTEGER
n4(input) INTEGER Problem dimensions for the subroutine NAME; these may not all be required.
name_lengthfortran string brain damage, length of name
opts_lengthfortran string brain damage, length of opts
AA_API void sgebal_ ( const char  JOB[1],
int *  N,
float *  A,
const int *  LDA,
int *  ILO,
int *  IHI,
float *  SCALE,
int *  INFO 
)

Balances a general real matrix A.

This involves, first, permuting A by a similarity transformation to isolate eigenvalues in the first 1 to ILO-1 and last IHI+1 to N elements on the diagonal; and second, applying a diagonal similarity transformation to rows and columns ILO to IHI to make the rows and columns as close in norm as possible. Both steps are optional.

Balancing may reduce the 1-norm of the matrix, and improve the accuracy of the computed eigenvalues and/or eigenvectors.

Parameters
[in]JOBSpecifies the operations to be performed on A:
  • = 'N': none: simply set ILO = 1, IHI = N, SCALE(I) = 1.0 for i = 1,...,N;
  • = 'P': permute only;
  • = 'S': scale only;
  • = 'B': both permute and scale.
[in]NThe order of the matrix A. N >= 0.
[in,out]Adimension (LDA,N) On entry, the input matrix A. On exit, A is overwritten by the balanced matrix. If JOB = 'N', A is not referenced. See Further Details.
[in]LDAThe leading dimension of the array A. LDA >= max(1,N).
[out]ILO
[out]IHIILO and IHI are set to integers such that on exit A(i,j) = 0 if i > j and j = 1,...,ILO-1 or I = IHI+1,...,N. If JOB = 'N' or 'S', ILO = 1 and IHI = N.
[out]SCALEdimension (N) Details of the permutations and scaling factors applied to A. If P(j) is the index of the row and column interchanged with row and column j and D(j) is the scaling factor applied to row and column j, then SCALE(j) = P(j) for j = 1,...,ILO-1 = D(j) for j = ILO,...,IHI = P(j) for j = IHI+1,...,N. The order in which the interchanges are made is N to IHI+1, then 1 to ILO-1.
[out]INFO
  • = 0: successful exit.
  • < 0: if INFO = -i, the i-th argument had an illegal value.
AA_API void sgees_ ( const char  JOBVS[1],
const char  SORT[1],
int(*)(const float *, const float *)  SELECT,
const int *  N,
float *  A,
const int *  LDA,
int *  SDIM,
float *  WR,
float *  WI,
float *  VS,
const int *  LDVS,
float *  WORK,
const int *  LWORK,
int *  BWORK,
int *  INFO 
)

Computes for an N-by-N real nonsymmetric matrix A, the eigenvalues, the real Schur form T, and, optionally, the matrix of Schur vectors Z.

This gives the Schur factorization A = Z*T*(Z**T).

Optionally, it also orders the eigenvalues on the diagonal of the real Schur form so that selected eigenvalues are at the top left. The leading columns of Z then form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues.

A matrix is in real Schur form if it is upper quasi-triangular with 1-by-1 and 2-by-2 blocks. 2-by-2 blocks will be standardized in the form [ a b ] [ c a ]

where b*c < 0. The eigenvalues of such a block are a +- sqrt(bc).

Parameters
[in]JOBVS
  • = 'N': Schur vectors are not computed;
  • = 'V': Schur vectors are computed.
[in]SORTSpecifies whether or not to order the eigenvalues on the diagonal of the Schur form.
  • = 'N': Eigenvalues are not ordered;
  • = 'S': Eigenvalues are ordered (see SELECT).
[in]SELECTSELECT must be declared EXTERNAL in the calling subroutine. If SORT = 'S', SELECT is used to select eigenvalues to sort to the top left of the Schur form. If SORT = 'N', SELECT is not referenced. An eigenvalue WR(j)+sqrt(-1)*WI(j) is selected if SELECT(WR(j),WI(j)) is true; i.e., if either one of a complex conjugate pair of eigenvalues is selected, then both complex eigenvalues are selected. Note that a selected complex eigenvalue may no longer satisfy SELECT(WR(j),WI(j)) = .TRUE. after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case INFO is set to N+2 (see INFO below).
[in]NThe order of the matrix A. N >= 0.
[in,out]Adimension (LDA,N) On entry, the N-by-N matrix A. On exit, A has been overwritten by its real Schur form T.
[in]LDAThe leading dimension of the array A. LDA >= max(1,N).
[out]SDIM
  • If SORT = 'N', SDIM = 0.
  • If SORT = 'S', SDIM = number of eigenvalues (after sorting) for which SELECT is true. (Complex conjugate pairs for which SELECT is true for either eigenvalue count as 2.)
[out]WRdimension (N)
[out]WIdimension (N) WR and WI contain the real and imaginary parts, respectively, of the computed eigenvalues in the same order that they appear on the diagonal of the output Schur form T. Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first.
[out]VSdimension (LDVS,N)
  • If JOBVS = 'V', VS contains the orthogonal matrix Z of Schur vectors.
  • If JOBVS = 'N', VS is not referenced.
[in]LDVSThe leading dimension of the array VS. LDVS >= 1; if JOBVS = 'V', LDVS >= N.
[out]WORKdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) contains the optimal LWORK.
[in]LWORKThe dimension of the array WORK. LWORK >= max(1,3*N). For good performance, LWORK must generally be larger.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.

Parameters
BWORKdimension (N) Not referenced if SORT = 'N'.
[out]INFO
  • = 0: successful exit
  • < 0: if INFO = -i, the i-th argument had an illegal value.
  • > 0: if INFO = i, and i is <= N: the QR algorithm failed to compute all the eigenvalues; elements 1:ILO-1 and i+1:N of WR and WI contain those eigenvalues which have converged; if JOBVS = 'V', VS contains the matrix which reduces A to its partially converged Schur form. = N+1: the eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned); = N+2: after reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy SELECT=.TRUE. This could also be caused by underflow due to scaling.
AA_API void sgels_ ( const char  TRANS[1],
const int *  M,
const int *  N,
const int *  NRHS,
float *  A,
const int *  LDA,
float *  B,
const int *  LDB,
float *  WORK,
const int *  LWORK,
int *  INFO 
)

Solves overdetermined or underdetermined real linear systems involving an M-by-N matrix A, or its transpose, using a QR or LQ factorization of A.

It is assumed that A has full rank.

The following options are provided:

  • 1. If TRANS = 'N' and m >= n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem minimize || B - A*X ||.
  • 2. If TRANS = 'N' and m < n: find the minimum norm solution of an underdetermined system A * X = B.
  • 3. If TRANS = 'T' and m >= n: find the minimum norm solution of an undetermined system A**T * X = B.
  • 4. If TRANS = 'T' and m < n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem minimize || B - A**T * X ||.

Several right hand side vectors b and solution vectors x can be handled in a single call; they are stored as the columns of the M-by-NRHS right hand side matrix B and the N-by-NRHS solution matrix X.

Parameters
[in]TRANS
  • = 'N': the linear system involves A;
  • = 'T': the linear system involves A**T.
[in]MThe number of rows of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[in]NRHSThe number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >=0.
[in,out]Adimension (LDA,N) On entry, the M-by-N matrix A. On exit,
  • if M >= N, A is overwritten by details of its QR factorization as returned by DGEQRF;
  • if M < N, A is overwritten by details of its LQ factorization as returned by DGELQF.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[in,out]Bdimension (LDB,NRHS) On entry, the matrix B of right hand side vectors, stored columnwise; B is M-by-NRHS if TRANS = 'N', or N-by-NRHS
  • if TRANS = 'T'. On exit, if INFO = 0, B is overwritten by the solution vectors, stored columnwise:
  • if TRANS = 'N' and m >= n, rows 1 to n of B contain the least squares solution vectors; the residual sum of squares for the solution in each column is given by the sum of squares of elements N+1 to M in that column;
  • if TRANS = 'N' and m < n, rows 1 to N of B contain the minimum norm solution vectors;
  • if TRANS = 'T' and m >= n, rows 1 to M of B contain the minimum norm solution vectors;
  • if TRANS = 'T' and m < n, rows 1 to M of B contain the least squares solution vectors; the residual sum of squares for the solution in each column is given by the sum of squares of elements M+1 to N in that column.
[in]LDBThe leading dimension of the array B. LDB >= MAX(1,M,N).
WORKdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
[in]LWORKThe dimension of the array WORK. LWORK >= max( 1, MN + max( MN, NRHS ) ). For optimal performance, LWORK >= max( 1, MN + max( MN, NRHS )*NB ). where MN = min(M,N) and NB is the optimum block size. If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.
[out]INFO
  • = 0: successful exit
  • < 0: if INFO = -i, the i-th argument had an illegal value
  • > 0: if INFO = i, the i-th diagonal element of the triangular factor of A is zero, so that A does not have full rank; the least squares solution could not be computed.
AA_API void sgelsd_ ( const int *  M,
const int *  N,
const int *  NRHS,
float *  A,
const int *  LDA,
float *  B,
const int *  LDB,
float *  S,
const float *  RCOND,
int *  RANK,
float *  WORK,
int *  LWORK,
int *  IWORK,
int *  INFO 
)

DGELSD computes the minimum-norm solution to a real linear least squares problem.

Minimizes \(| b - A*x |\) using the singular value decomposition (SVD) of A. A is an M-by-N matrix which may be rank-deficient.

Several right hand side vectors b and solution vectors x can be handled in a single call; they are stored as the columns of the M-by-NRHS right hand side matrix B and the N-by-NRHS solution matrix X.

The problem is solved in three steps:

  • (1) Reduce the coefficient matrix A to bidiagonal form with Householder transformations, reducing the original problem into a "bidiagonal least squares problem" (BLS)
  • (2) Solve the BLS using a divide and conquer approach.
  • (3) Apply back all the Householder tranformations to solve the original least squares problem.

The effective rank of A is determined by treating as zero those singular values which are less than RCOND times the largest singular value.

The divide and conquer algorithm 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 X-MP, Cray Y-MP, Cray C-90, or Cray-2. It could conceivably fail on hexadecimal or decimal machines without guard digits, but we know of none.

Parameters
[in]MThe number of rows of A. M >= 0.
[in]NThe number of columns of A. N >= 0.
[in]NRHSThe number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
[in]Adimension (LDA,N) On entry, the M-by-N matrix A. On exit, A has been destroyed.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[in,out]Bdimension (LDB,NRHS) On entry, the M-by-NRHS right hand side matrix B. On exit, B is overwritten by the N-by-NRHS solution matrix X. If m >= n and RANK = n, the residual sum-of-squares for the solution in the i-th column is given by the sum of squares of elements n+1:m in that column.
[in]LDBThe leading dimension of the array B. LDB >= max(1,max(M,N)).
[out]Sdimension (min(M,N)) The singular values of A in decreasing order. The condition number of A in the 2-norm = S(1)/S(min(m,n)).
[in]RCONDRCOND is used to determine the effective rank of A. Singular values S(i) <= RCOND*S(1) are treated as zero. If RCOND < 0, machine precision is used instead.
[out]RANKThe effective rank of A, i.e., the number of singular values which are greater than RCOND*S(1).
[out]WORKdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
[in]LWORKThe dimension of the array WORK. LWORK must be at least 1. The exact minimum amount of workspace needed depends on M, N and NRHS. As long as LWORK is at least 12*N + 2*N*SMLSIZ + 8*N*NLVL + N*NRHS + (SMLSIZ+1)**2, if M is greater than or equal to N or 12*M + 2*M*SMLSIZ + 8*M*NLVL + M*NRHS + (SMLSIZ+1)**2, if M is less than N, the code will execute correctly. SMLSIZ is returned by ILAENV and is equal to the maximum size of the subproblems at the bottom of the computation tree (usually about 25), and NLVL = MAX( 0, INT( LOG_2( MIN( M,N )/(SMLSIZ+1) ) ) + 1 ) For good performance, LWORK should generally be larger. If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.
[out]IWORKdimension (MAX(1,LIWORK)) LIWORK >= max(1, 3 * MINMN * NLVL + 11 * MINMN), where MINMN = MIN( M,N ). On exit, if INFO = 0, IWORK(1) returns the minimum LIWORK.
[out]INFO
  • = 0: successful exit
  • < 0: if INFO = -i, the i-th argument had an illegal value.
  • > 0: the algorithm for computing the SVD failed to converge; if INFO = i, i off-diagonal elements of an intermediate bidiagonal form did not converge to zero.
AA_API void sgeqrf_ ( const int *  M,
const int *  N,
float *  A,
const int *  LDA,
float *  TAU,
float *  WORK,
int *  LWORK,
int *  INFO 
)

DGEQRF computes a QR factorization of a real M-by-N matrix A: A = Q * R.

Arguments

Parameters
[in]MThe number of rows of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[in,out]Adimension (LDA,N) On entry, the M-by-N matrix A. On exit, the elements on and above the diagonal of the array contain the min(M,N)-by-N upper trapezoidal matrix R (R is upper triangular if m >= n); the elements below the diagonal, with the array TAU, represent the orthogonal matrix Q as a product of min(m,n) elementary reflectors (see Further Details).
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[out]TAUdimension (min(M,N)) The scalar factors of the elementary reflectors (see Further Details).
[out]WORKdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
[in]LWORKThe dimension of the array WORK. LWORK >= max(1,N). For optimum performance LWORK >= N*NB, where NB is the optimal blocksize.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.

Parameters
[out]INFO= 0: successful exit

Further Details

The matrix Q is represented as a product of elementary reflectors

Q = H(1) H(2) . . . H(k), where k = min(m,n).

Each H(i) has the form

H(i) = I - tau * v * v'

where tau is a real scalar, and v is a real vector with v(1:i-1) = 0 and v(i) = 1; v(i+1:m) is stored on exit in A(i+1:m,i), and tau in TAU(i).

AA_API void sgesvd_ ( const char  jobu[1],
const char  jobvt[1],
const int *  m,
const int *  n,
float *  A,
const int *  lda,
float *  S,
float *  U,
const int *  ldu,
float *  Vt,
const int *  ldvt,
float *  work,
const int *  lwork,
int *  info 
)

Compute SVD.

Parameters
[in]jobuSpecifies options for computing all or part of the matrix U:
  • = 'A': all M columns of U are returned in array U:
  • = 'S': the first min(m,n) columns of U (the left singular vectors) are returned in the array U;
  • = 'O': the first min(m,n) columns of U (the left singular vectors) are overwritten on the array A;
  • = 'N': no columns of U (no left singular vectors) are computed.
[in]jobvtSpecifies options for computing all or part of the matrix V**T:
  • = 'A': all N rows of V**T are returned in the array VT;
  • = 'S': the first min(m,n) rows of V**T (the right singular vectors) are returned in the array VT;
  • = 'O': the first min(m,n) rows of V**T (the right singular vectors) are overwritten on the array A;
  • = 'N': no rows of V**T (no right singular vectors) are computed. JOBVT and JOBU cannot both be 'O'.
[in]mThe number of rows of the input matrix A. M >= 0.
[in]nThe number of columns of the input matrix A. N >= 0.
[in,out]AOn entry, the M-by-N matrix A. On exit,
  • if JOBU = 'O', A is overwritten with the first min(m,n) columns of U (the left singular vectors, stored columnwise);
  • if JOBVT = 'O', A is overwritten with the first min(m,n) rows of V**T (the right singular vectors, stored rowwise);
  • if JOBU .ne. 'O' and JOBVT .ne. 'O', the contents of A are destroyed.
[in]ldaThe leading dimension of the array A. LDA >= max(1,M).
[out]SThe singular values of A, sorted so that S(i) >= S(i+1). dimension (min(M,N))
[out]Udimension (LDU,UCOL) (LDU,M) if JOBU = 'A' or (LDU,min(M,N)) if JOBU = 'S'.
  • If JOBU = 'A', U contains the M-by-M orthogonal matrix U;
  • if JOBU = 'S', U contains the first min(m,n) columns of U (the left singular vectors, stored columnwise);
  • if JOBU = 'N' or 'O', U is not referenced.
[in]lduThe leading dimension of the array U. LDU >= 1; if JOBU = 'S' or 'A', LDU >= M.
[out]Vtdimension (LDVT,N)
  • If JOBVT = 'A', VT contains the N-by-N orthogonal matrix V**T;
  • if JOBVT = 'S', VT contains the first min(m,n) rows of V**T (the right singular vectors, stored rowwise);
  • if JOBVT = 'N' or 'O', VT is not referenced.
[in]ldvtThe leading dimension of the array VT. LDVT >= 1; if JOBVT = 'A', LDVT >= N; if JOBVT = 'S', LDVT >= min(M,N).
[out]workdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK; if INFO > 0, WORK(2:MIN(M,N)) contains the unconverged superdiagonal elements of an upper bidiagonal matrix B whose diagonal is in S (not necessarily sorted). B satisfies A = U * B * VT, so it has the same singular values as A, and singular vectors related by U and VT.
[in]lworkThe dimension of the array WORK. LWORK >= MAX(1,3*MIN(M,N)+MAX(M,N),5*MIN(M,N)). For good performance, LWORK should generally be larger. If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.
[out]info
  • = 0: successful exit.
  • < 0: if INFO = -i, the i-th argument had an illegal value.
  • > 0: if DBDSQR did not converge, INFO specifies how many superdiagonals of an intermediate bidiagonal form B did not converge to zero. See the description of WORK above for details.
AA_API void sgetrf_ ( const int *  M,
const int *  N,
float *  A,
const int *  LDA,
int *  IPIV,
int *  INFO 
)

Computes an LU factorization of a general M-by-N matrix A using partial pivoting with row interchanges.

The factorization has the form

\[ A = P * L * U \]

where P is a permutation matrix, L is lower triangular with unit diagonal elements (lower trapezoidal if m > n), and U is upper triangular (upper trapezoidal if m < n).

This is the right-looking Level 3 BLAS version of the algorithm.

Parameters
[in]MThe number of rows of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[in,out]AOn entry, the M-by-N matrix to be factored. On exit, the factors L and U from the factorization A = P*L*U; the unit diagonal elements of L are not stored.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[out]IPIVarray, dimension (min(M,N)) The pivot indices; for 1 <= i <= min(M,N), row i of the matrix was interchanged with row IPIV(i).
[out]INFO
  • = 0: successful exit
  • < 0: if INFO = -i, the i-th argument had an illegal value
  • > 0: if INFO = i, U(i,i) is exactly zero. The factorization has been completed, but the factor U is exactly singular, and division by zero will occur if it is used to solve a system of equations.
AA_API void sgetri_ ( const int *  N,
float *  A,
const int *  LDA,
const int *  IPIV,
float *  WORK,
const int *  LWORK,
int *  INFO 
)

type for operations

Inverse of matrix using LU factorization by *getrf.

You must call *getrf before you call *getri.

Parameters
[in]NOrder of the matrix A
[in,out]Aon entry the L and U factors from *getrf, on exit the inverse of the original A
[in]LDAnumber of rows in A
[in]IPIVpivot indices from sgetrf
WORKworkspace array
[in]LWORKlength of work, optimally > n*nb where nb is the optimal blocksize return by ilaenv_
[out]INFOoutput. info==0 for success, info<zero for illegal argument, info > 0 for singular matrix
AA_API void slacpy_ ( const char  UPLO[1],
const int *  M,
const int *  N,
const float *  A,
const int *  LDA,
float *  B,
const int *  LDB 
)

Copies all or part of a two-dimensional matrix A to another matrix B.

Parameters
[in]UPLOSpecifies the part of the matrix A to be copied to B.
  • = 'U': Upper triangular part
  • = 'L': Lower triangular part
  • Otherwise: All of the matrix A
[in]MThe number of rows of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[in]Adimension (LDA,N) The m by n matrix A. If UPLO = 'U', only the upper triangle or trapezoid is accessed; if UPLO = 'L', only the lower triangle or trapezoid is accessed.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[out]Bdimension (LDB,N) On exit, B = A in the locations specified by UPLO.
[in]LDBThe leading dimension of the array B. LDB >= max(1,M).
AA_API void slag2d_ ( const int *  M,
const int *  N,
float *  SA,
const int *  LDSA,
double *  A,
const int *  LDA,
const int *  INFO 
)

Converts a SINGLE PRECISION matrix, SA, to a DOUBLE PRECISION matrix, A.

RMAX is the overflow for the SINGLE PRECISION arithmetic DLAG2S checks that all the entries of A are between -RMAX and RMAX. If not the convertion is aborted and a flag is raised.

This is a helper routine so there is no argument checking.

Parameters
[in]MThe number of lines of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[out]AOn exit, if INFO=0, the M-by-N coefficient matrix A.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[in]SAOn entry, the M-by-N coefficient matrix SA.
[in]LDSAThe leading dimension of the array SA. LDSA >= max(1,M).
[out]INFO
  • = 0: successful exit
  • > 0: if INFO = k, the (i,j) entry of the matrix A has overflowed when moving from DOUBLE PRECISION to SINGLE k is given by k = (i-1)*LDA+j
AA_API void slarnv_ ( const int *  IDIST,
int  ISEED[4],
const int *  N,
float *  X 
)

Returns a vector of n random real numbers from a uniform or normal distribution.

Parameters
[in]IDISTSpecifies the distribution of the random numbers:
  • = 1: uniform (0,1)
  • = 2: uniform (-1,1)
  • = 3: normal (0,1)
[in,out]ISEEDOn entry, the seed of the random number generator; the array elements must be between 0 and 4095, and ISEED(4) must be odd. On exit, the seed is updated.
[in]NThe number of random numbers to be generated.
[out]XThe generated random numbers.

This routine calls the auxiliary routine DLARUV to generate random real numbers from a uniform (0,1) distribution, in batches of up to 128 using vectorisable code. The Box-Muller method is used to transform numbers from a uniform to a normal distribution.

AA_API void slaruv_ ( int  ISEED[4],
const int *  N,
float *  X 
)

Returns a vector of n random real numbers from a uniform (0,1) distribution (n <= 128).

This is an auxiliary routine called by DLARNV and ZLARNV.

Parameters
[in,out]ISEEDISEED is INTEGER array, dimension (4) On entry, the seed of the random number generator; the array elements must be between 0 and 4095, and ISEED(4) must be odd. On exit, the seed is updated.
[in]NN is INTEGER The number of random numbers to be generated. N <= 128.
[out]XX is AA_TYPE PRECISION array, dimension (N) The generated random numbers.
Author
Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.
Date
November 2011

This routine uses a multiplicative congruential method with modulus 2**48 and multiplier 33952834046453 (see G.S.Fishman, 'Multiplicative congruential random number generators with modulus 2**b: an exhaustive analysis for b = 32 and a partial analysis for b = 48', Math. Comp. 189, pp 331-344, 1990).

48-bit integers are stored in 4 integer array elements with 12 bits per element. Hence the routine is portable across machines with integers of 32 bits or more.

AA_API void slascl_ ( const char  TYPE[1],
const int *  KL,
const int *  KU,
const float *  CFROM,
const float *  CTO,
const int *  M,
const int *  N,
float *  A,
const int *  LDA,
int *  INFO 
)

Multiplies the M by N real matrix A by the real scalar CTO/CFROM.

k This is done without over/underflow as long as the final result CTO*A(I,J)/CFROM does not over/underflow. TYPE specifies that A may be full, upper triangular, lower triangular, upper Hessenberg, or banded.

Parameters
[in]TYPETYPE indices the storage type of the input matrix.
  • = 'G': A is a full matrix.
  • = 'L': A is a lower triangular matrix.
  • = 'U': A is an upper triangular matrix.
  • = 'H': A is an upper Hessenberg matrix.
  • = 'B': A is a symmetric band matrix with lower bandwidth KL and upper bandwidth KU and with the only the lower half stored.
  • = 'Q': A is a symmetric band matrix with lower bandwidth KL and upper bandwidth KU and with the only the upper half stored.
  • = 'Z': A is a band matrix with lower bandwidth KL and upper bandwidth KU.
[in]KLThe lower bandwidth of A. Referenced only if TYPE = 'B', 'Q' or 'Z'.
[in]KUThe upper bandwidth of A. Referenced only if TYPE = 'B', 'Q' or 'Z'.
[in]CFROM
[in]CTOThe matrix A is multiplied by CTO/CFROM. A(I,J) is computed without over/underflow if the final result CTO*A(I,J)/CFROM can be represented without over/underflow. CFROM must be nonzero.
[in]MThe number of rows of the matrix A. M >= 0.
[in]NThe number of columns of the matrix A. N >= 0.
[in,out]AThe matrix to be multiplied by CTO/CFROM. See TYPE for the storage type.
[in]LDAThe leading dimension of the array A. LDA >= max(1,M).
[out]INFO(output) INTEGER
  • 0 - successful exit
  • <0 - if INFO = -i, the i-th argument had an illegal value.
AA_API void slaset_ ( const char  UPLO[1],
const int *  M,
const int *  N,
const float *  ALPHA,
const float *  BETA,
float *  A,
const int *  LDA 
)

initializes an m-by-n matrix A to BETA on the diagonal and ALPHA on the offdiagonals.

Parameters
[in]UPLOUPLO is CHARACTER*1. Specifies the part of the matrix A to be set.
  • = 'U': Upper triangular part is set; the strictly lower triangular part of A is not changed.
  • = 'L': Lower triangular part is set; the strictly upper triangular part of A is not changed.
  • Otherwise: All of the matrix A is set.
[in]MM is INTEGER. The number of rows of the matrix A. M >= 0.
[in]NN is INTEGER. The number of columns of the matrix A. N >= 0.
[in]ALPHAALPHA is DOUBLE PRECISION. The constant to which the offdiagonal elements are to be set.
[in]BETABETA is DOUBLE PRECISION. The constant to which the diagonal elements are to be set.
[in,out]AA is DOUBLE PRECISION array, dimension (LDA,N). On exit, the leading m-by-n submatrix of A is set as follows:
  • if UPLO = 'U', A(i,j) = ALPHA, 1<=i<=j-1, 1<=j<=n,
  • if UPLO = 'L', A(i,j) = ALPHA, j+1<=i<=m, 1<=j<=n,
  • otherwise, A(i,j) = ALPHA, 1<=i<=m, 1<=j<=n, i.ne.j, and, for all UPLO, A(i,i) = BETA, 1<=i<=min(m,n).
[in]LDALDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
Author
Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.
Date
November 2011
AA_API void sorgqr_ ( const int *  M,
const int *  N,
const int *  K,
float *  A,
const int *  LDA,
const float *  TAU,
float *  WORK,
const int *  LWORK,
int *  INFO 
)

Generates an M-by-N real matrix Q with orthonormal columns, which is defined as the first N columns of a product of K elementary reflectors of order M.

Q = H(1) H(2) . . . H(k)

as returned by xGEQRF.

Parameters
[in]MThe number of rows of the matrix Q. M >= 0.
[in]NThe number of columns of the matrix Q. M >= N >= 0.
[in]KThe number of elementary reflectors whose product defines the matrix Q. N >= K >= 0.
[in,out]Adimension (LDA,N) On entry, the i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by DGEQRF in the first k columns of its array argument A. On exit, the M-by-N matrix Q.
[in]LDAThe first dimension of the array A. LDA >= max(1,M).
[in]TAUdimension (K) TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by DGEQRF.
[out]WORKdimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
[in]LWORKThe dimension of the array WORK. LWORK >= max(1,N). For optimum performance LWORK >= N*NB, where NB is the optimal blocksize.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.

Parameters
[out]INFO= 0: successful exit < 0: if INFO = -i, the i-th argument has an illegal value