/[ascend]/trunk/ascend/compiler/logrel_util.h
ViewVC logotype

Contents of /trunk/ascend/compiler/logrel_util.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2018 - (show annotations) (download) (as text)
Wed Apr 29 03:38:10 2009 UTC (11 years, 2 months ago) by jpye
File MIME type: text/x-chdr
File size: 17546 byte(s)
Fixed compile for new header file locations <ascend/compiler/xxx.h> etc.
1 /* ASCEND modelling environment
2 Copyright (C) 1997-2008 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 *//** @file
18 Logical Relation utility functions for Ascend
19 by Vicente Rico-Ramirez
20 */
21
22 #ifndef ASC_LOGRELATION_UTIL_H
23 #define ASC_LOGRELATION_UTIL_H
24
25 #include <ascend/utilities/ascConfig.h>
26 #include "compiler.h"
27 #include "logrelation.h"
28 #include "instance_enum.h"
29
30 /** @addtogroup compiler Compiler
31 @{
32 */
33
34 extern enum Expr_enum LogRelRelop(CONST struct logrelation *lrel);
35 /**<
36 * Return the type of the logical relation operator of the relation:
37 * - e_boolean_eq equality constraint
38 * - e_boolean_neq non-equality contraint
39 */
40
41 extern unsigned long NumberBoolVars(CONST struct logrelation *lrel);
42 /**<
43 * This will indicate the number of distinct boolean atoms to which this
44 * logical relation points. This number contains both fixed and non-fixed
45 * atoms.
46 */
47
48 extern struct Instance *LogRelBoolVar(CONST struct logrelation *lrel,
49 unsigned long varnum);
50 /**<
51 * This will return the varnum'th boolean variable.
52 */
53
54 extern unsigned long NumberRelations(CONST struct logrelation *lrel);
55 /**<
56 * This will indicate the number of distinct relations to which this
57 * logical relation points. This number contains both conditional
58 * relations and conditional logrelations.
59 */
60
61 extern struct Instance *LogRelRelation(CONST struct logrelation *lrel,
62 unsigned long relnum);
63 /**<
64 * This will return the relnum'th relation in the satisfied rel list.
65 */
66
67 /*---------------------------------------------------------------------------
68 * Logical Relation specific code.
69 * Very little sanity checking is done.
70 *---------------------------------------------------------------------------
71 */
72
73 extern unsigned long LogRelLength(CONST struct logrelation *lrel, int lhs);
74 /**<
75 * If lhs is true, return the number of terms on the left hand side of the
76 * logical relation; otherwise, return the number of terms on the right
77 * hand side of the logical relation.
78 */
79
80 extern CONST struct logrel_term
81 *LogRelTerm(CONST struct logrelation *lrel,
82 unsigned long pos,
83 int lhs);
84 /**<
85 * If lhs is true, return the term in position pos of the left hand side;
86 * otherwise, return the term in position pos of the right hand side.
87 * A bizarre thing about this operator: 1<=pos<=LogRelLength(lrel,lhs).
88 * This is a holdover from gllist days.
89 */
90
91 #ifdef NDEBUG
92 #define NewLogRelTerm(r,p,l) \
93 LOGA_TERM( (l)!=0 ? (&((r)->token.lhs[(p)])) : (&((r)->token.rhs[(p)])) )
94 #else
95 #define NewLogRelTerm(r,p,l) NewLogRelTermF((r),(p),(l))
96 #endif
97 /**<
98 * If lhs is true, return the term in position p of the left hand side;
99 * otherwise, return the term in position p of the right hand side.
100 * For this operator: 0 <= p < LogRelLength(lrel,lhs) as a C array.
101 * Once Everybody gets their damn hands off LogRelTerm(), switch its
102 * semantics and eliminate one of this pair.
103 * @param r const struct logrelation*, logical relation to query.
104 * @param p unsigned long, position to return.
105 * @param l int, TRUE to return from left hand side, FALSE then from rhs.
106 * @return The term as an CONST struct logrel_term*.
107 * @see NewLogRelTermF()
108 */
109 extern CONST struct logrel_term
110 *NewLogRelTermF(CONST struct logrelation *lrel, unsigned long apos, int lhs);
111 /**<
112 * Implementation function for NewLogRelTerm(). Do not use this
113 * function directly - use NewLogRelTerm() instead.
114 */
115
116 #ifdef NDEBUG
117 #define LogRelSideTerm(rs,p) LOGA_TERM(&((rs)[(p)]))
118 #else
119 #define LogRelSideTerm(rs,p) LogRelSideTermF((rs),(p))
120 #endif
121 /**<
122 * Return the term in position p of the side.
123 * For this operator: 0 <= p < length of the side.
124 * @param rs CONST union LogRelTermUnion*, side.
125 * @param p unsigned long, position to return.
126 * @return The term as an CONST struct logrel_term*.
127 * @see LogRelSideTermF()
128 */
129 extern CONST struct logrel_term
130 *LogRelSideTermF(CONST union LogRelTermUnion *lrelside, unsigned long apos);
131 /**<
132 * Implementation function for LogRelSideTerm(). Do not use this
133 * function directly - use LogRelSideTerm() instead.
134 */
135
136 #ifdef NDEBUG
137 #define LogRelTermType(rtp) ((rtp)->t)
138 #else
139 #define LogRelTermType(rtp) LogRelTermTypeF(rtp)
140 #endif
141 /**<
142 * Return the type of the logical relation term rtp.
143 * WARNING: if ALLOCATED_TESTS is active, rtp must be an allocated term;
144 * automatic variables will cause an assert() to fail.
145 * @param rtp const struct logrel_term*, the term to query.
146 * @return The type of the term as an enum Expr_enum.
147 * @see LogRelTermTypeF()
148 */
149 extern enum Expr_enum LogRelTermTypeF(CONST struct logrel_term *term);
150 /**<
151 * Implementation function for LogRelTermType(). Do not use this
152 * function directly - use LogRelTermType() instead.
153 */
154
155 extern unsigned long LogTermBoolVarNumber(CONST struct logrel_term *term);
156 /**<
157 * Return the index into the logical relation variable list.
158 */
159
160 extern int LogTermBoolean(CONST struct logrel_term *term);
161 /**<
162 * Return the boolean value from an e_boolean type logical relation term.
163 */
164
165 extern int LogTermInteger(CONST struct logrel_term *term);
166 /**<
167 * Return the integer value from an e_int type logical relation term.
168 */
169
170 extern int LogTermIntegerBoolValue(CONST struct logrel_term *term);
171 /**<
172 * Return a 0-1 value from an e_int type logical relation term.
173 */
174
175 extern int LogTermBoolVar(CONST struct logrelation *lrel,
176 CONST struct logrel_term *term);
177 /**<
178 * Return the integar value from a e_var type logical relation term.
179 */
180
181 extern int LogTermSatisfied(CONST struct logrelation *lrel,
182 CONST struct logrel_term *term,
183 int perturb,
184 struct gl_list_t *instances);
185 /**<
186 * Return the truth value of a SATISFIED logical relation term.
187 * If perturb, and the instances pointed by the SATISFIED term is included
188 * in the list instances, the truth value of the SATISFIED term is
189 * inverted.
190 */
191
192 extern CONST struct Name *LogTermSatName(CONST struct logrel_term *term);
193 /**<
194 * Return the name of the conditional equation specified in an
195 * e_satisfied term
196 */
197
198 extern unsigned long LogTermSatRelNumber(CONST struct logrel_term *term);
199 /**<
200 * Return the index into the logical relation relations list.
201 */
202
203 extern double LogTermSatTolerance(CONST struct logrel_term *term);
204 /**<
205 * Return the real value specified as the tolerance of an e_satisfied term
206 */
207
208 extern CONST dim_type *LogTermSatDimensions(CONST struct logrel_term *term);
209 /**<
210 * Return the dimensions of the real value specified in the tolerance of
211 * an e_satisfied term
212 */
213
214 extern unsigned long LogRelDepth(CONST struct logrelation *lrel);
215 /**<
216 * Return the depth of stack required to evaluate this logical relation.
217 */
218
219 /*---------------------------------------------------------------------------
220 * TokenRelation Infix operations.
221 *---------------------------------------------------------------------------
222 */
223
224 /*
225 * The four defines following return term pointers.
226 * struct logrel_term *r, *t;
227 * r = LogTermUniLeft(t); for example.
228 * These should be implemented as functions which assert type
229 * and revert to macros with NDEBUG.
230 */
231 #define LogTermUniLeft(t) ( ((struct LogRelUnary *)t) -> left)
232 /**<
233 * Retrieve the lhs of a unary logical relation.
234 * Parameter and return values are <code>struct logrel_term*</code>.
235 */
236 #define LogTermBinLeft(t) ( ((struct LogRelBinary *)t) -> left)
237 /**<
238 * Retrieve the lhs of a binary logical relation.
239 * Parameter and return values are <code>struct logrel_term*</code>.
240 */
241 #define LogTermBinRight(t) ( ((struct LogRelBinary *)t) -> right)
242 /**<
243 * Retrieve the rhs of a binary logical relation.
244 * Parameter and return values are <code>struct logrel_term*</code>.
245 */
246
247 extern struct logrel_term *LogRelINF_Lhs(CONST struct logrelation *lrel);
248 /**<
249 * Returns the lhs of an infix logical relation. This may be NULL,
250 * if the logical relation has not been set for infix scanning.
251 */
252
253 extern struct logrel_term *LogRelINF_Rhs(CONST struct logrelation *lrel);
254 /**<
255 * Return the rhs of an infix logical relation. This may be NULL
256 * if the logical relation has not been set up for infix scanning.
257 */
258
259 extern CONST struct gl_list_t *LogRelBoolVarList(CONST struct logrelation *lrel);
260 /**<
261 * Returns the unique incident variable list which is owned by the
262 * logical relation. *DO NOT MODIFY*. It is for the convenience of those
263 * desirous of a READ_ONLY look. It is a list of instance pointers,
264 * which maybe NULL.
265 */
266
267 extern CONST struct gl_list_t *LogRelSatRelList(CONST struct logrelation *lrel);
268 /**<
269 * Returns the unique relation list which is owned by the
270 * logical relation. *DO NOT MODIFY*. It is for the convenience of those
271 * desirous of a READ_ONLY look. It is a list of instance pointers,
272 * which maybe NULL.
273 */
274
275 ASC_DLLSPEC int LogRelResidual(CONST struct logrelation *lrel);
276 /**<
277 * Return the boolean residual of the logical relation.
278 */
279
280 extern void SetLogRelResidual(struct logrelation *lrel, int value);
281 /**<
282 * Set the value of the logical relation residual.
283 */
284
285 ASC_DLLSPEC int LogRelIsCond(CONST struct logrelation *lrel);
286 /**<
287 * Return the value of the logiscond flag of the logicalrelation.
288 */
289
290 extern void SetLogRelIsCond(struct logrelation *lrel);
291 /**<
292 * Sets the value of the logiscond field of the logical relation to 1
293 */
294
295 extern int LogRelNominal(CONST struct logrelation *lrel);
296 /**<
297 * Return the nominal of the logical relation.
298 */
299
300 extern void SetLogRelNominal(struct logrelation *lrel, int i);
301 /**<
302 * Sets the value of the nominal field of the logical relation to the
303 * value of i
304 */
305
306 extern int FindTolInSatTermOfLogRel(struct Instance *lrelinst,
307 struct Instance *condinst,
308 double *tolerance);
309 /**<
310 * Look in the logrelation instance lrelinst for a SATISFIED term involving
311 * the instance condinst. When found, it will find the obtain tolerance
312 * specified in the SATISFIED term (if such a value is given) and it will
313 * assign it to the *tolerance. If the condinst is a logrel (mistakenly),
314 * or if the SATISFIED term does not specify a value for the tolerance,
315 * it will assign the default value DEFTOLERANCE to *tolerance.
316 * status !=0 indicates it did not find a term containing the instance.
317 */
318
319 /*
320 *---------------------------------------------------------------------------
321 * Calculation routines
322 *---------------------------------------------------------------------------
323 */
324
325 /*
326 * Calculation of the Logical Residuals of a logical relation :
327 * LogRelCalcResidualPostfix
328 * LogRelCalcResidualInfix
329 * and calculation of the values(s) of a boolean variable which make a
330 * logical relation to be satisfied:
331 * LogRelFindBoolValues
332 *
333 * IMPORTANT:
334 * The solution of conditional model implicates the presence of
335 * SATISFIED terms (satisfaction of Boundary conditions)
336 * in some of the logical relations. Because the freedom that the
337 * modeling language gives to the user, sometimes is very difficult
338 * to know if the change of the truth value of a SATISFIED term is
339 * really meaningful to the configuration of the conditional problem.
340 * A boundary may be crossed, but still the boolean dependent on that
341 * condition may not change; furthermore, even a change in that boolean
342 * may not affect the configuration of the problem because a change
343 * of configuration may require the satisfaction of several conditions
344 * simultaneously.
345 * The easier way to test if the crossing of a boundary affects the current
346 * configuration is to solve the logical relations assuming such a
347 * crossing and finding if the configuration of the problem changes.
348 * This task is performed here by using the "perturb" flag and a list
349 * of pointers to the relation instance which constitutes the boundary(ies).
350 * The activation of the perturbation flag causes the calculation
351 * routines to INVERT the truth value of the SATISFIED terms containing
352 * the relation instances pointed by the list of pointers.
353 * The flag and the list of pointers are needed because the SATISFIED term
354 * is not an instance by itself and we have access to it only trough the
355 * logrel instance.
356 * Another option would be to modify the values of the variables incident
357 * in the boundary until the truth value of the SATISFIED changes by itself,
358 * but this would have to be iteratively (i.e. more expensive), since it
359 * would be required to perform gradient calculations in
360 * order to know how the change of the value of some variable will modify
361 * the residual of the boundary. Other question that we would need to
362 * answer is how many variables should be modified simultaneously,etc.
363 * Notice that this is not necessary because we do not care about a change
364 * in the real values of the variables incident in the boundary (and, as
365 * a matter of fact, we do not want ot modify the current values), we only
366 * want to know what would it happen with the value of logical variables
367 * if the truth value of the SATISFIED term changes.
368 *
369 * A third option would be to keep the information about the number
370 * of subregions in the conditional model and the values for the booleans
371 * which make them active. This is unaceptable for problems involving
372 * a big number of boundary conditions, since the problem is combinatorial.
373 *
374 * IN GENERAL, ANY USER INTERESTED IN THESE CALCULATION ROUTINES FOR
375 * PURPOSES OF SOLVING PURE LOGIC PROBLEMS (NOT CONTAINING BOUNDARIES),
376 * SHOULD NOT CONSIDER THE
377 * PARAMETERS EXPLAINED ABOVE. IT IS RECOMMENDED THAT HE/SHE SHOULD
378 * USE THE MACRO
379 * LogRelCalcResidual
380 * WHICH CALL THE CALCULATION ROUTINES WITHOUT CONSIDERING THOSE
381 * PARAMETERS.
382 */
383
384 extern int LogRelCalcResidualPostfix(struct Instance *i,
385 int *res,
386 int perturb,
387 struct gl_list_t *instances);
388 /**<
389 * Sets *res to the logical residual of the logical relation. The logical
390 * residual is evaluating by comparing the truth values of the two terms
391 * of the logical relation. If the logical relation is an equality, a
392 * residual of 1 (TRUE) means that the two terms has the same truth value,
393 * if they do not, the residual is zero. Similar reasoning applies when
394 * the logical relation is an inequality.
395 * Uses postfix evaluation.
396 * If *perturb !=0, that means that we will invert the truth value of
397 * the SATISFIED terms involving the relation instances pointed by the
398 * gl_list.
399 * status != 0 implies a problem.
400 */
401
402 extern int LogRelCalcResidualInfix(struct Instance *i,
403 int *res,
404 int perturb,
405 struct gl_list_t *instances);
406 /**<
407 * Sets *res to the logical residual of the logical relation. The logical
408 * residual is evaluating by comparing the truth values of the two terms
409 * of the logical relation. If the logical relation is an equality, a
410 * residual of 1 (TRUE) means that the two terms has the same truth value,
411 * if they do not, the residual is zero. Similar reasoning applies when
412 * the logical relation is an inequality.
413 * Uses infix evaluation.
414 * If *perturb !=0, that means that we will invert the truth value of
415 * the SATISFIED terms involving the relation instances pointed by the
416 * gl_list
417 * status != 0 implies a problem.
418 */
419
420 extern int *LogRelFindBoolValues(struct Instance *i,
421 unsigned long *dvarnum,
422 int *able,
423 int *nsolns,
424 int perturb,
425 struct gl_list_t *instances);
426 /**<
427 * LogRelFindBoolValues WILL find a booolean solution if there is one.
428 * The user must pass in a pointer to a
429 * struct logrelation. The calling function should check able and/or
430 * nsolns before accessing the information in the soln_list.
431 * nsolns < 0 : severe problems, soln_list will be NULL
432 * nsolns = 0 : No solution found
433 * nsolns > 0 : The soln_status equals the number of roots found
434 * nsolns is at most two for logical operations.
435 * The calling function should NOT free the soln_list.
436 * If *perturb !=0, that means that we will invert the truth value of
437 * the SATISFIED terms involving the relation instances pointed by the
438 * gl_list in order to find the boolean values wanted.
439 */
440
441 #define LogRelCalcResidual(i,r) LogRelCalcResidualPostfix(i,r,0,NULL)
442 /**<
443 * Macro for users interested in the calculation of pure logic relations.
444 * Not conditional modeling.
445 */
446
447 /* @} */
448
449 #endif /* ASC_LOGRELATION_UTIL_H */
450

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