function.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
// Copyright (C) 1998 - 2025 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Detailed license information governing the source code and contributions
// can be found in LICENSE.md and CONTRIBUTING.md at the top level directory.
//
// -----------------------------------------------------------------------------
 
#ifndef dealii_function_h
#define dealii_function_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/enable_observer_pointer.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/function_time.h>
#include <deal.II/base/numbers.h>
#include <deal.II/base/point.h>
#include <deal.II/base/symmetric_tensor.h>
#include <deal.II/base/tensor.h>
 
#include <functional>
#include <vector>
 
DEAL_II_NAMESPACE_OPEN
 
// Forward declarations
#ifndef DOXYGEN
template <typename number>
class Vector;
template <int rank, int dim, typename Number>
class TensorFunction;
#endif
 
template <int dim, typename RangeNumberType = double>
class Function : public FunctionTime<
                   typename numbers::NumberTraits<RangeNumberType>::real_type>,
                 public EnableObserverPointer
{
public:
  static constexpr unsigned int dimension = dim;
 
  const unsigned int n_components;
 
  using time_type = typename FunctionTime<
    typename numbers::NumberTraits<RangeNumberType>::real_type>::time_type;
 
  explicit 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 RangeNumberType
  value(const Point<dim> &p, const unsigned int component = 0) const;
 
  virtual void
  vector_value(const Point<dim> &p, Vector<RangeNumberType> &values) const;
 
  virtual void
  value_list(const std::vector<Point<dim>> &points,
             std::vector<RangeNumberType>  &values,
             const unsigned int             component = 0) const;
 
  virtual void
  vector_value_list(const std::vector<Point<dim>>        &points,
                    std::vector<Vector<RangeNumberType>> &values) const;
 
  virtual void
  vector_values(const std::vector<Point<dim>>             &points,
                std::vector<std::vector<RangeNumberType>> &values) const;
 
  virtual Tensor<1, dim, RangeNumberType>
  gradient(const Point<dim> &p, const unsigned int component = 0) const;
 
  virtual void
  vector_gradient(
    const Point<dim>                             &p,
    std::vector<Tensor<1, dim, RangeNumberType>> &gradients) const;
 
  virtual void
  gradient_list(const std::vector<Point<dim>>                &points,
                std::vector<Tensor<1, dim, RangeNumberType>> &gradients,
                const unsigned int component = 0) const;
 
  virtual void
  vector_gradients(
    const std::vector<Point<dim>>                             &points,
    std::vector<std::vector<Tensor<1, dim, RangeNumberType>>> &gradients) const;
 
  virtual void
  vector_gradient_list(
    const std::vector<Point<dim>>                             &points,
    std::vector<std::vector<Tensor<1, dim, RangeNumberType>>> &gradients) const;
 
  virtual RangeNumberType
  laplacian(const Point<dim> &p, const unsigned int component = 0) const;
 
  virtual void
  vector_laplacian(const Point<dim> &p, Vector<RangeNumberType> &values) const;
 
  virtual void
  laplacian_list(const std::vector<Point<dim>> &points,
                 std::vector<RangeNumberType>  &values,
                 const unsigned int             component = 0) const;
 
  virtual void
  vector_laplacian_list(const std::vector<Point<dim>>        &points,
                        std::vector<Vector<RangeNumberType>> &values) const;
 
  virtual SymmetricTensor<2, dim, RangeNumberType>
  hessian(const Point<dim> &p, const unsigned int component = 0) const;
 
  virtual void
  vector_hessian(
    const Point<dim>                                      &p,
    std::vector<SymmetricTensor<2, dim, RangeNumberType>> &values) const;
 
  virtual void
  hessian_list(const std::vector<Point<dim>>                         &points,
               std::vector<SymmetricTensor<2, dim, RangeNumberType>> &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, RangeNumberType>>> &values)
    const;
 
 
  virtual std::size_t
  memory_consumption() const;
};
 
 
namespace Functions
{
  template <int dim, typename RangeNumberType = double>
  class ConstantFunction : public Function<dim, RangeNumberType>
  {
  public:
    explicit ConstantFunction(const RangeNumberType value,
                              const unsigned int    n_components = 1);
 
    explicit ConstantFunction(const std::vector<RangeNumberType> &values);
 
    explicit ConstantFunction(const Vector<RangeNumberType> &values);
 
    ConstantFunction(const RangeNumberType *begin_ptr,
                     const unsigned int     n_components);
 
    virtual RangeNumberType
    value(const Point<dim> &p, const unsigned int component = 0) const override;
 
    virtual void
    vector_value(const Point<dim>        &p,
                 Vector<RangeNumberType> &return_value) const override;
 
