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