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

Last change on this file since 407 was 370, checked in by kulshres, 7 years ago

Merge branch '2.3.x_ISSM' into svn

This introduces the new externally differentiated functions API

From: Jean Utke <utke@…>

Please see comments in ADOL-C/include/adolc/externfcts.h for details

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

  • Property svn:keywords set to Author Date Id Revision
File size: 8.5 KB
Line 
1/*----------------------------------------------------------------------------
2 ADOL-C -- Automatic Differentiation by Overloading in C++
3 File:     externfcts.h
4 Revision: $Id: externfcts.h 370 2012-11-22 13:18:52Z kulshres $
5 Contents: public functions and data types for extern (differentiated)
6           functions.
7 
8 Copyright (c) Andreas Kowarz
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/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/**
36 * A variable of this type has to be instantiated by reg_ext_fct (see below) and a pointer to it is
37 * returned. Within reg_ext_fct the memberse function and index are properly set.
38 * is likely to be wrong in this case. Use pointers instead.
39 */
40typedef struct {
41
42  /**
43   * DO NOT touch - the function pointer is set through reg_ext_fct
44   */
45  ADOLC_ext_fct *function; 
46
47  /**
48   * DO NOT touch - the index is set through reg_ext_fct
49   */
50  locint index;           
51
52  /**
53   * below are function pointers used for call back from the corresponding ADOL-C trace interpreters;
54   * these function pointers are initialized to 0 by reg_ext_fct;
55   * the  user needs to set eplicitly the function pointers for the trace interpreters called in the
56   * application driver
57   */
58
59  /**
60   * this points to a  method implementing a forward execution of the externally differentiated function dp_y=f(dp_x);
61   * the pointer would typically be set to the same function pointer supplied in the call to reg_ext_fct,
62   * i.e. zos_forward would be equal to function (above)
63   * but there are cases when it makes sense for this to be different as illustrated
64   * in examples/additional_examples/ext_diff_func/ext_diff_func.cpp 
65   */
66  ADOLC_ext_fct *zos_forward;
67
68  /**
69   * this points to a  method implementing a forward execution of the externally differentiated function dp_y=f(dp_x)
70   * and computing the projection dp_Y=Jacobian*dp_x
71   * see also the explanation of the dp_X/Y  members below.
72   */
73  ADOLC_ext_fct_fos_forward *fos_forward;
74
75  /**
76   * this points to a  method implementing a forward execution of the externally differentiated function dp_y=f(dp_x)
77   * and computing the projection dpp_Y=Jacobian*dpp_x
78   * see also the explanation of the dpp_X/Y  members below.
79   */
80  ADOLC_ext_fct_fov_forward *fov_forward;
81  /**
82   * higher order scalar forward for external functions  is currently not implemented in uni5_for.c
83   */
84  ADOLC_ext_fct_hos_forward *hos_forward; 
85  /**
86   * higher order vector forward for external functions  is currently not implemented in uni5_for.c
87   */
88  ADOLC_ext_fct_hov_forward *hov_forward;
89  /**
90   * this points to a  method computing the projection dp_Z=transpose(dp_U) * Jacobian
91   * see also the explanation of the dp_U/Z  members below.
92   */
93  ADOLC_ext_fct_fos_reverse *fos_reverse; 
94  /**
95   * this points to a  method computing the projection dpp_Z=transpose(dpp_U) * Jacobian
96   * see also the explanation of the dpp_U/Z  members below.
97   */
98  ADOLC_ext_fct_fov_reverse *fov_reverse; 
99  /**
100   * higher order scalar reverse for external functions  is currently not implemented in ho_rev.c
101   */
102  ADOLC_ext_fct_hos_reverse *hos_reverse; 
103  /**
104   * higher order vector reverse for external functions  is currently not implemented in ho_rev.c
105   */
106  ADOLC_ext_fct_hov_reverse *hov_reverse; 
107
108
109  /**
110   * The names of the variables below correspond to the formal parameters names in the call back
111   * functions above;
112   * The user has to preallocate the variables and set the pointers for any of the call back functions
113   * that will be called during trace interpretation.
114   * The dimensions given below correspond to the formal arguments in the call back funtions signatures above.
115   * If the dimensions n and m change between multiple calls to the same external function, then the variables
116   * have to be preallocation with the maximum of the respective dimension values.
117   * The dp_x and dp_y pointers have to be valid during both, the tracing phase and the trace interpretation;
118   * all the other pointers are required to be valid only for the trace interpretation.
119   */
120       
121  /**
122   * function and all _forward calls: function argument, dimension [n]
123   */ 
124  double *dp_x;     
125
126  /**
127   * fos_forward: tangent direction, dimension [n]
128   */ 
129  double *dp_X;   
130
131  /**
132   * fov_forward: seed matrix for p directions, dimensions [n][p]
133   * hos_forward: argument Taylor polynomial coefficients up to order d. dimensions [n][d]
134   */
135  double **dpp_X;
136 
137  /**
138   * hov_forward: argument Taylor polynomial coefficients up to order d in p directions. dimensions [n][p][d]
139   */
140  double ***dppp_X; 
141
142  /**
143   * function and all _forward calls: function result, dimension [m]
144   */
145  double *dp_y;   
146
147  /**
148   * fos_forward: Jacobian projection, dimension [m]
149   */
150  double *dp_Y; 
151
152  /**
153   * fov_forward: Jacobian projection in p directions, dimension [m][p]
154   * hos_forward: result Taylor polynomial coefficients up to order d. dimensions [m][d]
155   */
156  double **dpp_Y;     
157
158  /**
159   * hov_forward: result Taylor polynomial coefficients up to order d in p directions. dimensions [m][p][d]
160   */
161  double ***dppp_Y;
162
163  /**
164   * fos_reverse and hos_reverse:  weight vector, dimension [m]
165   */
166  double *dp_U;
167 
168  /**
169   * fov_reverse and hov_reverse: p weight vectors, dimensions [p][m]
170   */
171  double **dpp_U;       
172
173  /**
174   * fos_reverse: Jacobian projection, dimension [n]
175   */
176  double *dp_Z; 
177
178  /**
179   * fov_reverse: Jacobian projection for p weight vectors, dimensions [p][n]
180   * hos_reverse: adjoint Taylor polynomial coefficients up to order d, dimensions [n][d+1]
181   */
182  double **dpp_Z;   
183
184  /**
185   * hov_reverse:  adjoint Taylor polynomial coefficients up to order d for p weight vectors, dimension [p][n][d+1]
186   */
187  double ***dppp_Z; 
188
189  /**
190   * hov_reverse: non-zero pattern of dppp_Z, dimension [p][n], see also the hov_reverse ADOL-C driver
191   */
192  short **spp_nz;
193
194  /**
195   * track maximal value of n when function is invoked
196   */
197  int max_n;
198
199  /**
200   * track maximal value of m when function is invoked
201   */
202  int max_m;
203
204  /**
205   * make the call such that Adol-C may be used inside
206   * of the externally differentiated function;
207   * defaults to non-0;
208   * this implies certain storage duplication that can
209   * be avoided if no nested use of Adol-C takes place
210   */
211  char nestedAdolc;
212
213  /**
214   * if 0, then the 'function' does not change dp_x;
215   * defaults to non-0 which implies dp_x values are saved in taylors
216   */
217  char dp_x_changes;
218
219  /**
220   * if 0, then the value of dp_y prior to calling 'function'
221   * is not required for reverse;
222   * defaults to non-0 which implies  dp_y values are saved in taylors
223   */
224  char dp_y_priorRequired;
225
226}
227ext_diff_fct;
228
229END_C_DECLS
230
231#if defined(__cplusplus)
232/****************************************************************************/
233/*                                                          This is all C++ */
234
235ADOLC_DLL_EXPORT ext_diff_fct *reg_ext_fct(ADOLC_ext_fct ext_fct);
236
237ADOLC_DLL_EXPORT int call_ext_fct (ext_diff_fct *edfct,
238                                   int n, double *xp, adouble *xa,
239                                   int m, double *yp, adouble *ya);
240
241#endif /* __CPLUSPLUS */
242
243/****************************************************************************/
244#endif /* ADOLC_EXTERNFCTS_H */
245
Note: See TracBrowser for help on using the repository browser.