Changeset 341


Ignore:
Timestamp:
Aug 16, 2012 12:42:17 PM (7 years ago)
Author:
utke
Message:

put comments (doxygen style) to explain the use of the pointers

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/ADOL-C/src/externfcts.h

    r290 r341  
    2424typedef int (*ADOLC_ext_fct) (int n, double *x, int m, double *y);
    2525
    26 /* A variable of this type is created by reg_ext_fct and a pointer to it is
    27  * returned. Please do not create a variable of this type yourself. The index
    28  * is likely to be wrong in this case. Use pointers instead. */
     26/**
     27 * A variable of this type has to be instantiated by reg_ext_fct (see below) and a pointer to it is
     28 * returned. Within reg_ext_fct the memberse function and index are properly set.
     29 * is likely to be wrong in this case. Use pointers instead.
     30 */
    2931typedef struct {
    30     ADOLC_ext_fct function;
    31 
    32     int (*zos_forward) (int n, double *dp_x,
    33                         int m, double *dp_y);
    34     int (*fos_forward) (int n, double *dp_x, double *dp_X,
    35                         int m, double *dp_y, double *dp_Y);
    36     int (*fov_forward) (int n, double *dp_x, int p, double **dpp_X,
    37                         int m, double *dp_y, double **dpp_Y);
    38     int (*hos_forward) (int n, double *dp_x, int d, double **dpp_X,
    39                         int m, double *dp_y, double **dpp_Y);
    40     int (*hov_forward) (int n, double *dp_x, int d, int p, double ***dppp_X,
    41                         int m, double *dp_y, double ***dppp_Y);
    42 
    43     int (*fos_reverse) (int m, double *dp_U,
    44                         int n, double *dp_Z);
    45     int (*fov_reverse) (int m, int p, double **dpp_U,
    46                         int n, double **dpp_Z);
    47     int (*hos_reverse) (int m, double *dp_U,
    48                         int n, int d, double **dpp_Z);
    49     int (*hov_reverse) (int m, int p, double **dpp_U,
    50                         int n, int d, double ***dppp_Z,
    51                         short **spp_nz);
    52 
    53     /* This variables must be set before calling the functions above. */
    54     double *dp_x;                /* x[n], x0[n]        - forward mode */
    55     double *dp_X;                /* x1[n]              - forward mode */
    56     double **dpp_X;              /* X[n][p], X[n][d]   - forward mode */
    57     double ***dppp_X;            /* X[n][p][d]         - forward mode */
    58     double *dp_y;                /* y[n], y0[n]        - forward mode */
    59     double *dp_Y;                /* y1[n]              - forward mode */
    60     double **dpp_Y;              /* Y[m][p], Y[m][d]   - forward mode */
    61     double ***dppp_Y;            /* Y[m][p][d]         - forward mode */
    62 
    63     double *dp_U;                /* u[m]               - reverse mode */
    64     double **dpp_U;              /* U[q][m]            - reverse mode */
    65     double *dp_Z;                /* z[n]               - reverse mode */
    66     double **dpp_Z;              /* Z[q][n], Z[n][d+1] - reverse mode */
    67     double ***dppp_Z;            /* Z[q][n][d+1]       - reverse mode */
    68 
    69     short **spp_nz;              /* nz[q][n]           - reverse mode */
    70 
    71     locint index;                      /* please do not change */
     32
     33  /**
     34   * DO NOT touch - the function pointer is set through reg_ext_fct
     35   */
     36  ADOLC_ext_fct function; 
     37
     38  /**
     39   * DO NOT touch - the index is set through reg_ext_fct
     40   */
     41  locint index;           
     42
     43  /**
     44   * below are function pointers used for call back from the corresponding ADOL-C trace interpreters;
     45   * these function pointers are initialized to 0 by reg_ext_fct;
     46   * the  user needs to set eplicitly the function pointers for the trace interpreters called in the
     47   * application driver
     48   */
     49
     50  /**
     51   * this points to a  method implementing a forward execution of the externally differentiated function dp_y=f(dp_x);
     52   * the pointer would typically be set to the same function pointer supplied in the call to reg_ext_fct,
     53   * i.e. zos_forward would be equal to function (above)
     54   * but there are cases when it makes sense for this to be different as illustrated
     55   * in examples/additional_examples/ext_diff_func/ext_diff_func.cpp 
     56   */
     57  int (*zos_forward) (int n, double *dp_x,
     58                      int m, double *dp_y);
     59
     60  /**
     61   * this points to a  method implementing a forward execution of the externally differentiated function dp_y=f(dp_x)
     62   * and computing the projection dp_Y=Jacobian*dp_x
     63   * see also the explanation of the dp_X/Y  members below.
     64   */
     65  int (*fos_forward) (int n, double *dp_x, double *dp_X,
     66                      int m, double *dp_y, double *dp_Y);
     67  /**
     68   * this points to a  method implementing a forward execution of the externally differentiated function dp_y=f(dp_x)
     69   * and computing the projection dpp_Y=Jacobian*dpp_x
     70   * see also the explanation of the dpp_X/Y  members below.
     71   */
     72  int (*fov_forward) (int n, double *dp_x, int p, double **dpp_X,
     73                      int m, double *dp_y, double **dpp_Y);
     74  /**
     75   * higher order scalar forward for external functions  is currently not implemented in uni5_for.c
     76   */
     77  int (*hos_forward) (int n, double *dp_x, int d, double **dpp_X,
     78                      int m, double *dp_y, double **dpp_Y);
     79  /**
     80   * higher order vector forward for external functions  is currently not implemented in uni5_for.c
     81   */
     82  int (*hov_forward) (int n, double *dp_x, int d, int p, double ***dppp_X,
     83                      int m, double *dp_y, double ***dppp_Y);
     84
     85  /**
     86   * this points to a  method computing the projection dp_Z=transpose(dp_U) * Jacobian
     87   * see also the explanation of the dp_U/Z  members below.
     88   */
     89  int (*fos_reverse) (int m, double *dp_U,
     90                      int n, double *dp_Z);
     91
     92  /**
     93   * this points to a  method computing the projection dpp_Z=transpose(dpp_U) * Jacobian
     94   * see also the explanation of the dpp_U/Z  members below.
     95   */
     96  int (*fov_reverse) (int m, int p, double **dpp_U,
     97                      int n, double **dpp_Z);
     98
     99  /**
     100   * higher order scalar reverse for external functions  is currently not implemented in ho_rev.c
     101   */
     102  int (*hos_reverse) (int m, double *dp_U,
     103                      int n, int d, double **dpp_Z);
     104  /**
     105   * higher order vector reverse for external functions  is currently not implemented in ho_rev.c
     106   */
     107  int (*hov_reverse) (int m, int p, double **dpp_U,
     108                      int n, int d, double ***dppp_Z,
     109                      short **spp_nz);
     110
     111
     112  /**
     113   * The names of the variables below correspond to the formal parameters names in the call back
     114   * functions above;
     115   * The user has to preallocate the variables and set the pointers for any of the call back functions
     116   * that will be called during trace interpretation.
     117   * The dimensions given below correspond to the formal arguments in the call back funtions signatures above.
     118   * If the dimensions n and m change between multiple calls to the same external function, then the variables
     119   * have to be preallocation with the maximum of the respective dimension values.
     120   * The dp_x and dp_y pointers have to be valid during both, the tracing phase and the trace interpretation;
     121   * all the other pointers are required to be valid only for the trace interpretation.
     122   */
     123       
     124  /**
     125   * function and all _forward calls: function argument, dimension [n]
     126   */
     127  double *dp_x;     
     128
     129  /**
     130   * fos_forward: tangent direction, dimension [n]
     131   */
     132  double *dp_X;   
     133
     134  /**
     135   * fov_forward: seed matrix for p directions, dimensions [n][p]
     136   * hos_forward: argument Taylor polynomial coefficients up to order d. dimensions [n][d]
     137   */
     138  double **dpp_X;
     139 
     140  /**
     141   * hov_forward: argument Taylor polynomial coefficients up to order d in p directions. dimensions [n][p][d]
     142   */
     143  double ***dppp_X;
     144
     145  /**
     146   * function and all _forward calls: function result, dimension [m]
     147   */
     148  double *dp_y;   
     149
     150  /**
     151   * fos_forward: Jacobian projection, dimension [m]
     152   */
     153  double *dp_Y; 
     154
     155  /**
     156   * fov_forward: Jacobian projection in p directions, dimension [m][p]
     157   * hos_forward: result Taylor polynomial coefficients up to order d. dimensions [m][d]
     158   */
     159  double **dpp_Y;     
     160
     161  /**
     162   * hov_forward: result Taylor polynomial coefficients up to order d in p directions. dimensions [m][p][d]
     163   */
     164  double ***dppp_Y;
     165
     166  /**
     167   * fos_reverse and hos_reverse:  weight vector, dimension [m]
     168   */
     169  double *dp_U;
     170 
     171  /**
     172   * fov_reverse and hov_reverse: p weight vectors, dimensions [p][m]
     173   */
     174  double **dpp_U;       
     175
     176  /**
     177   * fos_reverse: Jacobian projection, dimension [n]
     178   */
     179  double *dp_Z;
     180
     181  /**
     182   * fov_reverse: Jacobian projection for p weight vectors, dimensions [p][n]
     183   * hos_reverse: adjoint Taylor polynomial coefficients up to order d, dimensions [n][d+1]
     184   */
     185  double **dpp_Z;   
     186
     187  /**
     188   * hov_reverse:  adjoint Taylor polynomial coefficients up to order d for p weight vectors, dimension [p][n][d+1]
     189   */
     190  double ***dppp_Z;
     191
     192  /**
     193   * hov_reverse: non-zero pattern of dppp_Z, dimension [p][n], see also the hov_reverse ADOL-C driver
     194   */
     195  short **spp_nz;
     196
    72197}
    73198ext_diff_fct;
Note: See TracChangeset for help on using the changeset viewer.