Parent Directory | Revision Log

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

*Mon Jul 23 14:30:35 2007 UTC*
(12 years, 11 months ago)
by *jpye*

File MIME type: text/x-chdr

File size: 13255 byte(s)

File MIME type: text/x-chdr

File size: 13255 byte(s)

More work on IPOPT optimizer. Prevented repeated slv_get_status errors; added exception in getSimulationStatus in C++.

1 | /* ASCEND modelling environment |

2 | Copyright (C) 2007 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 | Encapsulation of the NLA solver interface, separate from the |

20 | system definition and access routines. |

21 | *//* |

22 | created from bits of slv.c, slv_stdcalls.c, etc. |

23 | John Pye, 2007. |

24 | */ |

25 | |

26 | #ifndef ASC_SOLVER_H |

27 | #define ASC_SOLVER_H |

28 | |

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

30 | #include <system/slv_client.h> |

31 | |

32 | /*----------------------------------------------------------------------- |

33 | SOLVER HOOKS AND REGISTRATION DATA STRUCTURE |

34 | */ |

35 | |

36 | /** @todo We will explain all these later in this file someday soon. */ |

37 | typedef SlvClientToken (SlvClientCreateF) (slv_system_t,int *); |

38 | typedef int (SlvClientDestroyF) (slv_system_t,SlvClientToken); |

39 | typedef int (SlvClientEligibleF) (slv_system_t); |

40 | typedef int32 (SlvGetDefParamsF) (slv_system_t,SlvClientToken,slv_parameters_t *); |

41 | typedef void (SlvGetParamsF) (slv_system_t, SlvClientToken, slv_parameters_t *); |

42 | typedef void (SlvSetParamsF) (slv_system_t, SlvClientToken, slv_parameters_t *); |

43 | typedef int (SlvGetStatusF) (slv_system_t, SlvClientToken, slv_status_t *); |

44 | typedef linsolqr_system_t (SlvGetLinSysF)(slv_system_t, SlvClientToken); |

45 | typedef mtx_matrix_t (SlvGetSysMtxF)(slv_system_t, SlvClientToken); |

46 | typedef void (SlvDumpInfoF)(slv_system_t, SlvClientToken,int); |

47 | typedef int (SlvSolveF)(slv_system_t, SlvClientToken); |

48 | |

49 | /** Registration information for a solver. |

50 | @TODO Complete documentation of slv_registration_data members. |

51 | */ |

52 | typedef struct slv_registration_data { |

53 | int number; |

54 | /**< we set number AFTER the client registration returns 0. |

55 | client sets all the rest, starting with a symbolic name */ |

56 | |

57 | const char *name; /**< symbolic name for solver (required). */ |

58 | /* |

59 | Required functions |

60 | */ |

61 | SlvClientCreateF *ccreate; /**< (required) */ |

62 | SlvClientDestroyF *cdestroy; /**< (required) */ |

63 | SlvClientEligibleF *celigible; /**< (required) */ |

64 | SlvGetDefParamsF *getdefparam; /**< Function that will create default solver-parameter structure (required) */ |

65 | SlvGetParamsF *get_parameters;/**< (required) */ |

66 | SlvSetParamsF *setparam; /**< (required) */ |

67 | SlvGetStatusF *getstatus; /**< (required) */ |

68 | SlvSolveF *solve; /**< (required) */ |

69 | /* |

70 | Functions we really want, but can live without if your solver is old |

71 | and klunky. Your solver may not 'look good' in an interactive environment, |

72 | but then those nasty batch codes seldom do anyway. |

73 | Redesign your bloody batch code. |

74 | */ |

75 | SlvSolveF *presolve; /**< (desired) */ |

76 | SlvSolveF *iterate; /**< (desired) */ |

77 | SlvSolveF *resolve; /**< (desired) */ |

78 | /** |

79 | Strictly Optional Functions |

80 | */ |

81 | SlvGetLinSysF *getlinsys; /**< (optional) */ |

82 | SlvGetSysMtxF *get_sys_mtx; /**< (optional) */ |

83 | SlvDumpInfoF *dumpinternals; /**< (optional) */ |

84 | } SlvFunctionsT; |

