CppAD: A C++ Algorithmic Differentiation Package 20110419
bool_fun.hpp
Go to the documentation of this file.
00001 /* $Id$ */
00002 # ifndef CPPAD_BOOL_FUN_INCLUDED
00003 # define CPPAD_BOOL_FUN_INCLUDED
00004 
00005 /* --------------------------------------------------------------------------
00006 CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-11 Bradley M. Bell
00007 
00008 CppAD is distributed under multiple licenses. This distribution is under
00009 the terms of the 
00010                     Common Public License Version 1.0.
00011 
00012 A copy of this license is included in the COPYING file of this distribution.
00013 Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
00014 -------------------------------------------------------------------------- */
00015 
00016 /*
00017 $begin BoolFun$$
00018 $spell
00019         namespace
00020         bool
00021         CppAD
00022         const
00023 $$
00024 
00025 $index bool, AD function$$
00026 $index function, AD bool$$
00027 $index unary, AD bool$$
00028 $index binary, AD bool$$
00029 
00030 $section AD Boolean Functions$$
00031 
00032 $head Syntax$$
00033 $syntax%CPPAD_BOOL_UNARY(%Base%, %unary_name%)
00034 %$$
00035 $syntax%%b% = %unary_name%(%u%)
00036 %$$
00037 $syntax%%b% = %unary_name%(%x%)
00038 %$$
00039 $syntax%CPPAD_BOOL_BINARY(%Base%, %binary_name%)
00040 %$$
00041 $syntax%%b% = %binary_name%(%u%, %v%)
00042 %$$
00043 $syntax%%b% = %binary_name%(%x%, %y%)%$$
00044 
00045 
00046 $head Purpose$$
00047 Create a $code bool$$ valued function that has $syntax%AD<%Base%>%$$ arguments.
00048 
00049 $head unary_name$$
00050 This is the name of the $code bool$$ valued function with one argument
00051 (as it is used in the source code).
00052 The user must provide a version of $italic unary_name$$ where
00053 the argument has type $italic Base$$.
00054 CppAD uses this to create a version of $italic unary_name$$ where the
00055 argument has type $syntax%AD<%Base%>%$$.
00056 
00057 $head u$$
00058 The argument $italic u$$ has prototype
00059 $syntax%
00060         const %Base% &%u%
00061 %$$
00062 It is the value at which the user provided version of $italic unary_name$$
00063 is to be evaluated.
00064 It is also used for the first argument to the 
00065 user provided version of $italic binary_name$$.
00066 
00067 $head x$$
00068 The argument $italic x$$ has prototype
00069 $syntax%
00070         const AD<%Base%> &%x%
00071 %$$
00072 It is the value at which the CppAD provided version of $italic unary_name$$
00073 is to be evaluated.
00074 It is also used for the first argument to the 
00075 CppAD provided version of $italic binary_name$$.
00076 
00077 $head b$$
00078 The result $italic b$$ has prototype
00079 $syntax%
00080         bool %b%
00081 %$$
00082 
00083 $head Create Unary$$
00084 $index CPPAD_BOOL_UNARY$$
00085 The preprocessor macro invocation
00086 $syntax%
00087         CPPAD_BOOL_UNARY(%Base%, %unary_name%)
00088 %$$
00089 defines the version of $italic unary_name$$ with a $syntax%AD<%Base%>%$$
00090 argument.
00091 This can with in a namespace 
00092 (not the $code CppAD$$ namespace)
00093 but must be outside of any routine.
00094 
00095 $head binary_name$$
00096 This is the name of the $code bool$$ valued function with two arguments
00097 (as it is used in the source code).
00098 The user must provide a version of $italic binary_name$$ where
00099 the arguments have type $italic Base$$.
00100 CppAD uses this to create a version of $italic binary_name$$ where the
00101 arguments have type $syntax%AD<%Base%>%$$.
00102 
00103 $head v$$
00104 The argument $italic v$$ has prototype
00105 $syntax%
00106         const %Base% &%v%
00107 %$$
00108 It is the second argument to
00109 the user provided version of $italic binary_name$$.
00110 
00111 $head y$$
00112 The argument $italic x$$ has prototype
00113 $syntax%
00114         const AD<%Base%> &%y%
00115 %$$
00116 It is the second argument to
00117 the CppAD provided version of $italic binary_name$$.
00118 
00119 $head Create Binary$$
00120 $index CPPAD_BOOL_BINARY$$
00121 The preprocessor macro invocation
00122 $syntax%
00123         CPPAD_BOOL_BINARY(%Base%, %binary_name%)
00124 %$$
00125 defines the version of $italic binary_name$$ with $syntax%AD<%Base%>%$$
00126 arguments.
00127 This can with in a namespace 
00128 (not the $code CppAD$$ namespace)
00129 but must be outside of any routine.
00130 
00131 
00132 $head Operation Sequence$$
00133 The result of this operation is not an
00134 $xref/glossary/AD of Base/AD of Base/$$ object.
00135 Thus it will not be recorded as part of an
00136 AD of $italic Base$$
00137 $xref/glossary/Operation/Sequence/operation sequence/1/$$.
00138 
00139 $head Example$$
00140 $children%
00141         example/bool_fun.cpp
00142 %$$
00143 The file
00144 $xref/BoolFun.cpp/$$
00145 contains an example and test of these operations.
00146 It returns true if it succeeds and false otherwise.
00147 
00148 $head Deprecated$$
00149 The preprocessor symbols $code CppADCreateUnaryBool$$ 
00150 and $code CppADCreateBinaryBool$$ are defined to be the same as
00151 $code CPPAD_BOOL_UNARY$$ and $code CPPAD_BOOL_BINARY$$ respectively
00152 (but their use is deprecated).
00153 
00154 $end
00155 */
00156 
00157 CPPAD_BEGIN_NAMESPACE
00158 /*!
00159 \file bool_fun.hpp
00160 Routines and macros that implement functions from AD<Base> to bool
00161 \ref bool_fun_hpp.
00162 
00163 \defgroup bool_fun_hpp bool_fun.hpp
00164 */
00165 /* \{ */
00166 
00167 /*!
00168 Macro that defines a unary function <tt>bool F(AD<Base> x)</tt> 
00169 using <tt>bool F(Base x)</tt>.
00170 
00171 \param Base
00172 base for the AD type of arguments to this unary bool valued function.
00173 
00174 \param unary_name
00175 name of this unary function; i.e., \c F.
00176 */
00177 # define CPPAD_BOOL_UNARY(Base, unary_name)                        \
00178      inline bool unary_name (const CppAD::AD<Base> &x)             \
00179      {                                                             \
00180           return CppAD::AD<Base>::UnaryBool(unary_name, x);        \
00181      }
00182 
00183 /*!
00184 Deprecated name for CPPAD_BOOL_UNARY
00185 */
00186 # define CppADCreateUnaryBool  CPPAD_BOOL_UNARY
00187 
00188 /*!
00189 Link a function name, and AD value pair to function call with base argument
00190 and bool retrun value.
00191 
00192 \param FunName
00193 is the name of the function that we are linking.
00194 
00195 \param x
00196 is the argument where we are evaluating the function.
00197 */
00198 template <class Base>
00199 inline bool AD<Base>::UnaryBool(
00200         bool FunName(const Base &x),
00201         const AD<Base> &x
00202 ) 
00203 {
00204         return FunName(x.value_);
00205 }
00206 
00207 /*!
00208 Macro that defines a binary function <tt>bool F(AD<Base> x, AD<Base> y)</tt> 
00209 using <tt>bool F(Base x, Base y)</tt>.
00210 
00211 \param Base
00212 base for the AD type of arguments to this binary bool valued function.
00213 
00214 \param binary_name
00215 name of this binary function; i.e., \c F.
00216 */
00217 
00218 # define CPPAD_BOOL_BINARY(Base, binary_name)                      \
00219      inline bool binary_name (                                     \
00220           const CppAD::AD<Base> &x, const CppAD::AD<Base> &y)      \
00221      {                                                             \
00222           return CppAD::AD<Base>::BinaryBool(binary_name, x, y);   \
00223      }
00224 /*!
00225 Deprecated name for CPPAD_BOOL_BINARY
00226 */
00227 # define CppADCreateBinaryBool CPPAD_BOOL_BINARY
00228 
00229 
00230 /*!
00231 Link a function name, and two AD values to function call with base arguments
00232 and bool retrun value.
00233 
00234 \param FunName
00235 is the name of the function that we are linking.
00236 
00237 \param x
00238 is the first argument where we are evaluating the function at.
00239 
00240 \param y
00241 is the second argument where we are evaluating the function at.
00242 */
00243 template <class Base>
00244 inline bool AD<Base>::BinaryBool(
00245         bool FunName(const Base &x, const Base &y),
00246         const AD<Base> &x, const AD<Base> &y
00247 ) 
00248 {
00249         return FunName(x.value_, y.value_);
00250 }
00251 
00252 /* \} */
00253 CPPAD_END_NAMESPACE
00254 # endif