// $Id$
// Version: $Name$
//
-// Copyright (C) 2001, 2002, 2003 by the deal authors
+// Copyright (C) 2001, 2002, 2003, 2004 by the deal authors
//
// This file is subject to QPL and may not be distributed
// without copyright and license information. Please refer
* employing numerical difference quotients. This only, if the user
* function does not provide the gradient function himself.
*
- * @sect3{Usage}
+ * @section Usage Usage
* The following example of an user defined function overloads and
- * implements only the @p{value} function but not the @p{gradient}
- * function. If the @p{gradient} function is invoked then the gradient
- * function implemented by the @p{AutoDerivativeFunction} is called,
+ * implements only the value() function but not the gradient()
+ * function. If the gradient() function is invoked then the gradient
+ * function implemented by the AutoDerivativeFunction is called,
* where the latter function imployes numerical difference quotients.
*
- * @begin{verbatim}
+ * @code
* class UserFunction: public AutoDerivativeFunction
* { // access to one component at one point
* double value (const Point<dim> &p, const
*
* // gradient by employing difference quotients.
* Tensor<1,dim> grad=user_function.gradient(some_point);
- * @end{verbatim}
+ * @endcode
*
* If the user overloads and implements also the gradient function,
* then, of course, the users gradient function is called.
*
- * Note, that the usage of the @p{value} and @p{gradient} functions
- * explained above, also applies to the @p{value_list} and
- * @p{gradient_list} functions as well as to the vector valued
- * versions of these functions, see e.g. @p{vector_value},
- * @p{vector_gradient}, @p{vector_value_list} and
- * @p{vector_gradient_list}.
+ * Note, that the usage of the value() and gradient() functions
+ * explained above, also applies to the value_list() and
+ * gradient_list() functions as well as to the vector valued
+ * versions of these functions, see e.g. vector_value(),
+ * vector_gradient(), vector_value_list() and
+ * vector_gradient_list().
*
- * The @p{gradient} and @p{gradient_list} functions make use of the
- * @p{value} function. The @p{vector_gradient} and
- * @p{vector_gradient_list} make use of the @p{vector_value}
+ * The gradient() and gradient_list() functions make use of the
+ * Function::value() function. The vector_gradient() and
+ * vector_gradient_list() make use of the Function::vector_value()
* function. Make sure that the user defined function implements the
- * @p{value} function and the @p{vector_value} function, respectively.
+ * value() function and the vector_value() function, respectively.
*
- * Furthermore note, that an object of this class does @em{not} represent
- * the derivative of a function, like @ref{FunctionDerivative}, that
- * gives a directional derivate by calling the @p{value} function. In
- * fact, this class (the @p{AutoDerivativeFunction} class) can
- * substitute the @p{Function} class as base class for user defined
- * classes. This class implements the @p{gradient} functions for
+ * Furthermore note, that an object of this class does <b>not</b> represent
+ * the derivative of a function, like FunctionDerivative, that
+ * gives a directional derivate by calling the value() function. In
+ * fact, this class (the AutoDerivativeFunction class) can
+ * substitute the Function class as base class for user defined
+ * classes. This class implements the gradient() functions for
* automatic computation of numerical difference quotients and serves
- * as intermediate class between the base @p{Function} class and the
+ * as intermediate class between the base Function class and the
* user defined function class.
*
* @author Ralf Hartmann, 2001
/**
* Constructor. Takes the
* difference step size
- * @p{h}. It's within the user's
+ * <tt>h</tt>. It's within the user's
* responsibility to choose an
- * appropriate value here. @p{h}
+ * appropriate value here. <tt>h</tt>
* should be chosen taking into
* account the absolute value as
* well as the amount of local
* variation of the function.
- * Setting @p{h=1e-6} might be a
+ * Setting <tt>h=1e-6</tt> might be a
* good choice for functions with
* an absolute value of about 1,
* that furthermore does not vary
* to much.
*
- * @p{h} can be changed later
- * using the @p{set_h} function.
+ * <tt>h</tt> can be changed later
+ * using the set_h() function.
*
- * Sets @p{DifferenceFormula}
- * @p{formula} to the default
- * @p{Euler} formula of the
- * @p{set_formula}
+ * Sets DifferenceFormula
+ * <tt>formula</tt> to the default
+ * <tt>Euler</tt> formula of the
+ * set_formula()
* function. Change this preset
* formula by calling the
- * @p{set_formula} function.
+ * set_formula() function.
*/
AutoDerivativeFunction (const double h,
const unsigned int n_components = 1,
/**
* Choose the difference formula.
- *
- * Formulas implemented right now
- * are first order backward Euler
- * (@p{UpwindEuler}), second
- * order symmetric Euler
- * (@p{Euler}) and a symmetric
- * fourth order formula
- * (@p{FourthOrder}).
+ * See the enum #DifferenceFormula
+ * for available choices.
*/
void set_formula (const DifferenceFormula formula = Euler);
/**
* Takes the difference step size
- * @p{h}. It's within the user's
+ * <tt>h</tt>. It's within the user's
* responsibility to choose an
- * appropriate value here. @p{h}
+ * appropriate value here. <tt>h</tt>
* should be chosen taking into
* account the absolute value of
* as well as the amount of local
* variation of the function.
- * Setting @p{h=1e-6} might be a
+ * Setting <tt>h=1e-6</tt> might be a
* good choice for functions with
* an absolute value of about 1,
* that furthermore does not vary
* specified component of the
* function at the given point.
*
- * Imployes numerical difference
+ * Computes numerical difference
* quotients using the preset
- * @p{DifferenceFormula}
- * @p{formula}.
+ * #DifferenceFormula.
*/
virtual Tensor<1,dim> gradient (const Point<dim> &p,
const unsigned int component = 0) const;
* components of the
* function at the given point.
*
- * Imployes numerical difference
+ * Computes numerical difference
* quotients using the preset
- * @p{DifferenceFormula}
- * @p{formula}.
+ * #DifferenceFormula.
*/
virtual void vector_gradient (const Point<dim> &p,
std::vector<Tensor<1,dim> > &gradients) const;
/**
- * Set @p{gradients} to the
+ * Set <tt>gradients</tt> to the
* gradients of the specified
* component of the function at
- * the @p{points}. It is assumed
- * that @p{gradients} already has the
+ * the <tt>points</tt>. It is assumed
+ * that <tt>gradients</tt> already has the
* right size, i.e. the same
- * size as the @p{points} array.
+ * size as the <tt>points</tt> array.
*
- * Imployes numerical difference
+ * Computes numerical difference
* quotients using the preset
- * @p{DifferenceFormula}
- * @p{formula}.
+ * #DifferenceFormula.
*/
virtual void gradient_list (const std::vector<Point<dim> > &points,
std::vector<Tensor<1,dim> > &gradients,
const unsigned int component = 0) const;
/**
- * Set @p{gradients} to the gradients of
- * the function at the @p{points},
+ * Set <tt>gradients</tt> to the gradients of
+ * the function at the <tt>points</tt>,
* for all components.
- * It is assumed that @p{gradients}
+ * It is assumed that <tt>gradients</tt>
* already has the right size, i.e.
- * the same size as the @p{points} array.
+ * the same size as the <tt>points</tt> array.
*
* The outer loop over
- * @p{gradients} is over the points
+ * <tt>gradients</tt> is over the points
* in the list, the inner loop
* over the different components
* of the function.
*
- * Imploys numerical difference
+ * Computes numerical difference
* quotients using the preset
- * @p{DifferenceFormula}
- * @p{formula}.
+ * #DifferenceFormula.
*/
virtual void vector_gradient_list (const std::vector<Point<dim> > &points,
std::vector<std::vector<Tensor<1,dim> > > &gradients) const;
/**
* Returns a
- * @p{DifferenceFormula} of the
- * order @p{ord} at minimum.
+ * #DifferenceFormula of the
+ * order <tt>ord</tt> at minimum.
*/
static
DifferenceFormula
/**
* Step size of the difference
- * formula. Set by the @p{set_h}
+ * formula. Set by the set_h()
* function.
*/
double h;
/**
* Includes the unit vectors
- * scaled by @p{h}.
+ * scaled by <tt>h</tt>.
*/
std::vector<Tensor<1,dim> > ht;
/**
* Difference formula. Set by the
- * @p{set_formula} function.
+ * set_formula() function.
*/
DifferenceFormula formula;
};