/[ascend]/trunk/ascend4/solver/slv_client.h
ViewVC logotype

Contents of /trunk/ascend4/solver/slv_client.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1 - (show annotations) (download) (as text)
Fri Oct 29 20:54:12 2004 UTC (17 years, 6 months ago) by aw0a
File MIME type: text/x-chdr
File size: 45432 byte(s)
Setting up web subdirectory in repository
1 /*
2 * SLV: Ascend Nonlinear Solver
3 * by Karl Michael Westerberg
4 * Created: 2/6/90
5 * Version: $Revision: 1.35 $
6 * Version control file: $RCSfile: slv_client.h,v $
7 * Date last modified: $Date: 1998/04/25 13:01:56 $
8 * Last modified by: $Author: ballan $
9 *
10 * This file is part of the SLV solver.
11 *
12 * Copyright (C) 1990 Karl Michael Westerberg
13 * Copyright (C) 1993 Joseph Zaher
14 * Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan
15 * Copyright (C) 1996 Benjamin Andrew Allan
16 *
17 * The SLV solver is free software; you can redistribute
18 * it and/or modify it under the terms of the GNU General Public License as
19 * published by the Free Software Foundation; either version 2 of the
20 * License, or (at your option) any later version.
21 *
22 * The SLV solver is distributed in hope that it will be
23 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
25 * General Public License for more details.
26 *
27 * You should have received a copy of the GNU General Public License
28 * along with the program; if not, write to the Free Software Foundation,
29 * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
30 * COPYING. COPYING is found in ../compiler.
31 */
32
33 /*
34 * SLV general interface for solver clients, etc.
35 * By Ben Allan
36 *
37 * Copyright(C) Karl Westerberg, Joseph Zaher, Benjamin Allan 1994
38 * Copyright(C) Benjamin Andrew Allan 1996
39 *
40 * ASCEND (the language) exists to separate, when desirable, the
41 * formulation of a mathematical problem (numeric) from the solution of
42 * the that problem. ASCEND (the interface) exists to give the user as
43 * much (or as little) control over the compilation and solution of their
44 * problem as they want.
45 *
46 * The problems expressible in the language cannot (and indeed should not)
47 * be reduced to a single formulation if the solutions are to be
48 * implemented in a robust, efficient, and user controllable manner.
49 * All but one of the solving engines attached to ASCEND must inevitably
50 * be hamstrung if we insist that they all fit in the same interface shoebox.
51 * Witness the minos/lsode implementations in the Pascal-version. The
52 * alternative is to make all engines talk through an interface defined
53 * by the intersection of the engines' individual interfaces. This
54 * alternative is unacceptable from a software engineering point of view.
55 *
56 * This portion of the interface, then, has the task of making every
57 * engine conform to a minimum set of semantics (thus enabling the GUI/
58 * CLUI to support the user wanting very little control over a host of
59 * powerful solving engines) while giving the power hungry user access
60 * to those parameters specific to a given engine.
61 * The minimum semantics chosen, due mostly to convenience and the biases
62 * of the developers, are those of slv0 with the provision of a set of
63 * arrays for the passing of auxillary, or 'sub', parameters to each
64 * solver.
65 * The data structures we desire to have common to all the solvers are
66 * kept in slv_common.h (or .c).
67 * The functions the UI are kept here.
68 */
69
70 /*
71 * Contents: Solver module
72 *
73 * Authors: Karl Westerberg
74 * Joseph Zaher
75 * Benjamin Allan
76 *
77 * Dates: 06/90 - original version
78 * 01/94 - modified tolerances, eliminated var_to_name
79 * and rel_to_name function pointers, and
80 * expanded status report
81 * 04/94 - expanded scope of slv0 to perform optimization
82 * 05/94 - added counting routines to count variables,
83 * boundaries, and relations which pass some
84 * specified filter
85 * 10/94 - added stubs for OPT and QRSlv
86 * 1/95 - moved status and parameters definitions to
87 * slv_common.h. BAA
88 * 02/96 - added stubs for NGSlv. KTH
89 * 06/96 - split into client and server headers.
90 * 0/97 - added stubs for CONOPT. KTH
91 * Description: The inputs to any solver consist of a formulation of
92 * the problem to solve along with a set of parameters to
93 * allow user control of the solution process. The
94 * general formulation is given below (for non-discrete
95 * problems only):
96 *
97 * min F(x,u,c)
98 *
99 * s.t. h(x,u,c) = 0
100 * r(x,u,c) = 0
101 * g(x,u,c) >= 0
102 * b(x,u,c) >= 0
103 *
104 * A variable list consists of fixed (c), independent (u),
105 * dependent variables (x), and unattached variables (q).
106 * A relation list consists of unconditional (or global)
107 * equality constraints (h), conditional equality
108 * constraints (r), and inequality constraints (g), each of
109 * type struct rel_relation *. The conditional equalities are
110 * isolated from the global equalities because they are only
111 * defined for certain ranges in values of the variables,
112 * expressed through a set of inequality boundary relations
113 * (b), each of type bnd_boundary_t which may or may not
114 * be satisfied at any given point. An objective function
115 * (F) is used to provide a criteria with which to
116 * optimize the values of the independent variables.
117 *
118 * The objective function is a relation (LHS only)
119 * struct rel_relation * and may be set (its default is NULL)
120 * using slv_set_obj_relation. The variable, boundary, and
121 * relation lists are pointer lists of
122 * struct var_variable * and struct rel_relation * and
123 * are expected to be NULL terminated. This means that for
124 * 10 variables to be placed in a list, for example, 11
125 * elements must exist in order to reserve the last pointer
126 * to be NULL. These lists ARE REQUIRED to be set.
127 *
128 * The additional set of inputs are the slv_parameters.
129 * These can specify stopping conditions or the amount of
130 * information displayed during solving, for example.
131 * Monitoring of the solution process is done using the
132 * status report for solvers that iterate.
133 * More details are given with the
134 * respective declarations below.
135 */
136
137 #ifndef slv_client_h__already_included
138 #define slv_client_h__already_included
139
140 /* requires #include "base.h" */
141 /* requires #include "instance_enum.h" */
142 /* requires #include "var.h" */
143 /* requires #include "rel.h" */
144 /* requires #include "discrete.h" */
145 /* requires #include "conditional.h" */
146 /* requires #include "logrel.h" */
147 /* requires #include "bnd.h" */
148 /* requires #include "linsol.h" */
149 /* requires #include "linsolqr.h" */
150 /* requires #include "slv_common.h" */
151 /* requires #include "slv_types.h" */
152
153 /*** ! ! We are going through a solver API definition restructuring.
154 ! ! The appearance of ! ! in the header means the code in question
155 ! ! has, or is about to have, a change in its meaning or is code that
156 ! ! is new and replaces some or all the functionality of an old
157 ! ! function definition. Basically, expect to have to read ! ! sections
158 ! ! carefully and maybe patch calls dependent on them.
159 **/
160 /***********************************************************************\
161 Right, so we're going to have a client-server, object-oriented,
162 open-architecture system designed to handle multiple clients in a
163 single-thread process. Furthermore, the clients will NOT have to
164 know anything at all about the ASCEND IV compiler hidden out back
165 some place -- in fact our compiler may not BE out back, it may be
166 on another machine or swapped to disk or whatever.
167
168 That's the ideal. In most applications of ASCEND, particularly the
169 interactive one, the compiler is never very far away. Isolating the
170 compiler data completely (meaning no looking back at it for anything)
171 would mean recreating all the relations (be they tokens, calls to
172 C code, or any kind) in a separate process. This is unacceptable from
173 a memory conservation point of view until RAM comes down to ~$1/MByte,
174 especially if ASCEND is to run on PCs any time soon.
175
176 What we really have then is a slv_system_t made up of variables and
177 relations and hiding all the compiler details from the clients.
178 Clients will operate directly on the slv_system_t only through real
179 C functions and not through macros so we can hide all the nasty
180 details about the compiler. Variables and relations only make
181 sense in the context of a slv_system_t, so the var_variable type
182 and the rel_relation type in this C code sometimes require that
183 the system pointer be provided when asking for certain properties
184 or services.
185
186 Q: What is a variable?
187 A: The question is ambiguous. In ASCEND we have the notion of a
188 solver_var ATOM type that includes bounding values, a scaling
189 value, and other properties. These are not the only real-number
190 based items that can occur, however. For purposes of the CLIENT
191 application programming interface (API) we collect all the real-
192 based objects we can find and map them all to struct var_variable.
193 See var.h for details. We sort them into lists as follows:
194 - vars. These are solver_var that are in an objective or relation.
195 - pars. These are solver_par appearing parametrically.
196 - unattached. These don't appear in relation or objective, and
197 they may be solver_var or solver_par or neither.
198 We keep 2 versions of each list: one for ourselves which is READ-
199 ONLY for clients and allows us to do many things efficiently, and
200 another for clients that clients may rearrange (or even delete)
201 as suits their needs. The former version is called a master list,
202 and the latter version is called a solvers list.
203
204 Q: What is a relation?
205 A: At present a relation in ASCEND is either an objective function
206 (a one-sided relation) or a constraining equation. We have a
207 variety of relation implementations within ASCEND, but all any
208 client needs to know about relations can be found in the rel.h
209 file. We keep master and client lists of relations as well.
210 We provide a variety of interesting services with relations:
211 residual and gradient calculations
212 symbolic inversion (where possible)
213 numeric root finding
214 scaling based on symbolic arguments
215 symbolic determination of linearity
216 and we expect to add others as they occur to us or you suggest
217 them.
218
219 Q: What else is a slv_system_t?
220 A: It's has a host of interesting properties.
221 1) One slv_system_t (system, hereafter) can only be used by one
222 ----------------- registered -------------
223 client at a time, but if your client is an unregistered manager
224 of several subclients (for example an NLP code and and MILP code)
225 then you can pass it back and forth to those registered clients to solve
226 an MINLP. (Note: we haven't done this ourselves yet.)
227 Any number of unregistered clients may share a system, but they
228 must take responsibility for not stepping on each other or the
229 registered client. Registration will be explained further below.
230 2) From any given ASCEND type definitions, the master lists in the
231 system will be ordered identically across all invocations of
232 ASCEND on any hardware that we are aware of. This property is
233 derived from the way we compile instances and create systems.
234 This is helpful in benchmarking and other applications.
235 3) We have a number of standard clients (registered and not)
236 you can use on a the system to precondition it in some way for
237 your client:
238 - Degrees of freedom analysis.
239 - Problem decomposition.
240 - Reordering of vars and rels for good factorization.
241 - Solution of square nonlinear systems.
242 - Generation of MPS code for popular MILP solvers.
243 - Generation of GAMS code for an old, slow compiler of an
244 extremely awkward modeling language that does happen to
245 have a lot of really good optimizers connected.
246
247
248 Future work:
249 Short term --
250 We expect to construct a client that takes the partitioned
251 problem and hands off the blocks in sequence to one or more
252 solvers designed to handle only 1 block.
253
254 Long term --
255 We anticipate that the structure laid out so far is capable of
256 expansion (probably by intermediate clients which add additional
257 semantic content) to provide standardized (mtx and harwellian)
258 sparse matrix support and memory management for codes that don't
259 care to think about such things directly.
260
261 \***********************************************************************/
262
263 typedef void *SlvClientToken;
264 /* A pointer that is meaningful to a registered client.
265 * Each call that requires a client response will include this
266 * token so that we can have multiple copies of a particular
267 * client simultaneously. Clients shouldn't have to use any
268 * global variables to save their state information -- they
269 * should put such info with their token.
270 */
271 /* NOTE TO present (6/96) developers: SlvClientToken is an alias for
272 * all the old slv*_system_t pointers. cast it to be the type you
273 * want.
274 */
275
276 struct slv_reorder_data {
277 int partition;
278 int basis_selection;
279 int block_reordering;
280 /* other parameters here. convert to enums. */
281 };
282
283 typedef struct dof_data_structure {
284 mtx_block_t blocks; /* block structure determined by analyze */
285 int32 structural_rank; /* length of output assignment */
286 int32 n_rows; /* total included equations */
287 int32 n_cols; /* total free and incident solver variables */
288 int32 n_fixed; /* total fixed solver variables */
289 int32 n_unincluded; /* total unincluded equations */
290 struct slv_reorder_data reorder;
291 } dof_t;
292
293 #define slv_number_of_solvers g_SlvNumberOfRegisteredClients
294 extern int g_SlvNumberOfRegisteredClients;
295
296 /* The number of solver's that have ever registered.
297 * Once a solver is registered, we keep track of its name,
298 * a number which is the order it was registered in, and
299 * the functions it defines.
300 */
301 #define SLVMAXCLIENTS 100
302 /*
303 * The maximum number of clients that ever can be registered.
304 * Limit is arbitrary. Note that not all clients of slv_system_t
305 * should register, just those that purport to be solve engines
306 * and the like.
307 */
308
309 /* type declarations for registered client functions */
310 /* We will explain all these later in this file someday soon. */
311 typedef SlvClientToken (SlvClientCreateF) (slv_system_t,int *);
312 typedef int (SlvClientDestroyF) (slv_system_t,SlvClientToken);
313 typedef int (SlvClientEligibleF) (slv_system_t);
314 typedef int32 (SlvGetDefParamsF) (slv_system_t,SlvClientToken,slv_parameters_t *);
315 typedef void (SlvGetParamsF) (slv_system_t, SlvClientToken, slv_parameters_t *);
316 typedef void (SlvSetParamsF) (slv_system_t, SlvClientToken, slv_parameters_t *);
317 typedef void (SlvGetStatusF) (slv_system_t, SlvClientToken, slv_status_t *);
318 typedef linsol_system_t (SlvGetLinsolF)(slv_system_t, SlvClientToken);
319 typedef linsolqr_system_t (SlvGetLinSysF)(slv_system_t, SlvClientToken);
320 typedef mtx_matrix_t (SlvGetSysMtxF)(slv_system_t, SlvClientToken);
321 typedef void (SlvDumpInfoF)(slv_system_t, SlvClientToken,int);
322 typedef void (SlvSolveF)(slv_system_t, SlvClientToken);
323
324 typedef struct slv_registration_data {
325 int number; /* we set number AFTER the client registration returns 0 */
326 /* client sets all the rest, starting with a symbolic name */
327 const char *name;
328 /* Required functions */
329 SlvClientCreateF *ccreate;
330 SlvClientDestroyF *cdestroy;
331 SlvClientEligibleF *celigible;
332 SlvGetDefParamsF *getdefparam;
333 SlvGetParamsF *getparam;
334 SlvSetParamsF *setparam;
335 SlvGetStatusF *getstatus;
336 SlvSolveF *solve;
337 /* Functions we really want, but can live without if your solver is old
338 * and klunky. Your solver may not 'look good' in an interactive environment,
339 * but then those nasty batch codes seldom do anyway.
340 * Redesign you're blinkin' batch code.
341 */
342 SlvSolveF *presolve;
343 SlvSolveF *iterate;
344 SlvSolveF *resolve;
345 /* Strictly Optional Functions */
346 SlvGetLinsolF *getlinsol;
347 SlvGetLinSysF *getlinsys;
348 SlvGetSysMtxF *getsysmtx;
349 SlvDumpInfoF *dumpinternals;
350 } SlvFunctionsT;
351
352
353 typedef int (SlvRegistration)(SlvFunctionsT *);
354 /**
355 *** status = YourRegistrationFunction(our_sft);
356 *** SlvFunctionsT *our_sft;
357 *** int status;
358 ***
359 *** We assume a nonzero return value means you don't register successfully.
360 *** Your function is probably part of an entire file that bridges
361 *** between our headers and your solve engine back end.
362 *** You must provide a function in your solver bridge which conforms with
363 *** the prototype above (SlvRegistration).
364 *** Your function should fill in all the required and as many of the
365 *** optional slots in the SlvFunctions pointer you are passed as it can.
366 *** (note: do not fill in number -- that is ours.)
367 *** If you register, but do not fill in a slot we will not accidently
368 *** call a bogus function. We will instead tell the user that an
369 *** incompetent solver was registered.
370 **/
371
372 extern int slv_register_client(SlvRegistration, char *, char *);
373 /**
374 *** Examples:
375 *** slv_register_client(slv0_register,NULL,NULL);
376 *** slv_register_client(NULL,"yourregisterfuncname","yourbinaryname");
377 ***
378 *** Call this function with the SlvRegistration function
379 *** from your solver or with 2 strings, but not both.
380 *** The 2 char strings will be used in dynamically loading
381 *** a solver.
382 ***
383 *** Returns 0 if registration succeeds, nonzero OTHERWISE.
384 ***
385 *** Note: the second syntax is NOT YET IMPLEMENTED.
386 **/
387
388 extern const char *slv_solver_name(int);
389 /**
390 *** There may in general be more than one solver. The solvers will be
391 *** numbered from 0 to slv_number_of_solvers-1. Not all the solvers may
392 *** be present in a given installation of ASCEND as some are proprietary
393 *** (MINOS, for example).
394 *** Solvers not yet registered will not have names. Each registered
395 *** client must have a unique name if user interfaces are to be happy,
396 *** though we suppose an interface could make a unique identifier out
397 *** of name-number pair.
398 **/
399
400 extern int Solv_C_CheckHalt_Flag;
401 extern int Solv_C_CheckHalt();
402 /**
403 *** Function to check for variable ascSolvStatVect(menubreak) ="1"
404 *** Returns 1 if true or if variable not found in global context,
405 *** else returns 0.
406 *** Solvers which do not have a real slv_iterate function should
407 *** use this in the functions that call on the ASCEND data structure
408 *** and should stop and restart their time clocks around the call.
409 ***
410 *** This is the present hack to deal with signals, particularly
411 *** SIGINT. It needs to be changed along with the front end
412 *** signal handling in the solver and scripting codes.
413 **/
414
415 extern unsigned int slv_serial_id(slv_system_t);
416 /**
417 *** id =slv_serial_id(sys);
418 *** slv_system_t sys;
419 *** unsigned id;
420 ***
421 *** Returns the id number of the slv_system_t. The id is unique
422 *** within the life of the program.
423 **/
424
425 extern dof_t *slv_get_dofdata(slv_system_t);
426 extern dof_t *slv_get_log_dofdata(slv_system_t);
427 /**
428 *** d=slv_get_dofdata(server);
429 *** d=slv_get_log_dofdata(server);
430 *** slv_system_t server;
431 *** dof_t *d;
432 *** Returns a pointer to the system's dof structure.
433 *** This structure can be for a logical solver or a nonlinear
434 *** solver.
435 *** Data in the structure should be consistent with
436 *** some interpretation of the solvers_var/rel lists.
437 *** The DEFAULT interpretation has not yet been established.
438 *** The pointer this returns cannot be freed.
439 *** If server is not NULL, d will not be NULL.
440 **/
441
442 extern const mtx_block_t *slv_get_solvers_blocks(slv_system_t);
443 extern const mtx_block_t *slv_get_solvers_log_blocks(slv_system_t);
444 /**
445 *** bl = slv_get_solvers_blocks(sys);
446 *** bl = slv_get_solvers_log_blocks(sys);
447 *** slv_system_t sys;
448 *** mtx_block_t *bl;
449 ***
450 *** Decomposition information for the nonlinear and logical solvers.
451 *** For the nonlinear case:
452 *** The blocks of bl contain decomposition information about the
453 *** Jacobian of the equations(included) and variables(free and
454 *** incident) if it is constructed in the ordering of relations/
455 *** variables in the solvers_rel/var_lists.
456 *** That is, we have done the subproblem partitioning already.
457 *** Each region may be solved as a separate subproblem in the
458 *** order given in the list.
459 *** We may have also done what we think is a good ordering
460 *** for row-wise lower-triangular linear factorization codes
461 *** within each of the blocks. We may have even arranged the
462 *** columns so that we believe we have made a 'good' set of
463 *** variables non-basic in the event that the last block is
464 *** rectangular.
465 ***
466 *** You are free to reorder any matrix you construct from
467 *** our equation gradients to suit any factorization method
468 *** you choose. We strongly recommend that you not do this.
469 ***
470 *** bl is a pointer to the struct with the number of blocks
471 *** and the data for the blocks. Each block but the last one
472 *** will be square and will contain a set of rows/columns that
473 *** should be solved simultaneously. The last block may be
474 *** rectangular. Rectangular last blocks will be wider.
475 ***
476 *** In the event that we have a structurally overspecified
477 *** problem, we will have excluded the redundant equations from
478 *** the region covered by the block list and partitioned those
479 *** equations remaining. If you are a solver client which solves
480 *** least squares problems, you should probably just ignore our
481 *** block structure completely.
482 ***
483 *** This will never return NULL unless sys is NULL, but if the
484 *** length of the block array is 0, then the region pointer will
485 *** be NULL.
486 **/
487
488 extern void slv_set_solvers_blocks(slv_system_t,int32,mtx_region_t *);
489 extern void slv_set_solvers_log_blocks(slv_system_t,int32,mtx_region_t *);
490 /**
491 *** slv_get_solvers_blocks(sys,len,data);
492 *** slv_get_solvers_log_blocks(sys,len,data);
493 *** slv_system_t sys;
494 *** int32 len;
495 *** mtx_region_t *data;
496 *** Set the block data for the solvers to the array given which
497 *** should be of length len. Solvers may be nonlinear or logical.
498 *** If the system in question already has a list of blocks,
499 *** it will be freed. This may have antisocial consequences
500 *** for registered clients if they have stored a copy of the pointer to the
501 *** old data. The should be told to reinitialize themselves.
502 **/
503
504 extern void slv_check_var_initialization(slv_system_t);
505 extern void slv_check_dvar_initialization(slv_system_t);
506 /**
507 *** slv_check_var_initialization(sys);
508 *** slv_check_dvar_initialization(sys);
509 *** slv_system_t sys;
510 ***
511 *** Checks that all the variables on the solvers_var_list have
512 *** been assigned at least once. If any has not, it is assigned
513 *** its scaling value (var_nominal) since this is generally a
514 *** much better starting value than 0.0.
515 *** Checks that all the boolean variables on the solvers_dvar_list have
516 *** been assigned at least once. If any has not, it is assigned
517 *** a value of TRUE.
518 **/
519
520 extern void slv_bnd_initialization(slv_system_t);
521 /**
522 *** slv_bnd_initialization(sys);
523 *** slv_system_t sys;
524 ***
525 *** Initialize the status of a boundary (satisfied ?)
526 *** At the initial point, it will be given the same value to
527 *** the current status and the previous status. Therefore, the bit
528 *** crossed (which can be modified during the iterative scheme)
529 *** is initialized to FALSE.
530 *** The evaluation of the status is performed with a call to the
531 *** function provided in bndman.
532 **/
533
534 extern void slv_set_solvers_var_list(slv_system_t, struct var_variable **,int);
535 extern void slv_set_solvers_par_list(slv_system_t, struct var_variable **,int);
536 extern void slv_set_solvers_unattached_list(slv_system_t,
537 struct var_variable **,int);
538 extern void slv_set_solvers_dvar_list(slv_system_t,struct dis_discrete **,int);
539 extern void slv_set_solvers_disunatt_list(slv_system_t,
540 struct dis_discrete **,int);
541 extern void slv_set_solvers_rel_list(slv_system_t, struct rel_relation **,int);
542 extern void slv_set_solvers_condrel_list(slv_system_t,
543 struct rel_relation **,int);
544 extern void slv_set_solvers_obj_list(slv_system_t, struct rel_relation **,int);
545 extern void slv_set_solvers_logrel_list(slv_system_t,
546 struct logrel_relation **,int);
547 extern void slv_set_solvers_condlogrel_list(slv_system_t,
548 struct logrel_relation **,int);
549 extern void slv_set_solvers_when_list(slv_system_t, struct w_when **,int);
550 extern void slv_set_solvers_bnd_list(slv_system_t, struct bnd_boundary **,int);
551 /**
552 ! ! slv_set_solvers_var_list(sys,vlist,size);
553 ! ! slv_set_solvers_par_list(sys,vlist);
554 ! ! slv_set_solvers_unattached_list(sys,vlist,size);
555 ! ! slv_set_solvers_dvar_list(sys,dvlist,size);
556 ! ! slv_set_solvers_disunatt_list(sys,dvlist,size);
557 ! ! slv_set_solvers_rel_list(sys,rlist,size);
558 ! ! slv_set_solvers_condrel_list(sys,clist,size);
559 ! ! slv_set_solvers_obj_list(sys,rlist,size);
560 ! ! slv_set_solvers_logrel_list(sys,lrlist,size);
561 ! ! slv_set_solvers_condlogrel_list(sys,lrlist,size);
562 ! ! slv_set_solvers_when_list(sys,wlist,size);
563 ! ! slv_set_solvers_bnd_list(sys,blist,size);
564 *** slv_system_t sys;
565 *** struct var_variable **vlist;
566 *** struct rel_relation **rlist;
567 *** struct logrel_relation **lrlist;
568 *** struct w_when **wlist;
569 *** struct bnd_boundary **blist;
570 *** int size;
571 ***
572 *** The list should be NULL terminated and the size should be the length
573 *** of the list EXCLUDING the terminal NULL.
574 *** Sets the system's pointer list to the list given. If the system already
575 *** has such a list, the old list will be freed unless the two lists are
576 *** in fact the same (in which case why are you calling this?).
577 *** Size is the length of the vlist (excluding the terminal NULL entry).
578 *** The sindex field of each var in the list should match it's list position.
579 ! !
580 ! ! There are now 2 var lists: the master var list pulled of the instance
581 ! ! tree, and the solvers var list is to be fetched by the solvers.
582 ! ! Eventually the solvers_varlist will only include those vars the specific
583 ! ! solver needs to know about.
584 ! ! For the moment, the content of the two lists is the same, but the ordering
585 ! ! is not. The master list is in the order collected. The solvers list
586 ! ! is reordered in some useful fashion defined elsewhere.
587 **/
588
589 extern struct var_variable **slv_get_solvers_var_list(slv_system_t);
590 extern struct var_variable **slv_get_solvers_par_list(slv_system_t);
591 extern struct var_variable **slv_get_solvers_unattached_list(slv_system_t);
592 extern struct dis_discrete **slv_get_solvers_dvar_list(slv_system_t);
593 extern struct dis_discrete **slv_get_solvers_disunatt_list(slv_system_t);
594 extern struct var_variable **slv_get_master_var_list(slv_system_t);
595 extern struct var_variable **slv_get_master_par_list(slv_system_t);
596 extern struct var_variable **slv_get_master_unattached_list(slv_system_t);
597 extern struct dis_discrete **slv_get_master_dvar_list(slv_system_t);
598 extern struct dis_discrete **slv_get_master_disunatt_list(slv_system_t);
599 /**
600 *** vlist = slv_get_*_*_list(sys)
601 *** slv_system_t sys;
602 *** struct var_variable **vlist;
603 *** int size;
604 ***
605 *** slv_get_*_*_list will return the most recently set variable list
606 *** (never NULL) for the convenience of those who need it.
607 ! !
608 ! ! There are now 2 var lists: the master var list pulled of the instance
609 ! ! tree, and the solvers var list isto be handed to the solvers.
610 ! ! Eventually the solvers_varlist will only include those vars the specific
611 ! ! solver needs to know about.
612 ! ! For the moment, the content of the two lists is the same, but the ordering
613 ! ! is not. The master list is in the order collected. The solvers list
614 ! ! is reordered in some useful fashion defined by a client.
615 ! ! Solver clients don't need to know about the master list. UI clients may.
616 ***
617 *** Parameters are problem invariant constants that the GUI
618 *** user might change before solving another problem using the
619 *** same MODEL.
620 **/
621
622 extern struct rel_relation **slv_get_solvers_rel_list(slv_system_t);
623 extern struct rel_relation **slv_get_solvers_condrel_list(slv_system_t);
624 extern struct rel_relation **slv_get_solvers_obj_list(slv_system_t);
625 extern struct logrel_relation **slv_get_solvers_logrel_list(slv_system_t);
626 extern struct logrel_relation **slv_get_solvers_condlogrel_list(slv_system_t);
627 extern struct w_when **slv_get_solvers_when_list(slv_system_t);
628 extern struct bnd_boundary **slv_get_solvers_bnd_list(slv_system_t);
629 extern struct rel_relation **slv_get_master_rel_list(slv_system_t);
630 extern struct rel_relation **slv_get_master_condrel_list(slv_system_t);
631 extern struct rel_relation **slv_get_master_obj_list(slv_system_t);
632 extern struct logrel_relation **slv_get_master_logrel_list(slv_system_t);
633 extern struct logrel_relation **slv_get_master_condlogrel_list(slv_system_t);
634 extern struct w_when **slv_get_master_when_list(slv_system_t);
635 extern struct bnd_boundary **slv_get_master_bnd_list(slv_system_t);
636 /***
637 *** Returns a list of relations, logical relations, boundaries,
638 *** objective relations and whens.
639 *** The list is NULL terminated.
640 *** Example: For relations and objective relations:
641 *** rlist = slv_get_solvers_rel_list(sys)
642 *** olist = slv_get_solvers_obj_list(sys);
643 *** rlist = slv_get_master_rel_list(sys)
644 *** rlist = slv_get_master_obj_list(sys)
645 *** slv_system_t sys;
646 *** struct rel_relation **rlist;
647 *** struct rel_relation **olist;
648 ***
649 **/
650
651 extern struct gl_list_t *slv_get_symbol_list(slv_system_t);
652 /*
653 * return the list of SymbolValues struct os a slv_sys
654 */
655
656 extern int32 slv_need_consistency(slv_system_t);
657 /*
658 * slv_need_consistency(sys);
659 * Gets the int need_consitency associated with the system.
660 */
661
662 extern int32 slv_get_num_solvers_vars(slv_system_t);
663 extern int32 slv_get_num_solvers_pars(slv_system_t);
664 extern int32 slv_get_num_solvers_unattached(slv_system_t);
665 extern int32 slv_get_num_solvers_dvars(slv_system_t);
666 extern int32 slv_get_num_solvers_disunatt(slv_system_t);
667 extern int32 slv_get_num_solvers_rels(slv_system_t);
668 extern int32 slv_get_num_solvers_condrels(slv_system_t);
669 extern int32 slv_get_num_solvers_objs(slv_system_t);
670 extern int32 slv_get_num_solvers_logrels(slv_system_t);
671 extern int32 slv_get_num_solvers_condlogrels(slv_system_t);
672 extern int32 slv_get_num_solvers_whens(slv_system_t);
673 extern int32 slv_get_num_solvers_bnds(slv_system_t);
674 extern int32 slv_get_num_master_vars(slv_system_t);
675 extern int32 slv_get_num_master_pars(slv_system_t);
676 extern int32 slv_get_num_master_unattached(slv_system_t);
677 extern int32 slv_get_num_master_dvars(slv_system_t);
678 extern int32 slv_get_num_master_disunatt(slv_system_t);
679 extern int32 slv_get_num_master_rels(slv_system_t);
680 extern int32 slv_get_num_master_condrels(slv_system_t);
681 extern int32 slv_get_num_master_objs(slv_system_t);
682 extern int32 slv_get_num_master_logrels(slv_system_t);
683 extern int32 slv_get_num_master_condlogrels(slv_system_t);
684 extern int32 slv_get_num_master_whens(slv_system_t);
685 extern int32 slv_get_num_master_bnds(slv_system_t);
686 /**
687 *** len = slv_get_num_*_*(sys);
688 *** slv_system_t sys;
689 *** int len;
690 ***
691 *** Returns the length of the corresponding pointer list.
692 *** The length does NOT include the terminating NULL.
693 ***
694 **/
695
696 extern int32 slv_get_num_models(slv_system_t);
697 /**
698 *** len = slv_get_num_models(sys);
699 *** slv_system_t sys;
700 *** int len;
701 ***
702 *** Returns the number of models found in the tree the
703 *** problem was constructed from. There is no corresponding list.
704 *** Rel_relations will know which of these models they came from.
705 **/
706
707 extern int32 slv_count_solvers_vars(slv_system_t,var_filter_t *);
708 extern int32 slv_count_solvers_pars(slv_system_t,var_filter_t *);
709 extern int32 slv_count_solvers_unattached(slv_system_t,var_filter_t *);
710 extern int32 slv_count_solvers_dvars(slv_system_t,dis_filter_t *);
711 extern int32 slv_count_solvers_disunatt(slv_system_t,dis_filter_t *);
712 extern int32 slv_count_solvers_rels(slv_system_t,rel_filter_t *);
713 extern int32 slv_count_solvers_condrels(slv_system_t,rel_filter_t *);
714 extern int32 slv_count_solvers_objs(slv_system_t,rel_filter_t *);
715 extern int32 slv_count_solvers_logrels(slv_system_t,logrel_filter_t *);
716 extern int32 slv_count_solvers_condlogrels(slv_system_t,logrel_filter_t *);
717 extern int32 slv_count_solvers_whens(slv_system_t,when_filter_t *);
718 extern int32 slv_count_solvers_bnds(slv_system_t,bnd_filter_t *);
719 extern int32 slv_count_master_vars(slv_system_t,var_filter_t *);
720 extern int32 slv_count_master_pars(slv_system_t,var_filter_t *);
721 extern int32 slv_count_master_unattached(slv_system_t,var_filter_t *);
722 extern int32 slv_count_master_dvars(slv_system_t,dis_filter_t *);
723 extern int32 slv_count_master_disunatt(slv_system_t,dis_filter_t *);
724 extern int32 slv_count_master_rels(slv_system_t,rel_filter_t *);
725 extern int32 slv_count_master_condrels(slv_system_t,rel_filter_t *);
726 extern int32 slv_count_master_objs(slv_system_t,rel_filter_t *);
727 extern int32 slv_count_master_logrels(slv_system_t,logrel_filter_t *);
728 extern int32 slv_count_master_condlogrels(slv_system_t,logrel_filter_t *);
729 extern int32 slv_count_master_whens(slv_system_t,when_filter_t *);
730 extern int32 slv_count_master_bnds(slv_system_t,bnd_filter_t *);
731 /**
732 *** count = slv_count_*_*(sys,vfilter)
733 *** count = slv_count_*_*rels(sys,rfilter)
734 *** slv_system_t sys;
735 *** var_filter_t *vfilter;
736 *** rel_filter_t *rfilter;
737 *** int count;
738 ***
739 *** Counts the variables, boundaries, relations or whens currently
740 *** in the system's solvers or master list which match the
741 *** specified filter.
742 ***
743 *** Efficiency note: if you are using this with a match anything
744 *** filter, you would be better off just calling the slv_get_num_*
745 *** function for the list in question.
746 **/
747
748 /**************************************************************************\
749 Registered client queries.
750 \**************************************************************************/
751 extern void slv_set_obj_relation(slv_system_t,struct rel_relation *);
752 extern struct rel_relation *slv_get_obj_relation(slv_system_t);
753 /**
754 *** slv_set_obj_relation(sys,obj)
755 *** obj = slv_get_obj_relation(sys)
756 *** slv_system_t sys;
757 *** struct rel_relation *obj;
758 ***
759 *** slv_set_obj_relation sets the objective relation of the solver to the
760 *** given one which should come from the objective list. A special value
761 *** of NULL for the objective function indicates no objective function.
762 ***
763 *** slv_get_obj_relation returns the internal copy of the objective
764 *** function, or NULL if none was specified.
765 ***
766 *** Client solvers should minimize the residual of this equation.
767 **/
768
769 extern void slv_set_obj_variable(slv_system_t, struct var_variable *,unsigned);
770 extern struct var_variable *slv_get_obj_variable(slv_system_t);
771 extern real64 slv_get_obj_variable_gradient(slv_system_t);
772 /**
773 *** slv_set_obj_variable(sys,objvar,maximize);
774 *** objvar = slv_get_obj_variable(sys);
775 *** objvar_grad = slv_get_obj_variable_gradient(sys);
776 *** slv_system_t sys;
777 *** struct var_variable *var;
778 *** unsigned int maximize;
779 *** real64 objvar_grad;
780 ***
781 *** By default, the objective var is NULL, even if there is
782 *** and objective relation (maximize,minimize) in the ASCEND MODEL.
783 *** (ascend MODEL objectives are handled with obj_relation functions)
784 *** Optimizers should use objective var in preference to the obj
785 *** relation if the var is defined.
786 ***
787 *** slv_set_obj_variable
788 *** specifies the var to use for an objective and whether it should
789 *** be maximized or minimized. Var must be from the slv_system or
790 *** complete insanity may result.
791 ***
792 *** slv_get_obj_variable
793 *** Returns the var used for an objective or NULL if none set.
794 ***
795 *** slv_get_obj_variable_gradient
796 *** Returns the unscaled gradient of the objective variable, or 0
797 *** if no var is set.
798 *** There is no value function here. just use var_value
799 ***
800 *** Client solvers should minimize this variable.
801 **/
802
803 extern int slv_eligible_solver(slv_system_t);
804 /**
805 *** eligible = slv_eligible_solver(sys)
806 *** int eligible;
807 *** slv_system_t sys;
808 ***
809 *** Determines whether or not the current solver.
810 *** is capable of solving the given system as it is currently set up
811 *** (e.g. some solvers cannot do optimization, or inequalities, etc.).
812 *** The system must be set up first before calling this function, or the
813 *** return value may be misleading.
814 *** The solver in question will be asked to pass judgement on the
815 *** data in the slv_system_t wrt the solver being useful.
816 *** If no solver is registered, this returns FALSE.
817 **/
818
819 extern int slv_select_solver(slv_system_t,int);
820 extern int slv_get_selected_solver(slv_system_t);
821 /**
822 *** solver=slv_select_solver(sys,solver)
823 *** solver = slv_get_selected_solver(sys)
824 *** slv_system_t sys;
825 *** int solver;
826 ***
827 *** slv_select_solver sets the given solver to be the current solver
828 *** for the system. The intelligence or stupidity of this move is not
829 *** investigated. If the system has already has a solver selected and
830 *** it is not the same solver, the data structures of the old selection
831 *** will be blown away.
832 *** Return value is number of solver actually selected.
833 *** If failure, return is -1;
834 ***
835 *** slv_get_selected_solver returns the current solver number.
836 **/
837
838 extern int slv_switch_solver(slv_system_t,int);
839 /**
840 *** solver=slv_switch_solver(sys,solver)
841 *** slv_system_t sys;
842 *** int solver;
843 ***
844 *** slv_switch_solver sets the given solver to be the current solver
845 *** for the system.
846 *** Return value is number of solver actually selected.
847 *** If failure, return is -1;
848 ***
849 **/
850
851 extern int32 slv_get_default_parameters(int32,slv_parameters_t *);
852 /* KHACK: NEED TO COMMENT */
853
854 extern void slv_get_parameters(slv_system_t,slv_parameters_t *);
855 extern void slv_set_parameters(slv_system_t,slv_parameters_t *);
856 /**
857 *** slv_get_parameters(sys,parameters)
858 *** slv_set_parameters(sys,parameters)
859 *** slv_system_t sys;
860 *** slv_parameters_t *parameters;
861 ***
862 *** (Do not confuse these parameters [algorithm control variables]
863 *** with the parameter list which is a list of pointers to var_variable.)
864 ***
865 *** slv_get_parameters will copy the current system parameters to the
866 *** given structure.
867 ***
868 *** slv_set_parameters will set the current system parameters to the
869 *** values contained in the given structure. It is recommended that one
870 *** gets the parameters first, before one modifies them and sets them,
871 *** especially if not all of the parameters are to be modified (and you
872 *** never know when that might suddenly become true because a new
873 *** parameter was added to the structure). Parameters will only be
874 *** accepted by an engine if they came from that engine, so fetching
875 *** before setting is not only a good idea, it's the law (gas engines
876 *** don't run on diesel very well...).
877 **/
878
879 extern SlvClientToken slv_get_client_token(slv_system_t);
880 extern void slv_set_client_token(slv_system_t,SlvClientToken);
881 /**
882 *** ct=slv_get_client_token(sys)
883 *** slv_system_t sys;
884 *** Return/sets the client token of the system_t
885 **/
886
887 extern void slv_set_solver_index(slv_system_t, int);
888 /**
889 *** slv_set_solver_index(sys)
890 *** slv_system_t sys;
891 *** Sets the solver index of the slv_system_t
892 **/
893
894 extern void slv_get_status(slv_system_t,slv_status_t *);
895 /**
896 *** slv_get_status(sys,status)
897 *** slv_system_t sys;
898 *** slv_status_t *status;
899 ***
900 *** Copies the current system status into the given structure.
901 **/
902
903 extern linsolqr_system_t slv_get_linsolqr_sys(slv_system_t);
904 /* THIS CALL SHOULD GO AWAY */
905 /**
906 *** lqrsys = slv_get_linsolqr_sys(sys)
907 *** linsolqr_system_t lqrsys;
908 *** slv_system_t sys;
909 ***
910 *** Returns the linsolqr system used, or NULL if none.
911 **/
912
913 extern linsol_system_t slv_get_linsol_sys(slv_system_t);
914 /* THIS CALL SHOULD GO AWAY */
915 /**
916 *** lsys = slv_get_linsol_sys(sys)
917 *** linsol_system_t lsys;
918 *** slv_system_t sys;
919 ***
920 *** Returns the linsol system used, or NULL if none.
921 **/
922
923 extern mtx_matrix_t slv_get_sys_mtx(slv_system_t);
924 /* THIS CALL SHOULD GO AWAY */
925 /**
926 *** mtx = slv_get_sys_mtx(sys)
927 *** mtx_matrix_t mtx;
928 *** slv_system_t sys;
929 ***
930 *** Returns the mtx used, or NULL if none. The user should check.
931 **/
932
933 extern void slv_dump_internals(slv_system_t,int);
934 /**
935 *** slv_dump_internals(sys,level)
936 *** slv_system_t sys;
937 *** int level;
938 ***
939 *** Will spew whatever the solver interface developer feels like to
940 *** stderr. Larger values of level will give more detailed information,
941 *** we hope. No specification is made with regard to what the
942 *** information will be. returns -1 if solver gutless. This is provided
943 *** principally to facilitate debugging a little.
944 **/
945
946 extern void slv_presolve(slv_system_t);
947 /**
948 *** slv_presolve(sys)
949 *** slv_system_t sys;
950 ***
951 *** Prepares the system for solving. This must be called before the
952 *** system is solved, but after everything about the system is set up
953 *** (i.e. variables and relations cannot be changed IN ANY WAY, objective
954 *** function cannot be modified, boundaries cannot be modified, or even
955 *** repermuted, and a new solver cannot be selected: some parameters may
956 *** be modified, they will be marked as such). The system essentially
957 *** becomes "read-only". If anything is modified after slv_presolve was
958 *** called, slv_presolve must be called again before solving (EXCEPTIONS:
959 *** slv_resolve may do for a certain restricted class of changes).
960 ***
961 *** It is at this point that the variable list is created if it does not
962 *** already exist and the newly created variables are indexed in the
963 *** order they end up. The relation list is indexed as well in the order
964 *** it is received.
965 ***
966 *** Among other things, this function will perform structural analysis
967 *** so that structural analysis flags in the status will be accurate.
968 **/
969
970 extern void slv_resolve(slv_system_t);
971 /**
972 *** slv_resolve(sys)
973 *** slv_system_t sys;
974 ***
975 *** This function re-prepares the system for solving. This function may
976 *** be used instead of slv_presolve, provided the system was partially
977 *** or completely solved before, and then the only changes to the system
978 *** since are as follows:
979 *** - any parameter except "partition".
980 *** - variable values.
981 *** - variable nominal values.
982 *** - variable bounds.
983 ***
984 *** In particular, the following changes are NOT allowed:
985 *** - variable fixed flag.
986 *** - relation included flag.
987 *** - variable/relation list contents, including order. Also, the
988 *** variable/relation indices must continue to be consistent with
989 *** the list.
990 *** - definition of relations, objective function, and boundaries:
991 *** including structural rearrangement on relations, although any
992 *** expression may be simplified.
993 ***
994 *** This function is considerably more efficient when it is usable.
995 **/
996
997 extern void slv_iterate(slv_system_t);
998 extern void slv_solve(slv_system_t);
999 /**
1000 *** slv_iterate(sys)
1001 *** slv_solve(sys)
1002 *** slv_system_t sys;
1003 ***
1004 *** slv_iterate performs one iteration toward the ultimate solution (or
1005 *** failure thereof) of the system. The user can obtain information
1006 *** from the status and from the variables and relations themselves
1007 *** (some care should be taken in examining the residuals of relations;
1008 *** they may not be up to date). The user may not modify the system in
1009 *** any way between iterations (i.e. you may look, but don't touch: see
1010 *** slv_presolve).
1011 ***
1012 *** slv_solve attempts to solve the entire system in one shot (i.e.
1013 *** performs as many iterations as needed or allowed). For some solvers,
1014 *** slv_iterate and slv_solve may mean the same thing.
1015 **/
1016
1017 extern void slv_destroy_client(slv_system_t);
1018 /**
1019 *** slv_destroy_client(sys)
1020 *** slv_system_t sys;
1021 *** Destroy the client token of slv_system_t. It does not deallocate
1022 *** the allocated data space of sys
1023 **/
1024
1025 extern boolean slv_change_basis(slv_system_t,int32,mtx_range_t *);
1026 /* THIS CALL SHOULD GO AWAY */
1027 /**
1028 *** slv_change_basis (sys,index,rng);
1029 *** slv_system_t sys;
1030 *** int32 index;
1031 *** mtx_range_t *rng;
1032 ***
1033 *** Move var (given by index #) to the unassigned region (far right)
1034 *** of the solver matrix if possible. returns FALSE if impossible
1035 *** because structural infeasibility would occur or because solver selected
1036 *** won't do it.
1037 **/
1038
1039 extern void slv_print_output(FILE *, slv_system_t);
1040
1041 /**
1042 *** start of some report generation routines. Just prints out
1043 *** the variable values and residuals at the moment. Will be
1044 *** made more general in the future.
1045 **/
1046
1047 #endif

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