Parent Directory | Revision Log

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

*Wed Jan 3 03:41:35 2007 UTC*
(13 years, 6 months ago)
by *johnpye*

File MIME type: text/x-chdr

File size: 11345 byte(s)

File MIME type: text/x-chdr

File size: 11345 byte(s)

Added doxygen comments for linear routines in base/generic/solver. Fixed up missing (still unimplemented) idalinear jacobian sjex.

1 | /* ASCEND modelling environment |

2 | Copyright (C) 1990 Karl Michael Westerberg |

3 | Copyright (C) 1993 Joseph Zaher |

4 | Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan |

5 | Copyright (C) 2006 Carnegie Mellon University |

6 | |

7 | This program is free software; you can redistribute it and/or modify |

8 | it under the terms of the GNU General Public License as published by |

9 | the Free Software Foundation; either version 2, or (at your option) |

10 | any later version. |

11 | |

12 | This program is distributed in the hope that it will be useful, |

13 | but WITHOUT ANY WARRANTY; without even the implied warranty of |

14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |

15 | GNU General Public License for more details. |

16 | |

17 | You should have received a copy of the GNU General Public License |

18 | along with this program; if not, write to the Free Software |

19 | Foundation, Inc., 59 Temple Place - Suite 330, |

20 | Boston, MA 02111-1307, USA. |

21 | *//** @file |

22 | ASCEND linear solver |

23 | |

24 | A linear system consists of a coefficient matrix (A) |

25 | and possibly several right-hand-sides (rhs). The |

26 | solution vector x sought can be that of either |

27 | <pre> |

28 | T |

29 | A x = rhs or A x = rhs </pre> |

30 | |

31 | depending on a specification inherent with rhs which |

32 | dictates whether or not A should be transposed. If a |

33 | rhs specifies transpose, then the vector itself is |

34 | expected to be indexed by the original column numbers |

35 | of the coefficient matrix and the solution vector shall |

36 | be indexed by original row numbers. Otherwise, rhs |

37 | is expected to be indexed by original row numbers while |

38 | the solution can be referenced using original column |

39 | numbers. The coefficient matrix and each rhs will be |

40 | preserved throughout solving, except that the |

41 | coefficient matrix may be permuted during reordering. |

42 | |

43 | Requires: |

44 | #include "utilities/ascConfig.h" |

45 | #include "mtx.h" |

46 | *//* |

47 | by Karl Michael Westerberg, created 2/6/90 |

48 | Last in CVS: $Revision: 1.6 $ $Date: 1997/07/18 12:14:20 $ $Author: mthomas $ |

49 | Authors: Karl Westerberg |

50 | Joseph Zaher |

51 | Dates: |

52 | 06/90 - original version |

53 | 04/91 - removed output assignment and partitioning |

54 | (belong in structural analysis) |

55 | 08/92 - added transpose ability |

56 | 01/94 - broke out linsol_invert() and linsol_solve() |

57 | */ |

58 | |

59 | #ifndef ASC_LINSOL_H |

60 | #define ASC_LINSOL_H |

61 | |

62 | /** @addtogroup linear @{ */ |

63 | |

64 | typedef struct linsol_header *linsol_system_t; |

65 | /**< linsol_system_t is the linear system handle. */ |

66 | |

67 | extern linsol_system_t linsol_create(void); |

68 | /**< |

69 | * Creates a linear system and returns a pointer to it. Initially the |

70 | * system has no coefficient matrix and no rhs. |

71 | */ |

72 | |

73 | extern void linsol_destroy(linsol_system_t sys); |

74 | /**< |

75 | * Destroys the linear system. The coefficient matrix and each rhs are |

76 | * not destroyed by this call. |

77 | */ |

78 | |

79 | extern void linsol_set_matrix(linsol_system_t sys, mtx_matrix_t mtx); |

80 | /**< |

81 | * Sets the coefficient matrix to mtx. |

82 | */ |

83 | |

84 | ASC_DLLSPEC(mtx_matrix_t ) linsol_get_matrix(linsol_system_t sys); |

85 | /**< |

86 | * Returns the coefficient matrix. |

87 | */ |

88 | |

89 | ASC_DLLSPEC(mtx_matrix_t ) linsol_get_inverse(linsol_system_t sys); |

90 | /**< |

91 | * Returns the inverse matrix. May be NULL. |

92 | */ |

93 | |

94 | extern void linsol_add_rhs(linsol_system_t sys, |

95 | real64 *rhs, |

96 | boolean transpose); |

