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 |
|