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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 221 by johnpye, Tue Dec 20 13:27:11 2005 UTC revision 222 by johnpye, Fri Jan 27 04:23:20 2006 UTC
# Line 1  Line 1 
1  /*  /*
2      SLV: Ascend Nonlinear Solver      SLV Common utilities and definitions
3        Ben Allan, based on the original slv.h by KW and JZ.
4        01/94. Abstracted from slvX.c January 1995. Ben Allan.
5    
6      Copyright (C) 1990 Karl Michael Westerberg      Copyright (C) 1990 Karl Michael Westerberg
7      Copyright (C) 1993 Joseph Zaher      Copyright (C) 1993 Joseph Zaher
8      Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan      Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan
# Line 22  Line 25 
25      This file is part of the SLV solver.      This file is part of the SLV solver.
26  */  */
27    
 /*  
  *  Contents:     slv common utilities and definitions  
  *  
  *  Authors:      Ben Allan  
  *                based on the original slv.h by KW and JZ.  
  *  
  *  Dates:        01/94 - original version  
  *  
  *  Description:  
  *  
  *  General C  utility routines for slv/Slv class interfaces. Abstracted from  
  *  slvX.c January 1995. Ben Allan.  
  *  slv.h is the header for folks on the ASCEND end, and this is the one for  
  *  folks on the Slv math end.  
  *  Don't protoize this file for ASCEND types other than mtx, vec, and boolean  
  *  real64, and int32 or we'll have you shot. In particular, not var and rel.  
  *  People who aren't supposed to know about var and rel include this.  
  *  
  *  In particular, this header may be used without knowing about the ASCEND  
  *  compiler or any of its annoying insanities so long as you drag out  
  *  ascmalloc().  
  *  This does commit you to being able to stomach the mtx.h file, however,  
  *  even if you choose to ignore the contents of mtx.  
  *  Several functions, notably the print suite for rel/var names,  
  *  assume you are linking against something that does know about  
  *  ASCEND instances unless the SLV_INSTANCES flag is set to FALSE.  
  *  
  *  The parameters and status struct definitions have been moved here,  
  *  being of general interest.  
  */  
   
