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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 34 - (show annotations) (download) (as text)
Sun Dec 26 20:35:09 2004 UTC (19 years, 5 months ago) by ben.allan
File MIME type: text/x-chdr
File size: 20267 byte(s)
fixed missing close comment in the two files i did by hand.
1 /*
2 * SLV: Ascend Numeric Solver
3 * by Karl Michael Westerberg
4 * Created: 2/6/90
5 * Version: $Revision: 1.26 $
6 * Version control file: $RCSfile: var.h,v $
7 * Date last modified: $Date: 1998/03/30 22:07:10 $
8 * Last modified by: $Author: rv2a $
9 *
10 * This file is part of the SLV solver.
11 *
12 * Copyright (C) 1990 Karl Michael Westerberg
13 * Copyright (C) 1993 Joseph Zaher
14 * Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan
15 *
16 * The SLV solver is free software; you can redistribute
17 * it and/or modify it under the terms of the GNU General Public License as
18 * published by the Free Software Foundation; either version 2 of the
19 * License, or (at your option) any later version.
20 *
21 * The SLV solver is distributed in hope that it will be
22 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
24 * General Public License for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with the program; if not, write to the Free Software Foundation,
28 * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
29 * COPYING. COPYING is found in ../compiler.
30 *
31 */
32 /**
33 * Contents: Variable module (ascend)
34 *
35 * Authors: Karl Westerberg
36 * Joseph Zaher
37 *
38 * Dates: 06/90 - original version
39 * 01/94 - added var_make_name() to create a copy of the
40 * instance name
41 * 04/94 - added var_apply_filter() which uses the new
42 * var_filter_t data structure for perfoming all
43 * variable filtering needs (eliminating the
44 * filter module)
45 * 08/94 - added var_BackendTokens_to_vars. BAA.
46 *
47 * Description: This is the ascend version of the var module. This
48 * version should be used by any user who receives his/her
49 * equations indirectly from an instance tree created by the
50 * ASCEND compiler.
51 *
52 * The idea of a var makes no sense outside the context of
53 * a slv_system_t, so some of the functions here may require
54 * the passing of a slv_system_t with the var.
55 */
56
57 #ifndef var__already_included
58 #define var__already_included
59
60 /*
61 * requires #include <stdio.h>
62 * requires #include "base.h"
63 * requires #include "slv_types.h"
64 */
65
66 /*
67 * The first section of flagbit definitions are those flags to be
68 * set by the server. Clients should not mess with them unless
69 * they are very, very smart.
70 */
71 #define VAR_REAL 0x1
72 /**< don't know what this is good for. */
73 #define VAR_INCIDENT 0x2
74 /**< is this variable incident on some equation in the slv_system? */
75 #define VAR_PVAR 0x4
76 /**< do we think this var a 'solver_par'? */
77 #define VAR_SVAR 0x8
78 /**< do we think this var a 'solver_var'? */
79 #define VAR_INTEGER 0x10
80 /**< do we think this var a solver_integer? */
81 #define VAR_BINARY 0x20
82 /**< do we think this var a solver_binary? */
83 #define VAR_SEMICONT 0x40
84 /**< do we think this var a solver_semi(continuous) ? */
85
86 /*
87 * The remaining flagbit definitions are those flags to be
88 * manipulated by registered clients. Unregistered clients
89 * should not change these bits unless the manner in which
90 * they affect the bits is explained in the header for the
91 * unregistered client.
92 */
93
94 #define VAR_PARAM 0x1000
95 /**< VAR_PARAM is this variable considered parametric currently? */
96
97 #define VAR_FIXED 0x2000
98 /**< VAR_FIXED is this variable considered fixed currently? */
99
100 #define VAR_INBLOCK 0x4000
101 /**< VAR_INBLOCK is this var in the columns of the block we are
102 currently solving? */
103
104 #define VAR_INTERFACE 0x8000
105 /**< VAR_INTERFACE is this var an interface var currently? */
106
107 #define VAR_RELAXED 0x10000
108 /**< VAR_RELAXED is this var currently a relaxed int or binary or semi var? */
109
110 #define VAR_ACTIVE 0x20000
111 /**< VAR_ACTIVE is this var currently a part of my problem */
112
113 #define VAR_NONBASIC 0x40000
114 /**< VAR_NONBASIC is this var currently an independent variable
115 * (optimization)? */
116
117 #define VAR_ACTIVE_AT_BND 0x80000
118 /**< VAR_ACTIVE_AT_BND is this var active in some of the subregions
119 * neighboring the boundary on which the problem
120 * currently lies ? */
121
122 #define VAR_ELIGIBLE 0x100000
123 /**< VAR_ELIGIBLE is this variable eligible to be fixed (globally)? */
124
125 #define VAR_ELIGIBLE_IN_SUBREGION 0x200000
126 /**< VAR_ELIGIBLE_IN_SUBREGION is this variable eligible to be fixed (in current
127 * subregion) ? */
128
129 #define VAR_POTENTIALLY_FIXED 0x400000
130 /**< VAR_POTENTIALLY_FIXED this bit is auxiliar while iteratively and recurively
131 * we are performing a combinatorial search, looking
132 * for a consitent partition for all the alternatives
133 * in an conditional model */
134
135 #define VAR_INCIDENT_IN_CASE 0x800000
136 /**< VAR_INCIDENT_IN_CASE is this variable incident in some relation of a
137 * CASE in a WHEN statement ?. This is for purposes of
138 * simplfying the analysis of conditional models
139 */
140
141 struct var_variable {
142 SlvBackendToken ratom; /**< the associated ascend ATOM */
143 struct rel_relation **incidence;
144 /**< array rels which contain var */
145 int32 n_incidences; /**< length of incidence. */
146 int32 sindex; /**< index in the solver clients list (often column index) */
147 int32 mindex; /**< index in the slv_system_t master list */
148 uint32 flags; /**< batch of binary flags. The bit positions are as above */
149 };
150
151 /**<
152 * Finally, we have a real structure so that we aren't hanging stuff
153 * of the global instance tree. Do not dereference this structure except
154 * via macros/functions, because we make no commitments about being
155 * backward compatible with such code.
156 *
157 * struct Instance * and struct var_variable *are no longer synonymous!
158 */
159
160 typedef struct var_filter_structure {
161 uint32 matchbits;
162 uint32 matchvalue;
163 } var_filter_t;
164
165
166 #define var_NO_UPPER_BOUND MAXDOUBLE
167 #define var_NO_LOWER_BOUND (-MAXDOUBLE/2)
168
169 #ifdef NDEBUG
170 #define var_instance(v) ((v)->ratom)
171 #define var_set_instance(v,i) ((v)->ratom = (i))
172 #else
173 #define var_instance(v) var_instanceF(v)
174 #define var_set_instance(v,i) var_set_instanceF((v),(i))
175 #endif /* NDEBUG */
176
177 extern SlvBackendToken var_instanceF(const struct var_variable *);
178 extern void var_set_instanceF(struct var_variable *,SlvBackendToken );
179 /**<
180 * i = var_instance(var);
181 * var_set_instance(var,i);
182 * struct var_variable *var;
183 * SlvBackendToken i;
184 * Returns/sets the ATOM instance associated with the variable.
185 */
186
187 extern char *var_make_name(const slv_system_t,const struct var_variable *);
188 extern char *var_make_xname(const struct var_variable *);
189 /**<
190 * name = var_make_name(sys,var)
191 * name = var_make_xname(var)
192 * struct var_variable *var;
193 *
194 * Creates and returns a sufficiently large string storing the
195 * qualified name of var as known by the solver instance tree.
196 * If the instance is not found, "?" is returned. The string
197 * should be destroyed when no longer in use.
198 * var_make_xname returns the index name, eg x23 rather than full name.
199 *
200 * The name of a var is context dependent, so you have to provide the
201 * slv_system_t from which you got the var.
202 */
203
204 extern void var_write_name(const slv_system_t,
205 const struct var_variable *,FILE *);
206 /**<
207 * var_write_name(sys,var,file);
208 * Writes a name to the file given. Handles NULL inputs gracefully.
209 * Does not print any whitespace, including carriage returns.
210 * Is faster than slv_print_var_name.
211 * If sys is NULL, writes full ascend name. If file or var is NULL
212 * does not write.
213 */
214
215 void var_destroy(struct var_variable *);
216 /**<
217 * var_destroy(var);
218 * struct var_variable *var;
219 *
220 * Since someone else allocates vars en masse, this just sets
221 * our integrity check to ERROR.
222 */
223
224 #ifdef NDEBUG
225 #define var_mindex(v) (v)->mindex
226 #define var_set_mindex(v,n) (v)->mindex = (n)
227 #else
228 #define var_mindex(v) var_mindexF(v)
229 #define var_set_mindex(v,n) var_set_mindexF((v),(n))
230 #endif /* NDEBUG */
231
232 extern int32 var_mindexF(const struct var_variable *);
233 extern void var_set_mindexF(struct var_variable *,int32);
234 /**<
235 * index = var_mindex(var)
236 * var_set_mindex(var,index)
237 * int32 index;
238 * struct var_variable *var;
239 *
240 * Gets/sets the index of the variable as it appears
241 * in a variable list. The index is also used to assign
242 * the variable to a specific original column of a matrix.
243 */
244
245 #ifdef NDEBUG
246 #define var_sindex(v) (v)->sindex
247 #define var_set_sindex(v,n) (v)->sindex = (n)
248 #else
249 #define var_sindex(v) var_sindexF(v)
250 #define var_set_sindex(v,n) var_set_sindexF((v),(n))
251 #endif /* NDEBUG */
252
253 extern int32 var_sindexF(const struct var_variable *);
254 extern void var_set_sindexF(struct var_variable *,int32);
255 /**<
256 * index = var_sindex(var)
257 * var_set_sindex(var,index)
258 * int32 index;
259 * struct var_variable *var;
260 *
261 * Gets/sets the index of the variable as it appears
262 * in a solvers variable list. The index is also used to assign
263 * the variable to a specific original column of a matrix.
264 */
265
266 extern real64 var_value(const struct var_variable *);
267 extern void var_set_value(struct var_variable *,real64);
268 /**<
269 * value = var_value(var)
270 * var_set_value(var,value)
271 * real64 value;
272 * struct var_variable *var;
273 *
274 * Gets/sets the value of the variable.
275 */
276
277 extern real64 var_nominal(struct var_variable *);
278 extern void var_set_nominal(struct var_variable *,real64);
279 /**<
280 * nominal = var_nominal(var)
281 * var_set_nominal(var,nominal)
282 * real64 nominal;
283 * struct var_variable *var;
284 *
285 * Gets/sets the nominal value of the variable.
286 * If no nominal field in var, returns 1.0.
287 */
288
289 extern real64 var_lower_bound(struct var_variable *);
290 extern void var_set_lower_bound(struct var_variable *,real64);
291 /**<
292 * lower_bound = var_lower_bound(var)
293 * var_set_lower_bound(var,lower_bound)
294 * real64 lower_bound;
295 * struct var_variable *var;
296 *
297 * Gets/sets the lower bound value of the variable.
298 */
299
300 extern real64 var_upper_bound(struct var_variable *);
301 extern void var_set_upper_bound(struct var_variable *,real64);
302 /**<
303 * upper_bound = var_upper_bound(var)
304 * var_set_upper_bound(var,upper_bound)
305 * real64 upper_bound;
306 * struct var_variable *var;
307 *
308 * Gets/sets the upper bound value of the variable.
309 */
310
311 #ifdef NDEBUG
312 #define var_n_incidences(r) ((r)->n_incidences)
313 #define var_set_incidences(r,n,ilist) \
314 (r)->n_incidences=(n); (r)->incidence = (ilist)
315 #else
316 #define var_n_incidences(r) var_n_incidencesF(r)
317 #define var_set_incidences(r,n,ilist) var_set_incidencesF((r),(n),(ilist))
318 #endif /* NDEBUG */
319
320 extern int32 var_n_incidencesF(struct var_variable *);
321 extern void var_set_incidencesF(struct var_variable *,
322 int32,struct rel_relation **);
323 /**<
324 * var_n_incidences(var)
325 * var_set_incidences(var,n,ilist) //SERVER ONLY
326 * struct var_variable *var;
327 * struct rel_relation **ilist;
328 * int32 n;
329 *
330 * var_n_incidences returns the length of the incidence_list.
331 * Not everything in the incidence list is necessarily a
332 * variable for your particular solver -- check the flags.
333 * Solver clients should not call var_set_incidences,
334 * it is only for use by constructors of bridges to varation
335 * back ends.
336 */
337
338 extern const struct rel_relation **var_incidence_list(struct var_variable *);
339 extern struct rel_relation
340 **var_incidence_list_to_modify(struct var_variable *);
341 /**<
342 * va = var_incidence_list(var)
343 * struct var_variable *var;
344 * struct rel_relation **va;
345 *
346 * Returns a pointer to an array var_n_incidences(var) long of vars.
347 * Each element of the array is a struct rel_relation *.
348 * Check the var sindex to see where each might go in a jacobian.
349 * If there is no incidence, NULL is returned.
350 * Pointers in this array will be unique.
351 * The list belongs to the varation. Do not destroy it. Do not change it.
352 *
353 * RA IS NOT a NULL-TERMINATED LIST.
354 */
355
356
357
358 #ifdef NDEBUG
359 #define var_flags(v) ((v)->flags)
360 #define var_set_flags(v,f) ((v)->flags = (f))
361 #else
362 #define var_flags(v) var_flagsF(v)
363 #define var_set_flags(v,f) var_set_flagsF((v),(f))
364 #endif /* NDEBUG */
365
366
367 extern uint32 var_flagsF(const struct var_variable *);
368 extern void var_set_flagsF(struct var_variable *,uint32);
369 /**<
370 * var_flags(var);
371 * var_set_flags(var,flags);
372 * struct var_variable *var;
373 * uint32 flags;
374 *
375 * var_flags(var) returns the flags field of the var.
376 * var_set_flags(var,flags) sets the entire flag field to the
377 * value of flags given. This flags value should be composed
378 * of the var_xxx values defined above.
379 */
380
381 extern uint32 var_flagbit(const struct var_variable *,const uint32);
382 /**<
383 * var_flagbit(rel,name);
384 * struct var_variable *rel;
385 * uint32 name;
386 * name should be a VAR_xx flag defined above)
387 * Returns the value of the bit specified from the variable flags.
388 */
389
390 extern void var_set_flagbit(struct var_variable *,uint32, uint32);
391 /**<
392 * struct var_variable *var;
393 * unsigned int32 NAME,oneorzero;
394 * var_set_flagbit(var,NAME,oneorzero)
395 *
396 * Sets the bit, which should be referred to by its macro name,
397 * on if oneorzero is >0 and off is oneorzero is 0.
398 * The macro names are the defined up at the top of this file.
399 *
400 * Example: var_set_flags(var,VAR_PARTITION,1) turns on the
401 * VAR_PARTITION bit.
402 * What it really does is:
403 * if (oneorzero) {
404 * var->flags |= field;
405 * } else {
406 * var->flags &= ~field;
407 * }
408 */
409
410 /**<
411 * At present there is some insanity about asking the instance tree
412 * vs asking our data structure about the flag values. This needs to
413 * be fixed. In the process of that fix, we should establish a
414 * protocol that means vars/rels never need to look back at ATOM
415 * instances to be queried during the solution process. Rather, we
416 * need to establish a process in which the var list tells all its
417 * atoms about the solver derived values or the var list updates
418 * its values and flags from the instance tree.
419 * There is a counterpart exercise that needs to go on in the
420 * rel module so that (for remote processing) it is possible to
421 * do everything without looking back at the instance tree.
422 * At present, we will always keep VAR_FIXED in sync with the
423 * instance tree, but the instance tree is the leader.
424 * 6/96. baa
425 */
426
427 extern int32 var_apply_filter(const struct var_variable *,
428 const var_filter_t *);
429 /**<
430 * value = var_apply_filter(var,filter)
431 * int32 value;
432 * struct var_variable *var;
433 * var_filter_t *filter;
434 *
435 * Returns 1 if filter and var flags are compatible, 0 elsewise.
436 * See the filter description in rel.h. This is exactly the same.
437 */
438
439 extern uint32 var_fixed(struct var_variable *);
440 extern void var_set_fixed(struct var_variable *, uint32);
441 extern uint32 var_relaxed(struct var_variable *);
442 extern void var_set_relaxed(struct var_variable *, uint32);
443 extern uint32 var_interface(struct var_variable *);
444 extern void var_set_interface(struct var_variable *, uint32);
445 /**<
446 * fixed = var_fixed(var)
447 * var_set_fixed(var,fixed)
448 * uint32 fixed;
449 * struct var_variable *var;
450 *
451 * Gets/sets the fixed/relaxed/interface flag of the variable. This
452 * has side effects in the ascend instance, with which
453 * we are keeping the bits in sync.
454 */
455
456 #ifdef NDEBUG
457 #define var_in_block(v) ((v)->flags & VAR_INBLOCK)
458 #define var_incident(v) ((v)->flags & VAR_INCIDENT)
459 #define var_active(v) ((v)->flags & VAR_ACTIVE)
460 #define var_nonbasic(v) ((v)->flags & VAR_NONBASIC)
461 #define var_active_at_bnd(v) ((v)->flags & VAR_ACTIVE_AT_BND)
462 #define var_eligible(v) ((v)->flags & VAR_ELIGIBLE)
463 #define var_eligible_in_subregion(v) ((v)->flags & VAR_ELIGIBLE_IN_SUBREGION)
464 #define var_incident_in_case(v) ((v)->flags & VAR_INCIDENT_IN_CASE)
465 #define var_potentially_fixed(v) ((v)->flags & VAR_POTENTIALLY_FIXED)
466 #else
467 #define var_in_block(v) var_flagbit((v),VAR_INBLOCK)
468 #define var_incident(v) var_flagbit((v),VAR_INCIDENT)
469 #define var_active(v) var_flagbit((v),VAR_ACTIVE)
470 #define var_nonbasic(v) var_flagbit((v),VAR_NONBASIC)
471 #define var_active_at_bnd(v) var_flagbit((v),VAR_ACTIVE_AT_BND)
472 #define var_eligible(v) var_flagbit((v),VAR_ELIGIBLE)
473 #define var_eligible_in_subregion(v) var_flagbit((v),VAR_ELIGIBLE_IN_SUBREGION)
474 #define var_incident_in_case(v) var_flagbit((v),VAR_INCIDENT_IN_CASE)
475 #define var_potentially_fixed(v) var_flagbit((v),VAR_POTENTIALLY_FIXED)
476 #endif /* NDEBUG */
477 #define var_set_in_block(v,b) var_set_flagbit((v),VAR_INBLOCK,(b))
478 #define var_set_incident(v,b) var_set_flagbit((v),VAR_INCIDENT,(b))
479 #define var_set_interface(v,b) var_set_flagbit((v),VAR_INTERFACE,(b))
480 #define var_set_active(v,b) var_set_flagbit((v),VAR_ACTIVE,(b))
481 #define var_set_nonbasic(v,b) var_set_flagbit((v),VAR_NONBASIC,(b))
482 #define var_set_active_at_bnd(v,b) var_set_flagbit((v),VAR_ACTIVE_AT_BND,(b))
483 #define var_set_eligible(v,b) var_set_flagbit((v),VAR_ELIGIBLE,(b))
484 #define var_set_eligible_in_subregion(v,b) var_set_flagbit((v),VAR_ELIGIBLE_IN_SUBREGION,(b))
485 #define var_set_incident_in_case(v,b) var_set_flagbit((v),VAR_INCIDENT_IN_CASE,(b))
486 #define var_set_potentially_fixed(v,b) var_set_flagbit((v),VAR_POTENTIALLY_FIXED,(b))
487
488 /**<
489 * incident = var_incident(var)
490 * var_set_incident(var,incident)
491 * uint32 incident;
492 * struct var_variable *var;
493 *
494 * Gets/sets the incident flag of the variable.
495 */
496 /**<
497 * in_block = var_in_block(var)
498 * var_set_in_block(var,in_block)
499 * uint32 in_block;
500 * struct var_variable *var;
501 *
502 * Gets/sets the in_block flag of the variable.
503 */
504
505 extern struct var_variable **var_BackendTokens_to_vars(slv_system_t,
506 SlvBackendToken *, int32);
507 /**<
508 * varp = var_BackendTokens_to_vars(sys,tokenlist,len);
509 * slv_system_t sys; System to get indexing from.
510 * SlvBackendToken tokenlist[]; Array of backend tokens.
511 * int32 len; Tokenlist size.
512 * struct var_variable *varp[]; aka **varp;
513 *
514 * varp is NULL iff something is amiss, OTHERWISE it
515 * contains len struct var_variable * s.
516 * The user should free the array varp when done with it.
517 * Some entries in the array varp may be NULL if the tokenlist
518 * contains a token which is not from the sys given.
519 * tokenlist[i] <--> varp[i];
520 *
521 * The whole point of a slv_system_t is to isolate the client from
522 * the compiler backend. Clients who find themselves in need of
523 * this function are very much in need of rethinking as well.
524 * For that reason, among others, this function is not heavily
525 * optimized, it is however reasonable for 1-off jobs.
526 *
527 * CPU Cost = k1*complexity of the instance under sys +
528 * k2*number of vars in sys + k3*len.
529 *
530 * BUGS: hasn't been through verification and testing. SQA asleep.
531 */
532
533 /*
534 * What constitutes a solver_var (and some other interesting types)
535 * is controlled by the ascend server via the following functions.
536 * Clients shouldn't use these.
537 */
538
539 #define SOLVER_VAR_STR "solver_var"
540 #define SOLVER_INT_STR "solver_int"
541 #define SOLVER_BINARY_STR "solver_binary"
542 #define SOLVER_SEMI_STR "solver_semi"
543
544 #define solver_par(i) (0)
545
546 extern boolean solver_var(SlvBackendToken);
547 extern boolean solver_int(SlvBackendToken);
548 extern boolean solver_binary(SlvBackendToken);
549 extern boolean solver_semi(SlvBackendToken);
550 /**<
551 * e.g. if (solver_var(inst)) {}
552 * SlvBackendToken inst;
553 * Returns true if the instance in question matches the currently
554 * known definition of solver_var.
555 * Ditto for solver_int, solver_binary, and solver_semi.
556 * Note that these definitions involve refinement, so
557 * solver_var will report TRUE on variables matching any of
558 * these types, while solver_binary will only be TRUE on binaries.
559 * hierarchy is solvervar-\----solver_int-----solver_binary
560 * \-solver_semi
561 *
562 * SERVER ONLY. clients should just look at the flagbits.
563 */
564
565 extern boolean set_solver_types(void);
566 /**<
567 * Sets (changes) the current definition of solver_var to match
568 * the current library. Returns 1 if unsuccessful, 0 if ok.
569 * If 1, it is useless to invoke the solvers.
570 * Also sets all the related types listed above.
571 */
572 #endif /* __VAR_H__SEEN__ */

Properties

Name Value
svn:executable *

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