| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 2008 - 2025 by the deal.II authors |
| 5 |
// |
| 6 |
// This file is part of the deal.II library. |
| 7 |
// |
| 8 |
// Part of the source code is dual licensed under Apache-2.0 WITH |
| 9 |
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information |
| 10 |
// governing the source code and code contributions can be found in |
| 11 |
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. |
| 12 |
// |
| 13 |
// ------------------------------------------------------------------------ |
| 14 |
|
| 15 |
|
| 16 |
#ifndef dealii_mapping_q_eulerian_h |
| 17 |
#define dealii_mapping_q_eulerian_h |
| 18 |
|
| 19 |
#include <deal.II/base/config.h> |
| 20 |
|
| 21 |
#include <deal.II/base/mutex.h> |
| 22 |
#include <deal.II/base/observer_pointer.h> |
| 23 |
|
| 24 |
#include <deal.II/dofs/dof_accessor.h> |
| 25 |
#include <deal.II/dofs/dof_handler.h> |
| 26 |
|
| 27 |
#include <deal.II/fe/fe_values.h> |
| 28 |
#include <deal.II/fe/mapping_q.h> |
| 29 |
|
| 30 |
#include <deal.II/grid/tria_iterator.h> |
| 31 |
|
| 32 |
#include <boost/container/small_vector.hpp> |
| 33 |
|
| 34 |
|
| 35 |
DEAL_II_NAMESPACE_OPEN |
| 36 |
|
| 37 |
template <typename> |
| 38 |
class Vector; |
| 39 |
|
| 40 |
|
| 41 |
/** |
| 42 |
* @addtogroup mapping |
| 43 |
* @{ |
| 44 |
*/ |
| 45 |
|
| 46 |
/** |
| 47 |
* This class is an extension of the MappingQ1Eulerian class to higher order |
| 48 |
* $Q_p$ mappings. It is useful when one wants to calculate shape function |
| 49 |
* information on a domain that is deforming as the computation proceeds. |
| 50 |
* |
| 51 |
* <h3>Usage</h3> |
| 52 |
* |
| 53 |
* The constructor of this class takes three arguments: the polynomial degree |
| 54 |
* of the desired Qp mapping, a reference to the vector that defines the |
| 55 |
* mapping from the initial configuration to the current configuration, and a |
| 56 |
* reference to the DoFHandler. The most common case is to use the solution |
| 57 |
* vector for the problem under consideration as the shift vector. The key |
| 58 |
* requirement is that the number of components of the given vector field must |
| 59 |
* be equal to (or possibly greater than) the number of space dimensions. If |
| 60 |
* there are more components than space dimensions (for example, if one is |
| 61 |
* working with a coupled problem where there are additional solution |
| 62 |
* variables), the first <tt>dim</tt> components are assumed to represent the |
| 63 |
* displacement field, and the remaining components are ignored. If this |
| 64 |
* assumption does not hold one may need to set up a separate DoFHandler on |
| 65 |
* the triangulation and associate the desired shift vector to it. |
| 66 |
* |
| 67 |
* Typically, the DoFHandler operates on a finite element that is constructed |
| 68 |
* as a system element (FESystem) from continuous FE_Q objects. An example |
| 69 |
* is shown below: |
| 70 |
* @code |
| 71 |
* FESystem<dim> fe(FE_Q<dim>(2), dim, FE_Q<dim>(1), 1); |
| 72 |
* DoFHandler<dim> dof_handler(triangulation); |
| 73 |
* dof_handler.distribute_dofs(fe); |
| 74 |
* Vector<double> displacement_field(dof_handler.n_dofs()); |
| 75 |
* // ... compute displacement field somehow... |
| 76 |
* MappingQEulerian<dim> q2_mapping(2, dof_handler, displacement_field); |
| 77 |
* @endcode |
| 78 |
* |
| 79 |
* In this example, our element consists of <tt>(dim+1)</tt> components. Only |
| 80 |
* the first <tt>dim</tt> components will be used, however, to define the Q2 |
| 81 |
* mapping. The remaining components are ignored. |
| 82 |
* |
| 83 |
* Note that it is essential to call the distribute_dofs(...) function before |
| 84 |
* constructing a mapping object. |
| 85 |
* |
| 86 |
* Also note that since the vector of shift values and the dof handler are |
| 87 |
* only associated to this object at construction time, you have to make sure |
| 88 |
* that whenever you use this object, the given objects still represent valid |
| 89 |
* data. |
| 90 |
* |
| 91 |
* To enable the use of the MappingQEulerian class also in the context of |
| 92 |
* parallel codes using the PETSc or Trilinos wrapper classes, the type |
| 93 |
* of the vector can be specified as template parameter <tt>VectorType</tt>. |
| 94 |
*/ |
| 95 |
template <int dim, typename VectorType = Vector<double>, int spacedim = dim> |
| 96 |
class MappingQEulerian : public MappingQ<dim, spacedim> |
| 97 |
{ |
| 98 |
public: |
| 99 |
/** |
| 100 |
* Constructor. |
| 101 |
* |
| 102 |
* @param[in] degree The polynomial degree of the desired $Q_p$ mapping. |
| 103 |
* @param[in] euler_dof_handler A DoFHandler object that defines a finite |
| 104 |
* element space. This space needs to have at least dim components and the |
| 105 |
* first dim components of the space will be considered displacements |
| 106 |
* relative to the original positions of the cells of the triangulation. |
| 107 |
* @param[in] euler_vector A finite element function in the space defined by |
| 108 |
* the second argument. The first dim components of this function will be |
| 109 |
* interpreted as the displacement we use in defining the mapping, relative |
| 110 |
* to the location of cells of the underlying triangulation. |
| 111 |
* @param[in] level The multi-grid level at which the mapping will |
| 112 |
* be used. It is mainly used to check if the size of the @p euler_vector |
| 113 |
* is consistent with the @p euler_dof_handler . |
| 114 |
*/ |
| 115 |
MappingQEulerian(const unsigned int degree, |
| 116 |
const DoFHandler<dim, spacedim> &euler_dof_handler, |
| 117 |
const VectorType &euler_vector, |
| 118 |
const unsigned int level = numbers::invalid_unsigned_int); |
| 119 |
|
| 120 |
/** |
| 121 |
* Return the mapped vertices of the cell. For the current class, this |
| 122 |
* function does not use the support points from the geometry of the current |
| 123 |
* cell but instead evaluates an externally given displacement field in |
| 124 |
* addition to the geometry of the cell. |
| 125 |
*/ |
| 126 |
virtual boost::container::small_vector<Point<spacedim>, |
| 127 |
#ifndef _MSC_VER |
| 128 |
ReferenceCells::max_n_vertices<dim>() |
| 129 |
#else |
| 130 |
GeometryInfo<dim>::vertices_per_cell |
| 131 |
#endif |
| 132 |
> |
| 133 |
get_vertices(const typename Triangulation<dim, spacedim>::cell_iterator &cell) |
| 134 |
const override; |
| 135 |
|
| 136 |
/** |
| 137 |
* Return a pointer to a copy of the present object. The caller of this copy |
| 138 |
* then assumes ownership of it. |
| 139 |
*/ |
| 140 |
virtual std::unique_ptr<Mapping<dim, spacedim>> |
| 141 |
clone() const override; |
| 142 |
|
| 143 |
/** |
| 144 |
* Always return @p false because MappingQEulerian does not in general |
| 145 |
* preserve vertex locations (unless the translation vector happens to |
| 146 |
* provide zero displacements at vertex locations). |
| 147 |
*/ |
| 148 |
virtual bool |
| 149 |
preserves_vertex_locations() const override; |
| 150 |
|
| 151 |
// for documentation, see the Mapping base class |
| 152 |
virtual std::vector<Point<spacedim>> |
| 153 |
compute_mapping_support_points( |
| 154 |
const typename Triangulation<dim, spacedim>::cell_iterator &cell) |
| 155 |
const override; |
| 156 |
|
| 157 |
/** |
| 158 |
* Exception which is thrown when the mapping is being evaluated at |
| 159 |
* non-active cell. |
| 160 |
*/ |
| 161 |
DeclException0(ExcInactiveCell); |
| 162 |
|
| 163 |
protected: |
| 164 |
/** |
| 165 |
* Compute mapping-related information for a cell. See the documentation of |
| 166 |
* Mapping::fill_fe_values() for a discussion of purpose, arguments, and |
| 167 |
* return value of this function. |
| 168 |
* |
| 169 |
* This function overrides the function in the base class since we cannot |
| 170 |
* use any cell similarity for this class. |
| 171 |
*/ |
| 172 |
virtual CellSimilarity::Similarity |
| 173 |
fill_fe_values( |
| 174 |
const typename Triangulation<dim, spacedim>::cell_iterator &cell, |
| 175 |
const CellSimilarity::Similarity cell_similarity, |
| 176 |
const Quadrature<dim> &quadrature, |
| 177 |
const typename Mapping<dim, spacedim>::InternalDataBase &internal_data, |
| 178 |
internal::FEValuesImplementation::MappingRelatedData<dim, spacedim> |
| 179 |
&output_data) const override; |
| 180 |
|
| 181 |
/** |
| 182 |
* Reference to the vector of shifts. |
| 183 |
*/ |
| 184 |
ObserverPointer<const VectorType, MappingQEulerian<dim, VectorType, spacedim>> |
| 185 |
euler_vector; |
| 186 |
|
| 187 |
/** |
| 188 |
* Pointer to the DoFHandler to which the mapping vector is associated. |
| 189 |
*/ |
| 190 |
ObserverPointer<const DoFHandler<dim, spacedim>, |
| 191 |
MappingQEulerian<dim, VectorType, spacedim>> |
| 192 |
euler_dof_handler; |
| 193 |
|
| 194 |
private: |
| 195 |
/** |
| 196 |
* Multigrid level at which the mapping is to be used. |
| 197 |
*/ |
| 198 |
const unsigned int level; |
| 199 |
|
| 200 |
/** |
| 201 |
* Special quadrature rule used to define the support points in the |
| 202 |
* reference configuration. |
| 203 |
*/ |
| 204 |
class SupportQuadrature : public Quadrature<dim> |
| 205 |
{ |
| 206 |
public: |
| 207 |
/** |
| 208 |
* Constructor, with an argument defining the desired polynomial degree. |
| 209 |
*/ |
| 210 |
SupportQuadrature(const unsigned int map_degree); |
| 211 |
}; |
| 212 |
|
| 213 |
/** |
| 214 |
* A member variable holding the quadrature points in the right order. |
| 215 |
*/ |
| 216 |
const SupportQuadrature support_quadrature; |
| 217 |
|
| 218 |
/** |
| 219 |
* A MappingQ object, which is used by the fe_values |
| 220 |
* member variable to compute the undeformed mapping support |
| 221 |
* points, before adding any deformation. |
| 222 |
*/ |
| 223 |
const MappingQ<dim, spacedim> mapping_q; |
| 224 |
|
| 225 |
/** |
| 226 |
* FEValues object used to query the given finite element field at the |
| 227 |
* support points in the reference configuration. |
| 228 |
* |
| 229 |
* The variable is marked as mutable since we have to call |
| 230 |
* FEValues::reinit from compute_mapping_support_points, a function that |
| 231 |
* is 'const'. |
| 232 |
*/ |
| 233 |
mutable FEValues<dim, spacedim> fe_values; |
| 234 |
|
| 235 |
/** |
| 236 |
* A variable to guard access to the fe_values variable. |
| 237 |
*/ |
| 238 |
mutable Threads::Mutex fe_values_mutex; |
| 239 |
}; |
| 240 |
|
| 241 |
/** @} */ |
| 242 |
|
| 243 |
|
| 244 |
/*----------------------------------------------------------------------*/ |
| 245 |
|
| 246 |
#ifndef DOXYGEN |
| 247 |
|
| 248 |
template <int dim, typename VectorType, int spacedim> |
| 249 |
inline bool |
| 250 |
MappingQEulerian<dim, VectorType, spacedim>::preserves_vertex_locations() const |
| 251 |
{ |
| 252 |
return false; |
| 253 |
} |
| 254 |
|
| 255 |
#endif // DOXYGEN |
| 256 |
|
| 257 |
|
| 258 |
DEAL_II_NAMESPACE_CLOSE |
| 259 |
|
| 260 |
|
| 261 |
#endif // dealii_mapping_q_eulerian_h |