85 | |

86 | |

87 | typedef int SolverRegisterFn(void); |

88 | /**< |

89 | Registration function for solvers. Should add solver to the list of |

90 | available solvers for NLA/LP/NLP/MINLP problems. |

91 | @return 0 on success |

92 | */ |

93 | |

94 | /*------------------------------------------------------------------------------ |

95 | REGISTRATION SOLVERS AND QUERYING OF SOLVER LIST |

96 | */ |

97 | |

98 | ASC_DLLSPEC int solver_register(const SlvFunctionsT *solver); |

99 | |

100 | ASC_DLLSPEC int SlvRegisterStandardClients(void); |

101 | /**< |

102 | Attempts to register solvers slv0 through (as of 6/96) slv7. |

103 | |

104 | The solvers registered here are those linked at build time of the |

105 | ascend binary. See slv_client.h for registering dynamically loaded |

106 | solvers. |

107 | |

108 | @return number of solvers registered successfully |

109 | */ |

110 | |

111 | ASC_DLLSPEC const struct gl_list_t *solver_get_engines(); |

112 | /**< |

113 | Get the list of engines. For the purpose of output to the GUI. |

114 | */ |

115 | |

116 | ASC_DLLSPEC const SlvFunctionsT *solver_engine(const int number); |

117 | /**< |

118 | @param number solver ID number to check for |

119 | @return SlvFunctions for this solver, if the number is valid, else NULL |

120 | */ |

121 | |

122 | ASC_DLLSPEC const SlvFunctionsT *solver_engine_named(const char *name); |

123 | /**< |

124 | @param name name of solver to check for |

125 | @return SlvFunctions for this solver, if the name is found, else NULL |

126 | */ |

127 | |

128 | /*------------------------------------------------------------------------------ |

129 | HOOKS INTO SOLVER ENGINE, CALLED BY ASCEND |

130 | */ |

131 | |

132 | ASC_DLLSPEC int slv_get_status(slv_system_t sys, slv_status_t *status); |

133 | /**< |

134 | Copies the current system status into the given structure. |

135 | @return 0 on success, or nonzero if there is a problem determining status. |

136 | */ |

137 | |

138 | ASC_DLLSPEC linsolqr_system_t slv_get_linsolqr_sys(slv_system_t sys); |

139 | /**< |

140 | Returns the linsolqr system used, or NULL if none. |

141 | @deprecated { THIS CALL SHOULD GO AWAY } |

142 | */ |

143 | |

144 | ASC_DLLSPEC mtx_matrix_t slv_get_sys_mtx(slv_system_t sys); |

145 | /**< |

146 | Returns the mtx used, or NULL if none. The user should check. |

147 | |

148 | @deprecated {THIS CALL SHOULD GO AWAY} |

149 | |

150 | @NOTE this function is referenced by the C++ api (Simulation::getMatrix). |

151 | So don't don't vanish it! -- JP 20070113 @ENDNOTE |

152 | **/ |

153 | |

154 | ASC_DLLSPEC void slv_dump_internals(slv_system_t sys, int level); |

155 | /**< |

156 | Will spew whatever the solver interface developer feels like to |

157 | stderr. Larger values of level will give more detailed information, |

158 | we hope. No specification is made with regard to what the |

159 | information will be. returns -1 if solver gutless. This is provided |

160 | principally to facilitate debugging a little. |

161 | |

162 | @TODO fix dubious documentation (return type is void...) |

163 | */ |

164 | |

165 | ASC_DLLSPEC int slv_presolve(slv_system_t sys); |

