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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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