source: trunk/ADOL-C/include/adolc/externfcts.h @ 736

Last change on this file since 736 was 736, checked in by kulshres, 2 years ago

design a C++ object oriented wrapper for external functions

it is easier to work with classes, inheritence and overloaded member
functions in scripting languages like python and R instead of raw
pointers to functions in order to call arbitrary code.

Signed-off-by: Kshitij Kulshreshtha <kshitij@…>

  • Property svn:keywords set to Author Date Id Revision
File size: 11.0 KB
Line 
1/*----------------------------------------------------------------------------
2 ADOL-C -- Automatic Differentiation by Overloading in C++
3 File:     externfcts.h
4 Revision: $Id: externfcts.h 736 2017-05-30 08:48:05Z kulshres $
5 Contents: public functions and data types for extern (differentiated)
6           functions.
7 
8 Copyright (c) Andreas Kowarz, Jean Utke
9
10 This file is part of ADOL-C. This software is provided as open source.
11 Any use, reproduction, or distribution of the software constitutes
12 recipient's acceptance of the terms of the accompanying license file.
13                     
14----------------------------------------------------------------------------*/
15
16#if !defined(ADOLC_EXTERNFCTS_H)
17#define ADOLC_EXTERNFCTS_H 1
18
19#include <adolc/internal/common.h>
20#include <adolc/adouble.h>
21
22BEGIN_C_DECLS
23
24typedef int (ADOLC_ext_fct) (int n, double *x, int m, double *y);
25typedef int (ADOLC_ext_fct_fos_forward) (int n, double *dp_x, double *dp_X, int m, double *dp_y, double *dp_Y);
26typedef int (ADOLC_ext_fct_fov_forward) (int n, double *dp_x, int p, double **dpp_X, int m, double *dp_y, double **dpp_Y);
27typedef int (ADOLC_ext_fct_hos_forward) (int n, double *dp_x, int d, double **dpp_X, int m, double *dp_y, double **dpp_Y);
28typedef int (ADOLC_ext_fct_hov_forward) (int n, double *dp_x, int d, int p, double ***dppp_X, int m, double *dp_y, double ***dppp_Y);
29typedef int (ADOLC_ext_fct_fos_reverse) (int m, double *dp_U, int n, double *dp_Z, double *dp_x, double *dp_y);
30typedef int (ADOLC_ext_fct_fov_reverse) (int m, int p, double **dpp_U, int n, double **dpp_Z, double *dp_x, double *dp_y);
31typedef int (ADOLC_ext_fct_hos_reverse) (int m, double *dp_U, int n, int d, double **dpp_Z); 
32typedef int (ADOLC_ext_fct_hov_reverse) (int m, int p, double **dpp_U, int n, int d, double ***dppp_Z, short **spp_nz);
33
34/**
35 * we add a second set of function pointers with a signature expanded by a an integer array iArr
36 * and a parameter iArrLength motivated by externalizing sparse solvers where the sparsity format
37 * may be triples (i,j,A[i][j]) and a number of nonzero entries nz where all these integers are to
38 * be packed into iArr. Doing this will still allow the integers to be stored in the locint part
39 * of the tape.
40 * The alternative to doing this is the introduction of a separate stack to contain the extra data
41 * but this would break the self-containment of the tape.
42 */
43typedef int (ADOLC_ext_fct_iArr) (int iArrLength, int *iArr, int n, double *x, int m, double *y);
44typedef int (ADOLC_ext_fct_iArr_fos_forward) (int iArrLength, int *iArr, int n, double *dp_x, double *dp_X, int m, double *dp_y, double *dp_Y);
45typedef int (ADOLC_ext_fct_iArr_fov_forward) (int iArrLength, int *iArr, int n, double *dp_x, int p, double **dpp_X, int m, double *dp_y, double **dpp_Y);
46typedef int (ADOLC_ext_fct_iArr_hos_forward) (int iArrLength, int *iArr, int n, double *dp_x, int d, double **dpp_X, int m, double *dp_y, double **dpp_Y);
47typedef int (ADOLC_ext_fct_iArr_hov_forward) (int iArrLength, int *iArr, int n, double *dp_x, int d, int p, double ***dppp_X, int m, double *dp_y, double ***dppp_Y);
48typedef int (ADOLC_ext_fct_iArr_fos_reverse) (int iArrLength, int *iArr, int m, double *dp_U, int n, double *dp_Z, double *dp_x, double *dp_y);
49typedef int (ADOLC_ext_fct_iArr_fov_reverse) (int iArrLength, int *iArr, int m, int p, double **dpp_U, int n, double **dpp_Z, double *dp_x, double *dp_y);
50typedef int (ADOLC_ext_fct_iArr_hos_reverse) (int iArrLength, int *iArr, int m, double *dp_U, int n, int d, double **dpp_Z);
51typedef int (ADOLC_ext_fct_iArr_hov_reverse) (int iArrLength, int *iArr, int m, int p, double **dpp_U, int n, int d, double ***dppp_Z, short **spp_nz);
52
53
54/**
55 * A variable of this type has to be instantiated by reg_ext_fct (see below) and a pointer to it is
56 * returned. Within reg_ext_fct the memberse function and index are properly set.
57 * is likely to be wrong in this case. Use pointers instead.
58 */
59typedef struct {
60
61  /**
62   * DO NOT touch - the function pointer is set through reg_ext_fct
63   */
64  ADOLC_ext_fct *function; 
65  ADOLC_ext_fct_iArr *function_iArr;
66
67  /**
68   * DO NOT touch - the index is set through reg_ext_fct
69   */
70  locint index;           
71
72  /**
73   * below are function pointers used for call back from the corresponding ADOL-C trace interpreters;
74   * these function pointers are initialized to 0 by reg_ext_fct;
75   * the  user needs to set eplicitly the function pointers for the trace interpreters called in the
76   * application driver
77   */
78
79  /**
80   * this points to a  method implementing a forward execution of the externally differentiated function dp_y=f(dp_x);
81   * the pointer would typically be set to the same function pointer supplied in the call to reg_ext_fct,
82   * i.e. zos_forward would be equal to function (above)
83   * but there are cases when it makes sense for this to be different as illustrated
84   * in examples/additional_examples/ext_diff_func/ext_diff_func.cpp 
85   */
86  ADOLC_ext_fct *zos_forward;
87  ADOLC_ext_fct_iArr *zos_forward_iArr;
88
89  /**
90   * this points to a  method implementing a forward execution of the externally differentiated function dp_y=f(dp_x)
91   * and computing the projection dp_Y=Jacobian*dp_x
92   * see also the explanation of the dp_X/Y  members below.
93   */
94  ADOLC_ext_fct_fos_forward *fos_forward;
95  ADOLC_ext_fct_iArr_fos_forward *fos_forward_iArr;
96
97  /**
98   * this points to a  method implementing a forward execution of the externally differentiated function dp_y=f(dp_x)
99   * and computing the projection dpp_Y=Jacobian*dpp_x
100   * see also the explanation of the dpp_X/Y  members below.
101   */
102  ADOLC_ext_fct_fov_forward *fov_forward;
103  ADOLC_ext_fct_iArr_fov_forward *fov_forward_iArr;
104  /**
105   * higher order scalar forward for external functions  is currently not implemented in uni5_for.c
106   */
107  ADOLC_ext_fct_hos_forward *hos_forward; 
108  ADOLC_ext_fct_iArr_hos_forward *hos_forward_iArr;
109  /**
110   * higher order vector forward for external functions  is currently not implemented in uni5_for.c
111   */
112  ADOLC_ext_fct_hov_forward *hov_forward;
113  ADOLC_ext_fct_iArr_hov_forward *hov_forward_iArr;
114  /**
115   * this points to a  method computing the projection dp_Z=transpose(dp_U) * Jacobian
116   * see also the explanation of the dp_U/Z  members below.
117   */
118  ADOLC_ext_fct_fos_reverse *fos_reverse; 
119  ADOLC_ext_fct_iArr_fos_reverse *fos_reverse_iArr;
120  /**
121   * this points to a  method computing the projection dpp_Z=transpose(dpp_U) * Jacobian
122   * see also the explanation of the dpp_U/Z  members below.
123   */
124  ADOLC_ext_fct_fov_reverse *fov_reverse; 
125  ADOLC_ext_fct_iArr_fov_reverse *fov_reverse_iArr;
126  /**
127   * higher order scalar reverse for external functions  is currently not implemented in ho_rev.c
128   */
129  ADOLC_ext_fct_hos_reverse *hos_reverse; 
130  ADOLC_ext_fct_iArr_hos_reverse *hos_reverse_iArr;
131  /**
132   * higher order vector reverse for external functions  is currently not implemented in ho_rev.c
133   */
134  ADOLC_ext_fct_hov_reverse *hov_reverse; 
135  ADOLC_ext_fct_iArr_hov_reverse *hov_reverse_iArr;
136
137
138  /**
139   * The names of the variables below correspond to the formal parameters names in the call back
140   * functions above;
141   */
142       
143  /**
144   * function and all _forward calls: function argument, dimension [n]
145   */ 
146  double *dp_x;     
147
148  /**
149   * fos_forward: tangent direction, dimension [n]
150   */ 
151  double *dp_X;   
152
153  /**
154   * fov_forward: seed matrix for p directions, dimensions [n][p]
155   * hos_forward: argument Taylor polynomial coefficients up to order d. dimensions [n][d]
156   */
157  double **dpp_X;
158 
159  /**
160   * hov_forward: argument Taylor polynomial coefficients up to order d in p directions. dimensions [n][p][d]
161   */
162  double ***dppp_X; 
163
164  /**
165   * function and all _forward calls: function result, dimension [m]
166   */
167  double *dp_y;   
168
169  /**
170   * fos_forward: Jacobian projection, dimension [m]
171   */
172  double *dp_Y; 
173
174  /**
175   * fov_forward: Jacobian projection in p directions, dimension [m][p]
176   * hos_forward: result Taylor polynomial coefficients up to order d. dimensions [m][d]
177   */
178  double **dpp_Y;     
179
180  /**
181   * hov_forward: result Taylor polynomial coefficients up to order d in p directions. dimensions [m][p][d]
182   */
183  double ***dppp_Y;
184
185  /**
186   * fos_reverse and hos_reverse:  weight vector, dimension [m]
187   */
188  double *dp_U;
189 
190  /**
191   * fov_reverse and hov_reverse: p weight vectors, dimensions [p][m]
192   */
193  double **dpp_U;       
194
195  /**
196   * fos_reverse: Jacobian projection, dimension [n]
197   */
198  double *dp_Z; 
199
200  /**
201   * fov_reverse: Jacobian projection for p weight vectors, dimensions [p][n]
202   * hos_reverse: adjoint Taylor polynomial coefficients up to order d, dimensions [n][d+1]
203   */
204  double **dpp_Z;   
205
206  /**
207   * hov_reverse:  adjoint Taylor polynomial coefficients up to order d for p weight vectors, dimension [p][n][d+1]
208   */
209  double ***dppp_Z; 
210
211  /**
212   * hov_reverse: non-zero pattern of dppp_Z, dimension [p][n], see also the hov_reverse ADOL-C driver
213   */
214  short **spp_nz;
215
216  /**
217   * track maximal value of n when function is invoked
218   */
219  locint max_n;
220
221  /**
222   * track maximal value of m when function is invoked
223   */
224  locint max_m;
225
226  /**
227   * make the call such that Adol-C may be used inside
228   * of the externally differentiated function;
229   * defaults to non-0;
230   * this implies certain storage duplication that can
231   * be avoided if no nested use of Adol-C takes place
232   */
233  char nestedAdolc;
234
235  /**
236   * if 0, then the 'function' does not change dp_x;
237   * defaults to non-0 which implies dp_x values are saved in taylors
238   */
239  char dp_x_changes;
240
241  /**
242   * if 0, then the value of dp_y prior to calling 'function'
243   * is not required for reverse;
244   * defaults to non-0 which implies  dp_y values are saved in taylors
245   */
246  char dp_y_priorRequired;
247
248  /**
249   * This is an all-memory pointer for allocating and deallocating
250   * all other pointers can point to memory within here.
251   */
252  char* allmem;
253
254  /**
255   * This is a reference to an object for the C++ object-oriented
256   * implementation of the external function ** do not touch **
257   */
258  void* obj;
259
260  /**
261   * This flag indicates that user allocates memory and internally no
262   * memory should be allocated
263   */
264  char user_allocated_mem;
265}
266ext_diff_fct;
267
268END_C_DECLS
269
270#include <adolc/externfcts2.h>
271
272#if defined(__cplusplus)
273/****************************************************************************/
274/*                                                          This is all C++ */
275
276ADOLC_DLL_EXPORT ext_diff_fct *reg_ext_fct(ADOLC_ext_fct ext_fct);
277ADOLC_DLL_EXPORT ext_diff_fct *reg_ext_fct(ADOLC_ext_fct_iArr ext_fct);
278
279ADOLC_DLL_EXPORT int call_ext_fct (ext_diff_fct *edfct,
280                                   int n, adouble *xa,
281                                   int m, adouble *ya);
282ADOLC_DLL_EXPORT int call_ext_fct (ext_diff_fct *edfct,
283                                   int iArrLength, int* iArr,
284                                   int n, adouble *xa,
285                                   int m, adouble *ya);
286
287/**
288 * zeros out the edf pointers and sets bools to defaults
289 */
290ADOLC_DLL_EXPORT void edf_zero(ext_diff_fct *edfct);
291
292#include <adolc/edfclasses.h>
293
294#endif /* __CPLUSPLUS */
295
296/****************************************************************************/
297#endif /* ADOLC_EXTERNFCTS_H */
298
Note: See TracBrowser for help on using the repository browser.