Debian Codegraph @

include/deal.II/meshworker/loop.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2009 - 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
16 #ifndef dealii_mesh_worker_loop_h
17 #define dealii_mesh_worker_loop_h
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/template_constraints.h>
22 #include <deal.II/base/work_stream.h>
23
24 #include <deal.II/grid/filtered_iterator.h>
25 #include <deal.II/grid/tria.h>
26
27 #include <deal.II/meshworker/dof_info.h>
28 #include <deal.II/meshworker/integration_info.h>
29 #include <deal.II/meshworker/local_integrator.h>
30
31 #include <functional>
32
33 DEAL_II_NAMESPACE_OPEN
34
35 // Forward declaration
36 #ifndef DOXYGEN
37 template <typename>
38 class TriaActiveIterator;
39 #endif
40
41 namespace internal
42 {
43 /**
44 * Find out if an iterator supports inactive cells.
45 */
46 template <class DI>
47 inline bool
48 is_active_iterator(const DI &)
49 {
50 return false;
51 }
52
53 template <typename AccessorType>
54 inline bool
55 is_active_iterator(const TriaActiveIterator<AccessorType> &)
56 {
57 return true;
58 }
59
60 template <typename AccessorType>
61 inline bool
62 is_active_iterator(
63 const dealii::FilteredIterator<TriaActiveIterator<AccessorType>> &)
64 {
65 return true;
66 }
67
68 template <int dim, class DOFINFO, class A>
69 void
70 assemble(const MeshWorker::DoFInfoBox<dim, DOFINFO> &dinfo, A *assembler)
71 {
72 dinfo.assemble(*assembler);
73 }
74 } // namespace internal
75
76
77
78 /**
79 * A collection of functions and classes for the mesh loops that are an
80 * ubiquitous part of each finite element program.
81 *
82 * The workhorse of this namespace is the loop() function, which implements a
83 * completely generic loop over all mesh cells.
84 * The loop() function depends on certain objects handed to it as arguments.
85 * These
86 * objects are of two types, @p info objects like DoFInfo and IntegrationInfo and
87 * function objects ("workers") that perform the local operations on cells,
88 * faces, and boundaries.
89 *
90 * Worker objects usually do two different jobs: first, they compute the local
91 * contribution of a cell or face to the global operation. Second, they
92 * assemble this local contribution into the global result, whether a
93 * functional, a form or a bilinear form. While the first job is particular to
94 * the problem being solved, the second is generic and only depends on the
95 * data structures. Therefore, base classes for workers assembling into global
96 * data are provided in the namespace Assembler.
97 *
98 * <h3>Template argument types</h3>
99 *
100 * The functions loop() and cell_action() take some arguments which are
101 * template parameters. Let us list the minimum requirements for these classes
102 * here and describe their properties.
103 *
104 * <h4>ITERATOR</h4>
105 *
106 * Any object that has an <tt>operator++()</tt> and points to a
107 * TriaAccessor or derived class.
108 *
109 * <h4>DOFINFO</h4>
110 *
111 * For an example implementation, refer to the class template DoFInfo. In
112 * order to work with cell_action() and loop(), DOFINFO needs to follow the
113 * following interface.
114 * @code
115 * class DOFINFO
116 * {
117 * private:
118 * DOFINFO();
119 * DOFINFO(const DOFINFO&);
120 * DOFINFO& operator=(const DOFINFO&);
121 *
122 * public:
123 * template <class CellIt>
124 * void reinit(const CellIt& c);
125 *
126 * template <class CellIt, class FaceIt>
127 * void reinit(const CellIt& c, const FaceIt& f, const unsigned int n);
128 *
129 * template <class CellIt, class FaceIt>
130 * void reinit(const CellIt& c, const FaceIt& f, const unsigned int n,
131 * const unsigned int s);
132 *
133 * friend template class DoFInfoBox<int dim, DOFINFO>;
134 * };
135 * @endcode
136 *
137 * The three private functions are called by DoFInfoBox and should not be
138 * needed elsewhere. Obviously, they can be made public and then the friend
139 * declaration at the end may be missing.
140 *
141 * Additionally, you will need at least one public constructor. Furthermore
142 * DOFINFO is pretty useless yet: functions to interface with INTEGRATIONINFO
143 * and ASSEMBLER are needed.
144 *
145 * DOFINFO objects are gathered in a DoFInfoBox. In those objects, we store
146 * the results of local operations on each cell and its faces. Once all this
147 * information has been gathered, an ASSEMBLER is used to assemble it into
148 * global data.
149 *
150 * <h4>INFOBOX</h4>
151 *
152 * This type is exemplified in IntegrationInfoBox. It collects the input data
153 * for actions on cells and faces in INFO objects (see below). It provides the
154 * following interface to loop() and cell_action():
155 *
156 * @code
157 * class INFOBOX
158 * {
159 * public:
160 * template <int dim, class DOFINFO>
161 * void post_cell(const DoFInfoBox<dim, DOFINFO>&);
162 *
163 * template <int dim, class DOFINFO>
164 * void post_faces(const DoFInfoBox<dim, DOFINFO>&);
165 *
166 * INFO cell;
167 * INFO boundary;
168 * INFO face;
169 * INFO subface;
170 * INFO neighbor;
171 * };
172 * @endcode
173 *
174 * The main purpose of this class is gathering the five INFO objects, which
175 * contain the temporary data used on each cell or face. The requirements on
176 * these objects are listed below. Here, we only note that there need to be
177 * these 5 objects with the names listed above.
178 *
179 * The two function templates are call back functions called in cell_action().
180 * The first is called before the faces are worked on, the second after the
181 * faces.
182 *
183 * <h4>INFO</h4>
184 *
185 * See IntegrationInfo for an example of these objects. They contain the
186 * temporary data needed on each cell or face to compute the result. The
187 * MeshWorker only uses the interface
188 *
189 * @code
190 * class INFO
191 * {
192 * public:
193 * void reinit(const DOFINFO& i);
194 * };
195 * @endcode
196 *
197 * @ingroup MeshWorker
198 * @ingroup Integrators
199 */
200 namespace MeshWorker
201 {
202 /**
203 * Collection of parameters to control the execution of MeshWorker loops.
204 */
205 class LoopControl
206 {
207 public:
208 /**
209 * Constructor.
210 */
211 LoopControl()
212 : own_cells(true)
213 , ghost_cells(false)
214 , faces_to_ghost(LoopControl::one)
215 , own_faces(LoopControl::one)
216 , cells_first(true)
217 {}
218
219 /**
220 * Loop over cells owned by this process. Defaults to <code>true</code>.
221 */
222 bool own_cells;
223
224 /**
225 * Loop over cells not owned by this process. Defaults to
226 * <code>false</code>.
227 */
228 bool ghost_cells;
229
230 /**
231 * Enumeration describing when to do assembly on a face: see, e.g.,
232 * MeshWorker::LoopControl::faces_to_ghost for an example of how the value
233 * of this enumeration is interpreted in a particular circumstance.
234 */
235 enum FaceOption
236 {
237 /**
238 * Do not perform assembly on a face.
239 */
240 never,
241 /**
242 * Perform assembly on one face.
243 */
244 one,
245 /**
246 * Perform assembly on both faces.
247 */
248 both
249 };
250
251 /**
252 * Control for looping over faces between a locally owned cell and a ghost
253 * cell:
254 *
255 * - never: Do not assembly these faces.
256 * - one: Only one of the processes will assemble these faces (from the
257 * finer side or the process with the lower MPI rank).
258 * - both: Both processes will assemble these faces. Note that these faces
259 * are never assembled from both sides on a single process.
260 *
261 * The default is <code>one</code>.
262 */
263 FaceOption faces_to_ghost;
264
265 /**
266 * Control for looping over faces between two locally owned cells:
267 *
268 * - never: Do not assemble face terms.
269 * - one: Assemble once (always coming from the finer side).
270 * - both: Assemble each face twice (not implemented for hanging nodes!).
271 *
272 * The default is <code>one</code>.
273 */
274 FaceOption own_faces;
275
276 /**
277 * A flag to determine if cells integrals should be done before or after
278 * face integrals. The default is <code>true</code>.
279 */
280 bool cells_first;
281 };
282
283
284
285 /**
286 * The function called by loop() to perform the required actions on a cell
287 * and its faces. The three functions <tt>cell_worker</tt>,
288 * <tt>boundary_worker</tt> and <tt>face_worker</tt> are the same ones
289 * handed to loop(). While there we only run the loop over all cells, here,
290 * we do a single cell and, if necessary, its faces, interior and boundary.
291 *
292 * Upon return, the DoFInfo objects in the DoFInfoBox are filled with the
293 * data computed on the cell and each of the faces. Thus, after the
294 * execution of this function, we are ready to call DoFInfoBox::assemble()
295 * to distribute the local data into global data.
296 *
297 * @param cell is the cell we work on
298 * @param dof_info is the object into which local results are entered. It is
299 * expected to have been set up for the right types of data.
300 * @param info is the object containing additional data only needed for
301 * internal processing.
302 * @param cell_worker defines the local action on each cell.
303 * @param boundary_worker defines the local action on boundary faces
304 * @param face_worker defines the local action on interior faces.
305 * @param loop_control control structure to specify what actions should be
306 * performed.
307 *
308 * @ingroup MeshWorker
309 */
310 template <class INFOBOX,
311 class DOFINFO,
312 int dim,
313 int spacedim,
314 typename IteratorType>
315 void
316 cell_action(
317 IteratorType cell,
318 DoFInfoBox<dim, DOFINFO> &dof_info,
319 INFOBOX &info,
320 const std::function<void(DOFINFO &, typename INFOBOX::CellInfo &)>
321 &cell_worker,
322 const std::function<void(DOFINFO &, typename INFOBOX::CellInfo &)>
323 &boundary_worker,
324 const std::function<void(DOFINFO &,
325 DOFINFO &,
326 typename INFOBOX::CellInfo &,
327 typename INFOBOX::CellInfo &)> &face_worker,
328 const LoopControl &loop_control)
329 {
330 const bool ignore_subdomain =
331 (cell->get_triangulation().locally_owned_subdomain() ==
332 numbers::invalid_subdomain_id);
333
334 types::subdomain_id csid = (cell->is_level_cell()) ?
335 cell->level_subdomain_id() :
336 cell->subdomain_id();
337
338 const bool own_cell =
339 ignore_subdomain ||
340 (csid == cell->get_triangulation().locally_owned_subdomain());
341
342 dof_info.reset();
343
344 if ((!ignore_subdomain) && (csid == numbers::artificial_subdomain_id))
345 return;
346
347 dof_info.cell.reinit(cell);
348 dof_info.cell_valid = true;
349
350 const bool integrate_cell = (cell_worker != nullptr);
351 const bool integrate_boundary = (boundary_worker != nullptr);
352 const bool integrate_interior_face = (face_worker != nullptr);
353
354 if (integrate_cell)
355 info.cell.reinit(dof_info.cell);
356 // Execute this, if cells
357 // have to be dealt with
358 // before faces
359 if (integrate_cell && loop_control.cells_first &&
360 ((loop_control.own_cells && own_cell) ||
361 (loop_control.ghost_cells && !own_cell)))
362 cell_worker(dof_info.cell, info.cell);
363
364 // Call the callback function in
365 // the info box to do
366 // computations between cell and
367 // face action.
368 info.post_cell(dof_info);
369
370 if (integrate_interior_face || integrate_boundary)
371 for (const unsigned int face_no : cell->face_indices())
372 {
373 typename IteratorType::AccessorType::Container::face_iterator face =
374 cell->face(face_no);
375 if (cell->at_boundary(face_no) &&
376 !cell->has_periodic_neighbor(face_no))
377 {
378 // only integrate boundary faces of own cells
379 if (integrate_boundary && own_cell)
380 {
381 dof_info.interior_face_available[face_no] = true;
382 dof_info.interior[face_no].reinit(cell, face, face_no);
383 info.boundary.reinit(dof_info.interior[face_no]);
384 boundary_worker(dof_info.interior[face_no], info.boundary);
385 }
386 }
387 else if (integrate_interior_face)
388 {
389 // Interior face
390 TriaIterator<typename IteratorType::AccessorType> neighbor =
391 cell->neighbor_or_periodic_neighbor(face_no);
392
393 types::subdomain_id neighbid = numbers::artificial_subdomain_id;
394 if (neighbor->is_level_cell())
395 neighbid = neighbor->level_subdomain_id();
396 // subdomain id is only valid for active cells
397 else if (neighbor->is_active())
398 neighbid = neighbor->subdomain_id();
399
400 const bool own_neighbor =
401 ignore_subdomain ||
402 (neighbid ==
403 cell->get_triangulation().locally_owned_subdomain());
404
405 // skip all faces between two ghost cells
406 if (!own_cell && !own_neighbor)
407 continue;
408
409 // skip if the user doesn't want faces between own cells
410 if (own_cell && own_neighbor &&
411 loop_control.own_faces == LoopControl::never)
412 continue;
413
414 // skip face to ghost
415 if (own_cell != own_neighbor &&
416 loop_control.faces_to_ghost == LoopControl::never)
417 continue;
418
419 // Deal with refinement edges from the refined side. Assuming
420 // one-irregular meshes, this situation should only occur if both
421 // cells are active.
422 const bool periodic_neighbor =
423 cell->has_periodic_neighbor(face_no);
424
425 if ((!periodic_neighbor && cell->neighbor_is_coarser(face_no)) ||
426 (periodic_neighbor &&
427 cell->periodic_neighbor_is_coarser(face_no)))
428 {
429 Assert(cell->is_active(), ExcInternalError());
430 Assert(neighbor->is_active(), ExcInternalError());
431
432 // skip if only one processor needs to assemble the face
433 // to a ghost cell and the fine cell is not ours.
434 if (!own_cell &&
435 loop_control.faces_to_ghost == LoopControl::one)
436 continue;
437
438 const std::pair<unsigned int, unsigned int> neighbor_face_no =
439 periodic_neighbor ?
440 cell->periodic_neighbor_of_coarser_periodic_neighbor(
441 face_no) :
442 cell->neighbor_of_coarser_neighbor(face_no);
443 const typename IteratorType::AccessorType::Container::
444 face_iterator nface =
445 neighbor->face(neighbor_face_no.first);
446
447 dof_info.interior_face_available[face_no] = true;
448 dof_info.exterior_face_available[face_no] = true;
449 dof_info.interior[face_no].reinit(cell, face, face_no);
450 info.face.reinit(dof_info.interior[face_no]);
451 dof_info.exterior[face_no].reinit(neighbor,
452 nface,
453 neighbor_face_no.first,
454 neighbor_face_no.second);
455 info.subface.reinit(dof_info.exterior[face_no]);
456
457 face_worker(dof_info.interior[face_no],
458 dof_info.exterior[face_no],
459 info.face,
460 info.subface);
461 }
462 else
463 {
464 // If iterator is active and neighbor is refined, skip
465 // internal face.
466 if (dealii::internal::is_active_iterator(cell) &&
467 neighbor->has_children())
468 {
469 Assert(
470 loop_control.own_faces != LoopControl::both,
471 ExcMessage(
472 "Assembling from both sides for own_faces is not "
473 "supported with hanging nodes!"));
474 continue;
475 }
476
477 // Now neighbor is on same level, double-check this:
478 Assert(cell->level() == neighbor->level(),
479 ExcInternalError());
480
481 // If we own both cells only do faces from one side (unless
482 // LoopControl says otherwise). Here, we rely on cell
483 // comparison that will look at cell->index().
484 if (own_cell && own_neighbor &&
485 loop_control.own_faces == LoopControl::one &&
486 (neighbor < cell))
487 continue;
488
489 // independent of loop_control.faces_to_ghost,
490 // we only look at faces to ghost on the same level once
491 // (only where own_cell=true and own_neighbor=false)
492 if (!own_cell)
493 continue;
494
495 // now only one processor assembles faces_to_ghost. We let the
496 // processor with the smaller (level-)subdomain id assemble
497 // the face.
498 if (own_cell && !own_neighbor &&
499 loop_control.faces_to_ghost == LoopControl::one &&
500 (neighbid < csid))
501 continue;
502
503 const unsigned int neighbor_face_no =
504 periodic_neighbor ?
505 cell->periodic_neighbor_face_no(face_no) :
506 cell->neighbor_face_no(face_no);
507 Assert(periodic_neighbor ||
508 neighbor->face(neighbor_face_no) == face,
509 ExcInternalError());
510 // Regular interior face
511 dof_info.interior_face_available[face_no] = true;
512 dof_info.exterior_face_available[face_no] = true;
513 dof_info.interior[face_no].reinit(cell, face, face_no);
514 info.face.reinit(dof_info.interior[face_no]);
515 dof_info.exterior[face_no].reinit(neighbor,
516 neighbor->face(
517 neighbor_face_no),
518 neighbor_face_no);
519 info.neighbor.reinit(dof_info.exterior[face_no]);
520
521 face_worker(dof_info.interior[face_no],
522 dof_info.exterior[face_no],
523 info.face,
524 info.neighbor);
525 }
526 }
527 } // faces
528 // Call the callback function in
529 // the info box to do
530 // computations between face and
531 // cell action.
532 info.post_faces(dof_info);
533
534 // Execute this, if faces
535 // have to be handled first
536 if (integrate_cell && !loop_control.cells_first &&
537 ((loop_control.own_cells && own_cell) ||
538 (loop_control.ghost_cells && !own_cell)))
539 cell_worker(dof_info.cell, info.cell);
540 }
541
542
543 /**
544 * The main work function of this namespace. It is a loop over all cells in
545 * an iterator range, in which cell_action() is called for each cell.
546 * Unilaterally refined interior faces are handled automatically by the
547 * loop. Most of the work in this loop is done in cell_action(), which also
548 * receives most of the parameters of this function. See the documentation
549 * there for more details.
550 *
551 * If you don't want anything to be done on cells, interior or boundary
552 * faces to happen, simply pass the Null pointer to one of the function
553 * arguments.
554 *
555 * @ingroup MeshWorker
556 */
557 template <int dim,
558 int spacedim,
559 class DOFINFO,
560 class INFOBOX,
561 typename AssemblerType,
562 typename IteratorType>
563 void
564 loop(IteratorType begin,
565 std_cxx20::type_identity_t<IteratorType> end,
566 DOFINFO &dinfo,
567 INFOBOX &info,
568 const std::function<void(std_cxx20::type_identity_t<DOFINFO> &,
569 typename INFOBOX::CellInfo &)> &cell_worker,
570 const std::function<void(std_cxx20::type_identity_t<DOFINFO> &,
571 typename INFOBOX::CellInfo &)> &boundary_worker,
572 const std::function<void(std_cxx20::type_identity_t<DOFINFO> &,
573 std_cxx20::type_identity_t<DOFINFO> &,
574 typename INFOBOX::CellInfo &,
575 typename INFOBOX::CellInfo &)> &face_worker,
576 AssemblerType &assembler,
577 const LoopControl &lctrl = LoopControl())
578 {
579 DoFInfoBox<dim, DOFINFO> dof_info(dinfo);
580
581 assembler.initialize_info(dof_info.cell, false);
582 for (const unsigned int i : GeometryInfo<dim>::face_indices())
583 {
584 assembler.initialize_info(dof_info.interior[i], true);
585 assembler.initialize_info(dof_info.exterior[i], true);
586 }
587
588 // Loop over all cells
589 WorkStream::run(
590 begin,
591 end,
592 [&cell_worker, &boundary_worker, &face_worker, &lctrl](
593 IteratorType cell, INFOBOX &info, DoFInfoBox<dim, DOFINFO> &dof_info) {
594 cell_action<INFOBOX, DOFINFO, dim, spacedim, IteratorType>(
595 cell,
596 dof_info,
597 info,
598 cell_worker,
599 boundary_worker,
600 face_worker,
601 lctrl);
602 },
603 [&assembler](const MeshWorker::DoFInfoBox<dim, DOFINFO> &dinfo) {
604 dealii::internal::assemble<dim, DOFINFO, AssemblerType>(dinfo,
605 &assembler);
606 },
607 info,
608 dof_info);
609 }
610
611
612 /**
613 * Simplified interface for loop() if specialized for integration, using the
614 * virtual functions in LocalIntegrator.
615 *
616 * @deprecated This function is deprecated, along with the LocalIntegrator
617 * class. Use the MeshWorker::loop() function directly, with three function
618 * objects that perform the cell, boundary, and interior face integration.
619 *
620 * @ingroup MeshWorker
621 */
622 template <int dim,
623 int spacedim,
624 typename IteratorType,
625 typename AssemblerType>
626 DEAL_II_DEPRECATED void
627 integration_loop(IteratorType begin,
628 std_cxx20::type_identity_t<IteratorType> end,
629 DoFInfo<dim, spacedim> &dof_info,
630 IntegrationInfoBox<dim, spacedim> &box,
631 const LocalIntegrator<dim, spacedim> &integrator,
632 AssemblerType &assembler,
633 const LoopControl &lctrl = LoopControl())
634 {
635 std::function<void(DoFInfo<dim, spacedim> &,
636 IntegrationInfo<dim, spacedim> &)>
637 cell_worker;
638 std::function<void(DoFInfo<dim, spacedim> &,
639 IntegrationInfo<dim, spacedim> &)>
640 boundary_worker;
641 std::function<void(DoFInfo<dim, spacedim> &,
642 DoFInfo<dim, spacedim> &,
643 IntegrationInfo<dim, spacedim> &,
644 IntegrationInfo<dim, spacedim> &)>
645 face_worker;
646 if (integrator.use_cell)
647 cell_worker =
648 [&integrator](DoFInfo<dim, spacedim> &dof_info,
649 IntegrationInfo<dim, spacedim> &integration_info) {
650 integrator.cell(dof_info, integration_info);
651 };
652 if (integrator.use_boundary)
653 boundary_worker =
654 [&integrator](DoFInfo<dim, spacedim> &dof_info,
655 IntegrationInfo<dim, spacedim> &integration_info) {
656 integrator.boundary(dof_info, integration_info);
657 };
658 if (integrator.use_face)
659 face_worker =
660 [&integrator](DoFInfo<dim, spacedim> &dof_info_1,
661 DoFInfo<dim, spacedim> &dof_info_2,
662 IntegrationInfo<dim, spacedim> &integration_info_1,
663 IntegrationInfo<dim, spacedim> &integration_info_2) {
664 integrator.face(dof_info_1,
665 dof_info_2,
666 integration_info_1,
667 integration_info_2);
668 };
669
670 loop<dim, spacedim>(begin,
671 end,
672 dof_info,
673 box,
674 cell_worker,
675 boundary_worker,
676 face_worker,
677 assembler,
678 lctrl);
679 }
680
681 } // namespace MeshWorker
682
683 DEAL_II_NAMESPACE_CLOSE
684
685 #endif