/[ascend]/trunk/ascend/system/slv_server.h
ViewVC logotype

Contents of /trunk/ascend/system/slv_server.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2377 - (show annotations) (download) (as text)
Thu Feb 3 06:11:59 2011 UTC (11 years, 5 months ago) by jpye
File MIME type: text/x-chdr
File size: 13252 byte(s)
Solver doxygen comments.
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) 1996 Benjamin Andrew Allan
6 Copyright (C) 2006 Carnegie Mellon University
7
8 This program is free software; you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation; either version 2, or (at your option)
11 any later version.
12
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
17
18 You should have received a copy of the GNU General Public License
19 along with this program; if not, write to the Free Software
20 Foundation, Inc., 59 Temple Place - Suite 330,
21 Boston, MA 02111-1307, USA.
22 *//**
23 @file
24 Server functions for the SLV solver.
25
26 Requires:
27
28 @NOTE
29 We are going through a solver API definition restructuring.
30 The appearance of a NOTE section in the header means the code in question
31 has, or is about to have, a change in its meaning or is code that
32 is new and replaces some or all the functionality of an old
33 function definition. Basically, expect to have to read NOTE sections
34 carefully and maybe patch calls dependent on them.
35 *//*
36 by Karl Michael Westerberg
37 Created: 2/6/90
38 */
39
40 #ifndef ASC_SLV_SERVER_H
41 #define ASC_SLV_SERVER_H
42
43 #include <ascend/utilities/config.h>
44
45 #include "var.h"
46 #include "rel.h"
47 #include "discrete.h"
48 #include "conditional.h"
49 #include "logrel.h"
50 #include "bnd.h"
51 #include "slv_common.h"
52 #include "slv_types.h"
53 #include "slv_client.h"
54
55 #include <ascend/linear/linsolqr.h>
56
57 #include <ascend/general/platform.h>
58
59 /** @addtogroup solver_server Solver Server
60 @{
61 */
62
63 extern slv_system_t slv_create(void);
64 /**<
65 Creates a system of the currently selected type in sys.
66 */
67
68 ASC_DLLSPEC int slv_destroy(slv_system_t sys);
69 /**<
70 Destroys all currently created systems in sys.
71
72 @param sys a system
73 @return 0 on success, or else the number of solvers with trouble destroying if there were problems.
74 */
75
76 extern SlvBackendToken slv_instance(slv_system_t sys);
77 /**<
78 Returns the root instance of the slv system.
79 @see slv_set_instance().
80 */
81
82 extern void slv_set_instance(slv_system_t sys, SlvBackendToken root);
83 /**<
84 Sets the root instance of the slv system.
85
86 All naming within the context of the slv_system_t is
87 done relative to this instance pointer.
88
89 NOTE: THESE TWO FUNCTIONS SHOULD TAKE A VOID * AND
90 THEN THE USER SHOULD CAST IT BACK TO WHATEVER IS
91 NEEDED GIVEN THE KNOWLEDGE OF THE BACK END IN QUESTION.
92 */
93
94 extern void slv_set_num_models(slv_system_t sys, int32 nmod);
95 /**<
96 Sets the number of models associated with a system.
97
98 @param sys a system
99 @param nmod number of models associated with the system
100 */
101
102 extern void slv_set_need_consistency(slv_system_t sys, int32 need_consistency);
103 /**<
104 Sets the int need_consistency associated with the system.
105 */
106
107 extern void slv_set_master_var_list(slv_system_t sys,
108 struct var_variable **vlist,
109 int size);
110 /**< Set the master variable list to vlist of length size. */
111
112 extern void slv_set_master_par_list(slv_system_t sys,
113 struct var_variable **vlist,
114 int size);
115 /**< Set the master parameter list to vlist of length size. */
116
117 extern void slv_set_master_unattached_list(slv_system_t sys,
118 struct var_variable **vlist,
119 int size);
120 /**< Set the master unattached variable list to vlist of length size. */
121
122 extern void slv_set_master_dvar_list(slv_system_t sys,
123 struct dis_discrete **dvlist,
124 int size);
125 /**< Set the master discrete variable list to dvlist of length size. */
126
127 extern void slv_set_master_disunatt_list(slv_system_t sys,
128 struct dis_discrete **dvlist,
129 int size);
130 /**< Set the master unattached discrete variable list to dvlist of length size. */
131
132 extern void slv_set_master_rel_list(slv_system_t sys,
133 struct rel_relation **rlist,
134 int size);
135 /**< Set the master relation list to rlist of length size. */
136
137 extern void slv_set_master_condrel_list(slv_system_t sys,
138 struct rel_relation **rlist,
139 int size);
140 /**< Set the master conditional relation list to rlist of length size. */
141
142 extern void slv_set_master_obj_list(slv_system_t sys,
143 struct rel_relation **rlist,
144 int size);
145 /**< Set the master objective relation list to rlist of length size. */
146
147 extern void slv_set_master_logrel_list(slv_system_t sys,
148 struct logrel_relation **lrlist,
149 int size);
150 /**< Set the master logical relation list to lrlist of length size. */
151
152 extern void slv_set_master_condlogrel_list(slv_system_t sys,
153 struct logrel_relation **lrlist,
154 int size);
155 /**< Set the master conditional logical relation list to lrlist of length size. */
156
157 extern void slv_set_master_when_list(slv_system_t sys,
158 struct w_when **wlist,
159 int size);
160 /**< Set the master when list to wlist of length size. */
161
162 extern void slv_set_master_bnd_list(slv_system_t sys,
163 struct bnd_boundary **wlist,
164 int size);
165 /**<
166 Set the master boundaries list to blist of length size.
167
168 @NOTE
169 There are now 2 lists: the master list pulled of the instance
170 tree, and the solvers list is to be handed to the solvers.
171 Eventually the solvers_list will only include those elements the specific
172 solver needs to know about.
173 For the moment,the content of the two lists is the same, but the ordering
174 is not. The master list is in the order collected. The solvers list
175 is reordered in some useful fashion defined elsewhere.
176 */
177
178 extern void slv_set_symbol_list(slv_system_t sys, struct gl_list_t *sv);
179 /**<
180 Set gllist of SymbolValues struct to sys.
181 They are used to assign an integer value to a symbol value
182 */
183
184 extern void slv_set_var_buf(slv_system_t sys, struct var_variable *vbuf);
185 /**<
186 Set the array variables of for the system.
187 See slv_set_bnd_buf() for more information.
188 */
189
190 extern void slv_set_par_buf(slv_system_t sys, struct var_variable *pbuf);
191 /**<
192 Set the array of parameters for the system.
193 See slv_set_bnd_buf() for more information.
194 */
195
196 extern void slv_set_unattached_buf(slv_system_t sys, struct var_variable *ubuf);
197 /**<
198 Set the array of unattached variables for the system.
199 See slv_set_bnd_buf() for more information.
200 */
201
202 extern void slv_set_dvar_buf(slv_system_t sys, struct dis_discrete *dbuf, int len);
203 /**<
204 Set the array of discrete variables for the system.
205 See slv_set_bnd_buf() for more information.
206 */
207
208 extern void slv_set_disunatt_buf(slv_system_t sys, struct dis_discrete *udbuf);
209 /**<
210 Set the array of unattached discrete variables for the system.
211 See slv_set_bnd_buf() for more information.
212 */
213
214 extern void slv_set_rel_buf(slv_system_t sys, struct rel_relation *rbuf);
215 /**<
216 Set the array of relations for the system.
217 See slv_set_bnd_buf() for more information.
218 */
219
220 extern void slv_set_condrel_buf(slv_system_t sys, struct rel_relation *cbuf);
221 /**<
222 Set the array of conditional relations for the system.
223 See slv_set_bnd_buf() for more information.
224 */
225
226 extern void slv_set_obj_buf(slv_system_t sys, struct rel_relation *obuf);
227 /**<
228 Set the array of objective relations for the system.
229 See slv_set_bnd_buf() for more information.
230 */
231
232 extern void slv_set_logrel_buf(slv_system_t sys, struct logrel_relation *lbuf);
233 /**<
234 Set the array of logical relations for the system.
235 See slv_set_bnd_buf() for more information.
236 */
237
238 extern void slv_set_condlogrel_buf(slv_system_t sys, struct logrel_relation *clbuf);
239 /**<
240 Set the array of conditional logical relations for the system.
241 See slv_set_bnd_buf() for more information.
242 */
243
244 extern void slv_set_when_buf(slv_system_t sys, struct w_when *wbuf, int len);
245 /**<
246 Set the array of whens for the system.
247 See slv_set_bnd_buf() for more information.
248 */
249
250 extern void slv_set_bnd_buf(slv_system_t sys, struct bnd_boundary *bbuf, int len);
251 /**<
252 Set the array of boundaries for the system.
253
254 slv_set_*_buf(sys,array);
255 You should give these functions a pointer to an array of
256 the var or rel structure. These arrays should contain the
257 memory pointed to by any and all pointers in the var/rel/when/bdn
258 lists associated with the slv_system_t. If you have none
259 of a particular type, its buf may be NULL.
260
261 There is no way to RETRIEVE these -- they are destroyed with
262 the slv_system_t. You should have no individually allocated
263 vars/rels in the system: these are the only ones we will free.
264
265 Calling any of these twice on the system is an extreme error.
266 */
267
268 extern void slv_set_incidence(slv_system_t sys,
269 struct var_variable **array,
270 long size);
271 /**<
272 Set the list of variables incident in a relation.
273
274 You should give this function a pointer to an array of
275 struct var_variable *. This array should contain the
276 memory pointed to by any and all pointers in rel incidence
277 lists associated with the slv_system_t.
278 There is no way to RETRIEVE these -- they are destroyed with
279 the slv_system_t. You should have no individually allocated
280 rel incidence in the system: this is the only one we will free.
281 Size is the length of the array, which we want for accounting.
282
283 Calling this function twice on the system is an extreme error.
284 */
285
286 extern void slv_set_var_incidence(slv_system_t sys,
287 struct rel_relation **array,
288 long size);
289 /**<
290 Set the list of logical relations in which a discrete variable is
291 incident. Calling this function twice on the system is an extreme error.
292 See slv_set_var_incidence() for more information.
293 */
294
295 extern void slv_set_logincidence(slv_system_t sys,
296 struct dis_discrete **array,
297 long size);
298 /**<
299 Set the list of relations in which a variable is incident.
300 Calling this function twice on the system is an extreme error.
301 See slv_set_var_incidence() for more information.
302 */
303
304 extern void slv_set_extrel_list(slv_system_t sys,
305 struct ExtRelCache **rlist,
306 int size);
307 /**<
308 The solver will merely reference the list, it will not make
309 its own private copy of the list, nor will it destroy the list
310 when the system is destroyed. This is a list of pointers to
311 struct ExtRelCache's. These external rel caches provide convenient
312 and quick access to information needed by external relations. All
313 external relations with the same node stamp will point to the same
314 ExtRelCache. The extrel list contains only unique ExtRelCaches though
315 the list is not sorted. Size is the number of such ExtRelCaches.
316 Calling slv_set_extrel_list twice on the same system is fatal.
317 */
318
319 extern struct ExtRelCache **slv_get_extrel_list(slv_system_t sys);
320 /**<
321 Returns the most recently set extrel list (or NULL if it is empty).
322 This is for the convenience of those who were not around when it
323 was initially set.
324 */
325
326 extern int slv_get_num_extrels(slv_system_t sys);
327 /**< Returns the size of the most recently set extrel list. */
328
329 ASC_DLLSPEC int32 slv_obj_select_list(slv_system_t sys, int32 **rip);
330 /**<
331 Allocates rip and fills it with solver objective list
332 positions of included objectives.
333 The rip list is terminated with a -1.
334 Returns number of objectives found.
335 The calling function must free rip.
336 */
337
338 ASC_DLLSPEC int32 slv_get_obj_num(slv_system_t sys);
339 /**<
340 Returns the solver list index of the current objective.
341 If the objective is NULL then -1 is returned.
342 */
343
344 ASC_DLLSPEC int32 slv_near_bounds(slv_system_t sys, real64 epsilon, int32 **rip);
345 /**<
346 Allocates rip and fills it with:
347 -# the number of vars close to lower bounds
348 -# the number of vars close to upper bounds
349 -# solver variable list positions of close to UB.
350 -# solver variable list positions of close to LB.
351 -# Returns number of variables close to bounds.
352
353 A variable is close to its bound if
354 abs(value - bound)/nominal < epsilon
355
356 @par The calling function must free rip.
357 */
358
359 ASC_DLLSPEC int32 slv_far_from_nominals(slv_system_t sys, real64 bignum, int32 **rip);
360 /**<
361 Allocates rip and fills it with
362 solver variable list positions of variables far
363 from nominal values.
364
365 Test used: abs(value - nominal)/nominal > bignum
366 <br><br>
367 The calling function must free rip.
368 */
369
370 int slv_set_diffvars(slv_system_t sys,void *diffvars);
371 /**< @return 0 on success */
372
373 /* @} */
374
375 #endif /* ASC_SLV_SERVER_H */
376

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22