generic/compiler/extfunc.h

/*
 *  External Functions Module
 *  by Kirk Andre Abbott
 *  Created: July 4, 1994.
 *  Version: $Revision: 1.5 $
 *  Version control file: $RCSfile: extfunc.h,v $
 *  Date last modified: $Date: 1997/07/18 12:29:30 $
 *  Last modified by: $Author: mthomas $
 *
 *  This file is part of the Ascend Language Interpreter.
 *
 *  Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly, Kirk Andre Abbott
 *
 *  The Ascend Language Interpreter is free software; you can redistribute
 *  it and/or modify it under the terms of the GNU General Public License as
 *  published by the Free Software Foundation; either version 2 of the
 *  License, or (at your option) any later version.
 *
 *  The Ascend Language Interpreter is distributed in hope that it will be
 *  useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with the program; if not, write to the Free Software Foundation, Inc., 675
 *  Mass Ave, Cambridge, MA 02139 USA.  Check the file named COPYING.
 */

/** @file
 *  External Functions Module.
 *  <pre>
 *  When #including extfunc.h, make sure these files are #included first:
 *         #include "utilities/ascConfig.h"
 *         #include "compiler.h"
 *  </pre>
 *  @todo Complete documentation of compiler/extfunc.h.
 */

#ifndef ASC_EXTFUNC_H
#define ASC_EXTFUNC_H

/**
    ExtEvalFunc type is a function pointer.
    @see rootfind.c:51

    @param mode 'to pass to the eval function' (?)
    @param m    relation index
    @param n    variable index
    @param x    'x' vector (?)
    @param u    'u' vector (?)
    @param f    vector of residuals
    @param g    vector of gradients
*/
typedef int ExtEvalFunc(int *mode, int *m, int *n,
   double *x, double *u, double *f, double *g);

/**
    ExtProcFunc type is a function pointer.

    @param mode 
    @param m
    @param n
    @param x
    @param u
    @param f
    @param g
*/
typedef int ExtProcFunc(int *mode, int *m, unsigned long *n,
   double *x, double *u, double *f, double *g);


struct ExternalFunc {
  CONST char *name;
  unsigned long n_inputs;
  unsigned long n_outputs;
  char *help;
  ExtEvalFunc *init;
  ExtEvalFunc *value;
  ExtEvalFunc *deriv;
  ExtEvalFunc *deriv2;
};

enum Calc_status {
  calc_converged, calc_diverged, calc_fp_error, calc_incorrect_args,
  calc_error, calc_all_ok
};

struct Slv_Interp {
  int nodestamp;
  enum Calc_status status;
  void *user_data;
  unsigned first_call  :1;
  unsigned last_call   :1;
  unsigned check_args  :1;
  unsigned recalculate :1;
  unsigned deriv_eval  :1;
  unsigned func_eval   :1;
  unsigned single_step  :1;
};

typedef int ExtBBoxFunc(struct Slv_Interp *,
   int ninputs, int noutputs,
   double *inputs, double *outputs, double *jacobian);

extern void InitExternalFuncLibrary(void);
/**<
 *  The main external functions library initialization routine. This
 *  function must be called before all others.
 */

extern void DestroyExtFuncLibrary(void);
/**<
 *  Destroys the external function library and deallocates all the
 *  information associated with it.
 */


extern struct ExternalFunc *CreateExternalFunc(CONST char *name);
/**<
 *  Creates a new ExternalFunc node having the specified name.  
 *  All other attributes are initialized to 0 or NULL.  There is
 *  no checking for the validity or uniqueness of name.
 *
 *  @param name The name for the new ExternalFunc.
 *  @return A pointer to the new ExternalFunc.
 */

extern int AddExternalFunc(struct ExternalFunc *efunc, int force);
/**< 
 *  Adds an external function node to the external function library. 
 *  We look up the external function before adding it to the
 *  library.  If force is zero and the function exists then nothing
 *  is done and 0 is returned.  If force is true, then the old entry is
 *  removed and the new one is added; 1 is returned.  If the name is not
 *  found then the information is added to the library.
 */

extern struct ExternalFunc *LookupExtFunc(CONST char *funcname);
/**< 
 *  Returns the external function having the given name, or NULL if
 *  not found.
 */


