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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 693 by johnpye, Fri Apr 21 07:22:20 2006 UTC revision 694 by johnpye, Thu Jun 22 07:54:53 2006 UTC
# Line 65  extern int RelationCheckDimensions(struc Line 65  extern int RelationCheckDimensions(struc
65   *  the dimensions of the relation (or at least what the function   *  the dimensions of the relation (or at least what the function
66   *  thinks the dimensions ought to be) can be also obtained.   *  thinks the dimensions ought to be) can be also obtained.
67   *   *
68   *  THIS ONLY WORKS ON e_token relations and maybe in future e_opcode   *  @NOTE THIS ONLY WORKS ON e_token relations and maybe in future e_opcode
69   *  relations. rel is assumed to be valid when called. !!!   *  relations. rel is assumed to be valid when called. !!!
70   *   *
71   *  This brings in the asc_check_dimensions function from ascend_utils.   *  @NOTE This brings in the asc_check_dimensions function from ascend_utils.
72   *  3/96 Ben Allan   *  3/96 Ben Allan
73   */   */
74    
# Line 90  ASC_DLLSPEC(enum Expr_enum ) RelationRel Line 90  ASC_DLLSPEC(enum Expr_enum ) RelationRel
90    
91  extern unsigned long NumberVariables(CONST struct relation *rel);  extern unsigned long NumberVariables(CONST struct relation *rel);
92  /**<  /**<
93   *  This will indicate the number of distinct real atoms to which this relation      This will indicate the number of distinct real atoms to which this relation
94   *  points.  This number contains both fixed and non-fixed atoms.      points.  This number contains both fixed and non-fixed atoms.
95   *  This routine is smart enough to deal with all the different relation types.      This routine is smart enough to deal with all the different relation types.
96   */  */
97    
98  ASC_DLLSPEC(struct Instance *) RelationVariable(CONST struct relation *rel,  ASC_DLLSPEC(struct Instance *) RelationVariable(CONST struct relation *rel,
99                                           unsigned long varnum);                                           unsigned long varnum);
100  /**<  /**<
101   *  This will return the varnum'th variable.      This will return the varnum'th variable.
102   *  This routine is smart enough to deal with all the different relation      This routine is smart enough to deal with all the different relation
103   *  types.      types.
104   */  */
105    
106  /*----------------------------------------------------------------------------  /*----------------------------------------------------------------------------
107   *  TokenRelation and OpCodeRelation specific code.      TOKENRELATION AND OPCODERELATION STUFF
108   *  
109   *  It is the responsibility of the user of these routines to be aware      It is the responsibility of the user of these routines to be aware
110   *  of the type of relation being used. Very little sanity checking is      of the type of relation being used. Very little sanity checking is
111   *  done.      done.
112   *----------------------------------------------------------------------------  */
  */  
113    
114  ASC_DLLSPEC(unsigned long ) RelationLength(CONST struct relation *rel, int lhs);  ASC_DLLSPEC(unsigned long ) RelationLength(CONST struct relation *rel, int lhs);
115  /**<  /**<
116   *  If lhs is true, return the number of terms on the left hand side of the      Returns the number of terms on one side of the equation. If lhs!=0, does this
117   *  relation.  Otherwise, return the number of terms on the right hand side      for the LHS. If lhs==0, does this for the RHS.
118   *  of the relation.  */
  */  
