fe_values.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 - 2024 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_fe_values_h
#define dealii_fe_values_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/derivative_form.h>
#include <deal.II/base/enable_observer_pointer.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/point.h>
#include <deal.II/base/quadrature.h>
#include <deal.II/base/std_cxx20/iota_view.h>
#include <deal.II/base/symmetric_tensor.h>
 
#include <deal.II/dofs/dof_accessor.h>
#include <deal.II/dofs/dof_handler.h>
 
#include <deal.II/fe/fe.h>
#include <deal.II/fe/fe_update_flags.h>
#include <deal.II/fe/fe_values_base.h>
#include <deal.II/fe/fe_values_extractors.h>
#include <deal.II/fe/mapping.h>
#include <deal.II/fe/mapping_related_data.h>
 
#include <deal.II/grid/tria.h>
#include <deal.II/grid/tria_iterator.h>
 
#include <deal.II/hp/q_collection.h>
 
#include <deal.II/lac/read_vector.h>
 
#include <algorithm>
#include <memory>
#include <type_traits>
 
DEAL_II_NAMESPACE_OPEN
 
template <int dim, int spacedim = dim>
class FEValues : public FEValuesBase<dim, spacedim>
{
public:
  static constexpr unsigned int integral_dimension = dim;
 
  FEValues(const Mapping<dim, spacedim>       &mapping,
           const FiniteElement<dim, spacedim> &fe,
           const Quadrature<dim>              &quadrature,
           const UpdateFlags                   update_flags);
 
  FEValues(const Mapping<dim, spacedim>       &mapping,
           const FiniteElement<dim, spacedim> &fe,
           const hp::QCollection<dim>         &quadrature,
           const UpdateFlags                   update_flags);
 
  FEValues(const FiniteElement<dim, spacedim> &fe,
           const Quadrature<dim>              &quadrature,
           const UpdateFlags                   update_flags);
 
  FEValues(const FiniteElement<dim, spacedim> &fe,
           const hp::QCollection<dim>         &quadrature,
           const UpdateFlags                   update_flags);
 
  template <bool level_dof_access>
  void
  reinit(
    const TriaIterator<DoFCellAccessor<dim, spacedim, level_dof_access>> &cell);
 
  void
  reinit(const typename Triangulation<dim, spacedim>::cell_iterator &cell);
 
  const Quadrature<dim> &
  get_quadrature() const;
 
  std::size_t
  memory_consumption() const;
 
  const FEValues<dim, spacedim> &
  get_present_fe_values() const;
 
private:
  const Quadrature<dim> quadrature;
 
  void
  initialize(const UpdateFlags update_flags);
 
  void
  do_reinit();
};
 
 
template <int dim, int spacedim = dim>
class FEFaceValuesBase : public FEValuesBase<dim, spacedim>
{
public:
  static constexpr unsigned int integral_dimension = dim - 1;
 
  FEFaceValuesBase(const unsigned int                  dofs_per_cell,
                   const UpdateFlags                   update_flags,
                   const Mapping<dim, spacedim>       &mapping,
                   const FiniteElement<dim, spacedim> &fe,
                   const Quadrature<dim - 1>          &quadrature);
 
  FEFaceValuesBase(const unsigned int                  dofs_per_cell,
                   const UpdateFlags                   update_flags,
                   const Mapping<dim, spacedim>       &mapping,
                   const FiniteElement<dim, spacedim> &fe,
                   const hp::QCollection<dim - 1>     &quadrature);
 
  const Tensor<1, spacedim> &
  boundary_form(const unsigned int q_point) const;
 
  const std::vector<Tensor<1, spacedim>> &
  get_boundary_forms() const;
 
  unsigned int
  get_face_number() const;
 
  unsigned int
  get_face_index() const;
 
  const Quadrature<dim - 1> &
  get_quadrature() const;
 
  std::size_t
  memory_consumption() const;
 
protected:
  unsigned int present_face_no;
 
  unsigned int present_face_index;
 
  const hp::QCollection<dim - 1> quadrature;
};
 
 
 
template <int dim, int spacedim = dim>
class FEFaceValues : public FEFaceValuesBase<dim, spacedim>
{
public:
  static constexpr unsigned int dimension = dim;
 
  static constexpr unsigned int space_dimension = spacedim;
 
  static constexpr unsigned int integral_dimension = dim - 1;
 
  FEFaceValues(const Mapping<dim, spacedim>       &mapping,
               const FiniteElement<dim, spacedim> &fe,
               const Quadrature<dim - 1>          &quadrature,
               const UpdateFlags                   update_flags);
 
  FEFaceValues(const Mapping<dim, spacedim>       &mapping,
               const FiniteElement<dim, spacedim> &fe,
               const hp::QCollection<dim - 1>     &quadrature,
               const UpdateFlags                   update_flags);
 
  FEFaceValues(const FiniteElement<dim, spacedim> &fe,
               const Quadrature<dim - 1>          &quadrature,
               const UpdateFlags                   update_flags);
 
  FEFaceValues(const FiniteElement<dim, spacedim> &fe,
               const hp::QCollection<dim - 1>     &quadrature,
               const UpdateFlags                   update_flags);
 
  template <bool level_dof_access>
  void
  reinit(
    const TriaIterator<DoFCellAccessor<dim, spacedim, level_dof_access>> &cell,
    const unsigned int face_no);
 
  template <bool level_dof_access>
  void
  reinit(
    const TriaIterator<DoFCellAccessor<dim, spacedim, level_dof_access>> &cell,
    const typename Triangulation<dim, spacedim>::face_iterator           &face);
 
  void
  reinit(const typename Triangulation<dim, spacedim>::cell_iterator &cell,
         const unsigned int                                          face_no);
 