extern int CreateUserFunction(CONST char *name,
                              ExtEvalFunc *init,
                              ExtEvalFunc **value,
                              ExtEvalFunc **deriv,
                              ExtEvalFunc **deriv2,
                              CONST unsigned long n_inputs,
                              CONST unsigned long n_outputs,
                              CONST char *help);
/**<
 *  Adds an external function to the ASCEND system.
 *  The name of the function is looked up.  If it already exists, the 
 *  information will be updated.  If the name was not found in the 
 *  external function library, then an external function node will be 
 *  created and added to the external function library.  We make a 
 *  *copy* of the help string if it is provided.  We also make a copy 
 *  of the name.  Anyone desirous of ASCEND knowing about their 
 *  functions must use this protocol.
 *
 *  @param name Name of the function being added (or updated).
 *  @param init Pointer to initialisation function, or NULL if none.
 *  @param value Pointer to a function pointer to the evaluation function, 
 *               or NULL if none.
 *  @param deriv Pointer to a function pointer to the first partial 
 *               derivative function, or NULL if none.
 *  @param deriv2 Pointer to a function pointer to the second derivative 
 *                function, or NULL if none.
 *  @return Returns 0 if the function was successfully added, 
 *          non-zero otherwise.
 *
 *  @todo compiler/extfunc:CreateUserFunction() is broken.  The current
 *        implementation wants to treat value, deriv, and deriv2 as BOTH
 *        function pointers and arrays of function pointers.  We need to 
 *        decide which they are or else provide a mechanism supporting dual
 *        roles.  This could be a union in ExternalFunc explicitly allowing 
 *        them to be both.  This would necessitate 2 CreateUserFunction()
 *        varieties - 1 taking (ExtEvalFunc *) and 1 taking (ExtEvalFunc **)
 *        to allow the different types of ExternalFunc's to be set up.
 */

extern struct ExternalFunc *RemoveExternalFunc(char *name);
/**< 
 *  Removes the external function having the given name from the
 *  External function library.
 */

extern void DestroyExternalFunc(struct ExternalFunc *name);
/**< 
 *  Destroys an external function, but does *not* remove it from the
 *  library. Use the RemoveExternalFunc library first to retrieve the
 *  information, then call this function.
 */

extern int (*GetInitFunc(struct ExternalFunc *efunc))(/* */);
extern ExtBBoxFunc *GetValueFunc(struct ExternalFunc *efunc);
extern ExtBBoxFunc *GetDerivFunc(struct ExternalFunc *efunc);
extern ExtBBoxFunc *GetDeriv2Func(struct ExternalFunc *efunc);

extern ExtEvalFunc **GetValueJumpTable(struct ExternalFunc *efunc);
extern ExtEvalFunc **GetDerivJumpTable(struct ExternalFunc *efunc);
extern ExtEvalFunc **GetDeriv2JumpTable(struct ExternalFunc *efunc);

extern CONST char *ExternalFuncName(CONST struct ExternalFunc *efunc);
/**< 
 *  Returns the name of an external function.
 */

extern unsigned long NumberInputArgs(CONST struct ExternalFunc *efunc);
extern unsigned long NumberOutputArgs(CONST struct ExternalFunc *efunc);


extern void PrintExtFuncLibrary(FILE *f);
/**< 
 *  Prints the contents of the external function library to the given
 *  file. The file must be opened for writing.
 */

extern char *WriteExtFuncLibraryString(void);
/**< 
 * Returns a string of formatted information about the external functions
 * defined. the string looks like "{{name1} {help1}} {{name2} {help2}} "
 * The string may be empty/NULL if there are no external functions loaded.
 */

/**
    This provides a way for other code to visit the external function list
*/
extern void TraverseExtFuncLibrary(void (*)(void *,void *),void *secondparam);

