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

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