/[ascend]/trunk/ascend4/solver/var.h
ViewVC logotype

Contents of /trunk/ascend4/solver/var.h

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

Name Value
svn:executable *

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