mapping.h

// ---------------------------------------------------------------------
//
// Copyright (C) 2000 - 2018 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 at
// the top level of the deal.II distribution.
//
// ---------------------------------------------------------------------

#ifndef dealii_mapping_h
#define dealii_mapping_h


#include <deal.II/base/config.h>
#include <deal.II/base/derivative_form.h>
#include <deal.II/grid/tria.h>
#include <deal.II/fe/fe_update_flags.h>

#include <array>
#include <cmath>
#include <memory>

DEAL_II_NAMESPACE_OPEN

template <typename ElementType> 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
  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