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

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

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

revision 125 by johnpye, Wed Nov 30 16:31:29 2005 UTC revision 126 by johnpye, Tue Dec 20 13:27:11 2005 UTC
# Line 1  Line 1 
1  /*  /*
2   *  SLV: Ascend Nonlinear Solver      SLV: Ascend Nonlinear Solver
3   *  by Karl Michael Westerberg      Copyright (C) 1990 Karl Michael Westerberg
4   *  Created: 2/6/90      Copyright (C) 1993 Joseph Zaher
5   *  Version: $Revision: 1.35 $      Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan
6   *  Version control file: $RCSfile: slv_client.h,v $      Copyright (C) 1996 Benjamin Andrew Allan
7   *  Date last modified: $Date: 1998/04/25 13:01:56 $      Copyright (C) 2005 The ASCEND developers
8   *  Last modified by: $Author: ballan $  
9   *      This program is free software; you can redistribute it and/or modify
10   *  This file is part of the SLV solver.      it under the terms of the GNU General Public License as published by
11   *      the Free Software Foundation; either version 2 of the License, or
12   *  Copyright (C) 1990 Karl Michael Westerberg      (at your option) any later version.
13   *  Copyright (C) 1993 Joseph Zaher  
14   *  Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan      This program is distributed in the hope that it will be useful,
15   *  Copyright (C) 1996 Benjamin Andrew Allan      but WITHOUT ANY WARRANTY; without even the implied warranty of
16   *      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17   *  The SLV solver is free software; you can redistribute      GNU General Public License for more details.
18   *  it and/or modify it under the terms of the GNU General Public License as  
19   *  published by the Free Software Foundation; either version 2 of the      You should have received a copy of the GNU General Public License
20   *  License, or (at your option) any later version.      along with this program; if not, write to the Free Software
21   *                                                            Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
22   *  The SLV solver is distributed in hope that it will be      This file is part of the SLV solver.
23   *  useful, but WITHOUT ANY WARRANTY; without even the implied warranty of  */
  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  
  *  General Public License for more details.  
  *  
  *  You should have received a copy of the GNU General Public License  
  *  along with the program; if not, write to the Free Software Foundation,  
  *  Inc., 675 Mass Ave, Cambridge, MA 02139 USA.  Check the file named  
  *  COPYING.  COPYING is found in ../compiler.  
  */  
   
 /** @file  
  *  SLV general interface for solver clients, etc.  
  *  <pre>  
  *  By Ben Allan  
  *  
  *  Copyright(C) Karl Westerberg, Joseph Zaher, Benjamin Allan 1994  
  *  Copyright(C) Benjamin Andrew Allan 1996  
  *  
  *  ASCEND (the language) exists to separate, when desirable, the  
  *  formulation of a mathematical problem (numeric) from the solution of  
  *  the that problem. ASCEND (the interface) exists to give the user as  
  *  much (or as little) control over the compilation and solution of their  
  *  problem as they want.  
  *  
  *  The problems expressible in the language cannot (and indeed should not)  
  *  be reduced to a single formulation if the solutions are to be  
  *  implemented in a robust, efficient, and user controllable manner.  
  *  All but one of the solving engines attached to ASCEND must inevitably  
  *  be hamstrung if we insist that they all fit in the same interface shoebox.  
  *  Witness the minos/lsode implementations in the Pascal-version. The  
  *  alternative is to make all engines talk through an interface defined  
  *  by the intersection of the engines' individual interfaces. This  
  *  alternative is unacceptable from a software engineering point of view.  
  *  
  *  This portion of the interface, then, has the task of making every  
  *  engine conform to a minimum set of semantics (thus enabling the GUI/  
  *  CLUI to support the user wanting very little control over a host of  
  *  powerful solving engines) while giving the power hungry user access  
  *  to those parameters specific to a given engine.  
  *  The minimum semantics chosen, due mostly to convenience and the biases  
  *  of the developers, are those of slv0 with the provision of a set of  
  *  arrays for the passing of auxillary, or 'sub', parameters to each  
  *  solver.  
  *  The data structures we desire to have common to all the solvers are  
  *  kept in slv_common.h (or .c).  
  *  The functions the UI are kept here.  
  *  
  *--------------------------------------------------------------------------  
  *  
  *  Contents:     Solver module  
  *  
  *  Authors:      Karl Westerberg  
  *                Joseph Zaher  
  *                Benjamin Allan  
  *  
  *  Dates:        06/90 - original version  
  *                01/94 - modified tolerances, eliminated var_to_name  
  *                        and rel_to_name function pointers, and  
  *                        expanded status report  
  *                04/94 - expanded scope of slv0 to perform optimization  
  *                05/94 - added counting routines to count variables,  
  *                        boundaries, and relations which pass some  
  *                        specified filter  
  *                10/94 - added stubs for OPT and QRSlv  
  *                1/95  - moved status and parameters definitions to  
  *                        slv_common.h. BAA  
  *                02/96 - added stubs for NGSlv. KTH  
  *                06/96 - split into client and server headers.  
  *                0/97 - added stubs for CONOPT. KTH  
  *  
  *  Description:  The inputs to any solver consist of a formulation of  
  *                the problem to solve along with a set of parameters to  
  *                allow user control of the solution process.  The  
  *                general formulation is given below (for non-discrete  
  *                problems only):  
  *  
  *                         min F(x,u,c)  
  *  
  *                   s.t.  h(x,u,c) = 0  
  *                         r(x,u,c) = 0  
  *                         g(x,u,c) >= 0  
  *                         b(x,u,c) >= 0  
  *  
  *                A variable list consists of fixed (c), independent (u),  
  *                dependent variables (x), and unattached variables (q).  
  *                A relation list consists of unconditional (or global)  
  *                equality constraints (h), conditional equality  
  *                constraints (r), and inequality constraints (g), each of  
  *                type struct rel_relation *.  The conditional equalities are  
  *                isolated from the global equalities because they are only  
  *                defined for certain ranges in values of the variables,  
  *                expressed through a set of inequality boundary relations  
  *                (b), each of type bnd_boundary_t which may or may not  
  *                be satisfied at any given point.  An objective function  
  *                (F) is used to provide a criteria with which to  
  *                optimize the values of the independent variables.  
  *  
  *                The objective function is a relation (LHS only)  
  *                struct rel_relation * and may be set (its default is NULL)  
  *                using slv_set_obj_relation.  The variable, boundary, and  
  *                relation lists are pointer lists of  
  *                struct var_variable * and struct rel_relation * and  
  *                are expected to be NULL terminated.  This means that for  
  *                10 variables to be placed in a list, for example, 11  
  *                elements must exist in order to reserve the last pointer  
  *                to be NULL.  These lists ARE REQUIRED to be set.  
  *  
  *                The additional set of inputs are the slv_parameters.  
  *                These can specify stopping conditions or the amount of  
  *                information displayed during solving, for example.  
  *                Monitoring of the solution process is done using the  
  *                status report for solvers that iterate.  
  *                More details are given with the  
  *                respective declarations below.  
  *  
  *  Requires:     #include "utilities/ascConfig.h"  
  *                #include "compiler/instance_enum.h"  
  *                #include "var.h"  
  *                #include "rel.h"  
  *                #include "discrete.h"  
  *                #include "conditional.h"  
  *                #include "logrel.h"  
  *                #include "bnd.h"  
  *                #include "linsol.h"  
  *                #include "linsolqr.h"  
  *                #include "slv_common.h"  
  *                #include "slv_types.h"  
  *  </pre>  
  *  @todo Reformat file comments?  
  *  
  *--------------------------------------------------------------------------  
  *  
  *  Right, so we're going to have a client-server, object-oriented,  
  *  open-architecture system designed to handle multiple clients in a  
  *  single-thread process. Furthermore, the clients will NOT have to  
  *  know anything at all about the ASCEND IV compiler hidden out back  
  *  some place -- in fact our compiler may not BE out back, it may be  
  *  on another machine or swapped to disk or whatever.  
  *  
  *  That's the ideal. In most applications of ASCEND, particularly the  
  *  interactive one, the compiler is never very far away. Isolating the  
  *  compiler data completely (meaning no looking back at it for anything)  
  *  would mean recreating all the relations (be they tokens, calls to  
  *  C code, or any kind) in a separate process. This is unacceptable from  
  *  a memory conservation point of view until RAM comes down to ~$1/MByte,  
  *  especially if ASCEND is to run on PCs any time soon.  
  *  
  *  What we really have then is a slv_system_t made up of variables and  
  *  relations and hiding all the compiler details from the clients.  
  *  Clients will operate directly on the slv_system_t only through real  
  *  C functions and not through macros so we can hide all the nasty  
  *  details about the compiler. Variables and relations only make  
  *  sense in the context of a slv_system_t, so the var_variable type  
  *  and the rel_relation type in this C code sometimes require that  
  *  the system pointer be provided when asking for certain properties  
  *  or services.  
  *  
  *  Q: What is a variable?  
  *  A: The question is ambiguous. In ASCEND we have the notion of a  
  *     solver_var ATOM type that includes bounding values, a scaling  
  *     value, and other properties. These are not the only real-number  
  *     based items that can occur, however. For purposes of the CLIENT  
  *     application programming interface (API) we collect all the real-  
  *     based objects we can find and map them all to struct var_variable.  
  *     See var.h for details. We sort them into lists as follows:  
  *       - vars.  These are solver_var that are in an objective or relation.  
  *       - pars.  These are solver_par appearing parametrically.  
  *       - unattached.  These don't appear in relation or objective, and  
  *                      they may be solver_var or solver_par or neither.  
  *     We keep 2 versions of each list: one for ourselves which is READ-  
  *     ONLY for clients and allows us to do many things efficiently, and  
  *     another for clients that clients may rearrange (or even delete)  
  *     as suits their needs. The former version is called a master list,  
  *     and the latter version is called a solvers list.  
  *  
  *   Q: What is a relation?  
  *   A: At present a relation in ASCEND is either an objective function  
  *      (a one-sided relation) or a constraining equation. We have a  
  *      variety of relation implementations within ASCEND, but all any  
  *      client needs to know about relations can be found in the rel.h  
  *      file. We keep master and client lists of relations as well.  
  *      We provide a variety of interesting services with relations:  
  *         residual and gradient calculations  
  *         symbolic inversion (where possible)  
  *         numeric root finding  
  *         scaling based on symbolic arguments  
  *         symbolic determination of linearity  
  *      and we expect to add others as they occur to us or you suggest  
  *      them.  
  *  
  *   Q: What else is a slv_system_t?  
  *   A: It's has a host of interesting properties.  
  *   1) One slv_system_t (system, hereafter) can only be used by one  
  *      -----------------         registered           -------------  
  *      client at a time, but if your client is an unregistered manager  
  *      of several subclients (for example an NLP code and and MILP code)  
  *      then you can pass it back and forth to those registered clients to solve  
  *      an MINLP. (Note: we haven't done this ourselves yet.)  
  *      Any number of unregistered clients may share a system, but they  
  *      must take responsibility for not stepping on each other or the  
  *      registered client. Registration will be explained further below.  
  *   2) From any given ASCEND type definitions, the master lists in the  
  *      system will be ordered identically across all invocations of  
  *      ASCEND on any hardware that we are aware of. This property is  
  *      derived from the way we compile instances and create systems.  
  *      This is helpful in benchmarking and other applications.  
  *   3) We have a number of standard clients (registered and not)  
  *      you can use on a the system to precondition it in some way for  
  *      your client:  
  *        - Degrees of freedom analysis.  
  *        - Problem decomposition.  
  *        - Reordering of vars and rels for good factorization.  
  *        - Solution of square nonlinear systems.  
  *        - Generation of MPS code for popular MILP solvers.  
  *        - Generation of GAMS code for an old, slow compiler of an  
  *          extremely awkward modeling language that does happen to  
  *          have a lot of really good optimizers connected.  
  *  
  *  Future work:  
  *  Short term --  
  *  We expect to construct a client that takes the partitioned  
  *  problem and hands off the blocks in sequence to one or more  
  *  solvers designed to handle only 1 block.  
  *  
  *  Long term --  
  *  We anticipate that the structure laid out so far is capable of  
  *  expansion (probably by intermediate clients which add additional  
  *  semantic content) to provide standardized (mtx and harwellian)  
  *  sparse matrix support and memory management for codes that don't  
  *  care to think about such things directly.  
  *  
  *  PLEASE NOTE  
  *  
  ! !  We are going through a solver API definition restructuring.  
  ! !  The appearance of ! ! in the header means the code in question  
  ! !  has, or is about to have, a change in its meaning or is code that  
  ! !  is new and replaces some or all the functionality of an old  
  ! !  function definition. Basically, expect to have to read ! ! sections  
  ! !  carefully and maybe patch calls dependent on them.  
  */  
