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

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