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

Contents of /trunk/base/generic/solver/bnd.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: 12835 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) 2007 Carnegie Mellon University
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation; either version 2, or (at your option)
7 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., 59 Temple Place - Suite 330,
17 Boston, MA 02111-1307, USA.
18 *//* @file
19 Boundary Module
20
21 This is the ascend version of the boundary module.
22 This version should be used by any user who receives
23 his/her formulation directly from an instance tree
24 created by the ASCEND compiler.
25 *//*
26 Created: 04/97
27 Last in CVS: $Revision: 1.10 $ $Date: 1997/07/18 12:13:55 $ $Author: mthomas $
28 */
29
30 #ifndef ASC_BND_H
31 #define ASC_BND_H
32
33 #include <utilities/ascConfig.h>
34
35 #include "slv_types.h"
36 #include "rel.h"
37 #include "logrel.h"
38
39 /** @addtogroup system System
40 @{
41 */
42
43 /** Type of condition held by a boundary. */
44 enum bnd_enum {
45 e_bnd_rel, /**< real condition */
46 e_bnd_logrel, /**< logical condition */
47 e_bnd_undefined /**< undefined condition type */
48 };
49
50 /** Union of boundary condition structures. */
51 union bnd_union {
52 struct rel_relation *relbnd; /**< real condition */
53 struct logrel_relation *logrelbnd; /**< logical condition */
54 };
55
56 /** Boundary data structure. */
57 struct bnd_boundary {
58 enum bnd_enum kind; /**< type of condition - real or logical */
59 union bnd_union cond; /**< condition */
60 struct gl_list_t *logrels; /**< logrel using the truth value of condition */
61 real64 tolerance; /**< assume a unique and consistent value for the
62 tolerance. Used only when the condition is a
63 rel_relation. Needs FIX for arbitrary values */
64 int32 mindex; /**< index in the slv_system_t master list */
65 int32 sindex; /**< index in the slv_system_t solver list */
66 int32 model; /**< index of a hypothetical MODEL bnd is from */
67 uint32 flags; /**< flags */
68 };
69
70 extern struct bnd_boundary *bnd_create(struct bnd_boundary *bnd);
71 /**<
72 * Creates a new boundary.
73 * If the bnd supplied is NULL, new memory will be allocated for
74 * the returned bnd. If non-NULL, the memory will be initialized
75 * and returned. Setting the the information is the job of the
76 * bridge building function between the ascend instance tree and
77 * the slv_system_t. When finished with it, the caller should
78 * bnd_destroy() and ascfree() the new boundary.
79 */
80
81 extern void bnd_destroy(struct bnd_boundary *bnd);
82 /**<
83 * Deallocates any memory held internally by the specified boundary.
84 * Nothing is done if bnd is NULL.
85 */
86
87 extern void bnd_set_kind(struct bnd_boundary *bnd, enum bnd_enum kind);
88 /**<
89 * Sets the type of the specified boundary.
90 * bnd may not be NULL (checked by asc_assertion).
91 */
92
93 extern enum bnd_enum bnd_kind(struct bnd_boundary *bnd);
94 /**<
95 * Retrieves the type of the specified boundary.
96 * bnd may not be NULL (checked by asc_assertion).
97 */
98
99 #define bnd_log_cond(b) ((b)->cond.logrelbnd)
100 /**<
101 * Retrieves the condition of a logrel boundary.
102 * @param b The boundary to query (struct bnd_boundary *)
103 * @return The boundary's condition as a struct logrel_relation *.
104 */
105 #define bnd_real_cond(b) ((b)->cond.relbnd)
106 /**<
107 * Retrieves the condition of a rel boundary.
108 * @param b The boundary to query (struct bnd_boundary *)
109 * @return The boundary's condition as a struct rel_relation *.
110 */
111 #define bnd_logrel(b) ((struct logrel_relation *)(b))
112 /**<
113 * Casts a pointer to logrel condition pointer.
114 * @param b The pointer to cast to (struct logrel_relation *).
115 * @return No return value.
116 */
117 #define bnd_rel(b) ((struct rel_relation *)(b))
118 /**<
119 * Casts a pointer to rel condition pointer.
120 * @param b The pointer to cast to (struct rel_relation *).
121 * @return No return value.
122 */
123
124 extern void bnd_set_logrels(struct bnd_boundary *bnd,
125 struct gl_list_t *logrels);
126 /**<
127 * Sets the list of pointers to the logrels using the condition.
128 * logrels is a gl_list of (struct logrel_relation *).
129 * bnd may not be NULL (checked by asc_assertion).
130 */
131
132 extern struct gl_list_t *bnd_logrels(struct bnd_boundary *bnd);
133 /**<
134 * Retrieves the list of pointers to the logrels using the condition.
135 * logrels is a gl_list of (struct logrel_relation *).
136 * bnd may not be NULL (checked by asc_assertion).
137 */
138
139 extern void bnd_set_tolerance(struct bnd_boundary *bnd, real64 tolerance);
140 /**<
141 * Set the tolerance used to determine the truth value
142 * of the condition. The current implimentation allows a single
143 * tolerance. If different values are required, this needs a FIX.
144 * bnd may not be NULL (checked by asc_assertion).
145 */
146
147 extern real64 bnd_tolerance(struct bnd_boundary *bnd);
148 /**<
149 * Retrieves the tolerance used to determine the truth value
150 * of the condition. The current implimentation allows a single
151 * tolerance. If different values are required, this needs a FIX.
152 * bnd may not be NULL (checked by asc_assertion).
153 */
154
155 extern char *bnd_make_name(slv_system_t sys, struct bnd_boundary *bnd);
156 /**<
157 * Copies of the condition instance name can be made and returned.
158 * The string returned should be freed when no longer in use.
159 * Returns NULL if either sys or bnd are NULL.
160 */
161
162 extern int32 bnd_mindex(struct bnd_boundary *bnd);
163 /**<
164 * Retrieves the index of the given boundary as it
165 * appears in a slv_system_t master boundary list.
166 * bnd may not be NULL (checked by asc_assertion).
167 */
168
169 extern void bnd_set_mindex(struct bnd_boundary *bnd, int32 mindex);
170 /**<
171 * Sets the index of the given boundary as it
172 * appears in a slv_system_t master boundary list.
173 * bnd may not be NULL (checked by asc_assertion).
174 */
175
176 extern int32 bnd_sindex(const struct bnd_boundary *bnd);
177 /**<
178 * Retrieves the index of the given boundary as it
179 * appears in a solvers boundary list.
180 * bnd may not be NULL (checked by asc_assertion).
181 */
182
183 extern void bnd_set_sindex(struct bnd_boundary *bnd, int32 sindex);
184 /**<
185 * Sets the index of the given boundary as it
186 * appears in a solvers boundary list.
187 * bnd may not be NULL (checked by asc_assertion).
188 */
189
190 extern int32 bnd_model(const struct bnd_boundary *bnd);
191 /**<
192 * Retrieves the model number of the given boundary.
193 * In a hierarchy, boundaries come in groups associated with
194 * models. Models are numbered from 1 to some upper limit.
195 * bnd may not be NULL (checked by asc_assertion).
196 */
197
198 extern void bnd_set_model(struct bnd_boundary *bnd, int32 mindex);
199 /**<
200 * Sets the model number of the given boundary.
201 * In a hierarchy, boundaries come in groups associated with
202 * models. Models are numbered from 1 to some upper limit.
203 * bnd may not be NULL (checked by asc_assertion).
204 */
205
206 extern struct var_variable **bnd_real_incidence(struct bnd_boundary *bnd);
207 /**<
208 * Returns a pointer to an array of variables incident in the
209 * relation constituting the boundary. The returned list is kept
210 * by the relation - do not destroy or change it in any way.
211 * bnd may not be NULL (checked by asc_assertion).
212 */
213
214 extern int32 bnd_n_real_incidences(struct bnd_boundary *bnd);
215 /**<
216 * Gets the number of variables incident in the relation
217 * constituting the boundary. This will be the length of the
218 * array pointed to by the return value of bnd_real_incidence().
219 * bnd may not be NULL (checked by asc_assertion).
220 */
221
222 /*
223 * Boundary filtration functions.
224 * We have a lot (32) of binary (one bit) flags a client may want to query
225 * in arbitrary combinations and paying attention to only certain of
226 * the bits. We will provide a set of macros and functions for each of
227 * these bits and for operations on the whole set.
228 */
229
230 /** Boundary filter structure. */
231 typedef struct bnd_filter_structure {
232 uint32 matchbits; /**< Bits to match. */
233 uint32 matchvalue; /**< Value to match. */
234 } bnd_filter_t;
235 /**< Boundary filter type. */
236
237 extern int bnd_apply_filter(const struct bnd_boundary *bnd,
238 bnd_filter_t *filter);
239 /**<
240 * Applies a filter to a boundary.
241 * Returns 1 only if all of the positions specified in
242 * filter->matchbits have the same values in
243 * filter->matchvalue and the boundary's flags value.
244 * Bits set to 0 in filter->matchbits are ignored for the test.
245 * Returns 0 if either bnd or filter is NULL.
246 */
247
248 extern unsigned int bnd_flags(struct bnd_boundary *bnd);
249 /**<
250 * Returns the flags field of the boundary.
251 * bnd may not be NULL (checked by asc_assertion).
252 */
253
254 extern void bnd_set_flags(struct bnd_boundary *bnd, uint32 flags);
255 /**<
256 * Sets the entire flag field to the value of flags given.
257 * bnd may not be NULL (checked by asc_assertion).
258 */
259
260 extern uint32 bnd_flagbit(struct bnd_boundary *bnd, uint32 name);
261 /**<
262 * Returns the value of the bit specified from the boundary flags.
263 * name should be a BND_xx flag defined below).
264 * bnd may not be NULL (checked by asc_assertion).
265 */
266
267 extern void bnd_set_flagbit(struct bnd_boundary *bnd,
268 uint32 NAME, uint32 oneorzero);
269 /**<
270 * Sets a flag bit for a boundary.
271 * Sets the bit, which should be referred to by its macro
272 * name, on if oneorzero is >0 and off is oneorzero is 0.
273 * The macro names are the defined up at the top of this file.
274 * bnd may not be NULL (checked by asc_assertion).
275 */
276
277 /* the bit flags.*/
278 #define BND_REAL 0x1 /**< is the boundary a real relation ? */
279 #define BND_IN_LOGREL 0x2 /**< is the boundary used in some logical relation ? */
280 #define BND_EQUALITY 0x4 /**< is the boundary an equality? readonly for clients. */
281 #define BND_AT_ZERO 0x8 /**< Am I at the "zero" of a conditional boundary ? */
282 #define BND_CUR_STATUS 0x10 /**< Is the Boundary boundary currently satisfied ? */
283 #define BND_PRE_STATUS 0x20 /**< Was the Boundary boundary satisfied in the previous
284 iteration ? (The last two help to answer the query
285 "Was the boundary crossed ?") */
286 #define BND_CROSSED 0x40 /**< Was the boundary crossed ? */
287 #define BND_PERTURB 0x80 /**< Should I perturb this boundary in the calculation
288 of logical variables ? */
289 /*
290 * the bit flag lookups
291 */
292 #ifdef NDEBUG
293 #define bnd_real(b) ((b)->flags & BND_REAL)
294 #define bnd_in_logrel(b) ((b)->flags & BND_IN_LOGREL)
295 #define bnd_equality(b) ((b)->flags & BND_EQUALITY)
296 #define bnd_at_zero(b) ((b)->flags & BND_AT_ZERO)
297 #define bnd_cur_status(b) ((b)->flags & BND_CUR_STATUS)
298 #define bnd_pre_status(b) ((b)->flags & BND_PRE_STATUS)
299 #define bnd_crossed(b) ((b)->flags & BND_CROSSED)
300 #define bnd_perturb(b) ((b)->flags & BND_PERTURB)
301 #else
302 #define bnd_real(b) bnd_flagbit((b),BND_REAL)
303 #define bnd_in_logrel(b) bnd_flagbit((b),BND_IN_LOGREL)
304 #define bnd_equality(b) bnd_flagbit((b),BND_EQUALITY)
305 #define bnd_at_zero(b) bnd_flagbit((b),BND_AT_ZERO)
306 #define bnd_cur_status(b) bnd_flagbit((b),BND_CUR_STATUS)
307 #define bnd_pre_status(b) bnd_flagbit((b),BND_PRE_STATUS)
308 #define bnd_crossed(b) bnd_flagbit((b),BND_CROSSED)
309 #define bnd_perturb(b) bnd_flagbit((b),BND_PERTURB)
310 #endif /* NDEBUG */
311
312 /*
313 * bit flag assignments. any value other than 0 for bv turns the
314 * named flag to 1. 0 sets it to 0.
315 */
316 #define bnd_set_real(b,bv) bnd_set_flagbit((b),BND_REAL,(bv))
317 #define bnd_set_in_logrel(b,bv) bnd_set_flagbit((b),BND_IN_LOGREL,(bv))
318 #define bnd_set_equality(b,bv) bnd_set_flagbit((b),BND_EQUALITY,(bv))
319 #define bnd_set_at_zero(b,bv) bnd_set_flagbit((b),BND_AT_ZERO,(bv))
320 #define bnd_set_cur_status(b,bv) bnd_set_flagbit((b),BND_CUR_STATUS,(bv))
321 #define bnd_set_pre_status(b,bv) bnd_set_flagbit((b),BND_PRE_STATUS,(bv))
322 #define bnd_set_crossed(b,bv) bnd_set_flagbit((b),BND_CROSSED,(bv))
323 #define bnd_set_perturb(b,bv) bnd_set_flagbit((b),BND_PERTURB,(bv))
324
325 extern int32 bnd_status_cur(struct bnd_boundary *bnd); /**< See bnd_status_pre(). */
326 extern int32 bnd_status_pre(struct bnd_boundary *bnd);
327 /**<
328 * Returns an int32 (0 or 1) instead of an arbitrary nonzero or
329 * zero value. It is silly, but it makes easier to deal with comparisons
330 * between the current and the previous status of a boundary.
331 * bnd may not be NULL (checked by asc_assertion).
332 */
333
334 /* @} */
335
336 #endif /* ASC_BND_H */
337

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