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

Annotation of /trunk/base/generic/solver/rel.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 301 - (hide annotations) (download) (as text)
Mon Feb 20 07:39:14 2006 UTC (16 years, 11 months ago) by johnpye
File MIME type: text/x-chdr
File size: 30963 byte(s)
Documentation and indentation changes
1 jds 54 /*
2 aw0a 1 * SLV: Ascend Numeric Solver
3     * by Karl Michael Westerberg
4     * Created: 2/6/90
5     * Version: $Revision: 1.41 $
6     * Version control file: $RCSfile: rel.h,v $
7     * Date last modified: $Date: 1998/02/05 15:59:24 $
8     * Last modified by: $Author: ballan $
9     *
10     * This file is part of the SLV solver.
11     *
12     * Copyright (C) 1990 Karl Michael Westerberg
13     * Copyright (C) 1993 Joseph Zaher
14     * Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan
15     *
16     * The SLV solver is free software; you can redistribute
17     * it and/or modify it under the terms of the GNU General Public License as
18     * published by the Free Software Foundation; either version 2 of the
19     * License, or (at your option) any later version.
20     *
21     * The SLV solver is distributed in hope that it will be
22     * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
23     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
24     * General Public License for more details.
25     *
26     * You should have received a copy of the GNU General Public License
27     * along with the program; if not, write to the Free Software Foundation,
28     * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
29     * COPYING. COPYING is found in ../compiler.
30     */
31    
32 jds 54 /** @file
33     * Relation module for the SLV solver.
34     * <pre>
35 aw0a 1 * Contents: Relation module (ascend)
36     *
37     * Authors: Karl Westerberg
38 jds 54 * Joseph Zaher
39 aw0a 1 *
40     * Dates: 06/90 - original version
41     * 04/94 - added rel_apply_filter() which uses the new
42     * rel_filter_t data structure for perfoming all
43     * relation filtering needs (eliminating the
44     * filter module)
45     *
46     * Description: This is the ascend version of the rel module. This
47     * version should be used by any user who receives his/her
48     * equations directly from an instance tree created by the
49     * ASCEND compiler.
50 jds 54 *
51     * Requires: #include "utilities/ascConfig.h"
52     * #include "var.h"
53     *
54     * SERVER ONLY: #include "expr.h"
55     * #include "types.h"
56     * #include "extfunc.h"
57     * #include "relation.h"
58     * #include "packages.h"
59     * #include "extcall.h"
60     * #include "mtx.h"
61     * </pre>
62 aw0a 1 */
63    
64 johnpye 67 #ifndef ASC_REL_H
65     #define ASC_REL_H
66 aw0a 1
67 jds 54 /*
68 aw0a 1 * rel_relation data type and basic type operators.
69     */
70    
71     #define rel_TOK_less 0x1
72     #define rel_TOK_equal 0x2
73     #define rel_TOK_greater 0x4
74    
75     struct rel_extnode {
76     int32 whichvar;
77 jds 54 struct ExtRelCache *cache; /**< pointer to private structure */
78 aw0a 1 };
79    
80 jds 54 /** The exact operator of a relation. */
81 aw0a 1 enum rel_enum {
82     e_rel_minimize,
83     e_rel_maximize,
84     e_rel_equal,
85     e_rel_not_equal,
86     e_rel_less,
87     e_rel_greater,
88     e_rel_lesseq,
89     e_rel_greatereq
90     };
91 jds 54
92     /** Backend relation types. */
93 aw0a 1 enum backend_enum {
94     e_rel_token,
95     e_rel_glassbox,
96     e_rel_blackbox
97     };
98 jds 54
99     /**
100     * Relation data structure.
101     * If you mess with this struct, change the defaults for it in .c file.
102     */
103 aw0a 1 struct rel_relation {
104     SlvBackendToken instance;
105 jds 54 struct rel_extnode *nodeinfo; /**< Not NULL if blackbox relation */
106 aw0a 1 struct var_variable **incidence;
107 jds 54 /**< array of atomic vars and nonvars in rel */
108     /*
109 aw0a 1 * For future use:
110     *
111 jds 54 * struct var_variable **incidentals; array of nonvars,
112 aw0a 1 * once solveratoms arrive.
113     *
114 jds 54 * int32 n_incidentals;
115 aw0a 1 */
116 jds 54 enum backend_enum type; /**< tokens, glassbox or blackbox */
117     int32 n_incidences; /**< length of incidence. */
118     int32 mindex; /**< index in the slv_system_t master list */
119     int32 sindex; /**< index in the slv_system_t solver list */
120     int32 model; /**< index of a hypothetical MODEL rel is from */
121     uint32 flags; /**< flags */
122 aw0a 1 };
123    
124 jds 54 extern struct rel_relation *rel_create(SlvBackendToken instance,
125     struct rel_relation *rel);
126     /**<
127 aw0a 1 * Creates a relation given the relation instance.
128     * If the rel supplied is NULL, we allocate the memory for the
129     * rel we return, else we just init the memory you hand us and
130 jds 54 * return it to you.<br><br>
131 aw0a 1 * We set the fields instance, nodeinfo, type following
132     * the instance. Setting the rest of the information is the job
133     * of the bridge building function between the ascend instance
134     * tree (or other relation back end) and the slv_system_t.
135     * In particular, the incidence list and indexing info is not
136     * handled here.
137     */
138    
139 jds 54 extern void rel_destroy(struct rel_relation *rel);
140     /**<
141 aw0a 1 * Destroys a relation.
142     */
143    
144 jds 54 extern void rel_write_name(slv_system_t sys, struct rel_relation *rel, FILE *file);
145     /**<
146 aw0a 1 * Writes a name to the file given. Handles NULL inputs gracefully.
147     * Does not print any whitespace, including carriage returns.
148     * Is faster than slv_print_var_name.
149     * If sys is NULL, writes full ascend name. If file or rel is NULL
150     * does not write.
151     */
152    
153 jds 54 /** Relation filter structure */
154 aw0a 1 typedef struct rel_filter_structure {
155 jds 54 uint32 matchbits; /**< Bits to match. */
156     uint32 matchvalue; /**< Value to match. */
157 aw0a 1 } rel_filter_t;
158 jds 54 /**< Relation filter type */
159 aw0a 1
160 jds 54 extern SlvBackendToken rel_instance(struct rel_relation *rel);
161     /**<
162 aw0a 1 * Returns the instance pointer from a rel.
163     */
164    
165 jds 54 extern void rel_set_extnodeinfo(struct rel_relation *rel,
166     struct rel_extnode *nodeinfo);
167     /**< Sets the external node information structure for a relation. */
168     extern struct rel_extnode *rel_extnodeinfo(struct rel_relation *rel);
169     /**<
170 aw0a 1 * Fetches the pointer to the external node information structure for
171     * a relation. If this is NULL, which will be the case for most
172     * relations, then there are no external call nodes present.
173     */
174    
175 jds 54 extern void rel_set_extwhichvar(struct rel_relation *rel, int whichvar);
176     /**< Sets the argument list index for a relation having external nodes. */
177     extern int32 rel_extwhichvar(struct rel_relation *rel);
178     /**<
179     * Returns the index into the argument list from which rel was
180     * constructed. This applies ONLY to rels that have external nodes !
181 aw0a 1 * Relations that have external nodes have associated with them an
182     * index into the argument list from which the relation was constructed.
183     * rel_whichvar returns that index. e.g. if when this relation was
184     * constructed from an external procedure call, the number of output
185     * variables was 4, and the number of inputs was 6, valid results from
186     * this rel_whichvar would be 7, 8, 9, 10.
187     * A return value <= 0 is an error.
188     */
189    
190 jds 54 extern boolean rel_less(struct rel_relation *rel);
191     /**<
192     * Returns true if the given relation is satisfied if "less than"
193     * is among those that make up the comparator of the relation
194     * (i.e. <>, <, or <=).<br><br>
195     * le==TRUE implies rel would be satisfied if lhs < rhs
196     */
197     extern boolean rel_equal(struct rel_relation *rel);
198     /**<
199     * Returns true if the given relation is satisfied if "equals"
200     * is among those that make up the comparator of the relation
201     * (i.e. =, >=, or <=).<br><br>
202     * eq==TRUE implies rel would be satisfied if lhs ~ rhs
203     */
204     extern boolean rel_greater(struct rel_relation *rel);
205     /**<
206     * Returns true if the given relation is satisfied if "greater than"
207     * is among those that make up the comparator of the relation
208     * (i.e. <>, >, or >=).<br><br>
209     * gr==TRUE implies rel would be satisfied if lhs > rhs
210     */
211     /* OLD GROUP COMMENT */
212     /*
213 aw0a 1 * le = rel_less(rel)
214     * eq = rel_equal(rel)
215     * gr = rel_greater(rel)
216     * boolean le,eq,gr;
217     * struct rel_relation *rel;
218     *
219     * Returns true if the given relation is satisfied if the
220     * operator in question is among those that make up the
221     * comparator of the relation. (e.g. rel_less is satisfied
222     * by (<>,<.<=).
223     * le==TRUE implies rel would be satisfied if lhs < rhs
224     * gr==TRUE implies rel would be satisfied if lhs > rhs
225     * eq==TRUE implies rel would be satisfied if lhs ~ rhs
226     */
227    
228 jds 54 extern enum rel_enum rel_relop(struct rel_relation *rel);
229     /**<
230 aw0a 1 * Returns the type of the relational operator of a given relation.
231     */
232    
233 jds 54 extern char *rel_make_name(slv_system_t sys, struct rel_relation *rel);
234     /**<
235 aw0a 1 * Copies of the relation instance name can be made and returned.
236     * The string returned should be freed when no longer in use.
237     */
238 jds 54
239     extern int32 rel_mindex(struct rel_relation *rel);
240     /**<
241     * Retrieves the index number of the given relation as it
242     * appears in a slv_system_t master relation list.
243     */
244     extern void rel_set_mindex(struct rel_relation *rel, int32 index);
245     /**<
246     * Sets the index number of the given relation as it
247     * appears in a slv_system_t master relation list.
248 aw0a 1 */
249    
250 jds 54 extern int32 rel_sindex(const struct rel_relation *rel);
251     /**<
252     * Retrieves the index number of the given relation as it
253     * appears in a solvers relation list. The index is most often used
254     * to assign the relation to a specific original row of a matrix.
255     */
256     extern void rel_set_sindex(struct rel_relation *rel, int32 index);
257     /**<
258     * Sets the index number of the given relation as it
259 aw0a 1 * appears in a solvers relation list. The index is most often used
260     * to assign the relation to a specific original row of a matrix.
261     */
262    
263 jds 54 extern int32 rel_model(const struct rel_relation *rel);
264     /**<
265     * Retrieves the model number of the given relation.
266     * In a hierarchy, relations come in groups associated with
267     * models. Models are numbered from 1 to some upper limit.
268     */
269     extern void rel_set_model(struct rel_relation *rel, int32 index);
270     /**<
271     * Sets the model number of the given relation.
272 aw0a 1 * In a hierarchy, relations come in groups associated with
273     * models. Models are numbered from 1 to some upper limit.
274     */
275    
276 jds 54 extern real64 rel_residual(struct rel_relation *rel);
277     /**<
278     * Retrieves the residual field of the given relation.
279 aw0a 1 * Note that the residual is not actually computed by rel_residual:
280     * there is no guarantee (from this function) that the residual is
281     * actually correct.
282     */
283 jds 54 extern void rel_set_residual(struct rel_relation *rel, real64 residual);
284     /**<
285     * Sets the residual field of the given relation.
286     */
287 aw0a 1
288 jds 54 extern real64 rel_nominal(struct rel_relation *rel);
289     /**<
290 aw0a 1 * Retrieves the nominal field of the given relation.
291     * No slv client has any business being able to set the nominal,
292     * so no such operator is provided.
293     */
294    
295 jds 54 extern void rel_set_nominal(struct rel_relation *rel, real64 nominal);
296     /**<
297     * Breaking the 'rule' of rel_nominal() for the time being.
298     * @todo Remove rel_set_nominal() or change "rule" stated by rel_nominal().
299 aw0a 1 */
300 jds 54
301 aw0a 1 #ifdef NDEBUG
302 jds 54 #define rel_n_incidences(rel) ((rel)->n_incidences)
303 aw0a 1 #else
304 jds 54 #define rel_n_incidences(rel) rel_n_incidencesF(rel)
305     #endif
306     /**<
307     * Returns the length of the incidence_list for a relation.
308     * Not everything in the incidence list is necessarily a
309     * variable for your particular solver -- check the flags.
310     * @param rel struct rel_relation *, the relation to query.
311     * @return Returns the length as an int32.
312     * @see rel_n_incidencesF()
313     */
314 aw0a 1
315 jds 54 #ifdef NDEBUG
316     #define rel_set_incidences(rel,n,ilist) \
317     (rel)->n_incidences=(n); (rel)->incidence = (ilist)
318     #else
319     #define rel_set_incidences(rel,n,ilist) rel_set_incidencesF((rel),(n),(ilist))
320     #endif
321     /**<
322     * Sets the length and incidence_list for a relation.
323     * Not everything in the incidence list is necessarily a
324     * variable for your particular solver -- check the flags.
325     * Solver clients should not call rel_set_incidences,
326     * it is only for use by constructors of bridges to relation
327     * back ends.
328     * @param rel struct rel_relation *, the relation to modify.
329     * @param n int32
330     * @param ilist struct var_variable **, the incidence list
331     * @return No return value.
332     * @see rel_set_incidencesF()
333     */
334    
335     extern int32 rel_n_incidencesF(struct rel_relation *rel);
336     /**<
337     * Implementation function for rel_n_incidences(). Do not call
338     * this function directly - use rel_n_incidences() instead.
339     */
340     extern void rel_set_incidencesF(struct rel_relation *rel,
341     int32 n,
342     struct var_variable **ilist);
343     /**<
344     * Implementation function for rel_set_incidences(). Do not call
345     * this function directly - use rel_set_incidences() instead.
346     */
347     /* OLD GROUP COMMENTS */
348     /*
349     * rel_n_incidences(rel)
350     * rel_set_incidences(rel,n,ilist) //SERVER ONLY
351     * struct rel_relation *rel;
352     * struct var_variable **ilist;
353 aw0a 1 * int32 n;
354     *
355     * rel_n_incidences returns the length of the incidence_list.
356     * Not everything in the incidence list is necessarily a
357     * variable for your particular solver -- check the flags.
358     * Solver clients should not call rel_set_incidences,
359     * it is only for use by constructors of bridges to relation
360     * back ends.
361     */
362    
363     extern struct var_variable
364 jds 54 **rel_incidence_list_to_modify(struct rel_relation *rel);
365     /**<
366     * Returns a non-const pointer to an array rel_n_incidences(rel)
367     * long of vars.
368     * @see rel_incidence_list().
369     */
370     extern const struct var_variable **rel_incidence_list(struct rel_relation *rel);
371     /**<
372 aw0a 1 * Returns a pointer to an array rel_n_incidences(rel) long of vars.
373     * Each element of the array is a struct var_variable *.
374     * Check the var sindex to see where each might go in a jacobian.
375     * If there is no incidence, NULL is returned.
376 jds 54 * Pointers in this array will be unique.<br><br>
377     * The list belongs to the relation. Do not destroy it. Do not change it.<br><br>
378 aw0a 1 *
379 jds 54 * The return value IS NOT A NULL-TERMINATED LIST.
380 aw0a 1 */
381    
382 jds 54 /*
383 aw0a 1 * relation filtration functions.
384     * We have a lot (32) of binary (one bit) flags a client may want to query
385     * in arbitrary combinations and paying attention to only certain of
386     * the bits. We will provide a set of macros and functions for each of
387     * these bits and for operations on the whole set.
388     */
389    
390 jds 54 extern int32 rel_apply_filter(const struct rel_relation *rel,
391     rel_filter_t *filter);
392 ben.allan 33 /**<
393 aw0a 1 * Returns 1 only if all of the positions specified in
394     * filter->matchbits have the same values in
395     * filter->matchvalue and the relation's flags value.
396 jds 54 * Bits set to 0 in filter->matchbits are ignored for the test.<br><br>
397 aw0a 1 *
398     * EXAMPLE:
399     * To find out if a relation is an unsatisfied equality:
400     * We don't care about anything except satisfaction and equality,
401     * so set filter->matchbits = (REL_SATISFIED | REL_EQUALITY);
402     * We want relation NOT satisfied, so leave REL_SATISFIED = 0
403     * in filter->matchvalue, i.e. filter->matchvalue = REL_EQUALITY;
404     * Usually it is most convenient to just declare a rel_filter_t filt;
405     * locally in a function and then take the address of it (&filt) after
406     * setting filt.matchbits = (| of all your interesting bits) and
407     * setting filt.matchvalue = (| of the bits you want to be TRUE).
408     */
409    
410 jds 54 extern uint32 rel_flags(struct rel_relation *rel);
411     /**<
412     * Returns the flags field of the relation.
413     */
414     extern void rel_set_flags(struct rel_relation *rel, uint32 flags);
415     /**<
416     * Sets the entire flag field to the value of flags given.
417 aw0a 1 */
418    
419 jds 54 extern uint32 rel_flagbit(struct rel_relation *rel, uint32 name);
420     /**<
421     * Returns the value of the bit specified from the relation flags.
422 aw0a 1 * name should be a REL_xx flag defined above)
423     */
424    
425 jds 54 extern void rel_set_flagbit(struct rel_relation *rel,
426     uint32 NAME, uint32 oneorzero);
427     /**<
428 aw0a 1 * Sets the bit, which should be referred to by its macro name,
429     * on if oneorzero is >0 and off is oneorzero is 0.
430     * The macro names are the defined up at the top of this file.
431 jds 54 * <pre>
432     * Example:
433     * rel_set_flags(rel,REL_PARTITION,1) turns on the REL_PARTITION bit.
434 aw0a 1 *
435 jds 54 * What it really does is:
436     * if (oneorzero) {
437     * rel->flags |= field;
438     * } else {
439     * rel->flags &= ~field;
440     * }
441     * </pre>
442 aw0a 1 * In unix, see also man 3f bit or man not.
443     */
444    
445 jds 54 /*
446 aw0a 1 * the bit flags. explained afterward. several are for use of
447 jds 54 * transient clients and should be ignored by solver engines
448 aw0a 1 */
449 jds 54 #define REL_PARTITION 0x1
450     /**< Is it in the interesting region? Reordering clients. */
451     #define REL_TORN 0x2
452     /**< Is it a tear? Reordering clients output. */
453     #define REL_INTERFACE 0x4
454     /**< User suggests it's a tear eqn. Solvers, ui clients. */
455     #define REL_INCLUDED 0x8
456     /**<
457     * User wants eqn in problem. Solvers, ui clients.
458     * Use rel_set_* to change.
459     * INCLUDED is as yet a funny one. Treat it as readonly because
460     * you can only change it using a real function and not the
461     * bit manipulation functions. It is here in the bits because
462     * it is useful in filters sometimes.
463     */
464     #define REL_OBJNEGATE 0x10
465     /**< Read_only for clients. Rel module. */
466     #define REL_BLACKBOX 0x20
467     /**< Read_only for clients. Rel module. */
468     #define REL_SATISFIED 0x40
469 ben.allan 33 /**<
470 jds 54 * Has rel been pronounced satisfied by someone?
471     * Bit should be treated as readonly. use rel_set_* to change.
472 aw0a 1 */
473 jds 54 #define REL_EQUALITY 0x80
474     /**< Is relation an equality? Readonly for clients. */
475     #define REL_INBLOCK 0x100
476     /**< Is the relation in the current block of registered client? For clients. */
477     /* Conditional Modeling */
478 aw0a 1 #define REL_INWHEN 0x200
479 jds 54 /**< Is relation in a when? Readonly for clients. */
480 aw0a 1 #define REL_ACTIVE 0x400
481 jds 54 /**< Is this relation currently a part of my problem? */
482 aw0a 1 #define REL_INVARIANT 0x800
483 jds 54 /**< Is this relation an invariant in the conditional modeling analysis? */
484     /* Conditional Relations (Boundaries) */
485     #define REL_CONDITIONAL 0x1000
486     /**< Is relation conditional? Readonly for clients. */
487     #define REL_IN_CUR_SUBREGION 0x2000
488     /**< Is the relation in the subregion currently analyzed? */
489 aw0a 1 #define REL_GENERATED 0x10000
490 jds 54 /**<
491     * Temporary relation that doesn't exist independently in the backend,
492     * but is made by some process of the backend or the solver client.
493     * Is rel fake and cooked up for this system only? */
494    
495     /* OLD GROUP COMMENTS */
496     /*
497 aw0a 1 * REL_PARTITION reordering clients. is it in the interesting region
498     * REL_TORN reordering clients output. is it a tear.
499     * REL_INTERFACE solvers, ui clients. user suggests it's a tear eqn.
500     * REL_INCLUDED solvers, ui clients. user wants eqn in problem.
501     * bit should be treated as readonly. use rel_set_*
502     * to change.
503     * REL_OBJNEGATE rel module. read_only for clients.
504     * REL_BLACKBOX rel module. read_only for clients.
505     * REL_SATISFIED has rel been pronounced satisfied by someone?
506     * bit should be treated as readonly. use rel_set_*
507     * to change.
508     * REL_EQUALITY is relation an equality? readonly for clients.
509     * REL_INBLOCK is the relation in the current block of registered
510     * client? for clients.
511     * REL_INWHEN is relation in a when? readonly for clients.
512     * REL_ACTIVE is this relation currently a part of my problem ?
513 jds 54 * REL_INVARIANT is this relation an invariant in the conditional
514 aw0a 1 * modeling analysis
515     * REL_CONDITIONAL is relation conditional? readonly for clients
516     * REL_IN_CUR_SUBREGION is the relation in the subregion currently
517     * analyzed ?
518     * REL_GENERATED is rel fake and cooked up for this system only?
519     */
520    
521 jds 54 /*
522     * the bit flag lookups
523 aw0a 1 */
524     #ifdef NDEBUG
525 jds 54 #define rel_partition(rel) ((rel)->flags & REL_PARTITION)
526     #define rel_torn(rel) ((rel)->flags & REL_TORN)
527     #define rel_interface(rel) ((rel)->flags & REL_INTERFACE)
528     #define rel_obj_negate(rel) ((rel)->flags & REL_OBJNEGATE)
529     /**<
530     * Returns TRUE if relation is of type e_maximize.
531     * Returns FALSE if relation is of type e_minimize.
532     * Note: should only be used on objectives. other relations
533     * will give a meaningless result (probably FALSE).
534     */
535     #define rel_blackbox(rel) ((rel)->flags & REL_BLACKBOX)
536     #define rel_satisfied(rel) ((rel)->flags & REL_SATISFIED)
537     /**< Retrieves the satisfied field of the given relation.
538     * See rel_residual() for disclaimer. */
539     #define rel_equality(rel) ((rel)->flags & REL_EQUALITY)
540     /**< TRUE if relation is of form lhs = rhs. */
541     #define rel_in_block(rel) ((rel)->flags & REL_INBLOCK)
542     /**< Retrieves the INBLOCK member of the given relation flags
543     * which determines if the relation is within the current block. */
544     #define rel_in_when(rel) ((rel)->flags & REL_INWHEN)
545     #define rel_active(rel) ((rel)->flags & REL_ACTIVE)
546     #define rel_invariant(rel) ((rel)->flags & REL_INVARIANT)
547     #define rel_conditional(rel) ((rel)->flags & REL_CONDITIONAL)
548     #define rel_in_cur_subregion(rel) ((rel)->flags & REL_IN_CUR_SUBREGION)
549     #define rel_generated(rel) ((rel)->flags & REL_GENERATED)
550 aw0a 1 #else
551 jds 54 #define rel_partition(rel) rel_flagbit((rel),REL_PARTITION)
552     #define rel_torn(rel) rel_flagbit((rel),REL_TORN)
553     #define rel_interface(rel) rel_flagbit((rel),REL_INTERFACE)
554     #define rel_obj_negate(rel) rel_flagbit((rel),REL_OBJNEGATE)
555     /**<
556     * Returns TRUE if relation is of type e_maximize.
557     * Returns FALSE if relation is of type e_minimize.
558     * Note: should only be used on objectives. other relations
559     * will give a meaningless result (probably FALSE).
560     */
561     #define rel_blackbox(rel) rel_flagbit((rel),REL_BLACKBOX)
562     #define rel_satisfied(rel) rel_flagbit((rel),REL_SATISFIED)
563     /**< Retrieves the satisfied field of the given relation.
564     * See rel_residual() for disclaimer. */
565     #define rel_equality(rel) rel_flagbit((rel),REL_EQUALITY)
566     /**< TRUE if relation is of form lhs = rhs. */
567     #define rel_in_block(rel) rel_flagbit((rel),REL_INBLOCK)
568     /**< Retrieves the INBLOCK member of the given relation flags
569     * which determines if the relation is within the current block. */
570     #define rel_in_when(rel) rel_flagbit((rel),REL_INWHEN)
571     #define rel_active(rel) rel_flagbit((rel),REL_ACTIVE)
572     #define rel_invariant(rel) rel_flagbit((rel),REL_INVARIANT)
573     #define rel_conditional(rel) rel_flagbit((rel),REL_CONDITIONAL)
574     #define rel_in_cur_subregion(rel) rel_flagbit((rel),REL_IN_CUR_SUBREGION)
575     #define rel_generated(rel) rel_flagbit((rel),REL_GENERATED)
576     #endif /* NDEBUG */
577 aw0a 1
578 jds 54 /*
579 aw0a 1 * bit flag assignments. any value other than 0 for bv turns the
580     * named flag to 1. 0 sets it to 0.
581     * Many of these bits have read-only semantics for clients.
582     * Take care when setting them.
583     */
584 jds 54 #define rel_set_partition(rel,bitval) rel_set_flagbit((rel),REL_PARTITION,(bitval))
585     #define rel_set_torn(rel,bitval) rel_set_flagbit((rel),REL_TORN,(bitval))
586     #define rel_set_interface(rel,bitval) rel_set_flagbit((rel),REL_INTERFACE,(bitval))
587     #define rel_set_obj_negate(rel,bitval) rel_set_flagbit((rel),REL_OBJNEGATE,(bitval))
588     #define rel_set_blackbox(rel,bitval) rel_set_flagbit((rel),REL_BLACKBOX,(bitval))
589     #define rel_set_satisfied(rel,bitval) rel_set_flagbit((rel),REL_SATISFIED,(bitval))
590     #define rel_set_equality(rel,bitval) rel_set_flagbit((rel),REL_EQUALITY,(bitval))
591     #define rel_set_in_block(rel,bitval) rel_set_flagbit((rel),REL_INBLOCK,(bitval))
592     #define rel_set_in_when(rel,bitval) rel_set_flagbit((rel),REL_INWHEN,(bitval))
593     #define rel_set_active(rel,bitval) rel_set_flagbit((rel),REL_ACTIVE,(bitval))
594     #define rel_set_invariant(rel,bitval) rel_set_flagbit((rel),REL_INVARIANT,(bitval))
595     #define rel_set_conditional(rel,bitval) \
596     rel_set_flagbit((rel),REL_CONDITIONAL,(bitval))
597     #define rel_set_in_cur_subregion(rel,bitval) \
598     rel_set_flagbit((rel),REL_IN_CUR_SUBREGION,(bitval))
599     #define rel_set_generated(rel,bitval) rel_set_flagbit((rel),REL_GENERATED,(bitval))
600 aw0a 1
601 jds 54 extern uint32 rel_included(struct rel_relation *rel);
602     /**<
603     * Retrieves the included field of the given relation.
604     * @todo This has side effects on the ascend instance, so it isn't
605     * implemented with the rest of the macros above. This needs to
606     * change.
607     */
608     extern void rel_set_included(struct rel_relation *rel, uint32 included);
609     /**<
610     * Sets the included field of the given relation.
611     * <!-- This has side effect on the ascend instance, so it isn't -->
612     * <!-- implemented with the rest of the macros above. This needs to -->
613     * <!-- change. -->
614 aw0a 1 */
615    
616 jds 54 /*
617 aw0a 1 * in_block = rel_in_block(rel)
618     * rel_set_in_block(rel,in_block)
619     * uint32 in_block;
620     * struct rel_relation *rel;
621     *
622     * Sets or retrieves the INBLOCK member of the given relation flags
623     * which determines if the relation is within the current block.
624     */
625    
626 jds 54 /*
627 aw0a 1 * rel_obj_negate(rel)
628     * struct rel_relation *rel;
629     *
630     * Returns TRUE if relation is of type e_maximize.
631     * Returns FALSE if relation is of type e_minimize.
632     * Note: should only be used on objectives. other relations
633 jds 54 * will give a meaningless result (probably FALSE).
634 aw0a 1 */
635    
636 jds 54 /*
637 aw0a 1 * satisfied = rel_satisfied(rel)
638     * rel_set_satisfied(rel,satisfied)
639     * uint32 satisfied;
640     * struct rel_relation *rel;
641     *
642     * Sets or retrieves the satisfied field of the given relation (see
643     * rel_residual() for disclaimer).
644     */
645    
646 jds 54 /*
647 aw0a 1 * equality = rel_equality(rel)
648     * rel_set_equality(rel,equality)
649     * uint32 equality;
650     * struct rel_relation *rel;
651     *
652     * TRUE if relation is of form lhs = rhs.
653 jds 54 */
654 aw0a 1
655 jds 54 extern real64 rel_multiplier(struct rel_relation *rel);
656     /**<
657     * Retrieves the multiplier field of the given relation.
658     * This is expected to be computed as a lagrange multiplier which will
659     * relate the gradient of the relation rel with that of some objective
660     * function.
661     */
662     extern void rel_set_multiplier(struct rel_relation *rel, real64 multiplier);
663     /**<
664     * (<!-- won a temporary reprieve. this should be a system property, not rel.) -->
665     * Sets the multiplier field of the given relation.
666 aw0a 1 * This is expected to be computed as a lagrange multiplier which will
667     * relate the gradient of the relation rel with that of some objective
668     * function.
669     */
670    
671 jds 54 /*
672 aw0a 1 * rel_relation utility functions.
673     *
674     * Things for the server side only. Not visible to clients.
675 jds 54 *
676     * Ok, really nosy clients courting death can cheat. Don't cry when
677 aw0a 1 * they break.
678     * We make absolutely no commitment to being compatible with this portion
679     * of the header at any time in the future.
680     */
681     #ifdef _SLV_SERVER_C_SEEN_
682 jds 54 /*
683     * requires #include "expr.h"
684     * requires #include "types.h"
685     * requires #include "extfunc.h"
686     * requires #include "relation.h"
687     * requires #include "packages.h"
688     * requires #include "extcall.h"
689     * requires #include "mtx.h"
690 aw0a 1 */
691    
692 ben.allan 33 extern double g_external_tolerance; /**< DEFAULT 1e-12 */
693 aw0a 1
694     struct ExtRelCache {
695     int32 nodestamp;
696 jds 54 struct ExternalFunc *efunc; /**< pre_slv, eval and deriv funcs */
697     SlvBackendToken data; /**< only passed on pre_slv */
698     struct gl_list_t *arglist; /**< only passed on pre_slv */
699 aw0a 1 struct gl_list_t *inputlist;
700 jds 54 void *user_data; /**< user data */
701 aw0a 1 int32 ninputs, noutputs;
702     double *inputs;
703     double *outputs;
704     double *jacobian;
705 jds 54 unsigned newcalc_done :1; /**< bits needed to control */
706     unsigned first_func_eval :1; /**< recalculation. until we can */
707     unsigned first_deriv_eval :1; /**< do proper block coding */
708 aw0a 1 };
709    
710 jds 54 extern struct ExtRelCache *rel_extcache(struct rel_relation *rel);
711     /**<
712     * Retrieve external relation information.
713     * This applies ONLY to rels that have external nodes !
714     * Ensure this by calling rel_extnodeinfo FIRST !
715     * This is the gateway to the external relation information
716     * stashed away to make processing of external relations efficient.
717     * See the file extrel.[ch] for functions to deal with the external
718     * relations cache, unless of course you are a client in which CASE
719     * don't.
720     */
721     extern void rel_set_extcache(struct rel_relation *rel, struct ExtRelCache *cache);
722     /**<
723 aw0a 1 * cache = rel_extcache(rel);
724     * rel_set_extcache(rel,cache);
725     * struct rel_relation *rel;
726     * struct ExtRelCache *cache;
727     *
728 jds 54 * Set external relation information.
729 aw0a 1 * This applies ONLY to rels that have external nodes !
730     * Ensure this by calling rel_extnodeinfo FIRST !
731     * This is the gateway to the external relation information
732     * stashed away to make processing of external relations efficient.
733     * See the file extrel.[ch] for functions to deal with the external
734     * relations cache, unless of course you are a client in which CASE
735     * don't.
736     */
737    
738 jds 54 /*
739 aw0a 1 * The following aren't commented because Kirk Abbott didn't comment them.
740     * It's all server magic anyway?
741     */
742    
743 jds 54 extern struct ExtRelCache *CreateExtRelCache(struct ExtCallNode *ext);
744     struct ExtRelCache *CreateCacheFromInstance(SlvBackendToken relinst);
745     extern void ExtRel_DestroyCache(struct ExtRelCache *cache);
746     extern int32 ExtRel_PreSolve(struct ExtRelCache *cache, int32 setup);
747     extern real64 ExtRel_Evaluate_RHS(struct rel_relation *rel);
748     extern real64 ExtRel_Evaluate_LHS(struct rel_relation *rel);
749     extern real64 ExtRel_Diffs_RHS(struct rel_relation *rel,
750     var_filter_t *filter,
751     int32 row,
752     mtx_matrix_t matrix);
753     extern real64 ExtRel_Diffs_LHS(struct rel_relation *rel,
754     var_filter_t *filter,
755     int32 row,
756     mtx_matrix_t matrix); /**< not implemented */
757 aw0a 1
758 jds 54 #endif /* _SLV_SERVER_C_SEEN_ */
759 aw0a 1
760 jds 54 /*
761 aw0a 1 * Things dead.
762     */
763 jds 54 /* DEFUNCT
764 aw0a 1 * extern struct rel_relation *rel_objcreate(SlvBackendToken, boolean);
765     * rel = rel_objcreate(instance,negate)
766     * struct rel_relation *rel;
767     * boolean negate;
768     * SlvBackendToken instance;
769     *
770     * Creates an objective relation given the relation instance.
771     * The other fields are given default values. The lhs will be NULL.
772     * objrels may not have extrel caches. Use a dummy relation if
773     * necessary. Negate must be TRUE for a maximize relation, FALSE for
774     * a minimize relation.
775     */
776    
777 jds 54 /* DEFUNCT
778 aw0a 1 * If you're smart enough to understand the answer to this question,
779     * then you should be asking the instance directly, not asking us.
780     * extern enum rel_enum rel_type(struct rel_relation *);
781     * rtype = rel_type(rel);
782     * rel_enum rtype;
783     * struct rel_relation *rel;
784     * Returns the type of a given relation. This indicates whether the
785     * the relation is a token, opcode, glassbox, or blackbox relation.
786     */
787    
788 jds 54 /* DEFUNCT for now.
789 aw0a 1 * extern boolean rel_in_subregion(struct rel_relation *);
790     * in_subregion = rel_in_subregion(rel)
791     * boolean in_subregion;
792     * struct rel_relation *rel;
793     *
794     * Computes if the conditions of the relation are all met by the
795     * current values of the subregion field of each relevant boundary.
796     * It will return TRUE even if there are no conditions.
797     */
798    
799 jds 54 /* DEFUNCT the solver has no business knowing about sides. this is the
800 aw0a 1 * compilers job. temporarily still active.
801     * extern expr_t rel_lhs(struct rel_relation *);
802     * extern expr_t rel_rhs(struct rel_relation *);
803     * lhs = rel_lhs(rel)
804     * rhs = rel_rhs(rel)
805     * expr_t lhs,rhs;
806     * struct rel_relation *rel;
807     *
808     * Fetches the (internal copy of the) rhs and lhs of the relation.
809     * The user should not modify the expression, nor should the user
810     * use the expression after the relation is destroyed or the
811     * lhs/rhs has been re-set.
812     */
813    
814 johnpye 67 #endif /* ASC_REL_H */
815 aw0a 1

Properties

Name Value
svn:executable *

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