1 #ifndef MISC_LAPACKWRAPP___NCBI_LAPACK__H 2 #define MISC_LAPACKWRAPP___NCBI_LAPACK__H 3 4 /* $Id: ncbi_lapack.h 503534 2016-06-06 14:44:06Z ucko $ 5 * =========================================================================== 6 * 7 * PUBLIC DOMAIN NOTICE 8 * National Center for Biotechnology Information 9 * 10 * This software/database is a "United States Government Work" under the 11 * terms of the United States Copyright Act. It was written as part of 12 * the author's official duties as a United States Government employee and 13 * thus cannot be copyrighted. This software/database is freely available 14 * to the public for use. The National Library of Medicine and the U.S. 15 * Government have not placed any restriction on its use or reproduction. 16 * 17 * Although all reasonable efforts have been taken to ensure the accuracy 18 * and reliability of the software and data, the NLM and the U.S. 19 * Government do not and cannot warrant the performance or results that 20 * may be obtained by using this software or data. The NLM and the U.S. 21 * Government disclaim all warranties, express or implied, including 22 * warranties of performance, merchantability or fitness for any particular 23 * purpose. 24 * 25 * Please cite the author in any work or product based on this material. 26 * 27 * =========================================================================== 28 * 29 * Author: Aaron Ucko 30 * 31 */ 32 33 /** @file ncbi_lapack.hpp 34 * Wrappers for LAPACK routines of interest. 35 */ 36 37 /** @addtogroup Miscellaneous 38 * 39 * @{ 40 */ 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 static const int kNcbiLapackMemoryError = -999; 47 48 enum EEigensWanted { 49 eEigenValues = 'N', 50 eEigenVectors = 'V' 51 }; 52 53 enum EMatrixTriangle { 54 eUpperTriangle = 'U', 55 eLowerTriangle = 'L' 56 }; 57 58 enum EMaybeTransposed { 59 eTransposed = 'T', 60 eNotTransposed = 'N' 61 }; 62 63 enum ESingularVectorDetailsWanted { 64 eSVD_All = 'A', /**< Full orthogonal matrix, in a dedicated arg. */ 65 eSVD_Singular = 'S', /**< Only the singular vectors, in a dedicated arg. */ 66 eSVD_Overwrite = 'O', /**< Only the singular vectors, overwriting A. */ 67 eSVD_None = 'N' /**< None. */ 68 }; 69 70 /** 71 * Compute the eigenvalues, and optionally also the eigenvectors, of a 72 * symmetric matrix. (Wraps the LAPACK routine DSYEV.) 73 * @param jobz 74 * Whether to compute eigenvectors, or just eigenvalues. 75 * @param uplo 76 * Which triangle of the matrix to consult. 77 * @param n 78 * The order of the matrix. 79 * @param a 80 * On entry, the matrix A to analyze, stored in COLUMN-MAJOR order 81 * (Fortran-style). On successful exit in eEigenVectors mode, contains the 82 * orthonormal eigenvectors of the original matrix. On exit in all other 83 * cases, undefined. 84 * @param lda 85 * The leading dimension of A (the spacing between the start of A's columns, 86 * which need not be contiguous, just uniformly spaced and non-overlapping). 87 * @param w 88 * On successful exit, contains the eigenvalues in ascending order. 89 * @return 90 * 0 on success, -N if the Nth argument had a bad value, 91 * kNcbiLapackMemoryError if unable to allocate temporary memory, +N if N 92 * off-diagonal elements of an intermediate tridiagonal form did not 93 * converge to zero. 94 * @sa http://www.netlib.org/lapack/explore-html/d2/d8a/group__double_s_yeigen.html#ga442c43fca5493590f8f26cf42fed4044 95 */ 96 int NCBI_SymmetricEigens(enum EEigensWanted jobz, enum EMatrixTriangle uplo, 97 unsigned int n, double* a, unsigned int lda, 98 double* w); 99 100 /** 101 * Find the least-squares solution of an overdetermined linear system, or the 102 * minimum-norm solution of an undetermined linear system. (Wraps the LAPACK 103 * routine DGELS.) 104 * @param trans 105 * Whether to work with matrix A or its transpose. 106 * @param r 107 * The number of rows in matrix A. 108 * @param c 109 * The number of columns in matrix A. 110 * @param nrhs 111 * The number of right-hand sides (columns in matrix B). 112 * @param a 113 * On entry, the matrix A, stored in COLUMN-MAJOR order (Fortran-style); 114 * expected to have full rank. On successful exit, details of the QR or LQ 115 * factorization of A. 116 * @param lda 117 * The leading dimension of A (the spacing between the start of A's columns, 118 * which need not be contiguous, just uniformly spaced and non-overlapping). 119 * @param b 120 * On entry, the matrix B of right-hand side vectors, stored in COLUMN-MAJOR 121 * order (Fortran-style). On successful exit, the corresponding solution 122 * vectors. 123 * @param ldb 124 * The leading dimension of B (the spacing between the start of B's columns, 125 * which need not be contiguous, just uniformly spaced and non-overlapping). 126 * @return 127 * 0 on success, -N if the Nth argument had a bad value, 128 * kNcbiLapackMemoryError if unable to allocate temporary memory, +N if the 129 * Nth diagonal element of the triangular factor of A is zero. 130 * @sa http://www.netlib.org/lapack/explore-html/d7/d3b/group__double_g_esolve.html#ga225c8efde208eaf246882df48e590eac 131 */ 132 int NCBI_LinearSolution(enum EMaybeTransposed trans, 133 unsigned int r, unsigned int c, unsigned int nrhs, 134 double* a, unsigned int lda, 135 double* b, unsigned int ldb); 136 137 /** 138 * Compute the singular value decomposition of a matrix. (Wraps the LAPACK 139 * routine DGESVD.) 140 * @param jobu 141 * How much of the left orthogonal matrix to return. 142 * @param jobvt 143 * How much of the right orthogonal matrix to return. 144 * @param r 145 * The number of rows in matrix A. 146 * @param c 147 * The number of columns in matrix A. 148 * @param a 149 * On entry, the matrix A, stored in COLUMN-MAJOR order (Fortran-style). On 150 * successful exit when either jobu or jobvt is eSVD_Overwrite, either the 151 * left singular vectors in column-major order or the right singular vectors 152 * in row-major order, respectively. On exit in all other cases, undefined. 153 * @param lda 154 * The leading dimension of A (the spacing between the start of A's columns, 155 * which need not be contiguous, just uniformly spaced and non-overlapping). 156 * @param s 157 * On success, receives the singular values of A, in descending order. 158 * @param u 159 * Depending on jobu, may receive the left singular vectors in column-major 160 * order or the full left orthogonal matrix, or be left alone altogether. 161 * @param ldu 162 * The leading dimension of U. Must be positive even if no output to U is 163 * requested. 164 * @param vt 165 * Depending on jobu, may receive the right singular vectors in row-major 166 * order or the full right orthogonal matrix, or be left alone altogether. 167 * @param ldvt 168 * The leading dimension of VT. Must be positive even if no output to VT is 169 * requested. 170 * @param superb 171 * If the algorithm didn't converge, receives (unless NULL!) the unconverged 172 * superdiagonal elements of an upper bidiagonal matrix B whose diagonal 173 * is in S (not necessarily sorted). 174 * @note jobu and jobvt cannot both be eSVD_Overwrite! 175 * @return 0 on success, -N if the Nth argument had an illegal value, 176 * kNcbiLapackMemoryError if unable to allocate temporary memory, +N if N 177 * superdiagonals of an intermediate bidiagonal form didn't converge to 0. 178 * @sa http://www.netlib.org/lapack/explore-html/d1/d7e/group__double_g_esing.html#ga84fdf22a62b12ff364621e4713ce02f2 179 */ 180 int NCBI_SingularValueDecomposition(enum ESingularVectorDetailsWanted jobu, 181 enum ESingularVectorDetailsWanted jobvt, 182 unsigned int r, unsigned int c, 183 double* a, unsigned int lda, double* s, 184 double* u, unsigned int ldu, 185 double* vt, unsigned int ldvt, 186 double* superb); 187 188 #ifdef __cplusplus 189 } 190 #endif 191 192 /* @} */ 193 194 #endif /* MISC_LAPACKWRAPP___NCBI_LAPACK__HPP */ 195