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

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