mapping.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) 2001 - 2026 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_mapping_h
#define dealii_mapping_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/array_view.h>
#include <deal.II/base/derivative_form.h>
 
#include <deal.II/fe/fe_update_flags.h>
#include <deal.II/fe/mapping_related_data.h>
 
#include <deal.II/grid/tria.h>
 
#include <deal.II/hp/q_collection.h>
 
#include <deal.II/non_matching/immersed_surface_quadrature.h>
 
#include <boost/container/small_vector.hpp>
 
#include <array>
#include <cmath>
#include <memory>
 
DEAL_II_NAMESPACE_OPEN
 
template <typename ElementType, typename MemorySpaceType>
class ArrayView;
template <int dim>
class Quadrature;
template <int dim, int spacedim>
class FEValues;
template <int dim, int spacedim>
class FEValuesBase;
template <int dim, int spacedim>
class FEValues;
template <int dim, int spacedim>
class FEFaceValues;
template <int dim, int spacedim>
class FESubfaceValues;
namespace NonMatching
{
  template <int dim>
  class FEImmersedSurfaceValues;
  namespace internal
  {
    template <int dim, int spacedim>
    class ComputeMappingDataHelper;
  }
  template <int dim, int spacedim, typename Number>
  class MappingInfo;
} // namespace NonMatching
 
 
enum MappingKind
{
  mapping_none = 0x0000,
 
  mapping_covariant = 0x0001,
 
  mapping_contravariant = 0x0002,
 
  mapping_covariant_gradient = 0x0003,
 
  mapping_contravariant_gradient = 0x0004,
 
  mapping_piola = 0x0100,
 
  mapping_piola_gradient = 0x0101,
 
  mapping_nedelec = 0x0200,
 
  mapping_raviart_thomas = 0x0300,
 
  mapping_bdm = mapping_raviart_thomas,
 
  mapping_covariant_hessian,
 
  mapping_contravariant_hessian,
 
  mapping_piola_hessian
};
 
 
template <int dim, int spacedim = dim>
class Mapping : public EnableObserverPointer
{
public:
  virtual ~Mapping() override = default;
 
  virtual std::unique_ptr<Mapping<dim, spacedim>>
  clone() const = 0;
 
  virtual boost::container::small_vector<Point<spacedim>,
#ifndef _MSC_VER
                                         ReferenceCells::max_n_vertices<dim>()
#else
                                         GeometryInfo<dim>::vertices_per_cell
#endif
                                         >
  get_vertices(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell) const;
 
  boost::container::small_vector<Point<spacedim>,
#ifndef _MSC_VER
                                 ReferenceCells::max_n_vertices<dim - 1>()
#else
                                 GeometryInfo<dim - 1>::vertices_per_cell
#endif
                                 >
  get_vertices(const typename Triangulation<dim, spacedim>::cell_iterator &cell,
               const unsigned int face_no) const;
 
  virtual Point<spacedim>
  get_center(const typename Triangulation<dim, spacedim>::cell_iterator &cell,
             const bool map_barycenter_of_reference_cell = true) const;
 
  virtual BoundingBox<spacedim>
  get_bounding_box(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell) const;
 
  virtual bool
  preserves_vertex_locations() const = 0;
 
  virtual bool
  is_compatible_with(const ReferenceCell<dim> &reference_cell) const = 0;
 
  virtual Point<spacedim>
  transform_unit_to_real_cell(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell,
    const Point<dim>                                           &p) const = 0;
 
  virtual Point<dim>
  transform_real_to_unit_cell(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell,
    const Point<spacedim>                                      &p) const = 0;
 
  virtual void
  transform_points_real_to_unit_cell(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell,
    const ArrayView<const Point<spacedim>>                     &real_points,
    const ArrayView<Point<dim>> &unit_points) const;
 
  Point<dim - 1>
  project_real_point_to_unit_point_on_face(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell,
    const unsigned int                                          face_no,
    const Point<spacedim>                                      &p) const;
 
  DeclException0(ExcInvalidData);
 
 
  DeclExceptionMsg(
    ExcTransformationFailed,
    "Computing the mapping between a real space point and a point in reference "
    "space failed, typically because the given point lies outside the cell "
    "where the inverse mapping is not unique.");
 
  DeclException3(ExcDistortedMappedCell,
                 Point<spacedim>,
                 double,
                 int,
                 << "The image of the mapping applied to cell with center ["
                 << arg1 << "] is distorted. The cell geometry or the "
                 << "mapping are invalid, giving a non-positive volume "
                 << "fraction of " << arg2 << " in quadrature point " << arg3
                 << '.');
 
public:
  class InternalDataBase
  {
  public:
    InternalDataBase();
 
    InternalDataBase(const InternalDataBase &) = delete;
 
    virtual void
    reinit(const UpdateFlags update_flags, const Quadrature<dim> &quadrature);
 