166 | /**< |

167 | Prepares the system for solving. This must be called before the |

168 | system is solved, but after everything about the system is set up |

169 | (i.e. variables and relations cannot be changed IN ANY WAY, objective |

170 | function cannot be modified, boundaries cannot be modified, or even |

171 | repermuted, and a new solver cannot be selected: some parameters may |

172 | be modified, they will be marked as such). The system essentially |

173 | becomes "read-only". If anything is modified after slv_presolve was |

174 | called, slv_presolve must be called again before solving (EXCEPTIONS: |

175 | slv_resolve may do for a certain restricted class of changes). @par |

176 | |

177 | It is at this point that the variable list is created if it does not |

178 | already exist and the newly created variables are indexed in the |

179 | order they end up. The relation list is indexed as well in the order |

180 | it is received. @par |

181 | |

182 | Among other things, this function will perform structural analysis |

183 | so that structural analysis flags in the status will be accurate. |

184 | |

185 | @return 0 on success, 1 if errors occurred (they will be output via ERROR_REPORTER) |

186 | */ |

187 | |

188 | ASC_DLLSPEC int slv_resolve(slv_system_t sys); |

189 | /**< |

190 | This function re-prepares the system for solving. This function may |

191 | be used instead of slv_presolve, provided the system was partially |

192 | or completely solved before, and then the only changes to the system |

193 | since are as follows: |

194 | |

195 | @li any parameter except "partition". |

196 | @li variable values. |

197 | @li variable nominal values. |

198 | @li variable bounds. |

199 | |

200 | In particular, the following changes are NOT allowed: |

201 | |

202 | @li variable fixed flag. |

203 | @li relation included flag. |

204 | @li variable/relation list contents, including order. Also, the |

205 | variable/relation indices must continue to be consistent with |

206 | the list. |

207 | @li definition of relations, objective function, and boundaries: |

208 | including structural rearrangement on relations, although any |

209 | expression may be simplified. |

210 | |

211 | This function is considerably more efficient when it is usable. |

212 | |

213 | @return 0 on success |

214 | */ |

215 | |

216 | ASC_DLLSPEC int slv_iterate(slv_system_t sys); |

217 | /**< |

218 | Performs one iteration toward the ultimate solution (or |

219 | failure thereof) of the system. The user can obtain information |

220 | from the status and from the variables and relations themselves |

221 | (some care should be taken in examining the residuals of relations; |

222 | they may not be up to date). The user may not modify the system in |

223 | any way between iterations (i.e. you may look, but don't touch: see |

224 | slv_presolve()). See also slv_solve(). |

225 | |

226 | @return 0 on success |

227 | */ |

228 | |

229 | ASC_DLLSPEC int slv_solve(slv_system_t sys); |

230 | /**< |

231 | Attempts to solve the entire system in one shot (i.e. |

232 | performs as many iterations as needed or allowed). For some solvers, |

233 | slv_iterate() and slv_solve() may mean the same thing. |

234 | |

235 | @return 0 on success |

236 | */ |

237 | |

238 | |

239 | ASC_DLLSPEC int slv_eligible_solver(slv_system_t sys); |

240 | /**< |

241 | Determines whether or not the current solver is capable of solving the |

242 | given system as it is currently set up (e.g. some solvers cannot do |

243 | optimization, or inequalities, etc). |

244 | |

245 | The system must be set up first before calling this function, or the |

246 | return value may be misleading. @par |

247 | |

248 | The solver in question will be asked to pass judgement on the |

249 | data in the slv_system_t wrt the solver being useful. |

250 | If no solver is registered, this returns FALSE. |

251 | |

252 | @return 1 if solver is elegible |

253 | */ |

254 | |

255 | ASC_DLLSPEC int slv_select_solver(slv_system_t sys, int solver); |

256 | /**< |

257 | Sets the given solver to be the current solver |

258 | for the system. The intelligence or stupidity of this move is not |

259 | investigated. If the system has already has a solver selected and |

260 | it is not the same solver, the data structures of the old selection |

261 | will be blown away. |

262 | |

263 | @return number of solver actually selected or -1 on failure |

264 | */ |

265 | |

266 | ASC_DLLSPEC int slv_get_selected_solver(slv_system_t sys); |

267 | /**< |

268 | Returns the current solver number for a system. |

269 | */ |

270 | |

271 | ASC_DLLSPEC int slv_switch_solver(slv_system_t sys, int solver); |