    virtual void
    value_list(const std::vector<Point<dim>> &points,
               std::vector<RangeNumberType>  &return_values,
               const unsigned int             component = 0) const override;
 
    virtual void
    vector_value_list(
      const std::vector<Point<dim>>        &points,
      std::vector<Vector<RangeNumberType>> &return_values) const override;
 
    virtual Tensor<1, dim, RangeNumberType>
    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, RangeNumberType>> &gradients) const override;
 
    virtual void
    gradient_list(const std::vector<Point<dim>>                &points,
                  std::vector<Tensor<1, dim, RangeNumberType>> &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, RangeNumberType>>> &gradients)
      const override;
 
    virtual SymmetricTensor<2, dim, RangeNumberType>
    hessian(const Point<dim>  &point,
            const unsigned int component = 0) const override;
 
    virtual RangeNumberType
    laplacian(const Point<dim>  &point,
              const unsigned int component = 0) const override;
 
    virtual std::size_t
    memory_consumption() const override;
 
  protected:
    std::vector<RangeNumberType> function_value_vector;
  };
 
 
 
  template <int dim, typename RangeNumberType = double>
  class ZeroFunction : public ConstantFunction<dim, RangeNumberType>
  {
  public:
    explicit ZeroFunction(const unsigned int n_components = 1);
  };
 
  template <int dim, typename RangeNumberType = double>
  class IdentityFunction : public Function<dim, RangeNumberType>
  {
  public:
    IdentityFunction();
 
    virtual RangeNumberType
    value(const Point<dim> &p, const unsigned int component = 0) const override;
 
    virtual Tensor<1, dim, RangeNumberType>
    gradient(const Point<dim>  &p,
             const unsigned int component = 0) const override;
 
    virtual RangeNumberType
    laplacian(const Point<dim>  &p,
              const unsigned int component = 0) const override;
 
    virtual SymmetricTensor<2, dim, RangeNumberType>
    hessian(const Point<dim>  &p,
            const unsigned int component = 0) const override;
  };
} // namespace Functions
 
template <int dim, typename RangeNumberType = double>
class ComponentSelectFunction
  : public Functions::ConstantFunction<dim, RangeNumberType>
{
public:
  ComponentSelectFunction(const unsigned int    selected,
                          const RangeNumberType value,
                          const unsigned int    n_components);
 
  ComponentSelectFunction(const unsigned int selected,
                          const unsigned int n_components);
 
  ComponentSelectFunction(const std::pair<unsigned int, unsigned int> &selected,
                          const unsigned int n_components);
 
 
  virtual void
  substitute_function_value_with(
    const Functions::ConstantFunction<dim, RangeNumberType> &f);
 
  virtual void
  vector_value(const Point<dim>        &p,
               Vector<RangeNumberType> &return_value) const override;
 
  virtual void
  vector_value_list(
    const std::vector<Point<dim>>        &points,
    std::vector<Vector<RangeNumberType>> &values) const override;
 
  virtual std::size_t
  memory_consumption() const override;
 
protected:
  const std::pair<unsigned int, unsigned int> selected_components;
};
 
 
 
template <int dim, typename RangeNumberType = double>
class ScalarFunctionFromFunctionObject : public Function<dim, RangeNumberType>
{
public:
  explicit ScalarFunctionFromFunctionObject(
    const std::function<RangeNumberType(const Point<dim> &)> &function_object);
 
  explicit ScalarFunctionFromFunctionObject(
    const std::function<RangeNumberType(const double, const Point<dim> &)>
      &function_object_t);
 
  virtual RangeNumberType
  value(const Point<dim> &p, const unsigned int component = 0) const override;
 
private:
  const std::function<RangeNumberType(const double, const Point<dim> &)>
    function_object;
};
 
 
 
template <int dim, typename RangeNumberType = double>
class VectorFunctionFromScalarFunctionObject
  : public Function<dim, RangeNumberType>
{
public:
  VectorFunctionFromScalarFunctionObject(
    const std::function<RangeNumberType(const Point<dim> &)> &function_object,
    const unsigned int selected_component,
    const unsigned int n_components);
 
  virtual RangeNumberType
  value(const Point<dim> &p, const unsigned int component = 0) const override;
 
  virtual void
  vector_value(const Point<dim>        &p,
               Vector<RangeNumberType> &values) const override;
 
private:
  const std::function<RangeNumberType(const Point<dim> &)> function_object;
 
  const unsigned int selected_component;
};
 
 
template <int dim, typename RangeNumberType = double>
class FunctionFromFunctionObjects : public Function<dim, RangeNumberType>
{
public:
  explicit FunctionFromFunctionObjects(const unsigned int n_components = 1,
                                       const double       initial_time = 0);
 
