1 /* $Id: matrix.h,v 6.1 1999/04/02 20:43:30 vakatov Exp $ 2 * =========================================================================== 3 * 4 * PUBLIC DOMAIN NOTICE 5 * National Center for Biotechnology Information (NCBI) 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 do not place any restriction on its use or reproduction. 13 * We would, however, appreciate having the NCBI and the author cited in 14 * any work or product based on this material 15 * 16 * Although all reasonable efforts have been taken to ensure the accuracy 17 * and reliability of the software and data, the NLM and the U.S. 18 * Government do not and cannot warrant the performance or results that 19 * may be obtained by using this software or data. The NLM and the U.S. 20 * Government disclaim all warranties, express or implied, including 21 * warranties of performance, merchantability or fitness for any particular 22 * purpose. 23 * 24 * =========================================================================== 25 * 26 * Author: Denis Vakatov 27 * 28 * File Description: 29 * Basic matrix & vector handling library. 30 * NOTE: most of the advanced functions are valid for square matrices only! 31 * 32 * =========================================================================== 33 * $Log: matrix.h,v $ 34 * Revision 6.1 1999/04/02 20:43:30 vakatov 35 * DLL'd for MS-Win 36 * Added detailed API function descriptions 37 * 38 * ========================================================================== 39 */ 40 41 #ifndef MATRIX_H 42 #define MATRIX_H 43 44 #include <ncbilcl.h> 45 #include <ncbistd.h> 46 47 /* The following preprocessor variables can be set on the compiling stage: 48 * #TEST_MODULE_MATRIX -- to build test application (needs CORELIB library) 49 * #CHECK_RANGE_MATRIX -- to check for the matrix indexes be in-range (slow) 50 */ 51 52 #undef NLM_EXTERN 53 #ifdef NLM_IMPORT 54 #define NLM_EXTERN NLM_IMPORT 55 #else 56 #define NLM_EXTERN extern 57 #endif 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 64 /* Forward declaration of the "Nlm_Matrix" internal structure. 65 */ 66 struct Nlm_MatrixTag; 67 typedef struct Nlm_MatrixTag *Nlm_Matrix; 68 69 70 /* Create new matrix("n_row" X "n_column"). 71 */ 72 NLM_EXTERN Nlm_Matrix Nlm_MatrixNew 73 (Nlm_Uint4 n_row, 74 Nlm_Uint4 n_column 75 ); 76 77 /* Destroy matrix "mat". 78 */ 79 NLM_EXTERN void Nlm_MatrixDelete 80 (Nlm_Matrix mat 81 ); 82 83 /* Assign the node of matrix "mat" located in the specified "row" and "column" 84 * to value "value". 85 */ 86 NLM_EXTERN void Nlm_MatrixSetNode 87 (Nlm_Matrix mat, 88 Nlm_Uint4 row, 89 Nlm_Uint4 column, 90 Nlm_FloatHi value 91 ); 92 93 /* Assign all nodes in the whole row "row" of matrix "mat" to values 94 * of the relevant nodes in row "row_src" of matrix "mat_src". 95 * NOTE: "mat" and "src_mat" must have the same # of columns! 96 */ 97 NLM_EXTERN void Nlm_MatrixSetRow 98 (Nlm_Matrix mat, 99 Nlm_Uint4 row, 100 const Nlm_Matrix mat_src, 101 Nlm_Uint4 row_src 102 ); 103 104 /* Assign all nodes in the whole column "column" of matrix "mat" to values 105 * of the relevan nodes in column "column_src" of matrix "mat_src". 106 * NOTE: "mat" and "src_mat" must have the same # of rows! 107 */ 108 NLM_EXTERN void Nlm_MatrixSetColumn 109 (Nlm_Matrix mat, 110 Nlm_Uint4 column, 111 const Nlm_Matrix mat_src, 112 Nlm_Uint4 column_src 113 ); 114 115 /* Return the value of specified matrix node. 116 */ 117 NLM_EXTERN Nlm_FloatHi Nlm_MatrixNode 118 (const Nlm_Matrix mat, 119 Nlm_Uint4 row, 120 Nlm_Uint4 column 121 ); 122 123 /* Create a vector and assign it with the 124 * values from the row "row" of matrix "mat". 125 * Return the created vector. 126 */ 127 NLM_EXTERN Nlm_Matrix Nlm_MatrixRow 128 (const Nlm_Matrix mat, 129 Nlm_Uint4 row 130 ); 131 132 /* Create a transposed vector and assign it with the 133 * values from the column "column" of matrix "mat". 134 * Return the created transposed vector. 135 */ 136 NLM_EXTERN Nlm_Matrix Nlm_MatrixColumn 137 (const Nlm_Matrix mat, 138 Nlm_Uint4 column 139 ); 140 141 /* Compare the two matrices; return TRUE if they are identical. 142 * NOTE: "mat1" and "mat2" must have the same # of rows and columns! 143 */ 144 NLM_EXTERN Nlm_Boolean Nlm_MatrixCompare 145 (const Nlm_Matrix mat1, 146 const Nlm_Matrix mat2 147 ); 148 149 /* Create and return an exact copy of matrix "mat". 150 */ 151 NLM_EXTERN Nlm_Matrix Nlm_MatrixCopy 152 (const Nlm_Matrix mat 153 ); 154 155 /* Create and return transposition of matrix "mat". 156 */ 157 NLM_EXTERN Nlm_Matrix Nlm_MatrixTranspose 158 (const Nlm_Matrix mat 159 ); 160 161 /* Return the result of multiplication of the two matrices. 162 * NOTE 1: the order is important, as in most cases: m1*m2 != m2*m1 163 * NOTE 2: "mat_left" must have exactly as many columns as # of rows 164 * in "mat_right"! 165 */ 166 NLM_EXTERN Nlm_Matrix Nlm_MatrixMultiply 167 (const Nlm_Matrix mat_left, 168 const Nlm_Matrix mat_right 169 ); 170 171 /* Solve equation: (mat) * |V| = |vector|. 172 * Return the found solution(vector |V|). 173 * NOTE 1: "vector" must be a 1-column matrix(i.e. vector)! 174 * NOTE 2: matrix "mat" must be square! 175 */ 176 NLM_EXTERN Nlm_Matrix Nlm_MatrixSolve 177 (const Nlm_Matrix mat, 178 const Nlm_Matrix vector 179 ); 180 181 /* Solve equation: (mat) * (M) = (1). 182 * Return the found solution(matrix (M)). 183 * NOTE 1: matrix "mat" must be square! 184 */ 185 NLM_EXTERN Nlm_Matrix Nlm_MatrixInvert 186 (const Nlm_Matrix mat 187 ); 188 189 /* Printout the content of matrix "mat" to the file stream "fd", 190 * with title "descr". 191 */ 192 NLM_EXTERN void Nlm_MatrixPrint 193 (const Nlm_Matrix mat, 194 FILE* fd, 195 const Char* descr 196 ); 197 198 #ifdef __cplusplus 199 } 200 #endif 201 202 #undef NLM_EXTERN 203 #ifdef NLM_EXPORT 204 #define NLM_EXTERN NLM_EXPORT 205 #else 206 #define NLM_EXTERN 207 #endif 208 209 #endif /* MATRIX_H */ 210