Parent Directory | Revision Log

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

*Wed Oct 24 13:04:05 2007 UTC*
(12 years, 9 months ago)
by *jpye*

File MIME type: text/x-chdr

File size: 17130 byte(s)

File MIME type: text/x-chdr

File size: 17130 byte(s)

IPOPT gets installed if built. added relman_hessian_count placeholder.

1 | /* ASCEND modelling environment |

2 | Copyright (C) 2006 Carnegie Mellon University |

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

4 | Copyright (C) 1993 Joseph Zaher |

5 | Copyright (C) 1990 Karl Michael Westerberg |

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 | Relation manipulator module for the SLV solver. |

23 | |

24 | This module will provide supplemental operations for |

25 | relations such as simplification, evaluation, and |

26 | differentiation. |

27 | |

28 | Dates: 06/90 - original version |

29 | 06/93 - separated out exprman |

30 | 11/93 - added relman_calc_satisfied |

31 | |

32 | *//* |

33 | by Karl Michael Westerberg and Joseph Zaher, 2/6/90 |

34 | Last in CVS: $Revision: 1.29 $ $Date: 1998/04/23 23:56:24 $ $Author: ballan $ |

35 | */ |

36 | |

37 | #ifndef ASC_RELMAN_H |

38 | #define ASC_RELMAN_H |

39 | |

40 | #include <utilities/ascConfig.h> |

41 | |

42 | #include <linear/mtx.h> |

43 | |

44 | #include "var.h" |

45 | #include "rel.h" |

46 | |

47 | /** @addtogroup solver Solver |

48 | @{ |

49 | */ |

50 | |

51 | #define relman_is_linear(a,b) (FALSE) |

52 | /**< |

53 | * Determines whether or not the given relation is linear in |

54 | * all of the variables which pass through the variable filter, treating |

55 | * those variables which fail to pass as constants.<br><br> |

56 | * |

57 | * Example: |

58 | * x1 + x2 >= 3 is a linear relation. |

59 | */ |

60 | |

61 | extern real64 relman_linear_coef(struct rel_relation *rel, |

62 | struct var_variable *var, |

63 | var_filter_t *filter); |

64 | /**< |

65 | * Computes the coefficient of the given variable in a linear |

66 | * relation. If var=NULL, then the "RHS" is returned instead. More |

67 | * nprecisely, "a[var]" is returned where:<br><br> |

68 | * |

69 | * rel : sum[variables v](a[v] * v) COMPARISON a[NULL]<br><br> |

70 | * |

71 | * It is assumed that the relation is linear, otherwise, |

72 | * something will be returned, but it won't be very meaningful. |

73 | */ |

74 | |

75 | #if 0 |

76 | extern void relman_simplify(struct rel_relation *rel, int opt_level); |

77 | /**< NOT IMPLEMENTED |

78 | * The left and right hand sides of the given relation are simplified |

79 | * to the extent given by opt_level. The effect of varying values of |

80 | * opt_level is given in the description for exprman_simplify(). |

81 | */ |

82 | |

83 | extern void relman_dissolve_vars(struct rel_relation *rel, var_filter_t *filter); |

84 | /**< NOT IMPLEMENTED |

85 | * Variables which pass through the filter are replaced in the |

86 | * relation by their current values. |

87 | */ |

88 | #endif |

89 | |

90 | extern void relman_decide_incidence(struct rel_relation *rel); |

91 | /**< |

92 | * Sets the incidence field of each variable which is found to be |

93 | * incident in the relation rel to TRUE. If these variables make |

94 | * up a subset of some larger variable list, it is important to first |

95 | * set the incidence field of all of the variables to FALSE before |

96 | * using this function in order to determine the unattached variables. |

97 | */ |

98 | |

99 | extern void relman_get_incidence(struct rel_relation *rel, |

100 | var_filter_t *filter, |

101 | mtx_matrix_t matrix); |

102 | /**< |

103 | * Upon return, coefficient (rel_n,var_n) (using original row and column |

104 | * numbers) is non-zero if and only if the relation rel with index rel_n |

105 | * depends on a variable with index var_n. |

106 | */ |

107 | |

108 | ASC_DLLSPEC real64 relman_eval(struct rel_relation *rel, int32 *calc_okp, int safe); |

109 | /**< |

110 | The residual of the relation is calculated and returned. In addition |

111 | to returning the residual, the residual field of the relation is |

112 | updated. The residual field of the relation is not updated when an error |

113 | occurs. |

114 | |

115 | @param safe If set nonzero, "safe" functions are used for evaluation (means |

116 | that overflows, divide by zero, etc are avoided) |

117 | @param calc_ok (returned) status of the calculation. 0=error, else ok. |

118 | @return residual (= LHS - RHS, regardless of comparison) |

119 | |

120 | @NOTE |

121 | This function should be surrounded by Asc_SignalHandlerPush/Pop both |

122 | with arguments (SIGFPE,SIG_IGN). If it is being called in a loop, |

123 | the push/pop should be _outside_ the loop. |

124 | */ |

