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