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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 592 - (hide annotations) (download) (as text)
Fri May 12 09:50:57 2006 UTC (14 years, 10 months ago) by johnpye
File MIME type: text/x-chdr
File size: 55354 byte(s)
Working on adding some more export symbols, for purpose of getting Jerry's test suite to work with SCons build.
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 485 Copyright (C) 2005-2006 Carnegie Mellon University
7 aw0a 1
8 johnpye 485 This program is free software; you can redistribute it and/or modify
9     it under the terms of the GNU General Public License as published by
10     the Free Software Foundation; either version 2, or (at your option)
11     any later version.
12 johnpye 126
13 johnpye 485 This program is distributed in the hope that it will be useful,
14     but WITHOUT ANY WARRANTY; without even the implied warranty of
15     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16     GNU General Public License for more details.
17 johnpye 126
18 johnpye 485 You should have received a copy of the GNU General Public License
19     along with this program; if not, write to the Free Software
20     Foundation, Inc., 59 Temple Place - Suite 330,
21     Boston, MA 02111-1307, USA.
22     *//**
23     @file
24 johnpye 222 General C utility routines for slv/Slv class interfaces. Abstracted from
25 johnpye 485 slvX.c January 1995. Based on the original slv.h by KW and JZ (01/94), by Ben Allan.
26 johnpye 222
27     slv.h is the header for folks on the ASCEND end, and this is the one for
28     folks on the Slv math end.
29     Don't protoize this file for ASCEND types other than mtx, vec, and boolean
30     real64, and int32 or we'll have you shot. In particular, not var and rel.
31     People who aren't supposed to know about var and rel include this.
32    
33     In particular, this header may be used without knowing about the ASCEND
34     compiler or any of its annoying insanities so long as you drag out
35     ascmalloc().
36     This does commit you to being able to stomach the mtx.h file, however,
37     even if you choose to ignore the contents of mtx.
38     Several functions, notably the print suite for rel/var names,
39     assume you are linking against something that does know about
40     ASCEND instances unless the SLV_INSTANCES flag is set to FALSE.
41    
42     The parameters and status struct definitions have been moved here,
43     being of general interest.
44    
45     SLV common utilities & structures for ASCEND solvers.
46     This includes the following:
47     - parameters struct definitions & manipulation routines
48     - status struct definitions & retrieval routines
49     - vector operations
50     - solver print routines
51     - lnkmap support functions
52 johnpye 480
53 johnpye 485 Requires:
54     #include <stdio.h>
55     #include <utilities/ascConfig.h>
56     #include <solver/slv_types.h>
57     #include <solver/rel.h>
58     #include <solver/logrel.h>
59     #include <solver/mtx.h>
60     #include <general/list.h>
61 johnpye 480
62 johnpye 222 Details on solver parameter definition:
63    
64 johnpye 480 When used together the parameter-related structures, functions, and
65 johnpye 222 macros allow us to define all of a solver's parameters in one file
66     and notify the interface of these parameters upon startup (dynamic
67     interface construction). The parameters can be defined in any order.
68     The only bookkeeping needed is associated with the macros. You must
69     have an array of void pointers large enough for all of the macros
70     you define and you must give each of the macros you define a unique
71     element of this array. Here is an example using a real parameter
72     and a character parameter. (The int and bool are similar to the real).
73    
74     @code
75    
76     (* these 4 macros can be defined anywhere more or less so long as it
77     is before the calls to slv_define_parm. *)
78     #define REAL_PTR (sys->parm_array[0])
79     #define REAL ((*(real64 *)REAL_PTR))
80     #define CHAR_PTR (sys->parm_array[1])
81     #define CHAR ((*(char **)CHAR_PTR))
82    
83     #define PA_SIZE 2
84     struct example {
85     struct slv_parameters_t p;
86     void *parm_array[PA_SIZE];
87     struct slv_parameter padata[PA_SIZE];
88     } e;
89     ...
90     e.p.parms = padata;
91     e.p.dynamic_parms = 0;
92    
93     static char *character_names[] = {
94     "name_one","name_two"
95     }
96     (* fill padata with appropriate info *)
97     slv_define_parm(&(e.p), real_parm,
98     "r_parm","real parameter" ,
99     "this is an example of a real parameter" ,
100     U_p_real(val,25),U_p_real(lo,0),U_p_real(hi,100),1);
101     (* now assign the element of e.parm_array from somewhere in padata *)
102     SLV_RPARM_MACRO(REAL_PTR,parameters);
103    
104     (* fill padata with appropriate info *)
105     slv_define_parm(&(e.p), char_parm,
106     "c_parm", "character parameter",
107     "this is an example of a character parameter",
108     U_p_string(val,character_names[0]),
109     U_p_strings(lo,character_names),
110     U_p_int(hi,sizeof(character_names)/sizeof(char *)),1);
111     (* now assign the element of e.parm_array that matches. *)
112     SLV_CPARM_MACRO(CHAR_PTR,parameters);
113    
114     Resetting the value of a parameter can be done directly
115     except for string parameters which should be set with, for example,
116     slv_set_char_parameter(CHAR_PTR,newvalue);
117     or outside a solver where there is no sys->parm_array:
118    
119     slv_set_char_parameter(&(p.parms[i].info.c.value),argv[j]);
120    
121     @endcode
122     */
123    
124 johnpye 67 #ifndef ASC_SLV_COMMON_H
125     #define ASC_SLV_COMMON_H
126 aw0a 1
127 johnpye 485 #include <utilities/ascConfig.h>
128    
129 aw0a 1 #undef SLV_INSTANCES
130     #define SLV_INSTANCES TRUE
131 jds 54 /**< SLV_INSTANCES should only be FALSE in a libasc.a free environment */
132 aw0a 1
133 jds 61 /*
134     * -------------------------------------------------------
135 johnpye 222 Common data structures for Westerberg derived solvers
136 jds 61 * -------------------------------------------------------
137 jds 74 */
138 jds 61
139     /** Solver output file informationn. */
140 aw0a 1 struct slv_output_data {
141 jds 61 FILE *more_important; /**< More significant output to this file stream. NULL ==> no output. */
142     FILE *less_important; /**< Less significant output to this file stream. NULL ==> no output. */
143 aw0a 1 };
144 jds 54
145 johnpye 480 /**
146 johnpye 222 Solver tolerance data structure.
147 johnpye 480 @todo KHACK THIS SHOULD BE REMOVED - solver/slv_common:slv_tolerance_data.
148 jds 61 */
149 aw0a 1 struct slv_tolerance_data {
150 jds 61 real64 drop; /**< Matrix entry drop tolerance during factorization */
151     real64 pivot; /**< Detect pivot too small, of those available. */
152     real64 singular; /**< Detect matrix numerically singular. */
153     real64 feasible; /**< Detect equality relations satisfied. */
154     real64 rootfind; /**< Detect single equality relation satisfied. */
155     real64 stationary; /**< Detect lagrange stationary. */
156     real64 termination; /**< Detect progress diminished. */
157 aw0a 1 };
158    
159 jds 61 /** Solver sub-parameter data structure. */
160 aw0a 1 struct slv_sub_parameters {
161 jds 54 /* arrays of parametric data */
162 jds 61 int32 *iap; /**< Array of parametric int32 data. */
163     real64 *rap; /**< Array of parametric real64 data. */
164     char* *cap; /**< Array of parametric char* data. */
165     void* *vap; /**< Array of parametric void* data. */
166 jds 54 /* symbolic parameter names */
167 jds 61 char* *ianames; /**< Array of symbolic names for iap parameters. */
168     char* *ranames; /**< Array of symbolic names for rap parameters. */
169     char* *canames; /**< Array of symbolic names for cap parameters. */
170     char* *vanames; /**< Array of symbolic names for vap parameters. */
171 jds 54 /* longer explanations of the parameter data */
172 jds 61 char* *iaexpln; /**< Array of longer descriptions of iap parameters. */
173     char* *raexpln; /**< Array of longer descriptions of rap parameters. */
174     char* *caexpln; /**< Array of longer descriptions of cap parameters. */
175     char* *vaexpln; /**< Array of longer descriptions of vap parameters. */
176 jds 54 /* lengths of arrays above */
177 jds 61 int32 ilen; /**< Length of iap, ianames, and iaexpln arrays. */
178     int32 rlen; /**< Length of rap, ranames, and raexpln arrays. */
179     int32 clen; /**< Length of cap, canames, and caexpln arrays. */
180     int32 vlen; /**< Length of vap, vanames, and vaexpln arrays. */
181 aw0a 1 };
182    
183 jds 61 /**
184 johnpye 222 Data structure for solver statistics.
185     This is to collect data for the comparison of algorithms. All solvers
186 johnpye 480 should have at least one of these, though the interface will check for
187     NULL before reading the data. The interpretation of these data is
188 johnpye 222 somewhat up to the coder.
189 jds 61 */
190 aw0a 1 struct slv_block_cost {
191 jds 61 int32 size, /**< How big is the block, in terms of variables? */
192     iterations, /**< How many iterations to convergence/divergence? */
193     funcs, /**< How many function evaluations were made? */
194     jacs, /**< How many jacobian evaluations were made? */
195     reorder_method; /**< Not documented. Up to individual solver? */
196     double time, /**< How much cpu total time elapsed while in the block? */
197     resid, /**< Not documented. The size of the residual? */
198     functime, /**< Time spent in function evaluations. */
199     jactime; /**< Time spent in jacobian evaluations, stuffing. */
200 aw0a 1 };
201    
202 jds 61 /** Integer solver parameter substructure. */
203 aw0a 1 struct slv_int_parameter {
204 jds 61 int32 value; /**< Value. */
205     int32 low; /**< Lower bound. */
206     int32 high; /**< Upper bound. */
207 aw0a 1 };
208    
209 jds 61 /** Boolean solver parameter substructure. */
210 aw0a 1 struct slv_boolean_parameter {
211 jds 61 int32 value; /**< Value. */
212     int32 low; /**< Lower bound. */
213     int32 high; /**< Upper bound. */
214 aw0a 1 };
215    
216 jds 61 /** Real solver parameter substructure. */
217 aw0a 1 struct slv_real_parameter {
218 jds 61 double value; /**< Value. */
219     double low; /**< Lower bound. */
220     double high; /**< Upper bound. */
221 aw0a 1 };
222    
223 jds 61 /** Char solver parameter substructure. */
224 aw0a 1 struct slv_char_parameter {
225 johnpye 222 char *value; /**< Selected value. */
226     char **argv; /**< Array of possible values */
227     int32 high; /**< Length of array of possible values. */
228 aw0a 1 };
229    
230 jds 54 /** Basic solver parameter types. */
231 aw0a 1 enum parm_type {
232 jds 61 int_parm, /**< Integer type. */
233     bool_parm, /**< Boolean type. */
234     real_parm, /**< Real type. */
235     char_parm /**< Char type. */
236 aw0a 1 };
237    
238 jds 61 /** Parameter arguments */
239 aw0a 1 union parm_arg
240     {
241 jds 61 char **argv; /**< Strings array argument. */
242     char *argc; /**< Char argument. */
243     int32 argi; /**< Integer argument. */
244     int32 argb; /**< Boolean argument. */
245     real64 argr; /**< Real argument. */
246 aw0a 1 };
247    
248 jds 61 /** Solver parameter structure. */
249 aw0a 1 struct slv_parameter {
250 jds 61 enum parm_type type; /**< Parameter type. */
251     int32 number; /**< Index in array. */
252     int32 display; /**< Display page. */
253     char *name; /**< Scripting short name. */
254     char *interface_label; /**< User interface label. */
255     char *description; /**< Modest help string. */
256 jds 54 union {
257 jds 61 struct slv_int_parameter i; /**< Integer parameter. */
258     struct slv_boolean_parameter b; /**< Boolean parameter. */
259     struct slv_real_parameter r; /**< Real parameter. */
260     struct slv_char_parameter c; /**< Char parameter. */
261     } info; /**< Data. */
262 aw0a 1 };
263    
264 jds 54 /*
265 aw0a 1 * Macros for parm_arg unions.
266 jds 54 * Sets appropriate member (parm_u) of the union to the
267     * value specified (val) and returns (parm_u).
268     * (parm_u) should be one of val, lo, or hi.
269 aw0a 1 * These macros are used in calls to the
270     * slv_define_parm function defined below.
271     */
272    
273 jds 54 #define U_p_int(parm_u,val) ((((parm_u).argi = (val))), (parm_u))
274     /**<
275 johnpye 222 Sets the argi of parm_arg parm_u to val and returns the parm_u.
276     This macro is used for setting integer parm_arg arguments in calls
277     to slv_define_parm(). parm_u should be one of { val, lo, hi },
278     which correspond to local parm_arg variables that should be used
279     in client functions calling slv_define_parm().
280 jds 61 *
281 johnpye 222 @param parm_u The parm_arg to modify, one of {val, lo, hi}.
282     @param val int, the new value for the parm_arg.
283     @return Returns parm_u.
284 jds 54 */
285     #define U_p_bool(parm_u,val) ((((parm_u).argb = (val))), (parm_u))
286     /**<
287 johnpye 222 Sets the argb of parm_arg parm_u to val and returns the parm_u.
288     This macro is used for setting boolean parm_arg arguments in calls
289     to slv_define_parm(). parm_u should be one of { val, lo, hi },
290     which correspond to local parm_arg variables that should be used
291     in client functions calling slv_define_parm().
292 jds 61 *
293 johnpye 222 @param parm_u The parm_arg to modify, one of {val, lo, hi}.
294     @param val boolean, the new value for the parm_arg.
295     @return Returns parm_u.
296 jds 54 */
297     #define U_p_real(parm_u,val) ((((parm_u).argr = (val))), (parm_u))
298     /**<
299 johnpye 222 Sets the argr of parm_arg parm_u to val and returns the parm_u.
300     This macro is used for setting real parm_arg arguments in calls
301     to slv_define_parm(). parm_u should be one of { val, lo, hi },
302     which correspond to local parm_arg variables that should be used
303     in client functions calling slv_define_parm().
304 jds 61 *
305 johnpye 222 @param parm_u The parm_arg to modify, one of {val, lo, hi}.
306     @param val double, the new value for the parm_arg.
307     @return Returns parm_u.
308 jds 54 */
309     #define U_p_string(parm_u,val) ((((parm_u).argc = (val))), (parm_u))
310     /**<
311 johnpye 222 Sets the argc of parm_arg parm_u to val and returns the parm_u.
312     This macro is used for setting string parm_arg arguments in calls
313     to slv_define_parm(). parm_u should be one of { val, lo, hi },
314     which correspond to local parm_arg variables that should be used
315     in client functions calling slv_define_parm().
316 jds 61 *
317 johnpye 222 @param parm_u The parm_arg to modify, one of {val, lo, hi}.
318     @param val char *, the new value for the parm_arg.
319     @return Returns parm_u.
320     For use in calls to slv_define_parm().
321 jds 54 */
322     #define U_p_strings(parm_u,val) ((((parm_u).argv = (val))), (parm_u))
323     /**<
324 johnpye 222 Sets the argv of parm_arg parm_u to val and returns the parm_u.
325 johnpye 480 This macro is used for setting string array parm_arg arguments in
326 johnpye 222 calls to slv_define_parm(). parm_u should be one of { val, lo, hi },
327     which correspond to local parm_arg variables that should be used
328     in client functions calling slv_define_parm().
329 jds 61 *
330 johnpye 222 @param parm_u The parm_arg to modify, one of {val, lo, hi}.
331     @param val char **, the new value for the parm_arg.
332     @return Returns parm_u.
333     For use in calls to slv_define_parm().
334 jds 54 */
335 aw0a 1
336 jds 61 #define SLV_IPARM_MACRO(NAME,slv_parms) \
337 aw0a 1 if (make_macros == 1) { \
338 jds 61 (NAME) = &((slv_parms)->parms[(slv_parms)->num_parms-1].info.i.value); \
339 aw0a 1 }
340 jds 54 /**<
341 johnpye 222 Macro for defining macros of type integer (IPARM).
342     See SLV_CPARM_MACRO() for more information.
343 jds 54 */
344 jds 61 #define SLV_BPARM_MACRO(NAME,slv_parms) \
345 aw0a 1 if (make_macros == 1) { \
346 jds 61 (NAME) = &((slv_parms)->parms[(slv_parms)->num_parms-1].info.b.value); \
347 aw0a 1 }
348 jds 54 /**<
349 johnpye 222 Macro for defining macros of type boolean (BPARM).
350     See SLV_CPARM_MACRO() for more information.
351 jds 54 */
352 jds 61 #define SLV_RPARM_MACRO(NAME,slv_parms) \
353 aw0a 1 if (make_macros == 1) { \
354 jds 61 (NAME) = &((slv_parms)->parms[(slv_parms)->num_parms-1].info.r.value); \
355 aw0a 1 }
356 jds 54 /**<
357 johnpye 222 Macro for defining macros of type real (RPARM).
358     See SLV_CPARM_MACRO() for more information.
359 jds 54 */
360 jds 61 #define SLV_CPARM_MACRO(NAME,slv_parms) \
361 aw0a 1 if (make_macros == 1) { \
362 jds 61 (NAME) = &((slv_parms)->parms[(slv_parms)->num_parms-1].info.c.value); \
363 aw0a 1 }
364 jds 54 /**<
365     * Macro for defining macros of type character (CPARM).
366 jds 61 * To use, provide a NAME for the macro (in caps by convention)
367     * and a slv_parameters_t pointer (slv_parm). The NAME should be
368 jds 54 * defined as an element in an array of void pointers in the
369     * module in which the macro is to be used. This macro uses the
370     * current number of registered parameters to link the array of
371     * _VOID_ _POINTERS_ to the correct parameters. If you want to create
372     * a macro for a parameter, you should put the appropriate macro
373     * creating macro IMEDIATELY after the call to slv_define_parm
374     * for that parameter.<br><br>
375     * Local int make_macros; must be defined.
376 aw0a 1 */
377    
378 jds 54 /**
379 johnpye 480 Holds the array of parameters and keeps a count of how many it
380     contains. Also holds various other information which should be
381 johnpye 222 turned into slv_parameters or moved elsewhere
382     <pre>
383     Every registered client should have a slv_parameters_t somewhere in it.
384    
385     The following is a list of parameters (those parameters that can be
386     modified during solve without calling slv_presolve() are marked with
387     "$$$"). It should be noted that some solvers may not be conformable
388     to some of the parameters. Default values are subject to change via
389     experimentation.
390    
391     output.more_important (default stdout): $$$
392     output.less_important (default NULL): $$$
393     All output from the solver is written to one of these two files
394     (except bug messages which are written to stderr). Common values
395     are NULL (==> no file) and stdout. The more important messages
396     go to output.more_important and less important messages go to
397     output.less_important. To shut the solver up, set both files to
398     NULL.
399    
400     tolerance.drop (default 1e-16):
401     tolerance.pivot (default 0.1):
402     tolerance.singular (default 1e-12):
403     tolerance.feasible (default 1e-8):
404     tolerance.rootfind (default 1e-12):
405     tolerance.stationary (default 1e-8):
406     tolerance.termination (default 1e-12):
407     These define the criterion for selecting pivotable relations,
408     whether the equations are satisfied, if a local minimum has been
409     found, or if no further reduction in the augmented lagrange merit
410     phi can be achieved.
411     - During jacobian reduction, each equation pivot selected must be
412     at least a certain fraction given by TOLERANCE.PIVOT of the largest
413     available.
414     Also, the largest value in the row must exceed TOLERANCE.SINGULAR
415     in order to be considered independent.
416     - The absolute value of each unscaled equation residual is compared
417     with TOLERANCE.FEASIBLE in order to determine convergence of the
418     equality constraints during Newton iteration.
419     - The absolute value of each unscaled equation residual is compared
420     with TOLERANCE.ROOTFIND in order to determine convergence of the
421     constraint during rootfinding of single equations.
422     - Detection of a minimum requires the stationary condition of the
423     lagrange to be less than TOLERANCE.STATIONARY.
424     - If the directional derivative of phi along the negative gradient
425     direction using the suggested iteration step length falls below
426     TOLERANCE.TERMINATION, iteration is ceased.
427     - TOLERANCE.DROP is the smallest number magnitude to be allowed
428     in the Jacobian matrix during factorization. Default is optimistic.
429    
430     time_limit (default 30.0): $$$
431     This defines the time limit expressed as cpu seconds per block.
432     If the solver requires more time than this in any given block,
433     then it will stop.
434    
435     iteration_limit (default 100): $$$
436     This defines the maximum number of iterations attempted in a given
437     block. The solver will stop after this many iterations if it fails
438     to converge.
439    
440     factor_option (default 0):
441     This sets the number of the linear factorization to suggest.
442     This does not map directly to linsol numbering of any sort.
443     The map is: 0 <==> RANKI, 1 <==> RANKI_JZ, 2+ <==> ?.
444     The solver is free to ignore this suggestion.
445     In fact, the specific solver is free to define the meaning of factor
446     option depending on what linear packages it can talk to.
447    
448     partition (default TRUE):
449     Specifies whether or not the system will be partitioned into blocks
450     or not. If not, then the system will be considered as one large
451     block.
452    
453     ignore_bounds (default FALSE):
454     Specifies whether or not bounds will be considered during solving.
455     WARNING: if this flag is set, there will be no guarantees that the
456     solution will lie in bounds. Suggested use might be to set this
457     flag to TRUE, solve, reset this flag to FALSE, and resolve.
458     More often than not, in fact, ignore bounds will lead to floating
459     point exceptions, halting the solution process.
460    
461     rho (default 1.0):
462     Used as a scalar pre-multiplier of the penalty term quantified by one
463     half the two norm of the equality constraint residuals in an
464     augmented lagrange merit function.
465    
466     sp.ia/ra/ca/vap (defaults NULL, READ ONLY):
467     Is a set of pointers to arrays (int/double/(char*)/void*).
468     The values of the pointers themselves should not be modified,
469     though the values pointed at may be modified. Note that this is
470     _direct_ modification and will take effect immediately, not on
471     the next call to slv_set_parameters. When the engine gets around
472     to looking at the values in these arrays is engine dependent.
473     NULL is the expected value for some or all of these array
474     pointers, depending on the engine. The sizes of these arrays are
475     specific to each solver's interface. As being of interest (at
476     compile time) to both the slvI.c file and the GUI/CLUI, the
477     sizes of the arrays to be pointed to are part of the slvI.h file.
478     The implementor of each slvI.c should take care to use as much of
479     the slv_parameters_t as possible before passing data through the
480     arrays provided in the sub_parameters. This will make for a
481     minimal amount of work when adding an engine to the GUI/CLUI.
482     To further aid reusability/sanity preservation, slvI.h should
483     be appended with proper defines for subscripting these arrays.
484    
485     sp.i/r/c/vlen (defaults 0, READ ONLY)
486     lengths of the sub_parameter arrays.
487    
488     sp.ia/ra/ca/vanames (defaults NULL, READONLY)
489     symbolic names for the corresponding entries in ia/ra/ca/vap.
490    
491     sp.ia/ra/ca/vaexpln (defaults NULL, READONLY)
492     longer explanations for the corresponding entries in ia/ra/ca/vap.
493    
494     whose (default 0=>slv0, READ ONLY)
495     This tells where a parameter set came from, since the default
496     action of slv_get_parameters is to return a copy of slv0's
497     parameters if the parameters asked for don't exist because
498     the solver in question wasn't built/linked.
499     </pre>
500 aw0a 1 */
501 jds 54 typedef struct slv_parameters_structure {
502 jds 61 struct slv_output_data output; /**< File streams for solver output. */
503     struct slv_tolerance_data tolerance; /**< Defince various tolerances for the solver. */
504     struct slv_parameter *parms; /**< Holds the parameters defined for a solver. */
505     int32 num_parms; /**< The number of parameters in parms. */
506     int32 dynamic_parms; /**< Set to TRUE if parms is dynamically allocated. */
507 aw0a 1
508 jds 54 /* we wish the following were on the way out */
509 jds 61 struct slv_sub_parameters sp; /**< Solver sub-parameters. */
510     int whose; /**< Code for where a parameter set came from. */
511     int32 ignore_bounds; /**< Set to TRUE to disregard boundary conditions. */
512     int32 partition; /**< Set to TRUE if system will be partitioned into blocks. */
513 jds 54
514     /* the following are on the way out */
515 jds 61 double time_limit; /**< Max cpu seconds per block. @todo kill */
516     double rho; /**< Scaler premultiplier of penalty term. @todo kill */
517     int32 iteration_limit; /**< Max number of iterations. @todo kill */
518     int32 factor_option; /**< Suggests a number for linear factorization. @todo kill */
519 jds 54
520     } slv_parameters_t;
521    
522 jds 61
523     /* slv_destroy_parms() is defined in slv.c */
524 johnpye 522 ASC_DLLSPEC(void ) slv_destroy_parms(slv_parameters_t *p);
525 jds 61 /**<
526 johnpye 222 Deallocates any allocated memory held by a parameter structure.
527     Only the held memory is freed, not p itself. Further, if
528     (p->dynamic_parms != 0), the strings in p->parms are freed
529     but not p->parms itself. Does nothing if p is NULL.
530    
531     @param p The parameter structure to destroy.
532 jds 54 */
533 jds 61
534     /* slv_define_parm() is defined in slv.c */
535 jds 54 extern int32 slv_define_parm(slv_parameters_t *p,
536     enum parm_type type,
537     char *interface_name,
538     char *interface_label,
539     char *description,
540     union parm_arg value,
541     union parm_arg lower_bound,
542     union parm_arg upper_bound,
543     int32 page);
544 jds 61 /**<
545 johnpye 222 Adds (defines) a new parameter in a parameter structure.
546     Use this function to add & define new parameters for a solver.
547    
548     @param p Parameter structure to receive the new parameter.
549     @param type Parameter type: int_parm, bool_parm, real_parm, or char_parm.
550     @param interface_name A very short but descriptive name that the interface
551     can use to identify the parameter.
552     @param interface_label A short text string to be displayed on the interface.
553     @param description A slightly more detailed string to be displayed
554     upon request a la balloon help.
555     @param value The value for the parameter, set using one of
556     the U_p_int() style macros defined above.
557     @param lower_bound The lower bound for the parameter, set using one of
558     the U_p_int() style macros defined above.
559     @param upper_bound The upper bound for the parameter, set using one of
560     the U_p_int() style macros defined above.
561     @param page The page of the interface options dialog on which
562     to display this parameter. Ranges from 1..max_page_no.
563     Set to -1 if this parameter is not to be displayed in
564     the interface.
565 johnpye 480 @return Returns -1 if p is NULL or called with unsupported type;
566 johnpye 222 otherwise returns the number of registered parameters in p.
567 jds 61 */
568 jds 54
569 jds 61 /* slv_set_char_parameter() is defined in slv.c */
570 johnpye 490 ASC_DLLSPEC(void) slv_set_char_parameter(char **cptr, CONST char *newvalue);
571 jds 61 /**<
572 johnpye 222 Sets a char parameter value to a new string.
573     Resetting the value of a parameter can be done directly except
574     for string parameters which must be set with this function. The
575     string newvalue is not kept by the function.<br><br>
576    
577     Example: slv_set_char_parameter(&(p.parms[i].info.c.value),argv[j]);
578    
579     @param cptr Pointer to the char array to set.
580     @param newvalue New value for *cptr.
581 jds 54 */
582    
583 jds 61 /** Solver block status record. */
584 aw0a 1 struct slv__block_status_structure {
585 jds 61 int32 number_of; /**< Number of blocks in system. */
586     int32 current_block; /**< Block number of the current block that the
587     solver is working on. It is assumed that all
588     previous blocks have already converged. */
589     int32 current_reordered_block; /**< Number of the block most recently reordered. */
590     int32 current_size; /**< Number of variables/relations in the current block. */
591     int32 previous_total_size; /**< Total size of previous blocks (= number of
592     variables/relations already converged). */
593     int32 previous_total_size_vars; /**< Not currently implemented. */
594     int32 iteration; /**< Number of iterations so far in the current block. */
595     int32 funcs; /**< Number of residuals calculated in the current block. */
596     int32 jacs; /**< Number of jacobians evaluated in the current block. */
597     double cpu_elapsed; /**< Number of cpu seconds elapsed in the current block. */
598     double functime; /**< Number of cpu seconds elapsed getting residuals. */
599     double jactime; /**< Number of cpu seconds elapsed getting jacobians. */
600     real64 residual; /**< Current residual (RMS value) for the current block. */
601 aw0a 1 };
602    
603 jds 54 /**
604     * Solver status flags.
605     * <pre>
606 aw0a 1 * The following is a list of statuses and their meanings. Statuses
607     * cannot be written to, and thus there is no notion of default value.
608     *
609     * ok:
610     * Specifies whether or not everything is "ok". It is a shorthand for
611     * testing all of the other flags.
612     *
613     * over_defined:
614     * under_defined:
615     * struct_singular:
616     * Specifies whether the system is over-defined, under-defined, or
617     * structurally singular. These fields are set by slv_presolve where
618     * the structural analysis is performed. It should be noted that
619     * over_defined and under_defined are mutually exclusive and both
620     * imply struct_singular, although a system can be structurally
621     * singular without being over-defined or under-defined.
622     *
623     * ready_to_solve:
624     * Specifies whether the system is ready to solve. In other words, is
625     * slv_iterate or slv_solve legal? This flag is FALSE before
626     * slv_presolve or after the system has converged or the solver has
627     * given up for whatever reason.
628     *
629     * converged:
630     * This flag is set whenever the entire system has converged. The
631     * convergence will be genuine (all relations satisfied within
632     * tolerance, all bounds satisfied, all calculations defined, etc.).
633     *
634     * diverged:
635     * This flag is set whenever the solver has truly given up (i.e. given
636     * up for any reason not covered below).
637     *
638     * inconsistent:
639     * The solver has concluded unambiguously (e.g. by symbolic
640     * manipulation) that the system is inconsistent.
641     *
642     * calc_ok:
643     * Specifies whether or not there were any calculation errors in
644     * computing the residuals at the current point.
645     *
646     * iteration_limit_exceeded:
647     * Specifies whether or not the iteration count was exceeded or not.
648     *
649     * time_limit_exceeded:
650     * Specifies whether or not the cpu time limit was exceeded.
651     *
652     * panic:
653     * Specifies whether or not the user called a halt interactively;
654     *
655     * iteration:
656     * Total number of iterations so far. Total iteration count is reset to
657     * zero whenever slv_presolve or slv_resolve is called.
658     *
659     * cpu_elapsed:
660     * Total number of cpu seconds elapsed. Total cpu time elapsed is reset
661     * to zero whenever slv_presolve or slv_resolve is called.
662     *
663     * block.number_of:
664     * Number of blocks in system.
665     *
666     * block.current_block:
667     * Block number of the current block that the solver is working on.
668     * It is assumed that all previous blocks have already converged.
669     *
670     * block.current_size:
671     * Number of variables/relations in the current block.
672     *
673     * block.previous_total_size:
674     * Total size of previous blocks (= number of variables/relations
675     * already converged).
676     *
677     * block.iteration:
678     * Number of iterations so far in the current block.
679     *
680     * block.functime:
681     * Number of cpu seconds elapsed getting residuals from whereever.
682     *
683     * block.jactime:
684     * Number of cpu seconds elapsed getting jacobians from whereever.
685     *
686     * block.cpu_elapsed:
687     * Number of cpu seconds elapsed so far in the current block.
688     *
689     * block.residual:
690     * Current residual (RMS value) for the current block.
691     *
692     * cost (READ ONLY)
693     * This is a pointer to first of an array which is costsize long of
694     * slv_block_cost structures. This is to collect data for the
695     * comparison of algorithms. All solvers should have at least
696     * one of these, though the interface will check for null before
697     * reading the data. The block_cost structure contains:
698     * size (how big is the block, in terms of variables)
699     * iterations (how many iterations to convergence/divergence)
700     * funcs (how many function evaluations were made?)
701     * jacs (how many jacobian evaluations were made?)
702     * time (how much cpu total time elapsed while in the block?)
703     * functime (time spent in function evaluations)
704     * jactime (time spent in jacobian evaluations, stuffing)
705     * (for those codes where a function evaluation is
706     * a byproduct of gradient evaluation, the func cost
707     * will be billed here.)
708 jds 74 * The interpretation of these data is somewhat up to the coder.
709 aw0a 1 *
710     * costsize
711     * This is how big the cost array is. It should in general be the
712     * number of blocks in the system plus 1 so that all the unincluded
713     * relations can be billed to the blocks+1th cost if they are
714     * evaluated.
715 jds 54 * </pre>
716 aw0a 1 */
717 jds 54 typedef struct slv_status_structure {
718 jds 61 uint32 ok : 1; /**< If TRUE, everything is ok. */
719     uint32 over_defined : 1; /**< Is system over-defined? */
720     uint32 under_defined : 1; /**< Is system under-defined? */
721     uint32 struct_singular : 1; /**< Is system structurally singular? */
722     uint32 ready_to_solve : 1; /**< Is system ready to solve? */
723     uint32 converged : 1; /**< Has system fully convergeded? */
724     uint32 diverged : 1; /**< Has system diverged? */
725     uint32 inconsistent : 1; /**< Was system was found to be inconsistent? */
726     uint32 calc_ok : 1; /**< Were any errors encounted calculating residuals? */
727     uint32 iteration_limit_exceeded : 1; /**< Was the iteraction limit exceeded? */
728     uint32 time_limit_exceeded : 1; /**< Was the time limit exceeded? */
729     uint32 panic :1; /**< Did the user stop the solver interactively? */
730     int32 iteration; /**< Total number of iterations so far. */
731     int32 costsize; /**< Number of elements in the cost array. */
732     double cpu_elapsed; /**< Total elapsed cpu seconds. */
733     struct slv_block_cost *cost; /**< Array of slv_block_cost records. */
734     struct slv__block_status_structure block; /**< Block status information. */
735 jds 54 } slv_status_t;
736 aw0a 1
737 jds 61 /*
738     * --------------------------------
739     * vector_data class & operations
740     * --------------------------------
741     *
742     * If we get brave, we will consider replacing the cores of these
743     * routines with blas calls. We aren't overeager to go mixed
744     * language call nuts just yet, however.
745     */
746    
747 johnpye 480 /**
748 jds 61 * A dense vector class of some utility and the functions for it.
749     * The vector consists of an array of real64 (vec) and a mtx_range_t
750     * (rng) which refers to subsets of the range of indexes of vec.
751     * When calling the various vector functions, the range indexes in
752     * rng are used to calculate offsets in the vec array. Therefore,
753     * it is important that your rng->(low,high) refer to valid indexes
754     * of vec[]. In particular
755     * - neither rng->low nor rng->high may be negative
756     * - low <= high
757     * - high < length of vec
758 johnpye 480 * This means that whatever your maximum high is, you should allocate
759 jds 61 * (high+1) values in vec.
760     * @todo solver/slv_common:vector_data & operations should be
761     * moved to a module in general or utilities.
762     */
763 aw0a 1 struct vector_data {
764 jds 61 real64 norm2; /**< 2-norm of vector squared. */
765     mtx_range_t *rng; /**< Pointer to range of vector (low..high). */
766     real64 *vec; /**< Data array (NULL => uninitialized). */
767     boolean accurate; /**< Is vector currently accurate? User-manipulated. */
768 aw0a 1 };
769    
770 johnpye 592 ASC_DLLSPEC(struct vector_data *) slv_create_vector(int32 low, int32 high);
771 jds 61 /**<
772     * Returns a new vector_data initialized to the specified range.
773     * This function creates, initializes, and returns a new vector_data
774     * structure. The vector is initialized using init_vector() and
775     * a pointer to the new struct is returned. If the specified range
776     * is improper (see slv_init_vector()) then a valid vector cannot be
777     * created and NULL is returned.<br><br>
778 aw0a 1 *
779 jds 61 * Destruction of the returned vector_data is the responsibility of
780     * the caller. slv_destroy_vector() may be used for this purpose.
781     *
782     * @param low The lower bound of the vector's range.
783     * @param high The upper bound of the vector's range.
784     * @return A new initialized vector_data, or NULL if one could
785     * not be created.
786 jds 54 */
787    
788 johnpye 592 ASC_DLLSPEC(int) slv_init_vector(struct vector_data *vec, int32 low, int32 high);
789 jds 61 /**<
790     * Initializes a vector_data structure.
791     * The new range (low..high) is considered proper if both low and
792     * high are zero or positive, and (low <= high). If the new range is
793     * not proper (or if vec itself is NULL), then no modifications are
794     * made to vec.<br><br>
795     *
796     * If the range is proper then vec->rng is allocated if NULL and then
797     * set using low and high. Then vec->vec is allocated (if NULL) or
798     * reallocated to size (high+1). The data in vec->vec is not
799     * initialized or changed. The member vec->accurate is set to FALSE.
800     *
801     * @param vec Pointer to the vector_data to initialize.
802     * @param low The lower bound of the vector's range.
803     * @param high The upper bound of the vector's range.
804     * @return Returns 0 if the vector is initialized successfully,
805     * 1 if an improper range was specified, 2 if vec is NULL,
806     * and 3 if memory cannot be allocated.
807     */
808    
809 johnpye 592 ASC_DLLSPEC(void) slv_destroy_vector(struct vector_data *vec);
810 jds 61 /**<
811     * Destroys a vector and its assocated data.
812     * Deallocates any memory held in vec->rng and vec->vec,
813 johnpye 480 * and then deallocates the vector itself. NULL is tolerated
814 jds 61 * for vec, vec->rng, or vec->vec.
815     *
816     * @param vec Pointer to the vector_data to destroy.
817     */
818    
819 johnpye 592 ASC_DLLSPEC(void) slv_zero_vector(struct vector_data *vec);
820 jds 54 /**<
821 jds 61 * Zeroes a vector.
822     * The vector entries between vec->rng.low and vec->rng.high will
823 johnpye 480 * be set to 0.0.
824 jds 61 * The following are not allowed and are checked by assertion:
825     * - NULL vec
826     * - NULL vec->rng
827     * - NULL vec->vec
828     * - vec->rng->low < 0
829     * - vec->rng->low > vec->rng->high
830     *
831     * @param vec The vector to zero.
832 jds 54 */
833    
834 johnpye 592 ASC_DLLSPEC(void) slv_copy_vector(struct vector_data *srcvec,
835 jds 61 struct vector_data *destvec);
836 jds 54 /**<
837 jds 61 * Copies the data from srcvec to destvec.
838     * The data in the range [srcvec->rng.low .. srcvec->rng.high]
839     * is copied to destvec starting at position destvec->rng.low.
840     * destvec must have at least as many elements in vec as srcvec.
841     * The following are not allowed and are checked by assertion:
842     * - NULL srcvec
843     * - NULL srcvec->rng
844     * - NULL srcvec->vec
845     * - srcvec->rng->low < 0
846     * - srcvec->rng->low > srcvec->rng->high
847     * - NULL destvec
848     * - NULL destvec->rng
849     * - NULL destvec->vec
850     * - destvec->rng->low < 0
851 aw0a 1 *
852 jds 61 * @param srcvec The vector to copy.
853     * @param destvec The vector to receive the copied data.
854 jds 54 */
855    
856 johnpye 592 ASC_DLLSPEC(real64) slv_inner_product(struct vector_data *vec1,
857 jds 54 struct vector_data *vec2);
858     /**<
859 jds 61 * Calculates the dot product of 2 vectors.
860 jds 54 * Dot [vec1->rng.low .. vec1->rng.high] with vec2 starting at
861     * position vec2->rng.low.
862 jds 61 * The following are not allowed and are checked by assertion:
863     * - NULL vec1
864     * - NULL vec1->rng
865     * - NULL vec1->vec
866     * - vec1->rng->low < 0
867     * - vec1->rng->low > vec1->rng->high
868     * - NULL vec2
869     * - NULL vec2->rng
870     * - NULL vec2->vec
871     * - vec2->rng->low < 0
872 aw0a 1 *
873 jds 61 * @param vec1 The 1st vector for the dot product.
874     * @param vec2 The 2nd vector for the dot product.
875     * @todo solver/slv_common:slv_inner_product() could stand to be optimized.
876 jds 54 */
877    
878 johnpye 592 ASC_DLLSPEC(real64) slv_square_norm(struct vector_data *vec);
879 jds 54 /**<
880 jds 61 * Calculates the dot product of a vector with itself.
881 jds 54 * Dot [vec->rng.low .. vec->rng.high] with itself and store the
882     * result in vec->norm2.
883 jds 61 * The following are not allowed and are checked by assertion:
884     * - NULL vec
885     * - NULL vec->rng
886     * - NULL vec->vec
887     * - vec->rng->low < 0
888     * - vec->rng->low > vec->rng->high
889 aw0a 1 *
890 jds 61 * @param vec The vector for the dot product.
891     * @todo solver/slv_common:slv_square_norm() could stand to be optimized.
892 jds 54 */
893    
894 johnpye 592 ASC_DLLSPEC(void) slv_matrix_product(mtx_matrix_t mtx,
895 jds 54 struct vector_data *vec,
896 jds 61 struct vector_data *prod,
897     real64 scale,
898 jds 54 boolean transpose);
899     /**<
900 jds 61 * Calculates the product of a vector, matrix, and scale factor.
901     * Stores prod := (scale)*(mtx)*(vec) if transpose = FALSE,
902     * or prod := (scale)*(mtx-transpose)(vec) if transpose = TRUE.
903 aw0a 1 * vec and prod must be completely different.
904     * If (!transpose) vec->vec is assumed indexed by current col and
905     * prod->vec is indexed by current row of mtx.
906     * If (transpose) vec->vec is assumed indexed by current row and
907     * prod->vec is indexed by current col of mtx.
908 jds 61 * The following are not allowed and are checked by assertion:
909     * - NULL mtx
910     * - NULL vec
911     * - NULL vec->rng
912     * - NULL vec->vec
913     * - vec->rng->low < 0
914     * - vec->rng->low > vec->rng->high
915     * - NULL prod
916     * - NULL prod->rng
917     * - NULL prod->vec
918     * - prod->rng->low < 0
919     * - prod->rng->low > prod->rng->high
920 aw0a 1 *
921 jds 61 * @param mtx The matrix for the product.
922     * @param vec The vector for the product.
923     * @param prod The vector to receive the matrix product.
924     * @param scale The scale factor by which to multiply the matrix product.
925     * @param transpose Flag for whether to use mtx or its transpose.
926     *
927     * @todo solver/slv_common:slv_mtx_product needs attention -
928     * does it go into mtx?
929 aw0a 1 */
930    
931 jds 54 extern void slv_write_vector(FILE *fp, struct vector_data *vec);
932     /**<
933 jds 61 * Write vector information to a file stream.
934     * Prints general information about the vector followed by the
935     * values in the range of the vector to file fp.
936     *
937     * @param fp The file stream to receive the report.
938     * @param vec The vector on which to report.
939 jds 54 */
940    
941     /*
942 jds 61 * ----------------------------
943     * Misc. BLAS-like functions
944     * ----------------------------
945 aw0a 1 */
946 jds 54
947 johnpye 592 ASC_DLLSPEC(real64) slv_dot(int32 len, const real64 *a1, const real64 *a2);
948 jds 61 /**<
949     * Calculates the dot product of 2 arrays of real64.
950     * This is an optimized routine (loop unrolled). It takes
951     * advantage of identical vectors. The 2 arrays must have
952     * at least len elements.
953     * The following are not allowed and are checked by assertion:
954     * - NULL a1
955     * - NULL a2
956     * - len < 0
957 aw0a 1 *
958 jds 61 * The same algorithm is used inside slv_inner_product(), so there
959     * is no need to use this function directly if you are using the
960     * vector_data type.
961     *
962     * @param len The length of the 2 arrays.
963     * @param a1 The 1st array for the dot product.
964     * @param a2 The 2nd array for the dot product.
965 aw0a 1 */
966    
967 jds 54 /*
968 jds 61 * --------------------------------
969 aw0a 1 * General input/output routines
970 jds 61 * --------------------------------
971 aw0a 1 */
972    
973 johnpye 592 ASC_DLLSPEC(FILE *)slv_get_output_file(FILE *fp);
974 jds 61 /**<
975     * Checks a file pointer, and if NULL returns a pointer to the nul device.
976 jds 54 * If you are in environment that doesn't have something like
977 johnpye 480 * /dev/null (nul on Windows), you'd better be damn sure your
978 jds 61 * sys->p.output.*_important are not NULL.
979     *
980     * @param fp The file stream to check.
981     * @return fp if it is not NULL, a pointer to the nul device otherwise.
982 jds 54 */
983    
984     /*
985 aw0a 1 * FILE pointer macros.
986     * fp = MIF(sys)
987     * fp = LIF(sys)
988     * fp = PMIF(sys)
989     * fp = PLIF(sys)
990     * or fprintf(MIF(sys),"stuff",data...);
991     * Use of these is requested on grounds of readability but not required.
992 jds 61 * All of these are macros, which means any specific solver interface
993 aw0a 1 * to ASCEND can use them, since all interfaces are supposed to
994     * support a parameters structure p somewhere in a larger system
995     * structure (sys) they keep privately.
996     * Use the PMIF or PLIF flavors if the parameters sys->p is a pointer
997     * rather than a in-struct member.
998     */
999     #define MIF(sys) slv_get_output_file( (sys)->p.output.more_important )
1000 jds 61 /**<
1001 jds 54 * Retrieve the "more important" output file for a system.
1002     * sys must exist and contain an element p of type slv_parameters_t.
1003 jds 61 *
1004     * @param sys The slv_system_t to query.
1005     * @return A FILE * to the "more important" output file for sys.
1006 jds 54 */
1007 aw0a 1 #define LIF(sys) slv_get_output_file( (sys)->p.output.less_important )
1008 jds 61 /**<
1009 jds 54 * Retrieve the "less important" output file for a system.
1010     * sys must exist and contain an element p of type slv_parameters_t.
1011 jds 61 *
1012     * @param sys The slv_system_t to query.
1013     * @return A FILE * to the "less important" output file for sys.
1014 jds 54 */
1015 aw0a 1 #define PMIF(sys) slv_get_output_file( (sys)->p->output.more_important )
1016 jds 61 /**<
1017 jds 54 * Retrieve the "more important" output file for a system.
1018     * sys must exist and contain an element p of type slv_parameters_t*.
1019 jds 61 *
1020     * @param sys The slv_system_t to query.
1021     * @return A FILE * to the "more important" output file for sys.
1022 jds 54 */
1023 aw0a 1 #define PLIF(sys) slv_get_output_file( (sys)->p->output.less_important )
1024 jds 61 /**<
1025 jds 54 * Retrieve the "less important" output file for a system.
1026     * sys must exist and contain an element p of type slv_parameters_t*.
1027 jds 61 *
1028     * @param sys The slv_system_t to query.
1029     * @return A FILE * to the "less important" output file for sys.
1030 jds 54 */
1031 aw0a 1
1032     /*------------------- begin compiler dependent functions -------------------*/
1033     #if SLV_INSTANCES
1034 jds 54
1035     #ifdef NEWSTUFF
1036     extern void slv_print_obj_name(FILE *outfile, obj_objective_t obj);
1037 jds 61 /**<
1038     * Not implemented.
1039     * Prints the name of obj to outfile. If obj_make_name() can't
1040     * generate a name, the global index is printed instead.
1041     * @todo Implement solver/slv_common:slv_print_obj_name() or remove prototype.
1042     */
1043 jds 54 #endif
1044     extern void slv_print_rel_name(FILE *outfile,
1045     slv_system_t sys,
1046     struct rel_relation *rel);
1047 jds 61 /**<
1048     * Prints the name of rel to outfile. If rel_make_name() can't
1049     * generate a name, the global index is printed instead.
1050     *
1051     * @param outfile The stream to receive the output.
1052     * @param sys The solver system.
1053     * @param rel The relation whose name should be printed.
1054     * @todo Move solver/slv_common:slv_print_rel_name() to solver/rel.
1055     */
1056    
1057 jds 54 extern void slv_print_var_name(FILE *outfile,
1058     slv_system_t sys,
1059     struct var_variable *var);
1060 jds 61 /**<
1061     * Prints the name of var to outfile. If var_make_name() can't
1062     * generate a name, the global index is printed instead.
1063     *
1064     * @param outfile The stream to receive the output.
1065     * @param sys The solver system.
1066     * @param var The variable whose name should be printed.
1067     * @todo Move solver/slv_common:slv_print_var_name() to solver/var.
1068     */
1069    
1070 jds 54 extern void slv_print_logrel_name(FILE *outfile,
1071     slv_system_t sys,
1072     struct logrel_relation *lrel);
1073 jds 61 /**<
1074     * Prints the name of lrel to outfile. If logrel_make_name() can't
1075     * generate a name, the global index is printed instead.
1076     *
1077     * @param outfile The stream to receive the output.
1078     * @param sys The solver system.
1079     * @param lrel The logical relation whose name should be printed.
1080     * @todo Move solver/slv_common:slv_print_logrel_name() to solver/logrel.
1081     */
1082    
1083 jds 54 extern void slv_print_dis_name(FILE *outfile,
1084     slv_system_t sys,
1085     struct dis_discrete *dvar);
1086 jds 61 /**<
1087     * Prints the name of dvar to outfile. If dis_make_name() can't
1088     * generate a name, the global index is printed instead.
1089     *
1090     * @param outfile The stream to receive the output.
1091     * @param sys The solver system.
1092     * @param dvar The discrete variable whose name should be printed.
1093     * @todo Move solver/slv_common:slv_print_dis_name() to solver/discrete.
1094     */
1095 aw0a 1
1096 jds 54 #ifdef NEWSTUFF
1097     extern void slv_print_obj_index(FILE *outfile, obj_objective_t obj);
1098 jds 61 /**<
1099     * Not implemented.
1100     * Prints the index of obj to outfile.
1101     * @todo Implement solver/slv_common:slv_print_obj_index() or remove prototype.
1102     */
1103 jds 54 #endif
1104     extern void slv_print_rel_sindex(FILE *outfile, struct rel_relation *rel);
1105 johnpye 480 /**<
1106 jds 61 * Prints the index of rel to outfile.
1107     *
1108     * @param outfile The stream to receive the output.
1109     * @param rel The relation whose index should be printed.
1110     * @todo Move solver/slv_common:slv_print_rel_name() to solver/rel.
1111     */
1112    
1113 jds 54 extern void slv_print_var_sindex(FILE *outfile, struct var_variable *var);
1114 jds 61 /**<
1115     * Prints the index of var to outfile.
1116     *
1117     * @param outfile The stream to receive the output.
1118     * @param var The variable whose index should be printed.
1119     * @todo Move solver/slv_common:slv_print_var_name() to solver/var.
1120     */
1121    
1122 jds 54 extern void slv_print_logrel_sindex(FILE *outfile, struct logrel_relation *lrel);
1123 johnpye 480 /**<
1124 jds 61 * Prints the index of lrel to outfile.
1125     *
1126     * @param outfile The stream to receive the output.
1127     * @param lrel The logical relation whose index should be printed.
1128     * @todo Move solver/slv_common:slv_print_logrel_name() to solver/logrel.
1129     */
1130    
1131 jds 54 extern void slv_print_dis_sindex(FILE *outfile, struct dis_discrete *dvar);
1132 jds 61 /**<
1133     * Prints the index of dvar to outfile.
1134     *
1135     * @param outfile The stream to receive the output.
1136     * @param dvar The discrete variable whose index should be printed.
1137     * @todo Move solver/slv_common:slv_print_dis_name() to solver/discrete.
1138     */
1139 aw0a 1
1140 jds 61 extern int slv_direct_solve(slv_system_t server,
1141     struct rel_relation *rel,
1142     struct var_variable *var,
1143     FILE *file,
1144     real64 epsilon,
1145     int ignore_bounds,
1146     int scaled);
1147     /**<
1148     * Attempts to directly solve the given relation (equality constraint) for
1149 aw0a 1 * the given variable, leaving the others fixed. Returns an integer
1150     * signifying the status as one of the following three:
1151 jds 54 * <pre>
1152 aw0a 1 * 0 ==> Unable to determine anything.
1153     * Not symbolically invertible.
1154     * 1 ==> Solution(s) found.
1155     * Variable value set to first found if more than one.
1156     * -1 ==> No solution found.
1157     * Function invertible, but no solution exists satisfying
1158     * var bounds (if active) and the epsilon given.
1159 jds 54 * </pre>
1160 aw0a 1 * The variable bounds will be upheld, unless ignore_bounds=FALSE.
1161     * Residual testing will be against epsilon and either scaled or
1162 jds 61 * unscaled residual according to scaled (no scale -> 0).
1163 aw0a 1 * If file != NULL and there are leftover possible solutions, we
1164     * will write about them to file.
1165 jds 61 *
1166     * @param server The slv_system_t (mostly ignored).
1167     * @param rel The relation to attempt to solve.
1168     * @param var The variable for which to solve.
1169     * @param file File stream to receive other possible solutions.
1170     * @param epsilon Tolerance for testing convergence.
1171     * @param ignore_bounds If TRUE, ignore bounds on variable.
1172     * @param scaled If TRUE, test scaled residuals against epsilon.
1173     * @todo solver/slv_common:slv_direct_solve() should be in solver/relman
1174     * or solver/slv3.
1175 aw0a 1 */
1176    
1177 jds 61 extern int slv_direct_log_solve(slv_system_t sys,
1178     struct logrel_relation *lrel,
1179     struct dis_discrete *dvar,
1180     FILE *file,
1181     int perturb,
1182     struct gl_list_t *instances);
1183     /**<
1184 aw0a 1 * Attempt to directly solve the given logrelation for the given
1185     * discrete variable, leaving the others fixed. Returns an integer
1186     * signifying the status as one of the following three:
1187 jds 54 * <pre>
1188 aw0a 1 * 0 ==> Unable to determine anything. Bad logrelation or dvar
1189     * 1 ==> Solution found.
1190     * 2 ==> More than one solution found. It does not modify the value
1191     * of dvar. Conflicting.
1192     * -1 ==> No solution found. Inconsistency
1193 jds 54 * </pre>
1194 aw0a 1 * If file != NULL and there are leftover possible solutions, we
1195     * will write about them to file.
1196     * The flag perturb and the gl_list are used to change the truth
1197     * value of some boundaries. This is sometimes useful in
1198     * conditional modeling.
1199 jds 61 *
1200     * @param sys The slv_system_t (mostly ignored).
1201     * @param lrel The logical relation to attempt to solve.
1202     * @param dvar The discrete variable for which to solve.
1203     * @param file File stream to receive other possible solutions.
1204     * @param perturb If TRUE, perturbs the truth values if necessary to find the solution.
1205     * @param instances List of instances.
1206     * @todo solver/slv_common:slv_direct_log_solve() should be in solver/logrel
1207     * or solver/slv9.
1208 aw0a 1 */
1209    
1210     #endif
1211     /*-------------------- END compiler dependent functions --------------------*/
1212    
1213 jds 54 /*
1214 jds 61 * --------------------
1215     * lnkmap functions
1216     * --------------------
1217 jds 54 */
1218    
1219 johnpye 592 ASC_DLLSPEC(int32 **) slv_create_lnkmap(int32 m, int32 n, int32 hl, int32 *hi, int32 *hj);
1220 jds 54 /**<
1221 jds 61 * Builds a row-biased mapping array from the hi,hj lists given.
1222 jds 54 * The map returned has the following format:
1223     * - map[i] is a vector describing the incidence in row i of the matrix.
1224     * - Let vars=map[i], where vars is int32 *.
1225     * - vars[0]=number of incidences in the relation.
1226     * - For all 0<=k<vars[0]
1227 jds 61 * - vars[2*k+1] = original column index of some var in the eqn.
1228     * - vars[2*k+2] = the lnk list index of element(i,vars[2*k+1])
1229 jds 54 *
1230 jds 61 * The ordering of column data (i.e. vars[2*k+1]) is implementation-defined
1231     * and should not be counted on. Similarly, the lnk list index (i.e.
1232     * vars[2*k+2]) will be a unique number in the range (0..hl-1), but the
1233     * exact ordering is implementation-defined. The map should only be
1234     * deallocated by destroy_lnkmap(). The memory allocation for a lnkmap
1235     * is done efficiently.<br><br>
1236 jds 54 *
1237 aw0a 1 * These create an odd compressed row mapping, given the hi and hj
1238 jds 61 * subscript vectors. The primary utility of the lnkmap is that
1239 aw0a 1 * it can be traversed rapidly when one wants to conditionally map a row of
1240     * a Harwell style (arbitrarily ordered) link representation
1241     * back into another representation where adding elements to a row
1242 jds 54 * is easily done.<br><br>
1243 aw0a 1 *
1244 jds 61 * hi and hj should specify a unique incidence pattern. That is, duplicate
1245     * (hi, hj) coordinates are not allowed and only 1 of the occurrences will
1246 johnpye 480 * end up in the map. hi should contain row indexes all less than m.
1247 jds 61 * hj should contain column indexes all less than n. If an invalid row/col
1248     * index is encountered, NULL is returned.
1249 jds 54 *
1250 jds 61 * @param m The number of rows expected (> highest index in hi).
1251     * The map returned will be this long.
1252     * @param n The number of columns expected (> highest index in hj).
1253 jds 54 * @param hl The length of hi and hj.
1254     * @param hi The eqn indices of a C numbered sparse matrix list.
1255     * @param hj The var indices of a C numbered sparse matrix list.
1256 jds 61 * @return Pointer to the new lnkmap array, or NULL if an error occurred.
1257 aw0a 1 */
1258    
1259 johnpye 592 ASC_DLLSPEC(int32 **) slv_lnkmap_from_mtx(mtx_matrix_t mtx, mtx_region_t *region);
1260 jds 54 /**<
1261 jds 61 * Generates a lnkmap from a region of a matrix.
1262     * The length of the map returned will be the order of mtx. Empty rows
1263     * and columns are allowed in the matrix. Map entries for rows outside
1264     * the specified region will be 0 even if the row contains non-zero
1265     * elements. If mtx is NULL, or if the region is invalid for mtx, then
1266     * NULL is returned.<br><br>
1267 jds 54 *
1268 jds 61 * The map returned has the following format:
1269     * - map[i] is a vector describing the incidence in row i of the matrix.
1270     * - Let vars=map[i], where vars is int32 *.
1271     * - vars[0]=number of non-zeros in the row.
1272     * - For all 0<=k<vars[0]
1273     * - vars[2*k+1] = original column index of some a non-zero element in the row.
1274     * - vars[2*k+2] = the value of the element (i,vars[2*k+1]), cast to int32.
1275 jds 54 *
1276 jds 61 * @param mtx The matrix to map (non-NULL).
1277     * @param region The region of the matrix to map (non-NULL).
1278     * @return Pointer to the new lnkmap array, or NULL if an error occurred.
1279     * @see slv_create_lnkmap() for a more details about lnkmaps.
1280 aw0a 1 */
1281    
1282 johnpye 592 ASC_DLLSPEC(void) slv_destroy_lnkmap(int32 **map);
1283 jds 54 /**<
1284     * Deallocate a map created by slv_create_lnkmap() or slv_destroy_lnkmap().
1285     * destroy_lnkmap() will tolerate a NULL map as input.
1286 jds 61 *
1287     * @param map The lnkmap to destroy.
1288 jds 54 */
1289    
1290 johnpye 592 ASC_DLLSPEC(void) slv_write_lnkmap(FILE *fp, int m, int32 **map);
1291 jds 54 /**<
1292 jds 61 * Prints a link map to a file.
1293     * write_lnkmap() will tolerate a NULL map as input.
1294 jds 54 *
1295 jds 61 * @param fp The file stream to receive the report.
1296     * @param m The number of rows in map to print.
1297     * @param map The lnkmap to print.
1298 jds 54 */
1299    
1300 johnpye 67 #endif /* ASC_SLV_COMMON_H */
1301 jds 54

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