125 | |

126 | ASC_DLLSPEC int32 relman_obj_direction(struct rel_relation *rel); |

127 | /**< |

128 | * Returns: |

129 | * - direction = -1 if objective is minimization |

130 | * - direction = 1 if objective is maximization |

131 | * - direction = 0 otherwise. (ie. if not an objective) |

132 | */ |

133 | |

134 | ASC_DLLSPEC real64 relman_scale(struct rel_relation *rel); |

135 | /**< |

136 | * Calculates relation nominal scaling factor for |

137 | * current values stored in the relations variables. |

138 | * Fills the relations nominal field and also returns |

139 | * the relations nominal. |

140 | */ |

141 | |

142 | #define relman_diff(a,b,c,d) (abort(),1) |

143 | /**< |

144 | Calculates the derivative of the relation residual with respect to |

145 | the specified variable and stuffs it in pd. if problem with |

146 | calculation, returns 1, else 0. |

147 | If the value of safe is nonzero, "safe" functions will be used to |

148 | calculate the residual. |

149 | |

150 | @TODO relman_diff() needs to be reimplemented - needs compiler-side work. |

151 | */ |

152 | |

153 | ASC_DLLSPEC int relman_diff2(struct rel_relation *rel, |

154 | const var_filter_t *filter, |

155 | real64 *derivatives, |

156 | int32 *variables, |

157 | int32 *count, |

158 | int32 safe); |

159 | /**< |

160 | Calculates the row of the jacobian matrix (the transpose gradient of |

161 | the relation residual, $ \grad^{T}(f) $) corresponding to the relation |

162 | rel. The filter determines which variables actually contribute to the |

163 | jacobian. |

164 | |

165 | derivatives[i] will contain the derivative of the relation with |

166 | respect to the variable whose solver index is stored in |

167 | variables[i]. |

168 | |

169 | @param rel Relation being differentiated |

170 | @param filter Filter for variables for which derivs are desired |

171 | @param safe If nonzero, "safe" functions are used to for the calculations |

172 | @param derivatives output vector (allocated by the calling function) |

173 | @param variables output vector (allocated by the calling function) |

174 | @param count output value, will be set to the number of elements assigned upon exit. |

175 | |

176 | @return 0 on success, non-zero if an error is encountered in the calculation |

177 | */ |

178 | |

179 | |

180 | ASC_DLLSPEC int relman_diff3(struct rel_relation *rel, |

181 | const var_filter_t *filter, |

182 | real64 *derivatives, |

183 | struct var_variable **variables, |

184 | int32 *count, |

185 | int32 safe); |

186 | /**< as relman_diff2 but fills a var_variable* array intest of an index array. */ |

187 | |

188 | ASC_DLLSPEC int relman_diff_grad(struct rel_relation *rel, |

189 | const var_filter_t *filter, |

190 | real64 *derivatives, |

191 | int32 *variables_master, |

192 | int32 *variables_solver, |

193 | int32 *count, |

194 | real64 *resid, |

195 | int32 safe); |

196 | /**< |

197 | * Calculates the row of the jacobian matrix (the transpose gradient of |

198 | * the relation residual grad^T(f) ) corresponding to the relation |

199 | * rel. The filter determines which variables actually contribute to the |

200 | * jacobian. The residual of the relation is also computed and returned. |

201 | * If an error is encountered in the calculation, the status returned is |

202 | * 1. Status = 0 is OK. |

203 | * If the value of safe is nonzero, "safe" functions are used to for |

204 | * the calculations.<br><br> |

205 | * The calling function should allocate the output vectors 'derivatives', |

206 | * 'variables_master' and 'variables_solver'. 'count' will be set to |

207 | * the number of elements assigned upon exit. |

208 | * derivative(i) will contain the derivative of the relation with |

209 | * respect to the variable whose master index is stored in |

210 | * variables_master(i). The solver index of each variable is stored in |

211 | * variables_solver(i). |

212 | * |

213 | * There are two differences wrt to relman_diff2: |

214 | * - the master index (solver independent) is obtained |

215 | * - the residual is evaluated |

216 | */ |

217 | |

218 | ASC_DLLSPEC int relman_diffs(struct rel_relation *rel, |

219 | const var_filter_t *filter, mtx_matrix_t mtx, |

220 | real64 *resid, int safe); |

