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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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