/[ascend]/trunk/base/generic/compiler/relation_util.h
ViewVC logotype

Contents of /trunk/base/generic/compiler/relation_util.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 54 - (show annotations) (download) (as text)
Tue Aug 2 11:20:09 2005 UTC (14 years, 4 months ago) by jds
File MIME type: text/x-chdr
File size: 34152 byte(s)
Manual rework of doxygen comments in all headers.
- Added @file comment to all headers.
- Added parameter names to all function declarations in headers.
- Corrected comment referencing where necessary.
- Split some comments which documented blocks of declarations.
- Converted notes about required work into @todo comments so doxygen can generate a todo list.
Minor bug fixes.
1 /*
2 * Relation utility functions for Ascend
3 * Version: $Revision: 1.27 $
4 * Version control file: $RCSfile: relation_util.h,v $
5 * Date last modified: $Date: 1998/02/05 16:37:48 $
6 * Last modified by: $Author: ballan $
7 * Part of Ascend
8 *
9 * This file is part of the Ascend Programming System.
10 *
11 * Copyright (C) 1990 Karl Michael Westerberg, Thomas Guthrie Weidner Epperly
12 * Copyright (C) 1993 Joseph James Zaher
13 * Copyright (C) 1993, 1994 Benjamin Andrew Allan, Joseph James Zaher
14 * Copyright (C) 1996 Benjamin Andrew Allan, Kenneth Tyner
15 *
16 * The Ascend Interpreter 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 * Ascend 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.
30 */
31
32 /** @file
33 * Relation utility functions for Ascend.
34 * This module defines the dimensionality checking and some other
35 * auxillaries for Ascend.
36 * <pre>
37 * When including this file, you must include:
38 * #include "utilities/ascConfig.h"
39 * #include "compiler/fractions.h"
40 * #include "compiler/compiler.h"
41 * #include "compiler/functype.h"
42 * #include "compiler/safe.h"
43 * #include "compiler/dimen.h"
44 * #include "compiler/types.h"
45 * #include "compiler/relation_type.h"
46 * #include "compiler/relation_util.h"
47 * </pre>
48 */
49
50 #ifndef __RELATION_UTIL_H_SEEN__
51 #define __RELATION_UTIL_H_SEEN__
52
53 extern int g_check_dimensions_noisy;
54 /**<
55 * If 0, warnings are suppressed. If 1, warnings are given
56 * from RelationCheckDimensions();
57 */
58
59 extern int RelationCheckDimensions(struct relation *rel, dim_type *dimens);
60 /**<
61 * <!-- valid = RelationCheckDimensions(rel,dimens); -->
62 * <!-- int valid; -->
63 * <!-- struct relation *rel; -->
64 * <!-- dim_type *dimens; -->
65 *
66 * Scans a relation in postfix and collects all dimensional
67 * information by applying each token. It returns a value of TRUE
68 * only if no real instances or real atom instances with wild
69 * dimensionality and no dimensional inconsistencies were encountered.
70 * If the return value is 2 rather than 1, then the dimensionality
71 * has been determined before.
72 * The address of an allocated dimension type is passed in so that
73 * the dimensions of the relation (or at least what the function
74 * thinks the dimensions ought to be) can be also obtained.
75 *
76 * THIS ONLY WORKS ON e_token relations and maybe in future e_opcode
77 * relations. rel is assumed to be valid when called. !!!
78 *
79 * This brings in the asc_check_dimensions function from ascend_utils.
80 * 3/96 Ben Allan
81 */
82
83 extern enum Expr_enum RelationRelop(CONST struct relation *rel);
84 /**<
85 * <!-- enum Expr_enum RelationRelop(rel) -->
86 * <!-- CONST struct relation *rel; -->
87 * Return the type of the relation operator of the relation.
88 * Returns one of the following:
89 * <pre>
90 * e_equal equality constraint
91 * e_notequal non-equality contraint
92 * e_less less than contraint
93 * e_greater greater than contraint
94 * e_lesseq less than or equal contraint
95 * e_greatereq greater than or equal contraint
96 * e_maximize objective function to be maximized (rhs is empty)
97 * e_minimize objective function to be minimized (rhs is empty)
98 * </pre>
99 */
100
101 extern unsigned long NumberVariables(CONST struct relation *rel);
102 /**<
103 * <!-- unsigned long NumberVariables(rel) -->
104 * <!-- struct relation *rel; -->
105 * This will indicate the number of distinct real atoms to which this relation
106 * points. This number contains both fixed and non-fixed atoms.
107 * This routine is smart enough to deal with all the different relation types.
108 */
109
110 extern struct Instance *RelationVariable(CONST struct relation *rel,
111 unsigned long varnum);
112 /**<
113 * <!-- struct Instance *RelationVariable(rel,varnum) -->
114 * <!-- struct relation *rel; -->
115 * <!-- unsigned long varnum; 1 <= varnum <= NumberVariables(rel); -->
116 * This will return the varnum'th variable.
117 * This routine is smart enough to deal with all the different relation
118 * types.
119 */
120
121 /*----------------------------------------------------------------------------
122 * TokenRelation and OpCodeRelation specific code.
123 *
124 * It is the responsibility of the user of these routines to be aware
125 * of the type of relation being used. Very little sanity checking is
126 * done.
127 *----------------------------------------------------------------------------
128 */
129
130 extern unsigned long RelationLength(CONST struct relation *rel, int lhs);
131 /**<
132 * <!-- unsigned long RelationLength(rel,lhs) -->
133 * <!-- const struct relation *rel; -->
134 * <!-- int lhs; -->
135 * If lhs is true, return the number of terms on the left hand side of the
136 * relation. Otherwise, return the number of terms on the right hand side
137 * of the relation.
138 */
139
140 extern CONST struct relation_term *RelationTerm(CONST struct relation *rel,
141 unsigned long pos,
142 int lhs);
143 /**<
144 * <!-- const struct relation_term *RelationTerm(rel,pos,lhs) -->
145 * <!-- const struct relation *rel; -->
146 * <!-- unsigned long pos; -->
147 * <!-- int lhs; -->
148 * If lhs is true, return the term in position pos of the left hand side.
149 * Otherwise, return the term in position pos of the right hand side.
150 * A bizarre thing about this operator: 1 <= pos <= RelationLength(rel,lhs).
151 * This is a holdover from gl_list days.
152 */
153
154 #ifdef NDEBUG
155 #define NewRelationTerm(r,p,l) \
156 A_TERM( (l)!=0 ? (&(RTOKEN(r).lhs[(p)])) : (&(RTOKEN(r).rhs[(p)])) )
157 #else
158 #define NewRelationTerm(r,p,l) NewRelationTermF((r),(p),(l))
159 #endif
160 /**<
161 * If l is true, return the term in position p of the left hand side.
162 * Otherwise, return the term in position p of the right hand side.
163 * For this operator: 0 <= p < RelationLength(rel,lhs) as a C array.
164 * Once Everybody gets their damn hands off RelationTerm, switch its
165 * semantics and eliminate one of this pair.
166 * @param r CONST struct relation*, the relation to query.
167 * @param p unsigned long, the position to retrieve.
168 * @param l int, flag for whether to return from the lhs or rhs.
169 * @return The specified term as a CONST struct relation_term*.
170 * @see NewRelationTermF()
171 */
172 extern CONST struct relation_term
173 *NewRelationTermF(CONST struct relation *rel, unsigned long apos, int lhs);
174 /**<
175 * <!-- const struct relation_term *NewRelationTerm(rel,apos,lhs) -->
176 * <!-- const struct relation *rel; -->
177 * <!-- unsigned long apos; -->
178 * <!-- int lhs; -->
179 * <!-- If lhs is true, return the term in position apos of the left hand side; -->
180 * <!-- otherwise, return the term in position pos of the right hand side. -->
181 * <!-- For this operator: 0 <= apos < RelationLength(rel,lhs) as a Carray. -->
182 * <!-- Once Everybody gets their damn hands off RelationTerm, switch its -->
183 * <!-- semantics and eliminate one of this pair. -->
184 * Implementation function for NewRelationTerm(). Do not call this
185 * function directly - use NewRelationTerm() instead.
186 */
187
188 #ifdef NDEBUG
189 #define RelationSideTerm(rs,p) A_TERM(&((rs)[(p)]))
190 #else
191 #define RelationSideTerm(rs,p) RelationSideTermF((rs),(p))
192 #endif
193 /**<
194 * Return the term in position p of the side.
195 * For this operator: 0 <= p < length of the side.
196 * @param rs CONST union RelationTermUnion*, the relation to query.
197 * @param p unsigned long, the position to retrieve.
198 * @return The specified term as a CONST struct relation_term*.
199 * @see RelationSideTermF()
200 */
201 extern CONST struct relation_term
202 *RelationSideTermF(CONST union RelationTermUnion *relside, unsigned long apos);
203 /**<
204 * <!-- CONST struct relation_term *RelationSideTerm(relside,apos) -->
205 * <!-- CONST union RelationTermUnion *relside -->
206 * <!-- unsigned long apos; -->
207 * <!-- Return the term in position apos of the side. -->
208 * <!-- For this operator: 0 <= apos < length of the side. -->
209 * Implementation function for RelationSideTerm(). Do not call this
210 * function directly - use RelationSideTerm() instead.
211 */
212
213 #ifdef NDEBUG
214 #define RelationTermType(rtp) ((rtp)->t)
215 #else
216 #define RelationTermType(rtp) RelationTermTypeF(rtp)
217 #endif
218 /**<
219 * Return the type of the relation term.
220 * WARNING: if ALLOCATED_TESTS is active, term must be an allocated term;
221 * automatic variables will cause an assert() to fail.
222 * @param rtp CONST struct relation_term*, the term to query.
223 * @return The type as an enum Expr_enum.
224 * @see RelationTermTypeF()
225 */
226 extern enum Expr_enum RelationTermTypeF(CONST struct relation_term *term);
227 /**<
228 * <!-- enum Expr_enum RelationTermType(term) -->
229 * <!-- const struct relation_term *term; -->
230 * <!-- return the type of the relation term. -->
231 * <!-- WARNING: if ALLOCATED_TESTS is active, term must be an allocated -->
232 * <!-- term; automatic variables will cause an assert() to fail. -->
233 * Implementation function for RelationTermType(). Do not call this
234 * function directly - use RelationTermType() instead.
235 */
236
237 extern unsigned long TermVarNumber(CONST struct relation_term *term);
238 /**<
239 * <!-- unsigned long TermVarNumber(term) -->
240 * <!-- const struct relation_term *term; -->
241 * Return the index into the relations variable list.
242 */
243
244 extern long TermInteger(CONST struct relation_term *term);
245 /**<
246 * <!-- long TermInteger(term) -->
247 * <!-- const struct relation_term *term; -->
248 * Return the integer value from a e_int type relation term.
249 */
250
251 extern double TermReal(CONST struct relation_term *term);
252 /**<
253 * <!-- double TermReal(term) -->
254 * <!-- const struct relation_term *term; -->
255 * Return the double value from a e_real type relation term.
256 */
257
258 extern double TermVariable(CONST struct relation *rel,
259 CONST struct relation_term *term);
260 /**<
261 * <!-- double TermVariable(rel,term) -->
262 * <!-- const struct relation *rel; -->
263 * <!-- const struct relation_term *term; -->
264 * Return the double value from a e_var type relation term.
265 */
266
267 extern CONST dim_type *TermDimensions(CONST struct relation_term *term);
268 /**<
269 * <!-- const dim_type *TermDimensions(term) -->
270 * <!-- const struct relation_term *term; -->
271 * Return the dimensions of a e_real, e_int, or e_zero relation term type.
272 * (e_int is always Dimensionless(); e_zero is always WildDimension().)
273 */
274
275 extern CONST struct Func *TermFunc(CONST struct relation_term *term);
276 /**<
277 * <!-- struct Func *TermFunc(term) -->
278 * <!-- const struct relation_term; -->
279 * Return the function pointer of a function operator.
280 */
281
282 extern unsigned long RelationDepth(CONST struct relation *rel);
283 /**<
284 * <!-- unsigned long RelationDepth(rel) -->
285 * <!-- struct relation *rel; -->
286 * Return the depth of stack required to evaluate this relation.
287 */
288
289 /*------------------------------------------------------------------------
290 * TokenRelation Infix operations.
291 *------------------------------------------------------------------------
292 */
293
294 /*------------------------------------------------------------------------
295 * The four defines following return term pointers.
296 * struct relation_term *r, *t;
297 * r = TermUniLeft(t); for example.
298 * These should be implemented as functions which assert type
299 * and revert to macros with NDEBUG.
300 *------------------------------------------------------------------------
301 */
302 #define TermUniLeft(t) ( ((struct RelationUnary *)t) -> left)
303 #define TermFuncLeft(t) ( ((struct RelationFunc *)t) -> left)
304 #define TermBinLeft(t) ( ((struct RelationBinary *)t) -> left)
305 #define TermBinRight(t) ( ((struct RelationBinary *)t) -> right)
306
307 extern struct relation_term *RelationINF_Lhs(CONST struct relation *rel);
308 /**<
309 * Returns the lhs of an infix relation. This may be NULL,
310 * if the relation has not been set for infix scanning.
311 */
312
313 extern struct relation_term *RelationINF_Rhs(CONST struct relation *rel);
314 /**<
315 * Return the rhs of an infix relation. This may be NULL
316 * if the relation has not been set up for infix scanning, or if
317 * the relation is an objective relation.
318 */
319
320 extern int ArgsForRealToken(enum Expr_enum ex);
321 /**<
322 * Return the number of args required for a token from a real equation.
323 */
324
325 /*------------------------------------------------------------------------
326 * Opcode Relation processing.
327 * This stuff is NOT complete.
328 *------------------------------------------------------------------------
329 */
330 #define OpCode_Lhs(r) ((int *)(ROPCODE(r).lhs))
331 #define OpCode_Rhs(r) ((int *)(ROPCODE(r).rhs))
332 #define OpCodeNumberArgs(r) (ROPCODE(r).nargs)
333 #define OpCodeConstants(r) ((double *)(ROPCODE(r).constants))
334
335 /*------------------------------------------------------------------------
336 * BlackBox Relation processing.
337 *------------------------------------------------------------------------
338 */
339 extern struct ExtCallNode *BlackBoxExtCall(CONST struct relation *rel);
340 extern int *BlackBoxArgs(CONST struct relation *rel);
341
342 #define BlackBoxNumberArgs(r) (RBBOX(r).nargs)
343
344 /*------------------------------------------------------------------------
345 * GlassBoxRelation queries.
346 * These will be called a lot so that they will all be made
347 * macros. Double check that the same is true for the
348 * ExternalFunc routines.
349 *------------------------------------------------------------------------
350 */
351 extern struct ExternalFunc *GlassBoxExtFunc(CONST struct relation *rel);
352 extern int GlassBoxRelIndex(CONST struct relation *rel);
353 extern int *GlassBoxArgs(CONST struct relation *rel);
354
355 #define GlassBoxNumberArgs(r) (RGBOX(r).nargs)
356
357 extern CONST struct gl_list_t *RelationVarList(CONST struct relation *r);
358 /**<
359 * <!-- const struct gl_list_t *RelationVarList(r); -->
360 * <!-- const struct relation *r; -->
361 * Returns the unique incident variable list which is owned by the
362 * relation. *DO NOT MODIFY*. It is for the convenience of those
363 * desirous of a READ_ONLY look. It is a list of instance pointers, which may
364 * be NULL.
365 * All relation types will properly respond to this qurey.
366 */
367
368 extern dim_type *RelationDim(CONST struct relation *rel);
369 /**<
370 * <!-- dim_type *RelationDim(rel) -->
371 * <!-- const struct relation *rel; -->
372 * Return the derived dimensionality of the relation.
373 * Defaults to Wild.
374 */
375
376 extern int SetRelationDim(struct relation *rel, dim_type *d);
377 /**<
378 * <!-- int SetRelationDim(rel,d) -->
379 * <!-- const struct relation *rel; -->
380 * Set the dimensionality of the relation. return 0 unless there is a
381 * problem (rel was null, for instance.)
382 */
383
384 extern double RelationResidual(CONST struct relation *rel);
385 /**<
386 * <!-- double RelationResidual(rel) -->
387 * <!-- const struct relation *rel; -->
388 * Return the residual of the relation.
389 */
390
391 extern void SetRelationResidual(struct relation *rel, double value);
392 /**<
393 * <!-- void SetRelationResidual(rel,value) -->
394 * <!-- struct relation *rel; -->
395 * <!-- double value; -->
396 * Set the value of the relation residual.
397 */
398
399 extern double RelationMultiplier(CONST struct relation *rel);
400 /**<
401 * <!-- double RelationMultiplier(rel) -->
402 * <!-- const struct relation *rel; -->
403 * Return the langrage multiplier of the relation. This will have some
404 * hybrid dimensions that still needs to be decided, as it is a function
405 * of the objective function(s).
406 */
407
408 extern void SetRelationMultiplier(struct relation *rel, double value);
409 /**<
410 * <!-- void SetRelationMultiplier(rel,value) -->
411 * <!-- struct relation *rel; -->
412 * <!-- double value; -->
413 * Set the value of the relation langrage multiplier. This will have some
414 * hybrid dimensions that still needs to be decided.
415 */
416
417 extern int RelationIsCond(CONST struct relation *rel);
418 /**<
419 * <!-- int RelationIsCond(rel) -->
420 * <!-- const struct relation *rel; -->
421 * Return the value of the iscond flag of the relation.
422 * If relation is NULL, returns 0.
423 */
424
425 extern void SetRelationIsCond(struct relation *rel);
426 /**<
427 * <!-- void SetRelationIsCond(rel) -->
428 * <!-- struct relation *rel; -->
429 * Sets the value of the iscond field of the relation to 1
430 * If relation is NULL, writes error message.
431 */
432
433 extern double RelationNominal(CONST struct relation *rel);
434 /**<
435 * <!-- double RelationNominal(rel) -->
436 * <!-- const struct relation *rel; -->
437 * Return the nominal of the relation.
438 */
439
440 extern void SetRelationNominal(struct relation *rel, double d);
441 /**<
442 * <!-- void SetRelationNominal(rel,d) -->
443 * <!-- struct relation *rel; -->
444 * <!-- double d; -->
445 * Sets the value of the nominal field of the relation to the absolute
446 * value of d, unless d is 0.0.
447 */
448
449 extern double CalcRelationNominal(struct Instance *i);
450 /**<
451 * <!-- d = CalcRelationNominal(i); -->
452 * <!-- struct Instance *i; -->
453 * <!-- double d; -->
454 * Calculate the nominal of a relation.
455 * Returns 0.0 if something went detectably wrong in the calculation,
456 * otherwise calculates the absolute value of the maximum affine term
457 * and returns it, given an instance which is a token relation. Other
458 * relation types return the value 1.0.
459 * Does not set the constant stored with the relation.<br><br>
460 *
461 * When opcode relations are fully supported,
462 * this function should be made to work for them, too.<br><br>
463 *
464 * Art contends that the proper nominal for blackbox
465 * relations is the nominal of the output variable, though this is
466 * not implemented at present.<br><br>
467 *
468 * Art further contends that the proper nominal for glassbox relations
469 * is the 2 norm of its gradient vector after fixed variables are
470 * removed and free elements have been scaled by the variable nominals.
471 * It should be noted that the glassbox scaling proposed by this method
472 * is precisely what the Slv solvers used up to August 1995.
473 * IMHO (baa) the glassbox generated should include code which knows
474 * how to calculate relation nominals.
475 */
476
477 extern void PrintRelationNominals(struct Instance *i);
478 /**<
479 * Perform a visit instance tree starting at i and calc/print consts.
480 * This function doesn't belong here.
481 */
482
483 extern char *tmpalloc(int nbytes);
484 /**<
485 * Temporarily allocates a given number of bytes. The memory need
486 * not be freed, but the next call to this function will reuse the
487 * previous allocation. Memory returned will NOT be zeroed.
488 * Calling with nbytes==0 will free any memory allocated.
489 */
490
491 #define tmpalloc_array(nelts,type) ((type *)tmpalloc((nelts)*sizeof(type)))
492 /**<
493 * Creates an array of "nelts" objects, each with type "type".
494 */
495
496 /*
497 * The following mess of functions
498 * migrated out of the solver directory into this file. Who
499 * ever heard of a math modeling language that doesn't supply
500 * evaluation functions for its equations?
501 * These are for Token equations, though if they can be done
502 * for all equation types that's a plus.
503 * Supercedes the bleeding mess in calc.c, rel.c, relman.c which was
504 * very ugly.
505 * BAA 5/96
506 *
507 */
508
509 extern int RelationCalcResidualBinary(CONST struct relation *rel, double *res);
510 /**<
511 * <!-- err = RelationCalcResidualBinary(rel,res); -->
512 * Returns 0 if it calculates a valid residual, 1 if
513 * for any reason it cannot. Reasons include:
514 * - relation not token relation.
515 * - token relation not compiled to binary.
516 * - NaN/infinity result.
517 * - out of memory.
518 * If return is 1, then res will not have been changed.
519 * This function may raise SIGFPE it calls external code.
520 */
521
522 extern enum safe_err
523 RelationCalcResidualPostfixSafe(struct Instance *i, double *res);
524 /**<
525 * <!-- status = RelationCalcResidualPostfixSafe(i,res); -->
526 * <!-- struct RelationInstance *i; -->
527 * <!-- double *res; -->
528 * <!-- enum safe_err status; -->
529 * Sets *res to the value (leftside - rightside) of the relation.
530 * status != 0 (safe_ok = 0) implies a problem.
531 * This function is slower than RelationCalcResidual() because it does
532 * a lot of range checking AND a floating point trap.
533 */
534
535 extern int RelationCalcResidualPostfix(struct Instance *i, double *res);
536 /**<
537 * <!-- status = RelationCalcResidualPostfix(i,res); -->
538 * <!-- struct RelationInstance *i; -->
539 * <!-- double *res; -->
540 * <!-- int status; -->
541 * Sets *res to the value (leftside - rightside) of the relation.
542 * Uses postfix evaluation.
543 * status != 0 implies a problem.
544 * Notes: This function is a possible source of floating point
545 * exceptions and should not be used during compilation.
546 */
547
548 /*
549 * The following bit flags are used to build up the return
550 * status from RelationCalcExceptionsInfix.
551 * No provision is made for checking gradient elements --
552 * gradients are in principle an all or nothing affair.
553 */
554 #define RCE_BADINPUT -1 /**< called with non-token relation */
555 #define RCE_OK 0 /**< no error */
556 #define RCE_ERR_LHS 0x1 /**< left side evaluation error */
557 #define RCE_ERR_RHS 0x2 /**< right side evaluation error */
558 #define RCE_ERR_LHSGRAD 0x4 /**< left side gradient error */
559 #define RCE_ERR_RHSGRAD 0x8 /**< right side gradient error */
560 #define RCE_ERR_LHSINF 0x10 /**< left side returns Infinity */
561 #define RCE_ERR_RHSINF 0x20 /**< right side returns Infinity */
562 #define RCE_ERR_LHSNAN 0x40 /**< left side returns NaN */
563 #define RCE_ERR_RHSNAN 0x80 /**< right side returns NaN */
564
565 extern int RelationCalcExceptionsInfix(struct Instance *i);
566 /**<
567 * <!-- status = RelationCalcExceptionsInfix(i); -->
568 * <!-- struct RelationInstance *i; -->
569 * <!-- int status; -->
570 * Uses infix evaluation to check gradient and residual
571 * floating point exceptions.
572 * status != 0 implies a problem.
573 * Notes: This function is a possible source of floating point
574 * exceptions and should not be used during compilation.
575 * This function should not be called except inside the scope of a
576 * Asc_SignalHandlerPush(SIGFPE,SIG_IGN);
577 * Asc_SignalHandlerPop(SIGFPE,SIG_IGN);
578 * pair.
579 * Functions that report exceptions here may still be evaluated
580 * With the Safe relation evaluation routines in all but the most
581 * bizarre circumstances. The Safe results are necessarily approximate.
582 *
583 * @bug At present, gradient checks are not implemented as the code
584 * required is messy. We need to rearrange CalcResidGrad().
585 */
586
587 extern int RelationCalcResidualInfix(struct Instance *i, double *res);
588 /**<
589 * <!-- status = RelationCalcResidualInfix(i,res); -->
590 * <!-- struct RelationInstance *i; -->
591 * <!-- double *res; -->
592 * <!-- int status; -->
593 * Sets *res to the value (leftside - rightside) of the relation.
594 * Uses infix evaluation.
595 * Non-zero return value implies a problem.
596 * Notes: This function is a possible source of floating point
597 * exceptions and should not be used during compilation.
598 */
599
600 #define RelationCalcResidual(i,r) RelationCalcResidualPostfix(i,r)
601 #define RelationCalcResidualSafe(i,r) RelationCalcResidualPostfixSafe(i,r)
602
603 extern int RelationCalcGradient(struct Instance *i, double *grad);
604 /**<
605 * <!-- status = RelationCalcGradient(i,grad); -->
606 * <!-- struct RelationInstance *i; -->
607 * <!-- double grad[]; -->
608 * <!-- int status; -->
609 * <!-- status != 0 implies a problem. -->
610 * This calculates the gradient of the relation df/dx (f = lhs-rhs)
611 * where x is ALL entries in the relation's var list.
612 * The var list is a gl_list_t indexed from 1 to length.
613 * You must provide grad, the space to put the gradient, an array of
614 * double of length matching the gl_list_t.
615 * We will stuff df/dx[i] into grad[i-1], where i is the list position
616 * in the relation's var list.<br><br>
617 *
618 * Non-zero return value implies a problem.<br><br>
619 *
620 * Notes: This function is a possible source of floating point
621 * exceptions and should not be used during compilation.
622 */
623
624 extern enum safe_err RelationCalcGradientSafe(struct Instance *i, double *grad);
625 /**<
626 * <!-- status = RelationCalcGradientSafe(i,grad); -->
627 * <!-- struct RelationInstance *i; -->
628 * <!-- double grad[]; -->
629 * <!-- enum safe_err status; -->
630 * <!-- status != 0 (safe_ok = 0) implies a problem. -->
631 * This calculates the gradient of the relation df/dx (f = lhs-rhs)
632 * where x is ALL entries in the relation's var list.
633 * This function is to RelationCalcGradient as
634 * RelationCalcResidualSafe is to RelationCalcResidual.
635 * Non-zero return value implies a problem.
636 */
637
638 extern int RelationCalcResidGrad(struct Instance *i, double *res, double *grad);
639 /**<
640 * <!-- status = RelationCalcResidGrad(i,res,grad); -->
641 * <!-- struct RelationInstance *i; -->
642 * <!-- double *res; -->
643 * <!-- double grad[]; -->
644 * <!-- int status; -->
645 * <!-- status != 0 implies a problem. -->
646 * This function combines the Residual and Gradient calls, since these
647 * may be done together at basically the cost of just one.
648 * Non-zero return value implies a problem.<br><br>
649 * Notes: This function is a possible source of floating point
650 * exceptions and should not be used during compilation.
651 */
652
653 extern enum safe_err
654 RelationCalcResidGradSafe(struct Instance *i, double *res, double *grad);
655 /**<
656 * <!-- status = RelationCalcResidGradSafe(i,res,grad); -->
657 * <!-- struct RelationInstance *i; -->
658 * <!-- double *res; -->
659 * <!-- double grad[]; -->
660 * <!-- enum safe_err status; -->
661 * <!-- status != 0 (safe_ok = 0) implies a problem. -->
662 * This is the combined Safe version.
663 * Non-zero return value implies a problem.
664 */
665
666 extern double *RelationFindRoots(struct Instance *i,
667 double lower_bound,
668 double upper_bound,
669 double nominal,
670 double tolerance,
671 unsigned long *varnum,
672 int *able,
673 int *nsolns);
674 /**<
675 * <!-- soln_list = RelationFindRoots(i,lower_bound,upper_bound,nominal, -->
676 * <!-- tolerance,varnum,able,nsolns); -->
677 * <!-- struct Instance *i; -->
678 * <!-- double lower_bound; -->
679 * <!-- double upper_bound; -->
680 * <!-- double nominal; -->
681 * <!-- double tolerance; -->
682 * <!-- long *varnum; -->
683 * <!-- int *able; -->
684 * <!-- int *nsolns; -->
685 * <!-- double *soln_list; -->
686 *
687 * RelationFindRoot WILL find a root if there is one. It is in charge of
688 * trying every trick in the book. The user must pass in a pointer to a
689 * struct relation. We require that the relation be of the type e_token with
690 * relation->relop = e_equals and we will whine if it is not. The calling
691 * function should check able and/or nsolns before accessing the information
692 * in the soln_list.
693 * - nsolns < 0 : severe problems, soln_list will be NULL
694 * - nsolns = 0 : No solution found
695 * - nsolns > 0 : The soln_status equals the number of roots found
696 *
697 * The calling function should NOT free the soln_list.<br><br>
698 *
699 * This function is NOT thread safe because it uses an internal memory
700 * recycle.
701 * Before shutting down the system, or as desired, call this as:
702 * (void) RelationFindRoots(NULL,0,0,0,0,NULL,NULL,NULL);
703 * in order to free this memory.
704 */
705
706 extern int RelationCalcDerivative(struct Instance *i, unsigned long index, double *grad);
707 /**<
708 * <!-- status = RelationCalcDerivative(i,index,grad); -->
709 * <!-- struct RelationInstance *i; -->
710 * <!-- unsigned long index; -->
711 * <!-- double *grad; -->
712 * <!-- int status; -->
713 * <!-- status != 0 implies a problem. -->
714 * This calculates the derivative of the relation df/dx (f = lhs-rhs)
715 * where x is the INDEX-th entry in the relation's var list.
716 * The var list is a gl_list_t indexed from 1 to length.
717 * Non-zero return value implies a problem.<br><br>
718 *
719 * Notes: This function is a possible source of floating point
720 * exceptions and should not be used during compilation.
721 */
722
723 extern enum safe_err
724 RelationCalcDerivativeSafe(struct Instance *i, unsigned long index, double *grad);
725 /**<
726 * <!-- status = RelationCalcDerivativeSafe(i,index,grad); -->
727 * <!-- struct RelationInstance *i; -->
728 * <!-- unsigned long index; -->
729 * <!-- double *grad; -->
730 * <!-- enum_safe_err status; -->
731 * <!-- status != 0 (safe_ok = 0) implies a problem. -->
732 * Calculates the derivative safely.
733 * Non-zero return value implies a problem.
734 */
735
736
737 extern struct gl_list_t
738 *CollectTokenRelationsWithUniqueBINlessShares(struct Instance *i, unsigned long maxlen);
739 /**<
740 * <!-- rlist = CollectTokenRelationsWithUniqueBINlessShares(i,maxlen); -->
741 * Collect the token relation 'shares' in i which have not been compiled
742 * (or at least attempted so) to binary form yet.
743 * If more than maxlen are found, returns NULL instead. Presumably there
744 * is some upper limit beyond which you don't want to know the answer to
745 * this question. If none are found, returns a 0 length list.
746 * Actually, it is not a share that is collected, but instead any
747 * one of the relation instances which use the share is collected.
748 * The list returned should be destroyed by the user (not its content,though).
749 */
750
751 #endif /* __RELATION_UTIL_H_SEEN__ */
752

Properties

Name Value
svn:executable *

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