NCBI C++ ToolKit
ncbi_lapack.h
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef MISC_LAPACKWRAPP___NCBI_LAPACK__H
2 #define MISC_LAPACKWRAPP___NCBI_LAPACK__H
3 
4 /* $Id: ncbi_lapack.h 72886 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 
49  eEigenValues = 'N',
50  eEigenVectors = 'V'
51 };
52 
55  eLowerTriangle = 'L'
56 };
57 
59  eTransposed = 'T',
60  eNotTransposed = 'N'
61 };
62 
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  */
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  */
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 */
static const int kNcbiLapackMemoryError
Definition: ncbi_lapack.h:46
int NCBI_SymmetricEigens(enum EEigensWanted jobz, enum EMatrixTriangle uplo, unsigned int n, double *a, unsigned int lda, double *w)
Compute the eigenvalues, and optionally also the eigenvectors, of a symmetric matrix.
Definition: ncbi_lapack.c:103
EMatrixTriangle
Definition: ncbi_lapack.h:53
ESingularVectorDetailsWanted
Definition: ncbi_lapack.h:63
int NCBI_SingularValueDecomposition(enum ESingularVectorDetailsWanted jobu, enum ESingularVectorDetailsWanted jobvt, unsigned int r, unsigned int c, double *a, unsigned int lda, double *s, double *u, unsigned int ldu, double *vt, unsigned int ldvt, double *superb)
Compute the singular value decomposition of a matrix.
Definition: ncbi_lapack.c:147
int NCBI_LinearSolution(enum EMaybeTransposed trans, unsigned int r, unsigned int c, unsigned int nrhs, double *a, unsigned int lda, double *b, unsigned int ldb)
Find the least-squares solution of an overdetermined linear system, or the minimum-norm solution of a...
Definition: ncbi_lapack.c:124
EMaybeTransposed
Definition: ncbi_lapack.h:58
EEigensWanted
Definition: ncbi_lapack.h:48
@ eLowerTriangle
Definition: ncbi_lapack.h:55
@ eUpperTriangle
Definition: ncbi_lapack.h:54
@ eSVD_All
Full orthogonal matrix, in a dedicated arg.
Definition: ncbi_lapack.h:64
@ eSVD_None
None.
Definition: ncbi_lapack.h:67
@ eSVD_Overwrite
Only the singular vectors, overwriting A.
Definition: ncbi_lapack.h:66
@ eSVD_Singular
Only the singular vectors, in a dedicated arg.
Definition: ncbi_lapack.h:65
@ eNotTransposed
Definition: ncbi_lapack.h:60
@ eTransposed
Definition: ncbi_lapack.h:59
@ eEigenValues
Definition: ncbi_lapack.h:49
@ eEigenVectors
Definition: ncbi_lapack.h:50
yy_size_t n
unsigned int a
Definition: ncbi_localip.c:102
double r(size_t dimension_, const Int4 *score_, const double *prob_, double theta_)
Modified on Wed Jul 24 17:20:00 2024 by modify_doxy.py rev. 669887