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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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