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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1068 - (show annotations) (download) (as text)
Mon Jan 8 04:45:47 2007 UTC (15 years, 5 months ago) by johnpye
File MIME type: text/x-chdr
File size: 51639 byte(s)
Fixed some ASC_PANIC calls in atomvalue.c
Removed some <!-- --> comments from list.h
Added flagging of 'deriv' vars in analyse.c (no new lists are added though)
Created separate doxygen module 'Analyse' (only affect C comments)
Fixed return codes in slv9a.c, as well as some FPRINTFs.
Cleaned up some documentation in slv_client.h.
Removed var_diff, var_set_diff flag stuff.
Added docstring for Integrator_getEngines in python wrapper.

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

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