Changeset 109


Ignore:
Timestamp:
Jul 13, 2010 5:25:29 AM (9 years ago)
Author:
kulshres
Message:

Squashed merge of branch 'master' of 'gitclone' into svn

  • 'master' of 'gitclone': (5 commits) document the tape directory specification too allow to change the directory where tapes are written too. bring documentation of usrparms.h up to par allow compilation with pdflatex as well as latex Add hyperlinks in the manual pdf file

Details of the commits:

commit e7066ed0e6c85acd69e14ecbb736a4a5b1a105f8
Author: Kshitij Kulshreshtha <kshitij@…>
Date: Tue Jul 13 11:14:22 2010 +0200

document the tape directory specification too

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

commit 5405a01ec41b48c6dd25cde772913fbe9d717421
Author: Kshitij Kulshreshtha <kshitij@…>
Date: Fri Jul 9 10:38:33 2010 +0200

allow to change the directory where tapes are written too.

this can be done for now in dvlparms.h before compiling adolc.

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

commit d82f1eb1aa9dde55811ec1b978b2d6360b71d140
Author: Kshitij Kulshreshtha <kshitij@…>
Date: Thu Jul 8 16:40:37 2010 +0200

bring documentation of usrparms.h up to par

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

commit 28c9cf190fa165c80b19af3c38b409e05cffb9b6
Author: Kshitij Kulshreshtha <kshitij@…>
Date: Wed Jul 7 16:08:18 2010 +0200

allow compilation with pdflatex as well as latex

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

commit 0e5d6bfcc3b5bae3d34b8ac99e29f18675fa8b1a
Author: Kshitij Kulshreshtha <kshitij@…>
Date: Wed Jul 7 15:43:24 2010 +0200

Add hyperlinks in the manual pdf file

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

Location:
trunk/ADOL-C
Files:
3 added
9 edited