97 | /**< |

98 | * Adds the given rhs to the collection of rhs's already part of the |

99 | * system. rhs should point to an array of numbers indexed by original |

100 | * column number if the linear system is to be solved using the transpose |

101 | * of the matrix or by original row number if the matrix is not to be |

102 | * transposed. This is determined using the boolean transpose. The |

103 | * rhs should be refered to in the future by its pointer. |

104 | */ |

105 | |

106 | extern void linsol_remove_rhs(linsol_system_t sys, real64 *rhs); |

107 | /**< |

108 | * Removes the given rhs from the system. The rhs is not destroyed, just |

109 | * removed from the system. |

110 | */ |

111 | |

112 | extern int linsol_number_of_rhs(linsol_system_t sys); |

113 | /**< |

114 | * Returns the number of rhs's currently part of the system. |

115 | */ |

116 | |

117 | ASC_DLLSPEC(real64 *) linsol_get_rhs(linsol_system_t sys, int n); |

118 | /**< |

119 | * Returns the n-th rhs, where rhs's are indexed in the order they were |

120 | * added using linsol_add_rhs() from 0 to (# rhs's)-1. NULL is returned |

121 | * if the index is out of range. |

122 | */ |

123 | |

124 | ASC_DLLSPEC(void ) linsol_matrix_was_changed(linsol_system_t sys); |

125 | /**< |

126 | * Informs the solver that a numerical value of a non-zero was changed. |

127 | * This must be called whenever any numerical changes to the matrix are |

128 | * made. |

129 | */ |

130 | |

131 | ASC_DLLSPEC(void ) linsol_rhs_was_changed(linsol_system_t sys, real64 *rhs); |

132 | /**< |

133 | * Informs the solver that the given rhs has been modified. This must be |

134 | * called whenever the rhs is modified. |

135 | */ |

136 | |

137 | extern void linsol_set_pivot_zero(linsol_system_t sys, real64 pivot_zero); |

138 | /**< |

139 | * Sets the pivot zero for the system. Pivots less than or equal to |

140 | * this value are regarded as zero. linsol_set_pivot_zero() will |

141 | * automatically call linsol_matrix_was_changed(). |

142 | */ |

143 | extern real64 linsol_pivot_zero(linsol_system_t sys); |

144 | /**< |

145 | Gets the pivot zero for the system. Pivots less than or equal to |

146 | this value are regarded as zero. |

147 | |

148 | Calls linsol_matrix_was_changed(). |

149 | */ |

150 | |

151 | extern void linsol_set_pivot_tolerance(linsol_system_t sys, real64 ptol); |

152 | /**< |

153 | * Sets the pivot tolerance for the system. Pivots less than this |

154 | * fraction of the maximum pivot value in the same row are disregarded. |

155 | * linsol_set_pivot_tolerance() will automatically call |

156 | * linsol_matrix_was_changed(). |

157 | */ |

158 | extern real64 linsol_pivot_tolerance(linsol_system_t sys); |

159 | /**< |

160 | Gets the pivot tolerance for the system. Pivots less than this |

161 | fraction of the maximum pivot value in the same row are disregarded. |

162 | |

163 | Calls linsol_matrix_was_changed(). |

164 | */ |

165 | |

166 | ASC_DLLSPEC(void ) linsol_reorder(linsol_system_t sys, mtx_region_t *region); |

167 | /**< |

168 | * The specified region of the coefficient matrix is reordered. This |

169 | * should be called before inverting the matrix. The specified region |

170 | * is assumed to contain only nonempty rows and columns. |

171 | */ |

172 | |

173 | ASC_DLLSPEC(void ) linsol_invert(linsol_system_t sys, mtx_region_t *region); |

174 | /**< |

175 | * Decompose the specified region of a copy of the coefficient matrix |

176 | * into upper and lower triangular factors (if necessary) which can be |

177 | * inverted easily when applied to any rhs. Matrix must be inverted in |

178 | * order to perform any of the operations below. The numerical rank and |

179 | * the smallest pivot encountered during pivoting are computed in the |

180 | * process. |

181 | */ |

182 | |

183 | extern int32 linsol_rank(linsol_system_t sys); |

184 | /**< |

185 | * Returns the rank of the system. The system must be previously |

186 | * inverted. |

187 | */ |

188 | |

189 | extern real64 linsol_smallest_pivot(linsol_system_t sys); |

190 | /**< |

191 | * Returns the smallest pivot accepted in solving the system. The |

192 | * system must be previously inverted. If no pivoting was performed, |

193 | * MAXDOUBLE is returned. |

194 | */ |

195 | |

196 | extern int linsol_get_pivot_sets(linsol_system_t sys, |

197 | unsigned *org_rowpivots, |

198 | unsigned *org_colpivots); |