#endif /* ASC_EXTFUNC_H */

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	extern struct ExternalFunc CreateExternalFunc(CONST char name);
119	/**<
120	* Creates a new ExternalFunc node having the specified name.
121	* All other attributes are initialized to 0 or NULL. There is
122	* no checking for the validity or uniqueness of name.
123	*
124	* @param name The name for the new ExternalFunc.
125	* @return A pointer to the new ExternalFunc.
126	*/
127
128	extern int AddExternalFunc(struct ExternalFunc *efunc, int force);
129	/**<
130	* Adds an external function node to the external function library.
131	* We look up the external function before adding it to the
132	* library. If force is zero and the function exists then nothing
133	* is done and 0 is returned. If force is true, then the old entry is
134	* removed and the new one is added; 1 is returned. If the name is not
135	* found then the information is added to the library.
136	*/
137
138	extern struct ExternalFunc LookupExtFunc(CONST char funcname);
139	/**<
140	* Returns the external function having the given name, or NULL if
141	* not found.
142	*/
143
144
145	extern int CreateUserFunction(CONST char *name,
146	ExtEvalFunc *init,
147	ExtEvalFunc **value,
148	ExtEvalFunc **deriv,
149	ExtEvalFunc **deriv2,
150	CONST unsigned long n_inputs,
151	CONST unsigned long n_outputs,
152	CONST char *help);
153	/**<
154	* Adds an external function to the ASCEND system.
155	* The name of the function is looked up. If it already exists, the
156	* information will be updated. If the name was not found in the
157	* external function library, then an external function node will be
158	* created and added to the external function library. We make a
159	* copy of the help string if it is provided. We also make a copy
160	* of the name. Anyone desirous of ASCEND knowing about their
161	* functions must use this protocol.
162	*
163	* @param name Name of the function being added (or updated).
164	* @param init Pointer to initialisation function, or NULL if none.
165	* @param value Pointer to a function pointer to the evaluation function,
166	* or NULL if none.
167	* @param deriv Pointer to a function pointer to the first partial
168	* derivative function, or NULL if none.
169	* @param deriv2 Pointer to a function pointer to the second derivative
170	* function, or NULL if none.
171	* @return Returns 0 if the function was successfully added,
172	* non-zero otherwise.
173	*
174	* @todo compiler/extfunc:CreateUserFunction() is broken. The current
175	* implementation wants to treat value, deriv, and deriv2 as BOTH
176	* function pointers and arrays of function pointers. We need to
177	* decide which they are or else provide a mechanism supporting dual
178	* roles. This could be a union in ExternalFunc explicitly allowing
179	* them to be both. This would necessitate 2 CreateUserFunction()
180	* varieties - 1 taking (ExtEvalFunc ) and 1 taking (ExtEvalFunc *)
181	* to allow the different types of ExternalFunc's to be set up.
182	*/
183
184	extern struct ExternalFunc RemoveExternalFunc(char name);
185	/**<
186	* Removes the external function having the given name from the
187	* External function library.
188	*/
189
190	extern void DestroyExternalFunc(struct ExternalFunc *name);
191	/**<
192	* Destroys an external function, but does not remove it from the
193	* library. Use the RemoveExternalFunc library first to retrieve the
194	* information, then call this function.
195	*/
196
197	extern int (GetInitFunc(struct ExternalFunc efunc))(/* */);
198	extern ExtBBoxFunc GetValueFunc(struct ExternalFunc efunc);
199	extern ExtBBoxFunc GetDerivFunc(struct ExternalFunc efunc);
200	extern ExtBBoxFunc GetDeriv2Func(struct ExternalFunc efunc);
201
202	extern ExtEvalFunc *GetValueJumpTable(struct ExternalFunc efunc);
203	extern ExtEvalFunc *GetDerivJumpTable(struct ExternalFunc efunc);
204	extern ExtEvalFunc *GetDeriv2JumpTable(struct ExternalFunc efunc);
205
206	extern CONST char ExternalFuncName(CONST struct ExternalFunc efunc);
207	/**<
208	* Returns the name of an external function.
209	*/
210
211	extern unsigned long NumberInputArgs(CONST struct ExternalFunc *efunc);
212	extern unsigned long NumberOutputArgs(CONST struct ExternalFunc *efunc);
213
214
215	extern void PrintExtFuncLibrary(FILE *f);
216	/**<
217	* Prints the contents of the external function library to the given
218	* file. The file must be opened for writing.
219	*/
220
221	extern char *WriteExtFuncLibraryString(void);
222	/**<
223	* Returns a string of formatted information about the external functions
224	* defined. the string looks like "{{name1} {help1}} {{name2} {help2}} "
225	* The string may be empty/NULL if there are no external functions loaded.
226	*/
227
228	/**
229	This provides a way for other code to visit the external function list
230	*/
231	extern void TraverseExtFuncLibrary(void ()(void ,void ),void secondparam);
232
233	#endif /* ASC_EXTFUNC_H */
234