24    
25  #ifndef ASC_SLV_CLIENT_H  #ifndef ASC_SLV_CLIENT_H
26  #define ASC_SLV_CLIENT_H  #define ASC_SLV_CLIENT_H
27    
28    /** @file
29        @see slv
30    
31        Requires:
32        #include "utilities/ascConfig.h"
33        #include "compiler/instance_enum.h"
34        #include "var.h"
35        #include "rel.h"
36        #include "discrete.h"
37        #include "conditional.h"
38        #include "logrel.h"
39        #include "bnd.h"
40        #include "linsol.h"
41        #include "linsolqr.h"
42        #include "slv_common.h"
43        #include "slv_types.h"
44    
45    */
46    
47    /** @page slv SLV Solver Interface
48    
49        ASCEND (the language) exists to separate, when desirable, the
50        formulation of a mathematical problem (numeric) from the solution of
51        the that problem. ASCEND (the interface) exists to give the user as
52        much (or as little) control over the compilation and solution of their
53        problem as they want. @par
54        
55        The problems expressible in the language cannot (and indeed should not)
56        be reduced to a single formulation if the solutions are to be
57        implemented in a robust, efficient, and user controllable manner.
58        All but one of the solving engines attached to ASCEND must inevitably
59        be hamstrung if we insist that they all fit in the same interface shoebox.
60        Witness the minos/lsode implementations in the Pascal-version. The
61        alternative is to make all engines talk through an interface defined
62        by the intersection of the engines' individual interfaces. This
63        alternative is unacceptable from a software engineering point of view. @par
64        
65        This portion of the interface, then, has the task of making every
66        engine conform to a minimum set of semantics (thus enabling the GUI/
67        CLUI to support the user wanting very little control over a host of
68        powerful solving engines) while giving the power hungry user access
69        to those parameters specific to a given engine.
70        The minimum semantics chosen, due mostly to convenience and the biases
71        of the developers, are those of slv0 with the provision of a set of
72        arrays for the passing of auxillary, or 'sub', parameters to each
73        solver. @par
74    
75        @see slv_common.h for the data structures we desire to have common to all the solvers.
76        
77        <pre>
78        Dates:        06/90 - original version KMW
79                      01/94 - modified tolerances, eliminated var_to_name
80                              and rel_to_name function pointers, and
81                              expanded status report
82                      04/94 - expanded scope of slv0 to perform optimization
83                      05/94 - added counting routines to count variables,
84                              boundaries, and relations which pass some
85                              specified filter
86                      10/94 - added stubs for OPT and QRSlv
87                      1/95  - moved status and parameters definitions to
88                              slv_common.h. BAA
89                      02/96 - added stubs for NGSlv. KTH
90                      06/96 - split into client and server headers.
91                      0/97 - added stubs for CONOPT. KTH
92        </pre>
93    
94        @section desc Description
95        
96        The inputs to any solver consist of a formulation of
97        the problem to solve along with a set of parameters to
98        allow user control of the solution process.  The
99        general formulation is given below (for non-discrete
100        problems only):
101    
102        @code
103                min F(x,u,c)
104    
105            s.t.  h(x,u,c) = 0
106                r(x,u,c) = 0
107                g(x,u,c) >= 0
108                b(x,u,c) >= 0
109        @endcode
110    
111        A variable list consists of fixed (c), independent (u),
112        dependent variables (x), and unattached variables (q).
113        A relation list consists of unconditional (or global)
114        equality constraints (h), conditional equality
115        constraints (r), and inequality constraints (g), each of
116        type struct rel_relation *.  The conditional equalities are
117        isolated from the global equalities because they are only
118        defined for certain ranges in values of the variables,
119        expressed through a set of inequality boundary relations
120        (b), each of type bnd_boundary_t which may or may not
121        be satisfied at any given point.  An objective function
122        (F) is used to provide a criteria with which to
123        optimize the values of the independent variables. @par
124    
125        The objective function is a relation (LHS only)
126        struct rel_relation * and may be set (its default is NULL)
127        using slv_set_obj_relation.  The variable, boundary, and
128        relation lists are pointer lists of
129        struct var_variable * and struct rel_relation * and
130        are expected to be NULL terminated.  This means that for
131        10 variables to be placed in a list, for example, 11
132        elements must exist in order to reserve the last pointer
133        to be NULL.  These lists ARE REQUIRED to be set. @par
134    
135        The additional set of inputs are the slv_parameters.
136        These can specify stopping conditions or the amount of
137        information displayed during solving, for example.
138        Monitoring of the solution process is done using the
139        status report for solvers that iterate.
140        More details are given with the
141        respective declarations below. @par
142    
143        @section arch Architecture
144        
145        Right, so we're going to have a client-server, object-oriented,
146        open-architecture system designed to handle multiple clients in a
147        single-thread process. Furthermore, the clients will NOT have to
148        know anything at all about the ASCEND IV compiler hidden out back
149        some place -- in fact our compiler may not BE out back, it may be
150        on another machine or swapped to disk or whatever.
151        
152        That's the ideal. In most applications of ASCEND, particularly the
153        interactive one, the compiler is never very far away. Isolating the
154        compiler data completely (meaning no looking back at it for anything)
155        would mean recreating all the relations (be they tokens, calls to
156        C code, or any kind) in a separate process. This is unacceptable from
157        a memory conservation point of view until RAM comes down to ~$1/MByte,
158        especially if ASCEND is to run on PCs any time soon.
159        
160        What we really have then is a slv_system_t made up of variables and
161        relations and hiding all the compiler details from the clients.
162        Clients will operate directly on the slv_system_t only through real
163        C functions and not through macros so we can hide all the nasty
164        details about the compiler. Variables and relations only make
165        sense in the context of a slv_system_t, so the var_variable type
166        and the rel_relation type in this C code sometimes require that
167        the system pointer be provided when asking for certain properties
168        or services.
169        
170        @section faq FAQ
171    
172        @subsection whatisvar What is a variable?
173        The question is ambiguous. In ASCEND we have the notion of a
174        solver_var ATOM type that includes bounding values, a scaling
175        value, and other properties. These are not the only real-number
176        based items that can occur, however. For purposes of the CLIENT
177        application programming interface (API) we collect all the real-
178        based objects we can find and map them all to struct var_variable.
179        See var.h for details. We sort them into lists as follows:
180            - vars.  These are solver_var that are in an objective or relation.
181            - pars.  These are solver_par appearing parametrically.
182            - unattached.  These don't appear in relation or objective, and
183                        they may be solver_var or solver_par or neither.
184        We keep 2 versions of each list: one for ourselves which is READ-
185        ONLY for clients and allows us to do many things efficiently, and
186        another for clients that clients may rearrange (or even delete)
187        as suits their needs. The former version is called a master list,
188        and the latter version is called a solvers list.
189        
190        @subsection whatisrel What is a relation?
191        At present a relation in ASCEND is either an objective function
192        (a one-sided relation) or a constraining equation. We have a
193        variety of relation implementations within ASCEND, but all any
194        client needs to know about relations can be found in the rel.h
195        file. We keep master and client lists of relations as well.
196        We provide a variety of interesting services with relations:
197            residual and gradient calculations
198            symbolic inversion (where possible)
199            numeric root finding
200            scaling based on symbolic arguments
201            symbolic determination of linearity
202        and we expect to add others as they occur to us or you suggest
203        them.
204        
205         @subsection whatisslvsys What else is a slv_system_t?
206         It's has a host of interesting properties.
207         @li One slv_system_t (system, hereafter) can only be used by one
208            *registered* client at a time, but if your client is an unregistered manager
209            of several subclients (for example an NLP code and and MILP code)
210            then you can pass it back and forth to those registered clients to solve
211            an MINLP. (Note: we haven't done this ourselves yet.)
212            Any number of unregistered clients may share a system, but they
213            must take responsibility for not stepping on each other or the
214            registered client. Registration will be explained further below.
215         @li From any given ASCEND type definitions, the master lists in the
216            system will be ordered identically across all invocations of
217            ASCEND on any hardware that we are aware of. This property is
218            derived from the way we compile instances and create systems.
219            This is helpful in benchmarking and other applications.
220         @li We have a number of standard clients (registered and not)
221            you can use on a the system to precondition it in some way for
222            your client:
223              - Degrees of freedom analysis.
224              - Problem decomposition.
225              - Reordering of vars and rels for good factorization.
226              - Solution of square nonlinear systems.
227              - Generation of MPS code for popular MILP solvers.
228              - Generation of GAMS code for an old, slow compiler of an
229                extremely awkward modeling language that does happen to
230                have a lot of really good optimizers connected.
231        
232        @TODO Short term, we expect to construct a client that takes the partitioned
233        problem and hands off the blocks in sequence to one or more
234        solvers designed to handle only 1 block.
235        
236        @TODO Long term, we anticipate that the structure laid out so far is capable of
237        expansion (probably by intermediate clients which add additional
238        semantic content) to provide standardized (mtx and harwellian)
239        sparse matrix support and memory management for codes that don't
240        care to think about such things directly.
241        
242        @NOTE
243            We are going through a solver API definition restructuring.
244            The appearance of NOTEs in the header means the code in question
245            has, or is about to have, a change in its meaning or is code that
246            is new and replaces some or all the functionality of an old
247            function definition. Basically, expect to have to read NOTE sections
248            carefully and maybe patch calls dependent on them.
249    */
250    
251  typedef void *SlvClientToken;  typedef void *SlvClientToken;
252  /**<  /**<
253   *  A pointer that is meaningful to a registered client.      A pointer that is meaningful to a registered client.
254   *  Each call that requires a client response will include this      Each call that requires a client response will include this
255   *  token so that we can have multiple copies of a particular      token so that we can have multiple copies of a particular
256   *  client simultaneously. Clients shouldn't have to use any      client simultaneously. Clients shouldn't have to use any
257   *  global variables to save their state information -- they      global variables to save their state information -- they
258   *  should put such info with their token.      should put such info with their token.
259   *      
260   *  NOTE TO present (6/96) developers: SlvClientToken is an alias for      @NOTE to present (6/96) developers: SlvClientToken is an alias for
261   *  all the old slv*_system_t pointers. cast it to be the type you want.      all the old slv*_system_t pointers. cast it to be the type you want.
262   */  */
263    
264  struct slv_reorder_data {  struct slv_reorder_data {
265    int partition;    int partition;
# Line 301  typedef struct dof_data_structure { Line 285  typedef struct dof_data_structure {
285    
286  extern int g_SlvNumberOfRegisteredClients;  extern int g_SlvNumberOfRegisteredClients;
287  /**<  /**<
288   *  The number of solver's that have ever registered.      The number of solver's that have ever registered.
289   *  Once a solver is registered, we keep track of its name,      Once a solver is registered, we keep track of its name,
290   *  a number which is the order it was registered in, and      a number which is the order it was registered in, and
291   *  the functions it defines.      the functions it defines.
292   */  */
293    
294  #define SLVMAXCLIENTS 100  #define SLVMAXCLIENTS 100
295  /**<  /**<
296   *  The maximum number of clients that ever can be registered.      The maximum number of clients that ever can be registered.
297   *  Limit is arbitrary. Note that not all clients of slv_system_t      Limit is arbitrary. Note that not all clients of slv_system_t
298   *  should register, just those that purport to be solve engines      should register, just those that purport to be solve engines
299   *  and the like.      and the like.
300   */  */
301    
302    /*-----------------------------------------------------------------------
303        Type declarations for registered client functions
304    */
305    
 /* type declarations for registered client functions */  
306  /** @todo We will explain all these later in this file someday soon. */  /** @todo We will explain all these later in this file someday soon. */
307  typedef SlvClientToken (SlvClientCreateF) (slv_system_t,int *);  typedef SlvClientToken (SlvClientCreateF) (slv_system_t,int *);
308  typedef int (SlvClientDestroyF) (slv_system_t,SlvClientToken);  typedef int (SlvClientDestroyF) (slv_system_t,SlvClientToken);
# Line 331  typedef void (SlvDumpInfoF)(slv_system_t Line 318  typedef void (SlvDumpInfoF)(slv_system_t
318  typedef void (SlvSolveF)(slv_system_t, SlvClientToken);  typedef void (SlvSolveF)(slv_system_t, SlvClientToken);
319    
320  /** Registration information for a solver.  /** Registration information for a solver.
321   *  @todo Complete documentation of slv_registration_data members.      @TODO Complete documentation of slv_registration_data members.
322   */  */
323  typedef struct slv_registration_data {  typedef struct slv_registration_data {
324    int number; /**< we set number AFTER the client registration returns 0.    int number;
325                     client sets all the rest, starting with a symbolic name */       /**< we set number AFTER the client registration returns 0.
326            client sets all the rest, starting with a symbolic name */
327    
328    const char *name;                   /**< symbolic name for solver (required). */    const char *name;                   /**< symbolic name for solver (required). */
329    /* Required functions */    /*
330        Required functions
331      */
332    SlvClientCreateF    *ccreate;       /**<  (required) */    SlvClientCreateF    *ccreate;       /**<  (required) */
333    SlvClientDestroyF   *cdestroy;      /**<  (required) */    SlvClientDestroyF   *cdestroy;      /**<  (required) */
334    SlvClientEligibleF  *celigible;     /**<  (required) */    SlvClientEligibleF  *celigible;     /**<  (required) */
# Line 346  typedef struct slv_registration_data { Line 337  typedef struct slv_registration_data {
337    SlvSetParamsF       *setparam;      /**<  (required) */    SlvSetParamsF       *setparam;      /**<  (required) */
338    SlvGetStatusF       *getstatus;     /**<  (required) */    SlvGetStatusF       *getstatus;     /**<  (required) */
339    SlvSolveF           *solve;         /**<  (required) */    SlvSolveF           *solve;         /**<  (required) */
340    /* Functions we really want, but can live without if your solver is old    /*
341     * and klunky. Your solver may not 'look good' in an interactive environment,      Functions we really want, but can live without if your solver is old
342     * but then those nasty batch codes seldom do anyway.      and klunky. Your solver may not 'look good' in an interactive environment,
343     * Redesign you're blinkin' batch code.      but then those nasty batch codes seldom do anyway.
344     */      Redesign your bloody batch code.
345      */
346    SlvSolveF           *presolve;      /**<  (desired) */    SlvSolveF           *presolve;      /**<  (desired) */
347    SlvSolveF           *iterate;       /**<  (desired) */    SlvSolveF           *iterate;       /**<  (desired) */
348    SlvSolveF           *resolve;       /**<  (desired) */    SlvSolveF           *resolve;       /**<  (desired) */
349    /**< Strictly Optional Functions */    /**
350        Strictly Optional Functions
351      */
352    SlvGetLinsolF       *getlinsol;     /**<  (optional) */    SlvGetLinsolF       *getlinsol;     /**<  (optional) */
353    SlvGetLinSysF       *getlinsys;     /**<  (optional) */    SlvGetLinSysF       *getlinsys;     /**<  (optional) */
354    SlvGetSysMtxF       *getsysmtx;     /**<  (optional) */    SlvGetSysMtxF       *getsysmtx;     /**<  (optional) */
# Line 364  typedef struct slv_registration_data { Line 358  typedef struct slv_registration_data {
358    
359  typedef int (SlvRegistration)(SlvFunctionsT *our_sft);  typedef int (SlvRegistration)(SlvFunctionsT *our_sft);
360  /**<  /**<
361   ***  <!--  status = YourRegistrationFunction(our_sft);                -->      This defines the required form of a function to register a new solver.
362   ***  <!--  SlvFunctionsT *our_sft;                                    -->  
363   ***  <!--  int status;                                                -->      We assume a nonzero return value means you don't register successfully.
364   ***      Your function is probably part of an entire file that bridges
365   ***  We assume a nonzero return value means you don't register successfully.      between our headers and your solve engine back end.
366   ***  Your function is probably part of an entire file that bridges  
367   ***  between our headers and your solve engine back end.      You must provide a function in your solver bridge which to this typedef.
368   ***  You must provide a function in your solver bridge which conforms with  
369   ***  the prototype above (SlvRegistration).      Your function should fill in all the required and as many of the
370   ***  Your function should fill in all the required and as many of the      optional slots in the SlvFunctions pointer you are passed as it can.
371   ***  optional slots in the SlvFunctions pointer you are passed as it can.      (note: do not fill in number -- that is ours.)
372   ***  (note: do not fill in number -- that is ours.)  
373   ***  If you register, but do not fill in a slot we will not accidently      If you register, but do not fill in a slot we will not accidently
374   ***  call a bogus function. We will instead tell the user that an      call a bogus function. We will instead tell the user that an
375   ***  incompetent solver was registered.      incompetent solver was registered.
376   **/  */
377    
378  extern int slv_register_client(SlvRegistration slv0_register,  extern int slv_register_client(SlvRegistration slv0_register,
379                                 char *yourregisterfuncname,                                 char *yourregisterfuncname,
380                                 char *yourbinaryname);                                 char *yourbinaryname);
381  /**<  /**<
382   ***  Examples:      Examples: @code
383   ***   - slv_register_client(slv0_register,NULL,NULL);      slv_register_client(slv0_register,NULL,NULL);
384   ***   - slv_register_client(NULL,"yourregisterfuncname","yourbinaryname");      slv_register_client(NULL,"yourregisterfuncname","yourbinaryname");
385   ***      @endcode
386   ***  Call this function with the SlvRegistration function  
387   ***  from your solver or with 2 strings, but not both.      Call this function with the SlvRegistration function
388   ***  The 2 char strings will be used in dynamically loading      from your solver or with 2 strings, but not both.
389   ***  a solver.<br><br>      The 2 char strings will be used in dynamically loading
390   ***      a solver. @par
391   ***  Returns 0 if registration succeeds, nonzero OTHERWISE.      
392   ***      @return 0 if registration succeeds, nonzero OTHERWISE.
393   ***  @todo Note: the second syntax is NOT YET IMPLEMENTED.  
394   **/      @todo Note: the second syntax is NOT YET IMPLEMENTED.
395    */
396    
397  extern const char *slv_solver_name(int index);  extern const char *slv_solver_name(int index);
398  /**<  /**<
399   ***  There may in general be more than one solver.  The solvers will be      @param index index of the solver in question (the index depends on the order in which the solvers have been registered)
400   ***  numbered from 0 to slv_number_of_solvers-1.  Not all the solvers may      @return name of the solver
401   ***  be present in a given installation of ASCEND as some are proprietary  
402   ***  (MINOS, for example).<br><br>      There may in general be more than one solver.  The solvers will be
403   ***  Solvers not yet registered will not have names. Each registered      numbered [0..slv_number_of_solvers).  Not all the solvers may
404   ***  client must have a unique name if user interfaces are to be happy,      be present in a given installation of ASCEND as some are proprietary
405   ***  though we suppose an interface could make a unique identifier out      (MINOS, for example). @par
406   ***  of name-number pair.  
407   **/      Solvers not yet registered will not have names. Each registered
408        client must have a unique name if user interfaces are to be happy,
409        though we suppose an interface could make a unique identifier out
410        of name-number pair.
411    */
412    
413  extern int Solv_C_CheckHalt_Flag;  extern int Solv_C_CheckHalt_Flag;
414  /**<  /**<
415   ***  Global variable used to communicate information between solvers and      Global variable used to communicate information between solvers and
416   ***  an interface, whether a calculation should be halted or not.      an interface, whether a calculation should be halted or not.
417   ***  @todo Should Solc_C_CheckHalt_Flag be in the public interface?  
418   **/      @TODO Should Solc_C_CheckHalt_Flag be in the public interface?
419    */
420    
421  extern int Solv_C_CheckHalt(void);  extern int Solv_C_CheckHalt(void);
422  /**<  /**< Function to check for variable ascSolvStatVect(menubreak) ="1"
423   ***  Function to check for variable ascSolvStatVect(menubreak) ="1"  
424   ***  Returns 1 if true or if variable not found in global context,      @return 1 if true or if variable not found in global context, else returns 0.
425   ***  else returns 0.<br><br>  
426   ***      Solvers which do not have a real slv_iterate function should
427   ***  Solvers which do not have a real slv_iterate function should      use this in the functions that call on the ASCEND data structure
428   ***  use this in the functions that call on the ASCEND data structure      and should stop and restart their time clocks around the call. @par
429   ***  and should stop and restart their time clocks around the call.<br><br>  
430   ***      This is the present hack to deal with signals, particularly
431   ***  This is the present hack to deal with signals, particularly      SIGINT. It needs to be changed along with the front end
432   ***  SIGINT. It needs to be changed along with the front end      signal handling in the solver and scripting codes.
433   ***  signal handling in the solver and scripting codes.  */
  **/  
434    
435  extern unsigned int slv_serial_id(slv_system_t sys);  extern unsigned int slv_serial_id(slv_system_t sys);
436  /**<  /**< Return the system serial number.
437   ***  <!--  id =slv_serial_id(sys);                                    -->  
438   ***  <!--  slv_system_t sys;                                          -->      @return serial id number of given system.
439   ***  <!--  unsigned id;                                               -->  
440   ***      The id is unique within the life of the program.
441   ***  Returns the id number of the slv_system_t. The id is unique  */
  ***  within the life of the program.  
  **/  
442    
443  extern dof_t *slv_get_dofdata(slv_system_t server);  extern dof_t *slv_get_dofdata(slv_system_t server);
444  /**<  /**<
445   ***  Returns a pointer to the system's dof structure for a      @return pointer to the system's dof structure for a nonlinear solver.
446   ***  nonlinear  solver. See additional discussion under  
447   ***  slv_get_log_dofdata().      @see slv_get_log_dofdata().
448   **/   **/
449  extern dof_t *slv_get_log_dofdata(slv_system_t server);  extern dof_t *slv_get_log_dofdata(slv_system_t server);
450  /**<  /**<
451   ***  <!--  d=slv_get_dofdata(server);                                 -->      @return pointer to the system's dof structure for a logical solver.
452   ***  <!--  d=slv_get_log_dofdata(server);                             -->      Data in the structure should be consistent with
453   ***  <!--  slv_system_t server;                                       -->      some interpretation of the solvers_var/rel lists.
454   ***  <!--  dof_t *d;                                                  -->      The pointer this returns cannot be freed.
455   ***      If server is not NULL, the return value will not be NULL.
456   ***  Returns a pointer to the system's dof structure for a      
457   ***  logical solver.      @TODO The DEFAULT interpretation has not yet been established.
458   ***  Data in the structure should be consistent with  */
  ***  some interpretation of the solvers_var/rel lists.  
  ***  The pointer this returns cannot be freed.  
  ***  If server is not NULL, the return value will not be NULL.  
  ***  @todo The DEFAULT interpretation has not yet been established.  
  **/  
459    
460  extern const mtx_block_t *slv_get_solvers_blocks(slv_system_t sys);  extern const mtx_block_t *slv_get_solvers_blocks(slv_system_t sys);
461  /**<  /**< Decomposition information for the nonlinear solver.
462   ***  Decomposition information for the nonlinear solver.  
463   ***      The blocks of the return value contain decomposition information
464   ***  The blocks of the return value contain decomposition information      about the Jacobian of the equations(included) and variables(free
465   ***  about the Jacobian of the equations(included) and variables(free      and incident) if it is constructed in the ordering of relations/
466   ***  and incident) if it is constructed in the ordering of relations/      variables in the solvers_rel/var_lists. @par
467   ***  variables in the solvers_rel/var_lists.  
468   ***  That is, we have done the subproblem partitioning already.      That is, we have done the subproblem partitioning already.
469   ***  Each region may be solved as a separate subproblem in the      Each region may be solved as a separate subproblem in the
470   ***  order given in the list.      order given in the list. @par
471   ***  We may have also done what we think is a good ordering  
472   ***  for row-wise lower-triangular linear factorization codes      We may have also done what we think is a good ordering
473   ***  within each of the blocks. We may have even arranged the      for row-wise lower-triangular linear factorization codes
474   ***  columns so that we believe we have made a 'good' set of      within each of the blocks. We may have even arranged the
475   ***  variables non-basic in the event that the last block is      columns so that we believe we have made a 'good' set of
476   ***  rectangular.<br><br>      variables non-basic in the event that the last block is
477   ***      rectangular.
478   ***  See slv_get_solvers_log_blocks() for more information.  
479   **/      @see slv_get_solvers_log_blocks()
480    */
481    
482  extern const mtx_block_t *slv_get_solvers_log_blocks(slv_system_t sys);  extern const mtx_block_t *slv_get_solvers_log_blocks(slv_system_t sys);
483  /**<  /**< Decomposition information for the logical solver.
484   ***  <!--  bl = slv_get_solvers_blocks(sys);                          -->  
485   ***  <!--  bl = slv_get_solvers_log_blocks(sys);                      -->      @param sys system being analysed.
486   ***  <!--  slv_system_t sys;                                          -->  
487   ***  <!--  mtx_block_t *bl;                                           -->      @return pointer to the block structure, or NULL if and only if sys is NULL.
488   ***  
489   ***  Decomposition information for the logical solver.      You are free to reorder any matrix you construct from
490   ***      our equation gradients to suit any factorization method
491   ***  You are free to reorder any matrix you construct from      you choose. We strongly recommend that you not do this. @par
492   ***  our equation gradients to suit any factorization method  
493   ***  you choose. We strongly recommend that you not do this.<br><br>      The return value is a pointer to the struct with the number of
494   ***      blocks and the data for the blocks. Each block but the last
495   ***  The return value is a pointer to the struct with the number of      one will be square and will contain a set of rows/columns that
496   ***  blocks and the data for the blocks. Each block but the last      should be solved simultaneously. The last block may be
497   ***  one will be square and will contain a set of rows/columns that      rectangular. Rectangular last blocks will be wider.<br><br>
498   ***  should be solved simultaneously. The last block may be  
499   ***  rectangular. Rectangular last blocks will be wider.<br><br>      In the event that we have a structurally overspecified
500   ***      problem, we will have excluded the redundant equations from
501   ***  In the event that we have a structurally overspecified      the region covered by the block list and partitioned those
502   ***  problem, we will have excluded the redundant equations from      equations remaining. If you are a solver client which solves
503   ***  the region covered by the block list and partitioned those      least squares problems, you should probably just ignore our
504   ***  equations remaining. If you are a solver client which solves      block structure completely. @par
505   ***  least squares problems, you should probably just ignore our  
506   ***  block structure completely.<br><br>      This will never return NULL unless sys is NULL, but if the
507   ***      length of the block array is 0, then the region pointer will
508   ***  This will never return NULL unless sys is NULL, but if the      be NULL.
509   ***  length of the block array is 0, then the region pointer will  */
  ***  be NULL.  
  **/  
510    
511  extern void slv_set_solvers_blocks(slv_system_t sys,  extern void slv_set_solvers_blocks(slv_system_t sys,
512                                     int32 len,                                     int32 len,
513                                     mtx_region_t *data);                                     mtx_region_t *data);
514  /**<  /**<
515   ***  Set the block data for the nonlinear solver to the array      Set the block data for the nonlinear solver to the array
516   ***  given which should be of length len. See      given which should be of length len.
517   ***  slv_set_solvers_log_blocks() for more information.  
518   **/      @see slv_set_solvers_log_blocks()
519    */
520  extern void slv_set_solvers_log_blocks(slv_system_t sys,  extern void slv_set_solvers_log_blocks(slv_system_t sys,
521                                         int32 len,                                         int32 len,
522                                         mtx_region_t *data);                                         mtx_region_t *data);
523  /**<  /**<
524   ***  <!--  slv_get_solvers_blocks(sys,len,data);                      -->      Set the block data for the logical solver to the array
525   ***  <!--  slv_get_solvers_log_blocks(sys,len,data);                  -->      given which should be of length len.
526   ***  <!--  slv_system_t sys;                                          -->      If the system in question already has a list of blocks,
527   ***  <!--  int32 len;                                                 -->      it will be freed. This may have antisocial consequences
528   ***  <!--  mtx_region_t *data;                                        -->      for registered clients if they have stored a copy of the pointer to the
529   ***      old data. The should be told to reinitialize themselves.
530   ***  Set the block data for the logical solver to the array  */
  ***  given which should be of length len.  
  ***  If the system in question already has a list of blocks,  
  ***  it will be freed. This may have antisocial consequences  
  ***  for registered clients if they have stored a copy of the pointer to the  
  ***  old data. The should be told to reinitialize themselves.  
  **/  
531    
532  extern void slv_check_var_initialization(slv_system_t sys);  extern void slv_check_var_initialization(slv_system_t sys);
533  /**<  /**<
534   ***  Checks that all the variables on the solvers_var_list have      Checks that all the variables on the solvers_var_list have
535   ***  been assigned at least once. If any has not, it is assigned      been assigned at least once. If any has not, it is assigned
536   ***  its scaling value (var_nominal) since this is generally a      its scaling value (var_nominal) since this is generally a
537   ***  much better starting value than 0.0.      much better starting value than 0.0.
538   **/  */
539  extern void slv_check_dvar_initialization(slv_system_t sys);  extern void slv_check_dvar_initialization(slv_system_t sys);
540  /**<  /**<
541   ***  <!--  slv_check_var_initialization(sys);                         -->      Checks that all the boolean variables on the solvers_dvar_list have
542   ***  <!--  slv_check_dvar_initialization(sys);                        -->      been assigned at least once. If any has not, it is assigned
543   ***  <!--  slv_system_t sys;                                          -->      a value of TRUE.
544   ***  */
  ***  Checks that all the boolean variables on the solvers_dvar_list have  
  ***  been assigned at least once. If any has not, it is assigned  
  ***  a value of TRUE.  
  **/  
545    
546  extern void slv_bnd_initialization(slv_system_t sys);  extern void slv_bnd_initialization(slv_system_t sys);
547  /**<  /**<
548   ***  <!--  slv_bnd_initialization(sys);                               -->      Initializes the status of a boundary (satisfied ?).
549   ***  <!--  slv_system_t sys;                                          -->      At the initial point, it will be given the same value to
550   ***      the current status and the previous status. Therefore, the bit
551   ***  Initializes the status of a boundary (satisfied ?).      crossed (which can be modified during the iterative scheme)
552   ***  At the initial point, it will be given the same value to      is initialized to FALSE.
553   ***  the current status and the previous status. Therefore, the bit      The evaluation of the status is performed with a call to the
554   ***  crossed (which can be modified during the iterative scheme)      function provided in bndman.
555   ***  is initialized to FALSE.  */
  ***  The evaluation of the status is performed with a call to the  
  ***  function provided in bndman.  
  **/  
556    
557  extern void slv_set_solvers_var_list(slv_system_t sys,  extern void slv_set_solvers_var_list(slv_system_t sys,
558                                       struct var_variable **vlist,                                       struct var_variable **vlist,
559                                       int size);                                       int size);
560  /**<  /**<
561   ***  Sets the system's variable list to vlist.      Sets the system's variable list to vlist.
562   ***  See slv_set_solvers_bnd_list() for more information.  
563        @see slv_set_solvers_bnd_list()
564   **/   **/
565  extern void slv_set_solvers_par_list(slv_system_t sys,  extern void slv_set_solvers_par_list(slv_system_t sys,
566                                       struct var_variable **vlist,                                       struct var_variable **vlist,
567                                       int size);                                       int size);
568  /**<  /**<
569   ***  Sets the system's parameters list to vlist.      Sets the system's parameters list to vlist.
570   ***  See slv_set_solvers_bnd_list() for more information.      
571   **/      @see slv_set_solvers_bnd_list()
572    */
573  extern void slv_set_solvers_unattached_list(slv_system_t sys,  extern void slv_set_solvers_unattached_list(slv_system_t sys,
574                                              struct var_variable **vlist,                                              struct var_variable **vlist,
575                                              int size);                                              int size);
576  /**<  /**<
577   ***  Sets the system's unattached variable list to vlist.      Sets the system's unattached variable list to vlist.
578   ***  See slv_set_solvers_bnd_list() for more information.  
579   **/      @see slv_set_solvers_bnd_list()
580    */
581    
582  extern void slv_set_solvers_dvar_list(slv_system_t sys,  extern void slv_set_solvers_dvar_list(slv_system_t sys,
583                                        struct dis_discrete **dvlist,                                        struct dis_discrete **dvlist,
584                                        int size);                                        int size);
585  /**<  /**<
586   ***  Sets the system's discrete varialbe list to dvlist.      Sets the system's discrete varialbe list to dvlist.
587   ***  See slv_set_solvers_bnd_list() for more information.  
588   **/      @see slv_set_solvers_bnd_list()
589    */
590    
591  extern void slv_set_solvers_disunatt_list(slv_system_t sys,  extern void slv_set_solvers_disunatt_list(slv_system_t sys,
592                                            struct dis_discrete **dvlist,                                            struct dis_discrete **dvlist,
593                                            int size);                                            int size);
594  /**<  /**<
595   ***  Sets the system's unattached discrete variable list to dvlist.      Sets the system's unattached discrete variable list to dvlist.
596   ***  See slv_set_solvers_bnd_list() for more information.  
597   **/      @see slv_set_solvers_bnd_list()
598    */
599    
600  extern void slv_set_solvers_rel_list(slv_system_t sys,  extern void slv_set_solvers_rel_list(slv_system_t sys,
601                                       struct rel_relation **rlist,                                       struct rel_relation **rlist,
602                                       int size);                                       int size);
603  /**<  /**< Sets the system's relation list to rlist.
604   ***  Sets the system's relation list to rlist.  
605   ***  See slv_set_solvers_bnd_list() for more information.      @see slv_set_solvers_bnd_list()
606   **/  */
607     @par
608  extern void slv_set_solvers_condrel_list(slv_system_t sys,  extern void slv_set_solvers_condrel_list(slv_system_t sys,
609                                           struct rel_relation **clist,                                           struct rel_relation **clist,
610                                           int size);                                           int size);
611  /**<  /**< Sets the system's conditional relation list to clist.
612   ***  Sets the system's conditional relation list to clist.      @see slv_set_solvers_bnd_list()
613   ***  See slv_set_solvers_bnd_list() for more information.  */
614   **/  
615  extern void slv_set_solvers_obj_list(slv_system_t sys,  extern void slv_set_solvers_obj_list(slv_system_t sys,
616                                       struct rel_relation **rlist,                                       struct rel_relation **rlist,
617                                       int size);                                       int size);
618  /**<  /**< Sets the system's objective relation list to rlist.
619   ***  Sets the system's objective relation list to rlist.      @see slv_set_solvers_bnd_list()
620   ***  See slv_set_solvers_bnd_list() for more information.  */
621   **/  
622  extern void slv_set_solvers_logrel_list(slv_system_t sys,  extern void slv_set_solvers_logrel_list(slv_system_t sys,
623                                          struct logrel_relation **lrlist,                                          struct logrel_relation **lrlist,
624                                          int size);                                          int size);
625  /**<  /**< Sets the system's logical relation list to lrlist.
626   ***  Sets the system's logical relation list to lrlist.      @see slv_set_solvers_bnd_list()
627   ***  See slv_set_solvers_bnd_list() for more information.  */
628   **/  
629  extern void slv_set_solvers_condlogrel_list(slv_system_t sys,  extern void slv_set_solvers_condlogrel_list(slv_system_t sys,
630                                              struct logrel_relation **lrlist,                                              struct logrel_relation **lrlist,
631                                              int size);                                              int size);
632  /**<  /**< Sets the system's conditional relation list to lrlist.
633   ***  Sets the system's conditional relation list to lrlist.      @see slv_set_solvers_bnd_list()
634   ***  See slv_set_solvers_bnd_list() for more information.  */
635   **/  
636  extern void slv_set_solvers_when_list(slv_system_t sys,  extern void slv_set_solvers_when_list(slv_system_t sys,
637                                        struct w_when **wlist,                                        struct w_when **wlist,
638                                        int size);                                        int size);
639  /**<  /**< Sets the system's when list to wlist.
640   ***  Sets the system's when list to wlist.      @see slv_set_solvers_bnd_list()
641   ***  See slv_set_solvers_bnd_list() for more information.  */
642   **/  
643  extern void slv_set_solvers_bnd_list(slv_system_t sys,  extern void slv_set_solvers_bnd_list(slv_system_t sys,
644                                       struct bnd_boundary **blist,                                       struct bnd_boundary **blist,
645                                       int size);                                       int size);
646  /**<  /**<
647   <!--  ! !  slv_set_solvers_var_list(sys,vlist,size);                  -->      Sets the system's boundary list to blist. If the system already
648   <!--  ! !  slv_set_solvers_par_list(sys,vlist,size);                  -->      has such a list, the old list will be freed unless the two lists are
649   <!--  ! !  slv_set_solvers_unattached_list(sys,vlist,size);           -->      in fact the same (in which case why are you calling this?).
650   <!--  ! !  slv_set_solvers_dvar_list(sys,dvlist,size);                -->      Size is the length of the vlist (excluding the terminal NULL entry).
651   <!--  ! !  slv_set_solvers_disunatt_list(sys,dvlist,size);            -->      The sindex field of each var in the list should match it's list position. @par
652   <!--  ! !  slv_set_solvers_rel_list(sys,rlist,size);                  -->  
653   <!--  ! !  slv_set_solvers_condrel_list(sys,clist,size);              -->      The list should be NULL terminated and the size should be the length
654   <!--  ! !  slv_set_solvers_obj_list(sys,rlist,size);                  -->      of the list  EXCLUDING  the terminal NULL.
655   <!--  ! !  slv_set_solvers_logrel_list(sys,lrlist,size);              -->  
656   <!--  ! !  slv_set_solvers_condlogrel_list(sys,lrlist,size);          -->      @NOTE
657   <!--  ! !  slv_set_solvers_when_list(sys,wlist,size);                 -->          There are now 2 var lists: the master var list pulled of the instance
658   <!--  ! !  slv_set_solvers_bnd_list(sys,blist,size);                  -->          tree, and the solvers var list is to be fetched by the solvers.
659   ***  <!--  slv_system_t sys;                                          -->          Eventually the solvers_varlist will only include those vars the specific
660   ***  <!--  struct var_variable **vlist;                               -->          solver needs to know about.
661   ***  <!--  struct rel_relation **rlist;                               -->          For the moment, the content of the two lists is the same, but the ordering
662   ***  <!--  struct logrel_relation **lrlist;                           -->          is not. The master list is in the order collected. The solvers list
663   ***  <!--  struct w_when **wlist;                                     -->          is reordered in some useful fashion defined elsewhere.
664   ***  <!--  struct bnd_boundary **blist;                               -->  */
  ***  <!--  int size;                                                  -->  
  ***  
  ***  Sets the system's boundary list to blist. If the system already  
  ***  has such a list, the old list will be freed unless the two lists are  
  ***  in fact the same (in which case why are you calling this?).  
  ***  Size is the length of the vlist (excluding the terminal NULL entry).  
  ***  The sindex field of each var in the list should match it's list position.<br><br>  
  ***  
  ***  The list should be NULL terminated and the size should be the length  
  ***  of the list  EXCLUDING  the terminal NULL.<br><br>  
  ! !  
  ! !  There are now 2 var lists: the master var list pulled of the instance  
  ! !  tree, and the solvers var list is to be fetched by the solvers.  
  ! !  Eventually the solvers_varlist will only include those vars the specific  
  ! !  solver needs to know about.  
  ! !  For the moment, the content of the two lists is the same, but the ordering  
  ! !  is not. The master list is in the order collected. The solvers list  
  ! !  is reordered in some useful fashion defined elsewhere.  
  **/  
665    
666  extern struct var_variable **slv_get_solvers_var_list(slv_system_t sys);  extern struct var_variable **slv_get_solvers_var_list(slv_system_t sys);
667  /**<  /**< Returns the most recently set variable list (never NULL) from the system.
668   ***  Returns the most recently set variable list (never NULL) from the system.      @see slv_get_master_disunatt_list()
669   ***  See slv_get_master_disunatt_list() for more information.  */
670   **/  
671  extern struct var_variable **slv_get_solvers_par_list(slv_system_t sys);  extern struct var_variable **slv_get_solvers_par_list(slv_system_t sys);
672  /**<  /**< Returns the most recently set par list (never NULL) from the system.
673   ***  Returns the most recently set par list (never NULL) from the system.      @see slv_get_master_disunatt_list()
674   ***  See slv_get_master_disunatt_list() for more information.  */
  **/  
675  extern struct var_variable **slv_get_solvers_unattached_list(slv_system_t sys);  extern struct var_variable **slv_get_solvers_unattached_list(slv_system_t sys);
676  /**<  /**< Returns the most recently set unattached variable list (never NULL) from the system.
677   ***  Returns the most recently set unattached variable list (never NULL)      @see slv_get_master_disunatt_list()
678   *** from the system.  See slv_get_master_disunatt_list() for more information.  */
679   **/  
680  extern struct dis_discrete **slv_get_solvers_dvar_list(slv_system_t sys);  extern struct dis_discrete **slv_get_solvers_dvar_list(slv_system_t sys);
681  /**<  /**< Returns the most recently set discrete variable list (never NULL) from the system.
682   ***  Returns the most recently set discrete variable list (never NULL)      @see slv_get_master_disunatt_list()
683   ***  from the system.  See slv_get_master_disunatt_list() for more information.  */
  **/  
684  extern struct dis_discrete **slv_get_solvers_disunatt_list(slv_system_t sys);  extern struct dis_discrete **slv_get_solvers_disunatt_list(slv_system_t sys);
685  /**<  /**< Returns the most recently set unattached discrete variable list (never NULL)  from the system.
686   ***  Returns the most recently set unattached discrete variable list      @see slv_get_master_disunatt_list()
687   ***  (never NULL) from the system.  */
  ***  See slv_get_master_disunatt_list() for more information.  
  **/  
688  extern struct var_variable **slv_get_master_var_list(slv_system_t sys);  extern struct var_variable **slv_get_master_var_list(slv_system_t sys);
689  /**<  /**< Returns the most recently set master variable list (never NULL) from the system.
690   ***  Returns the most recently set master variable list (never NULL)      @see slv_get_master_disunatt_list()
691   ***  from the system.  See slv_get_master_disunatt_list() for more information.  */
  **/  
692  extern struct var_variable **slv_get_master_par_list(slv_system_t sys);  extern struct var_variable **slv_get_master_par_list(slv_system_t sys);
693  /**<  /**< Returns the most recently set master par list (never NULL) from the system.
694   ***  Returns the most recently set master par list (never NULL) from the      @see slv_get_master_disunatt_list()
695   ***  system.  See slv_get_master_disunatt_list() for more information.  */
  **/  
696  extern struct var_variable **slv_get_master_unattached_list(slv_system_t sys);  extern struct var_variable **slv_get_master_unattached_list(slv_system_t sys);
697  /**<  /**< Returns the most recently set master unattached variable list (never NULL) from the system.
698   ***  Returns the most recently set master unattached variable list (never      @see slv_get_master_disunatt_list()
699   ***  NULL) from the system.  See slv_get_master_disunatt_list() for more  */
  ***  information.  
  **/  
700  extern struct dis_discrete **slv_get_master_dvar_list(slv_system_t sys);  extern struct dis_discrete **slv_get_master_dvar_list(slv_system_t sys);
701  /**<  /**< Returns the most recently set master discrete variable list (never NULL) from the system.
702   ***  Returns the most recently set master discrete variable list (never      @see slv_get_master_disunatt_list()
703   ***  NULL) from the system.  See slv_get_master_disunatt_list() for more  */
  ***  information.  
  **/  
704  extern struct dis_discrete **slv_get_master_disunatt_list(slv_system_t sys);  extern struct dis_discrete **slv_get_master_disunatt_list(slv_system_t sys);
705  /**<  /** Returns the most recently set master unattached discrete variable list
706   ***  <!--  vlist = slv_get_*_*_list(sys)                              -->      (never NULL) for the convenience of those who need it.<br><br>
707   ***  <!--  slv_system_t sys;                                          -->  
708   ***  <!--  struct var_variable **vlist;                               -->      @NOTE
709   ***  <!--  int size;                                                  -->          There are now 2 var lists: the master var list pulled of the instance
710   ***          tree, and the solvers var list to be handed to the solvers.
711   ***  Returns the most recently set master unattached discrete variable list          Eventually the solvers_varlist will only include those vars the specific
712   ***  (never NULL) for the convenience of those who need it.<br><br>          solver needs to know about.
713   ! !          For the moment, the content of the two lists is the same, but the ordering
714   ! !  There are now 2 var lists: the master var list pulled of the instance          is not. The master list is in the order collected. The solvers list
715   ! !  tree, and the solvers var list to be handed to the solvers.          is reordered in some useful fashion defined by a client.
716   ! !  Eventually the solvers_varlist will only include those vars the specific          Solver clients don't need to know about the master list. UI clients may.<br><br>
717   ! !  solver needs to know about.  
718   ! !  For the moment, the content of the two lists is the same, but the ordering      Parameters are problem invariant constants that the GUI
719   ! !  is not. The master list is in the order collected. The solvers list      user might change before solving another problem using the
720   ! !  is reordered in some useful fashion defined by a client.      same MODEL.
721   ! !  Solver clients don't need to know about the master list. UI clients may.<br><br>  */
  ***  
  ***  Parameters are problem invariant constants that the GUI  
  ***  user might change before solving another problem using the  
  ***  same MODEL.  
  **/  
722    
723  extern struct rel_relation **slv_get_solvers_rel_list(slv_system_t sys);  extern struct rel_relation **slv_get_solvers_rel_list(slv_system_t sys);
724  /**<  Returns the (NULL-terminated) list of solver relations. */  /**<  Returns the (NULL-terminated) list of solver relations. */
725    
726  extern struct rel_relation **slv_get_solvers_condrel_list(slv_system_t sys);  extern struct rel_relation **slv_get_solvers_condrel_list(slv_system_t sys);
727  /**<  Returns the (NULL-terminated) list of solver conditional relations. */  /**<  Returns the (NULL-terminated) list of solver conditional relations. */
728    
729  extern struct rel_relation **slv_get_solvers_obj_list(slv_system_t sys);  extern struct rel_relation **slv_get_solvers_obj_list(slv_system_t sys);
730  /**<  Returns the (NULL-terminated) list of solver objective relations. */  /**<  Returns the (NULL-terminated) list of solver objective relations. */
731    
732  extern struct logrel_relation **slv_get_solvers_logrel_list(slv_system_t sys);  extern struct logrel_relation **slv_get_solvers_logrel_list(slv_system_t sys);
733  /**<  Returns the (NULL-terminated) list of solver logical relations. */  /**<  Returns the (NULL-terminated) list of solver logical relations. */
734    
735  extern struct logrel_relation **slv_get_solvers_condlogrel_list(slv_system_t sys);  extern struct logrel_relation **slv_get_solvers_condlogrel_list(slv_system_t sys);
736  /**<  Returns the (NULL-terminated) list of solver conditional relations. */  /**<  Returns the (NULL-terminated) list of solver conditional relations. */
737    
738  extern struct w_when **slv_get_solvers_when_list(slv_system_t sys);  extern struct w_when **slv_get_solvers_when_list(slv_system_t sys);
739  /**<  Returns the (NULL-terminated) list of solver whens. */  /**<  Returns the (NULL-terminated) list of solver whens. */
740    
741  extern struct bnd_boundary **slv_get_solvers_bnd_list(slv_system_t sys);  extern struct bnd_boundary **slv_get_solvers_bnd_list(slv_system_t sys);
742  /**<  Returns the (NULL-terminated) list of solver boundaries. */  /**<  Returns the (NULL-terminated) list of solver boundaries. */
743    
744  extern struct rel_relation **slv_get_master_rel_list(slv_system_t sys);  extern struct rel_relation **slv_get_master_rel_list(slv_system_t sys);
745  /**<  Returns the (NULL-terminated) list of master relations. */  /**<  Returns the (NULL-terminated) list of master relations. */
746    
747  extern struct rel_relation **slv_get_master_condrel_list(slv_system_t sys);  extern struct rel_relation **slv_get_master_condrel_list(slv_system_t sys);
748  /**<  Returns the (NULL-terminated) list of master conditional relations. */  /**<  Returns the (NULL-terminated) list of master conditional relations. */
749    
750  extern struct rel_relation **slv_get_master_obj_list(slv_system_t sys);  extern struct rel_relation **slv_get_master_obj_list(slv_system_t sys);
751  /**<  Returns the (NULL-terminated) list of master objective relations. */  /**<  Returns the (NULL-terminated) list of master objective relations. */
752    
753  extern struct logrel_relation **slv_get_master_logrel_list(slv_system_t sys);  extern struct logrel_relation **slv_get_master_logrel_list(slv_system_t sys);
754  /**<  Returns the (NULL-terminated) list of master logical relations. */  /**<  Returns the (NULL-terminated) list of master logical relations. */
755    
756  extern struct logrel_relation **slv_get_master_condlogrel_list(slv_system_t sys);  extern struct logrel_relation **slv_get_master_condlogrel_list(slv_system_t sys);
757  /**<  Returns the (NULL-terminated) list of master conditional relations. */  /**<  Returns the (NULL-terminated) list of master conditional relations. */
758    
759  extern struct w_when **slv_get_master_when_list(slv_system_t sys);  extern struct w_when **slv_get_master_when_list(slv_system_t sys);
760  /**<  Returns the (NULL-terminated) list of master whens. */  /**<  Returns the (NULL-terminated) list of master whens. */
761    
762  extern struct bnd_boundary **slv_get_master_bnd_list(slv_system_t sys);  extern struct bnd_boundary **slv_get_master_bnd_list(slv_system_t sys);
763  /**<  Returns the (NULL-terminated) list of master boundaries. */  /**<  Returns the (NULL-terminated) list of master boundaries. */
 /*  
  ***  Returns a list of relations, logical relations, boundaries,  
  ***  objective relations and whens.  
  ***  The list is NULL terminated.  
  ***  Example: For relations and objective relations:  
  ***  rlist = slv_get_solvers_rel_list(sys)  
  ***  olist = slv_get_solvers_obj_list(sys);  
  ***  rlist = slv_get_master_rel_list(sys)  
  ***  rlist = slv_get_master_obj_list(sys)  
  ***  slv_system_t sys;  
  ***  struct rel_relation **rlist;  
  ***  struct rel_relation **olist;  
  **/  
764    
765  extern struct gl_list_t *slv_get_symbol_list(slv_system_t sys);  extern struct gl_list_t *slv_get_symbol_list(slv_system_t sys);
766  /**< Returns the list of SymbolValues struct of a solver system. */  /**< Returns the list of SymbolValues struct of a solver system. */
767    
768  extern int32 slv_need_consistency(slv_system_t sys);  extern int32 slv_need_consistency(slv_system_t sys);
769  /**<  /**< Gets the int need_consitency associated with the system. */
  * <!--  slv_need_consistency(sys);                                    -->  
  * Gets the int need_consitency associated with the system.  
  */  
770    
771  extern int32 slv_get_num_solvers_vars(slv_system_t sys);  extern int32 slv_get_num_solvers_vars(slv_system_t sys);
772  /**<  /**< Returns the length of the solver variable list.
773   ***  Returns the length of the solver variable list.      The length does NOT include the terminating NULL.
774   ***  The length does NOT include the terminating NULL.  */
775   **/  
776  extern int32 slv_get_num_solvers_pars(slv_system_t sys);  extern int32 slv_get_num_solvers_pars(slv_system_t sys);
777  /**<  /**< Returns the length of the solver parameters list.
778   ***  Returns the length of the solver parameters list.      The length does NOT include the terminating NULL.
779   ***  The length does NOT include the terminating NULL.  */
780   **/  
781  extern int32 slv_get_num_solvers_unattached(slv_system_t sys);  extern int32 slv_get_num_solvers_unattached(slv_system_t sys);
782  /**<  /**< Returns the length of the solver unsattached variable list.
783   ***  Returns the length of the solver unsattached variable list.      The length does NOT include the terminating NULL.
784   ***  The length does NOT include the terminating NULL.  */
785   **/  
786  extern int32 slv_get_num_solvers_dvars(slv_system_t sys);  extern int32 slv_get_num_solvers_dvars(slv_system_t sys);
787  /**<  /**< Returns the length of the solver discrete variables list.
788   ***  Returns the length of the solver discrete variables list.      The length does NOT include the terminating NULL.
789   ***  The length does NOT include the terminating NULL.  */
790   **/  
791  extern int32 slv_get_num_solvers_disunatt(slv_system_t sys);  extern int32 slv_get_num_solvers_disunatt(slv_system_t sys);
792  /**<  /**< Returns the length of the solver unattached discrete variables list.
793   ***  Returns the length of the solver unattached discrete variables list.      The length does NOT include the terminating NULL.
794   ***  The length does NOT include the terminating NULL.  */
795   **/  
796  extern int32 slv_get_num_solvers_rels(slv_system_t sys);  extern int32 slv_get_num_solvers_rels(slv_system_t sys);
797  /**<  /**< Returns the length of the solver relations list.
798   ***  Returns the length of the solver relations list.      The length does NOT include the terminating NULL.
799   ***  The length does NOT include the terminating NULL.  */
800   **/  
801  extern int32 slv_get_num_solvers_condrels(slv_system_t sys);  extern int32 slv_get_num_solvers_condrels(slv_system_t sys);
802  /**<  /**< Returns the length of the solver conditional relations list.
803   ***  Returns the length of the solver conditional relations list.      The length does NOT include the terminating NULL.
804   ***  The length does NOT include the terminating NULL.  */
805   **/  
806  extern int32 slv_get_num_solvers_objs(slv_system_t sys);  extern int32 slv_get_num_solvers_objs(slv_system_t sys);
807  /**<  /**< Returns the length of the solver objective relations list.
808   ***  Returns the length of the solver objective relations list.      The length does NOT include the terminating NULL.
809   ***  The length does NOT include the terminating NULL.  */
810   **/  
811  extern int32 slv_get_num_solvers_logrels(slv_system_t sys);  extern int32 slv_get_num_solvers_logrels(slv_system_t sys);
812  /**<  /**< Returns the length of the solver logical relations list.
813   ***  Returns the length of the solver logical relations list.      The length does NOT include the terminating NULL.
814   ***  The length does NOT include the terminating NULL.  */
815   **/  
816  extern int32 slv_get_num_solvers_condlogrels(slv_system_t sys);  extern int32 slv_get_num_solvers_condlogrels(slv_system_t sys);
817  /**<  /**< Returns the length of the solver conditional relations list.
818   ***  Returns the length of the solver conditional relations list.      The length does NOT include the terminating NULL.
819   ***  The length does NOT include the terminating NULL.  */
820   **/  
821  extern int32 slv_get_num_solvers_whens(slv_system_t sys);  extern int32 slv_get_num_solvers_whens(slv_system_t sys);
822  /**<  /**< Returns the length of the solver whens list.
823   ***  Returns the length of the solver whens list.      The length does NOT include the terminating NULL.
824   ***  The length does NOT include the terminating NULL.  */
825   **/  
826  extern int32 slv_get_num_solvers_bnds(slv_system_t sys);  extern int32 slv_get_num_solvers_bnds(slv_system_t sys);
827  /**<  /**<
828   ***  Returns the length of the solver boundaries list.   ***  Returns the length of the solver boundaries list.
# Line 882  extern int32 slv_get_num_master_vars(slv Line 834  extern int32 slv_get_num_master_vars(slv
834   ***  The length does NOT include the terminating NULL.   ***  The length does NOT include the terminating NULL.
835   **/   **/
836  extern int32 slv_get_num_master_pars(slv_system_t sys);  extern int32 slv_get_num_master_pars(slv_system_t sys);
837  /**<  /**< Returns the length of the master parameters list.
838   ***  Returns the length of the master parameters list.      The length does NOT include the terminating NULL.
839   ***  The length does NOT include the terminating NULL.  */
840   **/  
841  extern int32 slv_get_num_master_unattached(slv_system_t sys);  extern int32 slv_get_num_master_unattached(slv_system_t sys);
842  /**<  /**< Returns the length of the master unattached variables list.
843   ***  Returns the length of the master unattached variables list.      The length does NOT include the terminating NULL.
844   ***  The length does NOT include the terminating NULL.  */
845   **/  
846  extern int32 slv_get_num_master_dvars(slv_system_t sys);  extern int32 slv_get_num_master_dvars(slv_system_t sys);
847  /**<  /**< Returns the length of the master discrete variables list.
848   ***  Returns the length of the master discrete variables list.      The length does NOT include the terminating NULL.
849   ***  The length does NOT include the terminating NULL.  */
850   **/  
851  extern int32 slv_get_num_master_disunatt(slv_system_t sys);  extern int32 slv_get_num_master_disunatt(slv_system_t sys);
852  /**<  /**< Returns the length of the master unattached discrete variables list.
853   ***  Returns the length of the master unattached discrete variables list.      The length does NOT include the terminating NULL.
854   ***  The length does NOT include the terminating NULL.  */
855   **/  
856  extern int32 slv_get_num_master_rels(slv_system_t sys);  extern int32 slv_get_num_master_rels(slv_system_t sys);
857  /**<  /**< Returns the length of the master relations list.
858   ***  Returns the length of the master relations list.      The length does NOT include the terminating NULL.
859   ***  The length does NOT include the terminating NULL.  */
860   **/  
861  extern int32 slv_get_num_master_condrels(slv_system_t sys);  extern int32 slv_get_num_master_condrels(slv_system_t sys);
862  /**<  /**< Returns the length of the master conditional relations list.
863   ***  Returns the length of the master conditional relations list.      The length does NOT include the terminating NULL.
864   ***  The length does NOT include the terminating NULL.  */
865   **/  
866  extern int32 slv_get_num_master_objs(slv_system_t sys);  extern int32 slv_get_num_master_objs(slv_system_t sys);
867  /**<  /**< Returns the length of the master objective relations list.
868   ***  Returns the length of the master objective relations list.      The length does NOT include the terminating NULL.
869   ***  The length does NOT include the terminating NULL.  */
870   **/  
871  extern int32 slv_get_num_master_logrels(slv_system_t sys);  extern int32 slv_get_num_master_logrels(slv_system_t sys);
872  /**<  /**< Returns the length of the master logical relations list.
873   ***  Returns the length of the master logical relations list.      The length does NOT include the terminating NULL.
874   ***  The length does NOT include the terminating NULL.  */
875   **/  
876  extern int32 slv_get_num_master_condlogrels(slv_system_t sys);  extern int32 slv_get_num_master_condlogrels(slv_system_t sys);
877  /**<  /**< Returns the length of the master conditional relations list.
878   ***  Returns the length of the master conditional relations list.      The length does NOT include the terminating NULL.
879   ***  The length does NOT include the terminating NULL.  */
880   **/  
881  extern int32 slv_get_num_master_whens(slv_system_t sys);  extern int32 slv_get_num_master_whens(slv_system_t sys);
882  /**<  /**< Returns the length of the master whens list.
883   ***  Returns the length of the master whens list.      The length does NOT include the terminating NULL.
884   ***  The length does NOT include the terminating NULL.  */
885   **/  
886  extern int32 slv_get_num_master_bnds(slv_system_t sys);  extern int32 slv_get_num_master_bnds(slv_system_t sys);
887  /**<  /**<  Returns the length of the master boundaries list.
888   ***  Returns the length of the master boundaries list.      The length does NOT include the terminating NULL.
889   ***  The length does NOT include the terminating NULL.  */
  **/  
 /*  
  ***  len = slv_get_num_*_*(sys);  
  ***  slv_system_t sys;  
  ***  int len;  
  ***  
  ***  Returns the length of the corresponding pointer list.  
  ***  The length does NOT include the terminating NULL.  
  **/  
890    
891  extern int32 slv_get_num_models(slv_system_t sys);  extern int32 slv_get_num_models(slv_system_t sys);
892  /**<  /**< Returns the number of models found in the tree the
893   ***  <!--  len = slv_get_num_models(sys);                             -->      problem was constructed from. There is no corresponding list.
894   ***  <!--  slv_system_t sys;                                          -->      Rel_relations will know which of these models they came from.
895   ***  <!--  int len;                                                   -->  */
  ***  
  ***  Returns the number of models found in the tree the  
  ***  problem was constructed from. There is no corresponding list.  
  ***  Rel_relations will know which of these models they came from.  
  **/  
896    
897  extern int32 slv_count_solvers_vars(slv_system_t sys, var_filter_t *vfilter);  extern int32 slv_count_solvers_vars(slv_system_t sys, var_filter_t *vfilter);
898  /**< Returns the number of solver variables matching the specified filter. */  /**< Returns the number of solver variables matching the specified filter. */
899    
900  extern int32 slv_count_solvers_pars(slv_system_t sys, var_filter_t *vfilter);  extern int32 slv_count_solvers_pars(slv_system_t sys, var_filter_t *vfilter);
901  /**< Returns the number of solver parameters matching the specified filter. */  /**< Returns the number of solver parameters matching the specified filter. */
902    
903  extern int32 slv_count_solvers_unattached(slv_system_t sys, var_filter_t *vfilter);  extern int32 slv_count_solvers_unattached(slv_system_t sys, var_filter_t *vfilter);
904  /**< Returns the number of solver unattached variables matching the specified filter. */  /**< Returns the number of solver unattached variables matching the specified filter. */
905    
906  extern int32 slv_count_solvers_dvars(slv_system_t sys, dis_filter_t *dfilter);  extern int32 slv_count_solvers_dvars(slv_system_t sys, dis_filter_t *dfilter);
907  /**< Returns the number of solver discrete variables matching the specified filter. */  /**< Returns the number of solver discrete variables matching the specified filter. */
908    
909  extern int32 slv_count_solvers_disunatt(slv_system_t sys, dis_filter_t *dfilter);  extern int32 slv_count_solvers_disunatt(slv_system_t sys, dis_filter_t *dfilter);
910  /**< Returns the number of solver unattached discrete variables matching the specified filter. */  /**< Returns the number of solver unattached discrete variables matching the specified filter. */
911    
912  extern int32 slv_count_solvers_rels(slv_system_t sys, rel_filter_t *rfilter);  extern int32 slv_count_solvers_rels(slv_system_t sys, rel_filter_t *rfilter);
913  /**< Returns the number of solver relations matching the specified filter. */  /**< Returns the number of solver relations matching the specified filter. */
914    
915  extern int32 slv_count_solvers_condrels(slv_system_t sys, rel_filter_t *rfilter);  extern int32 slv_count_solvers_condrels(slv_system_t sys, rel_filter_t *rfilter);
916  /**< Returns the number of solver conditional relations matching the specified filter. */  /**< Returns the number of solver conditional relations matching the specified filter. */
917    
918  extern int32 slv_count_solvers_objs(slv_system_t sys, rel_filter_t *rfilter);  extern int32 slv_count_solvers_objs(slv_system_t sys, rel_filter_t *rfilter);
919  /**< Returns the number of solver objective relations matching the specified filter. */  /**< Returns the number of solver objective relations matching the specified filter. */
920    
921  extern int32 slv_count_solvers_logrels(slv_system_t sys, logrel_filter_t *lrfilter);  extern int32 slv_count_solvers_logrels(slv_system_t sys, logrel_filter_t *lrfilter);
922  /**< Returns the number of solver logical relations matching the specified filter. */  /**< Returns the number of solver logical relations matching the specified filter. */
923    
924  extern int32 slv_count_solvers_condlogrels(slv_system_t sys, logrel_filter_t *lrfilter);  extern int32 slv_count_solvers_condlogrels(slv_system_t sys, logrel_filter_t *lrfilter);
925  /**< Returns the number of solver conditional logical relations matching the specified filter. */  /**< Returns the number of solver conditional logical relations matching the specified filter. */
926    
927  extern int32 slv_count_solvers_whens(slv_system_t sys, when_filter_t *wfilter);  extern int32 slv_count_solvers_whens(slv_system_t sys, when_filter_t *wfilter);
928  /**< Returns the number of solver whens matching the specified filter. */  /**< Returns the number of solver whens matching the specified filter. */
929    
930  extern int32 slv_count_solvers_bnds(slv_system_t sys, bnd_filter_t *bfilter);  extern int32 slv_count_solvers_bnds(slv_system_t sys, bnd_filter_t *bfilter);
931  /**< Returns the number of solver boundaries matching the specified filter. */  /**< Returns the number of solver boundaries matching the specified filter. */
932    
933  extern int32 slv_count_master_vars(slv_system_t sys, var_filter_t *vfilter);  extern int32 slv_count_master_vars(slv_system_t sys, var_filter_t *vfilter);
934  /**< Returns the number of master variables matching the specified filter. */  /**< Returns the number of master variables matching the specified filter. */
935    
936  extern int32 slv_count_master_pars(slv_system_t sys, var_filter_t *vfilter);  extern int32 slv_count_master_pars(slv_system_t sys, var_filter_t *vfilter);
937  /**< Returns the number of master parameters matching the specified filter. */  /**< Returns the number of master parameters matching the specified filter. */
938    
939  extern int32 slv_count_master_unattached(slv_system_t sys, var_filter_t *vfilter);  extern int32 slv_count_master_unattached(slv_system_t sys, var_filter_t *vfilter);
940  /**< Returns the number of master unattached variables matching the specified filter. */  /**< Returns the number of master unattached variables matching the specified filter. */
941    
942  extern int32 slv_count_master_dvars(slv_system_t sys, dis_filter_t *dfilter);  extern int32 slv_count_master_dvars(slv_system_t sys, dis_filter_t *dfilter);
943  /**< Returns the number of master discrete variables matching the specified filter. */  /**< Returns the number of master discrete variables matching the specified filter. */
944    
945  extern int32 slv_count_master_disunatt(slv_system_t sys, dis_filter_t *dfilter);  extern int32 slv_count_master_disunatt(slv_system_t sys, dis_filter_t *dfilter);
946  /**< Returns the number of master unattached discrete variables matching the specified filter. */  /**< Returns the number of master unattached discrete variables matching the specified filter. */
947    
948  extern int32 slv_count_master_rels(slv_system_t sys, rel_filter_t *rfilter);  extern int32 slv_count_master_rels(slv_system_t sys, rel_filter_t *rfilter);
949  /**< Returns the number of master relations matching the specified filter. */  /**< Returns the number of master relations matching the specified filter. */
950    
951  extern int32 slv_count_master_condrels(slv_system_t sys, rel_filter_t *rfilter);  extern int32 slv_count_master_condrels(slv_system_t sys, rel_filter_t *rfilter);
952  /**< Returns the number of master conditional relations matching the specified filter. */  /**< Returns the number of master conditional relations matching the specified filter. */
953    
954  extern int32 slv_count_master_objs(slv_system_t sys, rel_filter_t *rfilter);  extern int32 slv_count_master_objs(slv_system_t sys, rel_filter_t *rfilter);
955  /**< Returns the number of master objective relations matching the specified filter. */  /**< Returns the number of master objective relations matching the specified filter. */
956    
957  extern int32 slv_count_master_logrels(slv_system_t sys, logrel_filter_t *lrfilter);  extern int32 slv_count_master_logrels(slv_system_t sys, logrel_filter_t *lrfilter);
958  /**< Returns the number of master logical relations matching the specified filter. */  /**< Returns the number of master logical relations matching the specified filter. */
959    
960  extern int32 slv_count_master_condlogrels(slv_system_t sys, logrel_filter_t *lrfilter);  extern int32 slv_count_master_condlogrels(slv_system_t sys, logrel_filter_t *lrfilter);
961  /**< Returns the number of master conditional logical relations matching the specified filter. */  /**< Returns the number of master conditional logical relations matching the specified filter. */
962    
963  extern int32 slv_count_master_whens(slv_system_t sys, when_filter_t *wfilter);  extern int32 slv_count_master_whens(slv_system_t sys, when_filter_t *wfilter);
964  /**< Returns the number of master whens matching the specified filter. */  /**< Returns the number of master whens matching the specified filter. */
965    
966  extern int32 slv_count_master_bnds(slv_system_t sys, bnd_filter_t *bfilter);  extern int32 slv_count_master_bnds(slv_system_t sys, bnd_filter_t *bfilter);
967  /**< Returns the number of master boundaries matching the specified filter. */  /**< Returns the number of master boundaries matching the specified filter. */
 /*  
  ***  count = slv_count_*_*(sys,vfilter)  
  ***  count = slv_count_*_*rels(sys,rfilter)  
  ***  slv_system_t sys;  
  ***  var_filter_t *vfilter;  
  ***  rel_filter_t *rfilter;  
  ***  int count;  
  ***  
  ***  Counts the variables, boundaries, relations or whens currently  
  ***  in the system's solvers or master list which match the  
  ***  specified filter.  
  ***  
  ***  Efficiency note: if you are using this with a match anything  
  ***  filter, you would be better off just calling the slv_get_num_*  
  ***  function for the list in question.  
  **/  
968    
969  /*========================================================================*\  /** @file slv_client.h
970    Registered client queries.      @NOTE
971  \*========================================================================*/          Efficiency note relating to slv_count_master_*: if you are using this with a match anything
972            filter, you would be better off just calling the slv_get_num_*
973            function for the list in question.
974    */
975    
976    
977    /*-----------------------------------------------------------------------
978        Registered client queries.
979    */
980    
981  extern void slv_set_obj_relation(slv_system_t sys, struct rel_relation *obj);  extern void slv_set_obj_relation(slv_system_t sys, struct rel_relation *obj);
982  /**<  /**<
983   ***  Sets the objective relation of the solver to the      Sets the objective relation of the solver to the
984   ***  given one which should come from the objective list.  A special value      given one which should come from the objective list.  A special value
985   ***  of NULL for the objective function indicates no objective function.<br><br>      of NULL for the objective function indicates no objective function.<br><br>
986   ***  Client solvers should minimize the residual of this equation.      Client solvers should minimize the residual of this equation.
987   **/  */
988    
989  extern struct rel_relation *slv_get_obj_relation(slv_system_t sys);  extern struct rel_relation *slv_get_obj_relation(slv_system_t sys);
990  /**<  /**<
991   ***  <!--  slv_set_obj_relation(sys,obj)                              -->      @return the internal copy of the objective function, or
992   ***  <!--  obj = slv_get_obj_relation(sys)                            -->      NULL if none was specified.<br><br>
993   ***  <!--  slv_system_t sys;                                          -->  
994   ***  <!--  struct rel_relation *obj;                                  -->      Client solvers should minimize the residual of this equation.
995   ***  */
  ***  Returns the internal copy of the objective function, or  
  ***  NULL if none was specified.<br><br>  
  ***  
  ***  Client solvers should minimize the residual of this equation.  
  **/  
996    
997  extern void slv_set_obj_variable(slv_system_t sys,  extern void slv_set_obj_variable(slv_system_t sys,
998                                   struct var_variable *objvar,                                   struct var_variable *objvar,
999                                   unsigned maximize);                                   unsigned maximize);
1000  /**<  /**<
1001   ***  Specifies the var to use for an objective and whether it should      Specifies the var to use for an objective and whether it should
1002   ***  be maximized or minimized. Var must be from the slv_system or      be maximized or minimized. Var must be from the slv_system or
1003   ***  complete insanity may result.      complete insanity may result.
1004   ***      
1005   ***  There is no value function here. just use var_value      There is no value function here. just use var_value
1006   ***  Client solvers should minimize this variable.      Client solvers should minimize this variable.
1007   ***  
1008   ***  By default, the objective var is NULL, even if there is      By default, the objective var is NULL, even if there is
1009   ***  and objective relation (maximize,minimize) in the ASCEND MODEL.      and objective relation (maximize,minimize) in the ASCEND MODEL.
1010   ***  (ascend MODEL objectives are handled with obj_relation functions)      (ascend MODEL objectives are handled with obj_relation functions)
1011   ***  Optimizers should use objective var in preference to the obj      Optimizers should use objective var in preference to the obj
1012   ***  relation if the var is defined.      relation if the var is defined.
1013   **/  */
1014    
1015  extern struct var_variable *slv_get_obj_variable(slv_system_t sys);  extern struct var_variable *slv_get_obj_variable(slv_system_t sys);
1016  /**<  Returns the var used for an objective or NULL if none set. */  /**<  Returns the var used for an objective or NULL if none set. */
1017    
1018  extern real64 slv_get_obj_variable_gradient(slv_system_t sys);  extern real64 slv_get_obj_variable_gradient(slv_system_t sys);
1019  /**<  /**<
1020   ***  <!--  slv_set_obj_variable(sys,objvar,maximize);                 -->      Returns the unscaled gradient of the objective variable, or 0
1021   ***  <!--  objvar = slv_get_obj_variable(sys);                        -->      if no var is set.
1022   ***  <!--  objvar_grad = slv_get_obj_variable_gradient(sys);          -->  */
  ***  <!--  slv_system_t sys;                                          -->  
  ***  <!--  struct var_variable *var;                                  -->  
  ***  <!--  unsigned int maximize;                                     -->  
  ***  <!--  real64 objvar_grad;                                        -->  
  ***  
  ***  Returns the unscaled gradient of the objective variable, or 0  
  ***  if no var is set.  
  **/  
1023    
1024  extern int slv_eligible_solver(slv_system_t sys);  extern int slv_eligible_solver(slv_system_t sys);
1025  /**<  /**<
1026   ***  <!--  eligible = slv_eligible_solver(sys)                        -->      Determines whether or not the current solver.
1027   ***  <!--  int eligible;                                              -->      is capable of solving the given system as it is currently set up
1028   ***  <!--  slv_system_t sys;                                          -->      (e.g. some solvers cannot do optimization, or inequalities, etc.).
1029   ***      The system must be set up first before calling this function, or the
1030   ***  Determines whether or not the current solver.      return value may be misleading. @par
1031   ***  is capable of solving the given system as it is currently set up  
1032   ***  (e.g. some solvers cannot do optimization, or inequalities, etc.).      The solver in question will be asked to pass judgement on the
1033   ***  The system must be set up first before calling this function, or the      data in the slv_system_t wrt the solver being useful.
1034   ***  return value may be misleading.<br><br>      If no solver is registered, this returns FALSE.
1035   ***  The solver in question will be asked to pass judgement on the  */
  ***  data in the slv_system_t wrt the solver being useful.  
  ***  If no solver is registered, this returns FALSE.  
  **/  
1036    
1037  extern int slv_select_solver(slv_system_t sys, int solver);  extern int slv_select_solver(slv_system_t sys, int solver);
1038  /**<  /**<
1039   ***  Sets the given solver to be the current solver      Sets the given solver to be the current solver
1040   ***  for the system.  The intelligence or stupidity of this move is not      for the system.  The intelligence or stupidity of this move is not
1041   ***  investigated. If the system has already has a solver selected and      investigated. If the system has already has a solver selected and
1042   ***  it is not the same solver, the data structures of the old selection      it is not the same solver, the data structures of the old selection
1043   ***  will be blown away.      will be blown away.
1044   ***  Return value is number of solver actually selected.  
1045   ***  If failure, return is -1;      @return number of solver actually selected or -1 on failure
1046   **/  */
1047    
1048  extern int slv_get_selected_solver(slv_system_t sys);  extern int slv_get_selected_solver(slv_system_t sys);
1049  /**<  /**<
1050   ***  <!--  solver=slv_select_solver(sys,solver)                       -->      Returns the current solver number for a system.
1051   ***  <!--  solver = slv_get_selected_solver(sys)                      -->  */
  ***  <!--  slv_system_t sys;                                          -->  
  ***  <!--  int solver;                                                -->  
  ***  
  ***  Returns the current solver number.  
  **/  
1052    
1053  extern int slv_switch_solver(slv_system_t sys, int solver);  extern int slv_switch_solver(slv_system_t sys, int solver);
1054  /**<  /**<
1055   ***  <!--  solver=slv_switch_solver(sys,solver)                       -->      Sets the given solver to be the current solver for the system.
1056   ***  <!--  slv_system_t sys;                                          -->      Return value is number of solver actually selected.
1057   ***  <!--  int solver;                                                -->      If failure, return is -1;
1058   ***  */
  ***  Sets the given solver to be the current solver for the system.  
  ***  Return value is number of solver actually selected.  
  ***  If failure, return is -1;  
  **/  
1059    
1060  extern int32 slv_get_default_parameters(int32 index, slv_parameters_t *parameters);  extern int32 slv_get_default_parameters(int32 index, slv_parameters_t *parameters);
1061  /**< @todo KHACK: NEED TO COMMENT. */  /**< @TODO needs commenting, KHACK */
1062    
1063  extern void slv_get_parameters(slv_system_t sys, slv_parameters_t *parameters);  extern void slv_get_parameters(slv_system_t sys, slv_parameters_t *parameters);
1064  /**<  /**<
1065   ***  Copies the current system parameters to the given structure.      Copies the current system parameters to the given structure.
1066   ***  
1067   ***  Do not confuse these parameters [algorithm control variables]      Do not confuse these parameters [algorithm control variables]
1068   ***  with the parameter list which is a list of pointers to var_variable.      with the parameter list which is a list of pointers to var_variable.
1069   **/  */
1070  extern void slv_set_parameters(slv_system_t sys, slv_parameters_t *parameters);  extern void slv_set_parameters(slv_system_t sys, slv_parameters_t *parameters);
1071  /**<  /**<
1072   ***  <!--  slv_get_parameters(sys,parameters)                         -->      Sets the current system parameters to the values contained
1073   ***  <!--  slv_set_parameters(sys,parameters)                         -->      in the given structure.  It is recommended that one
1074   ***  <!--  slv_system_t sys;                                          -->      gets the parameters first, before one modifies them and sets them,
1075   ***  <!--  slv_parameters_t *parameters;                              -->      especially if not all of the parameters are to be modified (and you
1076   ***      never know when that might suddenly become true because a new
1077   ***  Sets the current system parameters to the values contained      parameter was added to the structure).  Parameters will only be
1078   ***  in the given structure.  It is recommended that one      accepted by an engine if they came from that engine, so fetching
1079   ***  gets the parameters first, before one modifies them and sets them,      before setting is not only a good idea, it's the law (gas engines
1080   ***  especially if not all of the parameters are to be modified (and you      don't run on diesel very well...). @par
1081   ***  never know when that might suddenly become true because a new      
1082   ***  parameter was added to the structure).  Parameters will only be      Do not confuse these parameters [algorithm control variables]
1083   ***  accepted by an engine if they came from that engine, so fetching      with the parameter list which is a list of pointers to var_variable.
1084   ***  before setting is not only a good idea, it's the law (gas engines  */
  ***  don't run on diesel very well...).<br><br>  
  ***  
  ***  Do not confuse these parameters [algorithm control variables]  
  ***  with the parameter list which is a list of pointers to var_variable.  
  **/  
1085    
1086  extern SlvClientToken slv_get_client_token(slv_system_t sys);  extern SlvClientToken slv_get_client_token(slv_system_t sys);
1087  /**<  Returns  the client token of the system_t. */  /**<  Returns  the client token of the system_t. */
1088    
1089  extern void slv_set_client_token(slv_system_t sys, SlvClientToken ct);  extern void slv_set_client_token(slv_system_t sys, SlvClientToken ct);
1090  /**<  /**<
1091   ***  <!--  ct=slv_get_client_token(sys)                               -->      Sets  the client token of the system_t.
1092   ***  <!--  slv_system_t sys;                                          -->  */
  ***  Sets  the client token of the system_t.  
  **/  
1093    
1094  extern void slv_set_solver_index(slv_system_t sys, int index);  extern void slv_set_solver_index(slv_system_t sys, int index);
1095  /**<  /**<
1096   ***  <!--  slv_set_solver_index(sys)                                  -->      Sets the solver index of the slv_system_t.
1097   ***  <!--  slv_system_t sys;                                          -->  */
  ***  Sets the solver index of the slv_system_t.  
  **/  
1098    
1099  extern void slv_get_status(slv_system_t sys, slv_status_t *status);  extern void slv_get_status(slv_system_t sys, slv_status_t *status);
1100  /**<  /**<
1101   ***  <!--  slv_get_status(sys,status)                                 -->      Copies the current system status into the given structure.
1102   ***  <!--  slv_system_t sys;                                          -->  */
  ***  <!--  slv_status_t *status;                                      -->  
  ***  
  ***  Copies the current system status into the given structure.  
  **/  
1103    
 /* THIS CALL SHOULD GO AWAY */  
1104  extern linsolqr_system_t slv_get_linsolqr_sys(slv_system_t sys);  extern linsolqr_system_t slv_get_linsolqr_sys(slv_system_t sys);
1105  /**<  /**<
1106   ***  <!--  lqrsys = slv_get_linsolqr_sys(sys)                         -->      Returns the linsolqr system used, or NULL if none.
1107   ***  <!--  linsolqr_system_t lqrsys;                                  -->      @deprecated { THIS CALL SHOULD GO AWAY }
1108   ***  <!--  slv_system_t sys;                                          -->  */
  ***  
  ***  Returns the linsolqr system used, or NULL if none.  
  ***  
  ***  @todo THIS CALL SHOULD GO AWAY  
  **/  
1109    
 /* THIS CALL SHOULD GO AWAY */  
1110  extern linsol_system_t slv_get_linsol_sys(slv_system_t sys);  extern linsol_system_t slv_get_linsol_sys(slv_system_t sys);
1111  /**<  /**<
1112   ***  <!--  lsys = slv_get_linsol_sys(sys)                             -->      Returns the linsol system used, or NULL if none.
1113   ***  <!--  linsol_system_t lsys;                                      -->      @deprecated { THIS CALL SHOULD GO AWAY }
1114   ***  <!--  slv_system_t sys;                                          -->  */
  ***  
  ***  Returns the linsol system used, or NULL if none.  
  ***  
  ***  @todo THIS CALL SHOULD GO AWAY  
  **/  
1115    
 /* THIS CALL SHOULD GO AWAY */  
1116  extern mtx_matrix_t slv_get_sys_mtx(slv_system_t sys);  extern mtx_matrix_t slv_get_sys_mtx(slv_system_t sys);
1117  /**<  /**<
1118   ***  <!--  mtx = slv_get_sys_mtx(sys)                                 -->      Returns the mtx used, or NULL if none. The user should check.
1119   ***  <!--  mtx_matrix_t mtx;                                          -->      
1120   ***  <!--  slv_system_t sys;                                          -->      @deprecated {THIS CALL SHOULD GO AWAY}
  ***  
  ***  Returns the mtx used, or NULL if none. The user should check.  
  ***  
  ***  @todo THIS CALL SHOULD GO AWAY  
1121   **/   **/
1122    
1123  extern void slv_dump_internals(slv_system_t sys, int level);  extern void slv_dump_internals(slv_system_t sys, int level);
1124  /**<  /**<
1125   ***  <!--  slv_dump_internals(sys,level)                              -->      Will spew whatever the solver interface developer feels like to
1126   ***  <!--  slv_system_t sys;                                          -->      stderr.  Larger values of level will give more detailed information,
1127   ***  <!--  int level;                                                 -->      we hope.  No specification is made with regard to what the
1128   ***      information will be.  returns -1 if solver gutless.  This is provided
1129   ***  Will spew whatever the solver interface developer feels like to      principally to facilitate debugging a little.
1130   ***  stderr.  Larger values of level will give more detailed information,  
1131   ***  we hope.  No specification is made with regard to what the      @TODO fix dubious documentation (return type is void...)
1132   ***  information will be.  returns -1 if solver gutless.  This is provided  */
  ***  principally to facilitate debugging a little.  
  **/  
1133    
1134  extern void slv_presolve(slv_system_t sys);  extern void slv_presolve(slv_system_t sys);
1135  /**<  /**<
1136   ***  <!--  slv_presolve(sys)                                          -->      Prepares the system for solving.  This must be called before the
1137   ***  <!--  slv_system_t sys;                                          -->      system is solved, but after everything about the system is set up
1138   ***      (i.e. variables and relations cannot be changed IN ANY WAY, objective
1139   ***  Prepares the system for solving.  This must be called before the      function cannot be modified, boundaries cannot be modified, or even
1140   ***  system is solved, but after everything about the system is set up      repermuted, and a new solver cannot be selected: some parameters may
1141   ***  (i.e. variables and relations cannot be changed IN ANY WAY, objective      be modified, they will be marked as such).  The system essentially
1142   ***  function cannot be modified, boundaries cannot be modified, or even      becomes "read-only".  If anything is modified after slv_presolve was
1143   ***  repermuted, and a new solver cannot be selected: some parameters may      called, slv_presolve must be called again before solving (EXCEPTIONS:
1144   ***  be modified, they will be marked as such).  The system essentially      slv_resolve may do for a certain restricted class of changes). @par
1145   ***  becomes "read-only".  If anything is modified after slv_presolve was  
1146   ***  called, slv_presolve must be called again before solving (EXCEPTIONS:      It is at this point that the variable list is created if it does not
1147   ***  slv_resolve may do for a certain restricted class of changes).<br><br>      already exist and the newly created variables are indexed in the
1148   ***      order they end up.  The relation list is indexed as well in the order
1149   ***  It is at this point that the variable list is created if it does not      it is received. @par
1150   ***  already exist and the newly created variables are indexed in the  
1151   ***  order they end up.  The relation list is indexed as well in the order      Among other things, this function will perform structural analysis
1152   ***  it is received.<br><br>      so that structural analysis flags in the status will be accurate.
1153   ***  */
  ***  Among other things, this function will perform structural analysis  
  ***  so that structural analysis flags in the status will be accurate.  
  **/  
1154    
1155  extern void slv_resolve(slv_system_t sys);  extern void slv_resolve(slv_system_t sys);
1156  /**<  /**<
1157   ***  <!--  slv_resolve(sys)                                           -->      This function re-prepares the system for solving.  This function may
1158   ***  <!--  slv_system_t sys;                                          -->      be used instead of slv_presolve, provided the system was partially
1159   ***      or completely solved before, and then the only changes to the system
1160   ***  This function re-prepares the system for solving.  This function may      since are as follows:
1161   ***  be used instead of slv_presolve, provided the system was partially  
1162   ***  or completely solved before, and then the only changes to the system      @li  any parameter except "partition".
1163   ***  since are as follows:      @li  variable values.
1164   ***     - any parameter except "partition".      @li  variable nominal values.
1165   ***     - variable values.      @li  variable bounds.
1166   ***     - variable nominal values.  
1167   ***     - variable bounds.      In particular, the following changes are NOT allowed:
1168   ***  
1169   ***  In particular, the following changes are NOT allowed:      @li  variable fixed flag.
1170   ***     - variable fixed flag.      @li  relation included flag.
1171   ***     - relation included flag.      @li  variable/relation list contents, including order.  Also, the
1172   ***     - variable/relation list contents, including order.  Also, the          variable/relation indices must continue to be consistent with
1173   ***       variable/relation indices must continue to be consistent with          the list.
1174   ***       the list.      @li  definition of relations, objective function, and boundaries:
1175   ***     - definition of relations, objective function, and boundaries:          including structural rearrangement on relations, although any
1176   ***       including structural rearrangement on relations, although any          expression may be simplified.
1177   ***       expression may be simplified.  
1178   ***      This function is considerably more efficient when it is usable.
1179   ***  This function is considerably more efficient when it is usable.  */
  **/  
1180    
1181  extern void slv_iterate(slv_system_t sys);  extern void slv_iterate(slv_system_t sys);
1182  /**<  /**<
1183   ***  Performs one iteration toward the ultimate solution (or      Performs one iteration toward the ultimate solution (or
1184   ***  failure thereof) of the system.  The user can obtain information      failure thereof) of the system.  The user can obtain information
1185   ***  from the status and from the variables and relations themselves      from the status and from the variables and relations themselves
1186   ***  (some care should be taken in examining the residuals of relations;      (some care should be taken in examining the residuals of relations;
1187   ***  they may not be up to date).  The user may not modify the system in      they may not be up to date).  The user may not modify the system in
1188   ***  any way between iterations (i.e. you may look, but don't touch: see      any way between iterations (i.e. you may look, but don't touch: see
1189   ***  slv_presolve()).  See also slv_solve().      slv_presolve()).  See also slv_solve().
1190   **/  */
1191    
1192  extern void slv_solve(slv_system_t sys);  extern void slv_solve(slv_system_t sys);
1193  /**<  /**<
1194   ***  <!--  slv_iterate(sys)                                           -->      Attempts to solve the entire system in one shot (i.e.
1195   ***  <!--  slv_solve(sys)                                             -->      performs as many iterations as needed or allowed).  For some solvers,
1196   ***  <!--  slv_system_t sys;                                          -->      slv_iterate() and slv_solve() may mean the same thing.
1197   ***  */
  ***  Attempts to solve the entire system in one shot (i.e.  
  ***  performs as many iterations as needed or allowed).  For some solvers,  
  ***  slv_iterate() and slv_solve() may mean the same thing.  
  **/  
1198    
1199  extern void slv_destroy_client(slv_system_t sys);  extern void slv_destroy_client(slv_system_t sys);
1200  /**<  /**<
1201   ***  <!--  slv_destroy_client(sys)                                    -->      Destroy the client token of slv_system_t. It does not deallocate
1202   ***  <!--  slv_system_t sys;                                          -->      the allocated data space of sys
1203   ***  Destroy the client token of slv_system_t. It does not deallocate  */
  ***  the allocated data space of sys  
  **/  
1204    
 /* THIS CALL SHOULD GO AWAY */  
1205  extern boolean slv_change_basis(slv_system_t,int32,mtx_range_t *);  extern boolean slv_change_basis(slv_system_t,int32,mtx_range_t *);
1206  /**<  /**<
1207   *** <!--  slv_change_basis (sys,index,rng);                           -->      Move var (given by index #) to the unassigned region (far right)
1208   *** <!--  slv_system_t sys;                                           -->      of the solver matrix if possible. returns FALSE if impossible
1209   *** <!--  int32 index;                                                -->      because structural infeasibility would occur or because solver selected
1210   *** <!--  mtx_range_t *rng;                                           -->      won't do it.
1211   ***      
1212   ***  Move var (given by index #) to the unassigned region (far right)      @deprecated THIS CALL SHOULD GO AWAY
1213   ***  of the solver matrix if possible. returns FALSE if impossible  */
  ***  because structural infeasibility would occur or because solver selected  
  ***  won't do it.  
  ***  
  ***  @todo THIS CALL SHOULD GO AWAY  
  **/  
1214    
1215  extern void slv_print_output(FILE *fp, slv_system_t sys);  extern void slv_print_output(FILE *fp, slv_system_t sys);
1216  /**<  /**<
1217   ***  Start of some report generation routines. For now just prints out      Start of some report generation routines. For now just prints out
1218   ***  the variable values and residuals at the moment.      the variable values and residuals at the moment.
1219   ***  
1220   ***  @todo Will be made more general in the future.      @TODO make more general in the future.
1221   **/  */
1222    
1223  #endif  /* ASC_SLV_CLIENT_H */  #endif  /* ASC_SLV_CLIENT_H */
1224    
Legend:
Removed from v.125  
changed lines
  Added in v.126
john.pye@anu.edu.au
 ViewVC Help
Powered by ViewVC 1.1.22