Debian Codegraph @

include/deal.II/numerics/solution_transfer.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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 #ifndef dealii_solution_transfer_h
16 #define dealii_solution_transfer_h
17
18
19 /*---------------------------- solutiontransfer.h ----------------------*/
20
21
22 #include <deal.II/base/config.h>
23
24 #include <deal.II/base/exceptions.h>
25 #include <deal.II/base/observer_pointer.h>
26
27 #include <deal.II/dofs/dof_handler.h>
28
29 #include <deal.II/lac/vector.h>
30
31 #include <boost/range/iterator_range_core.hpp>
32
33 #include <vector>
34
35 DEAL_II_NAMESPACE_OPEN
36
37
38 /**
39 * This class implements the transfer of a discrete FE function (e.g. a
40 * solution vector) from one mesh to another that is obtained from the first
41 * by a single refinement and/or coarsening step. During interpolation the
42 * vector is filled with the interpolated values. This class is used in the
43 * step-15, step-26, step-31, and step-33 tutorial programs. This class
44 * works both for serial and distributed meshes.
45 *
46 * <h3>Usage</h3>
47 *
48 * @note It is important to note, that if you use more than one
49 * SolutionTransfer object at the same time, that the calls to prepare_*()
50 * and interpolate()/deserialize() need to be in the same order.
51 *
52 * <h3>Transferring a solution</h3> Here VectorType is your favorite
53 * vector type, e.g. Vector, LinearAlgebra::distributed::Vector,
54 * PETScWrappers::MPI::Vector, TrilinosWrappers::MPI::Vector, or corresponding
55 * block vectors.
56 * @code
57 * SolutionTransfer<dim, VectorType> soltrans(dof_handler);
58 * // flag some cells for refinement and coarsening, e.g.
59 * GridRefinement::
60 * refine_and_coarsen_fixed_fraction(tria,
61 * error_indicators,
62 * 0.3,
63 * 0.05);
64 * // Use parallel::distributed::GridRefinement for distributed triangulations.
65 *
66 * // prepare the triangulation,
67 * tria.prepare_coarsening_and_refinement();
68 *
69 * // prepare the SolutionTransfer object for coarsening and refinement
70 * // and give the solution vector that we intend to interpolate later,
71 * soltrans.prepare_for_coarsening_and_refinement(solution);
72 *
73 * // actually execute the refinement,
74 * tria.execute_coarsening_and_refinement();
75 *
76 * // redistribute dofs,
77 * dof_handler.distribute_dofs(fe);
78 *
79 * // adjust the vector size so that it can hold all dofs
80 * // (for distributed grids, see instructions below),
81 * solution.reinit(...);
82 *
83 * // and interpolate the solution
84 * soltrans.interpolate(solution);
85 * @endcode
86 *
87 * <h3>Usage on distributed grids</h3>
88 * If the grid is distributed, it is important to note that the old
89 * solution(s) must be copied to one that also provides access to the
90 * locally relevant DoF values (these values required for the interpolation
91 * process):
92 * @code
93 * // Create initial indexsets pertaining to the grid before refinement
94 * const IndexSet &locally_owned_dofs = dof_handler.locally_owned_dofs();
95 * const IndexSet locally_relevant_dofs =
96 * DoFTools::extract_locally_relevant_dofs(dof_handler);
97 *
98 * // The solution vector only knows about locally owned DoFs
99 * TrilinosWrappers::MPI::Vector solution;
100 * solution.reinit(locally_owned_dofs,
101 * mpi_communicator);
102 * ...
103 * // Transfer solution to vector that provides access to
104 * // locally relevant DoFs
105 * TrilinosWrappers::MPI::Vector old_solution;
106 * old_solution.reinit(locally_owned_dofs,
107 * locally_relevant_dofs,
108 * mpi_communicator);
109 * old_solution = solution;
110 *
111 * // Initialize SolutionTransfer object
112 * SolutionTransfer<dim, VectorType> soltrans(dof_handler);
113 * soltrans.prepare_for_coarsening_and_refinement(old_solution);
114 * ...
115 * // Refine grid
116 * // Recreate locally_owned_dofs and locally_relevant_dofs index sets
117 * ...
118 * solution.reinit(locally_owned_dofs, mpi_communicator);
119 * soltrans.interpolate(solution);
120 * @endcode
121 *
122 * <h4>Note on ghost elements</h4> In a parallel computation PETSc or
123 * Trilinos vector may contain ghost elements or not. For reading in
124 * information with prepare_for_coarsening_and_refinement() or
125 * prepare_for_serialization() you need to supply vectors with ghost
126 * elements, so that all locally_active elements can be read. On the other
127 * hand, ghosted vectors are generally not writable, so for calls to
128 * interpolate() or deserialize() you need to supply distributed vectors
129 * without ghost elements. More precisely, during interpolation the
130 * current algorithm writes into all locally active degrees of freedom.
131 *
132 * Different from PETSc and Trilinos vectors, LinearAlgebra::distributed::Vector
133 * allows writing into ghost elements. For a ghosted vector the interpolation
134 * step can be accomplished via
135 * @code
136 * interpolated_solution.zero_out_ghost_values();
137 * soltrans.interpolate(interpolated_solution);
138 * interpolated_solution.update_ghost_values();
139 * @endcode
140 *
141 * <h3>Use for serialization</h3>
142 *
143 * This class can be used to serialize and later deserialize a
144 * mesh with solution vectors to a file. If you use more than one
145 * DoFHandler and therefore more than one SolutionTransfer object, they
146 * need to be serialized and deserialized in the same order.
147 *
148 * If vector has the locally relevant DoFs, serialization works as
149 * follows:
150 * @code
151 * SolutionTransfer<dim, VectorType> sol_trans(dof_handler);
152 * sol_trans.prepare_for_serialization(vector);
153 *
154 * triangulation.save(filename);
155 * @endcode
156 * For deserialization the vector needs to be a distributed vector
157 * (without ghost elements):
158 * @code
159 * //[create coarse mesh...]
160 * triangulation.load(filename);
161 *
162 * SolutionTransfer<dim, VectorType> sol_trans(dof_handler);
163 * sol_trans.deserialize(distributed_vector);
164 * @endcode
165 *
166 *
167 * <h3>Note on usage with DoFHandler with hp-capabilities</h3>
168 *
169 * Since data on DoFHandler objects with hp-capabilities is associated with
170 * many different FiniteElement objects, each cell's data has to be
171 * processed with its corresponding `future_fe_index`. Further, if
172 * refinement is involved, data will be packed on the parent cell with its
173 * `future_fe_index` and unpacked later with the same index on its children.
174 * If cells get coarsened into one, data will be packed on the children with
175 * the least dominant finite element of their common subspace, and unpacked
176 * on the parent with this particular finite element (consult
177 * hp::FECollection::find_dominated_fe_extended() for more information).
178 *
179 * Transferring a solution across refinement works exactly like in the
180 * non-hp-case. However, when considering serialization, we also have to
181 * store the active FE indices in an additional step. A code snippet
182 * demonstrating serialization with the SolutionTransfer class with DoFHandler
183 * objects with hp-capabilities is provided in the following. Here VectorType is
184 * your favorite vector type, e.g. Vector, LinearAlgebra::distributed::Vector,
185 * PETScWrappers::MPI::Vector, TrilinosWrappers::MPI::Vector, or corresponding
186 * block vectors.
187 *
188 * If vector has the locally relevant DoFs, serialization works as follows:
189 * @code
190 * SolutionTransfer<dim, VectorType, DoFHandler<dim,spacedim>>
191 * sol_trans(hp_dof_handler);
192 *
193 * hp_dof_handler.prepare_for_serialization_of_active_fe_indices();
194 * sol_trans.prepare_for_serialization(vector);
195 *
196 * triangulation.save(filename);
197 * @endcode
198 *
199 * For deserialization the vector needs to be a distributed vector
200 * (without ghost elements):
201 * @code
202 * //[create coarse mesh...]
203 * triangulation.load(filename);
204 *
205 * hp::FECollection<dim,spacedim> fe_collection;
206 * //[prepare identical fe_collection...]
207 *
208 * DoFHandler<dim,spacedim> hp_dof_handler(triangulation);
209 * // We need to introduce our dof_handler to the fe_collection
210 * // before setting all active FE indices.
211 * hp_dof_handler.deserialize_active_fe_indices();
212 * hp_dof_handler.distribute_dofs(fe_collection);
213 *
214 * SolutionTransfer<dim,VectorType,DoFHandler<dim,spacedim>>
215 * sol_trans(hp_dof_handler);
216 * sol_trans.deserialize(distributed_vector);
217 * @endcode
218 *
219 *
220 * <h3>Interaction with hanging nodes</h3>
221 *
222 * This class does its best to represent on the new mesh the finite element
223 * function that existed on the old mesh, but this may lead to situations
224 * where the function on the new mesh is no longer conforming at hanging
225 * nodes. To this end, consider a situation of a twice refined mesh that
226 * started with a single square cell (i.e., we now have 16 cells). Consider
227 * also that we coarsen 4 of the cells back to the first refinement level. In
228 * this case, we end up with a mesh that will look as follows if we were to
229 * use a $Q_1$ element:
230 *
231 * @image html hanging_nodes.png ""
232 *
233 * The process of interpolating from the old to the new mesh would imply that
234 * the values of the finite element function will not change on all of the
235 * cells that remained as they are (i.e., the fine cells) but that on the
236 * coarse cell at the top right, the four values at the vertices are obtained
237 * by interpolating down from its former children. If the original function
238 * was not linear, this implies that the marked hanging nodes will retain
239 * their old values which, in general, will not lead to a continuous function
240 * along the corresponding edges. In other words, the solution vector obtained
241 * after SolutionTransfer::interpolate() does not satisfy hanging node
242 * constraints: it corresponds to the pointwise interpolation, but not to the
243 * interpolation <i>onto the new finite element space that contains
244 * constraints from hanging nodes</i>.
245 *
246 * Whether this is a problem you need to worry about or not depends on your
247 * application. The situation is easily corrected, of course, by applying
248 * AffineConstraints::distribute() to your solution vector after transfer,
249 * using a constraints object computed on the new DoFHandler object (you
250 * probably need to create this object anyway if you have hanging nodes). This
251 * is also what is done, for example, in step-15.
252 *
253 * @note This situation can only happen if you do coarsening. If all cells
254 * remain as they are or are refined, then SolutionTransfer::interpolate()
255 * computes a new vector of nodal values, but the function represented is of
256 * course exactly the same because the old finite element space is a subspace
257 * of the new one. Thus, if the old function was conforming (i.e., satisfied
258 * hanging node constraints), then so does the new one, and it is not
259 * necessary to call AffineConstraints::distribute().
260 *
261 *
262 * <h3>Implementation in the context of hp-finite elements</h3>
263 *
264 * In the case of DoFHandlers with hp-capabilities, nothing defines which of
265 * the finite elements that are part of the hp::FECollection associated with
266 * the DoFHandler, should be considered on cells that are not active (i.e.,
267 * that have children). This is because degrees of freedom are only allocated
268 * for active cells and, in fact, it is not allowed to set an active FE index
269 * on non-active cells using DoFAccessor::set_active_fe_index().
270 *
271 * It is, thus, not entirely natural what should happen if, for example, a few
272 * cells are coarsened away. This class then implements the following
273 * algorithm:
274 * - If a cell is refined, then the values of the solution vector(s) are
275 * interpolated before refinement on the to-be-refined cell from the space
276 * of the active finite element to the one of the future finite element. These
277 * values are then distributed on the finite element spaces of the children
278 * post-refinement. This may lose information if, for example, the old cell
279 * used a Q2 space and the children use Q1 spaces, or the information may be
280 * prolonged if the parent cell used a Q1 space and the children are Q2s.
281 * - If cells are to be coarsened, then the values from the child cells are
282 * interpolated to the parent cell using the largest of the child cell
283 * future finite element spaces, which will be identified as the least
284 * dominant element following the FiniteElementDomination logic (consult
285 * hp::FECollection::find_dominated_fe_extended() for more information). For
286 * example, if the children of a cell use Q1, Q2 and Q3 spaces, then the
287 * values from the children are interpolated into a Q3 space on the parent
288 * cell. After refinement, this Q3 function on the parent cell is then
289 * interpolated into the space the user has selected for this cell (which
290 * may be different from Q3, in this example, if the user has set the active
291 * FE index for a different space post-refinement and before calling
292 * DoFHandler::distribute_dofs()).
293 *
294 * @note In the context of hp-refinement, if cells are coarsened or the
295 * polynomial degree is lowered on some cells, then the old finite element
296 * space is not a subspace of the new space and you may run into the same
297 * situation as discussed above with hanging nodes. You may want to consider
298 * calling AffineConstraints::distribute() on the vector obtained by
299 * transferring the solution.
300 *
301 * @ingroup numerics
302 */
303 template <int dim, typename VectorType = Vector<double>, int spacedim = dim>
304 class SolutionTransfer
305 {
306 public:
307 /**
308 * Constructor.
309 *
310 * @param[in] dof_handler The DoFHandler on which all operations will
311 * happen. At the time when this constructor is called, the DoFHandler
312 * still points to the Triangulation before the refinement in question
313 * happens.
314 * @param[in] average_values Average the contribututions to the same
315 * DoF coming from different cells. Note: averaging requires an
316 * additional communication step, since the valence of the DoF has to be
317 * determined.
318 */
319 SolutionTransfer(const DoFHandler<dim, spacedim> &dof_handler,
320 const bool average_values = false);
321
322 /**
323 * Destructor.
324 */
325 ~SolutionTransfer() = default;
326
327 /**
328 * Prepare the current object for coarsening and refinement. It
329 * stores pointers to the vectors in @p all_in to be interpolated onto the new
330 * (refined and/or coarsened) grid, and registers this object for data
331 * transfer on the grid.
332 */
333 void
334 prepare_for_coarsening_and_refinement(
335 const std::vector<const VectorType *> &all_in);
336
337 /**
338 * Same as above but without pointers.
339 */
340 void
341 prepare_for_coarsening_and_refinement(const std::vector<VectorType> &all_in);
342
343 /**
344 * Same as the previous function but for only one discrete function to be
345 * interpolated.
346 */
347 void
348 prepare_for_coarsening_and_refinement(const VectorType &in);
349
350 /**
351 * Interpolate the data previously stored in this object before the mesh
352 * was refined or coarsened onto the current set of cells. Do so for
353 * each of the vectors provided to
354 * prepare_for_coarsening_and_refinement() and write the result into the
355 * given set of vectors.
356 */
357 void
358 interpolate(std::vector<VectorType *> &all_out);
359
360 /**
361 * Same as above but without pointers.
362 */
363 void
364 interpolate(std::vector<VectorType> &all_out);
365
366 /**
367 * Same as the previous function. It interpolates only one function. It
368 * assumes the vector has the right size (i.e.
369 * <tt>out.size()==n_dofs_refined</tt>)
370 *
371 * Multiple calling of this function is NOT allowed. Interpolating
372 * several functions can be performed in one step by using
373 * <tt>interpolate (all_out)</tt>
374 */
375 void
376 interpolate(VectorType &out);
377
378 /**
379 * Prepare the serialization of the given vector. The serialization is
380 * done by Triangulation::save(). The given vector needs all information
381 * on the locally active DoFs (it must be ghosted). See documentation of
382 * this class for more information.
383 */
384 void
385 prepare_for_serialization(const VectorType &in);
386
387 /**
388 * Same as the function above, only for a list of vectors.
389 */
390 void
391 prepare_for_serialization(const std::vector<const VectorType *> &all_in);
392
393 /**
394 * Execute the deserialization of the given vector. This needs to be
395 * done after calling Triangulation::load(). The given vector must be a
396 * fully distributed vector without ghost elements. See documentation of
397 * this class for more information.
398 */
399 void
400 deserialize(VectorType &in);
401
402
403 /**
404 * Same as the function above, only for a list of vectors.
405 */
406 void
407 deserialize(std::vector<VectorType *> &all_in);
408
409 /**
410 * Reinit this class to the state that it has directly after calling the
411 * constructor.
412 */
413 DEAL_II_DEPRECATED_EARLY void
414 clear();
415
416 private:
417 /**
418 * Pointer to the degree of freedom handler to work with.
419 */
420 ObserverPointer<const DoFHandler<dim, spacedim>,
421 SolutionTransfer<dim, VectorType, spacedim>>
422 dof_handler;
423
424 /**
425 * Flag indicating if averaging should be performed.
426 */
427 const bool average_values;
428
429 /**
430 * A vector that stores pointers to all the vectors we are supposed to
431 * copy over from the old to the new mesh.
432 */
433 std::vector<const VectorType *> input_vectors;
434
435 /**
436 * The handle that the Triangulation has assigned to this object
437 * with which we can access our memory offset and our pack function.
438 */
439 unsigned int handle;
440
441 /**
442 * A callback function used to pack the data on the current mesh into
443 * objects that can later be retrieved after refinement, coarsening and
444 * repartitioning.
445 */
446 std::vector<char>
447 pack_callback(
448 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
449 const CellStatus status);
450
451 /**
452 * A callback function used to unpack the data on the current mesh that
453 * has been packed up previously on the mesh before refinement,
454 * coarsening and repartitioning.
455 */
456 void
457 unpack_callback(
458 const typename Triangulation<dim, spacedim>::cell_iterator &cell,
459 const CellStatus status,
460 const boost::iterator_range<std::vector<char>::const_iterator> &data_range,
461 std::vector<VectorType *> &all_out,
462 VectorType &valence);
463
464
465 /**
466 * Registers the pack_callback() function to the Triangulation that has been
467 * assigned to the DoFHandler class member and stores the returning handle.
468 */
469 void
470 register_data_attach();
471 };
472
473
474
475 namespace Legacy
476 {
477 /**
478 * This class implements the transfer of a discrete FE function (e.g. a
479 * solution vector) from one mesh to another that is obtained from the first
480 * by a single refinement and/or coarsening step. During interpolation the
481 * vector is reinitialized to the new size and filled with the interpolated
482 * values. This class is used in the step-15, step-26, step-31, and step-33
483 * tutorial programs. A version of this class that works on all types of
484 * triangulations, including distributed ones, is available as
485 * dealii::SolutionTransfer.
486 *
487 * <h3>Usage</h3>
488 *
489 * This class implements the algorithms in two different ways:
490 * <ul>
491 * <li> If the grid will only be refined (i.e. no cells are coarsened) then
492 * use @p SolutionTransfer as follows:
493 * @code
494 * SolutionTransfer<dim, Vector<double> > soltrans(*dof_handler);
495 *
496 * // flag some cells for refinement, e.g.
497 * GridRefinement::refine_and_coarsen_fixed_fraction(*tria,
498 * error_indicators,
499 * 0.3,
500 * 0);
501 * // prepare the triangulation for refinement,
502 * tria->prepare_coarsening_and_refinement();
503 *
504 * // tell the SolutionTransfer object that we intend to do pure refinement,
505 * soltrans.prepare_for_pure_refinement();
506 *
507 * // actually execute the refinement,
508 * tria->execute_coarsening_and_refinement();
509 *
510 * // and redistribute dofs.
511 * dof_handler->distribute_dofs (fe);
512 * @endcode
513 *
514 * Then to proceed do
515 * @code
516 * // take a copy of the solution vector
517 * Vector<double> solution_old(solution);
518 *
519 * // resize solution vector to the correct size, as the @p refine_interpolate
520 * // function requires the vectors to be of right sizes
521 * solution.reinit(dof_handler->n_dofs());
522 *
523 * // and finally interpolate
524 * soltrans.refine_interpolate(solution_old, solution);
525 * @endcode
526 *
527 * Although the @p refine_interpolate functions are allowed to be called
528 * multiple times, e.g. for interpolating several solution vectors, there is
529 * the following possibility of interpolating several functions
530 * simultaneously.
531 * @code
532 * std::vector<Vector<double> > solutions_old(n_vectors, Vector<double> (n));
533 * ...
534 * std::vector<Vector<double> > solutions(n_vectors, Vector<double> (n));
535 * soltrans.refine_interpolate(solutions_old, solutions);
536 * @endcode
537 * This is used in several of the tutorial programs, for example step-31
538 * and step-33.
539 *
540 * <li> If the grid has cells that will be coarsened, then use @p
541 * SolutionTransfer as follows:
542 * @code
543 * SolutionTransfer<dim, Vector<double> > soltrans(*dof_handler);
544 *
545 * // flag some cells for refinement and coarsening, e.g.
546 * GridRefinement::refine_and_coarsen_fixed_fraction(*tria,
547 * error_indicators,
548 * 0.3,
549 * 0.05);
550 *
551 * // prepare the triangulation,
552 * tria->prepare_coarsening_and_refinement();
553 *
554 * // prepare the SolutionTransfer object for coarsening and refinement and
555 * give
556 * // the solution vector that we intend to interpolate later,
557 * soltrans.prepare_for_coarsening_and_refinement(solution);
558 *
559 * // actually execute the refinement,
560 * tria->execute_coarsening_and_refinement ();
561 *
562 * // redistribute dofs,
563 * dof_handler->distribute_dofs (fe);
564 *
565 * // and interpolate the solution
566 * Vector<double> interpolate_solution(dof_handler->n_dofs());
567 * soltrans.interpolate(solution, interpolated_solution);
568 * @endcode
569 *
570 * If the grid is partitioned across several MPI processes, then it is
571 * important to note that the old solution(s) must be copied to one that
572 * also provides access to the locally relevant DoF values (these values
573 * required for the interpolation process):
574 * @code
575 * // Create initial indexsets pertaining to the grid before refinement
576 * const IndexSet &locally_owned_dofs = dof_handler.locally_owned_dofs();
577 * const IndexSet locally_relevant_dofs =
578 * DoFTools::extract_locally_relevant_dofs(dof_handler);
579 *
580 * // The solution vector only knows about locally owned DoFs
581 * TrilinosWrappers::MPI::Vector solution;
582 * solution.reinit(locally_owned_dofs,
583 * mpi_communicator);
584 * ...
585 * // Transfer solution to vector that provides access to locally relevant
586 * DoFs TrilinosWrappers::MPI::Vector old_solution;
587 * old_solution.reinit(locally_owned_dofs,
588 * locally_relevant_dofs,
589 * mpi_communicator);
590 * old_solution = solution;
591 * ...
592 * // Refine grid
593 * // Recreate locally_owned_dofs and locally_relevant_dofs index sets
594 * ...
595 * solution.reinit(locally_owned_dofs, mpi_communicator);
596 * soltrans.refine_interpolate(old_solution, solution);
597 * @endcode
598 *
599 * Multiple calls to the function <code>interpolate (const VectorType &in,
600 * VectorType &out)</code> are NOT allowed. Interpolating several
601 * functions can be performed in one step by using <tt>void interpolate (const
602 * vector<VectorType> &all_in, vector<VectorType> &all_out)
603 * const</tt>, and using the respective @p
604 * prepare_for_coarsening_and_refinement function taking several vectors as
605 * input before actually refining and coarsening the triangulation (see
606 * there).
607 * </ul>
608 *
609 * For deleting all stored data in @p SolutionTransfer and reinitializing it
610 * use the <tt>clear()</tt> function.
611 *
612 * The template argument @p VectorType denotes the type of data container you
613 * want to transfer.
614 *
615 *
616 * <h3>Interpolating in the presence of hanging nodes and boundary values</h3>
617 *
618 * The interpolation onto the new mesh is a local operation, i.e., it
619 * interpolates onto the new mesh only. If that new mesh has hanging nodes,
620 * you will therefore get a solution that does not satisfy hanging node
621 * constraints. The same is true with boundary values: the interpolated
622 * solution will just be the interpolation of the old solution at the
623 * boundary, and this may or may not satisfy boundary values at newly
624 * introduced boundary nodes.
625 *
626 * Consequently, you may have to apply hanging node or boundary value
627 * constraints after interpolation. step-15 and step-26 have examples of
628 * dealing with this.
629 *
630 *
631 * <h3>Implementation</h3>
632 *
633 * <ul>
634 * <li> Solution transfer with only refinement. Assume that we have got a
635 * solution vector on the current (original) grid. Each entry of this vector
636 * belongs to one of the DoFs of the discretization. If we now refine the grid
637 * then the calling of DoFHandler::distribute_dofs() will change at least some
638 * of the DoF indices. Hence we need to store the DoF indices of all active
639 * cells before the refinement. A pointer for each active cell is used to
640 * point to the vector of these DoF indices of that cell. This is done by
641 * prepare_for_pure_refinement().
642 *
643 * In the function <tt>refine_interpolate(in,out)</tt> and on each cell where
644 * the pointer is set (i.e. the cells that were active in the original grid)
645 * we can now access the local values of the solution vector @p in on that
646 * cell by using the stored DoF indices. These local values are interpolated
647 * and set into the vector @p out that is at the end the discrete function @p
648 * in interpolated on the refined mesh.
649 *
650 * The <tt>refine_interpolate(in,out)</tt> function can be called multiple
651 * times for arbitrary many discrete functions (solution vectors) on the
652 * original grid.
653 *
654 * <li> Solution transfer with coarsening and refinement. After calling
655 * Triangulation::prepare_coarsening_and_refinement the coarsen flags of
656 * either all or none of the children of a (parent-)cell are set. While
657 * coarsening (Triangulation::execute_coarsening_and_refinement) the cells
658 * that are not needed any more will be deleted from the Triangulation.
659 *
660 * For the interpolation from the (to be coarsenend) children to their parent
661 * the children cells are needed. Hence this interpolation and the storing of
662 * the interpolated values of each of the discrete functions that we want to
663 * interpolate needs to take place before these children cells are coarsened
664 * (and deleted!!). Again a pointer for each relevant cell is set to point to
665 * these values (see below). Additionally the DoF indices of the cells that
666 * will not be coarsened need to be stored according to the solution transfer
667 * with pure refinement (cf there). All this is performed by
668 * <tt>prepare_for_coarsening_and_refinement(all_in)</tt> where the
669 * <tt>vector<VectorType> all_in</tt> includes all discrete
670 * functions to be interpolated onto the new grid.
671 *
672 * As we need two different kinds of pointers (<tt>vector<unsigned int> *</tt>
673 * for the Dof indices and <tt>vector<VectorType> *</tt> for the
674 * interpolated DoF values) we use the @p Pointerstruct that includes both of
675 * these pointers and the pointer for each cell points to these @p
676 * Pointerstructs. On each cell only one of the two different pointers is used
677 * at one time hence we could use a <tt>void * pointer</tt> as
678 * <tt>vector<unsigned int> *</tt> at one time and as
679 * <tt>vector<VectorType> *</tt> at the other but using this @p
680 * Pointerstruct in between makes the use of these pointers more safe and
681 * gives better possibility to expand their usage.
682 *
683 * In <tt>interpolate(all_in, all_out)</tt> the refined cells are treated
684 * according to the solution transfer while pure refinement. Additionally, on
685 * each cell that is coarsened (hence previously was a parent cell), the
686 * values of the discrete functions in @p all_out are set to the stored local
687 * interpolated values that are accessible due to the 'vector<VectorType>
688 * *' pointer in @p Pointerstruct that is pointed to by the pointer of that
689 * cell. It is clear that <tt>interpolate(all_in, all_out)</tt> only can be
690 * called with the <tt>vector<VectorType> all_in</tt> that previously was
691 * the parameter of the <tt>prepare_for_coarsening_and_refinement(all_in)</tt>
692 * function. Hence <tt>interpolate(all_in, all_out)</tt> can (in contrast to
693 * <tt>refine_interpolate(in, out)</tt>) only be called once.
694 * </ul>
695 *
696 *
697 * <h3>Interaction with hanging nodes</h3>
698 *
699 * This class does its best to represent on the new mesh the finite element
700 * function that existed on the old mesh, but this may lead to situations
701 * where the function on the new mesh is no longer conforming at hanging
702 * nodes. To this end, consider a situation of a twice refined mesh that
703 * started with a single square cell (i.e., we now have 16 cells). Consider
704 * also that we coarsen 4 of the cells back to the first refinement level. In
705 * this case, we end up with a mesh that will look as follows if we were to
706 * use a $Q_1$ element:
707 *
708 * @image html hanging_nodes.png ""
709 *
710 * The process of interpolating from the old to the new mesh would imply that
711 * the values of the finite element function will not change on all of the
712 * cells that remained as they are (i.e., the fine cells) but that on the
713 * coarse cell at the top right, the four values at the vertices are obtained
714 * by interpolating down from its former children. If the original function
715 * was not linear, this implies that the marked hanging nodes will retain
716 * their old values which, in general, will not lead to a continuous function
717 * along the corresponding edges. In other words, the solution vector obtained
718 * after SolutionTransfer::interpolate() does not satisfy hanging node
719 * constraints: it corresponds to the pointwise interpolation, but not to the
720 * interpolation <i>onto the new finite element space that contains
721 * constraints from hanging nodes</i>.
722 *
723 * Whether this is a problem you need to worry about or not depends on your
724 * application. The situation is easily corrected, of course, by applying
725 * AffineConstraints::distribute() to your solution vector after transfer,
726 * using a constraints object computed on the new DoFHandler object (you
727 * probably need to create this object anyway if you have hanging nodes). This
728 * is also what is done, for example, in step-15.
729 *
730 * @note This situation can only happen if you do coarsening. If all cells
731 * remain as they are or are refined, then SolutionTransfer::interpolate()
732 * computes a new vector of nodal values, but the function represented is of
733 * course exactly the same because the old finite element space is a subspace
734 * of the new one. Thus, if the old function was conforming (i.e., satisfied
735 * hanging node constraints), then so does the new one, and it is not
736 * necessary to call AffineConstraints::distribute().
737 *
738 *
739 * <h3>Implementation in the context of hp-finite elements</h3>
740 *
741 * In the case of DoFHandlers with hp-capabilities, nothing defines which of
742 * the finite elements that are part of the hp::FECollection associated with
743 * the DoFHandler, should be considered on cells that are not active (i.e.,
744 * that have children). This is because degrees of freedom are only allocated
745 * for active cells and, in fact, it is not allowed to set an active FE index
746 * on non-active cells using DoFAccessor::set_active_fe_index().
747 *
748 * It is, thus, not entirely natural what should happen if, for example, a few
749 * cells are coarsened away. This class then implements the following
750 * algorithm:
751 * - If a cell is refined, then the values of the solution vector(s) are
752 * interpolated before refinement on the to-be-refined cell from the space
753 * of the active finite element to the one of the future finite element. These
754 * values are then distributed on the finite element spaces of the children
755 * post-refinement. This may lose information if, for example, the old cell
756 * used a Q2 space and the children use Q1 spaces, or the information may be
757 * prolonged if the parent cell used a Q1 space and the children are Q2s.
758 * - If cells are to be coarsened, then the values from the child cells are
759 * interpolated to the parent cell using the largest of the child cell
760 * future finite element spaces, which will be identified as the least
761 * dominant element following the FiniteElementDomination logic (consult
762 * hp::FECollection::find_dominated_fe_extended() for more information). For
763 * example, if the children of a cell use Q1, Q2 and Q3 spaces, then the
764 * values from the children are interpolated into a Q3 space on the parent
765 * cell. After refinement, this Q3 function on the parent cell is then
766 * interpolated into the space the user has selected for this cell (which
767 * may be different from Q3, in this example, if the user has set the active
768 * FE index for a different space post-refinement and before calling
769 * DoFHandler::distribute_dofs()).
770 *
771 * @note In the context of hp-refinement, if cells are coarsened or the
772 * polynomial degree is lowered on some cells, then the old finite element
773 * space is not a subspace of the new space and you may run into the same
774 * situation as discussed above with hanging nodes. You may want to consider
775 * calling AffineConstraints::distribute() on the vector obtained by
776 * transferring the solution.
777 *
778 * @ingroup numerics
779 *
780 * @deprecated Use dealii::SolutionTransfer instead.
781 */
782 template <int dim, typename VectorType = Vector<double>, int spacedim = dim>
783 class SolutionTransfer
784 {
785 public:
786 /**
787 * Constructor, takes the current DoFHandler as argument.
788 */
789 SolutionTransfer(const DoFHandler<dim, spacedim> &dof);
790
791 /**
792 * Destructor
793 */
794 ~SolutionTransfer();
795
796 /**
797 * Reinit this class to the state that it has directly after calling the
798 * Constructor
799 */
800 void
801 clear();
802
803 /**
804 * Prepares the @p SolutionTransfer for pure refinement. It stores the dof
805 * indices of each cell. After calling this function only calling the @p
806 * refine_interpolate functions is allowed.
807 */
808 void
809 prepare_for_pure_refinement();
810
811 /**
812 * Prepares the @p SolutionTransfer for coarsening and refinement. It stores
813 * the dof indices of each cell and stores the dof values of the vectors in
814 * @p all_in in each cell that'll be coarsened. @p all_in includes all
815 * vectors that are to be interpolated onto the new (refined and/or
816 * coarsenend) grid.
817 */
818 void
819 prepare_for_coarsening_and_refinement(
820 const std::vector<VectorType> &all_in);
821
822 /**
823 * Same as previous function but for only one discrete function to be
824 * interpolated.
825 */
826 void
827 prepare_for_coarsening_and_refinement(const VectorType &in);
828
829 /**
830 * This function interpolates the discrete function @p in, which is a vector
831 * on the grid before the refinement, to the function @p out which then is a
832 * vector on the refined grid. It assumes the vectors having the right sizes
833 * (i.e. <tt>in.size()==n_dofs_old</tt>,
834 * <tt>out.size()==n_dofs_refined</tt>)
835 *
836 * Calling this function is allowed only if @p prepare_for_pure_refinement
837 * is called and the refinement is executed before. Multiple calling of this
838 * function is allowed. e.g. for interpolating several functions.
839 */
840 void
841 refine_interpolate(const VectorType &in, VectorType &out) const;
842
843 /**
844 * This function interpolates the discrete functions that are stored in @p
845 * all_in onto the refined and/or coarsenend grid. It assumes the vectors in
846 * @p all_in denote the same vectors as in @p all_in as parameter of
847 * <tt>prepare_for_refinement_and_coarsening(all_in)</tt>. However, there is
848 * no way of verifying this internally, so be careful here.
849 *
850 * Calling this function is allowed only if first
851 * Triangulation::prepare_coarsening_and_refinement, second @p
852 * SolutionTransfer::prepare_for_coarsening_and_refinement, an then third
853 * Triangulation::execute_coarsening_and_refinement are called before.
854 * Multiple calling of this function is NOT allowed. Interpolating several
855 * functions can be performed in one step.
856 *
857 * The number of output vectors is assumed to be the same as the number of
858 * input vectors. Also, the sizes of the output vectors are assumed to be of
859 * the right size (@p n_dofs_refined). Otherwise an assertion will be
860 * thrown.
861 */
862 void
863 interpolate(const std::vector<VectorType> &all_in,
864 std::vector<VectorType> &all_out) const;
865
866 /**
867 * Same as the previous function. It interpolates only one function. It
868 * assumes the vectors having the right sizes (i.e.
869 * <tt>in.size()==n_dofs_old</tt>, <tt>out.size()==n_dofs_refined</tt>)
870 *
871 * Multiple calling of this function is NOT allowed. Interpolating several
872 * functions can be performed in one step by using <tt>interpolate (all_in,
873 * all_out)</tt>
874 */
875 void
876 interpolate(const VectorType &in, VectorType &out) const;
877
878 /**
879 * Determine an estimate for the memory consumption (in bytes) of this
880 * object.
881 */
882 std::size_t
883 memory_consumption() const;
884
885 /**
886 * Exception
887 */
888 DeclExceptionMsg(
889 ExcNotPrepared,
890 "You are attempting an operation for which this object is "
891 "not prepared. This may be because you either did not call "
892 "one of the prepare_*() functions at all, or because you "
893 "called the wrong one for the operation you are currently "
894 "attempting.");
895
896 /**
897 * Exception
898 */
899 DeclExceptionMsg(
900 ExcAlreadyPrepForRef,
901 "You are attempting to call one of the prepare_*() functions "
902 "of this object to prepare it for an operation for which it "
903 "is already prepared. Specifically, the object was "
904 "previously prepared for pure refinement.");
905
906 /**
907 * Exception
908 */
909 DeclExceptionMsg(
910 ExcAlreadyPrepForCoarseAndRef,
911 "You are attempting to call one of the prepare_*() functions "
912 "of this object to prepare it for an operation for which it "
913 "is already prepared. Specifically, the object was "
914 "previously prepared for both coarsening and refinement.");
915
916 private:
917 /**
918 * Pointer to the degree of freedom handler to work with.
919 */
920 ObserverPointer<const DoFHandler<dim, spacedim>,
921 SolutionTransfer<dim, VectorType, spacedim>>
922 dof_handler;
923
924 /**
925 * Stores the number of DoFs before the refinement and/or coarsening.
926 */
927 types::global_dof_index n_dofs_old;
928
929 /**
930 * Declaration of @p PreparationState that denotes the three possible states
931 * of the @p SolutionTransfer: being prepared for 'pure refinement',
932 * prepared for 'coarsening and refinement' or not prepared.
933 */
934 enum PreparationState
935 {
936 /**
937 * The SolutionTransfer is not yet prepared.
938 */
939 none,
940 /**
941 * The SolutionTransfer is prepared for purely refinement.
942 */
943 pure_refinement,
944 /**
945 * The SolutionTransfer is prepared for coarsening and refinement.
946 */
947 coarsening_and_refinement
948 };
949
950 /**
951 * Definition of the respective variable.
952 */
953 PreparationState prepared_for;
954
955
956 /**
957 * Is used for @p prepare_for_pure_refinement (of course also for
958 * @p prepare_for_coarsening_and_refinement) and stores all dof indices of
959 * the cells that'll be refined.
960 */
961 std::vector<std::vector<types::global_dof_index>> indices_on_cell;
962
963 /**
964 * All cell data (the dof indices and the dof values) should be accessible
965 * from each cell. As each cell has got only one @p user_pointer, multiple
966 * pointers to the data need to be packetized in a structure. Note that in
967 * our case on each cell either the <tt>vector<unsigned int> indices</tt>
968 * (if the cell will be refined) or the <tt>vector<double> dof_values</tt>
969 * (if the children of this cell will be deleted) is needed, hence one @p
970 * user_pointer should be sufficient, but to allow some error checks and to
971 * preserve the user from making user errors the @p user_pointer will be
972 * 'multiplied' by this structure.
973 */
974 struct Pointerstruct
975 {
976 Pointerstruct()
977 : indices_ptr(nullptr)
978 , dof_values_ptr(nullptr)
979 , active_fe_index(0)
980 {}
981 Pointerstruct(std::vector<types::global_dof_index> *indices_ptr_in,
982 const unsigned int active_fe_index_in = 0)
983 : indices_ptr(indices_ptr_in)
984 , dof_values_ptr(nullptr)
985 , active_fe_index(active_fe_index_in)
986 {}
987 Pointerstruct(
988 std::vector<Vector<typename VectorType::value_type>> *dof_values_ptr_in,
989 const unsigned int active_fe_index_in = 0)
990 : indices_ptr(nullptr)
991 , dof_values_ptr(dof_values_ptr_in)
992 , active_fe_index(active_fe_index_in)
993 {}
994 std::size_t
995 memory_consumption() const;
996
997 std::vector<types::global_dof_index> *indices_ptr;
998 std::vector<Vector<typename VectorType::value_type>> *dof_values_ptr;
999 unsigned int active_fe_index;
1000 };
1001
1002 /**
1003 * Map mapping from level and index of cell to the @p Pointerstructs (cf.
1004 * there). This map makes it possible to keep all the information needed to
1005 * transfer the solution inside this object rather than using user pointers
1006 * of the Triangulation for this purpose.
1007 */
1008 std::map<std::pair<unsigned int, unsigned int>, Pointerstruct> cell_map;
1009
1010 /**
1011 * Is used for @p prepare_for_coarsening_and_refinement. The interpolated
1012 * dof values of all cells that'll be coarsened will be stored in this
1013 * vector.
1014 */
1015 std::vector<std::vector<Vector<typename VectorType::value_type>>>
1016 dof_values_on_cell;
1017 };
1018 } // namespace Legacy
1019
1020 DEAL_II_NAMESPACE_CLOSE
1021
1022 #endif