// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 1999 - 2025 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_tensor_function_h #define dealii_tensor_function_h #include #include #include #include #include #include #include #include DEAL_II_NAMESPACE_OPEN /** * This class is a model for a tensor valued function. The interface of the * class is mostly the same as that for the Function class, with the exception * that it does not support vector-valued functions with several components, * but that the return type is always tensor-valued. The returned values of * the evaluation of objects of this type are always whole tensors, while for * the Function class, one can ask for a specific component only, or * use the vector_value function, which however does not return the * value, but rather writes it into the address provided by its second * argument. The reason for the different behavior of the classes is that in * the case of tensor valued functions, the size of the argument is known to * the compiler a priori, such that the correct amount of memory can be * allocated on the stack for the return value; on the other hand, for the * vector valued functions, the size is not known to the compiler, so memory * has to be allocated on the heap, resulting in relatively expensive copy * operations. One can therefore consider this class a specialization of the * Function class for which the size is known. An additional benefit * is that tensors of arbitrary rank can be returned, not only vectors, as for * them the size can be determined similarly simply. * * @ingroup functions */ template class TensorFunction : public FunctionTime::real_type>, public EnableObserverPointer { public: /** * Alias for the return types of the value function. */ using value_type = Tensor; /** * Alias for the return types of the gradient functions. */ using gradient_type = Tensor; /** * The scalar-valued real type used for representing time. */ using time_type = typename FunctionTime< typename numbers::NumberTraits::real_type>::time_type; /** * Constructor. May take an initial value for the time variable, which * defaults to zero. */ TensorFunction(const time_type initial_time = time_type(0.0)); /** * Virtual destructor; absolutely necessary in this case, as classes are * usually not used by their true type, but rather through pointers to this * base class. */ virtual ~TensorFunction() override = default; /** * Return the value of the function at the given point. */ virtual value_type value(const Point &p) const; /** * Set values to the point values of the function at the * points. It is assumed that values already has the * right size, i.e. the same size as the points array. */ virtual void value_list(const std::vector> &points, std::vector &values) const; /** * Return the gradient of the function at the given point. */ virtual gradient_type gradient(const Point &p) const; /** * Set gradients to the gradients of the function at the * points. It is assumed that values already has the * right size, i.e. the same size as the points array. */ virtual void gradient_list(const std::vector> &points, std::vector &gradients) const; }; /** * Provide a tensor valued function which always returns a constant tensor * value. Obviously, all derivatives of this function are zero. * * @ingroup functions */ template class ConstantTensorFunction : public TensorFunction { public: /** * The scalar-valued real type used for representing time. */ using time_type = typename TensorFunction::time_type; /** * Constructor; takes the constant tensor value as an argument. The * reference value is copied internally. * * An initial value for the time variable may be specified, otherwise it * defaults to zero. */ ConstantTensorFunction(const dealii::Tensor &value, const time_type initial_time = 0.0); virtual ~ConstantTensorFunction() override = default; virtual typename dealii::TensorFunction::value_type value(const Point &p) const override; virtual void value_list( const std::vector> &points, std::vector::value_type> &values) const override; virtual typename dealii::TensorFunction::gradient_type gradient(const Point &p) const override; virtual void gradient_list( const std::vector> &points, std::vector< typename dealii::TensorFunction::gradient_type> &gradients) const override; private: const dealii::Tensor _value; }; /** * Provide a tensor valued function which always returns zero. Obviously, all * derivatives of this function are zero. * * @ingroup functions */ template class ZeroTensorFunction : public ConstantTensorFunction { public: /** * The scalar-valued real type used for representing time. */ using time_type = typename ConstantTensorFunction::time_type; /** * Constructor. * * An initial value for the time variable may be specified, otherwise it * defaults to zero. */ ZeroTensorFunction(const time_type initial_time = 0.0); }; DEAL_II_NAMESPACE_CLOSE #endif