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

Contents of /trunk/base/generic/solver/discrete.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: 18948 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 Discrete variable module
20
21 This is the ascend version of the bvar module. This
22 version should be used by any user who receives his/her
23 equations indirectly from an instance tree created by the
24 ASCEND compiler.
25 *//*
26 by Vicente Rico-Ramirez, 0696
27 Last in CVS: $Revision: 1.7 $ $Date: 1998/03/30 22:06:54 $ $Author: rv2a $
28 */
29
30 #ifndef ASC_DISCRETE_H
31 #define ASC_DISCRETE_H
32
33 #include <stdio.h>
34 #include <utilities/ascConfig.h>
35 #include <general/list.h>
36
37 #include "slv_types.h"
38
39 /** @addtogroup system System
40 @{
41 */
42
43 /** Kinds of discrete variables. */
44 enum discrete_kind {
45 e_dis_boolean_t,
46 e_dis_integer_t,
47 e_dis_symbol_t,
48 e_dis_error_t
49 };
50
51 /** Discrete variable data structure. */
52 struct dis_discrete {
53 enum discrete_kind t; /**< kind of discrete variable */
54 SlvBackendToken datom; /**< the associated ascend ATOM */
55 struct dis_discrete **sos; /**< not implemented yet. Used to represent */
56 /**< integer and symbols in terms of booleans */
57 struct dis_discrete *source; /**< Not implemented yet. This would be used for
58 booleans, members of sos, to point back to
59 the variable which is using it */
60 struct gl_list_t *whens; /**< whens in which this variable is used */
61 int32 range; /**< Ranges for integer or symbols.Sme as above */
62 int32 cur_value; /**< current value */
63 int32 pre_value; /**< previous value */
64 int32 sindex; /**< index in the solver clients list */
65 int32 mindex; /**< index in the slv_system_t master list */
66 uint32 flags; /**< batch of binary flags */
67 };
68
69 /**
70 * Discrete variable filter info.
71 * Do not dereference this structure except
72 * via macros/functions, because we make no commitments about being
73 * backward compatible with such code.
74 */
75 typedef struct dis_filter_structure {
76 uint32 matchbits;
77 uint32 matchvalue;
78 } dis_filter_t;
79
80
81 extern struct dis_discrete *dis_create(SlvBackendToken instance,
82 struct dis_discrete *newdis);
83 /**<
84 * Creates a discrete variable given the variable instance.
85 * If the discrete var supplied is NULL, we allocate the memory for the
86 * discrete var we return, else we just init the memory you hand us and
87 * return it to you.
88 * We set the fields instance. Setting the rest of the information
89 * is the job of the bridge building function between the ascend instance
90 * tree (or other discrete var back end) and the slv_system_t.
91 */
92
93 #ifdef NDEBUG
94 #define dis_instance(dis) ((dis)->datom)
95 #else
96 #define dis_instance(dis) dis_instanceF(dis)
97 #endif
98 /**<
99 * Returns the ATOM instance associated with the variable.
100 * @param dis const struct dis_discrete*, the discrete var to query.
101 * @return The instance as a SlvBackendToken.
102 * @see dis_instanceF()
103 */
104
105 #ifdef NDEBUG
106 #define dis_set_instance(dis,inst) ((dis)->datom = (inst))
107 #else
108 #define dis_set_instance(dis,inst) dis_set_instanceF((dis),(inst))
109 #endif
110 /**<
111 * Sets the ATOM instance associated with the variable.
112 * @param dis const struct dis_discrete*, the discrete var to modify.
113 * @param inst SlvBackendToken, the new instance to associate with dis.
114 * @return No return value.
115 * @see dis_set_instanceF()
116 */
117
118 extern SlvBackendToken dis_instanceF(const struct dis_discrete *dis);
119 /**<
120 * Implementation function for dis_instance() (debug mode).
121 * Do not call this function directly - use dis_instance() instead.
122 */
123 extern void dis_set_instanceF(struct dis_discrete *dis, SlvBackendToken i);
124 /**<
125 * Implementation function for dis_set_instance() (debug mode).
126 * Do not call this function directly - use dis_set_instance() instead.
127 */
128
129 extern char *dis_make_name(const slv_system_t sys,
130 const struct dis_discrete *dis);
131 /**<
132 * Creates and returns a sufficiently large string storing the
133 * qualified name of var as known by the solver instance tree.
134 * If the instance is not found, "?" is returned. The string
135 * should be destroyed when no longer in use.<br><br>
136 * <!-- dis_make_xname returns the index name, eg x23 rather than full name. -->
137 *
138 * The name of a dis is context dependent, so you have to provide the
139 * slv_system_t from which you got the dis.
140 */
141 extern char *dis_make_xname(const struct dis_discrete *dis);
142 /**<
143 * Returns the index name, eg x23 rather than full name.
144 * @see dis_make_name()
145 */
146
147 extern void dis_write_name(const slv_system_t sys,
148 const struct dis_discrete *dis,
149 FILE *file);
150 /**<
151 * Writes a name to the file given.
152 * Does not print any whitespace, including carriage returns.
153 * If sys is NULL, writes full ascend name. If file or var is NULL
154 * does not write.
155 */
156
157 extern void dis_destroy(struct dis_discrete *dis);
158 /**<
159 * Since someone else allocates dis en masse, this just sets
160 * our integrity check to ERROR.
161 */
162
163 extern struct gl_list_t *dis_whens_list(struct dis_discrete *dis);
164 /**< Retrieves the list of whens of the given dis. */
165 extern void dis_set_whens_list(struct dis_discrete *dis,
166 struct gl_list_t *wlist);
167 /**<
168 * Sets the list of whens of the given dis.
169 */
170
171 #ifdef NDEBUG
172 #define dis_kind(dis) (dis)->t
173 #else
174 #define dis_kind(dis) dis_kindF(dis)
175 #endif
176 /**<
177 * Return the enumerated type that indicates the type of dis.
178 * @param dis const struct dis_discrete*, the discrete var to query.
179 * @return The type as an enum discrete_kind.
180 * @see dis_kindF()
181 */
182
183 #ifdef NDEBUG
184 #define dis_set_kind(dis,kind) (dis)->t = (kind)
185 #else
186 #define dis_set_kind(dis,kind) dis_set_kindF((dis),(kind))
187 #endif
188 /**<
189 * Sets the enumerated type that indicates the type of dis.
190 * @param dis const struct dis_discrete*, the discrete var to modify.
191 * @param kind enum discrete_kind, the new type for dis.
192 * @return No return value.
193 * @see dis_set_kindF()
194 */
195
196 extern enum discrete_kind dis_kindF(const struct dis_discrete *dis);
197 /**<
198 * Implementation function for dis_kind() (debug mode).
199 * Do not call this function directly - use dis_kind() instead.
200 */
201 extern void dis_set_kindF(struct dis_discrete *dis,
202 enum discrete_kind kind);
203 /**<
204 * Implementation function for dis_set_kind() (debug mode).
205 * Do not call this function directly - use dis_set_kind() instead.
206 */
207
208 #ifdef NDEBUG
209 #define dis_mindex(dis) (dis)->mindex
210 #else
211 #define dis_mindex(dis) dis_mindexF(dis)
212 #endif
213 /**<
214 * Gets the index of the variable as it appears in a variable list.
215 * @param dis const struct dis_discrete*, the discrete var to query.
216 * @return The index as an int32.
217 * @see dis_mindexF()
218 */
219
220 #ifdef NDEBUG
221 #define dis_set_mindex(dis,index) (dis)->mindex = (index)
222 #else
223 #define dis_set_mindex(dis,index) dis_set_mindexF((dis),(index))
224 #endif
225 /**<
226 * Sets the index of the variable as it appears in a variable list.
227 * @param dis const struct dis_discrete*, the discrete var to modify.
228 * @param index int32, the index value.
229 * @return No return value.
230 * @see dis_set_mindexF()
231 */
232
233 extern int32 dis_mindexF(const struct dis_discrete *dis);
234 /**<
235 * Implementation function for dis_mindex() (debug mode).
236 * Do not call this function directly - use dis_mindex() instead.
237 */
238 extern void dis_set_mindexF(struct dis_discrete *dis, int32 mindex);
239 /**<
240 * Implementation function for dis_set_mindex() (debug mode).
241 * Do not call this function directly - use dis_set_mindex() instead.
242 */
243
244 #ifdef NDEBUG
245 #define dis_sindex(dis) (dis)->sindex
246 #else
247 #define dis_sindex(dis) dis_sindexF(dis)
248 #endif
249 /**<
250 * Gets the index of the variable as it appears in a solvers variable list.
251 * @param dis const struct dis_discrete*, the discrete var to query.
252 * @return The index as an int32.
253 * @see dis_sindexF()
254 */
255
256 #ifdef NDEBUG
257 #define dis_set_sindex(dis,index) (dis)->sindex = (index)
258 #else
259 #define dis_set_sindex(dis,index) dis_set_sindexF((dis),(index))
260 #endif
261 /**<
262 * Sets the index of the variable as it appears in a solvers variable list.
263 * @param dis const struct dis_discrete*, the discrete var to modify.
264 * @param index int32, the index value.
265 * @return No return value.
266 * @see dis_set_sindexF()
267 */
268
269 extern int32 dis_sindexF(const struct dis_discrete *dis);
270 /**<
271 * Implementation function for dis_sindex() (debug mode).
272 * Do not call this function directly - use dis_sindex() instead.
273 */
274 extern void dis_set_sindexF(struct dis_discrete *dis, int32 sindex);
275 /**<
276 * Implementation function for dis_set_sindex() (debug mode).
277 * Do not call this function directly - use dis_set_sindex() instead.
278 */
279
280 extern int32 dis_value(const struct dis_discrete *dis);
281 /**<
282 * Gets the currrent value field of the discrete variable.
283 */
284 extern void dis_set_value(struct dis_discrete *dis, int32 value);
285 /**<
286 * Sets the currrent value field of the discrete variable.
287 * dis_set_value() also assigns the value before modification to
288 * the previous value field of the dis_discrete
289 */
290
291 extern void dis_set_inst_and_field_value(struct dis_discrete *dis,
292 int32 value);
293 /**<
294 * Set the current value of the dis_discrete and the value of
295 * the corresponding instance simultaneously. Such a value is
296 * passed as argument
297 * In the case of symbols, dis_set_inst_and_field_value() has no effect,
298 * since the value of a symbol instance is not a integer, but a symchar,
299 * and a solver client will never redefine it.
300 * If the token is constant, the assignment wont be done and the
301 * value is not affected.
302 *
303 * It also assigns the value before modification to
304 * the previous value field of the dis_discrete
305 */
306 extern void dis_set_value_from_inst(struct dis_discrete *dis,
307 struct gl_list_t *symbol_list);
308 /**<
309 * Set the current value of a dis_discrete based on the value of the
310 * corresponding instance.
311 * If the token is constant, the assignment wont be done and the
312 * value is not affected.
313 *
314 * It also assigns the value before modification to
315 * the previous value field of the dis_discrete
316 */
317 #define dis_set_boolean_value(dis,val) dis_set_inst_and_field_value(dis,val)
318 /**<
319 * Used to assign integer values to the field
320 * value of a dis, using values coming from dis->datom where
321 * datom is a inst. In the case of symbol, we get an "equivalent"
322 * integer value.
323 * This function is particularly useful for symbol instances.
324 *
325 * It also assigns the value before modification to
326 * the previous value field of the dis_discrete
327 */
328
329 extern int32 dis_previous_value(const struct dis_discrete *dis);
330 /**< Gets the previous value field of the discrete variable. */
331 extern void dis_set_previous_value(struct dis_discrete *dis,
332 int32 value);
333 /**<
334 * Sets the previous value field of the discrete variable.
335 */
336
337
338 /*
339 * What constitutes a boolean_var
340 * is controlled by the ascend server via the following functions.
341 * Clients shouldn't use these.
342 */
343
344 #define BOOLEAN_VAR_STR "boolean_var"
345
346 extern boolean boolean_var(SlvBackendToken inst);
347 /**<
348 * Returns true if the instance in question matches the currently
349 * known definition of boolean_var.
350 */
351
352 extern boolean set_boolean_types(void);
353 /**<
354 * Sets (changes) the current definition of boolean_var to match
355 * the current library. Returns 1 if unsuccessful, 0 if ok.
356 */
357
358 extern int32 dis_nominal(struct dis_discrete *dis);
359 /**<
360 * Gets the nominal value of the boolean variable.
361 * If no nominal field in dis, returns 1.
362 */
363 extern void dis_set_nominal(struct dis_discrete *dis, int32 nominal);
364 /**<
365 * Sets the nominal value of the boolean variable.
366 * <!-- If no nominal field in dis, returns 1. -->
367 */
368
369 extern uint32 dis_fixed(struct dis_discrete *dis);
370 /**<
371 * Gets the fixed flag of the boolean variable. This
372 * has side effects in the ascend instance, with which
373 * we are keeping the bits in sync.
374 */
375 extern void dis_set_fixed(struct dis_discrete *dis, uint32 fixed);
376 /**<
377 * Sets the fixed flag of the boolean variable. This
378 * has side effects in the ascend instance, with which
379 * we are keeping the bits in sync.
380 */
381
382 /*
383 * The section of flagbit definitions
384 */
385 #define DIS_INCIDENT 0x1 /**< is this variable incident on some equation in
386 the slv_system? */
387 #define DIS_INWHEN 0x2 /**< is this variable in some WHEN in the slv_system? */
388 #define DIS_BVAR 0x4 /**< do we think this var a 'boolean_var'? */
389 #define DIS_CONST 0x8 /**< is this discrete variable a constant? */
390 #define DIS_FIXED 0x10 /**< is this variable considered fixed currently? */
391 #define DIS_INBLOCK 0x20 /**< */
392 #define DIS_ACTIVE 0x40 /**< is this variable currently active ? */
393 #define DIS_BOOLEAN 0x80 /**< is this variable of type e_dis_boolean_t ? */
394 #define DIS_VAL_MODIFIED 0x100 /**< Did the value of this variable change after the
395 last logical solution ? */
396 #define DIS_CHANGES_STRUCTURE 0x200 /**< Is this discrete variable associated with a WHEN
397 changes the structural analysis of a conditional
398 model */
399
400 #ifdef NDEBUG
401 #define dis_flags(dis) ((dis)->flags)
402 #else
403 #define dis_flags(dis) dis_flagsF(dis)
404 #endif
405 /**<
406 * Returns the flags field of the var.
407 * @param dis const struct dis_discrete*, the discrete var to query.
408 * @return The flags as a uint32.
409 * @see dis_flagsF()
410 */
411
412 #ifdef NDEBUG
413 #define dis_set_flags(dis,flags) ((dis)->flags = (flags))
414 #else
415 #define dis_set_flags(dis,flags) dis_set_flagsF((dis),(flags))
416 #endif
417 /**<
418 * Sets the entire flag field to the value of flags given.
419 * This flags value should be composed of the DIS_xxx macro values.
420 * @param dis const struct dis_discrete*, the discrete var to modify.
421 * @param flags uint32, the flags value.
422 * @return No return value.
423 * @see dis_set_flagsF()
424 */
425
426 extern uint32 dis_flagsF(const struct dis_discrete *dis);
427 /**<
428 * Implementation function for dis_flags() (debug mode).
429 * Do not call this function directly - use dis_flags() instead.
430 */
431 extern void dis_set_flagsF(struct dis_discrete *dis, uint32 flags);
432 /**<
433 * Implementation function for dis_set_flags() (debug mode).
434 * Do not call this function directly - use dis_set_flags() instead.
435 */
436
437 extern uint32 dis_flagbit(const struct dis_discrete *dis,
438 const uint32 name);
439 /**<
440 * Returns the value of the bit specified from the variable flags.
441 * name should be a DIS_xx flag defined above)
442 */
443
444 extern void dis_set_flagbit(struct dis_discrete *dis,
445 uint32 NAME, uint32 oneorzero);
446 /**<
447 * Sets the bit, which should be referred to by its macro name,
448 * on if oneorzero is >0 and off is oneorzero is 0.
449 * The macro names are the defined up at the top of this file.
450 */
451
452 extern int32 dis_apply_filter(const struct dis_discrete *dis,
453 const dis_filter_t *filter);
454 /**<
455 * Returns 1 if filter and var flags are compatible, 0 elsewise.
456 * See the filter description in rel.h. This is exactly the same.
457 */
458
459 #ifdef NDEBUG
460 #define dis_inwhen(dis) ((dis)->flags & DIS_INWHEN)
461 #define dis_const(dis) ((dis)->flags & DIS_CONST)
462 #define dis_in_block(dis) ((dis)->flags & DIS_INBLOCK)
463 #define dis_incident(dis) ((dis)->flags & DIS_INCIDENT)
464 #define dis_active(dis) ((dis)->flags & DIS_ACTIVE)
465 #define dis_boolean(dis) ((dis)->flags & DIS_BOOLEAN)
466 #define dis_val_modified(dis) ((dis)->flags & DIS_VAL_MODIFIED)
467 #define dis_changes_structure(dis) ((dis)->flags & DIS_CHANGES_STRUCTURE)
468 #else
469 #define dis_inwhen(dis) dis_flagbit((dis),DIS_INWHEN)
470 #define dis_const(dis) dis_flagbit((dis),DIS_CONST)
471 #define dis_in_block(dis) dis_flagbit((dis),DIS_INBLOCK)
472 #define dis_incident(dis) dis_flagbit((dis),DIS_INCIDENT)
473 #define dis_active(dis) dis_flagbit((dis),DIS_ACTIVE)
474 #define dis_boolean(dis) dis_flagbit((dis),DIS_BOOLEAN)
475 #define dis_val_modified(dis) dis_flagbit((dis),DIS_VAL_MODIFIED)
476 #define dis_changes_structure(dis) dis_flagbit((dis),DIS_CHANGES_STRUCTURE)
477 #endif /* NDEBUG */
478
479 #define dis_set_inwhen(dis,b) dis_set_flagbit((dis),DIS_INWHEN,(b))
480 #define dis_set_const(dis,b) dis_set_flagbit((dis),DIS_CONST,(b))
481 #define dis_set_in_block(dis,b) dis_set_flagbit((dis),DIS_INBLOCK,(b))
482 #define dis_set_incident(dis,b) dis_set_flagbit((dis),DIS_INCIDENT,(b))
483 #define dis_set_active(dis,b) dis_set_flagbit((dis),DIS_ACTIVE,(b))
484 #define dis_set_boolean(dis,b) dis_set_flagbit((dis),DIS_BOOLEAN,(b))
485 #define dis_set_val_modified(dis,b) \
486 dis_set_flagbit((dis),DIS_VAL_MODIFIED,(b))
487 #define dis_set_changes_structure(dis,b) \
488 dis_set_flagbit((dis),DIS_CHANGES_STRUCTURE,(b))
489
490 /*
491 * incident = dis_incident(dis)
492 * dis_set_incident(dis,incident)
493 * uint32 incident;
494 * struct dis_discrete *dis;
495 *
496 * Gets/sets the incident flag of the discrete variable.
497 */
498
499 extern
500 struct dis_discrete **dis_BackendTokens_to_dis(slv_system_t sys,
501 SlvBackendToken *tokenlist,
502 int32 len);
503 /**<
504 * dislist is NULL iff something is a miss, OTHERWISE it
505 * contains len struct dis_discrete *.
506 * The user should free the array dislist when done with it.
507 * Some entries in the array dislist may be NULL if the tokenlist
508 * contains a token which is not from the sys given.
509 * tokenlist[i] <--> dislist[i];<br><br>
510 *
511 * The whole point of a slv_system_t is to isolate the client from
512 * the compiler backend. Clients who find themselves in need of
513 * this function are very much in need of rethinking as well.
514 * For that reason, among others, this function is not heavily
515 * optimized, it is however reasonable for 1-off jobs.
516 */
517
518 /* @} */
519
520 #endif /* ASC_DISCRETE_H */
521

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