119    
120  ASC_DLLSPEC(CONST struct relation_term *) RelationTerm(CONST struct relation *rel,  ASC_DLLSPEC(CONST struct relation_term *) RelationTerm(CONST struct relation *rel,
121                                                  unsigned long pos,                                                  unsigned long pos,
122                                                  int lhs);                                                  int lhs);
123  /**<  /**<
124   *  If lhs is true, return the term in position pos of the left hand side.      Returns the term in position POS (base 1) on one side of the equation.
125   *  Otherwise, return the term in position pos of the right hand side.      If lhs!=0, does this for the LHS. If lhs==0, does this for the RHS.
126   *  A bizarre thing about this operator: 1 <= pos <= RelationLength(rel,lhs).  
127   *  This is a holdover from gl_list days.      @NOTE A bizarre thing about this operator: 1 <= pos <= RelationLength(rel,lhs).
128   */      This is a holdover from gl_list days.
129    */
130    
131  #ifdef NDEBUG  #ifdef NDEBUG
132  #define NewRelationTerm(r,p,l) \  #define NewRelationTerm(r,p,l) \
# Line 136  A_TERM( (l)!=0 ? (&(RTOKEN(r).lhs[(p)])) Line 135  A_TERM( (l)!=0 ? (&(RTOKEN(r).lhs[(p)]))
135  #define NewRelationTerm(r,p,l) NewRelationTermF((r),(p),(l))  #define NewRelationTerm(r,p,l) NewRelationTermF((r),(p),(l))
136  #endif  #endif
137  /**<  /**<
138   *  If l is true, return the term in position p of the left hand side.      Returns the term in position POS (base 0) on one side of the equation.
139   *  Otherwise, return the term in position p of the right hand side.      If lhs!=0, does this for the LHS. If lhs==0, does this for the RHS.
140   *  For this operator: 0 <= p < RelationLength(rel,lhs) as a C array.  
141   *  Once Everybody gets their damn hands off RelationTerm, switch its      For this operator: 0 <= p < RelationLength(rel,lhs) as a C array.
142   *  semantics and eliminate one of this pair.  
143   *  @param r CONST struct relation*, the relation to query.      @TODO Once Everybody gets their damn hands off RelationTerm, switch its
144   *  @param p unsigned long, the position to retrieve.      semantics and eliminate one of this pair.
145   *  @param l int, flag for whether to return from the lhs or rhs.  
146   *  @return The specified term as a CONST struct relation_term*.      @param r CONST struct relation*, the relation to query.
147   *  @see NewRelationTermF()      @param p unsigned long, the position to retrieve.
148   */      @param l int, flag for whether to return from the lhs or rhs.
149        @return The specified term as a CONST struct relation_term*.
150        @see NewRelationTermF()
151    */
152    
153  extern CONST struct relation_term  extern CONST struct relation_term
154  *NewRelationTermF(CONST struct relation *rel, unsigned long apos, int lhs);  *NewRelationTermF(CONST struct relation *rel, unsigned long apos, int lhs);
155  /**<  /**<
156   *  Implementation function for NewRelationTerm().  Do not call this      Implementation function for NewRelationTerm().  Do not call this
157   *  function directly - use NewRelationTerm() instead.      function directly.
158   */  */
159    
160  #ifdef NDEBUG  #ifdef NDEBUG
161  #define RelationSideTerm(rs,p) A_TERM(&((rs)[(p)]))  #define RelationSideTerm(rs,p) A_TERM(&((rs)[(p)]))
# Line 160  extern CONST struct relation_term Line 163  extern CONST struct relation_term
163  #define RelationSideTerm(rs,p) RelationSideTermF((rs),(p))  #define RelationSideTerm(rs,p) RelationSideTermF((rs),(p))
164  #endif  #endif
165  /**<  /**<
166   *  Return the term in position p of the side.      Return the term in position p of the side.
167   *  For this operator: 0 <= p < length of the side.      For this operator: 0 <= p < length of the side.
168   *  @param rs CONST union RelationTermUnion*, the relation to query.  
169   *  @param p unsigned long, the position to retrieve.      @param rs CONST union RelationTermUnion*, the relation to query.
170   *  @return The specified term as a CONST struct relation_term*.      @param p unsigned long, the position to retrieve.
171   *  @see RelationSideTermF()      @return The specified term as a CONST struct relation_term*.
172   */      @see RelationSideTermF()
173    */
174  extern CONST struct relation_term  extern CONST struct relation_term
175  *RelationSideTermF(CONST union RelationTermUnion *relside, unsigned long apos);  *RelationSideTermF(CONST union RelationTermUnion *relside, unsigned long apos);
176  /**<  /**<
177   *  Implementation function for RelationSideTerm().  Do not call this      Implementation function for RelationSideTerm().  Do not call this
178   *  function directly - use RelationSideTerm() instead.      function directly - use RelationSideTerm() instead.
179   */  */
180    
181  #ifdef NDEBUG  #ifdef NDEBUG
182  #define RelationTermType(rtp) ((rtp)->t)  #define RelationTermType(rtp) ((rtp)->t)
# Line 180  extern CONST struct relation_term Line 184  extern CONST struct relation_term
184  #define RelationTermType(rtp) RelationTermTypeF(rtp)  #define RelationTermType(rtp) RelationTermTypeF(rtp)
185  #endif  #endif
186  /**<  /**<
187   *  Return the type of the relation term.      Return the type of the relation term.
188   *  WARNING: if ALLOCATED_TESTS is active, term must be an allocated term;  
189   *  automatic variables will cause an assert() to fail.      @NOTE WARNING: if ALLOCATED_TESTS is active, term must be an allocated term;
190   *  @param rtp CONST struct relation_term*, the term to query.      automatic variables will cause an assert() to fail.
191   *  @return The type as an enum Expr_enum.      @param rtp CONST struct relation_term*, the term to query.
192   *  @see RelationTermTypeF()      @return The type as an enum Expr_enum.
193   */      @see RelationTermTypeF()
194    */
195  ASC_DLLSPEC(enum Expr_enum ) RelationTermTypeF(CONST struct relation_term *term);  ASC_DLLSPEC(enum Expr_enum ) RelationTermTypeF(CONST struct relation_term *term);
196  /**<  /**<
197   *  Implementation function for RelationTermType().  Do not call this      Implementation function for RelationTermType().  Do not call this
198   *  function directly - use RelationTermType() instead.      function directly - use RelationTermType() instead.
199   */  */
200    
201  ASC_DLLSPEC(unsigned long ) TermVarNumber(CONST struct relation_term *term);  ASC_DLLSPEC(unsigned long ) TermVarNumber(CONST struct relation_term *term);
202  /**<  /**<
203   *  Return the index into the relations variable list.      @return the index into the relations variable list.
204   */  */
205    
206  ASC_DLLSPEC(long ) TermInteger(CONST struct relation_term *term);  ASC_DLLSPEC(long ) TermInteger(CONST struct relation_term *term);
207  /**<  /**<
208   *  Return the integer value from a e_int type relation term.      @return the integer value from a e_int type relation term.
209   */  */
210    
211  ASC_DLLSPEC(double ) TermReal(CONST struct relation_term *term);  ASC_DLLSPEC(double ) TermReal(CONST struct relation_term *term);
212  /**<  /**<
213   *  Return the double value from a e_real type relation term.      @return the double value from a e_real type relation term.
214   */  */
215    
216  extern double TermVariable(CONST struct relation *rel,  extern double TermVariable(CONST struct relation *rel,
217                             CONST struct relation_term *term);                             CONST struct relation_term *term);
218  /**<  /**<
219   *  Return the double value from a e_var type relation term.      @return the double value from a e_var type relation term.
220   */  */
221    
222  ASC_DLLSPEC(CONST dim_type *) TermDimensions(CONST struct relation_term *term);  ASC_DLLSPEC(CONST dim_type *) TermDimensions(CONST struct relation_term *term);
223  /**<  /**<
224   *  Return the dimensions of a e_real, e_int, or e_zero relation term type.      Return the dimensions of a e_real, e_int, or e_zero relation term type.
225   *  (e_int is always Dimensionless(); e_zero is always WildDimension().)      (e_int is always Dimensionless(); e_zero is always WildDimension().)
226   */  */
227    
228  ASC_DLLSPEC(CONST struct Func *) TermFunc(CONST struct relation_term *term);  ASC_DLLSPEC(CONST struct Func *) TermFunc(CONST struct relation_term *term);
229  /**<  /**<
# Line 227  ASC_DLLSPEC(CONST struct Func *) TermFun Line 232  ASC_DLLSPEC(CONST struct Func *) TermFun
232    
233  ASC_DLLSPEC(unsigned long ) RelationDepth(CONST struct relation *rel);  ASC_DLLSPEC(unsigned long ) RelationDepth(CONST struct relation *rel);
234  /**<  /**<
235   *  Return the depth of stack required to evaluate this relation.      Return the depth of stack required to evaluate this relation.
236   */  */
237    
238  /*------------------------------------------------------------------------  /*------------------------------------------------------------------------
239   *  TokenRelation Infix operations.      TOKENRELATION INFIX OPERATIONS
240   *------------------------------------------------------------------------  */
  */  
