Parent Directory | Revision Log

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

*Tue May 24 01:31:12 2016 UTC*
(8 years, 1 month ago)
by *jpye*

File MIME type: text/x-chdr

File size: 11249 byte(s)

File MIME type: text/x-chdr

File size: 11249 byte(s)

Creating new branch for [[User:Georgy]] for [[GSOC2016]], from trunk r3104.

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, see <http://www.gnu.org/licenses/>. |

19 | *//** @file |

20 | ASCEND linear solver |

21 | |

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

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

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

25 | <pre> |

26 | T |

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

28 | |

29 | depending on a specification inherent with rhs which |

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

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

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

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

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

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

36 | the solution can be referenced using original column |

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

38 | preserved throughout solving, except that the |

39 | coefficient matrix may be permuted during reordering. |

40 | *//* |

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

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

43 | Authors: Karl Westerberg |

44 | Joseph Zaher |

45 | Dates: |

46 | 06/90 - original version |

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

48 | (belong in structural analysis) |

49 | 08/92 - added transpose ability |

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

51 | */ |

52 | |

53 | #ifndef ASC_LINSOL_H |

54 | #define ASC_LINSOL_H |

55 | |

56 | #include <ascend/general/platform.h> |

57 | #include "mtx.h" |

58 | |

59 | /** @addtogroup linear Linear |

60 | @{ |

61 | */ |

62 | |

63 | typedef struct linsol_header *linsol_system_t; |

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

65 | |

66 | extern linsol_system_t linsol_create(void); |

67 | /**< |

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

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

70 | */ |

71 | |

72 | extern void linsol_destroy(linsol_system_t sys); |

73 | /**< |

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

75 | * not destroyed by this call. |

76 | */ |

77 | |

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

79 | /**< |

80 | * Sets the coefficient matrix to mtx. |

81 | */ |

82 | |

83 | ASC_DLLSPEC mtx_matrix_t linsol_get_matrix(linsol_system_t sys); |

84 | /**< |

85 | * Returns the coefficient matrix. |

86 | */ |

87 | |

88 | ASC_DLLSPEC mtx_matrix_t linsol_get_inverse(linsol_system_t sys); |

89 | /**< |

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

91 | */ |

92 | |

93 | extern void linsol_add_rhs(linsol_system_t sys, |

94 | real64 *rhs, |

95 | boolean transpose); |

96 | /**< |

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

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

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

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

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

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

103 | */ |

104 | |

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

106 | /**< |

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

108 | * removed from the system. |

109 | */ |

110 | |

111 | extern int linsol_number_of_rhs(linsol_system_t sys); |

112 | /**< |

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

114 | */ |

115 | |

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

117 | /**< |

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

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

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

121 | */ |

122 | |

123 | ASC_DLLSPEC void linsol_matrix_was_changed(linsol_system_t sys); |

124 | /**< |

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

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

127 | * made. |

128 | */ |

129 | |

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

131 | /**< |

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

133 | * called whenever the rhs is modified. |

134 | */ |

135 | |

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

137 | /**< |

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

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

140 | * automatically call linsol_matrix_was_changed(). |

141 | */ |

142 | extern real64 linsol_pivot_zero(linsol_system_t sys); |

143 | /**< |

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

145 | this value are regarded as zero. |

146 | |

147 | Calls linsol_matrix_was_changed(). |

148 | */ |

149 | |

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

151 | /**< |

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

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

154 | * linsol_set_pivot_tolerance() will automatically call |

155 | * linsol_matrix_was_changed(). |

156 | */ |

157 | extern real64 linsol_pivot_tolerance(linsol_system_t sys); |

158 | /**< |

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

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

161 | |

162 | Calls linsol_matrix_was_changed(). |

163 | */ |

164 | |

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

166 | /**< |

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

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

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

170 | */ |

171 | |

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

173 | /**< |

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

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

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

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

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

179 | * process. |

180 | */ |

181 | |

182 | extern int32 linsol_rank(linsol_system_t sys); |

183 | /**< |

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

185 | * inverted. |

186 | */ |

187 | |

188 | extern real64 linsol_smallest_pivot(linsol_system_t sys); |

189 | /**< |

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

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

192 | * MAXDOUBLE is returned. |

193 | */ |

194 | |

195 | extern int linsol_get_pivot_sets(linsol_system_t sys, |

196 | unsigned *org_rowpivots, |

197 | unsigned *org_colpivots); |

198 | /**< |

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

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

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

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

203 | * The system must be previously inverted. |

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

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

206 | * |

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

208 | * changed. |

209 | */ |

210 | |

211 | extern int32 linsol_org_row_to_org_col(linsol_system_t sys, |

212 | int32 org_row); |

213 | /**< |

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

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

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

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

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

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

220 | */ |

221 | extern int32 linsol_org_col_to_org_row(linsol_system_t sys, |

222 | int32 org_col); |

223 | /**< |

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

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

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

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

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

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

230 | */ |

231 | |

232 | extern real64 linsol_org_row_dependency(linsol_system_t sys, |

233 | int32 dep, int32 ind); |

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

235 | extern real64 linsol_org_col_dependency(linsol_system_t sys, |

236 | int32 dep, int32 ind); |

237 | /**< |

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

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

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

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

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

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

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

245 | */ |

246 | |

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

248 | /**< |

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

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

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

252 | * or not. |

253 | */ |

254 | |

255 | extern real64 linsol_var_value(linsol_system_t sys, |

256 | real64 *rhs, int32 var); |

257 | /**< |

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

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

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

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

262 | * original column number. |

263 | */ |

264 | |

265 | ASC_DLLSPEC boolean linsol_copy_solution(linsol_system_t sys, |

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

267 | /**< |

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

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

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

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

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

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

274 | * |

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

276 | */ |

277 | |

278 | extern real64 linsol_eqn_residual(linsol_system_t sys, |

279 | real64 *rhs, int32 eqn); |

280 | /**< |

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

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

283 | * <pre> |

284 | * T |

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

286 | * </pre> |

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

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

289 | * be an original row number. |

290 | */ |

291 | |

292 | /** @} */ |

293 | |

294 | #endif /* ASC_LINSOL_H */ |

295 |

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

Powered by ViewVC 1.1.22 |