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

Annotation of /trunk/ascend4/solver/logrel.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, 8 months ago) by aw0a
File MIME type: text/x-chdr
File size: 13770 byte(s)
Setting up web subdirectory in repository
1 aw0a 1 /*
2     * Logical Relation Module
3     * by Vicente Rico-Ramirez
4     * Created: 09/96
5     * Version: $Revision: 1.6 $
6     * Version control file: $RCSfile: logrel.h,v $
7     * Date last modified: $Date: 1997/07/29 15:47:43 $
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: Logical Relation module (ascend)
31     *
32     * Dates: 09/96 - original version
33     *
34     * Description: This is the ascend version of the logrel module. This
35     * version should be used by any user who receives his/her
36     * equations directly from an instance tree created by the
37     * ASCEND compiler.
38     */
39     #ifndef logrel__already_included
40     #define logrel__already_included
41    
42     /*
43     * requires #include "/base.h"
44     * requires #include "/discrete.h"
45     */
46    
47     /*********************************************************************\
48     logrel_relation basic type operators.
49     \*********************************************************************/
50    
51     enum logrel_enum {
52     e_logrel_equal,
53     e_logrel_not_equal
54     };
55    
56     /*
57     * enum logrel_enum:
58     * The operator of a logical relation.
59     */
60    
61     struct logrel_relation {
62     SlvBackendToken instance;
63     struct dis_discrete **incidence;
64     int32 n_incidences; /* length of incidence */
65     int32 mindex; /* index in the slv_system_t master list */
66     int32 sindex; /* index in the slv_system_t solver list */
67     int32 model; /* index of a hypothetical MODEL rel is from */
68     uint32 flags; /* flags */
69     };
70     /*
71     * if you mess with the above struct, change the defaults for it in .c file
72     */
73    
74    
75     extern struct logrel_relation *logrel_create(SlvBackendToken ,
76     struct logrel_relation *);
77     /*
78     * logrel_create(instance,newlogrel)
79     * struct logrel_relation *newlogrel;
80     * SlvBackendToken instance;
81     *
82     * Creates a logrelation given the logrelation instance.
83     * If the logrel supplied is NULL, we allocate the memory for the
84     * logrel we return, else we just init the memory you hand us and
85     * return it to you.
86     * We set the fields instance, nodeinfo.
87     * Setting the rest of the information is the job
88     * of the bridge building function between the ascend instance
89     * tree (or other logrelation back end) and the slv_system_t.
90     * In particular, the incidence list and indexing info is not
91     * handled here.
92     */
93    
94    
95     extern SlvBackendToken logrel_instance(struct logrel_relation *);
96     /*
97     * logrel_instance(logrel)
98     * struct logrel_relation *logrel;
99     *
100     * Returns the instance pointer from a logrel.
101     */
102    
103     extern void logrel_write_name(slv_system_t,struct logrel_relation *,FILE *);
104     /*
105     * logrel_write_name(sys,logrel,file);
106     *
107     * Writes a name to the file given.
108     * If sys is NULL, writes full ascend name. If file or logrel is NULL
109     * does not write.
110     */
111    
112     extern void logrel_destroy(struct logrel_relation *);
113     /*
114     * logrel_destroy(logrel)
115     * struct logrel_relation *logrel;
116     *
117     * Destroys a logrelation.
118     */
119    
120     extern boolean logrel_equal(struct logrel_relation *);
121     extern boolean logrel_not_equal(struct logrel_relation *);
122     /*
123     * eq = logrel_equal(logrel)
124     * neq = logrel_not_equal(logrel)
125     * boolean eq,neq;
126     * struct logrel_relation *logrel;
127     *
128     * Returns true if the given logrelation is satisfied if the
129     * operator in question is among those that make up the
130     * comparator of the logrelation.
131     * neq==TRUE implies logrel would be satisfied if lhs != rhs
132     * eq==TRUE implies logrel would be satisfied if lhs == rhs
133     */
134    
135     extern enum logrel_enum logrel_relop(struct logrel_relation *);
136     /*
137     * relop = logrel_relop(logrel);
138     * logrel_enum relop;
139     * struct logrel_relation *logrel;
140     * Returns the type of the operator of a given logrelation.
141     */
142    
143     extern char *logrel_make_name(slv_system_t,struct logrel_relation *);
144     /*
145     * name = logrel_make_name(sys,logrel)
146     * slv_system_t sys;
147     * struct logrel_relation *logrel;
148     * char *name;
149     *
150     * Copies of the logrelation instance name can be made and returned.
151     * The string returned should be freed when no longer in use.
152     */
153    
154     extern int32 logrel_mindex(struct logrel_relation *);
155     extern void logrel_set_mindex(struct logrel_relation *,int32);
156     /*
157     * index = logrel_mindex(logrel)
158     * logrel_set_mindex(logrel,index)
159     * int32 index;
160     * struct logrel_relation *logrel;
161     *
162     * Sets or retrieves the index number of the given logrelation as it
163     * appears in a slv_system_t master logrelation list.
164     */
165    
166     extern int32 logrel_sindex(struct logrel_relation *);
167     extern void logrel_set_sindex(struct logrel_relation *,int32);
168     /*
169     * index = logrel_sindex(logrel)
170     * logrel_set_sindex(logrel,index)
171     * int32 index;
172     * struct logrel_relation *logrel;
173     *
174     * Sets or retrieves the index number of the given logrelation as it
175     * appears in a solvers logrelation list.
176     */
177    
178     extern int32 logrel_model(const struct logrel_relation *);
179     extern void logrel_set_model(struct logrel_relation *,int32);
180     /*
181     * index = logrel_model(logrel)
182     * logrel_set_model(logrel,index)
183     * int32 index;
184     * struct logrel_relation *logrel;
185     *
186     * Sets or retrieves the model number of the given logrelation.
187     * Models are numbered from 1 to some upper limit.
188     */
189    
190     extern int32 logrel_residual(struct logrel_relation *);
191     extern void logrel_set_residual(struct logrel_relation *,int32);
192     /*
193     * residual = logrel_residual(logrel)
194     * logrel_set_residual(logrel,residual)
195     * int32 residual;
196     * struct logrel_relation *logrel;
197     *
198     * Sets or retrieves the logical residual field of the given logrelation.
199     * Note that the residual is not actually computed by logrel_residual:
200     * there is no guarantee (from this function) that the residual is
201     * actually correct.
202     */
203    
204     extern int32 logrel_nominal(struct logrel_relation *);
205     /*
206     * nominal = logrel_nominal(logrel)
207     * int32 nominal;
208     * struct logrel_relation *logrel;
209     *
210     * Retrieves the nominal field of the given logrelation.
211     * No slv client has any business being able to set the nominal,
212     * so no such operator is provided.
213     */
214    
215    
216     #ifdef NDEBUG
217     #define logrel_n_incidences(lr) ((lr)->n_incidences)
218     #define logrel_set_incidences(lr,n,ilist) \
219     (lr)->n_incidences=(n); (lr)->incidence = (ilist)
220     #else
221     #define logrel_n_incidences(lr) logrel_n_incidencesF(lr)
222     #define logrel_set_incidences(lr,n,ilist) \
223     logrel_set_incidencesF((lr),(n),(ilist))
224     #endif /* NDEBUG */
225    
226    
227     extern int32 logrel_n_incidencesF(struct logrel_relation *);
228     extern void logrel_set_incidencesF(struct logrel_relation *,
229     int32,struct dis_discrete **);
230     /*
231     * logrel_n_incidences(logrel)
232     * logrel_set_incidences(logrel,n,ilist)
233     * struct logrel_relation *logrel;
234     * struct dis_discrete **ilist;
235     * int32 n;
236     *
237     * logrel_n_incidences returns the length of the incidence_list.
238     * Solver clients should not call logrel_set_incidences,
239     * it is only for use by constructors of bridges to logrelation
240     * back ends.
241     */
242    
243     extern const struct dis_discrete
244     **logrel_incidence_list(struct logrel_relation *);
245     extern struct dis_discrete
246     **logrel_incidence_list_to_modify(struct logrel_relation *);
247     /*
248     * bv = logrel_incidence_list(logrel)
249     * struct logrel_relation *logrel;
250     * struct dis_discrete **bv;
251     *
252     * Returns a pointer to an array logrel_n_incidences(logrel) long of bvars.
253     * Each element of the array is a struct dis_discrete *.
254     * If there is no incidence, NULL is returned.
255     * Pointers in this array will be unique.
256     * The list belongs to the logrelation. Do not destroy it.
257     * Do not change it.
258     *
259     * BV IS NOT a NULL-TERMINATED LIST.
260     */
261    
262     /*
263     * logrelation filtration functions.
264     * We coulhave 32 binary (one bit) flags a client may want to query
265     * in arbitrary combinations and paying attention to only certain of
266     * the bits. We will provide a set of macros and functions for each of
267     * these bits and for operations on the whole set.
268     */
269    
270     typedef struct logrel_filter_structure {
271     uint32 matchbits;
272     uint32 matchvalue;
273     } logrel_filter_t;
274    
275     extern int logrel_apply_filter(struct logrel_relation *,logrel_filter_t *);
276     /*
277     * value = logrel_apply_filter(logrel,filter)
278     * int value;
279     * struct logrel_relation *logrel;
280     * logrel_filter_t *filter;
281     *
282     * Returns 1 only if all of the positions specified in
283     * filter->matchbits have the same values in
284     * filter->matchvalue and the logrelation's flags value.
285     * Bits set to 0 in filter->matchbits are ignored for the test.
286     */
287    
288     extern uint32 logrel_flags(struct logrel_relation *);
289     extern void logrel_set_flags(struct logrel_relation *,uint32);
290     /*
291     * struct logrel_relation *logrel;
292     * uint32 flags;
293     *
294     * logrel_flags(logrel) returns the flags field of the logrelation.
295     * logrel_set_flags(logrel,flags) sets the entire flag field to the
296     * value of flags given.
297     */
298    
299     extern uint32 logrel_flagbit(struct logrel_relation *,uint32);
300     /*
301     * logrel_flagbit(logrel,name);
302     * struct logrel_relation *logrel;
303     * uint32 name;
304     * name should be a LOGREL_xx flag defined above)
305     * Returns the value of the bit specified from the logrelation flags.
306     */
307    
308     extern void logrel_set_flagbit(struct logrel_relation *,uint32, uint32);
309     /*
310     * struct logrel_relation *logrel;
311     * unsigned int NAME,oneorzero;
312     * logrel_set_flagbit(logrel,NAME,oneorzero)
313     *
314     * Sets the bit, which should be referred to by its macro name,
315     * on if oneorzero is >0 and off is oneorzero is 0.
316     * The macro names are the defined up at the top of this file.
317     *
318     * Example: logrel_set_flags(logrel,LOGREL_INCLUDED,1) turns on the
319     * LOGREL_INCLUDED bit.
320     * What it really does is:
321     * if (oneorzero) {
322     * logrel->flags |= field;
323     * } else {
324     * logrel->flags &= ~field;
325     * }
326     * In unix, see also man 3f bit or man not.
327     */
328    
329     /*
330     * the bit flags. explained afterward. several are for use of
331     * transient clients and should be ignored by solver engines
332     */
333     #define LOGREL_INCLUDED 0x1
334     /*
335     * INCLUDED is as yet a funny one. treat it as readonly because
336     * you can only change it using a int function and not the
337     * bit manipulation functions. It is here in the bits because
338     * it is useful in filters sometimes.
339     */
340     #define LOGREL_SATISFIED 0x2
341     #define LOGREL_EQUALITY 0x4
342     /* Conditional Modeling */
343     #define LOGREL_INWHEN 0x8
344     #define LOGREL_ACTIVE 0x10
345     /* Conditional LogRelations (Boundaries) */
346     #define LOGREL_CONDITIONAL 0x20
347     #define LOGREL_IN_BLOCK 0x40
348     /*
349     * LOGREL_INCLUDED solvers, ui clients. user wants eqn in problem.
350     * bit should be treated as readonly. use logrel_set_*
351     * to change.
352     * LOGREL_SATISFIED has logrel been pronounced satisfied by someone?
353     * bit should be treated as readonly. use logrel_set_*
354     * to change.
355     * LOGREL_EQUALITY is logrelation an equality? readonly for clients.
356     * LOGREL_INWHEN is logrelation in a when? readonly for clients.
357     * LOGREL_ACTIVE is this logrelation currently a part of my problem?
358     * LOGREL_CONDITIONAL is logrelation conditional? readonly for clients.
359     * LOGREL_IN_BLOCK is the logrelation in the current block of registered
360     * client? for clients.
361     */
362    
363     /*
364     * the bit flag lookups
365     */
366     #ifdef NDEBUG
367     #define logrel_satisfied(lr) ((lr)->flags & LOGREL_SATISFIED)
368     #define logrel_equality(lr) ((lr)->flags & LOGREL_EQUALITY)
369     #define logrel_in_when(lr) ((lr)->flags & LOGREL_INWHEN)
370     #define logrel_active(lr) ((lr)->flags & LOGREL_ACTIVE)
371     #define logrel_conditional(lr) ((lr)->flags & LOGREL_CONDITIONAL)
372     #define logrel_in_block(lr) ((lr)->flags & LOGREL_IN_BLOCK)
373     #else
374     #define logrel_satisfied(lr) logrel_flagbit((lr),LOGREL_SATISFIED)
375     #define logrel_equality(lr) logrel_flagbit((lr),LOGREL_EQUALITY)
376     #define logrel_in_when(lr) logrel_flagbit((lr),LOGREL_INWHEN)
377     #define logrel_active(lr) logrel_flagbit((lr),LOGREL_ACTIVE)
378     #define logrel_conditional(lr) logrel_flagbit((lr),LOGREL_CONDITIONAL)
379     #define logrel_in_bolck(lr) logrel_flagbit((lr),LOGREL_IN_BLOCK)
380     #endif /* NDEBUG */
381    
382     /*
383     * bit flag assignments. any value other than 0 for bv turns the
384     * named flag to 1. 0 sets it to 0.
385     */
386     #define logrel_set_satisfied(lr,bv) \
387     logrel_set_flagbit((lr),LOGREL_SATISFIED,(bv))
388     #define logrel_set_equality(lr,bv) \
389     logrel_set_flagbit((lr),LOGREL_EQUALITY,(bv))
390     #define logrel_set_in_when(lr,bv) \
391     logrel_set_flagbit((lr),LOGREL_INWHEN,(bv))
392     #define logrel_set_active(lr,bv) \
393     logrel_set_flagbit((lr),LOGREL_ACTIVE,(bv))
394     #define logrel_set_conditional(lr,bv) \
395     logrel_set_flagbit((lr),LOGREL_CONDITIONAL,(bv))
396     #define logrel_set_in_block(lr,bv) \
397     logrel_set_flagbit((lr),LOGREL_IN_BLOCK,(bv))
398    
399     extern uint32 logrel_included(struct logrel_relation *);
400     extern void logrel_set_included(struct logrel_relation *,uint32);
401     /*
402     * included = logrel_included(logrel)
403     * logrel_set_included(logrel,included)
404     * uint32 included;
405     * struct logrel_relation *logrel;
406     *
407     * Sets or retrieves the included field of the given logrelation.
408     * This has side effect on the ascend instance, so it isn't
409     * implemented with the rest of the macros above. This needs to
410     * change.
411     */
412    
413     #endif /* logrel_already_included */

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