241    
242  /*------------------------------------------------------------------------  /*
243   *    The four defines following return term pointers.      The four defines following return term pointers.
244   *    struct relation_term *r, *t;      struct relation_term *r, *t;
245   *    r = TermUniLeft(t); for example.      r = TermUniLeft(t); for example.
246   *       These should be implemented as functions which assert type  
247   *       and revert to macros with NDEBUG.      @TODO These should be implemented as functions which assert type
248   *------------------------------------------------------------------------      and revert to macros with NDEBUG.
249   */  */
250  #define TermUniLeft(t)  ( ((struct RelationUnary *)t) -> left)  #define TermUniLeft(t)  ( ((struct RelationUnary *)t) -> left)
251  #define TermFuncLeft(t) ( ((struct RelationFunc *)t) -> left)  #define TermFuncLeft(t) ( ((struct RelationFunc *)t) -> left)
252  #define TermBinLeft(t)  ( ((struct RelationBinary *)t) -> left)  #define TermBinLeft(t)  ( ((struct RelationBinary *)t) -> left)
# Line 250  ASC_DLLSPEC(unsigned long ) RelationDept Line 254  ASC_DLLSPEC(unsigned long ) RelationDept
254    
255  extern struct relation_term *RelationINF_Lhs(CONST struct relation *rel);  extern struct relation_term *RelationINF_Lhs(CONST struct relation *rel);
256  /**<  /**<
257   *  Returns the lhs of an infix relation. This may be NULL,      Returns the lhs of an infix relation. This may be NULL,
258   *  if the relation has not been set for infix scanning.      if the relation has not been set for infix scanning.
259   */  */
260    
261  extern struct relation_term *RelationINF_Rhs(CONST struct relation *rel);  extern struct relation_term *RelationINF_Rhs(CONST struct relation *rel);
262  /**<  /**<
263   *  Return the rhs of an infix relation. This may be NULL      Return the rhs of an infix relation. This may be NULL
264   *  if the relation has not been set up for infix scanning, or if      if the relation has not been set up for infix scanning, or if
265   *  the relation is an objective relation.      the relation is an objective relation.
266   */  */
267    
268  extern int ArgsForRealToken(enum Expr_enum ex);  extern int ArgsForRealToken(enum Expr_enum ex);
269  /**<  /**<
270   *  Return the number of args required for a token from a real equation.      Return the number of args required for a token from a real equation.
271   */  */
272    
273  /*------------------------------------------------------------------------  /*------------------------------------------------------------------------
274   *    Opcode Relation processing.      OPCODE RELATION PROCESSING
275   *    This stuff is NOT complete.  */
276   *------------------------------------------------------------------------  
277   */  /**
278        @TODO What's that mean?
279        @TODO this stuff is not complete
280    */
281    
282  #define OpCode_Lhs(r)       ((int *)(ROPCODE(r).lhs))  #define OpCode_Lhs(r)       ((int *)(ROPCODE(r).lhs))
283  #define OpCode_Rhs(r)       ((int *)(ROPCODE(r).rhs))  #define OpCode_Rhs(r)       ((int *)(ROPCODE(r).rhs))
284  #define OpCodeNumberArgs(r) (ROPCODE(r).nargs)  #define OpCodeNumberArgs(r) (ROPCODE(r).nargs)
285  #define OpCodeConstants(r)  ((double *)(ROPCODE(r).constants))  #define OpCodeConstants(r)  ((double *)(ROPCODE(r).constants))
286    
287  /*------------------------------------------------------------------------  /*------------------------------------------------------------------------
288   *    BlackBox Relation processing.      BLACK BOX RELATION PROCESSING
289   *------------------------------------------------------------------------  */
  */  
