/[ascend]/trunk/base/generic/solver/mtx_vector.h
ViewVC logotype

Contents of /trunk/base/generic/solver/mtx_vector.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1062 - (show annotations) (download) (as text)
Sun Jan 7 07:21:02 2007 UTC (13 years, 6 months ago) by johnpye
File MIME type: text/x-chdr
File size: 9514 byte(s)
Added missing @} at end of header
1 /* ASCEND modelling environment
2 Copyright (C) 2006 Carnegie Mellon University
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation; either version 2, or (at your option)
7 any later version.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program; if not, write to the Free Software
16 Foundation, Inc., 59 Temple Place - Suite 330,
17 Boston, MA 02111-1307, USA.
18 *//* @file
19 Vector math structure and methods
20
21 If we get brave, we will consider replacing the cores of these routines with
22 BLAS calls. We aren't overeager to go mixed language call nuts just yet,
23 however.
24
25 Comment: the NVector implementation provided with SUNDIALS might be an
26 easier-to-integrate solution for this. It's also MPI-friendly. -- John Pye
27
28 A dense vector class of some utility and the functions for it.
29 The vector consists of an array of real64 (vec) and a mtx_range_t
30 (rng) which refers to subsets of the range of indexes of vec.
31 When calling the various vector functions, the range indexes in
32 rng are used to calculate offsets in the vec array. Therefore,
33 it is important that your rng->(low,high) refer to valid indexes
34 of vec[]. In particular
35 - neither rng->low nor rng->high may be negative
36 - low <= high
37 - high < length of vec
38 This means that whatever your maximum high is, you should allocate
39 (high+1) values in vec.
40
41 @todo solver/slv_common:vec_vector & operations should be
42 moved to a module in general or utilities.
43 */
44
45 #ifndef ASC_MTX_VECTOR_H
46 #define ASC_MTX_VECTOR_H
47
48 #include <utilities/ascConfig.h>
49 #include "mtx.h"
50
51 /** @addtogroup linear Linear
52 * @{
53 */
54
55 struct vec_vector {
56 real64 norm2; /**< 2-norm of vector squared. */
57 mtx_range_t *rng; /**< Pointer to range of vector (low..high). */
58 real64 *vec; /**< Data array (NULL => uninitialized). */
59 boolean accurate; /**< Is vector currently accurate? User-manipulated. */
60 };
61
62 ASC_DLLSPEC(struct vec_vector *) vec_create(int32 low, int32 high);
63 /**<
64 * Returns a new vec_vector initialized to the specified range.
65 * This function creates, initializes, and returns a new vec_vector
66 * structure. The vector is initialized using init_vector() and
67 * a pointer to the new struct is returned. If the specified range
68 * is improper (see vec_init()) then a valid vector cannot be
69 * created and NULL is returned.<br><br>
70 *
71 * Destruction of the returned vec_vector is the responsibility of
72 * the caller. vec_destroy() may be used for this purpose.
73 *
74 * @param low The lower bound of the vector's range.
75 * @param high The upper bound of the vector's range.
76 * @return A new initialized vec_vector, or NULL if one could
77 * not be created.
78 */
79
80 ASC_DLLSPEC(int) vec_init(struct vec_vector *vec, int32 low, int32 high);
81 /**<
82 * Initializes a vec_vector structure.
83 * The new range (low..high) is considered proper if both low and
84 * high are zero or positive, and (low <= high). If the new range is
85 * not proper (or if vec itself is NULL), then no modifications are
86 * made to vec.<br><br>
87 *
88 * If the range is proper then vec->rng is allocated if NULL and then
89 * set using low and high. Then vec->vec is allocated (if NULL) or
90 * reallocated to size (high+1). The data in vec->vec is not
91 * initialized or changed. The member vec->accurate is set to FALSE.
92 *
93 * @param vec Pointer to the vec_vector to initialize.
94 * @param low The lower bound of the vector's range.
95 * @param high The upper bound of the vector's range.
96 * @return Returns 0 if the vector is initialized successfully,
97 * 1 if an improper range was specified, 2 if vec is NULL,
98 * and 3 if memory cannot be allocated.
99 */
100
101 ASC_DLLSPEC(void) vec_destroy(struct vec_vector *vec);
102 /**<
103 * Destroys a vector and its assocated data.
104 * Deallocates any memory held in vec->rng and vec->vec,
105 * and then deallocates the vector itself. NULL is tolerated
106 * for vec, vec->rng, or vec->vec.
107 *
108 * @param vec Pointer to the vec_vector to destroy.
109 */
110
111 ASC_DLLSPEC(void) vec_zero(struct vec_vector *vec);
112 /**<
113 * Zeroes a vector.
114 * The vector entries between vec->rng.low and vec->rng.high will
115 * be set to 0.0.
116 * The following are not allowed and are checked by assertion:
117 * - NULL vec
118 * - NULL vec->rng
119 * - NULL vec->vec
120 * - vec->rng->low < 0
121 * - vec->rng->low > vec->rng->high
122 *
123 * @param vec The vector to zero.
124 */
125
126 ASC_DLLSPEC(void) vec_copy(struct vec_vector *srcvec,
127 struct vec_vector *destvec);
128 /**<
129 * Copies the data from srcvec to destvec.
130 * The data in the range [srcvec->rng.low .. srcvec->rng.high]
131 * is copied to destvec starting at position destvec->rng.low.
132 * destvec must have at least as many elements in vec as srcvec.
133 * The following are not allowed and are checked by assertion:
134 * - NULL srcvec
135 * - NULL srcvec->rng
136 * - NULL srcvec->vec
137 * - srcvec->rng->low < 0
138 * - srcvec->rng->low > srcvec->rng->high
139 * - NULL destvec
140 * - NULL destvec->rng
141 * - NULL destvec->vec
142 * - destvec->rng->low < 0
143 *
144 * @param srcvec The vector to copy.
145 * @param destvec The vector to receive the copied data.
146 */
147
148 ASC_DLLSPEC(real64) vec_inner_product(struct vec_vector *vec1,
149 struct vec_vector *vec2);
150 /**<
151 * Calculates the dot product of 2 vectors.
152 * Dot [vec1->rng.low .. vec1->rng.high] with vec2 starting at
153 * position vec2->rng.low.
154 * The following are not allowed and are checked by assertion:
155 * - NULL vec1
156 * - NULL vec1->rng
157 * - NULL vec1->vec
158 * - vec1->rng->low < 0
159 * - vec1->rng->low > vec1->rng->high
160 * - NULL vec2
161 * - NULL vec2->rng
162 * - NULL vec2->vec
163 * - vec2->rng->low < 0
164 *
165 * @param vec1 The 1st vector for the dot product.
166 * @param vec2 The 2nd vector for the dot product.
167 * @todo solver/slv_common:vec_inner_product() could stand to be optimized.
168 */
169
170 ASC_DLLSPEC(real64) vec_square_norm(struct vec_vector *vec);
171 /**<
172 * Calculates the dot product of a vector with itself.
173 * Dot [vec->rng.low .. vec->rng.high] with itself and store the
174 * result in vec->norm2.
175 * The following are not allowed and are checked by assertion:
176 * - NULL vec
177 * - NULL vec->rng
178 * - NULL vec->vec
179 * - vec->rng->low < 0
180 * - vec->rng->low > vec->rng->high
181 *
182 * @param vec The vector for the dot product.
183 * @todo solver/slv_common:vec_square_norm() could stand to be optimized.
184 */
185
186 ASC_DLLSPEC(void) vec_matrix_product(mtx_matrix_t mtx,
187 struct vec_vector *vec,
188 struct vec_vector *prod,
189 real64 scale,
190 boolean transpose);
191 /**<
192 * Calculates the product of a vector, matrix, and scale factor.
193 * Stores prod := (scale)*(mtx)*(vec) if transpose = FALSE,
194 * or prod := (scale)*(mtx-transpose)(vec) if transpose = TRUE.
195 * vec and prod must be completely different.
196 * If (!transpose) vec->vec is assumed indexed by current col and
197 * prod->vec is indexed by current row of mtx.
198 * If (transpose) vec->vec is assumed indexed by current row and
199 * prod->vec is indexed by current col of mtx.
200 * The following are not allowed and are checked by assertion:
201 * - NULL mtx
202 * - NULL vec
203 * - NULL vec->rng
204 * - NULL vec->vec
205 * - vec->rng->low < 0
206 * - vec->rng->low > vec->rng->high
207 * - NULL prod
208 * - NULL prod->rng
209 * - NULL prod->vec
210 * - prod->rng->low < 0
211 * - prod->rng->low > prod->rng->high
212 *
213 * @param mtx The matrix for the product.
214 * @param vec The vector for the product.
215 * @param prod The vector to receive the matrix product.
216 * @param scale The scale factor by which to multiply the matrix product.
217 * @param transpose Flag for whether to use mtx or its transpose.
218 *
219 * @todo solver/slv_common:slv_mtx_product needs attention -
220 * does it go into mtx?
221 */
222
223 ASC_DLLSPEC(void ) vec_write(FILE *fp, struct vec_vector *vec);
224 /**<
225 * Write vector information to a file stream.
226 * Prints general information about the vector followed by the
227 * values in the range of the vector to file fp.
228 *
229 * @param fp The file stream to receive the report.
230 * @param vec The vector on which to report.
231 */
232
233 /*------------------------------------------------------------------------------
234 BLAS-LIKE FUNCTIONS
235 */
236
237 ASC_DLLSPEC(real64) vec_dot(int32 len, const real64 *a1, const real64 *a2);
238 /**<
239 * Calculates the dot product of 2 arrays of real64.
240 * This is an optimized routine (loop unrolled). It takes
241 * advantage of identical vectors. The 2 arrays must have
242 * at least len elements.
243 * The following are not allowed and are checked by assertion:
244 * - NULL a1
245 * - NULL a2
246 * - len < 0
247 *
248 * The same algorithm is used inside vec_inner_product(), so there
249 * is no need to use this function directly if you are using the
250 * vec_vector type.
251 *
252 * @param len The length of the 2 arrays.
253 * @param a1 The 1st array for the dot product.
254 * @param a2 The 2nd array for the dot product.
255 */
256
257 /**
258 @}
259 */
260
261 #endif

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22