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

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