Parent Directory | Revision Log

Revision **1062** -
(**show annotations**)
(**download**)
(**as text**)

*Sun Jan 7 07:21:02 2007 UTC*
(14 years ago)
by *johnpye*

File MIME type: text/x-chdr

File size: 9514 byte(s)

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 |