mapping.h

// ---------------------------------------------------------------------
//
// Copyright (C) 2000 - 2019 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE.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/derivative_form.h>

#include <deal.II/fe/fe_update_flags.h>

#include <deal.II/grid/tria.h>

#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;


enum MappingType
{
  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 Subscriptor
{
public:
  virtual ~Mapping() override = default;

  virtual std::unique_ptr<Mapping<dim, spacedim>>
  clone() const = 0;

  virtual std::array<Point<spacedim>, GeometryInfo<dim>::vertices_per_cell>
  get_vertices(
    const typename Triangulation<dim, spacedim>::cell_iterator &cell) const;

  virtual Point<spacedim>
  get_center(const typename Triangulation<dim, spacedim>::cell_iterator &cell,
             const bool map_center_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 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;

  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 ~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 Quadrature<dim - 1> &quadrature) const = 0;

  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 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_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;

public:
  virtual void
  transform(const ArrayView<const Tensor<1, dim>> &                  input,
            const MappingType                                        type,
            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 MappingType                                        type,
            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 MappingType                                        type,
            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 MappingType                                        type,
            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 MappingType                                        type,
            const typename Mapping<dim, spacedim>::InternalDataBase &internal,
            const ArrayView<Tensor<3, spacedim>> &output) const = 0;

  friend class FEValuesBase<dim, spacedim>;
  friend class FEValues<dim, spacedim>;
  friend class FEFaceValues<dim, spacedim>;
  friend class FESubfaceValues<dim, spacedim>;
};


DEAL_II_NAMESPACE_CLOSE

#endif