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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 150 - (hide annotations) (download) (as text)
Thu Dec 22 09:24:56 2005 UTC (14 years, 3 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 jds 56 /*
2 johnpye 126 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 aw0a 1
9 johnpye 126 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 aw0a 1
14 johnpye 126 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 johnpye 67 #ifndef ASC_SLV_CLIENT_H
26     #define ASC_SLV_CLIENT_H
27 aw0a 1
28 johnpye 126 /** @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 aw0a 1 typedef void *SlvClientToken;
252 jds 54 /**<
253 johnpye 126 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 aw0a 1
264     struct slv_reorder_data {
265     int partition;
266     int basis_selection;
267     int block_reordering;
268 jds 54 /* other parameters here. convert to enums. */
269 aw0a 1 };
270    
271 jds 54 /** dof data structure */
272 aw0a 1 typedef struct dof_data_structure {
273 jds 54 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 aw0a 1 struct slv_reorder_data reorder;
280     } dof_t;
281 jds 54 /**< dof data type */
282 aw0a 1
283     #define slv_number_of_solvers g_SlvNumberOfRegisteredClients
284 jds 54 /**< Alias for the number of solver's that have ever registered. */
285    
286 aw0a 1 extern int g_SlvNumberOfRegisteredClients;
287 jds 54 /**<
288 johnpye 126 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 aw0a 1
294     #define SLVMAXCLIENTS 100
295 jds 54 /**<
296 johnpye 126 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 aw0a 1
302 johnpye 126 /*-----------------------------------------------------------------------
303     Type declarations for registered client functions
304     */
305    
306 jds 54 /** @todo We will explain all these later in this file someday soon. */
307 aw0a 1 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 jds 54 /** Registration information for a solver.
321 johnpye 126 @TODO Complete documentation of slv_registration_data members.
322     */
323 aw0a 1 typedef struct slv_registration_data {
324 johnpye 126 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 jds 54 const char *name; /**< symbolic name for solver (required). */
329 johnpye 126 /*
330     Required functions
331     */
332 jds 54 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 johnpye 126 /*
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 jds 54 SlvSolveF *presolve; /**< (desired) */
347     SlvSolveF *iterate; /**< (desired) */
348     SlvSolveF *resolve; /**< (desired) */
349 johnpye 126 /**
350     Strictly Optional Functions
351     */
352 jds 54 SlvGetLinsolF *getlinsol; /**< (optional) */
353     SlvGetLinSysF *getlinsys; /**< (optional) */
354     SlvGetSysMtxF *getsysmtx; /**< (optional) */
355     SlvDumpInfoF *dumpinternals; /**< (optional) */
356 aw0a 1 } SlvFunctionsT;
357    
358    
359 jds 54 typedef int (SlvRegistration)(SlvFunctionsT *our_sft);
360     /**<
361 johnpye 126 This defines the required form of a function to register a new solver.
362 aw0a 1
363 johnpye 126 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 ben.allan 147 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 johnpye 150 extern int slv_register_client(SlvRegistration slv0_register
389     ,CONST char *yourregisterfuncname
390     ,CONST char *yourbinaryname
391     ,int *new_client_id);
392 jds 54 /**<
393 johnpye 126 Examples: @code
394     slv_register_client(slv0_register,NULL,NULL);
395     slv_register_client(NULL,"yourregisterfuncname","yourbinaryname");
396     @endcode
397 aw0a 1
398 johnpye 126 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 jds 54 extern const char *slv_solver_name(int index);
409     /**<
410 johnpye 126 @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 aw0a 1
413 johnpye 126 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 aw0a 1 extern int Solv_C_CheckHalt_Flag;
425 jds 54 /**<
426 johnpye 126 Global variable used to communicate information between solvers and
427     an interface, whether a calculation should be halted or not.
428 jds 54
429 johnpye 126 @TODO Should Solc_C_CheckHalt_Flag be in the public interface?
430     */
431    
432 jds 54 extern int Solv_C_CheckHalt(void);
433 johnpye 126 /**< Function to check for variable ascSolvStatVect(menubreak) ="1"
434 aw0a 1
435 johnpye 126 @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 jds 54 extern unsigned int slv_serial_id(slv_system_t sys);
447 johnpye 126 /**< Return the system serial number.
448    
449     @return serial id number of given system.
450 aw0a 1
451 johnpye 126 The id is unique within the life of the program.
452     */
453    
454 jds 54 extern dof_t *slv_get_dofdata(slv_system_t server);
455     /**<
456 johnpye 126 @return pointer to the system's dof structure for a nonlinear solver.
457    
458     @see slv_get_log_dofdata().
459 jds 54 **/
460     extern dof_t *slv_get_log_dofdata(slv_system_t server);
461     /**<
462 johnpye 126 @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 jds 129
468 johnpye 126 @TODO The DEFAULT interpretation has not yet been established.
469     */
470 aw0a 1
471 jds 54 extern const mtx_block_t *slv_get_solvers_blocks(slv_system_t sys);
472 johnpye 126 /**< 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 jds 54 extern const mtx_block_t *slv_get_solvers_log_blocks(slv_system_t sys);
494 johnpye 126 /**< Decomposition information for the logical solver.
495 aw0a 1
496 johnpye 126 @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 jds 54 extern void slv_set_solvers_blocks(slv_system_t sys,
523     int32 len,
524     mtx_region_t *data);
525     /**<
526 johnpye 126 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 jds 54 extern void slv_set_solvers_log_blocks(slv_system_t sys,
532     int32 len,
533     mtx_region_t *data);
534     /**<
535 johnpye 126 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 aw0a 1
543 jds 54 extern void slv_check_var_initialization(slv_system_t sys);
544     /**<
545 johnpye 126 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 jds 54 extern void slv_check_dvar_initialization(slv_system_t sys);
551     /**<
552 johnpye 126 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 aw0a 1
557 jds 54 extern void slv_bnd_initialization(slv_system_t sys);
558     /**<
559 johnpye 126 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 aw0a 1
568 jds 54 extern void slv_set_solvers_var_list(slv_system_t sys,
569     struct var_variable **vlist,
570     int size);
571     /**<
572 johnpye 126 Sets the system's variable list to vlist.
573    
574     @see slv_set_solvers_bnd_list()
575 jds 54 **/
576     extern void slv_set_solvers_par_list(slv_system_t sys,
577     struct var_variable **vlist,
578     int size);
579     /**<
580 johnpye 126 Sets the system's parameters list to vlist.
581    
582     @see slv_set_solvers_bnd_list()
583     */
584 jds 54 extern void slv_set_solvers_unattached_list(slv_system_t sys,
585     struct var_variable **vlist,
586     int size);
587     /**<
588 johnpye 126 Sets the system's unattached variable list to vlist.
589    
590     @see slv_set_solvers_bnd_list()
591     */
592    
593 jds 54 extern void slv_set_solvers_dvar_list(slv_system_t sys,
594     struct dis_discrete **dvlist,
595     int size);
596     /**<
597 johnpye 126 Sets the system's discrete varialbe list to dvlist.
598    
599     @see slv_set_solvers_bnd_list()
600     */
601    
602 jds 54 extern void slv_set_solvers_disunatt_list(slv_system_t sys,
603     struct dis_discrete **dvlist,
604     int size);
605     /**<
606 johnpye 126 Sets the system's unattached discrete variable list to dvlist.
607    
608     @see slv_set_solvers_bnd_list()
609     */
610    
611 jds 54 extern void slv_set_solvers_rel_list(slv_system_t sys,
612     struct rel_relation **rlist,
613     int size);
614 johnpye 126 /**< Sets the system's relation list to rlist.
615    
616     @see slv_set_solvers_bnd_list()
617     */
618 jds 129
619 jds 54 extern void slv_set_solvers_condrel_list(slv_system_t sys,
620     struct rel_relation **clist,
621     int size);
622 johnpye 126 /**< Sets the system's conditional relation list to clist.
623     @see slv_set_solvers_bnd_list()
624     */
625    
626 jds 54 extern void slv_set_solvers_obj_list(slv_system_t sys,
627     struct rel_relation **rlist,
628     int size);
629 johnpye 126 /**< Sets the system's objective relation list to rlist.
630     @see slv_set_solvers_bnd_list()
631     */
632    
633 jds 54 extern void slv_set_solvers_logrel_list(slv_system_t sys,
634     struct logrel_relation **lrlist,
635     int size);
636 johnpye 126 /**< Sets the system's logical relation list to lrlist.
637     @see slv_set_solvers_bnd_list()
638     */
639    
640 jds 54 extern void slv_set_solvers_condlogrel_list(slv_system_t sys,
641     struct logrel_relation **lrlist,
642     int size);
643 johnpye 126 /**< Sets the system's conditional relation list to lrlist.
644     @see slv_set_solvers_bnd_list()
645     */
646    
647 jds 54 extern void slv_set_solvers_when_list(slv_system_t sys,
648     struct w_when **wlist,
649     int size);
650 johnpye 126 /**< Sets the system's when list to wlist.
651     @see slv_set_solvers_bnd_list()
652     */
653    
654 jds 54 extern void slv_set_solvers_bnd_list(slv_system_t sys,
655     struct bnd_boundary **blist,
656     int size);
657     /**<
658 johnpye 126 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 aw0a 1
664 johnpye 126 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 jds 54 extern struct var_variable **slv_get_solvers_var_list(slv_system_t sys);
678 johnpye 126 /**< Returns the most recently set variable list (never NULL) from the system.
679     @see slv_get_master_disunatt_list()
680     */
681    
682 jds 54 extern struct var_variable **slv_get_solvers_par_list(slv_system_t sys);
683 johnpye 126 /**< Returns the most recently set par list (never NULL) from the system.
684     @see slv_get_master_disunatt_list()
685     */
686 jds 54 extern struct var_variable **slv_get_solvers_unattached_list(slv_system_t sys);
687 johnpye 126 /**< Returns the most recently set unattached variable list (never NULL) from the system.
688     @see slv_get_master_disunatt_list()
689     */
690    
691 jds 54 extern struct dis_discrete **slv_get_solvers_dvar_list(slv_system_t sys);
692 johnpye 126 /**< Returns the most recently set discrete variable list (never NULL) from the system.
693     @see slv_get_master_disunatt_list()
694     */
695 jds 54 extern struct dis_discrete **slv_get_solvers_disunatt_list(slv_system_t sys);
696 johnpye 126 /**< Returns the most recently set unattached discrete variable list (never NULL) from the system.
697     @see slv_get_master_disunatt_list()
698     */
699 jds 54 extern struct var_variable **slv_get_master_var_list(slv_system_t sys);
700 johnpye 126 /**< Returns the most recently set master variable list (never NULL) from the system.
701     @see slv_get_master_disunatt_list()
702     */
703 jds 54 extern struct var_variable **slv_get_master_par_list(slv_system_t sys);
704 johnpye 126 /**< Returns the most recently set master par list (never NULL) from the system.
705     @see slv_get_master_disunatt_list()
706     */
707 jds 54 extern struct var_variable **slv_get_master_unattached_list(slv_system_t sys);
708 johnpye 126 /**< Returns the most recently set master unattached variable list (never NULL) from the system.
709     @see slv_get_master_disunatt_list()
710     */
711 jds 54 extern struct dis_discrete **slv_get_master_dvar_list(slv_system_t sys);
712 johnpye 126 /**< Returns the most recently set master discrete variable list (never NULL) from the system.
713     @see slv_get_master_disunatt_list()
714     */
715 jds 54 extern struct dis_discrete **slv_get_master_disunatt_list(slv_system_t sys);
716 johnpye 126 /** Returns the most recently set master unattached discrete variable list
717     (never NULL) for the convenience of those who need it.<br><br>
718 aw0a 1
719 johnpye 126 @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 jds 54 extern struct rel_relation **slv_get_solvers_rel_list(slv_system_t sys);
735     /**< Returns the (NULL-terminated) list of solver relations. */
736 johnpye 126
737 jds 54 extern struct rel_relation **slv_get_solvers_condrel_list(slv_system_t sys);
738     /**< Returns the (NULL-terminated) list of solver conditional relations. */
739 johnpye 126
740 jds 54 extern struct rel_relation **slv_get_solvers_obj_list(slv_system_t sys);
741     /**< Returns the (NULL-terminated) list of solver objective relations. */
742 johnpye 126
743 jds 54 extern struct logrel_relation **slv_get_solvers_logrel_list(slv_system_t sys);
744     /**< Returns the (NULL-terminated) list of solver logical relations. */
745 johnpye 126
746 jds 54 extern struct logrel_relation **slv_get_solvers_condlogrel_list(slv_system_t sys);
747     /**< Returns the (NULL-terminated) list of solver conditional relations. */
748 johnpye 126
749 jds 54 extern struct w_when **slv_get_solvers_when_list(slv_system_t sys);
750     /**< Returns the (NULL-terminated) list of solver whens. */
751 johnpye 126
752 jds 54 extern struct bnd_boundary **slv_get_solvers_bnd_list(slv_system_t sys);
753     /**< Returns the (NULL-terminated) list of solver boundaries. */
754 johnpye 126
755 jds 54 extern struct rel_relation **slv_get_master_rel_list(slv_system_t sys);
756     /**< Returns the (NULL-terminated) list of master relations. */
757 johnpye 126
758 jds 54 extern struct rel_relation **slv_get_master_condrel_list(slv_system_t sys);
759     /**< Returns the (NULL-terminated) list of master conditional relations. */
760 johnpye 126
761 jds 54 extern struct rel_relation **slv_get_master_obj_list(slv_system_t sys);
762     /**< Returns the (NULL-terminated) list of master objective relations. */
763 johnpye 126
764 jds 54 extern struct logrel_relation **slv_get_master_logrel_list(slv_system_t sys);
765     /**< Returns the (NULL-terminated) list of master logical relations. */
766 johnpye 126
767 jds 54 extern struct logrel_relation **slv_get_master_condlogrel_list(slv_system_t sys);
768     /**< Returns the (NULL-terminated) list of master conditional relations. */
769 johnpye 126
770 jds 54 extern struct w_when **slv_get_master_when_list(slv_system_t sys);
771     /**< Returns the (NULL-terminated) list of master whens. */
772 johnpye 126
773 jds 54 extern struct bnd_boundary **slv_get_master_bnd_list(slv_system_t sys);
774     /**< Returns the (NULL-terminated) list of master boundaries. */
775 aw0a 1
776 jds 54 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 aw0a 1
779 jds 54 extern int32 slv_need_consistency(slv_system_t sys);
780 johnpye 126 /**< Gets the int need_consitency associated with the system. */
781 aw0a 1
782 jds 54 extern int32 slv_get_num_solvers_vars(slv_system_t sys);
783 johnpye 126 /**< Returns the length of the solver variable list.
784     The length does NOT include the terminating NULL.
785     */
786    
787 jds 54 extern int32 slv_get_num_solvers_pars(slv_system_t sys);
788 johnpye 126 /**< Returns the length of the solver parameters list.
789     The length does NOT include the terminating NULL.
790     */
791    
792 jds 54 extern int32 slv_get_num_solvers_unattached(slv_system_t sys);
793 johnpye 126 /**< Returns the length of the solver unsattached variable list.
794     The length does NOT include the terminating NULL.
795     */
796    
797 jds 54 extern int32 slv_get_num_solvers_dvars(slv_system_t sys);
798 johnpye 126 /**< Returns the length of the solver discrete variables list.
799     The length does NOT include the terminating NULL.
800     */
801    
802 jds 54 extern int32 slv_get_num_solvers_disunatt(slv_system_t sys);
803 johnpye 126 /**< Returns the length of the solver unattached discrete variables list.
804     The length does NOT include the terminating NULL.
805     */
806    
807 jds 54 extern int32 slv_get_num_solvers_rels(slv_system_t sys);
808 johnpye 126 /**< Returns the length of the solver relations list.
809     The length does NOT include the terminating NULL.
810     */
811    
812 jds 54 extern int32 slv_get_num_solvers_condrels(slv_system_t sys);
813 johnpye 126 /**< Returns the length of the solver conditional relations list.
814     The length does NOT include the terminating NULL.
815     */
816    
817 jds 54 extern int32 slv_get_num_solvers_objs(slv_system_t sys);
818 johnpye 126 /**< Returns the length of the solver objective relations list.
819     The length does NOT include the terminating NULL.
820     */
821    
822 jds 54 extern int32 slv_get_num_solvers_logrels(slv_system_t sys);
823 johnpye 126 /**< Returns the length of the solver logical relations list.
824     The length does NOT include the terminating NULL.
825     */
826    
827 jds 54 extern int32 slv_get_num_solvers_condlogrels(slv_system_t sys);
828 johnpye 126 /**< Returns the length of the solver conditional relations list.
829     The length does NOT include the terminating NULL.
830     */
831    
832 jds 54 extern int32 slv_get_num_solvers_whens(slv_system_t sys);
833 johnpye 126 /**< Returns the length of the solver whens list.
834     The length does NOT include the terminating NULL.
835     */
836    
837 jds 54 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 johnpye 126 /**< Returns the length of the master parameters list.
849     The length does NOT include the terminating NULL.
850     */
851    
852 jds 54 extern int32 slv_get_num_master_unattached(slv_system_t sys);
853 johnpye 126 /**< Returns the length of the master unattached variables list.
854     The length does NOT include the terminating NULL.
855     */
856    
857 jds 54 extern int32 slv_get_num_master_dvars(slv_system_t sys);
858 johnpye 126 /**< Returns the length of the master discrete variables list.
859     The length does NOT include the terminating NULL.
860     */
861    
862 jds 54 extern int32 slv_get_num_master_disunatt(slv_system_t sys);
863 johnpye 126 /**< Returns the length of the master unattached discrete variables list.
864     The length does NOT include the terminating NULL.
865     */
866    
867 jds 54 extern int32 slv_get_num_master_rels(slv_system_t sys);
868 johnpye 126 /**< Returns the length of the master relations list.
869     The length does NOT include the terminating NULL.
870     */
871    
872 jds 54 extern int32 slv_get_num_master_condrels(slv_system_t sys);
873 johnpye 126 /**< Returns the length of the master conditional relations list.
874     The length does NOT include the terminating NULL.
875     */
876    
877 jds 54 extern int32 slv_get_num_master_objs(slv_system_t sys);
878 johnpye 126 /**< Returns the length of the master objective relations list.
879     The length does NOT include the terminating NULL.
880     */
881    
882 jds 54 extern int32 slv_get_num_master_logrels(slv_system_t sys);
883 johnpye 126 /**< Returns the length of the master logical relations list.
884     The length does NOT include the terminating NULL.
885     */
886    
887 jds 54 extern int32 slv_get_num_master_condlogrels(slv_system_t sys);
888 johnpye 126 /**< Returns the length of the master conditional relations list.
889     The length does NOT include the terminating NULL.
890     */
891    
892 jds 54 extern int32 slv_get_num_master_whens(slv_system_t sys);
893 johnpye 126 /**< Returns the length of the master whens list.
894     The length does NOT include the terminating NULL.
895     */
896    
897 jds 54 extern int32 slv_get_num_master_bnds(slv_system_t sys);
898 johnpye 126 /**< Returns the length of the master boundaries list.
899     The length does NOT include the terminating NULL.
900     */
901 aw0a 1
902 jds 54 extern int32 slv_get_num_models(slv_system_t sys);
903 johnpye 126 /**< 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 aw0a 1
908 jds 54 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 johnpye 126
911 jds 54 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 johnpye 126
914 jds 54 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 johnpye 126
917 jds 54 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 johnpye 126
920 jds 54 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 johnpye 126
923 jds 54 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 johnpye 126
926 jds 54 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 johnpye 126
929 jds 54 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 johnpye 126
932 jds 54 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 johnpye 126
935 jds 54 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 johnpye 126
938 jds 54 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 johnpye 126
941 jds 54 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 johnpye 126
944 jds 54 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 johnpye 126
947 jds 54 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 johnpye 126
950 jds 54 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 johnpye 126
953 jds 54 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 johnpye 126
956 jds 54 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 johnpye 126
959 jds 54 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 johnpye 126
962 jds 54 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 johnpye 126
965 jds 54 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 johnpye 126
968 jds 54 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 johnpye 126
971 jds 54 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 johnpye 126
974 jds 54 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 johnpye 126
977 jds 54 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 aw0a 1
980 johnpye 126 /** @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 jds 54 extern void slv_set_obj_relation(slv_system_t sys, struct rel_relation *obj);
993     /**<
994 johnpye 126 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 jds 54 extern struct rel_relation *slv_get_obj_relation(slv_system_t sys);
1001     /**<
1002 johnpye 126 @return the internal copy of the objective function, or
1003     NULL if none was specified.<br><br>
1004 aw0a 1
1005 johnpye 126 Client solvers should minimize the residual of this equation.
1006     */
1007    
1008 jds 54 extern void slv_set_obj_variable(slv_system_t sys,
1009     struct var_variable *objvar,
1010     unsigned maximize);
1011     /**<
1012 johnpye 126 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 jds 54 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 johnpye 126
1029 jds 54 extern real64 slv_get_obj_variable_gradient(slv_system_t sys);
1030     /**<
1031 johnpye 126 Returns the unscaled gradient of the objective variable, or 0
1032     if no var is set.
1033     */
1034 aw0a 1
1035 jds 54 extern int slv_eligible_solver(slv_system_t sys);
1036     /**<
1037 johnpye 126 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 aw0a 1
1043 johnpye 126 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 jds 54 extern int slv_select_solver(slv_system_t sys, int solver);
1049     /**<
1050 johnpye 126 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 jds 54 extern int slv_get_selected_solver(slv_system_t sys);
1060     /**<
1061 johnpye 126 Returns the current solver number for a system.
1062     */
1063 aw0a 1
1064 jds 54 extern int slv_switch_solver(slv_system_t sys, int solver);
1065     /**<
1066 johnpye 126 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 aw0a 1
1071 jds 54 extern int32 slv_get_default_parameters(int32 index, slv_parameters_t *parameters);
1072 johnpye 126 /**< @TODO needs commenting, KHACK */
1073 aw0a 1
1074 jds 54 extern void slv_get_parameters(slv_system_t sys, slv_parameters_t *parameters);
1075     /**<
1076 johnpye 126 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 jds 54 extern void slv_set_parameters(slv_system_t sys, slv_parameters_t *parameters);
1082     /**<
1083 johnpye 126 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 aw0a 1
1097 jds 54 extern SlvClientToken slv_get_client_token(slv_system_t sys);
1098     /**< Returns the client token of the system_t. */
1099 johnpye 126
1100 jds 54 extern void slv_set_client_token(slv_system_t sys, SlvClientToken ct);
1101     /**<
1102 johnpye 126 Sets the client token of the system_t.
1103     */
1104 aw0a 1
1105 jds 54 extern void slv_set_solver_index(slv_system_t sys, int index);
1106     /**<
1107 johnpye 126 Sets the solver index of the slv_system_t.
1108     */
1109 aw0a 1
1110 jds 54 extern void slv_get_status(slv_system_t sys, slv_status_t *status);
1111     /**<
1112 johnpye 126 Copies the current system status into the given structure.
1113     */
1114 aw0a 1
1115 jds 54 extern linsolqr_system_t slv_get_linsolqr_sys(slv_system_t sys);
1116     /**<
1117 johnpye 126 Returns the linsolqr system used, or NULL if none.
1118     @deprecated { THIS CALL SHOULD GO AWAY }
1119     */
1120 aw0a 1
1121 jds 54 extern linsol_system_t slv_get_linsol_sys(slv_system_t sys);
1122     /**<
1123 johnpye 126 Returns the linsol system used, or NULL if none.
1124     @deprecated { THIS CALL SHOULD GO AWAY }
1125     */
1126 aw0a 1
1127 jds 54 extern mtx_matrix_t slv_get_sys_mtx(slv_system_t sys);
1128     /**<
1129 johnpye 126 Returns the mtx used, or NULL if none. The user should check.
1130    
1131     @deprecated {THIS CALL SHOULD GO AWAY}
1132 aw0a 1 **/
1133    
1134 jds 54 extern void slv_dump_internals(slv_system_t sys, int level);
1135     /**<
1136 johnpye 126 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 aw0a 1
1142 johnpye 126 @TODO fix dubious documentation (return type is void...)
1143     */
1144    
1145 jds 54 extern void slv_presolve(slv_system_t sys);
1146     /**<
1147 johnpye 126 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 aw0a 1
1157 johnpye 126 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 jds 54 extern void slv_resolve(slv_system_t sys);
1167     /**<
1168 johnpye 126 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 aw0a 1
1173 johnpye 126 @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 jds 54 extern void slv_iterate(slv_system_t sys);
1193     /**<
1194 johnpye 126 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 jds 54 extern void slv_solve(slv_system_t sys);
1204     /**<
1205 johnpye 126 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 aw0a 1
1210 jds 54 extern void slv_destroy_client(slv_system_t sys);
1211     /**<
1212 johnpye 126 Destroy the client token of slv_system_t. It does not deallocate
1213     the allocated data space of sys
1214     */
1215 aw0a 1
1216     extern boolean slv_change_basis(slv_system_t,int32,mtx_range_t *);
1217 jds 54 /**<
1218 johnpye 126 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 aw0a 1
1226 jds 54 extern void slv_print_output(FILE *fp, slv_system_t sys);
1227     /**<
1228 johnpye 126 Start of some report generation routines. For now just prints out
1229     the variable values and residuals at the moment.
1230 aw0a 1
1231 johnpye 126 @TODO make more general in the future.
1232     */
1233    
1234 johnpye 67 #endif /* ASC_SLV_CLIENT_H */
1235 jds 54

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