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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 475 - (show annotations) (download) (as text)
Mon Apr 17 05:46:47 2006 UTC (18 years, 2 months ago) by ben.allan
File MIME type: text/x-chdr
File size: 16030 byte(s)
much more commenting for blackbox relations implementers.
1 /*
2 * External Functions Module
3 * by Kirk Andre Abbott and Ben Allan
4 * Created: July 4, 1994.
5 * Version: $Revision: 1.5 $
6 * Version control file: $RCSfile: extfunc.h,v $
7 * Date last modified: $Date: 1997/07/18 12:29:30 $
8 * Last modified by: $Author: mthomas $
9 *
10 * This file is part of the Ascend Language Interpreter.
11 *
12 * Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly, Kirk Andre Abbott
13 * Copyright (C) 2006 Benjamin Allan
14 *
15 * The Ascend Language Interpreter is free software; you can redistribute
16 * it and/or modify it under the terms of the GNU General Public License as
17 * published by the Free Software Foundation; either version 2 of the
18 * License, or (at your option) any later version.
19 *
20 * The Ascend Language Interpreter is distributed in hope that it will be
21 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23 * General Public License for more details.
24 *
25 * You should have received a copy of the GNU General Public License along
26 * with the program; if not, write to the Free Software Foundation, Inc., 675
27 * Mass Ave, Cambridge, MA 02139 USA. Check the file named COPYING.
28 */
29
30 /** @file
31 * External Functions Module.
32 * <pre>
33 * When #including extfunc.h, make sure these files are #included first:
34 * #include "utilities/ascConfig.h"
35 * #include "compiler/instance_enum.h"
36 * #include "general/list.h"
37 * #include "compiler/compiler.h"
38 * </pre>
39 * @todo Complete documentation of compiler/extfunc.h.
40 */
41
42 #ifndef ASC_EXTFUNC_H
43 #define ASC_EXTFUNC_H
44
45
46 /**
47 ExtEvalFunc type is a function pointer.
48 @see rootfind.c:51
49
50 @param mode 'to pass to the eval function' (?)
51 @param m relation index
52 @param n variable index
53 @param x 'x' vector (?)
54 @param u 'u' vector (?)
55 @param f vector of residuals
56 @param g vector of gradients
57 */
58 typedef int ExtEvalFunc(int *mode, int *m, int *n,
59 double *x, double *u, double *f, double *g);
60
61 /**
62 ExtProcFunc type is a function pointer.
63
64 @param mode
65 @param m
66 @param n
67 @param x
68 @param u
69 @param f
70 @param g
71 */
72 typedef int ExtProcFunc(int *mode, int *m, unsigned long *n,
73 double *x, double *u, double *f, double *g);
74
75
76 enum Calc_status {
77 calc_converged, calc_diverged, calc_fp_error, calc_incorrect_args,
78 calc_error, calc_all_ok
79 };
80
81 /**
82 * Each blackbox equation may show up more than once in a simulation
83 * if models repeat in the structure. For each occurence of the
84 * blackbox, a unique Slv_Interp object is given when the set of
85 * corresponding relations is created.
86 * It is used for the blackbox to communicate to the rest of the system.
87 * If the blackbox retains internal state between evaluation calls,
88 * it should store this state in the user_data pointer.
89 */
90 struct Slv_Interp {
91 /* unique identifier tied to instance tree. */
92 int nodestamp;
93 /* status is set by evaluation calls before returning. */
94 enum Calc_status status;
95 /* user_data is set by the external library if it has any persistent state
96 during calls to ExtBBoxInitFunc initial and final given in
97 CreateUserFunctionBlackBox.
98 */
99 void *user_data;
100 /* first call will be true when the initial function pointer is called. */
101 unsigned first_call :1;
102 /* first call will be true when the final function pointer is called. */
103 unsigned last_call :1;
104 /* If check_args, blackbox should do any argument checking of the variables, data. */
105 unsigned check_args :1;
106 /* If recalculate, the caller thinks the input may have changed. */
107 unsigned recalculate :1;
108 /* If func_eval, the caller is using the residual function pointer. */
109 unsigned func_eval :1;
110 /* If deriv_eval, the caller is using the deriv function pointer. */
111 unsigned deriv_eval :1;
112 /* If hess_eval, the caller is using the hessian function pointer. */
113 unsigned hess_eval :1;
114 /* If single_step, the caller would like one step toward the solution;
115 usually this is meaningless and should be answered with calc_diverged. */
116 unsigned single_step :1;
117 };
118
119 /** Setup/teardown, if any needed, for a particular instance.
120 We don't actually support this method anywhere right now, as
121 we're not sure what it can logically be used for that the
122 init function in dlopening shouldn't be doing.
123 In principal, we could add and cache a client-data pointer
124 in each instance so that the external method may be stateful.
125 Presently, the external methods must be clever to do that
126 on their own or must use ascend instances for state instead.
127 @param context the instance on which the method may be run.
128 */
129 typedef int ExtMethodInit( struct Instance *context);
130
131 /** Run method a particular instance.
132 @param context the instance on which the method is run.
133 context may also appear explicitly in the arg list as SELF.
134 @param args Each element of args is a list of instances; each
135 name in the ascend-language argument list is expanded to a list
136 (which may contain 0 or more Instances) and appended to args.
137 */
138 typedef int ExtMethodRun( struct Instance *context, struct gl_list_t *args);
139
140 typedef int ExtBBoxInitFunc(struct Slv_Interp *,
141 struct Instance *,
142 struct gl_list_t *);
143
144 /* this one may need splitting/rework for hessian */
145 typedef int ExtBBoxFunc(struct Slv_Interp *,
146 int ninputs,
147 int noutputs,
148 double *inputs,
149 double *outputs,
150 double *jacobian);
151
152
153 /** this is an enum to clarify and make type-safer the
154 the variation of external functions circa 1995.
155 Blackboxes might be callable from methods as well, but
156 this is dependent on their code registration to setup.
157 */
158 enum ExternalFuncType {
159 efunc_ERR = 0, /**< err value (Traps old mode errors too) */
160 efunc_BlackBox = 10, /**< remainder of struct is blackbox */
161 efunc_GlassBox = 20, /**< remainder of struct is glassbox */
162 efunc_Method = 30 /**< remainder of struct is method */
163 };
164
165 struct GlassBoxExternalFunc {
166 ExtEvalFunc *initial;
167 ExtEvalFunc **value; /**< array of relation residual functions. */
168 ExtEvalFunc **deriv; /**< array of relation gradient functions. */
169 ExtEvalFunc **deriv2; /**< array of relation hessian functions. */
170 ExtEvalFunc *final; /**< cleanup function. */
171 };
172
173 struct BlackBoxExternalFunc {
174 ExtBBoxInitFunc *initial;
175 ExtBBoxFunc *value; /**< relation residual function. */
176 ExtBBoxFunc *deriv; /**< relation gradient function. */
177 ExtBBoxFunc *deriv2; /**< relation hessian function. */
178 ExtBBoxFunc *final; /**< cleanup function. */
179 };
180
181 struct MethodExternalFunc {
182 ExtMethodRun *run; /**< the method invoked. */
183 #if 0 /* have no use for these currently. */
184 ExtMethodInit *initial; /**< allowed to be null if not needed. */
185 ExtMethodInit *final; /**< allowed to be null if not needed. */
186 #endif
187 };
188
189 struct ExternalFunc {
190 enum ExternalFuncType etype;
191 CONST char *name; /**< a string we own. */
192 CONST char *help; /**< a string we own. */
193 unsigned long n_inputs; /**< expected # of inputs. */
194 unsigned long n_outputs; /**< expected # of outputs. */
195 union {
196 struct GlassBoxExternalFunc glass;
197 struct BlackBoxExternalFunc black;
198 struct MethodExternalFunc method;
199 } u;
200 };
201
202
203 /** retired struct. */
204 struct RetiredExternalFunc {
205 CONST char *name; /**< a string we own. */
206 char *help; /**< a string we own. */
207 ExtEvalFunc *init;
208 ExtEvalFunc **value; /**< array of relation residual functions. */
209 ExtEvalFunc **deriv; /**< array of relation gradient functions. */
210 ExtEvalFunc **deriv2; /**< array of relation hessian functions. */
211 unsigned long n_inputs;
212 unsigned long n_outputs;
213 };
214
215
216 extern void InitExternalFuncLibrary(void);
217 /**<
218 * The main external functions library initialization routine. This
219 * function must be called before all others.
220 */
221
222 extern void DestroyExtFuncLibrary(void);
223 /**<
224 * Destroys the external function library and deallocates all the
225 * information associated with it.
226 */
227
228
229 extern int AddExternalFunc(struct ExternalFunc *efunc, int force);
230 /**<
231 * Adds an external function node to the external function library.
232 * We look up the external function before adding it to the
233 * library. If force is zero and the function exists then nothing
234 * is done and 0 is returned. If force is true, then the old entry is
235 * removed and the new one is added; 1 is returned. If the name is not
236 * found then the information is added to the library.
237 */
238
239 extern struct ExternalFunc *LookupExtFunc(CONST char *funcname);
240 /**<
241 * Returns the external function having the given name, or NULL if
242 * not found.
243 */
244
245 typedef int (*CreateUserFunction_fptr_t)(CONST char *name,
246 ExtEvalFunc *init,
247 ExtEvalFunc **value,
248 ExtEvalFunc **deriv,
249 ExtEvalFunc **deriv2,
250 CONST unsigned long n_inputs,
251 CONST unsigned long n_outputs,
252 CONST char *help);
253
254 extern int DLEXPORT CreateUserFunctionBlackBox(CONST char *name,
255 ExtBBoxInitFunc *init,
256 ExtBBoxFunc *value,
257 ExtBBoxFunc *deriv,
258 ExtBBoxFunc *deriv2,
259 ExtBBoxFunc *final,
260 CONST unsigned long n_inputs,
261 CONST unsigned long n_outputs,
262 CONST char *help);
263 /**<
264 * Adds an external function to the ASCEND system.
265 * The name of the function is looked up. If it already exists, the
266 * information will be updated. If the name was not found in the
267 * external function library, then an external function node will be
268 * created and added to the external function library. We make a
269 * *copy* of the help string if it is provided. We also make a copy
270 * of the name. Anyone desirous of ASCEND knowing about their
271 * functions must use this protocol.
272 *
273 * @param name Name of the function being added (or updated).
274 * @param init Pointer to initialisation function, or NULL if none.
275 * @param final Pointer to shutdown function. May be same as init.
276 * @param value evaluation function pointers, or NULL if none.
277 * @param deriv first partial derivative functions, or NULL if none.
278 * @param deriv2 second derivative functions, or NULL if none.
279 * @return Returns 0 if the function was successfully added,
280 * non-zero otherwise.
281 *
282 */
283
284 extern int DLEXPORT CreateUserFunctionGlassBox(CONST char *name,
285 ExtEvalFunc *init,
286 ExtEvalFunc **value,
287 ExtEvalFunc **deriv,
288 ExtEvalFunc **deriv2,
289 ExtEvalFunc *final,
290 CONST unsigned long n_inputs,
291 CONST unsigned long n_outputs,
292 CONST char *help);
293 /**<
294 * Adds an external function to the ASCEND system.
295 * The name of the function is looked up. If it already exists, the
296 * information will be updated. If the name was not found in the
297 * external function library, then an external function node will be
298 * created and added to the external function library. We make a
299 * *copy* of the help string if it is provided. We also make a copy
300 * of the name. Anyone desirous of ASCEND knowing about their
301 * functions must use this protocol.
302 *
303 * @param name Name of the function being added (or updated).
304 * @param init Pointer to initialisation function, or NULL if none.
305 * @param value array of evaluation function pointers,
306 * or NULL if none.
307 * @param deriv array of first partial
308 * derivative functions, or NULL if none.
309 * @param deriv2 array of second derivative
310 * functions, or NULL if none.
311 * @return Returns 0 if the function was successfully added,
312 * non-zero otherwise.
313 *
314 */
315
316 extern int DLEXPORT CreateUserFunctionMethod(CONST char *name,
317 /* ExtMethodInit *initial, */
318 ExtMethodRun *run,
319 /* ExtMethodInit *final, */
320 CONST long n_args,
321 CONST char *help);
322 /**<
323 * Adds an external method call to the ASCEND system.
324 * The name of the function is looked up. If it already exists, the
325 * information will be updated. If the name was not found in the
326 * external function library, then an external function node will be
327 * created and added to the external function library. We make a
328 * *copy* of the help string if it is provided. We also make a copy
329 * of the name. Anyone desirous of ASCEND knowing about their
330 * external methods must use this protocol.
331 *
332 * @param name Name of the function being added (or updated).
333 * @param initial Pointer to initialisation function, or NULL if none.
334 * @param run Pointer to the method.
335 * @param final Pointer to cleanup function, or NULL if none.
336 * @param n_args number of arguments expected as input, or -1 if any number is allowed.
337 * @return Returns 0 if the function was successfully added,
338 * non-zero otherwise.
339 */
340
341 extern struct ExternalFunc *RemoveExternalFunc(char *name);
342 /**<
343 * Removes the external function having the given name from the
344 * External function library.
345 */
346
347 extern void DestroyExternalFunc(struct ExternalFunc *name);
348 /**<
349 * Destroys an external function, but does *not* remove it from the
350 * library. Use the RemoveExternalFunc library first to retrieve the
351 * information, then call this function.
352 */
353
354 /** Fetch black initialization function. */
355 extern ExtBBoxInitFunc *GetInitFunc(struct ExternalFunc *efunc);
356 /** Fetch black residual function. */
357 extern ExtBBoxFunc *GetValueFunc(struct ExternalFunc *efunc);
358 /** Fetch black sensitivity gradient function. */
359 extern ExtBBoxFunc *GetDerivFunc(struct ExternalFunc *efunc);
360 /** Fetch black hessian function. */
361 extern ExtBBoxFunc *GetDeriv2Func(struct ExternalFunc *efunc);
362 /** Fetch black cleanup function. */
363 extern ExtBBoxInitFunc *GetFinalFunc(struct ExternalFunc *efunc);
364
365
366 /** Fetch glass initialization function. */
367 extern ExtEvalFunc *GetGlassBoxInit(struct ExternalFunc *efunc);
368 /** Get glass box residual function array. */
369 extern ExtEvalFunc **GetValueJumpTable(struct ExternalFunc *efunc);
370 /** Get glass box gradient function array. */
371 extern ExtEvalFunc **GetDerivJumpTable(struct ExternalFunc *efunc);
372 /** Get glass box hessian function array. */
373 extern ExtEvalFunc **GetDeriv2JumpTable(struct ExternalFunc *efunc);
374 /** Fetch black initialization function. */
375 extern ExtEvalFunc *GetGlassBoxFinal(struct ExternalFunc *efunc);
376
377 /** Fetch method run function. */
378 extern ExtMethodRun *GetExtMethodRun(struct ExternalFunc *efunc);
379
380
381 extern CONST char *ExternalFuncName(CONST struct ExternalFunc *efunc);
382 /**<
383 * Returns the name of an external function.
384 */
385
386 /** fetch the required input count for glass, black, or method. */
387 extern unsigned long NumberInputArgs(CONST struct ExternalFunc *efunc);
388 /** fetch the required output count for glass, black, or method. */
389 extern unsigned long NumberOutputArgs(CONST struct ExternalFunc *efunc);
390
391
392 extern void PrintExtFuncLibrary(FILE *f);
393 /**<
394 * Prints the contents of the external function library to the given
395 * file. The file must be opened for writing.
396 */
397
398 extern char *WriteExtFuncLibraryString(void);
399 /**<
400 * Returns a string of formatted information about the external functions
401 * defined. the string looks like "{{name1} {help1}} {{name2} {help2}} "
402 * The string may be empty/NULL if there are no external functions loaded.
403 */
404
405 /**
406 This provides a way for other code to visit the external function list
407 */
408 extern void TraverseExtFuncLibrary(void (*)(void *,void *),void *secondparam);
409
410 #endif /* ASC_EXTFUNC_H */
411

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