/[ascend]/trunk/base/generic/solver/solver.h
ViewVC logotype

Contents of /trunk/base/generic/solver/solver.h

Parent Directory Parent Directory | Revision Log 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)
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