  explicit FunctionFromFunctionObjects(
    const std::vector<std::function<RangeNumberType(const Point<dim> &)>>
                &values,
    const double initial_time = 0.0);
 
  explicit FunctionFromFunctionObjects(
    const std::function<RangeNumberType(const Point<dim> &, const unsigned int)>
                      &values,
    const unsigned int n_components,
    const double       initial_time = 0.0);
 
  FunctionFromFunctionObjects(
    const std::vector<std::function<RangeNumberType(const Point<dim> &)>>
      &values,
    const std::vector<
      std::function<Tensor<1, dim, RangeNumberType>(const Point<dim> &)>>
                &gradients,
    const double initial_time = 0.0);
 
 
  virtual RangeNumberType
  value(const Point<dim> &p, const unsigned int component = 0) const override;
 
  virtual Tensor<1, dim, RangeNumberType>
  gradient(const Point<dim>  &p,
           const unsigned int component = 0) const override;
 
  void
  set_function_values(
    const std::vector<std::function<RangeNumberType(const Point<dim> &)>>
      &values);
 
  void
  set_function_gradients(
    const std::vector<
      std::function<Tensor<1, dim, RangeNumberType>(const Point<dim> &)>>
      &gradients);
 
private:
  std::function<RangeNumberType(const Point<dim> &, const unsigned int)>
    function_values;
 
  std::function<Tensor<1, dim, RangeNumberType>(const Point<dim> &,
                                                const unsigned int)>
    function_gradients;
};
 
 
template <int dim, typename RangeNumberType = double>
class VectorFunctionFromTensorFunction : public Function<dim, RangeNumberType>
{
public:
  explicit VectorFunctionFromTensorFunction(
    const TensorFunction<1, dim, RangeNumberType> &tensor_function,
    const unsigned int                             selected_component = 0,
    const unsigned int                             n_components       = dim);
 
  virtual ~VectorFunctionFromTensorFunction() override = default;
 
  virtual RangeNumberType
  value(const Point<dim> &p, const unsigned int component = 0) const override;
 
  virtual void
  vector_value(const Point<dim>        &p,
               Vector<RangeNumberType> &values) const override;
 
  virtual void
  vector_value_list(
    const std::vector<Point<dim>>        &points,
    std::vector<Vector<RangeNumberType>> &value_list) const override;
 
  virtual Tensor<1, dim, RangeNumberType>
  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, RangeNumberType>> &gradients) const override;
 
  virtual void
  gradient_list(const std::vector<Point<dim>>                &points,
                std::vector<Tensor<1, dim, RangeNumberType>> &gradients,
                const unsigned int component = 0) const override;
 
  virtual void
  vector_gradients(const std::vector<Point<dim>> &points,
                   std::vector<std::vector<Tensor<1, dim, RangeNumberType>>>
                     &gradients) const override;
 
  virtual void
  vector_gradient_list(const std::vector<Point<dim>> &points,
                       std::vector<std::vector<Tensor<1, dim, RangeNumberType>>>
                         &gradients) const override;
 
private:
  const TensorFunction<1, dim, RangeNumberType> &tensor_function;
 
  const unsigned int selected_component;
};
 
 
template <int dim, typename RangeNumberType = double>
class VectorFunctionFromTensorFunctionObject
  : public Function<dim, RangeNumberType>
{
public:
  explicit VectorFunctionFromTensorFunctionObject(
    const std::function<Tensor<1, dim, RangeNumberType>(const Point<dim> &)>
                      &tensor_function_object,
    const unsigned int selected_component = 0,
    const unsigned int n_components       = dim);
 
  virtual ~VectorFunctionFromTensorFunctionObject() override = default;
 
  virtual RangeNumberType
  value(const Point<dim> &p, const unsigned int component = 0) const override;
 
  virtual void
  vector_value(const Point<dim>        &p,
               Vector<RangeNumberType> &values) const override;
 
  virtual void
  vector_value_list(
    const std::vector<Point<dim>>        &points,
    std::vector<Vector<RangeNumberType>> &value_list) const override;
 
private:
  const std::function<Tensor<1, dim, RangeNumberType>(const Point<dim> &)>
    tensor_function_object;
 
  const unsigned int selected_component;
};
 
 
#ifndef DOXYGEN
// icc 2018 complains about an undefined reference
// if we put this in the templates.h file
//
// The destructor is pure virtual so we can't default it
// in the declaration.
template <int dim, typename RangeNumberType>
inline Function<dim, RangeNumberType>::~Function() = default;
#endif
 
 
DEAL_II_NAMESPACE_CLOSE
 
#endif