221 | /**< |

222 | Calculates the row of the jacobian matrix (the transpose gradient of |

223 | the relation residual grad^T(f) ) corresponding to the relation |

224 | rel. The filter determines which variables actually contribute to the |

225 | jacobian. The residual of the relation is also computed and returned. |

226 | If an error is encountered in the calculation, the status returned is |

227 | 1 and the residual is set to some number we managed to calculate, |

228 | while the gradient is discarded. status = 0 is OK. |

229 | |

230 | @param rel relation for which jacobian entries are required |

231 | @param filter filter for which variables should actually contribute to the jacobian |

232 | @param mtx matrix into which the row (corresponding to rel) is written |

233 | @param safe if non-zero, "safe" functions are used to for the calucaltions. |

234 | |

235 | It doesn't matter how you have permuted the columns and rows: |

236 | for the vars which pass the filter you send we |

237 | fill the org row determined by rel_sindex and the org cols |

238 | determined by var_sindex. |

239 | |

240 | @return 0 on success, 1 on calculation error (residual will be returned, grad discarded) |

241 | |

242 | @NOTE The row of the mtx corresponding to rel should be cleared |

243 | before calling this function, since this FILLS with the gradient.<br><br> |

244 | |

245 | @NOTE *changed* -- This operator used to just ADD on top of any incidence |

246 | already in the row. This is not TRUE now. |

247 | |

248 | @TODO This operator really needs to be redesigned so it can deal with |

249 | harwellian matrices, glassbox rels and blackbox. |

250 | */ |

251 | |

252 | extern int32 relman_diff_harwell(struct rel_relation **rlist, |

253 | var_filter_t *vfilter, rel_filter_t *rfilter, |

254 | int32 rlen, int32 bias, int32 mors, |

255 | real64 *avec, int32 *ivec, int32 *jvec); |

256 | /**< |

257 | * This fills an "a-i-j" sparse matrix in the avec/ivec/jvec given. |

258 | * @param rlist struct rel_relation **, list of relations rlen long. |

259 | * @param vfilter var_filter_t *, stuffs gradient for matching variables only. |

260 | * @param rlen int32, length of list of relations. |

261 | * @param bias int32, 0 = row grouped together, 1 = column grouped together. |

262 | * There is a substantial penalty for bias = 1. we MODEL by row. |

263 | * @param mors int32, 0 = master var index of columns, master rel index of rows |

264 | * 1 = solver var index of columns, master rel index of rows |

265 | * 2 = master var index of columns, solver rel index of rows |

266 | * 3 = solver var index of columns, solver rel index of rows |

267 | * Size of avec,ivec,jvec given is assumed big enough. |

268 | * big_enough = relman_jacobian_count(rlist,rlen,vfilter,rfilter,&dummy); |

269 | * If ivec or jvec given is NULL, then neither is stuffed, though avec is. |

270 | @return 0 on success, <0 on floating point errors, 1 on unrecoverable error. |

271 | |

272 | err = 1 --> unrecoverable error/bad input. caller should probably punt. |

273 | err < 0 --> -(number of floating point errors in evaluation). |

274 | The matrix will contain an approximation only. |

275 | |

276 | @todo relman_diff_harwell() bias == 1 is not yet implemented. |

277 | */ |

278 | |

279 | ASC_DLLSPEC int32 relman_jacobian_count(struct rel_relation **rlist, |

280 | int32 rlen, |

281 | var_filter_t *vfilter, |

282 | rel_filter_t *rfilter, |

283 | int32 *rhomax); |

284 | /**< |

285 | * Return the number of nonzero gradient entries in the equations |

286 | * given. Only equations passing rfilter and entries passing vfilter |

287 | * are counted. rlen is the length of the relation list. |

288 | * *rhomax is the largest row count on return. |

289 | */ |

290 | |

291 | ASC_DLLSPEC int32 relman_hessian_count( |

292 | struct rel_relation **rlist, int32 rlen |

293 | , var_filter_t *vfilter, rel_filter_t *rfilter |

294 | , int32 *rhomax |

295 | ); |

296 | /**< |

297 | * Return the number of nonzero gradient entries in the equations |

298 | * given. Only equations passing rfilter and entries passing vfilter |

299 | * are counted. rlen is the length of the relation list. |

300 | * *rhomax is the largest row count on return. |

301 | */ |

302 | |

303 | ASC_DLLSPEC boolean relman_calc_satisfied_scaled(struct rel_relation *rel, |

304 | real64 tolerance); |

305 | /**< |

306 | * This definition of satisfaction includes the notion |

307 | * of scaling by the relation nominal before comparison. |

308 | * @see relman_calc_satisfied. |

309 | */ |

310 | ASC_DLLSPEC boolean relman_calc_satisfied(struct rel_relation *rel, |

311 | real64 tolerance); |

312 | /**< |

313 | * Returns TRUE or FALSE depending on whether the relation whose residual |

314 | * has been previously calculated is satisfied based on the value stored |

315 | * in the residual field. The satisfied field of the relation is also |

316 | * updated. A tolerance specification allows equalities to be declared |

317 | * satisfied as long as their residuals are close to zero. |

318 | * @see relman_calc_satisfied_scaled. |

319 | */ |

