source: trunk/cppad/local/fun_construct.hpp @ 1359

Last change on this file since 1359 was 1359, checked in by bradbell, 12 years ago

trunk: Add some cross referencing to examples.

doc.omh.in: add default hilite command for all documentation.
whats_new_09.omh: user's view of the changes.
user_ad.hpp: remove improper referece from documentation.
fun_construct.hpp: fix an error message.

File size: 6.2 KB
Line 
1# ifndef CPPAD_FUN_CONSTRUCT_INCLUDED
2# define CPPAD_FUN_CONSTRUCT_INCLUDED
3
4/* --------------------------------------------------------------------------
5CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-08 Bradley M. Bell
6
7CppAD is distributed under multiple licenses. This distribution is under
8the terms of the
9                    Common Public License Version 1.0.
10
11A copy of this license is included in the COPYING file of this distribution.
12Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
13-------------------------------------------------------------------------- */
14/*
15$begin FunConstruct$$
16$spell
17        taylor_
18        var
19        ADvector
20        const
21$$
22
23$spell
24$$
25
26$section Construct an ADFun Object and Stop Recording$$
27
28$index ADFun, construct$$
29$index construct, ADFun$$
30$index tape, stop recording$$
31$index recording, stop tape$$
32
33$head Syntax$$
34$codei%ADFun<%Base%> %f%
35%$$
36$codei%ADFun<%Base%> %f%(%x%, %y%)
37%$$
38
39
40$head Purpose$$
41The $codei%AD<%Base%>%$$ object $icode f$$ can
42store an AD of $icode Base$$
43$xref/glossary/Operation/Sequence/operation sequence/1/$$.
44It can then be used to calculate derivatives of the corresponding
45$xref/glossary/AD Function/AD function/$$
46$latex \[
47        F : B^n \rightarrow B^m
48\] $$
49where $latex B$$ is the space corresponding to objects of type $icode Base$$.
50
51$head x$$
52If the argument $icode x$$ is present, it has prototype
53$codei%
54        const %VectorAD% &%x%
55%$$
56It must be the vector argument in the previous call to
57$cref/Independent/$$.
58Neither its size, or any of its values, are allowed to change
59between calling
60$codei%
61        Independent(%x%)
62%$$
63and
64$codei%
65        ADFun<%Base%> %f%(%x%, %y%)
66%$$.
67
68$head y$$
69If the argument $icode y$$ is present, it has prototype
70$codei%
71        const %VectorAD% &%y%
72%$$
73The sequence of operations that map $icode x$$
74to $icode y$$ are stored in the AD function object $icode f$$.
75
76$head VectorAD$$
77The type $icode VectorAD$$ must be a $cref/SimpleVector/$$ class with
78$cref/elements of type/SimpleVector/Elements of Specified Type/$$
79$codei%AD<%Base%>%$$.
80The routine $cref/CheckSimpleVector/$$ will generate an error message
81if this is not the case.
82
83$head Default Constructor$$
84The default constructor
85$codei%
86        ADFun<%Base%> %f%
87%$$
88creates an
89$codei%AD<%Base%>%$$ object with no corresponding operation sequence; i.e.,
90$codei%
91        %f%.size_var()
92%$$
93returns the value zero (see $xref/SeqProperty/size_var/size_var/$$).
94
95$head Sequence Constructor$$
96The sequence constructor
97$codei%
98        ADFun<%Base%> %f%(%x%, %y%)
99%$$
100creates the $codei%AD<%Base%>%$$ object $icode f$$,
101stops the recording of AD of $icode Base$$ operations
102corresponding to the call
103$codei%
104        Independent(%x%)
105%$$
106and stores the corresponding operation sequence in the object $icode f$$.
107It then stores the first order taylor_ coefficients
108(corresponding to the value of $icode x$$) in $icode f$$.
109This is equivalent to the following steps using the default constructor:
110$list number$$
111Create $icode f$$ with the default constructor
112$codei%
113        ADFun<%Base%> %f%;
114%$$
115$lnext
116Stop the tape and storing the operation sequence using
117$codei%
118        %f%.Dependent(%x%, %y%);
119%$$
120(see $xref/Dependent/$$).
121$lnext
122Calculating the first order taylor_ coefficients for all
123the variables in the operation sequence using
124$codei%
125        %f%.Forward(%p%, %x_p%)
126%$$
127with $icode p$$ equal to zero and the elements of $icode x_p$$
128equal to the corresponding elements of $icode x$$
129(see $xref/Forward/$$).
130$lend
131
132$head OpenMP$$
133$index OpenMP, Dependent$$
134$index Dependent, OpenMP$$
135$index OpenMP, ADFun$$
136$index ADFun, OpenMP$$
137In the case of multi-threading with OpenMP,
138the call to $code Independent$$
139and the corresponding call to
140$codei%
141        ADFun<%Base%> %f%( %x%, %y%)
142%$$
143or
144$codei%
145        %f%.Dependent( %x%, %y%)
146%$$
147must be preformed by the same thread.
148
149
150$head Example$$
151
152$subhead Sequence Constructor$$
153The file
154$xref/Independent.cpp/$$
155contains an example and test of the sequence constructor.
156It returns true if it succeeds and false otherwise.
157
158$subhead Default Constructor$$
159The files
160$xref/FunCheck.cpp/$$
161and
162$xref/HesLagrangian.cpp/$$
163contain an examples and tests using the default constructor.
164They return true if they succeed and false otherwise.
165
166$end
167*/
168
169
170// BEGIN CppAD namespace
171namespace CppAD {
172
173template <typename Base>
174template <typename VectorAD>
175ADFun<Base>::ADFun(const VectorAD &x, const VectorAD &y)
176: total_num_var_(0), taylor_(CPPAD_NULL), for_jac_(CPPAD_NULL)
177{       size_t i, j, m, n;
178
179        CPPAD_ASSERT_KNOWN(
180                x.size() > 0,
181                "ADFun<Base>: independent variable vector has size zero."
182        );
183        CPPAD_ASSERT_KNOWN(
184                Variable(x[0]),
185                "ADFun<Base>: independent variable vector has been changed."
186        );
187        ADTape<Base> *tape = AD<Base>::tape_ptr(x[0].id_);
188        CPPAD_ASSERT_KNOWN(
189                tape->size_independent_ == x.size(),
190                "ADFun<Base>: independent variable vector has been changed."
191        );
192# ifndef NDEBUG
193        for(j = 0; j < x.size(); j++)
194        {       CPPAD_ASSERT_KNOWN(
195                x[j].taddr_ == (j+1),
196                "ADFun<Base>: independent variable vector has been changed."
197                );
198                CPPAD_ASSERT_KNOWN(
199                x[j].id_ == x[0].id_,
200                "ADFun<Base>: independent variable vector has been changed."
201                );
202        }
203        for(i = 0; i < y.size(); i++)
204        {       CPPAD_ASSERT_KNOWN(
205                CppAD::Parameter( y[i] ) | (y[i].id_ == x[0].id_) ,
206                "ADFun<Base>: dependent vector contains variables for"
207                "\na different tape than the independent variables."
208                );
209        }
210# endif
211
212        // stop the tape and store the operation sequence
213        Dependent(tape, y);
214
215        // allocate memory for one zero order taylor_ coefficient
216        taylor_per_var_= 1;
217        taylor_col_dim_  = 1;
218        taylor_        = CPPAD_TRACK_NEW_VEC(total_num_var_, taylor_);
219
220        // set zero order coefficients corresponding to indpendent variables
221        n = ind_taddr_.size();
222        CPPAD_ASSERT_UNKNOWN( n == x.size() );
223        for(j = 0; j < n; j++)
224        {       CPPAD_ASSERT_UNKNOWN( ind_taddr_[j] == (j+1) );
225                CPPAD_ASSERT_UNKNOWN( x[j].taddr_  == (j+1) );
226                taylor_[ ind_taddr_[j] ]  = x[j].value_;
227        }
228
229        // use independent variable values to fill in values for others
230        compare_change_ = forward0sweep(
231                false, total_num_var_, &play_, taylor_col_dim_, taylor_
232        );
233        CPPAD_ASSERT_UNKNOWN( compare_change_ == 0 );
234
235        // check the dependent variable values
236        m = dep_taddr_.size();
237        for(i = 0; i < m; i++) CPPAD_ASSERT_KNOWN(
238                taylor_[dep_taddr_[i]] == y[i].value_,
239                "A dependent variable is not equal its tape evaluation"
240                ", it may be nan."
241        );
242}
243
244} // END CppAD namespace
245
246# endif
Note: See TracBrowser for help on using the repository browser.