#include <deal.II/base/auto_derivative_function.h>

Inheritance diagram for AutoDerivativeFunction< dim >:

Public Types
enum	DifferenceFormula { Euler, UpwindEuler, FourthOrder }

Public Types inherited from Function< dim >
using	time_type = typename FunctionTime< typename numbers::NumberTraits< double >::real_type >::time_type

Public Types inherited from FunctionTime< numbers::NumberTraits< double >::real_type >
using	time_type = numbers::NumberTraits< double >::real_type

Public Member Functions
	AutoDerivativeFunction (const double h, const unsigned int n_components=1, const double initial_time=0.0)

virtual	~AutoDerivativeFunction () override=default

void	set_formula (const DifferenceFormula formula=Euler)

void	set_h (const double h)

virtual Tensor< 1, dim >	gradient (const Point< dim > &p, const unsigned int component=0) const override

virtual void	vector_gradient (const Point< dim > &p, std::vector< Tensor< 1, dim >> &gradients) const override

virtual void	gradient_list (const std::vector< Point< dim >> &points, std::vector< Tensor< 1, dim >> &gradients, const unsigned int component=0) const override

virtual void	vector_gradient_list (const std::vector< Point< dim >> &points, std::vector< std::vector< Tensor< 1, dim >>> &gradients) const override

Public Member Functions inherited from Function< dim >
	Function (const unsigned int n_components=1, const time_type initial_time=0.0)

	Function (const Function &f)=default

virtual	~Function () override=0

Function &	operator= (const Function &f)

virtual double	value (const Point< dim > &p, const unsigned int component=0) const

virtual void	vector_value (const Point< dim > &p, Vector< double > &values) const

virtual void	value_list (const std::vector< Point< dim >> &points, std::vector< double > &values, const unsigned int component=0) const

virtual void	vector_value_list (const std::vector< Point< dim >> &points, std::vector< Vector< double >> &values) const

virtual void	vector_values (const std::vector< Point< dim >> &points, std::vector< std::vector< double >> &values) const

virtual void	vector_gradient (const Point< dim > &p, std::vector< Tensor< 1, dim, double >> &gradients) const

virtual void	gradient_list (const std::vector< Point< dim >> &points, std::vector< Tensor< 1, dim, double >> &gradients, const unsigned int component=0) const

virtual void	vector_gradients (const std::vector< Point< dim >> &points, std::vector< std::vector< Tensor< 1, dim, double >>> &gradients) const

virtual void	vector_gradient_list (const std::vector< Point< dim >> &points, std::vector< std::vector< Tensor< 1, dim, double >>> &gradients) const

virtual double	laplacian (const Point< dim > &p, const unsigned int component=0) const

virtual void	vector_laplacian (const Point< dim > &p, Vector< double > &values) const

virtual void	laplacian_list (const std::vector< Point< dim >> &points, std::vector< double > &values, const unsigned int component=0) const

virtual void	vector_laplacian_list (const std::vector< Point< dim >> &points, std::vector< Vector< double >> &values) const

virtual SymmetricTensor< 2, dim, double >	hessian (const Point< dim > &p, const unsigned int component=0) const

virtual void	vector_hessian (const Point< dim > &p, std::vector< SymmetricTensor< 2, dim, double >> &values) const

virtual void	hessian_list (const std::vector< Point< dim >> &points, std::vector< SymmetricTensor< 2, dim, double >> &values, const unsigned int component=0) const

virtual void	vector_hessian_list (const std::vector< Point< dim >> &points, std::vector< std::vector< SymmetricTensor< 2, dim, double >>> &values) const

std::size_t	memory_consumption () const

Public Member Functions inherited from FunctionTime< numbers::NumberTraits< double >::real_type >
	FunctionTime (const numbers::NumberTraits< double >::real_type initial_time=numbers::NumberTraits< double >::real_type(0.0))

virtual	~FunctionTime ()=default

numbers::NumberTraits< double >::real_type	get_time () const

virtual void	set_time (const numbers::NumberTraits< double >::real_type new_time)

virtual void	advance_time (const numbers::NumberTraits< double >::real_type delta_t)

Public Member Functions inherited from Subscriptor
	Subscriptor ()

	Subscriptor (const Subscriptor &)

	Subscriptor (Subscriptor &&) noexcept

virtual	~Subscriptor ()

Subscriptor &	operator= (const Subscriptor &)

Subscriptor &	operator= (Subscriptor &&) noexcept

void	subscribe (std::atomic< bool > *const validity, const std::string &identifier="") const

void	unsubscribe (std::atomic< bool > *const validity, const std::string &identifier="") const

unsigned int	n_subscriptions () const

template<typename StreamType >
void	list_subscribers (StreamType &stream) const

void	list_subscribers () const

template<class Archive >
void	serialize (Archive &ar, const unsigned int version)

Static Public Member Functions
static DifferenceFormula	get_formula_of_order (const unsigned int ord)

Static Public Member Functions inherited from Subscriptor
static ::ExceptionBase &	ExcInUse (int arg1, std::string arg2, std::string arg3)

static ::ExceptionBase &	ExcNoSubscriber (std::string arg1, std::string arg2)

Private Attributes
double	h

std::vector< Tensor< 1, dim > >	ht

DifferenceFormula	formula

Additional Inherited Members
Public Attributes inherited from Function< dim >
const unsigned int	n_components

