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

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