/[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 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: 8154 byte(s)
Documentation changes; making 'FIX' statement less verbose;
Commenting out ununsed 'CreateExternalFunction' function
1 /*
2 * External Functions Module
3 * by Kirk Andre Abbott
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 *
14 * The Ascend Language Interpreter is free software; you can redistribute
15 * it and/or modify it under the terms of the GNU General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
18 *
19 * The Ascend Language Interpreter is distributed in hope that it will be
20 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * General Public License for more details.
23 *
24 * You should have received a copy of the GNU General Public License along
25 * with the program; if not, write to the Free Software Foundation, Inc., 675
26 * Mass Ave, Cambridge, MA 02139 USA. Check the file named COPYING.
27 */
28
29 /** @file
30 * External Functions Module.
31 * <pre>
32 * When #including extfunc.h, make sure these files are #included first:
33 * #include "utilities/ascConfig.h"
34 * #include "compiler.h"
35 * </pre>
36 * @todo Complete documentation of compiler/extfunc.h.
37 */
38
39 #ifndef ASC_EXTFUNC_H
40 #define ASC_EXTFUNC_H
41
42 /**
43 ExtEvalFunc type is a function pointer.
44 @see rootfind.c:51
45
46 @param mode 'to pass to the eval function' (?)
47 @param m relation index
48 @param n variable index
49 @param x 'x' vector (?)
50 @param u 'u' vector (?)
51 @param f vector of residuals
52 @param g vector of gradients
53 */
54 typedef int ExtEvalFunc(int *mode, int *m, int *n,
55 double *x, double *u, double *f, double *g);
56
57 /**
58 ExtProcFunc type is a function pointer.
59
60 @param mode
61 @param m
62 @param n
63 @param x
64 @param u
65 @param f
66 @param g
67 */
68 typedef int ExtProcFunc(int *mode, int *m, unsigned long *n,
69 double *x, double *u, double *f, double *g);
70
71
72 struct ExternalFunc {
73 CONST char *name;
74 unsigned long n_inputs;
75 unsigned long n_outputs;
76 char *help;
77 ExtEvalFunc *init;
78 ExtEvalFunc *value;
79 ExtEvalFunc *deriv;
80 ExtEvalFunc *deriv2;
81 };
82
83 enum Calc_status {
84 calc_converged, calc_diverged, calc_fp_error, calc_incorrect_args,
85 calc_error, calc_all_ok
86 };
87
88 struct Slv_Interp {
89 int nodestamp;
90 enum Calc_status status;
91 void *user_data;
92 unsigned first_call :1;
93 unsigned last_call :1;
94 unsigned check_args :1;
95 unsigned recalculate :1;
96 unsigned deriv_eval :1;
97 unsigned func_eval :1;
98 unsigned single_step :1;
99 };
100
101 typedef int ExtBBoxFunc(struct Slv_Interp *,
102 int ninputs, int noutputs,
103 double *inputs, double *outputs, double *jacobian);
104
105 extern void InitExternalFuncLibrary(void);
106 /**<
107 * The main external functions library initialization routine. This
108 * function must be called before all others.
109 */
110
111 extern void DestroyExtFuncLibrary(void);
112 /**<
113 * Destroys the external function library and deallocates all the
114 * information associated with it.
115 */
116
117
118 #ifdef THIS_IS_AN_UNUSED_FUNCTION
119 extern struct ExternalFunc *CreateExternalFunc(CONST char *name);
120 /**<
121 * Creates a new ExternalFunc node having the specified name.
122 * All other attributes are initialized to 0 or NULL. There is
123 * no checking for the validity or uniqueness of name.
124 *
125 * @param name The name for the new ExternalFunc.
126 * @return A pointer to the new ExternalFunc.
127 */
128 #endif /* THIS_IS_AN_UNUSED_FUNCTION */
129
130 extern int AddExternalFunc(struct ExternalFunc *efunc, int force);
131 /**<
132 * Adds an external function node to the external function library.
133 * We look up the external function before adding it to the
134 * library. If force is zero and the function exists then nothing
135 * is done and 0 is returned. If force is true, then the old entry is
136 * removed and the new one is added; 1 is returned. If the name is not
137 * found then the information is added to the library.
138 */
139
140 extern struct ExternalFunc *LookupExtFunc(CONST char *funcname);
141 /**<
142 * Returns the external function having the given name, or NULL if
143 * not found.
144 */
145
146
147 extern int CreateUserFunction(CONST char *name,
148 ExtEvalFunc *init,
149 ExtEvalFunc **value,
150 ExtEvalFunc **deriv,
151 ExtEvalFunc **deriv2,
152 CONST unsigned long n_inputs,
153 CONST unsigned long n_outputs,
154 CONST char *help);
155 /**<
156 * Adds an external function to the ASCEND system.
157 * The name of the function is looked up. If it already exists, the
158 * information will be updated. If the name was not found in the
159 * external function library, then an external function node will be
160 * created and added to the external function library. We make a
161 * *copy* of the help string if it is provided. We also make a copy
162 * of the name. Anyone desirous of ASCEND knowing about their
163 * functions must use this protocol.
164 *
165 * @param name Name of the function being added (or updated).
166 * @param init Pointer to initialisation function, or NULL if none.
167 * @param value Pointer to a function pointer to the evaluation function,
168 * or NULL if none.
169 * @param deriv Pointer to a function pointer to the first partial
170 * derivative function, or NULL if none.
171 * @param deriv2 Pointer to a function pointer to the second derivative
172 * function, or NULL if none.
173 * @return Returns 0 if the function was successfully added,
174 * non-zero otherwise.
175 *
176 * @todo compiler/extfunc:CreateUserFunction() is broken. The current
177 * implementation wants to treat value, deriv, and deriv2 as BOTH
178 * function pointers and arrays of function pointers. We need to
179 * decide which they are or else provide a mechanism supporting dual
180 * roles. This could be a union in ExternalFunc explicitly allowing
181 * them to be both. This would necessitate 2 CreateUserFunction()
182 * varieties - 1 taking (ExtEvalFunc *) and 1 taking (ExtEvalFunc **)
183 * to allow the different types of ExternalFunc's to be set up.
184 */
185
186 extern struct ExternalFunc *RemoveExternalFunc(char *name);
187 /**<
188 * Removes the external function having the given name from the
189 * External function library.
190 */
191
192 extern void DestroyExternalFunc(struct ExternalFunc *name);
193 /**<
194 * Destroys an external function, but does *not* remove it from the
195 * library. Use the RemoveExternalFunc library first to retrieve the
196 * information, then call this function.
197 */
198
199 extern int (*GetInitFunc(struct ExternalFunc *efunc))(/* */);
200 extern ExtBBoxFunc *GetValueFunc(struct ExternalFunc *efunc);
201 extern ExtBBoxFunc *GetDerivFunc(struct ExternalFunc *efunc);
202 extern ExtBBoxFunc *GetDeriv2Func(struct ExternalFunc *efunc);
203
204 extern ExtEvalFunc **GetValueJumpTable(struct ExternalFunc *efunc);
205 extern ExtEvalFunc **GetDerivJumpTable(struct ExternalFunc *efunc);
206 extern ExtEvalFunc **GetDeriv2JumpTable(struct ExternalFunc *efunc);
207
208 extern CONST char *ExternalFuncName(CONST struct ExternalFunc *efunc);
209 /**<
210 * Returns the name of an external function.
211 */
212
213 extern unsigned long NumberInputArgs(CONST struct ExternalFunc *efunc);
214 extern unsigned long NumberOutputArgs(CONST struct ExternalFunc *efunc);
215
216
217 extern void PrintExtFuncLibrary(FILE *f);
218 /**<
219 * Prints the contents of the external function library to the given
220 * file. The file must be opened for writing.
221 */
222
223 extern char *WriteExtFuncLibraryString(void);
224 /**<
225 * Returns a string of formatted information about the external functions
226 * defined. the string looks like "{{name1} {help1}} {{name2} {help2}} "
227 * The string may be empty/NULL if there are no external functions loaded.
228 */
229
230 /**
231 This provides a way for other code to visit the external function list
232 */
233 extern void TraverseExtFuncLibrary(void (*)(void *,void *),void *secondparam);
234
235 #endif /* ASC_EXTFUNC_H */
236

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