199 | /**< |

200 | * Returns the set of original row numbers / original column numbers which |

201 | * have been pivoted. org_rowpivots and org_colpivots are assumed to be |

202 | * sets created by (or at least for) the set module with sufficient size |

203 | * before calling this function. They must also be previously NULLed. |

204 | * The system must be previously inverted. |

205 | * The sets input should be the result of set_create(neqn),set_create(nvar). |

206 | * There is no association of rows with columns here.<br><br> |

207 | * |

208 | * Status is 0 if not inverted, 1 if inverted. if 0, sets will not be |

209 | * changed. |

210 | */ |

211 | |

212 | extern int32 linsol_org_row_to_org_col(linsol_system_t sys, |

213 | int32 org_row); |

214 | /**< |

215 | * Returns the org_col associated with the given org_row/org_col. |

216 | * Pivoted original columns and pivoted original rows can be associated |

217 | * with one another via the pivot sequence. If the given |

218 | * org_row is not pivoted, a meaningless value is returned. The |

219 | * system must be previously inverted. If not inverted, a value will be |

220 | * returned, but linsol may reorder making the value wrong. |

221 | */ |

222 | extern int32 linsol_org_col_to_org_row(linsol_system_t sys, |

223 | int32 org_col); |

224 | /**< |

225 | * Returns the org_row associated with the given org_col. |

226 | * Pivoted original columns and pivoted original rows can be associated |

227 | * with one another via the pivot sequence. If the given |

228 | * org_col is not pivoted, a meaningless value is returned. The |

229 | * system must be previously inverted. If not inverted, a value is returned,these functions |

230 | * but linsol may reorder making the value wrong. |

231 | */ |

232 | |

233 | extern real64 linsol_org_row_dependency(linsol_system_t sys, |

234 | int32 dep, int32 ind); |

235 | /**< See linsol_org_col_dependency(). */ |

236 | extern real64 linsol_org_col_dependency(linsol_system_t sys, |

237 | int32 dep, int32 ind); |

238 | /**< |

239 | * Any original row / column of the coefficient matrix which when submitted |

240 | * to the linear solver is not pivoted, is called dependent and can be |

241 | * written as a linear combination of the independent (pivoted) original |

242 | * rows / columns. These functions return the previously computed |

243 | * coefficients of the linear combination. The system must be previously |

244 | * inverted and the independent row / column must be a member of the |

245 | * set of row / column pivots obtained by linsol_get_pivot_sets. |

246 | */ |

247 | |

248 | ASC_DLLSPEC(void ) linsol_solve(linsol_system_t sys, real64 *rhs); |

249 | /**< |

250 | * Solves the system of linear equations (if necessary) utilizing the |

251 | * specified rhs along with the previously inverted matrix. The rhs |

252 | * is automatically checked if the matrix factors need to be transposed |

253 | * or not. |

254 | */ |

255 | |

256 | extern real64 linsol_var_value(linsol_system_t sys, |

257 | real64 *rhs, int32 var); |

258 | /**< |

259 | * Returns the value of the variable in the solution vector associated |

260 | * with the given rhs and either the matrix or its transpose. The rhs |

261 | * must be solved for first. If rhs specifies transpose, then var is |

262 | * expected to be an original row number, otherwise it should be an |

263 | * original column number. |

264 | */ |

265 | |

266 | ASC_DLLSPEC(boolean ) linsol_copy_solution(linsol_system_t sys, |

267 | real64 *rhs, real64 *vector); |

268 | /**< |

269 | * Will copy the solution vector into the vector provided. |

270 | * The user is responsible for allocating and deallocating said |

271 | * vector. The provided vector should be at least |

272 | * mtx_cacpacity(mtx), where mtx is the matrix that linsol_set_matrix, |

273 | * was called with. The returned vector will be indexed in the same |

274 | * way that the rhs is indexed.<br><br> |

275 | * |

276 | * Returns TRUE in the event of any of any errors, FALSE otherwise. |

277 | */ |

278 | |

279 | extern real64 linsol_eqn_residual(linsol_system_t sys, |

280 | real64 *rhs, int32 eqn); |

281 | /**< |

282 | * Returns the equation residual using the solution vector associated |

283 | * with the given rhs and either the matrix or its transpose. |

284 | * <pre> |

285 | * T |

286 | * residual = A x - b or residual = A x - b |

287 | * </pre> |

288 | * The rhs must be solved for first. If rhs specifies transpose, then |

289 | * eqn is expected to be an original column number, otherwise it should |

290 | * be an original row number. |

291 | */ |

292 | |

293 | /** @} */ |

294 | |

295 | #endif /* ASC_LINSOL_H */ |

296 |

john.pye@anu.edu.au | ViewVC Help |

Powered by ViewVC 1.1.22 |