Changeset 339 for trunk


Ignore:
Timestamp:
Aug 15, 2012 11:43:21 PM (8 years ago)
Author:
utke
Message:

various typos (advance -> advanced) , and rephrased the section on differetiating external functions trying to clarify things

Location:
trunk/ADOL-C/doc
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/ADOL-C/doc/adolc-manual.tex

    r320 r339  
    25942594%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    25952595%
    2596 \section{Advance algorithmic differentiation in ADOL-C}
     2596\section{Advanced algorithmic differentiation in ADOL-C}
    25972597\label{adv_ad}
    25982598%
    2599 \subsection{External differentiated functions}
    2600 %
    2601 Ideally, AD is applied to a given function as a whole.
     2599\subsection{Differentiating external functions}
     2600%
     2601Ideally, AD is applied to a given computation as a whole.
     2602This is not always possible because parts of the computation may
     2603be coded in a different programming language or may a call to
     2604an external library.
     2605In the former case one may want to differentiate the parts in
     2606question with a different AD tool or provide hand written derivatives.
     2607To integrate these
    26022608In practice, however, sophisticated projects usually evolve over a long period of time.
    26032609Within this process, a heterogeneous code base for the project
     
    26072613Hence, different \mbox{AD-tools} may be combined with hand-derived
    26082614codes based on the same or different programming languages.
    2609 ADOL-C support such settings  by the concept of external
    2610 differentiated functions. Hence, a external differentiated function
    2611 itself is not differentiated by ADOL-C. The required derivative
    2612 information have to be provided by the user.
    2613 
    2614 For this purpose, it is assumed that the external differentiated
    2615 function has the signature
     2615ADOL-C supports such settings  by  the concept of externally
     2616differentiated functions, that is, a function
     2617not differentiated by ADOL-C itself. The required derivatives
     2618have to be provided by the user.
     2619
     2620For this purpose, it is required that the externally differentiated
     2621function (for example named {\sf\em euler\_step} ) has the following signature.
    26162622\smallskip
    26172623
    26182624\noindent
    2619 \hspace*{2cm}{\sf int ext\_func(int n, double *yin, int m, double  *yout);}
     2625\hspace*{2cm}{\sf int euler\_step(int n, double *x, int m, double *y);}
    26202626\medskip
    26212627
    26222628\noindent
    2623 where the function names can be chosen by the user as long as the names are
    2624 unique. This {\sf double} version of the external differentiated function has to
    2625 be {\em registered} using the \mbox{ADOL-C} function
     2629Note that the formal paraemters in the signature have {\sf double} type, that is,
     2630they are not active as in the original program before the ADOL-C type change.
     2631The externally differentiated function has to
     2632be {\em registered}\footnote{we record the function pointer} using an \mbox{ADOL-C} method as follows.
    26262633\smallskip
    26272634
    26282635\noindent
    2629 \hspace*{2cm}{\sf edf = reg\_ext\_fct(ext\_func);}.
     2636\hspace*{2cm}{\sf ext\_diff\_fct *edf = reg\_ext\_fct(euler\_step);}.
    26302637\smallskip
    26312638
    26322639\noindent
    2633 This function initializes the structure {\sf edf}. Then,
    2634 the user has to provide the remaining  information
    2635 by the following commands:
    2636 \begin{tabbing}
    2637 \hspace*{2cm}\= {\sf edf-$>$zos\_forward = zos\_for\_ext\_func;}\\
     2640This returns a pointer to an {\sf ext\_diff\_fct} instance specific to the registered function.
     2641Then, the user has to supply the function pointers for the call back methods (for example here
     2642{\sf zos\_for\_euler\_step} and {\sf  fos\_rev\_euler\_step}) the user implemented
     2643to compute the derivatives as follows.
     2644\begin{tabbing}
     2645\hspace*{2cm}\= {\sf edf-$>$zos\_forward = {\em zos\_for\_euler\_step};}\\
    26382646             \> {\sf // function pointer for computing
    26392647               Zero-Order-Scalar (=zos)}\\
    26402648             \> {\sf // forward information}\\
    2641              \> {\sf edf-$>$dp\_x = xp;}\\
    2642              \> {\sf edf-$>$dp\_y = yp;}\\
    2643              \> {\sf // double arrays for arguments and results}\\
    2644              \> {\sf edf-$>$fos\_reverse = fos\_rev\_ext\_func;} \\
     2649%             \> {\sf edf-$>$dp\_x = xp;}\\
     2650%             \> {\sf edf-$>$dp\_y = yp;}\\
     2651%             \> {\sf // double arrays for arguments and results}\\
     2652             \> {\sf edf-$>$fos\_reverse = fos\_rev\_euler\_step;} \\
    26452653             \> {\sf // function pointer for computing
    26462654               First-Order-Scalar (=fos)}\\
    26472655             \> {\sf reverse information}
    26482656\end{tabbing}
    2649 Subsequently, the call to the external differentiated function  in the function evaluation can be
    2650 substituted by the call of
     2657To facilitate the switch between active and passive versions of the parameters {\sf x} and {\sf y}
     2658one has to provide (allocate) both variants. I.e. if the call to {\sf euler\_step} was originally
     2659\noindent
     2660\hspace*{2cm}{\sf rc=euler\_step(n, sOld, m, sNew);}
    26512661\medskip
     2662then the ADOL-C typechange for the calling context will turn  {\sf sOld} and {\sf sNew} in {\sf adouble} pointers.
     2663To trigger the appropriate action for the derivative computation (i.e. creating an external differentiation entry on the trace)
     2664the original call to the externally differentiated function
     2665must be substituted by
     2666\medskip
    26522667
    26532668\noindent
    2654 \hspace*{2cm}{\sf int call\_ext\_fct(edf, n, xp, x, m, yp, y);}
     2669\hspace*{2cm}{\sf rc=call\_ext\_fct(edf, n, sOldPassive, sOld, m, sNewPassive, sNew);}
    26552670\medskip
    26562671
    26572672\noindent
     2673Here, {\sf sOldPassive} and {\sf sNewPassive} are the passive counterparts ({\sf double} pointers allocated to length {\sf n} and {\sf m}, respectively) 
     2674to the active arguments {\sf sNew} in {\sf adouble}.
    26582675The usage of the external function facility is illustrated by the
    26592676example \verb=ext_diff_func= contained in
    26602677\verb=examples/additional_examples/ext_diff_func=.
    2661 Here,the external differentiated function is also a C code, but the
     2678There,the external differentiated function is also a C code, but the
    26622679handling as external differentiated functions also a decrease of the
    26632680overall required tape size.
    26642681
    26652682%
    2666 \subsection{Advance algorithmic differentiation of time integration processes}
     2683\subsection{Advanced algorithmic differentiation of time integration processes}
    26672684%
    26682685For many time-dependent applications, the corresponding simulations
     
    28002817%
    28012818%
    2802 \subsection{Advance algorithmic differentiation of fixed point iterations}
     2819\subsection{Advanced algorithmic differentiation of fixed point iterations}
    28032820%
    28042821Quite often, the state of the considered system denoted by $x\in\R^n$
     
    28972914expected signature of the function pointers is contained in the directory \verb=examples/additional_examples/fixpoint_exam=.
    28982915%
    2899 \subsection{Advance algorithmic differentiation of OpenMP parallel programs}
     2916\subsection{Advanced algorithmic differentiation of OpenMP parallel programs}
    29002917%
    29012918ADOL-C allows to compute derivatives in parallel for functions
Note: See TracChangeset for help on using the changeset viewer.