320 | |

321 | #define relman_directly_solve(r,s,a,n) \ |

322 | relman_directly_solve_new(r,s,a,n,1.0e-8) |

323 | /**< @see relman_directly_solve_new(). */ |

324 | extern real64 *relman_directly_solve_new(struct rel_relation *rel, |

325 | struct var_variable *solvefor, |

326 | int *able, |

327 | int *nsolns, |

328 | real64 tol); |

329 | /**< |

330 | * Attempts to solve the given equation for the given variable. If this |

331 | * function is able to determine the solution set, then *able is set to |

332 | * 1 and a newly allocated solution list is returned: *nsolns will be |

333 | * set to the length of this array. Otherwise *able is 0 and NULL |

334 | * is returned. NULL *may* also be returned if the solution set is empty. |

335 | * A return of able == 1, solution_list != NULL, and nsolns == 0 is |

336 | * possible for certain classes of floating point exceptions. |

337 | * It is assumed that the relation is a condition of equality.<br><br> |

338 | * |

339 | * relman_directly_solve_new() handles passing in a tolerance for glassbox |

340 | * relations so a rootfinder can do the work rather than leaving it to |

341 | * someone else. The rootfinder is based on Brent's algorithm. Old clients of |

342 | * relman_directly solve are grandfathered at a default tolerance of 1e-8. |

343 | * Once all these clients are gone, go back to the old name space for |

344 | * the new function.<br><br> |

345 | * |

346 | * Do NOT free or keep a persistent pointer to the solution_list this |

347 | * function returns. |

348 | */ |

349 | |

350 | #define relman_make_string_infix(sys,rel) \ |

351 | relman_make_vstring_infix((sys),(rel),TRUE) |

352 | /**< @see relman_make_xstring_infix() */ |

353 | #define relman_make_string_postfix(sys,rel) \ |

354 | relman_make_vstring_postfix((sys),(rel),TRUE) |

355 | /**< @see relman_make_xstring_infix() */ |

356 | #define relman_make_xstring_infix(sys,rel) \ |

357 | relman_make_vstring_infix((sys),(rel),FALSE) |

358 | /**< |

359 | @return string |

360 | @param sys |

361 | @param rel struct rel_relation *rel |

362 | |

363 | Creates a sufficiently large string (you must free it when you're |

364 | done with it) into which it converts a relation. The string will be |

365 | terminated with a '\0' character. |

366 | |

367 | The xstring versions of this call make strings where all the variables |

368 | are written as x<varindex> (e.g. x23) rather than as object names. |

369 | The MASTER index (var_mindex) is used, not the solver's sindex. |

370 | Currently the compiler does not support xstring postfix format, |

371 | but could easily do so if needed. |

372 | |

373 | The name of a var is context dependent, so you have to provide the |

374 | slv_system_t from which you got the relation. |

375 | |

376 | @see relman_make_string_postfix |

377 | @see relman_make_string_infix |

378 | */ |

379 | |

380 | #if 0 /* needs compiler-side work */ |

381 | # define relman_make_xstring_postfix(sys,rel) \ |

382 | relman_make_vstring_postfix((sys),(rel),FALSE) |

383 | #else |

384 | # define relman_make_xstring_postfix(sys,rel) \ |

385 | dummy_rel_string((sys),(rel),0) |

386 | #endif |

387 | /**< |

388 | * Not suppported. |

389 | * @TODO Consider adding support for xstring postfix format. |

390 | */ |

391 | |

392 | ASC_DLLSPEC char *relman_make_vstring_infix(slv_system_t sys, |

393 | struct rel_relation *rel, |

394 | int style); |

395 | /**< |

396 | * Implementation function for relman_make_string_infix() and |

397 | * relman_make_xstring_infix(). Do not call this function |

398 | * directly - use one of the macros instead. |

399 | */ |

400 | extern char *relman_make_vstring_postfix(slv_system_t sys, |

401 | struct rel_relation *rel, |

402 | int style); |

403 | /**< |

404 | * Implementation function for relman_make_string_postfix(). and |

405 | * Do not call this function directly - use the macro instead. |

406 | */ |

407 | |

408 | extern char *dummyrelstring(slv_system_t sys, |

409 | struct rel_relation *rel, |

410 | int style); |

411 | /**< Temporary no-op function to placehold unimplemented io functions. */ |

412 | |

413 | extern void relman_free_reused_mem(void); |

414 | /**< Call when desired to free memory cached internally. */ |

415 | |

416 | /* @} */ |

417 | |

418 | #endif /* ASC_RELMAN_H */ |

419 |

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

Powered by ViewVC 1.1.22 |