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

Annotation of /trunk/ascend4/solver/discrete.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1 - (hide annotations) (download) (as text)
Fri Oct 29 20:54:12 2004 UTC (17 years, 9 months ago) by aw0a
File MIME type: text/x-chdr
File size: 16194 byte(s)
Setting up web subdirectory in repository
1 aw0a 1 /*
2     * Discrete Variable Module
3     * by Vicente Rico-Ramirez
4     * Created: 06/96
5     * Version: $Revision: 1.7 $
6     * Version control file: $RCSfile: discrete.h,v $
7     * Date last modified: $Date: 1998/03/30 22:06:54 $
8     * Last modified by: $Author: rv2a $
9     *
10     * This file is part of the SLV solver.
11     *
12     * The SLV solver is free software; you can redistribute
13     * it and/or modify it under the terms of the GNU General Public License as
14     * published by the Free Software Foundation; either version 2 of the
15     * License, or (at your option) any later version.
16     *
17     * The SLV solver is distributed in hope that it will be
18     * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
19     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20     * General Public License for more details.
21     *
22     * You should have received a copy of the GNU General Public License
23     * along with the program; if not, write to the Free Software Foundation,
24     * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
25     * COPYING. COPYING is found in ../compiler.
26     *
27     */
28    
29     /*
30     * Contents: Discrete Variable module (ascend)
31     *
32     * Dates: 06/96 - original version
33     *
34     * Description: This is the ascend version of the bvar module. This
35     * version should be used by any user who receives his/her
36     * equations indirectly from an instance tree created by the
37     * ASCEND compiler.
38     *
39     */
40    
41     #ifndef dis__already_included
42     #define dis__already_included
43     /*
44     * requires #include <stdio.h>
45     * requires #include "base.h"
46     * requires #include "slv_types.h"
47     * requires #include "list.h"
48     */
49    
50    
51     enum discrete_kind {
52     e_dis_boolean_t,
53     e_dis_integer_t,
54     e_dis_symbol_t,
55     e_dis_error_t
56     };
57    
58     struct dis_discrete {
59     enum discrete_kind t; /* kind of discrete variable */
60     SlvBackendToken datom; /* the associated ascend ATOM */
61     struct dis_discrete **sos; /* not implemented yet. Used to represent */
62     /* integer and symbols in terms of booleans */
63     struct dis_discrete *source; /* Not implemented yet. This would be used for
64     booleans, members of sos, to point back to
65     the variable which is using it */
66     struct gl_list_t *whens; /* whens in which this variable is used */
67     int32 range; /* Ranges for integer or symbols.Sme as above */
68     int32 cur_value; /* current value */
69     int32 pre_value; /* previous value */
70     int32 sindex; /* index in the solver clients list */
71     int32 mindex; /* index in the slv_system_t master list */
72     uint32 flags; /* batch of binary flags */
73     };
74    
75     /*
76     * Do not dereference this structure except
77     * via macros/functions, because we make no commitments about being
78     * backward compatible with such code.
79     */
80    
81     typedef struct dis_filter_structure {
82     uint32 matchbits;
83     uint32 matchvalue;
84     } dis_filter_t;
85    
86    
87     extern struct dis_discrete *dis_create(SlvBackendToken,
88     struct dis_discrete *);
89     /*
90     * dis_create(instance,newdis)
91     * struct dis_discrete *newdis;
92     * SlvBackendToken instance;
93     *
94     * Creates a discrete variable given the variable instance.
95     * If the discrete var supplied is NULL, we allocate the memory for the
96     * discrete var we return, else we just init the memory you hand us and
97     * return it to you.
98     * We set the fields instance. Setting the rest of the information
99     * is the job of the bridge building function between the ascend instance
100     * tree (or other discrete var back end) and the slv_system_t.
101     */
102    
103     #ifdef NDEBUG
104     #define dis_instance(dis) ((dis)->datom)
105     #define dis_set_instance(dis,i) ((dis)->datom = (i))
106     #else
107     #define dis_instance(dis) dis_instanceF(dis)
108     #define dis_set_instance(dis,i) dis_set_instanceF((dis),(i))
109     #endif /* NDEBUG */
110    
111    
112     extern SlvBackendToken dis_instanceF(const struct dis_discrete *);
113     extern void dis_set_instanceF(struct dis_discrete *,SlvBackendToken );
114     /*
115     * i = dis_instance(dis);
116     * dis_set_instance(dis,i);
117     * struct dis_discrete *dis;
118     * SlvBackendToken i;
119     * Returns/sets the ATOM instance associated with the variable.
120     */
121    
122     extern char *dis_make_name(const slv_system_t,const struct dis_discrete *);
123     extern char *dis_make_xname(const struct dis_discrete *);
124     /*
125     * name = dis_make_name(sys,dis)
126     * name = dis_make_xname(dis)
127     * struct dis_discrete *dis;
128     *
129     * Creates and returns a sufficiently large string storing the
130     * qualified name of var as known by the solver instance tree.
131     * If the instance is not found, "?" is returned. The string
132     * should be destroyed when no longer in use.
133     * dis_make_xname returns the index name, eg x23 rather than full name.
134     *
135     * The name of a dis is context dependent, so you have to provide the
136     * slv_system_t from which you got the dis.
137     */
138    
139     extern void dis_write_name(const slv_system_t,
140     const struct dis_discrete *,FILE *);
141     /*
142     * dis_write_name(sys,dis,file);
143     * Writes a name to the file given.
144     * Does not print any whitespace, including carriage returns.
145     * If sys is NULL, writes full ascend name. If file or var is NULL
146     * does not write.
147     */
148    
149     void dis_destroy(struct dis_discrete *);
150     /*
151     * dis_destroy(dis);
152     * struct dis_discrete *dis;
153     *
154     * Since someone else allocates dis en masse, this just sets
155     * our integrity check to ERROR.
156     */
157    
158     extern struct gl_list_t *dis_whens_list(struct dis_discrete *);
159     extern void dis_set_whens_list(struct dis_discrete *, struct gl_list_t *);
160     /*
161     * wlist = dis_whens_list(dis)
162     * dis_set_whens_list(dis,wlist)
163     * struct gl_list_t *wlist;
164     * struct dis_discrete *dis;
165     *
166     * Sets or retrieves the list of whens of the given dis
167     */
168    
169     #ifdef NDEBUG
170     #define dis_kind(dis) (dis)->t
171     #define dis_set_kind(dis,kind) (dis)->t = (kind)
172     #else
173     #define dis_kind(dis) dis_kindF(dis)
174     #define dis_set_kind(dis,kind) dis_set_kindF((dis),(kind))
175     #endif /* NDEBUG */
176    
177     extern enum discrete_kind dis_kindF(const struct dis_discrete *);
178     extern void dis_set_kindF(struct dis_discrete *, enum discrete_kind);
179     /*
180     * enum discrete_kind dis_kind(dis);
181     * void dis_set_kind(dis,kind);
182     * const struct dis_discrete *dis;
183     * enum discrete_kind kind;
184     * Gets/sets the enumerated type that indicates the type of dis.
185     */
186    
187     #ifdef NDEBUG
188     #define dis_mindex(dis) (dis)->mindex
189     #define dis_set_mindex(dis,n) (dis)->mindex = (n)
190     #else
191     #define dis_mindex(dis) dis_mindexF(dis)
192     #define dis_set_mindex(dis,n) dis_set_mindexF((dis),(n))
193     #endif /* NDEBUG */
194    
195     extern int32 dis_mindexF(const struct dis_discrete *);
196     extern void dis_set_mindexF(struct dis_discrete *,int32);
197     /*
198     * index = dis_mindex(dis)
199     * dis_set_mindex(dis,index)
200     * int32 index;
201     * struct dis_discrete *dis;
202     *
203     * Gets/sets the index of the variable as it appears
204     * in a variable list.
205     */
206    
207     #ifdef NDEBUG
208     #define dis_sindex(dis) (dis)->sindex
209     #define dis_set_sindex(dis,n) (dis)->sindex = (n)
210     #else
211     #define dis_sindex(dis) dis_sindexF(dis)
212     #define dis_set_sindex(dis,n) dis_set_sindexF((dis),(n))
213     #endif /* NDEBUG */
214    
215     extern int32 dis_sindexF(const struct dis_discrete *);
216     extern void dis_set_sindexF(struct dis_discrete *,int32);
217     /*
218     * index = dis_sindex(dis)
219     * dis_set_sindex(dis,index)
220     * int32 index;
221     * struct dis_discrete *dis;
222     *
223     * Gets/sets the index of the variable as it appears
224     * in a solvers variable list.
225     */
226    
227     extern int32 dis_value(const struct dis_discrete *);
228     extern void dis_set_value(struct dis_discrete *,int32);
229     /*
230     * value = dis_value(dis)
231     * dis_set_value(dis,value)
232     * int32 value;
233     * struct dis_discrete *dis;
234     *
235     * Gets/sets the currrent value field of the discrete variable.
236     * dis_set_value also assigns the value before modification to
237     * the previous value field of the dis_discrete
238     */
239    
240    
241     extern void dis_set_inst_and_field_value(struct dis_discrete *,int32);
242     extern void dis_set_value_from_inst(struct dis_discrete *,struct gl_list_t *);
243     #define dis_set_boolean_value(dis,val) dis_set_inst_and_field_value(dis,val)
244     /*
245     * void dis_set_inst_and_field_value
246     * Set the current value of the dis_discrete and the value of
247     * the corresponding instance simultaneously. Such a value is
248     * passed as argument
249     * void dis_set_value_from_inst:
250     * Set the current value of a dis_discrete based on the value of the
251     * corresponding instance.
252     * In the case of symbols, dis_set_inst_and_field_value has no effect,
253     * since the value of a symbol instance is not a integer, but a symchar,
254     * and a solver client will never redefine it.
255     * If the token is constant, the asssignment wont be done and the
256     * value is not affected.
257     * the las function is particularly useful for symbol instances.
258     * It is used to assign integer values to the field
259     * value of a dis, using values coming from dis->datom where
260     * datom is a inst. In teh case of symbol, we get an "equivalent"
261     * integer value.
262     *
263     * They also assign the value before modification to
264     * the previous value field of the dis_discrete
265     */
266    
267    
268     extern int32 dis_previous_value(const struct dis_discrete *);
269     extern void dis_set_previous_value(struct dis_discrete *,int32);
270     /*
271     * value = dis_previous_value(dis)
272     * dis_set_previous_value(dis,value)
273     * int32 value;
274     * struct dis_discrete *dis;
275     *
276     * Gets/sets the previous value field of the discrete variable.
277     */
278    
279    
280     /*
281     * What constitutes a boolean_var
282     * is controlled by the ascend server via the following functions.
283     * Clients shouldn't use these.
284     */
285    
286     #define BOOLEAN_VAR_STR "boolean_var"
287    
288     extern boolean boolean_var(SlvBackendToken);
289    
290     /*
291     * e.g. if (boolean_var(inst)) {}
292     * SlvBackendToken inst;
293     * Returns true if the instance in question matches the currently
294     * known definition of boolean_var.
295     */
296    
297     extern boolean set_boolean_types(void);
298     /*
299     * Sets (changes) the current definition of boolean_var to match
300     * the current library. Returns 1 if unsuccessful, 0 if ok.
301     */
302    
303     extern int32 dis_nominal(struct dis_discrete *);
304     extern void dis_set_nominal(struct dis_discrete *,int32);
305     /*
306     * nominal = dis_nominal(dis)
307     * dis_set_nominal(dis,nominal)
308     * int32 nominal;
309     * struct dis_discrete *dis;
310     *
311     * Gets/sets the nominal value of the boolean variable.
312     * If no nominal field in dis, returns 1.
313     */
314    
315     extern uint32 dis_fixed(struct dis_discrete *);
316     extern void dis_set_fixed(struct dis_discrete *, uint32);
317     /*
318     * fixed = dis_fixed(dis)
319     * dis_set_fixed(dis,fixed)
320     * uint32 fixed;
321     * struct dis_discrete *dis;
322     *
323     * Gets/sets the fixed flag of the boolean variable. This
324     * has side effects in the ascend instance, with which
325     * we are keeping the bits in sync.
326     */
327    
328    
329     /*
330     * The section of flagbit definitions
331     */
332    
333     #define DIS_INCIDENT 0x1
334     #define DIS_INWHEN 0x2
335     #define DIS_BVAR 0x4
336     #define DIS_CONST 0x8
337     #define DIS_FIXED 0x10
338     #define DIS_INBLOCK 0x20
339     #define DIS_ACTIVE 0x40
340     #define DIS_BOOLEAN 0x80
341     #define DIS_VAL_MODIFIED 0x100
342     #define DIS_CHANGES_STRUCTURE 0x200
343    
344     /*
345     * DIS_INCIDENT is this variable incident on some equation in
346     * the slv_system?
347     * DIS_INWHEN is this variable in some WHEN in the slv_system?
348     * DIS_BVAR do we think this var a 'boolean_var'?
349     * DIS_CONST is this discrete variable a constant
350     * DIS_FIXED is this variable considered fixed currently?
351     * DIS_INBLOCK
352     * DIS_ACTIVE is this variable currently active ?
353     * DIS_BOOLEAN is this variable of type e_dis_boolean_t ?
354     * DIS_VAL_MODIFIED Did the value of this variable change after the
355     * last logical solution ?
356     * DIS_CHANGES_STRUCTURE Is this discrete variable associated with a WHEN
357     * changes the structural analysis of a conditional
358     * model
359     */
360    
361     #ifdef NDEBUG
362     #define dis_flags(dis) ((dis)->flags)
363     #define dis_set_flags(dis,f) ((dis)->flags = (f))
364     #else
365     #define dis_flags(dis) dis_flagsF(dis)
366     #define dis_set_flags(dis,f) dis_set_flagsF((dis),(f))
367     #endif /* NDEBUG */
368    
369     extern uint32 dis_flagsF(const struct dis_discrete *);
370     extern void dis_set_flagsF(struct dis_discrete *,uint32);
371     /*
372     * dis_flags(dis);
373     * dis_set_flags(dis,flags);
374     * struct dis_discrete *dis;
375     * uint32 flags;
376     *
377     * dis_flags(dis) returns the flags field of the var.
378     * dis_set_flags(dis,flags) sets the entire flag field to the
379     * value of flags given. This flags value should be composed
380     * of the dis_xxx values defined above.
381     */
382    
383     extern uint32 dis_flagbit(const struct dis_discrete *,const uint32);
384     /*
385     * dis_flagbit(dis,name);
386     * struct dis_discrete *dis;
387     * uint32 name;
388     * name should be a DIS_xx flag defined above)
389     * Returns the value of the bit specified from the variable flags.
390     */
391    
392     extern void dis_set_flagbit(struct dis_discrete *,uint32, uint32);
393     /*
394     * struct dis_discrete *dis;
395     * unsigned int NAME,oneorzero;
396     * dis_set_flagbit(dis,NAME,oneorzero)
397     *
398     * Sets the bit, which should be referred to by its macro name,
399     * on if oneorzero is >0 and off is oneorzero is 0.
400     * The macro names are the defined up at the top of this file.
401     */
402    
403     extern int32 dis_apply_filter(const struct dis_discrete *,
404     const dis_filter_t *);
405     /*
406     * value = dis_apply_filter(dis,filter)
407     * int32 value;
408     * struct dis_discrete *dis;
409     * dis_filter_t *filter;
410     *
411     * Returns 1 if filter and var flags are compatible, 0 elsewise.
412     * See the filter description in rel.h. This is exactly the same.
413     */
414    
415     #ifdef NDEBUG
416     #define dis_inwhen(dis) ((dis)->flags & DIS_INWHEN)
417     #define dis_const(dis) ((dis)->flags & DIS_CONST)
418     #define dis_in_block(dis) ((dis)->flags & DIS_INBLOCK)
419     #define dis_incident(dis) ((dis)->flags & DIS_INCIDENT)
420     #define dis_active(dis) ((dis)->flags & DIS_ACTIVE)
421     #define dis_boolean(dis) ((dis)->flags & DIS_BOOLEAN)
422     #define dis_val_modified(dis) ((dis)->flags & DIS_VAL_MODIFIED)
423     #define dis_changes_structure(dis) ((dis)->flags & DIS_CHANGES_STRUCTURE)
424     #else
425     #define dis_inwhen(dis) dis_flagbit((dis),DIS_INWHEN)
426     #define dis_const(dis) dis_flagbit((dis),DIS_CONST)
427     #define dis_in_block(dis) dis_flagbit((dis),DIS_INBLOCK)
428     #define dis_incident(dis) dis_flagbit((dis),DIS_INCIDENT)
429     #define dis_active(dis) dis_flagbit((dis),DIS_ACTIVE)
430     #define dis_boolean(dis) dis_flagbit((dis),DIS_BOOLEAN)
431     #define dis_val_modified(dis) dis_flagbit((dis),DIS_VAL_MODIFIED)
432     #define dis_changes_structure(dis) dis_flagbit((dis),DIS_CHANGES_STRUCTURE)
433     #endif /* NDEBUG */
434    
435     #define dis_set_inwhen(dis,b) dis_set_flagbit((dis),DIS_INWHEN,(b))
436     #define dis_set_const(dis,b) dis_set_flagbit((dis),DIS_CONST,(b))
437     #define dis_set_in_block(dis,b) dis_set_flagbit((dis),DIS_INBLOCK,(b))
438     #define dis_set_incident(dis,b) dis_set_flagbit((dis),DIS_INCIDENT,(b))
439     #define dis_set_active(dis,b) dis_set_flagbit((dis),DIS_ACTIVE,(b))
440     #define dis_set_boolean(dis,b) dis_set_flagbit((dis),DIS_BOOLEAN,(b))
441     #define dis_set_val_modified(dis,b) \
442     dis_set_flagbit((dis),DIS_VAL_MODIFIED,(b))
443     #define dis_set_changes_structure(dis,b) \
444     dis_set_flagbit((dis),DIS_CHANGES_STRUCTURE,(b))
445    
446     /*
447     * incident = dis_incident(dis)
448     * dis_set_incident(dis,incident)
449     * uint32 incident;
450     * struct dis_discrete *dis;
451     *
452     * Gets/sets the incident flag of the discrete variable.
453     */
454    
455     extern struct dis_discrete **dis_BackendTokens_to_dis(slv_system_t,
456     SlvBackendToken *,
457     int32);
458     /*
459     * dislist = dis_BackendTokens_to_dis(sys,tokenlist,len);
460     * slv_system_t sys; System to get indexing from.
461     * SlvBackendToken tokenlist[]; Array of backend tokens.
462     * int32 len; Tokenlist size.
463     * struct dis_discrete *dislist[]; aka **dislist;
464     *
465     * dislist is NULL iff something is a miss, OTHERWISE it
466     * contains len struct dis_discrete *.
467     * The user should free the array dislist when done with it.
468     * Some entries in the array dislist may be NULL if the tokenlist
469     * contains a token which is not from the sys given.
470     * tokenlist[i] <--> dislist[i];
471     *
472     * The whole point of a slv_system_t is to isolate the client from
473     * the compiler backend. Clients who find themselves in need of
474     * this function are very much in need of rethinking as well.
475     * For that reason, among others, this function is not heavily
476     * optimized, it is however reasonable for 1-off jobs.
477     *
478     */
479    
480     #endif /* dis__already_included */

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