Static Public Attributes inherited from Function< dim >
static const unsigned int	dimension

Detailed Description

template<int dim>
class AutoDerivativeFunction< dim >

This class automatically computes the gradient of a function by employing numerical difference quotients. This only, if the user function does not provide the gradient function himself.

The following example of an user defined function overloads and 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 employs numerical difference quotients.

class UserFunction: public AutoDerivativeFunction
{
  // access to one component at one point
  double value (const Point<dim>   &p,
                const unsigned int component = 0) const override
  {
    // Implementation ....
  };
};
 
UserFunction user_function;
 
// gradient by employing difference quotients.
Tensor<1,dim> grad=user_function.gradient(some_point);

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 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 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 value() function and the vector_value() function, respectively.

Furthermore note, that an object of this class does not represent the derivative of a function, like FunctionDerivative, that gives a directional derivative 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 Function class and the user defined function class.

Author: Ralf Hartmann, 2001

Definition at line 83 of file auto_derivative_function.h.

Member Enumeration Documentation

◆ DifferenceFormula

template<int dim>

enum AutoDerivativeFunction::DifferenceFormula

Names of difference formulas.

Enumerator

Euler

The symmetric Euler formula of second order:

\[ u'(t) \approx \frac{u(t+h) - u(t-h)}{2h}. \]

UpwindEuler

The upwind Euler formula of first order:

\[ u'(t) \approx \frac{u(t) - u(t-h)}{h}. \]

FourthOrder

The fourth order scheme

\[ u'(t) \approx \frac{u(t-2h) - 8u(t-h) + 8u(t+h) - u(t+2h)}{12h}. \]

Definition at line 89 of file auto_derivative_function.h.

Constructor & Destructor Documentation

◆ AutoDerivativeFunction()

template<int dim>

AutoDerivativeFunction< dim >::AutoDerivativeFunction	(	const double	h,
		const unsigned int	n_components = `1`,
		const double	initial_time = `0.0`
	)

Constructor. Takes the difference step size h. It's within the user's responsibility to choose an appropriate value here. h should be chosen taking into account the absolute value as well as the amount of local variation of the function. Setting h=1e-6 might be a good choice for functions with an absolute value of about 1, that furthermore does not vary to much.

h can be changed later using the set_h() function.

Sets DifferenceFormula formula to the default Euler formula of the set_formula() function. Change this preset formula by calling the set_formula() function.

Definition at line 26 of file auto_derivative_function.cc.

◆ ~AutoDerivativeFunction()

template<int dim>

virtual AutoDerivativeFunction< dim >::~AutoDerivativeFunction ( )

overridevirtualdefault

Virtual destructor; absolutely necessary in this case.

Member Function Documentation

◆ set_formula()

template<int dim>

void AutoDerivativeFunction< dim >::set_formula ( const DifferenceFormula formula = Euler )

Choose the difference formula. See the enum DifferenceFormula for available choices.

Definition at line 43 of file auto_derivative_function.cc.

◆ set_h()

template<int dim>

void AutoDerivativeFunction< dim >::set_h ( const double h )

Takes the difference step size h. It's within the user's responsibility to choose an appropriate value here. h should be chosen taking into account the absolute value of as well as the amount of local variation of the function. Setting h=1e-6 might be a good choice for functions with an absolute value of about 1, that furthermore does not vary to much.

Definition at line 65 of file auto_derivative_function.cc.

◆ gradient()

template<int dim>

Tensor< 1, dim > AutoDerivativeFunction< dim >::gradient	(	const Point< dim > &	p,
		const unsigned int	component = `0`
	)		const

overridevirtual

Return the gradient of the specified component of the function at the given point.

Compute numerical difference quotients using the preset DifferenceFormula.

Reimplemented from Function< dim >.

Definition at line 75 of file auto_derivative_function.cc.

◆ vector_gradient()

template<int dim>

void AutoDerivativeFunction< dim >::vector_gradient	(	const Point< dim > &	p,
		std::vector< Tensor< 1, dim >> &	gradients
	)		const

overridevirtual

Return the gradient of all components of the function at the given point.

Compute numerical difference quotients using the preset DifferenceFormula.

Definition at line 127 of file auto_derivative_function.cc.

◆ gradient_list()

template<int dim>

void AutoDerivativeFunction< dim >::gradient_list	(	const std::vector< Point< dim >> &	points,
		std::vector< Tensor< 1, dim >> &	gradients,
		const unsigned int	component = `0`
	)		const

overridevirtual

Set gradients to the gradients of the specified component of the function at the points. It is assumed that gradients already has the right size, i.e. the same size as the points array.

Compute numerical difference quotients using the preset DifferenceFormula.

Definition at line 204 of file auto_derivative_function.cc.

◆ vector_gradient_list()

template<int dim>

void AutoDerivativeFunction< dim >::vector_gradient_list	(	const std::vector< Point< dim >> &	points,
		std::vector< std::vector< Tensor< 1, dim >>> &	gradients
	)		const

overridevirtual

Set gradients to the gradients of the function at the points, for all components. It is assumed that gradients already has the right size, i.e. the same size as the points array.

The outer loop over gradients is over the points in the list, the inner loop over the different components of the function.

Compute numerical difference quotients using the preset DifferenceFormula.

Definition at line 268 of file auto_derivative_function.cc.