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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 203 - (show annotations) (download) (as text)
Mon Jan 23 04:13:17 2006 UTC (18 years, 5 months ago) by johnpye
File MIME type: text/x-chdr
File size: 13438 byte(s)
Documentation changes; making 'FIX' statement less verbose;
Commenting out ununsed 'CreateExternalFunction' function
1 /*
2 * Function module
3 * by Tom Epperly
4 * Version: $Revision: 1.16 $
5 * Version control file: $RCSfile: func.h,v $
6 * Date last modified: $Date: 2001/01/31 22:23:57 $
7 * Last modified by: $Author: ballan $
8 *
9 * This file is part of the Ascend Language Interpreter.
10 *
11 * Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
12 *
13 * The Ascend Language Interpreter is free software; you can redistribute
14 * it and/or modify it under the terms of the GNU General Public License as
15 * published by the Free Software Foundation; either version 2 of the
16 * License, or (at your option) any later version.
17 *
18 * The Ascend Language Interpreter is distributed in hope that it will be
19 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 * General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License
24 * along with the program; if not, write to the Free Software Foundation,
25 * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
26 * COPYING.
27 *
28 * Revision notes:
29 * If CHRIS_FUNC defined, auxillary quantities to func structure.
30 * 2/96 baa Probably somebody should properly set these evaluation
31 * defined below based on math.h when possible.
32 *
33 */
34
35 /** @file
36 * Function-of-one-variable module.
37 * <pre>
38 * When #including func.h, make sure these files are #included first:
39 * #include "utilities/ascConfig.h"
40 * #include "fractions.h"
41 * #include "compiler.h"
42 * #include "dimen.h"
43 * #include "functype.h"
44 * </pre>
45 * @todo Complete documentation of func.h.
46 */
47
48 #ifndef ASC_FUNC_H
49 #define ASC_FUNC_H
50
51 #include "general/mathmacros.h"
52
53 /*
54 * the following should be ifdefed to deal with math.h values
55 */
56 #define F_ERF_COEF 1.1283791670955130 /**< = 2 / sqrt(PI) */
57 #define F_LOG10_COEF 0.4342944819032518 /**< = log10(e) = 1/ln(10) */
58 #define F_PI 3.1415926535897932385E0
59 #define F_PI_HALF 1.5707963267948966192E0
60 #define F_LIM_EXP 709.78 /**< approximately ln(maxdouble) */
61 #define F_LIM_CUBE 5.6438030941223618e101 /**< cbrt(maxdouble)*/
62 #define F_LIM_SQR 1.0e154 /**< sqrt(maxdouble) */
63
64 #ifdef __STDC__
65 # if __STDC__
66 /**
67 * stdc==1 --> erf, cbrt not defined in headers. user should link
68 * against a library that does provide them. ASCEND is research
69 * code: we aren't going to waste time reimplementing these basic
70 * functions.
71 */
72 extern double DLEXPORT cbrt(double);
73
74 # ifdef HAVE_ERF
75 extern double erf(double);
76 # endif /* HAVE_ERF */
77 # endif /* __STDC__ == 1*/
78 /**<
79 * in the case where __STDC__ is defined but == 0, system headers
80 * should provide cbrt, erf.
81 */
82 #endif /* stdc defined */
83
84 extern CONST struct Func *LookupFunc(CONST char *name);
85 /**<
86 * Lookup the function with the given name. If no match is found, it
87 * returns NULL. name is the ASCEND name, not C name.
88 * <pre>
89 * Currently defined:
90 * "exp" e^x
91 * "ln" natural logarithm of x
92 * "log10" logarithm of x base 10
93 * "sin" sine of x
94 * "cos" cosine of x
95 * "tan" tangent of x
96 * "sqr" x*x
97 * "sqrt" the square root of x
98 * "arcsin" the inverse sine of x
99 * "arccos" the inverse cosine of x
100 * "arctan" the inverse tangent of x
101 *
102 * "erf" the error function
103 * "lnm" modified natural log:
104 * x>epsilon? ln(x): x/epsilon +ln(epsilon) -1
105 * "sinh" hyperbolic sine
106 * "cosh" hyperbolic cosine
107 * "tanh" hyperbolic tangent
108 * "arcsinh" inv hyperbolic sine
109 * "arccosh" inv hyperbolic cosine
110 * "arctanh" inv hyperbolic tangent
111 *
112 * "cube" the cube of x
113 * "cbrt" the cube root of x
114 * "abs" absolute value of x
115 *
116 * "hold" returns the current value of x.
117 * </pre>
118 * The last 10 are not fully supported for chris.[ch]
119 * All functions return principal (postive) values if there is a choice.
120 * None of them perform range checking. ln(-1) -> float error.
121 */
122
123 extern CONST struct Func *LookupFuncById(enum Func_enum id);
124 /**<
125 * Lookups a function by its enumerated type rather than by a string as
126 * in the above function.
127 */
128
129 extern double FuncGetLnmEpsilon(void);
130 /**<
131 * Return the current epsilon for the modified log function lnm.
132 */
133 #define FuncGetLnmEpsilon() (g_lnm_epsilon)
134
135 extern void FuncSetLnmEpsilon(double e);
136 /**<
137 * Change the current epsilon for the modified log function lnm.
138 * epsilon > 0.0.
139 */
140 extern double g_lnm_epsilon;
141 #define FuncSetLnmEpsilon(e) \
142 (e>(double)0.0 ? g_lnm_epsilon=e : FPRINTF(ASCERR,"bad lnm eps"))
143
144 /**<
145 * declare cbrt() and erf() since some vendors put
146 * these functions in odd headers
147 */
148 extern double DLEXPORT cbrt(double);
149 #ifdef HAVE_ERF
150 extern double erf(double);
151 #endif /* HAVE_ERF */
152
153 #ifdef NDEBUG
154 # define ascnint(d) (((int) (d)>=0.0 ? floor((d) + 0.5) : -floor(0.5 - (d))))
155 /**<
156 * Converts a double to the nearest integer (release version).
157 * @param d double, the real number to convert.
158 * @return The nearest integer as an int.
159 */
160 #else
161 # define ascnint(a) ascnintF(a)
162 /**<
163 * Converts a double to the nearest integer (debug version).
164 * @param d double, the real number to convert.
165 * @return The nearest integer as an int.
166 */
167 extern int DLEXPORT ascnintF(double);
168 /**<
169 * Implementation function for debug version of ascnint().
170 * Do not call this function directly - use ascnint() instead.
171 */
172
173 #endif
174
175 extern double DLEXPORT dln(double x);
176 extern double DLEXPORT dln2(double x);
177 extern double DLEXPORT dlog10(double x);
178 extern double DLEXPORT dlog102(double x);
179 extern double DLEXPORT lnm(double x);
180 extern double DLEXPORT dlnm(double x);
181 extern double DLEXPORT dlnm2(double x);
182 /**<
183 * Modified natural log function and derivatives.
184 * <pre>
185 *
186 * ( ln(x) if x.ge.epsilon
187 * lnm(x)= (
188 * ( x/epsilon + ln(epsilon) - 1 otherwise
189 *
190 *
191 * ( 1/x if x.ge.epsilon
192 * d( lnm(x) )/dx = (
193 * ( 1/epsilon otherwise
194 *
195 *
196 * ( -1/x^2 if x.ge.epsilon
197 * d^2( lnm(x) )/dx^2 = (
198 * ( 0 otherwise
199 *
200 * epsilon determined by FuncGet/SetLnmEpsilon.
201 * </pre>
202 */
203
204 extern double DLEXPORT dtanh(double x);
205 extern double DLEXPORT dtanh2(double x);
206 extern double DLEXPORT arcsinh(double x);
207 extern double DLEXPORT arccosh(double x);
208 extern double DLEXPORT arctanh(double x);
209 extern double DLEXPORT darcsinh(double x);
210 extern double DLEXPORT darcsinh2(double x);
211 extern double DLEXPORT darccosh(double x);
212 extern double DLEXPORT darccosh2(double x);
213 extern double DLEXPORT darctanh(double x);
214 extern double DLEXPORT darctanh2(double x);
215 /**<
216 * Zero, first and second partials of (inverse) hyperbolic functions.
217 */
218
219 extern double DLEXPORT sqr(double x);
220 extern double DLEXPORT dsqr(double x);
221 extern double DLEXPORT dsqr2(double x);
222 extern double DLEXPORT cube(double x);
223 extern double DLEXPORT dcube(double x);
224 extern double DLEXPORT dcube2(double x);
225 /**<
226 * Zero, first and second partials of x for sqr, cube.
227 */
228
229 extern double DLEXPORT asc_ipow(double a, int n);
230 extern double DLEXPORT asc_d1ipow(double a, int n);
231 extern double DLEXPORT asc_d2ipow(double a, int n);
232 /**<
233 * Integer power function, a^n, and its first and second derivatives.
234 * d = asc_ipow(a,n);
235 * d1 = asc_d1ipow(a,n);
236 * d2 = asc_d2ipow(a,n);
237 *
238 * Special cases ipow:
239 * a^0 = 1, 0^n = 0, 0^0=1 -- the last is mathematically undefined,
240 * so this function should not be called with 0.0,0.
241 *
242 * Special cases d1ipow,d2ipow:
243 */
244
245 extern double DLEXPORT hold(double x);
246 /**<
247 * Returns the value it is passed.
248 * The primary purpose is as an operator so we can write
249 * equations of the form x = hold(x) which act essentially
250 * as a fixed flag when a solver is partitioning.
251 * If x is fixed, the equation is singular.
252 * hold(x) is a constant value, so its derivatives are 0.
253 */
254
255 extern double DLEXPORT dsqrt(double x);
256 extern double DLEXPORT dsqrt2(double x);
257 extern double DLEXPORT dcbrt(double x);
258 extern double DLEXPORT dcbrt2(double x);
259 extern double DLEXPORT dfabs(double x);
260 extern double DLEXPORT dfabs2(double x);
261 extern double DLEXPORT dhold(double x);
262 #define dhold2 dhold
263 /**<
264 * first and second partials of sqrt cbrt fabs hold
265 * dfabs is undefined at 0. We take the standard kluge: d(abs(x=0))/dx=0
266 * dfabs2(x) = 0. It might be thought of as infinite at x=0, but not here.
267 * dhold, dhold2 = 0 for all x.
268 */
269
270 extern double DLEXPORT dasin(double x);
271 extern double DLEXPORT dasin2(double x);
272 extern double DLEXPORT dcos(double x);
273 extern double DLEXPORT dcos2(double x);
274 extern double DLEXPORT dacos(double x);
275 extern double DLEXPORT dacos2(double x);
276 extern double DLEXPORT dtan(double x);
277 extern double DLEXPORT dtan2(double x);
278 extern double DLEXPORT datan(double x);
279 extern double DLEXPORT datan2(double x);
280 /**<
281 * First and second partials of the cosine, tangent, arctangent functions
282 */
283
284 #ifdef HAVE_ERF
285 extern double DLEXPORT derf(double x);
286 extern double DLEXPORT derf2(double x);
287 #endif /* HAVE_ERF */
288 /**<
289 * First and second derivatives of erf()
290 */
291
292 extern CONST char *FuncName(CONST struct Func *f);
293 /**<
294 * Return the ASCEND language name of the function.
295 * Not a symchar.
296 */
297
298 extern CONST char *FuncCName(CONST struct Func *f);
299 /**<
300 * Return the C language name of the function, if any.
301 */
302
303 extern CONST char *FuncDeriv1CName(CONST struct Func *f);
304 /**<
305 * Return the C language name of the function first derivative, if any.
306 */
307
308 extern CONST char *FuncDeriv2CName(CONST struct Func *f);
309 /**<
310 * Return the C language name of the function second derivative, if any.
311 */
312
313 extern enum Func_enum FuncId(CONST struct Func *f);
314 /**<
315 * Return the identification of the function.
316 */
317
318 extern CONST dim_type *FuncDimens(CONST struct Func *f);
319 /**<
320 * Return the dimensionality required for the arg of the function.
321 * sin, cos, tan -> P.
322 * arc(sin,cos,tan),exp,ln,log,lnm,erf ->dimensionless.
323 * sqrt->wilddimension (user must check for even poweredness of arg)
324 * as this may be the case for an infinite # of different dims.
325 * sqr ->wilddimension (sqr, abs, cube anything you like.)
326 */
327
328 extern double FuncEval(CONST struct Func *f, double u);
329 /**<
330 * Return f(u).
331 */
332
333 extern double FuncEvalSafe(CONST struct Func *f,
334 double u,
335 enum safe_err *not_safe);
336 /**<
337 * Return f(u) (safe version).
338 */
339
340 extern double FuncDeriv(CONST struct Func *f, double u);
341 /**<
342 * Return df/du evaluated at u.
343 */
344
345 extern double FuncDerivSafe(CONST struct Func *f,
346 double u,
347 enum safe_err *not_safe);
348 /**<
349 * Return df/du evaluated at u (safe version).
350 */
351
352 extern double FuncDeriv2(CONST struct Func *f, double u);
353 /**<
354 * Return the second derivative (d^2f/du^2) evaluated at u.
355 */
356
357 extern double FuncDeriv2Safe(CONST struct Func *f,
358 double u,
359 enum safe_err *not_safe);
360 /**<
361 * Return the second derivative (d^2f/du^2) evaluated at u (safe version).
362 */
363
364 #ifdef CHRIS_FUNC
365
366 extern struct Interval FuncRange(CONST struct Func *f, struct Interval i);
367 /**<
368 * Return a bound on the range of the function over the given interval.
369 */
370
371 extern void FuncSlope(CONST struct Func *f,
372 unsigned long nvar,
373 struct Interval *center,
374 struct Interval *range,
375 struct Interval *slope);
376 /**<
377 * Perform the interval slope calculation.
378 */
379
380 extern struct Interval FuncIDeriv(CONST struct Func *f, struct Interval i);
381 /**<
382 * ...
383 */
384
385 extern double ArgMin(CONST struct Func *f, double lower, double upper);
386 /**<
387 * Return the arg min of the function over the range.
388 */
389
390 extern double ArgMax(CONST struct Func *f, double lower, double upper);
391 /**<
392 * Return the arg max of the function over the range.
393 */
394
395 extern double ConvexEnv(CONST struct Func *f, double x,
396 double lower, double upper);
397 /**<
398 * Return the value of the convex envelope of the function at the value
399 * x which ranges from lower to upper.
400 */
401
402 extern double ConvexEnvDeriv(CONST struct Func *f, double x,
403 double lower, double upper);
404 /**<
405 * Return the derivative of the convex envelope of the function at the
406 * value x which ranges from lower to upper.
407 */
408
409 extern double ConcaveEnv(CONST struct Func *f, double x,
410 double lower, double upper);
411 /**<
412 * Return the value of the concave envelope of the function at the value
413 * x which ranges from lower to upper.
414 */
415
416 extern double ConcaveEnvDeriv(CONST struct Func *f, double x,
417 double lower, double upper);
418 /**<
419 * Return the derivative of the concave envelope of the function at the
420 * value x which ranges from lower to upper.
421 */
422
423 #endif /* CHRIS_FUNC */
424
425 #endif /* ASC_FUNC_H */
426

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