mapping.h

Go to the documentation of this file.

// ------------------------------------------------------------------------
//
// SPDX-License-Identifier: LGPL-2.1-or-later
// Copyright (C) 2001 - 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_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 &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