28  /** @file  /** @file
29   *  SLV common utilities & structures for ASCEND solvers.  
30   *  This includes the following:      General C  utility routines for slv/Slv class interfaces. Abstracted from
31   *    - parameters struct definitions & manipulation routines      slvX.c January 1995. Ben Allan.
32   *    - status struct definitions & retrieval routines  
33   *    - vector operations      slv.h is the header for folks on the ASCEND end, and this is the one for
34   *    - solver print routines      folks on the Slv math end.
35   *    - lnkmap support functions      Don't protoize this file for ASCEND types other than mtx, vec, and boolean
36   *  <pre>      real64, and int32 or we'll have you shot. In particular, not var and rel.
37   *  Requires:     #include <stdio.h>      People who aren't supposed to know about var and rel include this.
38   *                #include "utilities/ascConfig.h"  
39   *                #include "solver/slv_types.h"      In particular, this header may be used without knowing about the ASCEND
40   *                #include "solver/rel.h"      compiler or any of its annoying insanities so long as you drag out
41   *                #include "solver/logrel.h"      ascmalloc().
42   *                #include "solver/mtx.h"      This does commit you to being able to stomach the mtx.h file, however,
43   *                #include "general/list.h"      even if you choose to ignore the contents of mtx.
44   *      Several functions, notably the print suite for rel/var names,
45   *  Details on solver parameter definition:      assume you are linking against something that does know about
46   *      ASCEND instances unless the SLV_INSTANCES flag is set to FALSE.
47   *  When used together the parameter-related structures, functions, and  
48   *  macros allow us to define all of a solver's parameters in one file      The parameters and status struct definitions have been moved here,
49   *  and notify the interface of these parameters upon startup (dynamic      being of general interest.
50   *  interface construction).  The parameters can be defined in any order.  
51   *  The only bookkeeping needed is associated with the macros.  You must      SLV common utilities & structures for ASCEND solvers.
52   *  have an array of void pointers large enough for all of the macros      This includes the following:
53   *  you define and you must give each of the macros you define a unique        - parameters struct definitions & manipulation routines
54   *  element of this array. Here is an example using a real parameter        - status struct definitions & retrieval routines
55   *  and a character parameter. (The int and bool are similar to the real).        - vector operations
56   *        - solver print routines
57   *  @code        - lnkmap support functions
58   *      <pre>
59   *  (* these 4 macros can be defined anywhere more or less so long as it      Requires:     #include <stdio.h>
60   *  is before the calls to slv_define_parm. *)                    #include "utilities/ascConfig.h"
61   *  #define REAL_PTR (sys->parm_array[0])                    #include "solver/slv_types.h"
62   *  #define REAL     ((*(real64 *)REAL_PTR))                    #include "solver/rel.h"
63   *  #define CHAR_PTR (sys->parm_array[1])                    #include "solver/logrel.h"
64   *  #define CHAR     ((*(char **)CHAR_PTR))                    #include "solver/mtx.h"
65   *                    #include "general/list.h"
66   *  #define PA_SIZE 2  
67   *  struct example {      Details on solver parameter definition:
68   *    struct slv_parameters_t p;  
69   *    void *parm_array[PA_SIZE];      When used together the parameter-related structures, functions, and
70   *    struct slv_parameter padata[PA_SIZE];      macros allow us to define all of a solver's parameters in one file
71   *  } e;      and notify the interface of these parameters upon startup (dynamic
72   *   ...      interface construction).  The parameters can be defined in any order.
73   *    e.p.parms = padata;      The only bookkeeping needed is associated with the macros.  You must
74   *    e.p.dynamic_parms = 0;      have an array of void pointers large enough for all of the macros
75   *      you define and you must give each of the macros you define a unique
76   *  static char *character_names[] = {      element of this array. Here is an example using a real parameter
77   *     "name_one","name_two"      and a character parameter. (The int and bool are similar to the real).
78   *  }  
79   *    (* fill padata with appropriate info *)      @code
80   *  slv_define_parm(&(e.p), real_parm,  
81   *                  "r_parm","real parameter" ,      (* these 4 macros can be defined anywhere more or less so long as it
82   *                  "this is an example of a real parameter" ,      is before the calls to slv_define_parm. *)
83   *                  U_p_real(val,25),U_p_real(lo,0),U_p_real(hi,100),1);      #define REAL_PTR (sys->parm_array[0])
84   *   (* now assign the element of e.parm_array from somewhere in padata *)      #define REAL     ((*(real64 *)REAL_PTR))
85   *  SLV_RPARM_MACRO(REAL_PTR,parameters);      #define CHAR_PTR (sys->parm_array[1])
86   *      #define CHAR     ((*(char **)CHAR_PTR))
87   *    (* fill padata with appropriate info *)  
88   *  slv_define_parm(&(e.p), char_parm,      #define PA_SIZE 2
89   *                  "c_parm", "character parameter",      struct example {
90   *                  "this is an example of a character parameter",        struct slv_parameters_t p;
91   *                  U_p_string(val,character_names[0]),        void *parm_array[PA_SIZE];
92   *                  U_p_strings(lo,character_names),        struct slv_parameter padata[PA_SIZE];
93   *                  U_p_int(hi,sizeof(character_names)/sizeof(char *)),1);      } e;
94   *   (* now assign the element of e.parm_array that matches. *)       ...
95   *  SLV_CPARM_MACRO(CHAR_PTR,parameters);        e.p.parms = padata;
96   *        e.p.dynamic_parms = 0;
97   *  Resetting the value of a parameter can be done directly  
98   *  except for string parameters which should be set with, for example,      static char *character_names[] = {
99   *  slv_set_char_parameter(CHAR_PTR,newvalue);         "name_one","name_two"
100   *  or outside a solver where there is no sys->parm_array:      }
101   *        (* fill padata with appropriate info *)
102   *     slv_set_char_parameter(&(p.parms[i].info.c.value),argv[j]);      slv_define_parm(&(e.p), real_parm,
103   *                      "r_parm","real parameter" ,
104   *  @endcod                      "this is an example of a real parameter" ,
105   */                      U_p_real(val,25),U_p_real(lo,0),U_p_real(hi,100),1);
106         (* now assign the element of e.parm_array from somewhere in padata *)
107        SLV_RPARM_MACRO(REAL_PTR,parameters);
108    
109          (* fill padata with appropriate info *)
110        slv_define_parm(&(e.p), char_parm,
111                        "c_parm", "character parameter",
112                        "this is an example of a character parameter",
113                        U_p_string(val,character_names[0]),
114                        U_p_strings(lo,character_names),
115                        U_p_int(hi,sizeof(character_names)/sizeof(char *)),1);
116         (* now assign the element of e.parm_array that matches. *)
117        SLV_CPARM_MACRO(CHAR_PTR,parameters);
118    
119        Resetting the value of a parameter can be done directly
120        except for string parameters which should be set with, for example,
121        slv_set_char_parameter(CHAR_PTR,newvalue);
122        or outside a solver where there is no sys->parm_array:
123    
124           slv_set_char_parameter(&(p.parms[i].info.c.value),argv[j]);
125    
126        @endcode
127    */
128    
129  #ifndef ASC_SLV_COMMON_H  #ifndef ASC_SLV_COMMON_H
130  #define ASC_SLV_COMMON_H  #define ASC_SLV_COMMON_H
# Line 141  Line 135 
135    
136  /*  /*
137   * -------------------------------------------------------   * -------------------------------------------------------
138   *  Common data structures for Westerberg derived solvers      Common data structures for Westerberg derived solvers
139   * -------------------------------------------------------   * -------------------------------------------------------
140   */   */
141    
# Line 152  struct slv_output_data { Line 146  struct slv_output_data {
146  };  };
147    
148  /**    /**  
149   *  Solver tolerance data structure.      Solver tolerance data structure.
150   *  @todo KHACK THIS SHOULD BE REMOVED - solver/slv_common:slv_tolerance_data.      @todo KHACK THIS SHOULD BE REMOVED - solver/slv_common:slv_tolerance_data.
151   */   */
152  struct slv_tolerance_data {  struct slv_tolerance_data {
153     real64 drop;         /**< Matrix entry drop tolerance during factorization */     real64 drop;         /**< Matrix entry drop tolerance during factorization */
# Line 190  struct slv_sub_parameters { Line 184  struct slv_sub_parameters {
184  };  };
185    
186  /**  /**
187   *  Data structure for solver statistics.      Data structure for solver statistics.
188   *  This is to collect data for the comparison of algorithms.  All solvers      This is to collect data for the comparison of algorithms.  All solvers
189   *  should have at least one of these, though the interface will check for      should have at least one of these, though the interface will check for
190   *  NULL before reading the data.  The interpretation of these data is      NULL before reading the data.  The interpretation of these data is
191   *  somewhat up to the coder.      somewhat up to the coder.
192   */   */
193  struct slv_block_cost {  struct slv_block_cost {
194    int32 size,             /**< How big is the block, in terms of variables? */    int32 size,             /**< How big is the block, in terms of variables? */
# Line 231  struct slv_real_parameter { Line 225  struct slv_real_parameter {
225    
226  /** Char solver parameter substructure. */  /** Char solver parameter substructure. */
227  struct slv_char_parameter {  struct slv_char_parameter {
228    char *value;            /**< Value. */    char *value;            /**< Selected value. */
229    char **argv;            /**< Lower bound. */    char **argv;            /**< Array of possible values */
230    int32 high;             /**< Upper bound. */    int32 high;             /**< Length of array of possible values. */
231  };  };
232    
233  /** Basic solver parameter types. */  /** Basic solver parameter types. */
# Line 281  struct slv_parameter { Line 275  struct slv_parameter {
275    
276  #define U_p_int(parm_u,val)     ((((parm_u).argi = (val))), (parm_u))  #define U_p_int(parm_u,val)     ((((parm_u).argi = (val))), (parm_u))
277  /**<  /**<
278   *  Sets the argi of parm_arg parm_u to val and returns the parm_u.      Sets the argi of parm_arg parm_u to val and returns the parm_u.
279   *  This macro is used for setting integer parm_arg arguments in calls      This macro is used for setting integer parm_arg arguments in calls
280   *  to slv_define_parm().  parm_u should be one of { val, lo, hi },      to slv_define_parm().  parm_u should be one of { val, lo, hi },
281   *  which correspond to local parm_arg variables that should be used      which correspond to local parm_arg variables that should be used
282   *  in client functions calling slv_define_parm().      in client functions calling slv_define_parm().
283   *   *
284   *  @param parm_u The parm_arg to modify, one of {val, lo, hi}.      @param parm_u The parm_arg to modify, one of {val, lo, hi}.
285   *  @param val    int, the new value for the parm_arg.      @param val    int, the new value for the parm_arg.
286   *  @return Returns parm_u.      @return Returns parm_u.
287   */   */
288  #define U_p_bool(parm_u,val)    ((((parm_u).argb = (val))), (parm_u))  #define U_p_bool(parm_u,val)    ((((parm_u).argb = (val))), (parm_u))
289  /**<  /**<
290   *  Sets the argb of parm_arg parm_u to val and returns the parm_u.      Sets the argb of parm_arg parm_u to val and returns the parm_u.
291   *  This macro is used for setting boolean parm_arg arguments in calls      This macro is used for setting boolean parm_arg arguments in calls
292   *  to slv_define_parm().  parm_u should be one of { val, lo, hi },      to slv_define_parm().  parm_u should be one of { val, lo, hi },
293   *  which correspond to local parm_arg variables that should be used      which correspond to local parm_arg variables that should be used
294   *  in client functions calling slv_define_parm().      in client functions calling slv_define_parm().
295   *   *
296   *  @param parm_u The parm_arg to modify, one of {val, lo, hi}.      @param parm_u The parm_arg to modify, one of {val, lo, hi}.
297   *  @param val    boolean, the new value for the parm_arg.      @param val    boolean, the new value for the parm_arg.
298   *  @return Returns parm_u.      @return Returns parm_u.
299   */   */
300  #define U_p_real(parm_u,val)    ((((parm_u).argr = (val))), (parm_u))  #define U_p_real(parm_u,val)    ((((parm_u).argr = (val))), (parm_u))
301  /**<  /**<
302   *  Sets the argr of parm_arg parm_u to val and returns the parm_u.      Sets the argr of parm_arg parm_u to val and returns the parm_u.
303   *  This macro is used for setting real parm_arg arguments in calls      This macro is used for setting real parm_arg arguments in calls
304   *  to slv_define_parm().  parm_u should be one of { val, lo, hi },      to slv_define_parm().  parm_u should be one of { val, lo, hi },
305   *  which correspond to local parm_arg variables that should be used      which correspond to local parm_arg variables that should be used
306   *  in client functions calling slv_define_parm().      in client functions calling slv_define_parm().
307   *   *
308   *  @param parm_u The parm_arg to modify, one of {val, lo, hi}.      @param parm_u The parm_arg to modify, one of {val, lo, hi}.
309   *  @param val    double, the new value for the parm_arg.      @param val    double, the new value for the parm_arg.
310   *  @return Returns parm_u.      @return Returns parm_u.
311   */   */
312  #define U_p_string(parm_u,val)  ((((parm_u).argc = (val))), (parm_u))  #define U_p_string(parm_u,val)  ((((parm_u).argc = (val))), (parm_u))
313  /**<  /**<
314   *  Sets the argc of parm_arg parm_u to val and returns the parm_u.      Sets the argc of parm_arg parm_u to val and returns the parm_u.
315   *  This macro is used for setting string parm_arg arguments in calls      This macro is used for setting string parm_arg arguments in calls
316   *  to slv_define_parm().  parm_u should be one of { val, lo, hi },      to slv_define_parm().  parm_u should be one of { val, lo, hi },
317   *  which correspond to local parm_arg variables that should be used      which correspond to local parm_arg variables that should be used
318   *  in client functions calling slv_define_parm().      in client functions calling slv_define_parm().
319   *   *
320   *  @param parm_u The parm_arg to modify, one of {val, lo, hi}.      @param parm_u The parm_arg to modify, one of {val, lo, hi}.
321   *  @param val    char *, the new value for the parm_arg.      @param val    char *, the new value for the parm_arg.
322   *  @return Returns parm_u.      @return Returns parm_u.
323   *  For use in calls to slv_define_parm().      For use in calls to slv_define_parm().
324   */   */
325  #define U_p_strings(parm_u,val) ((((parm_u).argv = (val))), (parm_u))  #define U_p_strings(parm_u,val) ((((parm_u).argv = (val))), (parm_u))
326  /**<  /**<
327   *  Sets the argv of parm_arg parm_u to val and returns the parm_u.      Sets the argv of parm_arg parm_u to val and returns the parm_u.
328   *  This macro is used for setting string array parm_arg arguments in      This macro is used for setting string array parm_arg arguments in
329   *  calls to slv_define_parm().  parm_u should be one of { val, lo, hi },      calls to slv_define_parm().  parm_u should be one of { val, lo, hi },
330   *  which correspond to local parm_arg variables that should be used      which correspond to local parm_arg variables that should be used
331   *  in client functions calling slv_define_parm().      in client functions calling slv_define_parm().
332   *   *
333   *  @param parm_u The parm_arg to modify, one of {val, lo, hi}.      @param parm_u The parm_arg to modify, one of {val, lo, hi}.
334   *  @param val    char **, the new value for the parm_arg.      @param val    char **, the new value for the parm_arg.
335   *  @return Returns parm_u.      @return Returns parm_u.
336   *  For use in calls to slv_define_parm().      For use in calls to slv_define_parm().
337   */   */
338    
339  #define SLV_IPARM_MACRO(NAME,slv_parms) \  #define SLV_IPARM_MACRO(NAME,slv_parms) \
# Line 347  struct slv_parameter { Line 341  struct slv_parameter {
341       (NAME)  = &((slv_parms)->parms[(slv_parms)->num_parms-1].info.i.value); \       (NAME)  = &((slv_parms)->parms[(slv_parms)->num_parms-1].info.i.value); \
342    }    }
343  /**<  /**<
344   *  Macro for defining macros of type integer (IPARM).      Macro for defining macros of type integer (IPARM).
345   *  See SLV_CPARM_MACRO() for more information.      See SLV_CPARM_MACRO() for more information.
346   */   */
347  #define SLV_BPARM_MACRO(NAME,slv_parms) \  #define SLV_BPARM_MACRO(NAME,slv_parms) \
348    if (make_macros == 1) {  \    if (make_macros == 1) {  \
349       (NAME)  = &((slv_parms)->parms[(slv_parms)->num_parms-1].info.b.value); \       (NAME)  = &((slv_parms)->parms[(slv_parms)->num_parms-1].info.b.value); \
350    }    }
351  /**<  /**<
352   *  Macro for defining macros of type boolean (BPARM).      Macro for defining macros of type boolean (BPARM).
353   *  See SLV_CPARM_MACRO() for more information.      See SLV_CPARM_MACRO() for more information.
354   */   */
355  #define SLV_RPARM_MACRO(NAME,slv_parms) \  #define SLV_RPARM_MACRO(NAME,slv_parms) \
356    if (make_macros == 1) {  \    if (make_macros == 1) {  \
357       (NAME)  = &((slv_parms)->parms[(slv_parms)->num_parms-1].info.r.value); \       (NAME)  = &((slv_parms)->parms[(slv_parms)->num_parms-1].info.r.value); \
358    }    }
359  /**<  /**<
360   *  Macro for defining macros of type real (RPARM).      Macro for defining macros of type real (RPARM).
361   *  See SLV_CPARM_MACRO() for more information.      See SLV_CPARM_MACRO() for more information.
362   */   */
363  #define SLV_CPARM_MACRO(NAME,slv_parms) \  #define SLV_CPARM_MACRO(NAME,slv_parms) \
364    if (make_macros == 1) {  \    if (make_macros == 1) {  \
# Line 385  struct slv_parameter { Line 379  struct slv_parameter {
379   */   */
380    
381  /**  /**
382   *  Holds the array of parameters and keeps a count of how many it      Holds the array of parameters and keeps a count of how many it
383   *  contains.  Also holds various other information which should be      contains.  Also holds various other information which should be
384   *  turned into slv_parameters or moved elsewhere      turned into slv_parameters or moved elsewhere
385   *  <pre>      <pre>
386   *  Every registered client should have a slv_parameters_t somewhere in it.      Every registered client should have a slv_parameters_t somewhere in it.
387   *  
388   *  The following is a list of parameters (those parameters that can be      The following is a list of parameters (those parameters that can be
389   *  modified during solve without calling slv_presolve() are marked with      modified during solve without calling slv_presolve() are marked with
390   *  "$$$").  It should be noted that some solvers may not be conformable      "$$$").  It should be noted that some solvers may not be conformable
391   *  to some of the parameters.  Default values are subject to change via      to some of the parameters.  Default values are subject to change via
392   *  experimentation.      experimentation.
393   *  
394   *  output.more_important (default stdout):   $$$      output.more_important (default stdout):   $$$
395   *  output.less_important (default NULL):     $$$      output.less_important (default NULL):     $$$
396   *     All output from the solver is written to one of these two files         All output from the solver is written to one of these two files
397   *     (except bug messages which are written to stderr).  Common values         (except bug messages which are written to stderr).  Common values
398   *     are NULL (==> no file) and stdout.  The more important messages         are NULL (==> no file) and stdout.  The more important messages
399   *     go to output.more_important and less important messages go to         go to output.more_important and less important messages go to
400   *     output.less_important.  To shut the solver up, set both files to         output.less_important.  To shut the solver up, set both files to
401   *     NULL.         NULL.
402   *  
403   *  tolerance.drop         (default 1e-16):      tolerance.drop         (default 1e-16):
404   *  tolerance.pivot        (default 0.1):      tolerance.pivot        (default 0.1):
405   *  tolerance.singular     (default 1e-12):      tolerance.singular     (default 1e-12):
406   *  tolerance.feasible     (default 1e-8):      tolerance.feasible     (default 1e-8):
407   *  tolerance.rootfind     (default 1e-12):      tolerance.rootfind     (default 1e-12):
408   *  tolerance.stationary   (default 1e-8):      tolerance.stationary   (default 1e-8):
409   *  tolerance.termination  (default 1e-12):      tolerance.termination  (default 1e-12):
410   *     These define the criterion for selecting pivotable relations,         These define the criterion for selecting pivotable relations,
411   *     whether the equations are satisfied, if a local minimum has been         whether the equations are satisfied, if a local minimum has been
412   *     found, or if no further reduction in the augmented lagrange merit         found, or if no further reduction in the augmented lagrange merit
413   *     phi can be achieved.         phi can be achieved.
414   *   - During jacobian reduction, each equation pivot selected must be       - During jacobian reduction, each equation pivot selected must be
415   *     at least a certain fraction given by TOLERANCE.PIVOT of the largest         at least a certain fraction given by TOLERANCE.PIVOT of the largest
416   *     available.         available.
417   *     Also, the largest value in the row must exceed TOLERANCE.SINGULAR         Also, the largest value in the row must exceed TOLERANCE.SINGULAR
418   *     in order to be considered independent.         in order to be considered independent.
419   *   - The absolute value of each unscaled equation residual is compared       - The absolute value of each unscaled equation residual is compared
420   *     with TOLERANCE.FEASIBLE in order to determine convergence of the         with TOLERANCE.FEASIBLE in order to determine convergence of the
421   *     equality constraints during Newton iteration.         equality constraints during Newton iteration.
422   *   - The absolute value of each unscaled equation residual is compared       - The absolute value of each unscaled equation residual is compared
423   *     with TOLERANCE.ROOTFIND in order to determine convergence of the         with TOLERANCE.ROOTFIND in order to determine convergence of the
424   *     constraint during rootfinding of single equations.         constraint during rootfinding of single equations.
425   *   - Detection of a minimum requires the stationary condition of the       - Detection of a minimum requires the stationary condition of the
426   *     lagrange to be less than TOLERANCE.STATIONARY.         lagrange to be less than TOLERANCE.STATIONARY.
427   *   - If the directional derivative of phi along the negative gradient       - If the directional derivative of phi along the negative gradient
428   *     direction using the suggested iteration step length falls below         direction using the suggested iteration step length falls below
429   *     TOLERANCE.TERMINATION, iteration is ceased.         TOLERANCE.TERMINATION, iteration is ceased.
430   *   - TOLERANCE.DROP is the smallest number magnitude to be allowed       - TOLERANCE.DROP is the smallest number magnitude to be allowed
431   *     in the Jacobian matrix during factorization. Default is optimistic.         in the Jacobian matrix during factorization. Default is optimistic.
432   *  
433   *  time_limit (default 30.0):   $$$      time_limit (default 30.0):   $$$
434   *     This defines the time limit expressed as cpu seconds per block.         This defines the time limit expressed as cpu seconds per block.
435   *     If the solver requires more time than this in any given block,         If the solver requires more time than this in any given block,
436   *     then it will stop.         then it will stop.
437   *  
438   *  iteration_limit (default 100):   $$$      iteration_limit (default 100):   $$$
439   *     This defines the maximum number of iterations attempted in a given         This defines the maximum number of iterations attempted in a given
440   *     block.  The solver will stop after this many iterations if it fails         block.  The solver will stop after this many iterations if it fails
441   *     to converge.         to converge.
442   *  
443   *  factor_option (default 0):      factor_option (default 0):
444   *     This sets the number of the linear factorization to suggest.         This sets the number of the linear factorization to suggest.
445   *     This does not map directly to linsol numbering of any sort.         This does not map directly to linsol numbering of any sort.
446   *     The map is: 0 <==> RANKI, 1 <==> RANKI_JZ, 2+ <==> ?.         The map is: 0 <==> RANKI, 1 <==> RANKI_JZ, 2+ <==> ?.
447   *     The solver is free to ignore this suggestion.         The solver is free to ignore this suggestion.
448   *     In fact, the specific solver is free to define the meaning of factor         In fact, the specific solver is free to define the meaning of factor
449   *     option depending on what linear packages it can talk to.         option depending on what linear packages it can talk to.
450   *  
451   *  partition (default TRUE):      partition (default TRUE):
452   *     Specifies whether or not the system will be partitioned into blocks         Specifies whether or not the system will be partitioned into blocks
453   *     or not.  If not, then the system will be considered as one large         or not.  If not, then the system will be considered as one large
454   *     block.         block.
455   *  
456   *  ignore_bounds (default FALSE):      ignore_bounds (default FALSE):
457   *     Specifies whether or not bounds will be considered during solving.         Specifies whether or not bounds will be considered during solving.
458   *     WARNING: if this flag is set, there will be no guarantees that the         WARNING: if this flag is set, there will be no guarantees that the
459   *     solution will lie in bounds.  Suggested use might be to set this         solution will lie in bounds.  Suggested use might be to set this
460   *     flag to TRUE, solve, reset this flag to FALSE, and resolve.         flag to TRUE, solve, reset this flag to FALSE, and resolve.
461   *     More often than not, in fact, ignore bounds will lead to floating         More often than not, in fact, ignore bounds will lead to floating
462   *     point exceptions, halting the solution process.         point exceptions, halting the solution process.
463   *  
464   *  rho (default 1.0):      rho (default 1.0):
465   *     Used as a scalar pre-multiplier of the penalty term quantified by one         Used as a scalar pre-multiplier of the penalty term quantified by one
466   *     half the two norm of the equality constraint residuals in an         half the two norm of the equality constraint residuals in an
467   *     augmented lagrange merit function.         augmented lagrange merit function.
468   *  
469   *  sp.ia/ra/ca/vap (defaults NULL, READ ONLY):      sp.ia/ra/ca/vap (defaults NULL, READ ONLY):
470   *     Is a set of pointers to arrays (int/double/(char*)/void*).         Is a set of pointers to arrays (int/double/(char*)/void*).
471   *     The values of the pointers themselves should not be modified,         The values of the pointers themselves should not be modified,
472   *     though the values pointed at may be modified. Note that this is         though the values pointed at may be modified. Note that this is
473   *     _direct_ modification and will take effect immediately, not on         _direct_ modification and will take effect immediately, not on
474   *     the next call to slv_set_parameters. When the engine gets around         the next call to slv_set_parameters. When the engine gets around
475   *     to looking at the values in these arrays is engine dependent.         to looking at the values in these arrays is engine dependent.
476   *     NULL is the expected value for some or all of these array         NULL is the expected value for some or all of these array
477   *     pointers, depending on the engine. The sizes of these arrays are         pointers, depending on the engine. The sizes of these arrays are
478   *     specific to each solver's interface. As being of interest (at         specific to each solver's interface. As being of interest (at
479   *     compile time) to both the slvI.c file and the GUI/CLUI, the         compile time) to both the slvI.c file and the GUI/CLUI, the
480   *     sizes of the arrays to be pointed to are part of the slvI.h file.         sizes of the arrays to be pointed to are part of the slvI.h file.
481   *     The implementor of each slvI.c should take care to use as much of         The implementor of each slvI.c should take care to use as much of
482   *     the slv_parameters_t as possible before passing data through the         the slv_parameters_t as possible before passing data through the
483   *     arrays provided in the sub_parameters. This will make for a         arrays provided in the sub_parameters. This will make for a
484   *     minimal amount of work when adding an engine to the GUI/CLUI.         minimal amount of work when adding an engine to the GUI/CLUI.
485   *     To further aid reusability/sanity preservation, slvI.h should         To further aid reusability/sanity preservation, slvI.h should
486   *     be appended with proper defines for subscripting these arrays.         be appended with proper defines for subscripting these arrays.
487   *  
488   *  sp.i/r/c/vlen (defaults 0, READ ONLY)      sp.i/r/c/vlen (defaults 0, READ ONLY)
489   *     lengths of the sub_parameter arrays.         lengths of the sub_parameter arrays.
490   *  
491   *  sp.ia/ra/ca/vanames (defaults NULL, READONLY)      sp.ia/ra/ca/vanames (defaults NULL, READONLY)
492   *     symbolic names for the corresponding entries in ia/ra/ca/vap.         symbolic names for the corresponding entries in ia/ra/ca/vap.
493   *  
494   *  sp.ia/ra/ca/vaexpln (defaults NULL, READONLY)      sp.ia/ra/ca/vaexpln (defaults NULL, READONLY)
495   *     longer explanations for the corresponding entries in ia/ra/ca/vap.         longer explanations for the corresponding entries in ia/ra/ca/vap.
496   *  
497   *  whose (default 0=>slv0, READ ONLY)      whose (default 0=>slv0, READ ONLY)
498   *     This tells where a parameter set came from, since the default         This tells where a parameter set came from, since the default
499   *     action of slv_get_parameters is to return a copy of slv0's         action of slv_get_parameters is to return a copy of slv0's
500   *     parameters if the parameters asked for don't exist because         parameters if the parameters asked for don't exist because
501   *     the solver in question wasn't built/linked.         the solver in question wasn't built/linked.
502   *  </pre>      </pre>
503   */   */
504  typedef struct slv_parameters_structure {  typedef struct slv_parameters_structure {
505     struct slv_output_data output;       /**< File streams for solver output. */     struct slv_output_data output;       /**< File streams for solver output. */
# Line 532  typedef struct slv_parameters_structure Line 526  typedef struct slv_parameters_structure
526  /* slv_destroy_parms() is defined in slv.c */  /* slv_destroy_parms() is defined in slv.c */
527  extern void slv_destroy_parms(slv_parameters_t *p);  extern void slv_destroy_parms(slv_parameters_t *p);
528  /**<  /**<
529   *  Deallocates any allocated memory held by a parameter structure.      Deallocates any allocated memory held by a parameter structure.
530   *  Only the held memory is freed, not p itself.  Further, if      Only the held memory is freed, not p itself.  Further, if
531   *  (p->dynamic_parms != 0), the strings in p->parms are freed      (p->dynamic_parms != 0), the strings in p->parms are freed
532   *  but not p->parms itself.  Does nothing if p is NULL.      but not p->parms itself.  Does nothing if p is NULL.
533   *  
534   *  @param p  The parameter structure to destroy.      @param p  The parameter structure to destroy.
535   */   */
536    
537  /* slv_define_parm() is defined in slv.c */  /* slv_define_parm() is defined in slv.c */
# Line 551  extern int32 slv_define_parm(slv_paramet Line 545  extern int32 slv_define_parm(slv_paramet
545                               union parm_arg upper_bound,                               union parm_arg upper_bound,
546                               int32 page);                               int32 page);
547  /**<  /**<
548   *  Adds (defines) a new parameter in a parameter structure.      Adds (defines) a new parameter in a parameter structure.
549   *  Use this function to add & define new parameters for a solver.      Use this function to add & define new parameters for a solver.
550   *  
551   *  @param p                Parameter structure to receive the new parameter.      @param p                Parameter structure to receive the new parameter.
552   *  @param type             Parameter type: int_parm, bool_parm, real_parm, or char_parm.      @param type             Parameter type: int_parm, bool_parm, real_parm, or char_parm.
553   *  @param interface_name   A very short but descriptive name that the interface      @param interface_name   A very short but descriptive name that the interface
554   *                          can use to identify the parameter.                              can use to identify the parameter.
555   *  @param interface_label  A short text string to be displayed on the interface.      @param interface_label  A short text string to be displayed on the interface.
556   *  @param description      A slightly more detailed string to be displayed      @param description      A slightly more detailed string to be displayed
557   *                          upon request a la balloon help.                              upon request a la balloon help.
558   *  @param value            The value for the parameter, set using one of      @param value            The value for the parameter, set using one of
559   *                          the U_p_int() style macros defined above.                              the U_p_int() style macros defined above.
560   *  @param lower_bound      The lower bound for the parameter, set using one of      @param lower_bound      The lower bound for the parameter, set using one of
561   *                          the U_p_int() style macros defined above.                              the U_p_int() style macros defined above.
562   *  @param upper_bound      The upper bound for the parameter, set using one of      @param upper_bound      The upper bound for the parameter, set using one of
563   *                          the U_p_int() style macros defined above.                              the U_p_int() style macros defined above.
564   *  @param page             The page of the interface options dialog on which      @param page             The page of the interface options dialog on which
565   *                          to display this parameter.  Ranges from 1..max_page_no.                              to display this parameter.  Ranges from 1..max_page_no.
566   *                          Set to -1 if this parameter is not to be displayed in                              Set to -1 if this parameter is not to be displayed in
567   *                          the interface.                              the interface.
568   *  @return Returns -1 if p is NULL or called with unsupported type;      @return Returns -1 if p is NULL or called with unsupported type;
569   *          otherwise returns the number of registered parameters in p.              otherwise returns the number of registered parameters in p.
570   */   */
571    
572  /* slv_set_char_parameter() is defined in slv.c */  /* slv_set_char_parameter() is defined in slv.c */
573  extern void slv_set_char_parameter(char **cptr, char *newvalue);  extern void slv_set_char_parameter(char **cptr, char *newvalue);
574  /**<  /**<
575   *  Sets a char parameter value to a new string.      Sets a char parameter value to a new string.
576   *  Resetting the value of a parameter can be done directly except      Resetting the value of a parameter can be done directly except
577   *  for string parameters which must be set with this function.  The      for string parameters which must be set with this function.  The
578   *  string newvalue is not kept by the function.<br><br>      string newvalue is not kept by the function.<br><br>
579   *  
580   *  Example:   slv_set_char_parameter(&(p.parms[i].info.c.value),argv[j]);      Example:   slv_set_char_parameter(&(p.parms[i].info.c.value),argv[j]);
581   *  
582   *  @param cptr     Pointer to the char array to set.      @param cptr     Pointer to the char array to set.
583   *  @param newvalue New value for *cptr.      @param newvalue New value for *cptr.
584   */   */
585    
586  /** Solver block status record. */  /** Solver block status record. */

Legend:
Removed from v.221  
changed lines
  Added in v.222

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