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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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