290  extern struct ExtCallNode *BlackBoxExtCall(CONST struct relation *rel);  extern struct ExtCallNode *BlackBoxExtCall(CONST struct relation *rel);
291  extern int *BlackBoxArgs(CONST struct relation *rel);  extern int *BlackBoxArgs(CONST struct relation *rel);
292    
293  #define BlackBoxNumberArgs(r) (RBBOX(r).nargs)  #define BlackBoxNumberArgs(r) (RBBOX(r).nargs)
294    
295  /*------------------------------------------------------------------------  /*------------------------------------------------------------------------
296   *    GlassBoxRelation queries.      GLASS BOX STUFF
297   *    These will be called a lot so that they will all be made  */
298   *    macros. Double check that the same is true for the  
299   *    ExternalFunc routines.  /*
300   *------------------------------------------------------------------------      These will be called a lot so that they will all be made
301   */      macros. Double check that the same is true for the
302        ExternalFunc routines.
303    */
304  extern struct ExternalFunc *GlassBoxExtFunc(CONST struct relation *rel);  extern struct ExternalFunc *GlassBoxExtFunc(CONST struct relation *rel);
305  extern int GlassBoxRelIndex(CONST struct relation *rel);  extern int GlassBoxRelIndex(CONST struct relation *rel);
306  extern int *GlassBoxArgs(CONST struct relation *rel);  extern int *GlassBoxArgs(CONST struct relation *rel);
307    
308  #define GlassBoxNumberArgs(r) (RGBOX(r).nargs)  #define GlassBoxNumberArgs(r) (RGBOX(r).nargs)
309    
310    /*-----------------------------------------------------------------------------
311        GENERAL STUFF FOR RELATIONS
312    */
313    
314  extern CONST struct gl_list_t *RelationVarList(CONST struct relation *r);  extern CONST struct gl_list_t *RelationVarList(CONST struct relation *r);
315  /**<  /**<
316   *  Returns the unique incident variable list which is owned by the      Returns the unique incident variable list which is owned by the
317   *  relation. *DO NOT MODIFY*. It is for the convenience of those      relation. *DO NOT MODIFY*. It is for the convenience of those
318   *  desirous of a READ_ONLY look. It is a list of instance pointers, which may      desirous of a READ_ONLY look. It is a list of instance pointers, which may
319   *  be NULL.      be NULL.
320   *  All relation types will properly respond to this qurey.      All relation types will properly respond to this qurey.
321   */  */
322    
323  ASC_DLLSPEC(dim_type *) RelationDim(CONST struct relation *rel);  ASC_DLLSPEC(dim_type *) RelationDim(CONST struct relation *rel);
324  /**<  /**<
325   *  Return the derived dimensionality of the relation.      Return the derived dimensionality of the relation.
326   *  Defaults to Wild.      Defaults to Wild.
327   */  */
328    
329  ASC_DLLSPEC(int ) SetRelationDim(struct relation *rel, dim_type *d);  ASC_DLLSPEC(int ) SetRelationDim(struct relation *rel, dim_type *d);
330  /**<  /**<
331   *  Set the  dimensionality of the relation. return 0 unless there is a      Set the  dimensionality of the relation. return 0 unless there is a
332   *  problem (rel was null, for instance.)      problem (rel was null, for instance.)
333   */  */
334    
335  ASC_DLLSPEC(double) RelationResidual(CONST struct relation *rel);  ASC_DLLSPEC(double) RelationResidual(CONST struct relation *rel);
336  /**<  /**<
337   *  Return the residual of the relation.      Return the residual of the relation.
338   */  */
339    
340  extern void SetRelationResidual(struct relation *rel, double value);  extern void SetRelationResidual(struct relation *rel, double value);
341  /**<  /**<
342   *  Set the value of the relation residual.      Set the value of the relation residual.
343   */  */
344    
345  extern double RelationMultiplier(CONST struct relation *rel);  extern double RelationMultiplier(CONST struct relation *rel);
346  /**<  /**<
347   *  Return the langrage multiplier of the relation. This will have some      Return the langrage multiplier of the relation. This will have some
348   *  hybrid dimensions that still needs to be decided, as it is a function      hybrid dimensions that still needs to be decided, as it is a function
349   *  of the objective function(s).      of the objective function(s).
350   */  */
351    
352  extern void SetRelationMultiplier(struct relation *rel, double value);  extern void SetRelationMultiplier(struct relation *rel, double value);
353  /**<  /**<
354   *  Set the value of the relation langrage multiplier. This will have some      Set the value of the relation langrage multiplier. This will have some
355   *  hybrid dimensions that still needs to be decided.      hybrid dimensions that still needs to be decided.
356   */  */
357    
358  ASC_DLLSPEC(int ) RelationIsCond(CONST struct relation *rel);  ASC_DLLSPEC(int ) RelationIsCond(CONST struct relation *rel);
359  /**<  /**<
360   *  Return the value of the iscond flag of the relation.      Return the value of the iscond flag of the relation.
361   *  If relation is NULL, returns 0.      If relation is NULL, returns 0.
362   */  */
363    
364  extern void SetRelationIsCond(struct relation *rel);  extern void SetRelationIsCond(struct relation *rel);
365  /**<  /**<
366   *  Sets the value of the iscond field of the relation to 1      Sets the value of the iscond field of the relation to 1
367   *  If relation is NULL, writes error message.      If relation is NULL, writes error message.
368   */  */
369    
370  extern double RelationNominal(CONST struct relation *rel);  extern double RelationNominal(CONST struct relation *rel);
371  /**<  /**<
372   *  Return the nominal of the relation.      Return the nominal of the relation.
373   */  */
374    
375  ASC_DLLSPEC(void ) SetRelationNominal(struct relation *rel, double d);  ASC_DLLSPEC(void ) SetRelationNominal(struct relation *rel, double d);
376  /**<  /**<
377   *  Sets the value of the nominal field of the relation to the absolute      Sets the value of the nominal field of the relation to the absolute
378   *  value of d, unless d is 0.0.      value of d, unless d is 0.0.
379   */  */
380    
381  ASC_DLLSPEC(double ) CalcRelationNominal(struct Instance *i);  ASC_DLLSPEC(double ) CalcRelationNominal(struct Instance *i);
382  /**<  /**<
383   *    Calculate the nominal of a relation.      Calculate the nominal of a relation.
384   *    Returns 0.0 if something went detectably wrong in the calculation,      Returns 0.0 if something went detectably wrong in the calculation,
385   *    otherwise calculates the absolute value of the maximum affine term      otherwise calculates the absolute value of the maximum affine term
386   *    and returns it, given an instance which is a token relation. Other      and returns it, given an instance which is a token relation. Other
387   *    relation types return the value 1.0.      relation types return the value 1.0.
388   *    Does not set the constant stored with the relation.<br><br>      Does not set the constant stored with the relation.
389   *  
390   *    When opcode relations are fully supported,      When opcode relations are fully supported,
391   *    this function should be made to work for them, too.<br><br>      this function should be made to work for them, too.
392   *  
393   *    Art contends that the proper nominal for blackbox      Art contends that the proper nominal for blackbox
394   *    relations is the nominal of the output variable, though this is      relations is the nominal of the output variable, though this is
395   *    not implemented at present.<br><br>      not implemented at present.
396   *  
397   *    Art further contends that the proper nominal for glassbox relations      Art further contends that the proper nominal for glassbox relations
398   *    is the 2 norm of its gradient vector after fixed variables are      is the 2 norm of its gradient vector after fixed variables are
399   *    removed and free elements have been scaled by the variable nominals.      removed and free elements have been scaled by the variable nominals.
400   *    It should be noted that the glassbox scaling proposed by this method      It should be noted that the glassbox scaling proposed by this method
401   *    is precisely what the Slv solvers used up to August 1995.      is precisely what the Slv solvers used up to August 1995.
402   *    IMHO (baa) the glassbox generated should include code which knows      IMHO the glassbox generated should include code which knows
403   *    how to calculate relation nominals.      how to calculate relation nominals. -- BAA
404   */  */
405    
406  extern void PrintRelationNominals(struct Instance *i);  extern void PrintRelationNominals(struct Instance *i);
407  /**<  /**<
408   *   Perform a visit instance tree starting at i and calc/print consts.      Perform a visit-instance-tree starting at i and calc/print consts.
409   *   This function doesn't belong here.      This function doesn't belong here.
410   */  */
411    
412  extern char *tmpalloc(int nbytes);  extern char *tmpalloc(int nbytes);
413  /**<  /**<
414   *   Temporarily allocates a given number of bytes.  The memory need      Temporarily allocates a given number of bytes.  The memory need
415   *   not be freed, but the next call to this function will reuse the      not be freed, but the next call to this function will reuse the
416   *   previous allocation. Memory returned will NOT be zeroed.      previous allocation. Memory returned will NOT be zeroed.
417   *   Calling with nbytes==0 will free any memory allocated.      Calling with nbytes==0 will free any memory allocated.
418   */  */
419    
420  #define tmpalloc_array(nelts,type)  ((type *)tmpalloc((nelts)*sizeof(type)))  #define tmpalloc_array(nelts,type)  ((type *)tmpalloc((nelts)*sizeof(type)))
421  /**<  /**<
422   *  Creates an array of "nelts" objects, each with type "type".      Creates an array of "nelts" objects, each with type "type".
423   */  */
424    
425    /*------------------------------------------------------------------------------
426        RELATION EVALUATION STUFF
427    
 /*  
428   *   The following mess of functions   *   The following mess of functions
429   *   migrated out of the solver directory into this file. Who   *   migrated out of the solver directory into this file. Who
430   *   ever heard of a math modeling language that doesn't supply   *   ever heard of a math modeling language that doesn't supply
# Line 417  extern char *tmpalloc(int nbytes); Line 432  extern char *tmpalloc(int nbytes);
432   *   These are for Token equations, though if they can be done   *   These are for Token equations, though if they can be done
433   *   for all equation types that's a plus.   *   for all equation types that's a plus.
434   *   Supercedes the bleeding mess in calc.c, rel.c, relman.c which was   *   Supercedes the bleeding mess in calc.c, rel.c, relman.c which was
435   *   very ugly.   *   very ugly. -- BAA 5/96
  *    BAA 5/96  
  *  
436   */   */
437    
438  extern int RelationCalcResidualBinary(CONST struct relation *rel, double *res);  int RelationCalcResidualBinary(CONST struct relation *rel, double *res);
439  /**<  /**<
440   * Returns 0 if it calculates a valid residual, 1 if   * Returns 0 if it calculates a valid residual, 1 if
441   * for any reason it cannot. Reasons include:   * for any reason it cannot. Reasons include:
# Line 434  extern int RelationCalcResidualBinary(CO Line 447  extern int RelationCalcResidualBinary(CO
447   * This function may raise SIGFPE it calls external code.   * This function may raise SIGFPE it calls external code.
448   */   */
449    
450  extern enum safe_err  enum safe_err
451  RelationCalcResidualPostfixSafe(struct Instance *i, double *res);  RelationCalcResidualPostfixSafe(struct Instance *i, double *res);
452  /**<  /**<
453   *  Sets *res to the value (leftside - rightside) of the relation.   *  Sets *res to the value (leftside - rightside) of the relation.
# Line 443  RelationCalcResidualPostfixSafe(struct I Line 456  RelationCalcResidualPostfixSafe(struct I
456   *  a lot of range checking AND a floating point trap.   *  a lot of range checking AND a floating point trap.
457   */   */
458    
459  extern int RelationCalcResidualPostfix(struct Instance *i, double *res);  int RelationCalcResidualPostfix(struct Instance *i, double *res);
460  /**<  /**<
461   *  Sets *res to the value (leftside - rightside) of the relation.   *  Sets *res to the value (leftside - rightside) of the relation.
462   *  Uses postfix evaluation.   *  Uses postfix evaluation.
# Line 484  ASC_DLLSPEC(int ) RelationCalcExceptions Line 497  ASC_DLLSPEC(int ) RelationCalcExceptions
497   *  With the Safe relation evaluation routines in all but the most   *  With the Safe relation evaluation routines in all but the most
498   *  bizarre circumstances. The Safe results are necessarily approximate.   *  bizarre circumstances. The Safe results are necessarily approximate.
499   *   *
500   * @bug At present, gradient checks are not implemented as the code   * @TODO (bug) At present, gradient checks are not implemented as the code
501   *      required is messy. We need to rearrange CalcResidGrad().   *      required is messy. We need to rearrange CalcResidGrad().
502   */   */
503    
504  extern int RelationCalcResidualInfix(struct Instance *i, double *res);  int RelationCalcResidualInfix(struct Instance *i, double *res);
505  /**<  /**<
506   *  Sets *res to the value (leftside - rightside) of the relation.   *  Sets *res to the value (leftside - rightside) of the relation.
507   *  Uses infix evaluation.   *  Uses infix evaluation.
# Line 500  extern int RelationCalcResidualInfix(str Line 513  extern int RelationCalcResidualInfix(str
513  #define RelationCalcResidual(i,r) RelationCalcResidualPostfix(i,r)  #define RelationCalcResidual(i,r) RelationCalcResidualPostfix(i,r)
514  #define RelationCalcResidualSafe(i,r) RelationCalcResidualPostfixSafe(i,r)  #define RelationCalcResidualSafe(i,r) RelationCalcResidualPostfixSafe(i,r)
515    
516  extern int RelationCalcGradient(struct Instance *i, double *grad);  int RelationCalcGradient(struct Instance *i, double *grad);
 /**<  
  *  This calculates the gradient of the relation df/dx (f = lhs-rhs)  
  *  where x is ALL entries in the relation's var list.  
  *  The var list is a gl_list_t indexed from 1 to length.  
  *  You must provide grad, the space to put the gradient, an array of  
  *  double of length matching the gl_list_t.  
  *  We will stuff df/dx[i] into grad[i-1], where i is the list position  
  *  in the relation's var list.<br><br>  
  *  
  *  Non-zero return value implies a problem.<br><br>  
  *  
  *  Notes: This function is a possible source of floating point  
  *         exceptions and should not be used during compilation.  
  */  
   
 extern enum safe_err RelationCalcGradientSafe(struct Instance *i, double *grad);  
 /**<  
  *  This calculates the gradient of the relation df/dx (f = lhs-rhs)  
  *  where x is ALL entries in the relation's var list.  
  *  This function is to RelationCalcGradient as  
  *  RelationCalcResidualSafe is to RelationCalcResidual.  
  *  Non-zero return value implies a problem.  
  */  
   
 extern int RelationCalcResidGrad(struct Instance *i, double *res, double *grad);  