  /*
   * Reinitialize the gradients, Jacobi determinants, etc for the given face
   * on a given cell of type "iterator into a Triangulation object", and the
   * given finite element. Since iterators into a triangulation alone only
   * convey information about the geometry of a cell, but not about degrees of
   * freedom possibly associated with this cell, you will not be able to call
   * some functions of this class if they need information about degrees of
   * freedom. These functions are, above all, the
   * <tt>get_function_value/gradients/hessians/third_derivatives</tt>
   * functions. If you want to call these functions, you have to call the @p
   * reinit variants that take iterators into DoFHandler or other DoF handler
   * type objects.
   *
   * @note @p face must be one of @p cell's face iterators.
   */
  void
  reinit(const typename Triangulation<dim, spacedim>::cell_iterator &cell,
         const typename Triangulation<dim, spacedim>::face_iterator &face);
 
  const FEFaceValues<dim, spacedim> &
  get_present_fe_values() const;
 
private:
  void
  initialize(const UpdateFlags update_flags);
 
  void
  do_reinit(const unsigned int face_no);
};
 
 
template <int dim, int spacedim = dim>
class FESubfaceValues : public FEFaceValuesBase<dim, spacedim>
{
public:
  static constexpr unsigned int dimension = dim;
 
  static constexpr unsigned int space_dimension = spacedim;
 
  static constexpr unsigned int integral_dimension = dim - 1;
 
  FESubfaceValues(const Mapping<dim, spacedim>       &mapping,
                  const FiniteElement<dim, spacedim> &fe,
                  const Quadrature<dim - 1>          &face_quadrature,
                  const UpdateFlags                   update_flags);
 
  FESubfaceValues(const Mapping<dim, spacedim>       &mapping,
                  const FiniteElement<dim, spacedim> &fe,
                  const hp::QCollection<dim - 1>     &face_quadrature,
                  const UpdateFlags                   update_flags);
 
  FESubfaceValues(const FiniteElement<dim, spacedim> &fe,
                  const Quadrature<dim - 1>          &face_quadrature,
                  const UpdateFlags                   update_flags);
 
  FESubfaceValues(const FiniteElement<dim, spacedim> &fe,
                  const hp::QCollection<dim - 1>     &face_quadrature,
                  const UpdateFlags                   update_flags);
 
  template <bool level_dof_access>
  void
  reinit(
    const TriaIterator<DoFCellAccessor<dim, spacedim, level_dof_access>> &cell,
    const unsigned int face_no,
    const unsigned int subface_no);
 
  template <bool level_dof_access>
  void
  reinit(
    const TriaIterator<DoFCellAccessor<dim, spacedim, level_dof_access>> &cell,
    const typename Triangulation<dim, spacedim>::face_iterator           &face,
    const typename Triangulation<dim, spacedim>::face_iterator &subface);
 
  void
  reinit(const typename Triangulation<dim, spacedim>::cell_iterator &cell,
         const unsigned int                                          face_no,
         const unsigned int subface_no);
 
  void
  reinit(const typename Triangulation<dim, spacedim>::cell_iterator &cell,
         const typename Triangulation<dim, spacedim>::face_iterator &face,
         const typename Triangulation<dim, spacedim>::face_iterator &subface);
 
  const FESubfaceValues<dim, spacedim> &
  get_present_fe_values() const;
 
  DeclException0(ExcReinitCalledWithBoundaryFace);
 
  DeclException0(ExcFaceHasNoSubfaces);
 
private:
  void
  initialize(const UpdateFlags update_flags);
 
  void
  do_reinit(const unsigned int face_no, const unsigned int subface_no);
};
 
 
#ifndef DOXYGEN
 
 
/*--------------------- Inline functions: FEValues --------------------------*/
 
 
template <int dim, int spacedim>
inline const Quadrature<dim> &
FEValues<dim, spacedim>::get_quadrature() const
{
  return quadrature;
}
 
 
 
template <int dim, int spacedim>
inline const FEValues<dim, spacedim> &
FEValues<dim, spacedim>::get_present_fe_values() const
{
  return *this;
}
 
 
/*---------------------- Inline functions: FEFaceValuesBase -----------------*/
 
 
template <int dim, int spacedim>
inline unsigned int
FEFaceValuesBase<dim, spacedim>::get_face_number() const
{
  return present_face_no;
}
 
 
template <int dim, int spacedim>
inline unsigned int
FEFaceValuesBase<dim, spacedim>::get_face_index() const
{
  return present_face_index;
}
 
 
/*----------------------- Inline functions: FE*FaceValues -------------------*/
 
template <int dim, int spacedim>
inline const Quadrature<dim - 1> &
FEFaceValuesBase<dim, spacedim>::get_quadrature() const
{
  return quadrature[quadrature.size() == 1 ? 0 : present_face_no];
}
 
 
 
template <int dim, int spacedim>
inline const FEFaceValues<dim, spacedim> &
FEFaceValues<dim, spacedim>::get_present_fe_values() const
{
  return *this;
}
 
 
 
template <int dim, int spacedim>
inline const FESubfaceValues<dim, spacedim> &
FESubfaceValues<dim, spacedim>::get_present_fe_values() const
{
  return *this;
}
 
 
 
template <int dim, int spacedim>
inline const Tensor<1, spacedim> &
FEFaceValuesBase<dim, spacedim>::boundary_form(const unsigned int q_point) const
{
  AssertIndexRange(q_point, this->mapping_output.boundary_forms.size());
  Assert(this->update_flags & update_boundary_forms,
         (typename FEValuesBase<dim, spacedim>::ExcAccessToUninitializedField(
           "update_boundary_forms")));
 
  return this->mapping_output.boundary_forms[q_point];
}
 
#endif // DOXYGEN
 
DEAL_II_NAMESPACE_CLOSE
 
#endif