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

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