| 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 |
|
Parent Directory
| 
Revision Log