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