    virtual ~InternalDataBase() = default;
 
    UpdateFlags update_each;
 
    virtual std::size_t
    memory_consumption() const;
  };
 
protected:
  virtual UpdateFlags
  requires_update_flags(const UpdateFlags update_flags) const = 0;
 
  virtual std::unique_ptr<InternalDataBase>
  get_data(const UpdateFlags      update_flags,
           const Quadrature<dim> &quadrature) const = 0;
 
  virtual std::unique_ptr<InternalDataBase>
  get_face_data(const UpdateFlags               update_flags,
                const hp::QCollection<dim - 1> &quadrature) const;
 
  virtual std::unique_ptr<InternalDataBase>
  get_face_data(const UpdateFlags          update_flags,
                const Quadrature<dim - 1> &quadrature) const;
 
  virtual std::unique_ptr<InternalDataBase>
  get_subface_data(const UpdateFlags          update_flags,
                   const Quadrature<dim - 1> &quadrature) const = 0;
 
  virtual CellSimilarity::Similarity
  fill_fe_values(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell,
    const CellSimilarity::Similarity                            cell_similarity,
    const Quadrature<dim>                                      &quadrature,
    const typename Mapping<dim, spacedim>::InternalDataBase    &internal_data,
    internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
      &output_data) const = 0;
 
  virtual void
  fill_fe_face_values(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell,
    const unsigned int                                          face_no,
    const hp::QCollection<dim - 1>                             &quadrature,
    const typename Mapping<dim, spacedim>::InternalDataBase    &internal_data,
    internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
      &output_data) const;
 
  virtual void
  fill_fe_face_values(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell,
    const unsigned int                                          face_no,
    const Quadrature<dim - 1>                                  &quadrature,
    const typename Mapping<dim, spacedim>::InternalDataBase    &internal_data,
    internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
      &output_data) const;
 
  virtual void
  fill_fe_subface_values(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell,
    const unsigned int                                          face_no,
    const unsigned int                                          subface_no,
    const Quadrature<dim - 1>                                  &quadrature,
    const typename Mapping<dim, spacedim>::InternalDataBase    &internal_data,
    internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
      &output_data) const = 0;
 
  virtual void
  fill_fe_immersed_surface_values(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell,
    const NonMatching::ImmersedSurfaceQuadrature<dim>          &quadrature,
    const typename Mapping<dim, spacedim>::InternalDataBase    &internal_data,
    internal::FEValuesImplementation::MappingRelatedData<dim, spacedim>
      &output_data) const;
 
public:
  virtual void
  transform(const ArrayView<const Tensor<1, dim>>                   &input,
            const MappingKind                                        kind,
            const typename Mapping<dim, spacedim>::InternalDataBase &internal,
            const ArrayView<Tensor<1, spacedim>> &output) const = 0;
 
  virtual void
  transform(const ArrayView<const DerivativeForm<1, dim, spacedim>> &input,
            const MappingKind                                        kind,
            const typename Mapping<dim, spacedim>::InternalDataBase &internal,
            const ArrayView<Tensor<2, spacedim>> &output) const = 0;
 
  virtual void
  transform(const ArrayView<const Tensor<2, dim>>                   &input,
            const MappingKind                                        kind,
            const typename Mapping<dim, spacedim>::InternalDataBase &internal,
            const ArrayView<Tensor<2, spacedim>> &output) const = 0;
 
  virtual void
  transform(const ArrayView<const DerivativeForm<2, dim, spacedim>> &input,
            const MappingKind                                        kind,
            const typename Mapping<dim, spacedim>::InternalDataBase &internal,
            const ArrayView<Tensor<3, spacedim>> &output) const = 0;
 
  virtual void
  transform(const ArrayView<const Tensor<3, dim>>                   &input,
            const MappingKind                                        kind,
            const typename Mapping<dim, spacedim>::InternalDataBase &internal,
            const ArrayView<Tensor<3, spacedim>> &output) const = 0;
 
  // Give class @p FEValues access to the private <tt>get_...data</tt> and
  // <tt>fill_fe_...values</tt> functions.
  friend class FEValuesBase<dim, spacedim>;
  friend class FEValues<dim, spacedim>;
  friend class FEFaceValues<dim, spacedim>;
  friend class FESubfaceValues<dim, spacedim>;
  friend class NonMatching::FEImmersedSurfaceValues<dim>;
  friend class NonMatching::internal::ComputeMappingDataHelper<dim, spacedim>;
  template <int, int, typename>
  friend class NonMatching::MappingInfo;
};
 
 
template <int dim, int spacedim>
const Mapping<dim, spacedim> &
get_default_linear_mapping(const Triangulation<dim, spacedim> &triangulation);
 
 
DEAL_II_NAMESPACE_CLOSE
 
#endif