1 /* $Id: nlm_linear_algebra.h,v 1.8 2008/08/21 19:55:43 kazimird Exp $
2  * ===========================================================================
3  *
4  *                            PUBLIC DOMAIN NOTICE
5  *               National Center for Biotechnology Information
6  *
7  *  This software/database is a "United States Government Work" under the
8  *  terms of the United States Copyright Act.  It was written as part of
9  *  the author's official duties as a United States Government employee and
10  *  thus cannot be copyrighted.  This software/database is freely available
11  *  to the public for use. The National Library of Medicine and the U.S.
12  *  Government have not placed any restriction on its use or reproduction.
13  *
14  *  Although all reasonable efforts have been taken to ensure the accuracy
15  *  and reliability of the software and data, the NLM and the U.S.
16  *  Government do not and cannot warrant the performance or results that
17  *  may be obtained by using this software or data. The NLM and the U.S.
18  *  Government disclaim all warranties, express or implied, including
19  *  warranties of performance, merchantability or fitness for any particular
20  *  purpose.
21  *
22  *  Please cite the author in any work or product based on this material.
23  *
24  * ===========================================================================*/
25 
26 /**
27  * @file nlm_linear_algebra.h
28  * Declarations for several linear algebra routines
29  *
30  * @author E. Michael Gertz
31  */
32 
33 #ifndef __NLM_LINEAR_ALGEBRA__
34 #define __NLM_LINEAR_ALGEBRA__
35 
36 #include <algo/blast/core/blast_export.h>
37 #include <algo/blast/core/ncbi_std.h>
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 /**
44  * Create and return a new, dense matrix.  Elements of the matrix A
45  * may be accessed as A[i][j]
46  *
47  * @param nrows     the number of rows for the new matrix.
48  * @param ncols     the number of columns for the new matrix.
49  */
50 NCBI_XBLAST_EXPORT
51 double ** Nlm_DenseMatrixNew(int nrows, int ncols);
52 
53 
54 /**
55  * Create and return a new, dense, lower-triangular matrix.  Elements
56  * of the matrix A may be accessed as A[i][j] for i <= j.
57  *
58  * @param n         the dimension of the matrix.
59  */
60 NCBI_XBLAST_EXPORT
61 double ** Nlm_LtriangMatrixNew(int n);
62 
63 
64 /**
65  * Free a matrix created by Nlm_DenseMatrixNew or
66  * Nlm_LtriangMatrixNew.
67  *
68  * @param mat       the matrix to be freed
69  * @return          always NULL
70  */
71 NCBI_XBLAST_EXPORT
72 void Nlm_DenseMatrixFree(double *** mat);
73 
74 
75 /**
76  * Create and return a new Int4 matrix.  Elements of the matrix A
77  * may be accessed as A[i][j]
78  *
79  * @param nrows     the number of rows for the new matrix.
80  * @param ncols     the number of columns for the new matrix.
81  */
82 NCBI_XBLAST_EXPORT
83 int ** Nlm_Int4MatrixNew(int nrows, int ncols);
84 
85 
86 /**
87  * Free a matrix created by Nlm_DenseMatrixNew or
88  * Nlm_LtriangMatrixNew.
89  *
90  * @param mat       the matrix to be freed
91  * @return          always NULL
92  */
93 NCBI_XBLAST_EXPORT
94 void Nlm_Int4MatrixFree(int *** mat);
95 
96 
97 /**
98  * Accessing only the lower triangular elements of the symmetric,
99  * positive definite matrix A, compute a lower triangular matrix L
100  * such that A = L L^T (Cholesky factorization.)  Overwrite the lower
101  * triangle of A with L.
102  *
103  * This routine may be used with the Nlm_SolveLtriangPosDef routine to
104  * solve systems of equations.
105  *
106  * @param A         the lower triangle of a symmetric, positive-definite
107  *                  matrix
108  * @param n         the size of A
109  */
110 NCBI_XBLAST_EXPORT
111 void Nlm_FactorLtriangPosDef(double ** A, int n);
112 
113 
114 /**
115  * Solve the linear system \f$ L L^T y = b \f$, where L is a non-singular
116  * lower triangular matrix, usually computed using
117  * the Nlm_FactorLtriangPosDef routine.
118  *
119  * @param x         on entry, the right hand size of the linear system
120  *                  L L^T y = b; on exit the solution
121  * @param n         the size of x
122  * @param L         a non-singular lower triangular matrix
123  */
124 NCBI_XBLAST_EXPORT
125 void Nlm_SolveLtriangPosDef(double x[], int n, double ** L);
126 
127 
128 /**
129  * Compute the Euclidean norm (2-norm) of a vector.
130  *
131  * This routine is based on the (freely available) BLAS routine dnrm2,
132  * which handles the scale of the elements of v in a stable fashion.
133  *
134  * @param v      a vector
135  * @param n      the length of v
136  */
137 NCBI_XBLAST_EXPORT
138 double Nlm_EuclideanNorm(const double v[], int n);
139 
140 
141 /**
142  * Let y = y + alpha * x
143  *
144  * @param y         a vector
145  * @param x         another vector
146  * @param n         the length of x and y
147  * @param alpha     a scale factor
148  */
149 NCBI_XBLAST_EXPORT
150 void Nlm_AddVectors(double y[], int n, double alpha,
151                     const double x[]);
152 
153 
154 /**
155  * Given a nonnegative vector x and a nonnegative scalar max, returns
156  * the largest value in [0, max] for which x + alpha * step_x >= 0.
157  *
158  * @param x         a vector with nonnegative elements
159  * @param step_x    another vector
160  * @param n         the size of x and step_x
161  * @param max       a nonnegative scalar
162  */
163 NCBI_XBLAST_EXPORT
164 double Nlm_StepBound(const double x[], int n,
165                      const double step_x[], double max);
166 
167 #ifdef __cplusplus
168 }
169 #endif
170 
171 #endif
172