517  /**<  /**<
518   *  This function combines the Residual and Gradient calls, since these      This calculates the gradient of the relation df/dx (f = lhs-rhs)
519   *  may be done together at basically the cost of just one.      where x is ALL entries in the relation's var list.
520   *  Non-zero return value implies a problem.<br><br>      The var list is a gl_list_t indexed from 1 to length.
521   *  Notes: This function is a possible source of floating point      You must provide grad, the space to put the gradient, an array of
522   *         exceptions and should not be used during compilation.      double of length matching the gl_list_t.
523   */      We will stuff df/dx[i] into grad[i-1], where i is the list position
524        in the relation's var list.<br><br>
525        
526        @return Non-zero return value implies a problem
527        
528        @NOTE This function is a possible source of floating point
529        exceptions and should not be used during compilation.
530    */
531    
532    enum safe_err RelationCalcGradientSafe(struct Instance *i, double *grad);
533    /**<
534        This calculates the gradient of the relation df/dx (f = lhs-rhs)
535        where x is ALL entries in the relation's var list.
536        This function is to RelationCalcGradient as
537        RelationCalcResidualSafe is to RelationCalcResidual.
538        Non-zero return value implies a problem.
539    */
540    
541    int RelationCalcResidGrad(struct Instance *i, double *res, double *grad);
542    /**<
543        This function combines the Residual and Gradient calls, since these
544        may be done together at basically the cost of just one.
545        Non-zero return value implies a problem.<br><br>
546        
547        @NOTE This function is a possible source of floating point exceptions
548        and should not be used during compilation.
549    */
550    
551  extern enum safe_err  enum safe_err
552  RelationCalcResidGradSafe(struct Instance *i, double *res, double *grad);  RelationCalcResidGradSafe(struct Instance *i, double *res, double *grad);
553  /**<  /**<
554   *  This is the combined Safe version.      This is the combined Safe version.
555   *  Non-zero return value implies a problem.      Non-zero return value implies a problem.
556   */  */
557    
558  extern double *RelationFindRoots(struct Instance *i,  /*------------------------------------------------------------------------------
559                                   double lower_bound,      ROOT FINDING FUNCTIONS (deprecated?)
560                                   double upper_bound,  */
561                                   double nominal,  
562                                   double tolerance,  double *RelationFindRoots(struct Instance *i,
563                                   unsigned long *varnum,          double lower_bound, double upper_bound,
564                                   int *able,          double nominal, double tolerance,
565                                   int *nsolns);          unsigned long *varnum,
566  /**<          int *able,
567   *  RelationFindRoot WILL find a root if there is one. It is in charge of          int *nsolns);
568   *  trying every trick in the book. The user must pass in a pointer to a  /**<
569   *  struct relation. We require that the relation be of the type e_token with      RelationFindRoot WILL find a root if there is one. It is in charge of
570   *  relation->relop = e_equals and we will whine if it is not.  The calling      trying every trick in the book. The user must pass in a pointer to a
571   *  function should check able and/or nsolns before accessing the information      struct relation. We require that the relation be of the type e_token with
572   *  in the soln_list.      relation->relop = e_equals and we will whine if it is not.  The calling
573   *  - nsolns < 0 : severe problems, soln_list will be NULL      function should check able and/or nsolns before accessing the information
574   *  - nsolns = 0 : No solution found      in the soln_list.
575   *  - nsolns > 0 : The soln_status equals the number of roots found      - nsolns < 0 : severe problems, such as var not found; soln_list will be NULL
576   *      - nsolns = 0 : No solution found
577   *  The calling function should NOT free the soln_list.<br><br>      - nsolns > 0 : The soln_status equals the number of roots found
578   *      
579   *  This function is NOT thread safe because it uses an internal memory      @return NULL if success? 1 for success and 0 for failure?
580   *  recycle.  
581   *  Before shutting down the system, or as desired, call this as:      @NOTE In general compiler functions return 0 for success but this function
582   *  (void) RelationFindRoots(NULL,0,0,0,0,NULL,NULL,NULL);      returns 1 for success because success = 1 is the convention on the solver
583   *  in order to free this memory.      side.
584   */  
585        @TODO (we really should make a system wide convention for return values)
586  extern int RelationCalcDerivative(struct Instance *i, unsigned long index, double *grad);  
587  /**<      @NOTE The calling function should NOT free the soln_list.
588   *  This calculates the derivative of the relation df/dx (f = lhs-rhs)  
589   *  where x is the INDEX-th entry in the relation's var list.      @NOTE we should recycle the memory used for glob_rel
590   *  The var list is a gl_list_t indexed from 1 to length.      
591   *  Non-zero return value implies a problem.<br><br>      @NOTE This function is NOT thread safe because it uses an internal memory
592   *      recycle.
593   *  Notes: This function is a possible source of floating point  
594   *         exceptions and should not be used during compilation.      @NOTE Before shutting down the system, or as desired, call this as:
595   */      (void) RelationFindRoots(NULL,0,0,0,0,NULL,NULL,NULL);
596        in order to free this memory.
597  extern enum safe_err  
598  RelationCalcDerivativeSafe(struct Instance *i, unsigned long index, double *grad);      @TODO I think that this function might not really be used, or might only
599  /**<      be used by old solvers. Is that the case? -- JP
600   *  Calculates the derivative safely.  */
601   *  Non-zero return value implies a problem.  
602   */  /*-----------------------------------------------------------------------------
603        BINTOKEN STUFF
604    */
605  extern struct gl_list_t  
606  *CollectTokenRelationsWithUniqueBINlessShares(struct Instance *i, unsigned long maxlen);  struct gl_list_t *CollectTokenRelationsWithUniqueBINlessShares(
607  /**<      struct Instance *i, unsigned long maxlen);
608   * Collect the token relation 'shares' in i which have not been compiled  /**<
609   * (or at least attempted so) to binary form yet.      Collect the token relation 'shares' in i which have not been compiled
610   * If more than maxlen are found, returns NULL instead. Presumably there      (or at least attempted so) to binary form yet.
611   * is some upper limit beyond which you don't want to know the answer to      If more than maxlen are found, returns NULL instead. Presumably there
612   * this question. If none are found, returns a 0 length list.      is some upper limit beyond which you don't want to know the answer to
613   * Actually, it is not a share that is collected, but instead any      this question. If none are found, returns a 0 length list.
614   * one of the relation instances which use the share is collected.      Actually, it is not a share that is collected, but instead any
615   * The list returned should be destroyed by the user (not its content,though).      one of the relation instances which use the share is collected.
616   */      The list returned should be destroyed by the user (not its content,though).
617    */
618    
619  #endif  /* ASC_RELATION_UTIL_H */  #endif  /* ASC_RELATION_UTIL_H */

Legend:
Removed from v.693  
changed lines
  Added in v.694

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