272 | /**< |

273 | Sets the given solver to be the current solver for the system. |

274 | Return value is number of solver actually selected. |

275 | If failure, return is -1; |

276 | */ |

277 | |

278 | ASC_DLLSPEC int32 slv_get_default_parameters(int32 sindex, slv_parameters_t *parameters); |

279 | /**< @TODO needs commenting, KHACK */ |

280 | |

281 | ASC_DLLSPEC void slv_get_parameters(slv_system_t sys, slv_parameters_t *parameters); |

282 | /**< |

283 | Copies the current system parameters to the given structure. |

284 | |

285 | Do not confuse these parameters [algorithm control variables] |

286 | with the parameter list which is a list of pointers to var_variable. |

287 | */ |

288 | ASC_DLLSPEC void slv_set_parameters(slv_system_t sys, slv_parameters_t *parameters); |

289 | /**< |

290 | Sets the current system parameters to the values contained |

291 | in the given structure. It is recommended that one |

292 | gets the parameters first, before one modifies them and sets them, |

293 | especially if not all of the parameters are to be modified (and you |

294 | never know when that might suddenly become true because a new |

295 | parameter was added to the structure). Parameters will only be |

296 | accepted by an engine if they came from that engine, so fetching |

297 | before setting is not only a good idea, it's the law (gas engines |

298 | don't run on diesel very well...). @par |

299 | |

300 | Do not confuse these parameters [algorithm control variables] |

301 | with the parameter list which is a list of pointers to var_variable. |

302 | */ |

303 | |

304 | //------------------------------------------------------------------------------ |

305 | |

306 | ASC_DLLSPEC SlvClientToken slv_get_client_token(slv_system_t sys); |

307 | /**< |

308 | Returns the client token of the system_t. |

309 | */ |

310 | |

311 | ASC_DLLSPEC void slv_set_client_token(slv_system_t sys, SlvClientToken ct); |

312 | /**< |

313 | Sets the client token of the system_t. |

314 | @deprecated |

315 | */ |

316 | |

317 | ASC_DLLSPEC void slv_set_solver_index(slv_system_t sys, int sindex); |

318 | /**< |

319 | Sets the solver index of the slv_system_t. |

320 | @deprecated |

321 | */ |

322 | |

323 | ASC_DLLSPEC void slv_destroy_client(slv_system_t sys); |

324 | /**< |

325 | Destroy the client token of slv_system_t. It does not deallocate |

326 | the allocated data space of sys |

327 | */ |

328 | |

329 | ASC_DLLSPEC boolean slv_change_basis(slv_system_t,int32,mtx_range_t *); |

330 | /**< |

331 | Move var (given by index #) to the unassigned region (far right) |

332 | of the solver matrix if possible. returns FALSE if impossible |

333 | because structural infeasibility would occur or because solver selected |

334 | won't do it. |

335 | |

336 | @deprecated THIS CALL SHOULD GO AWAY |

337 | */ |

338 | |

339 | extern void slv_print_output(FILE *fp, slv_system_t sys); |

340 | /**< |

341 | Start of some report generation routines. For now just prints out |

342 | the variable values and residuals at the moment. |

343 | |

344 | @TODO make more general in the future. |

345 | */ |

346 | |

347 | ASC_DLLSPEC const char*slv_solver_name(int sindex); |

348 | /**< |

349 | @param index index of the solver in question (the index depends on the order in which the solvers have been registered) |

350 | @return name of the solver |

351 | |

352 | There may in general be more than one solver. The solvers will be |

353 | numbered [0..slv_number_of_solvers). Not all the solvers may |

354 | be present in a given installation of ASCEND as some are proprietary |

355 | (MINOS, for example). @par |

356 | |

357 | Solvers not yet registered will not have names. Each registered |

358 | client must have a unique name if user interfaces are to be happy, |

359 | though we suppose an interface could make a unique identifier out |

360 | of name-number pair. |

361 | */ |

362 | |

363 | #endif |

364 | |

365 | |

366 |

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

Powered by ViewVC 1.1.22 |