Legend:

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

    r106 r109  
    1212\usepackage{hyperref}
    1313\usepackage{amsmath,amsthm,amssymb}
    14 \usepackage{epsfig}
    15 
    16 \usepackage[dvips]{color}
     14\usepackage{graphicx}
     15
     16\usepackage{color}
    1717
    1818\pagestyle{headings}
     
    3030\newcommand{\R}{{ {\rm I} \kern -.225em {\rm R} }}
    3131\newcommand{\T}{{ {\rm I} \kern -.425em {\rm T} }}
     32
     33\renewcommand{\sectionautorefname}{Section}
     34\renewcommand{\subsectionautorefname}{Section}
     35\renewcommand{\figureautorefname}{Figure}
     36\renewcommand{\tableautorefname}{Table}
     37
    3238\setcounter{equation}{0}
    3339
     
    129135modifications required to convert undifferentiated code to code that
    130136compiles with ADOL-C.
    131 Section \ref{tape} covers aspects of the tape of recorded data that ADOL-C uses to
     137\autoref{tape} covers aspects of the tape of recorded data that ADOL-C uses to
    132138evaluate arbitrarily high order derivatives. The discussion includes storage
    133139requirements and the tailoring of certain tape characteristics to fit specific
    134140user needs. Descriptions of easy-to-use drivers for a  convenient derivative
    135 evaluation are contained in Section \ref{drivers}.
    136  Section \ref{forw_rev_ad} offers a more mathematical characterization of
     141evaluation are contained in \autoref{drivers}.
     142\autoref{forw_rev_ad} offers a more mathematical characterization of
    137143the different modes of AD to compute derivatives. At the same time, the
    138144corresponding drivers of ADOL-C are explained. 
    139145The overloaded derivative evaluation routines using the forward and the reverse
    140 mode of AD are explained in Section \ref{forw_rev}.
     146mode of AD are explained in \autoref{forw_rev}.
    141147Advanced differentiation techniques as the optimal checkpointing for
    142148time integrations, the exploitation of fixed point iterations, the usages
    143149of external differentiated functions and the differentiation of OpenMP
    144 parallel programs are described in Section \ref{adv_ad}.
    145 The tapeless forward mode is presented in Section~\ref{tapeless}.
    146 Section \ref{install} details the installation and
    147 use of the ADOL-C package. Finally, Section \ref{example}
     150parallel programs are described in \autoref{adv_ad}.
     151The tapeless forward mode is presented in \autoref{tapeless}.
     152\autoref{install} details the installation and
     153use of the ADOL-C package. Finally, \autoref{example}
    148154furnishes some example programs that incorporate the ADOL-C package to
    149155evaluate first and higher-order
     
    211217Unless several tapes need to be kept, ${\sf tag} =0$ may be used throughout.
    212218The optional integer arguments {\sf keep} and
    213 {\sf file} will be discussed in Section \ref{tape}. We will refer to the
     219{\sf file} will be discussed in \autoref{tape}. We will refer to the
    214220sequence of statements executed between a particular call to
    215221{\sf trace\_on} and the following call to {\sf trace\_off} as an
     
    275281%
    276282As a generic example let us consider a C(++) function of the form
    277 shown in Figure \ref{code1}.
     283shown in \autoref{code1}.
    278284%
    279285\begin{figure}[hbt]
     
    308314{\sf adouble}. Subsequently, the subprogram must be compiled with the
    309315header file \verb=<adolc/adouble.h>= included as described
    310 in Section \ref{DecActVar}. Now let us consider the situation when {\sf eval} is
     316in \autoref{DecActVar}. Now let us consider the situation when {\sf eval} is
    311317still to be called with integer and real arguments, possibly from
    312318a program written in Fortran77, which  does not allow overloading.
     
    316322can make the body of the function into an active section. For
    317323example, we may modify the previous program segment
    318 as in Figure \ref{adolcexam}.
     324as in \autoref{adolcexam}.
    319325The renaming and doubling up of the original independent and dependent
    320326variable vectors by active counterparts may seem at first a bit clumsy.
     
    325331the code would not compile, because of a type conflict in the assignment
    326332following the declaration. More detailed example codes are listed in
    327 Section \ref{example}.
     333\autoref{example}.
    328334
    329335\begin{figure}[htb]
     
    358364\end{tabbing}
    359365\end{center}}}
    360 \caption{Activated version of the code listed in Figure~\ref{code1}}
     366\caption{Activated version of the code listed in \autoref{code1}}
    361367\label{adolcexam}
    362368\end{figure}
     
    431437either {\sf $\pm$InfVal}, 0
    432438or {\sf NoNum}, where {\sf InfVal} and {\sf NoNum} are user-defined
    433 parameters, see Section \ref{Customizing}.
     439parameters, see \autoref{Customizing}.
    434440On IEEE machines {\sf InfVal} can be set to the special value
    435441{\sf Inf}~=~$1.0/0.0$ and {\sf NoNum} to {\sf NaN}~=~$0.0/0.0$.
     
    471477%
    472478% and also the
    473 %active subscripts described in the Section  \ref{act_subscr}.
     479%active subscripts described in the \autoref{act_subscr}.
    474480Ambiguous statements like {\sf a += a++;} must be
    475481avoided because the compiler may sequence the evaluation of the
     
    492498the mathematical definition of the special function. Currently this
    493499direct approach has been implemented only for user-supplied quadratures
    494 as described in Section \ref{quadrat}.
     500as described in \autoref{quadrat}.
    495501%
    496502%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
     
    517523the ADOL-C routine called for derivative calculations indicates this
    518524contingency through its return value. Currently, there are six return values,
    519 see Table \ref{retvalues}.
     525see \autoref{retvalues}.
    520526\begin{table}[h]
    521527\center\small
     
    572578
    573579\begin{figure}[h]
    574 \centering\epsfig{file=tap_point.eps,width=10.0cm}
     580\centering\includegraphics[width=10.0cm]{tap_point}
    575581\caption{Return values around the taping point}
    576582\label{fi:tap_point}
    577583\end{figure}         
    578584
    579 In Figure \ref{fi:tap_point} these return values are illustrated.
     585In \autoref{fi:tap_point} these return values are illustrated.
    580586If the user finds the return value of an ADOL-C routine to be negative the
    581587taping process simply has to be repeated by executing the active section again.
     
    637643run time value. Thus the original dependency of {\sf b} on
    638644active variables gets lost, for instance if {\sf b} is a comparison
    639 expression, see Section \ref{OverOper}.
     645expression, see \autoref{OverOper}.
    640646If there is no {\sf else} part in a conditional assignment, one may call
    641647the three argument version
     
    688694The trace generated by the execution of an active section may stay
    689695within a triplet of internal arrays or it may be written out
    690 to corresponding files. We will refer to these triplets as the
    691 tape array or tape file, which may subsequently be used to evaluate the
     696to three corresponding files. We will refer to these triplets as the
     697tape array or tape file, in general tape, which may subsequently be
     698used to evaluate the
    692699underlying function and its derivatives at the original point or at
    693700alternative arguments. If the active section involves user-defined
     
    697704a new argument the evaluation process also needs to be re-taped at the
    698705new point. Otherwise, direct evaluation from
    699 the tape by the routine {\sf function} (Section \ref{optdrivers}) is
     706the tape by the routine {\sf function} (\autoref{optdrivers}) is
    700707likely to be
    701708faster. The use of quadratures and the results of all comparisons on
     
    705712branches can be recorded on the tape through
    706713the use of conditional assignments 
    707 described before in Section \ref{condassign}.
    708 
    709 Several tape files may be generated and kept simultaneously.
    710 A tape array is used as a triplet of buffers for a tape file if
    711 the length of any of the buffers exceeds the array length of
    712 {\sf BUFSIZE}. This parameter is
     714described before in \autoref{condassign}.
     715
     716Several tapes may be generated and kept simultaneously.
     717A tape array is used as a triplet of buffers or a tape file is generated if
     718the length of any of the buffers exceeds the maximal array lengths of
     719{\sf OBUFSIZE}, {\sf VBUFSIZE} or {\sf LBUFSIZE}. These parameters are
    713720defined in the header file \verb=<adolc/usrparms.h>=
    714 and may be adjusted by the user.
     721and may be adjusted by the user in the header file before compiling
     722the ADOL-C library, or on runtime using a file named \verb=.adolcrc=.
     723
    715724For simple usage, {\sf trace\_on} may be called with only the tape
    716725{\sf tag} as argument, and {\sf trace\_off} may be called
    717 without argument.
    718 
    719 The optional integer argument {\sf keep} of
     726without argument. The optional integer argument {\sf keep} of
    720727{\sf trace\_on} determines whether the numerical values of all
    721 active variables are recorded in a buffered temporary file called value
    722 stack before they will be overwritten.
     728active variables are recorded in a buffered temporary array or file
     729called the taylor stack.
    723730This option takes effect if
    724731{\sf keep} = 1 and prepares the scene for an immediately following
    725732gradient evaluation by a call to a routine implementing the reverse mode
    726 as described in the Sections \ref{forw_rev_ad} and \ref{forw_rev}.
    727 The name of the temporary file
    728 is {\sf FNAME3} found in \verb=<adolc/dvlparms.h>=.
     733as described in the \autoref{forw_rev_ad} and \autoref{forw_rev}. A
     734file is used instead of an array if the size exceeds the maximal array
     735length of {\sf TBUFSIZE} defined in \verb=<adolc/usrparms.h>= and may
     736be adjusted in the same way like the other buffer sizes mentioned above.
    729737Alternatively, gradients may be evaluated by a call
    730738to {\sf gradient}, which includes a preparatory forward sweep
    731739for the creation of the temporary file. If omitted, the argument
    732740{\sf  keep} defaults to 0, so that no temporary
    733 value stack file is generated.
     741taylor stack file is generated.
    734742
    735743By setting the optional integer argument {\sf file} of
     
    738746If the argument {\sf file} is omitted, it
    739747defaults to 0, so that the tape array is written onto a tape file only
    740 if the length of any of the buffers exceeds {\sf BUFSIZE} elements.
     748if the length of any of the buffers exceeds {\sf [OLVT]BUFSIZE} elements.
    741749
    742750After the execution of an active section, if a tape file was generated, i.e.,
    743 if the length of some buffer exceeded {\sf BUFSIZE} elements or if the
     751if the length of some buffer exceeded {\sf [OLVT]BUFSIZE} elements or if the
    744752argument {\sf file} of {\sf trace\_off} was set to 1, the files will be
    745 saved in the current working directory under the names
    746 {\sf FNAME.}$<${\sf tag}$>$, {\sf FNAME1.}$<${\sf tag}$>$, and
    747 {\sf FNAME2.}$<${\sf tag}$>$,  where {\sf tag} is the mandatory argument
    748 to {\sf trace\_on} and {\sf FNAME}, {\sf FNAME1}, and {\sf FNAME2} are
    749 the tape file
    750 names found in \verb=<adolc/dvlparms.h>=. Later, all problem-independent routines
     753saved in the directory defined as {\sf ADOLC\_TAPE\_DIR} (by default
     754the current working directory) under filenames formed by
     755the strings {\sf ADOLC\_OPERATIONS\_NAME}, {\sf
     756  ADOLC\_LOCATIONS\_NAME}, {\sf ADOLC\_VALUES\_NAME} and {\sf
     757  ADOLC\_TAYLORS\_NAME} defined in
     758the header file \verb=<adolc/dvlparms.h>= appended with the number
     759given as the {\sf tag} argument to {\sf trace\_on} and have the
     760extension {\sf .tap}.
     761
     762 Later, all problem-independent routines
    751763like {\sf gradient}, {\sf jacobian}, {\sf forward}, {\sf reverse}, and others
    752764expect as first argument a {\sf tag} to determine
     
    833845
    834846\begin{description}
    835 \item[{\sf BUFSIZE}{\rm :}] This integer determines the length of
     847\item[{\sf OBUFSIZE}, {\sf LBUFSIZE}, {\sf VBUFSIZE}{\rm :}] These integer determines the length of
    836848in\-ter\-nal buf\-fers (default: 65$\,$536). If the buffers are large enough to accommodate all
    837849required data, any file access is avoided unless {\sf trace\_off}
    838850is called with a positive argument. This desirable situation can
    839851be achieved for many problem functions with an execution trace of moderate
    840 size. Primarily {\sf BUFSIZE} occurs as an argument
     852size. Primarily these values occur as an argument
    841853to {\sf malloc}, so that setting it unnecessarily large may have no
    842854ill effects, unless the operating system prohibits or penalizes large
     
    844856
    845857\item[{\sf TBUFSIZE}{\rm :}] This integer determines the length of the
    846 in\-ter\-nal buf\-fer for a value stack (default: 65$\,$536).
    847 
    848 \item[{\sf TBUFNUM}{\rm :}] This integer determines the maximal number of value stacks (default: 32).
     858in\-ter\-nal buf\-fer for a taylor stack (default: 65$\,$536).
     859
     860\item[{\sf TBUFNUM}{\rm :}] This integer determines the maximal number of taylor stacks (default: 32).
    849861
    850862\item[{\sf locint}{\rm :}] The range of the integer type
    851863{\sf locint} determines how many {\sf adouble}s can be simultaneously
    852 alive (default: {\sf unsigned short}).  In extreme cases when there are more than 65$\,$536 {\sf adouble}s
     864alive (default: {\sf unsigned int}).  In extreme cases when there are more than $2^{32}$ {\sf adouble}s
    853865alive at any one time, the type {\sf locint} must be changed to
    854 {\sf unsigned int} or {\sf unsigned long}.
     866 {\sf unsigned long}.
    855867
    856868\item[{\sf revreal}{\rm :}] The choice of this floating-point type
     
    10131025of unnecessary activity are partly alleviated by run time
    10141026activity flags in the derivative routine
    1015 {\sf hov\_reverse} presented in Section \ref{forw_rev_ad}.
     1027{\sf hov\_reverse} presented in \autoref{forw_rev_ad}.
    10161028%
    10171029%
     
    10331045\]
    10341046The return value of all drivers presented in this section
    1035 indicate the validity of the tape as explained in Section~\ref{reuse_tape}.
     1047indicate the validity of the tape as explained in \autoref{reuse_tape}.
    10361048The presented drivers are all C functions and therefore can be used within
    10371049C and C++ programs. Some Fortran-callable companions can be found
     
    10461058equations are prototyped in the header file \verb=<adolc/drivers/drivers.h>=,
    10471059which is included automatically by the global header file \verb=<adolc/adolc.h>=
    1048 (see Section \ref{ssec:DesIH}).
     1060(see \autoref{ssec:DesIH}).
    10491061
    10501062The routine {\sf function} allows to evaluate the desired function from
     
    12001212during taping. If this assumption is falsely made all drivers
    12011213while internally calling the forward mode evaluation will return the value -1 or -2
    1202 as already specified in Section \ref{reuse_tape}. 
     1214as already specified in \autoref{reuse_tape}. 
    12031215%
    12041216%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
     
    12431255
    12441256Subsequently one may call the driver routine {\sf reverse} or corresponding
    1245 low level routines as explained in the Sections \ref{forw_rev} and
    1246 \ref{forw_rev_ad}, respectively, to compute
     1257low level routines as explained in the \autoref{forw_rev} and
     1258\autoref{forw_rev_ad}, respectively, to compute
    12471259the family of square matrices {\sf Z[n][n][deg]} defined by
    12481260\[
     
    12611273by an appropriate version of the chain rule.
    12621274To compute the total derivatives $B = (B_j)_{0\leq j <d}$
    1263 defined in (\ref{eq:bees}), one has to evaluate $\frac{1}{2}d(d-1)$
     1275defined in \eqref{eq:bees}, one has to evaluate $\frac{1}{2}d(d-1)$
    12641276matrix-matrix products. This can be done by a call of the routine {\sf accode} after the
    12651277corresponding evaluation of the {\sf hov\_reverse} function. The interface of
     
    12731285\>{\sf int deg;}               \> // degree on current call\\
    12741286\>{\sf double Z[n][n][deg];}   \> // partials of coefficient vectors\\
    1275 \>{\sf double B[n][n][deg];}   \> // result $B$ as defined in (\ref{eq:bees})\\
     1287\>{\sf double B[n][n][deg];}   \> // result $B$ as defined in \eqref{eq:bees}\\
    12761288\>{\sf short nz[n][n];}        \> // optional nonzero pattern
    12771289\end{tabbing}
     
    12801292nz}. For this purpose, {\sf nz} has to be set by a call of the routine {\sf
    12811293reverse} or the corresponding basic routines as explained below in
    1282 Section \ref{forw_rev_ad} and Section \ref{forw_rev}, respectively. The
     1294\autoref{forw_rev_ad} and \autoref{forw_rev}, respectively. The
    12831295non-positive entries of {\sf nz} are then changed by {\sf accode} so that upon
    12841296return
     
    12941306\verb=<adolc/drivers/odedrivers.h>=. The global header file
    12951307\verb=<adolc/adolc.h>=
    1296 includes this file automatically, see Section \ref{ssec:DesIH}.
     1308includes this file automatically, see \autoref{ssec:DesIH}.
    12971309
    12981310An example program using the procedures {\sf forode} and {\sf accode} together
    12991311with more detailed information about the coding can be found in
    1300 Section~\ref{exam:ode}. The corresponding source code
     1312\autoref{exam:ode}. The corresponding source code
    13011313\verb=odexam.cpp= is contained in the subdirectory
    13021314\verb=examples=.
     
    13161328separately to use the sparse drivers described here. ColPack is available for download at
    13171329\verb=http://www.cscapes.org/coloringpage/software.htm=. More information about the required
    1318 installation of ColPack is given in Section \ref{install}.
     1330installation of ColPack is given in \autoref{install}.
    13191331%
    13201332\subsubsection*{Sparse Jacobians and Sparse Hessians}
     
    13791391needs of application under consideration. Most frequently, the default options
    13801392will give a reasonable performance. The elements of the array {\sf options} control the action of
    1381 {\sf sparse\_jac} according to Table \ref{options_sparse_jac}.
     1393{\sf sparse\_jac} according to \autoref{options_sparse_jac}.
    13821394\begin{table}[h]
    13831395\center
     
    14281440
    14291441 The elements of the array {\sf options} control the action of
    1430 {\sf sparse\_hess} according to Table \ref{options_sparse_hess}.
     1442{\sf sparse\_hess} according to \autoref{options_sparse_hess}.
    14311443\begin{table}[h]
    14321444\center
     
    14461458matrices are prototyped in the header file
    14471459\verb=<adolc/sparse/sparsedrivers.h>=, which is included automatically by the
    1448 global header file \verb=<adolc/adolc.h>= (see Section \ref{ssec:DesIH}).
     1460global header file \verb=<adolc/adolc.h>= (see \autoref{ssec:DesIH}).
    14491461Example codes illustrating the usage of {\sf
    14501462  sparse\_jac} and {\sf sparse\_hess} can be found in the file
     
    14821494
    14831495The elements of the array {\sf options} control the action of
    1484 {\sf jac\_pat} according to Table \ref{options}.
     1496{\sf jac\_pat} according to \autoref{options}.
    14851497\begin{table}[h]
    14861498\center
     
    15351547The driver routine is prototyped in the header file
    15361548\verb=<adolc/sparse/sparsedrivers.h>=, which is included automatically by the
    1537 global header file \verb=<adolc/adolc.h>= (see Section
    1538 \ref{ssec:DesIH}). The determination of sparsity patterns is
     1549global header file \verb=<adolc/adolc.h>= (see
     1550\autoref{ssec:DesIH}). The determination of sparsity patterns is
    15391551illustrated by the examples \verb=sparse_jacobian.cpp=
    15401552and \verb=jacpatexam.cpp=
     
    15671579This driver routine is prototyped in the header file
    15681580\verb=<adolc/sparse/sparsedrivers.h>=, which is included automatically by the
    1569 global header file \verb=<adolc/adolc.h>= (see Section \ref{ssec:DesIH}).
     1581global header file \verb=<adolc/adolc.h>= (see \autoref{ssec:DesIH}).
    15701582An example employing the procedure {\sf hess\_pat}  can be found in the file
    15711583\verb=sparse_hessian.cpp=  contained in
     
    16401652These driver routines are prototyped in
    16411653\verb=<adolc/sparse/sparsedrivers.h>=, which is included automatically by the
    1642 global header file \verb=<adolc/adolc.h>= (see Section \ref{ssec:DesIH}).
     1654global header file \verb=<adolc/adolc.h>= (see \autoref{ssec:DesIH}).
    16431655An example code illustrating the usage of {\sf
    16441656generate\_seed\_jac} and {\sf generate\_seed\_hess} can be found in the file
     
    16801692\>{\sf int p;}                 \> // number of directions $p$\\
    16811693\>{\sf double x[n];}           \> // values of independent variables $x_0$\\
    1682 \>{\sf double tensor[m][size];}\> // result as defined in (\ref{eq:tensor}) in compressed form\\
     1694\>{\sf double tensor[m][size];}\> // result as defined in \eqref{eq:tensor} in compressed form\\
    16831695\>{\sf double S[n][p];}        \> // seed matrix $S$
    16841696\end{tabbing}
    16851697%
    1686 Using the symmetry of the tensors defined by (\ref{eq:tensor}), the memory 
     1698Using the symmetry of the tensors defined by \eqref{eq:tensor}, the memory 
    16871699requirement can be reduced enormously. The collection of  tensors up to order $d$ comprises 
    16881700$\binom{p+d}{d}$ distinct elements. Hence, the second dimension of {\sf tensor} must be
     
    17061718scheme described by Knuth \cite{Knuth73}. In the familiar quadratic
    17071719case $d=2$ the derivative with respect to $z_j$ and $z_k$ with $z$
    1708 as in (\ref{eq:tensor}) and $j \leq k$ is stored at {\sf tensor[i][l]} with
     1720as in \eqref{eq:tensor} and $j \leq k$ is stored at {\sf tensor[i][l]} with
    17091721$l = k*(k+1)/2+j$. At $j = 0 = k$ and hence $l = 0$ we find the
    17101722function value $F_{i+1}$ itself and the gradient
     
    17701782              \>{\sf tensor\_eval(tag,m,n,d,p,x,tensor,S);}   
    17711783\end{tabbing}
    1772 This way, we evaluated all tensors defined in (\ref{eq:tensor}) up to degree 3
     1784This way, we evaluated all tensors defined in \eqref{eq:tensor} up to degree 3
    17731785in both directions $s_1$ and
    17741786$s_2$ at some argument $x$. To allow the access of tensor entries by dereferencing the pointer
     
    18111823derivatives are prototyped in the header file \verb=<adolc/drivers/taylor.h>=,
    18121824which is included by the global header file \verb=<adolc/adolc.h>= automatically
    1813 (see Section \ref{ssec:DesIH}).
     1825(see \autoref{ssec:DesIH}).
    18141826Example codes using the above procedures can be found in the files
    18151827\verb=taylorexam.C= and \verb=accessexam.C= contained in the subdirectory
     
    18851897solving systems of nonlinear
    18861898equations $F(z)=0$ in the first place is not just a differentiation task.
    1887 However, the routine {\sf jac\_solv} described in Section \ref{optdrivers} may certainly be very
     1899However, the routine {\sf jac\_solv} described in \autoref{optdrivers} may certainly be very
    18881900useful for that purpose.
    18891901
     
    19401952\verb=<adolc/drivers/taylor.h>=. As indicated before this header
    19411953is included by the global header file \verb=<adolc/adolc.h>= automatically
    1942 (see Section \ref{ssec:DesIH}).
     1954(see \autoref{ssec:DesIH}).
    19431955The example programs \verb=inversexam.cpp=, \verb=coordinates.cpp= and
    19441956\verb=trigger.cpp=  in the directory \verb=examples/additional_examples/taylor=
     
    21342146initialization by the \boldmath $\ll=$ \unboldmath operator. The columns of
    21352147$X = \{x_j\}_{j=1\ldots d}$ represent Taylor coefficient vectors as in
    2136 (\ref{eq:x_of_t}). The rows of the matrix $Y$ must correspond to the
     2148\eqref{eq:x_of_t}. The rows of the matrix $Y$ must correspond to the
    21372149dependent variables in the order of their selection by the \boldmath $\gg=$ \unboldmath operator.
    21382150The columns of $Y = \{y_j\}_{j=1\ldots d}$ represent
    2139 Taylor coefficient vectors as in (\ref{eq:series}), i.e., {\sf hos\_forward}
     2151Taylor coefficient vectors as in \eqref{eq:series}, i.e., {\sf hos\_forward}
    21402152computes the values
    21412153$y_0=F(x_0)$, $y_1=F'(x_0)x_1$, \ldots, where
     
    21672179
    21682180There are also overloaded versions providing a general {\sf forward}-call.
    2169 Details of the appropriate calling sequences are given in Section \ref{forw_rev}.
     2181Details of the appropriate calling sequences are given in \autoref{forw_rev}.
    21702182
    21712183Once, the required information is generated due to a forward mode evaluation
     
    22562268
    22572269There are also overloaded versions providing a general {\sf reverse}-call.
    2258 Details of the appropriate calling sequences are given in the following Section \ref{forw_rev}.
     2270Details of the appropriate calling sequences are given in the following \autoref{forw_rev}.
    22592271%
    22602272%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
     
    22702282C and Fortran-callable versions prototyped in the same header file.
    22712283The bit pattern versions of {\sf forward} and {\sf reverse} introduced
    2272 in the subsection \ref{ProBit} are prototyped in the header file
     2284in the \autoref{ProBit} are prototyped in the header file
    22732285\verb=<adolc/sparse/sparsedrivers.h>=, which will be included by the header
    22742286file \verb=<adolc/interfaces.h>= automatically.
     
    22942306                                     independent variables \\
    22952307\>{\sf double Y[m][d+1];}      \> // Taylor coefficients $Y$ as
    2296                                      in (\ref{eq:series})
     2308                                     in \eqref{eq:series}
    22972309\end{tabbing}
    22982310%
     
    23002312initialization by the \boldmath $\ll=$ \unboldmath operator. The columns of
    23012313$X = \{x_j\}_{j=0\ldots d}$ represent Taylor coefficient vectors as in
    2302 (\ref{eq:x_of_t}). The rows of the matrix $Y$ must
     2314\eqref{eq:x_of_t}. The rows of the matrix $Y$ must
    23032315correspond to the
    23042316dependent variables in the order of their selection by the \boldmath $\gg=$ \unboldmath operator.
    23052317The columns of $Y = \{y_j\}_{j=0\ldots d}$ represent
    2306 Taylor coefficient vectors as in (\ref{eq:series}).
     2318Taylor coefficient vectors as in \eqref{eq:series}.
    23072319Thus the first column of $Y$ contains the
    23082320function value $F(x)$ itself, the next column represents the first
     
    23102322$d$-th Taylor coefficient vector. The integer flag {\sf keep} determines
    23112323how many Taylor coefficients of all intermediate quantities are
    2312 written into the value stack as explained in \ref{forw_rev_ad}.
     2324written into the value stack as explained in \autoref{forw_rev_ad}.
    23132325 If {\sf keep} is omitted, it defaults to 0.
    23142326
     
    23662378Through the optional argument {\sf nz} of {\sf reverse} one can compute
    23672379information about the sparsity pattern of $Z$ as described in detail
    2368 in the previous Section \ref{forw_rev_ad}.
     2380in the previous \autoref{forw_rev_ad}.
    23692381
    23702382The return values of {\sf reverse} calls can be interpreted according
    2371 to Table \ref{retvalues}, but negative return values are not
     2383to \autoref{retvalues}, but negative return values are not
    23722384valid, since the corresponding forward sweep would have
    23732385stopped without completing the necessary taylor file.
     
    24162428function cannot prepare a subsequent reverse sweep.
    24172429The return integer serves as a flag to indicate quadratures or altered
    2418 comparisons as described above in Section \ref{reuse_tape}.
     2430comparisons as described above in \autoref{reuse_tape}.
    24192431
    24202432Since the calculation of Jacobians is probably the most important
     
    25142526\>{\sf double y[m];}                \> // values of dependent variables $y_0$\\
    25152527\>{\sf unsigned long int Y[m][p];}  \> // dependence structure $Y$ according to
    2516                                      (\ref{eq:int_forrev})\\
     2528                                     \eqref{eq:int_forrev}\\
    25172529\>{\sf char mode;}                  \> // 0 : safe mode (default), 1 : tight mode
    25182530\end{tabbing}
     
    25332545\end{eqnarray*}
    25342546in the 4-byte long integer format. The parameter {\sf mode} determines
    2535 the mode of dependence analysis as explained already in subsection \ref{sparse}.
     2547the mode of dependence analysis as explained already in \autoref{sparse}.
    25362548
    25372549A call to the corresponding bit pattern {\sf reverse} routine
     
    25462558\>{\sf unsigned long int U[q][m];}  \> // dependence structure $U$ \\
    25472559\>{\sf unsigned long int Z[q][n];}  \> // dependence structure $Z$ according
    2548                                      to (\ref{eq:int_forrev})\\
     2560                                     to \eqref{eq:int_forrev}\\
    25492561\>{\sf char mode;}        \> // 0 : safe mode (default), 1 : tight mode
    25502562\end{tabbing}
     
    25622574
    25632575The return values of the bit pattern {\sf forward} and {\sf reverse} routines
    2564 correspond to those described in Table \ref{retvalues}.
     2576correspond to those described in \autoref{retvalues}.
    25652577
    25662578One can control the storage growth by the factor $p$ using
     
    25682580groups of columns or respectively rows at a time, i.e.~partitioning
    25692581$X$ or $U$ appropriately as described for the computation of Jacobians
    2570 in Section~\ref{vecCas}.
     2582in \autoref{vecCas}.
    25712583%
    25722584%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
     
    26672679control, the consequences for the tape generation using the ``basic''
    26682680taping approach as implemented in ADOL-C so far are shown in the left part of
    2669 Fig.~\ref{fig:bas_tap}.
     2681\autoref{fig:bas_tap}.
    26702682\begin{figure}[htbp] 
    26712683\begin{center}
    2672 \hspace*{0.5cm}\includegraphics[width=5.8cm]{tapebasic.eps}\hfill
    2673 \includegraphics[width=5.8cm]{tapeadv.eps} \hspace*{0.5cm}\
     2684\hspace*{0.5cm}\includegraphics[width=5.8cm]{tapebasic}\hfill
     2685\includegraphics[width=5.8cm]{tapeadv} \hspace*{0.5cm}\
    26742686\end{center}
    26752687\hspace*{0.8cm} Basic taping process \hspace*{4.3cm} Advanced taping process
     
    26812693time step. Hence, the overall tape comprises a serious amount of redundant
    26822694information as illustrated by the light grey rectangles in
    2683 Fig.~\ref{fig:bas_tap}. 
     2695\autoref{fig:bas_tap}. 
    26842696
    26852697To overcome the repeated storage of essentially the same information,
    26862698a {\em nested taping} mechanism has been incorporated into ADOL-C as illustrated on
    2687 the right-hand side of Fig.~\ref{fig:bas_tap}. This new
     2699the right-hand side of \autoref{fig:bas_tap}. This new
    26882700capability allows the encapsulation of the time-stepping procedure
    26892701such that only the last time step $x_{N} = F(x_{N-1},u_{N-1})$ is taped as one
     
    28032815point equation~\eqref{eq:fixedpoint}. Moreover,
    28042816suppose that $\|\frac{dF}{dx}(x_*,u)\|<1$ holds for any pair
    2805 $(x_*,u)$ satisfying equation (\ref{eq:fixedpoint}).
     2817$(x_*,u)$ satisfying equation \eqref{eq:fixedpoint}.
    28062818Hence, there exists a
    28072819differentiable function $\phi:\R^m \rightarrow \R^n$,
     
    28802892containing OpenMP parallel loops.
    28812893This implies that an explicit loop-handling approach is applied. A
    2882 typical situation is shown in Fig.~\ref{fig:basic_layout},
     2894typical situation is shown in \autoref{fig:basic_layout},
    28832895\begin{figure}[hbt]
    28842896    \vspace{3ex}
    28852897    \begin{center}
    2886         \includegraphics[height=4cm]{multiplexed.eps} \\
     2898        \includegraphics[height=4cm]{multiplexed} \\
    28872899        \begin{picture}(0,0)
    28882900            \put(-48,40){\vdots}
     
    29562968y_3  =  \arctan(x_2/x_1),
    29572969\end{eqnarray*}
    2958 as an example. The corresponding source code is shown in Figure \ref{fig:tapeless}.
     2970as an example. The corresponding source code is shown in \autoref{fig:tapeless}.
    29592971\begin{figure}[htb]
    29602972\framebox[\textwidth]{\parbox{\textwidth}{
     
    31053117  \end{tabular}
    31063118\end{center}
    3107 Fig.~\ref{fig:modcode} shows the resulting source code incorporating
     3119\autoref{fig:modcode} shows the resulting source code incorporating
    31083120all required changes for the example
    31093121given above.
     
    32103222\end{center}
    32113223The resulting source code containing all changes that are required is
    3212 shown in Fig.~\ref{fig:modcode2}
     3224shown in \autoref{fig:modcode2}
    32133225
    32143226\begin{figure}[!h!t!b]
     
    33603372Before doing so the user may modify the header file \verb=usrparms.h=
    33613373in order to tailor the \mbox{ADOL-C} package to the needs in the
    3362 particular system environment as discussed in Section
    3363 \ref{Customizing}. The configure procedure which creates the necessary
     3374particular system environment as discussed in
     3375\autoref{Customizing}. The configure procedure which creates the necessary
    33643376\verb=Makefile=s can be customized by use of some switches. Available
    33653377options and their meaning can be obtained by executing
     
    33893401\subsection{Compiling and Linking the Example Programs}
    33903402%
    3391 The installation procedure described in Subsection \ref{genlib} also
     3403The installation procedure described in \autoref{genlib} also
    33923404provides the \verb=Makefile=s  to compile the example
    33933405programs in the directories \verb=<ADOL-C-2.1.0>/ADOL-C/examples= and
     
    33993411\begin{tabular}[t]{ll}
    34003412\verb=--enable-docexa=&build all examples discussed in this manual\\
    3401 &(compare Section \ref{example})\\
     3413&(compare \autoref{example})\\
    34023414\verb=--enable-addexa=&build all additional examples\\
    34033415&(See file \verb=README= in the various subdirectories)
     
    34263438to take one of two possible ways to access the right interfaces.
    34273439The first and easy way is recommended to beginners: As indicated in
    3428 Table \ref{globalHeaders} the provided {\em global} header file
     3440\autoref{globalHeaders} the provided {\em global} header file
    34293441\verb=<adolc/adolc.h>= can be included by any user code to support all
    34303442capabilities of ADOL-C depending on the particular programming language
     
    34463458  \boldmath $\rightarrow$ \unboldmath
    34473459                 & user customization of ADOL-C package (see
    3448                    Section \ref{Customizing}); \\
     3460                   \autoref{Customizing}); \\
    34493461  $\bullet$      & after a change of
    34503462                   user options the ADOL-C library \verb=libadolc.*=
    3451                    has to be rebuilt (see Section \ref{genlib}); \\
     3463                   has to be rebuilt (see \autoref{genlib}); \\
    34523464  $\bullet$      & is included by all ADOL-C header files and thus by all user
    34533465                   programs.
     
    34653477ADOL-C routines are realized by automatic includes of headers in order
    34663478to maintain easy use. The header files important to the user are described
    3467 in the Tables~\ref{importantHeaders1} and \ref{importantHeaders2}.
     3479in the \autoref{importantHeaders1} and \autoref{importantHeaders2}.
    34683480
    34693481\begin{table}[h]
     
    34763488                & provides the interface to the basic active
    34773489                  scalar data type of ADOL-C: {\sf class adouble}
    3478                   (see Section \ref{prepar});
     3490                  (see \autoref{prepar});
    34793491%  $\bullet$     & includes the header files \verb=<adolc/avector.h>= and \verb=<adolc/taputil.h>=.
    34803492\end{tabular*}
     
    34863498%                  and matrix data types of ADOL-C: {\sf class adoublev}
    34873499%                  and {\sf class adoublem}, respectively
    3488 %                   (see Section \ref{arrays}); \\
     3500%                   (see \autoref{arrays}); \\
    34893501%  $\bullet$     & is included by the header \verb=<adolc/adouble.h>=.
    34903502%\end{tabular*}
     
    34943506  \boldmath $\rightarrow$ \unboldmath
    34953507                & provides functions to start/stop the tracing of
    3496                   active sections (see Sections \ref{markingActive})
     3508                  active sections (see \autoref{markingActive})
    34973509                  as well as utilities to obtain
    3498                   tape statistics (see Sections \ref{examiningTape}); \\
     3510                  tape statistics (see \autoref{examiningTape}); \\
    34993511  $\bullet$     & is included by the header \verb=<adolc/adouble.h>=.
    35003512\end{tabular*}
     
    35143526                & provides interfaces to the {\sf forward} and
    35153527                  {\sf reverse} routines as basic versions of derivative
    3516                   evaluation (see Section \ref{forw_rev}); \\
     3528                  evaluation (see \autoref{forw_rev}); \\
    35173529  $\bullet$     & comprises C++, C, and Fortran-callable versions; \\
    35183530  $\bullet$     & includes the header \verb=<adolc/sparse/sparsedrivers.h>=; \\
     
    35253537                & provides ``easy to use'' drivers for solving
    35263538                  optimization problems and nonlinear equations
    3527                   (see Section \ref{optdrivers}); \\
     3539                  (see \autoref{optdrivers}); \\
    35283540  $\bullet$     & comprises C and Fortran-callable versions.
    35293541\end{tabular*}
     
    35363548                & provides the ``easy to use'' sparse drivers
    35373549                  to exploit the sparsity structure of
    3538                   Jacobians (see Section \ref{sparse}); \\
     3550                  Jacobians (see \autoref{sparse}); \\
    35393551  \boldmath $\rightarrow$ \unboldmath & provides interfaces to \mbox{C++}-callable versions
    35403552                  of {\sf forward} and {\sf reverse} routines
    3541                   propagating bit patterns (see Section \ref{ProBit}); \\
     3553                  propagating bit patterns (see \autoref{ProBit}); \\
    35423554
    35433555  $\bullet$     & is included by the header \verb=<adolc/interfaces.h>=.
     
    35613573                & provides ``easy to use'' drivers for numerical
    35623574                  solution of ordinary differential equations
    3563                   (see Section \ref{odedrivers}); \\
     3575                  (see \autoref{odedrivers}); \\
    35643576  $\bullet$     & comprises C++, C, and Fortran-callable versions; \\
    35653577  $\bullet$     & includes the header \verb=<adolc/interfaces.h>=.
     
    35723584  \boldmath $\rightarrow$ \unboldmath
    35733585                & provides ``easy to use'' drivers for evaluation
    3574                   of higher order derivative tensors (see Section
    3575                   \ref{higherOrderDeriv}) and inverse/implicit function
    3576                   differentiation (see Section \ref{implicitInverse});\\
     3586                  of higher order derivative tensors (see
     3587                  \autoref{higherOrderDeriv}) and inverse/implicit function
     3588                  differentiation (see \autoref{implicitInverse});\\
    35773589  $\bullet$     & comprises C++ and C-callable versions.
    35783590\end{tabular*}
     
    35953607To compile a C/C++ program or single module using ADOL-C
    35963608data types and routines one has to ensure that all necessary
    3597 header files according to Section \ref{ssec:DesIH} are
     3609header files according to \autoref{ssec:DesIH} are
    35983610included. All modules involving {\em active} data types as
    35993611{\sf adouble}
     
    36053617the right ADOL-C prototypes.
    36063618For linking the resulting object codes the library \verb=libadolc.*=
    3607 must be used (see Section \ref{genlib}).
     3619must be used (see \autoref{genlib}).
    36083620%
    36093621\subsection{Adding Quadratures as Special Functions}
     
    36463658This macro is extended to the definition of
    36473659 {\sf adouble myintegral(adouble\& arg)}.
    3648 Then remake the library \verb=libadolc.*= (see Section \ref{genlib}).
     3660Then remake the library \verb=libadolc.*= (see \autoref{genlib}).
    36493661\item
    36503662In the definition of the class
  • trunk/ADOL-C/doc/short_ref.tex

    r42 r109  
    1111\documentclass[12pt,oneside,a4paper]{article}
    1212\usepackage{amsmath,amsthm,amssymb}
    13 \usepackage{epsfig,color,psfrag}
    1413\usepackage{fancyhdr}
    1514
  • trunk/ADOL-C/src/dvlparms.h

    r75 r109  
    2020
    2121/*--------------------------------------------------------------------------*/
     22/* Directory where tapes are created */
     23#define ADOLC_TAPE_DIR        "."
    2224/* File names for the tapes */
    2325#define ADOLC_TAYLORS_NAME    "ADOLC-Taylors_"
     
    2628#define ADOLC_OPERATIONS_NAME "ADOLC-Operations_"
    2729
     30#ifdef _WINDOWS
     31#define PATHSEPARATOR         "\\"
     32#else
     33#define PATHSEPARATOR         "/"
     34#endif
    2835/****************************************************************************/
    2936/* Tells ADOL-C which name space offers the mathematical functions          */
  • trunk/ADOL-C/src/taping.c

    r106 r109  
    301301/* the base names of every tape type */
    302302const char *tapeBaseNames[] = {
    303             ADOLC_LOCATIONS_NAME,
    304             ADOLC_VALUES_NAME,
    305             ADOLC_OPERATIONS_NAME,
    306             ADOLC_TAYLORS_NAME
     303            ADOLC_TAPE_DIR PATHSEPARATOR ADOLC_LOCATIONS_NAME,
     304            ADOLC_TAPE_DIR PATHSEPARATOR ADOLC_VALUES_NAME,
     305            ADOLC_TAPE_DIR PATHSEPARATOR ADOLC_OPERATIONS_NAME,
     306            ADOLC_TAPE_DIR PATHSEPARATOR ADOLC_TAYLORS_NAME
    307307        };
    308308
Note: See TracChangeset for help on using the changeset viewer.