Debian Codegraph @

include/deal.II/non_matching/mesh_classifier.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2021 - 2024 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 #ifndef dealii_non_matching_mesh_classifier
16 #define dealii_non_matching_mesh_classifier
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/dofs/dof_handler.h>
21
22 #include <deal.II/grid/tria.h>
23 #include <deal.II/grid/tria_accessor.h>
24
25 #include <deal.II/lac/lapack_full_matrix.h>
26
27 #include <vector>
28
29 DEAL_II_NAMESPACE_OPEN
30 namespace NonMatching
31 {
32 namespace internal
33 {
34 namespace MeshClassifierImplementation
35 {
36 template <int dim>
37 class LevelSetDescription;
38 } // namespace MeshClassifierImplementation
39 } // namespace internal
40
41
42 /**
43 * Type describing how a cell or a face is located relative to the zero
44 * contour of a level set function, $\psi$. The values of the type correspond
45 * to:
46 *
47 * inside if $\psi(x) < 0$,
48 * outside if $\psi(x) > 0$,
49 * intersected if $\psi(x)$ varies in sign,
50 *
51 * over the cell/face. The value "unassigned" is used to describe that the
52 * location of a cell/face has not yet been determined.
53 */
54 enum class LocationToLevelSet
55 {
56 inside,
57 outside,
58 intersected,
59 unassigned
60 };
61
62
63 /**
64 * Class responsible for determining how the active cells and faces of a
65 * triangulation relate to the sign of a level set function. When calling the
66 * reclassify() function each of the active cells and faces are categorized as
67 * one of the values of LocationToLevelSet: inside, outside or intersected,
68 * depending on the sign of the level set function over the cell/face. This
69 * information is typically required in immersed/cut finite element methods,
70 * both when distributing degrees of freedom over the triangulation and when
71 * the system is assembled. The given class would then be used in the
72 * following way:
73 *
74 * @code
75 * Vector<double> &level_set = ...
76 *
77 * MeshClassifier<dim> classifier(dof_handler, level_set);
78 * classifier.reclassify();
79 *
80 * LocationToLevelSet location = classifier.location_to_level_set(cell);
81 * @endcode
82 *
83 * The level set function can either be described as a discrete function by a
84 * (DoFHandler, Vector)-pair or as a general Function. In the case of a
85 * discrete function, LocationToLevelSet for a given face is determined
86 * by looking at the local degrees of freedom on the face. Since the Lagrange
87 * basis functions are not positive definite, positive/negative definite
88 * dof values do not imply that the interpolated function is
89 * positive/negative definite. Thus, to classify a face this class internally
90 * transforms the local dofs to a basis spanning the same polynomial space
91 * over the face but where definite dof values imply a definite function.
92 * Currently, only the case of FE_Q-elements is implemented, where we
93 * internally change basis to FE_Bernstein. For cells, LocationToLevelSet is
94 * determined from the faces of the cell. That is, if all faces of the cell
95 * are inside/outside the LocationToLevelSet of the cell is set to
96 * inside/outside. LocationToLevelSet of the cell is set to intersected if at
97 * least one face is intersected or if its faces have different
98 * LocationToLevelSet. Note that, this procedure will incorrectly classify the
99 * cell as inside/outside, if the mesh refinement is so low that the whole
100 * zero-contour is contained in a single cell (so that none of its faces are
101 * intersected).
102 *
103 * When the level set function is described as a Function, the level set
104 * function is locally interpolated to an FE_Q element and we proceed in the
105 * same way as for the discrete level set function.
106 */
107 template <int dim>
108 class MeshClassifier : public EnableObserverPointer
109 {
110 public:
111 /**
112 * Constructor. Takes a level set function described as a DoFHandler and a
113 * Vector. The triangulation attached to DoFHandler is the one that will be
114 * classified.
115 */
116 template <typename VectorType>
117 MeshClassifier(const DoFHandler<dim> &level_set_dof_handler,
118 const VectorType &level_set);
119
120 /**
121 * Constructor. Takes the triangulation that should be classified, a
122 * level set function described as a Function, and a scalar element that we
123 * interpolate the Function to in order to classify each cell/face.
124 *
125 * @note The Function and the FiniteElement must both have a single component.
126 */
127 MeshClassifier(const Triangulation<dim> &triangulation,
128 const Function<dim> &level_set,
129 const FiniteElement<dim> &element);
130
131 /**
132 * Perform the classification of the non artificial cells and faces in the
133 * triangulation.
134 */
135 void
136 reclassify();
137
138 /**
139 * Return how the incoming cell is located relative to the level set
140 * function.
141 */
142 LocationToLevelSet
143 location_to_level_set(
144 const typename Triangulation<dim>::cell_iterator &cell) const;
145
146 /**
147 * Return how a face of the incoming cell is located relative to the level
148 * set function.
149 */
150 LocationToLevelSet
151 location_to_level_set(
152 const typename Triangulation<dim>::cell_iterator &cell,
153 const unsigned int face_index) const;
154
155 private:
156 /**
157 * For each element in the hp::FECollection returned by
158 * level_set_description, sets up the local transformation matrices.
159 */
160 void
161 initialize();
162
163 /**
164 * Computes how the face with the given index on the incoming cell is
165 * located relative to the level set function.
166 */
167 LocationToLevelSet
168 determine_face_location_to_levelset(
169 const typename Triangulation<dim>::active_cell_iterator &cell,
170 const unsigned int face_index);
171
172 /**
173 * Pointer to the triangulation that should be classified.
174 */
175 const ObserverPointer<const Triangulation<dim>> triangulation;
176
177 /**
178 * Pointer to an object that describes what we need to know about the
179 * level set function. The underlying object will be of different type
180 * depending on whether the level set function is discrete
181 * (DoFHandler, Vector) or described by a Function.
182 */
183 const std::unique_ptr<
184 internal::MeshClassifierImplementation::LevelSetDescription<dim>>
185 level_set_description;
186
187 /**
188 * A vector that stores how each active cell is located relative to the
189 * level set function, based on the cells active index.
190 */
191 std::vector<LocationToLevelSet> cell_locations;
192
193 /**
194 * A vector that stores how each active face is located relative to the
195 * level set function, based on the face's global index.
196 */
197 std::vector<LocationToLevelSet> face_locations;
198
199 /**
200 * For each element in the hp::FECollection returned by the
201 * LevelSetDescription, and for each local face, this vector stores a
202 * transformation matrix to a basis where positive/negative definite
203 * face dofs implies that the underlying function is positive/negative
204 * definite over the face.
205 */
206 std::vector<
207 std::array<LAPACKFullMatrix<double>, GeometryInfo<dim>::faces_per_cell>>
208 lagrange_to_bernstein_face;
209 };
210
211
212 namespace internal
213 {
214 namespace MeshClassifierImplementation
215 {
216 /**
217 * Abstract class that describes what we need to know about the level set
218 * function independently of whether it is a Function or a
219 * (DoFHandler, Vector)-pair.
220 */
221 template <int dim>
222 class LevelSetDescription
223 {
224 public:
225 /**
226 * Destructor, declared to mark it virtual.
227 */
228 virtual ~LevelSetDescription() = default;
229
230 /**
231 * Return a collection to all the elements that are used to locally
232 * describe the level set function.
233 */
234 virtual const hp::FECollection<dim> &
235 get_fe_collection() const = 0;
236
237 /**
238 * Return the index of the element in the FECollection that we associate
239 * with the level set function on the incoming cell.
240 */
241 virtual unsigned int
242 active_fe_index(const typename Triangulation<dim>::active_cell_iterator
243 &cell) const = 0;
244
245 /**
246 * Fill the DoF values of the associated level set representation on the
247 * face of the incoming cell into the vector provided in the last
248 * argument.
249 *
250 * @note Since this function extracts the dofs on the face of the cell,
251 * it assumes that the underlying element has face support points.
252 */
253 virtual void
254 get_local_level_set_values(
255 const typename Triangulation<dim>::active_cell_iterator &cell,
256 const unsigned int face_index,
257 Vector<double> &local_dofs) = 0;
258 };
259
260 } // namespace MeshClassifierImplementation
261 } // namespace internal
262 } // namespace NonMatching
263 DEAL_II_NAMESPACE_CLOSE
264
265 #endif