Debian Codegraph @

include/deal.II/meshworker/mesh_loop.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2017 - 2023 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_mesh_loop_h
17 #define dealii_mesh_worker_mesh_loop_h
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/template_constraints.h>
22 #include <deal.II/base/types.h>
23 #include <deal.II/base/work_stream.h>
24
25 #include <deal.II/grid/filtered_iterator.h>
26 #include <deal.II/grid/tria.h>
27
28 #include <deal.II/meshworker/assemble_flags.h>
29 #include <deal.II/meshworker/dof_info.h>
30 #include <deal.II/meshworker/integration_info.h>
31 #include <deal.II/meshworker/local_integrator.h>
32 #include <deal.II/meshworker/loop.h>
33
34 #include <functional>
35 #include <type_traits>
36
37 DEAL_II_NAMESPACE_OPEN
38
39 // Forward declaration
40 #ifndef DOXYGEN
41 template <typename>
42 class TriaActiveIterator;
43 #endif
44
45 namespace MeshWorker
46 {
47 namespace internal
48 {
49 /**
50 * A helper class to provide a type definition for the underlying cell
51 * iterator type.
52 */
53 template <typename CellIteratorType>
54 struct CellIteratorBaseType
55 {
56 /**
57 * Type definition for the cell iterator type.
58 */
59 using type = CellIteratorType;
60 };
61
62 /**
63 * A helper class to provide a type definition for the underlying cell
64 * iterator type.
65 *
66 * This specialization is for IteratorRange, which may have either a
67 * TriaActiveIterator or a FilteredIterator as its base type.
68 */
69 template <typename CellIteratorType>
70 struct CellIteratorBaseType<IteratorOverIterators<CellIteratorType>>
71 {
72 /**
73 * Type definition for the cell iterator type.
74 */
75 // Since we can have filtered iterators and the like as template
76 // arguments, we recursivelyremove the template layers to retrieve the
77 // underlying iterator type.
78 using type = typename CellIteratorBaseType<CellIteratorType>::type;
79 };
80
81 /**
82 * A helper class to provide a type definition for the underlying cell
83 * iterator type.
84 *
85 * This specialization is for FilteredIterator, which may have either a
86 * TriaActiveIterator as its base type, or may be nested with another
87 * FilteredIterator as the type to iterate over.
88 */
89 template <typename CellIteratorType>
90 struct CellIteratorBaseType<FilteredIterator<CellIteratorType>>
91 {
92 /**
93 * Type definition for the cell iterator type.
94 */
95 // Since we can have nested filtered iterators, we recursively
96 // remove the template layers to retrieve the underlying iterator type.
97 using type = typename CellIteratorBaseType<CellIteratorType>::type;
98 };
99 } // namespace internal
100
101 #ifdef DOXYGEN
102 /**
103 * This alias introduces a friendly and short name for the function type
104 * for the cell worker used in mesh_loop().
105 */
106 using CellWorkerFunctionType = std::function<
107 void(const CellIteratorBaseType &, ScratchData &, CopyData &)>;
108
109 /**
110 * This alias introduces a friendly and short name for the function type
111 * for the cell worker used in mesh_loop().
112 */
113 using CopierFunctionType = std::function<void(const CopyData &)>;
114
115 /**
116 * This alias introduces a friendly and short name for the function type
117 * for the boundary worker used in mesh_loop().
118 */
119 using BoundaryWorkerFunctionType =
120 std::function<void(const CellIteratorBaseType &,
121 const unsigned int,
122 ScratchData &,
123 CopyData &)>;
124
125 /**
126 * This alias introduces a friendly and short name for the function type
127 * for the face worker used in mesh_loop().
128 */
129 using FaceWorkerFunctionType =
130 std::function<void(const CellIteratorBaseType &,
131 const unsigned int,
132 const unsigned int,
133 const CellIteratorBaseType &,
134 const unsigned int,
135 const unsigned int,
136 ScratchData &,
137 CopyData &)>;
138 #endif
139
140 /**
141 * This function extends the WorkStream concept to work on meshes
142 * (cells and/or faces) and handles the complicated logic for
143 * work on adaptively refined faces
144 * and parallel computation (work on faces to ghost neighbors for example).
145 * The @p mesh_loop can be used to simplify operations on cells (for example
146 * assembly), on boundaries (Neumann type boundary conditions), or on
147 * interior faces (for example in discontinuous Galerkin methods). The
148 * function is used in a number of tutorials, including step-12, step-16,
149 * and step-47, to name just a few.
150 *
151 * For uniformly refined meshes, it would be relatively easy to use
152 * WorkStream::run() with a @p cell_worker that also loops over faces, and
153 * takes care of assembling face terms depending on the current and neighbor
154 * cell. All user codes that do these loops would then need to insert
155 * manually the logic that identifies, for every face of the current cell,
156 * the neighboring cell, and the face index on the neighboring cell that
157 * corresponds to the current face.
158 *
159 * This is more complicated if local refinement is enabled and the current or
160 * neighbor cells have hanging nodes. In this case it is also necessary to
161 * identify the corresponding subface on either the current or the neighbor
162 * faces.
163 *
164 * This method externalizes that logic (which is independent from user codes)
165 * and separates the assembly of face terms (internal faces, boundary faces,
166 * or faces between different subdomain ids on parallel computations) from
167 * the assembling on cells, allowing the user to specify two additional
168 * workers (a @p cell_worker, a @p boundary_worker, and a @p face_worker) that
169 * are called automatically in each @p cell, according to the specific
170 * AssembleFlags @p flags that are passed. The @p cell_worker is passed the
171 * cell identifier, a ScratchData object, and a CopyData object, following
172 * the same principles of WorkStream::run(). Internally the function passes to
173 * @p boundary_worker, in addition to the above, also a @p face_no parameter
174 * that identifies the face on which the integration should be performed. The
175 * @p face_worker instead needs to identify the current face unambiguously
176 * both on the cell and on the neighboring cell, and it is therefore called
177 * with six arguments (three for each cell: the actual cell, the face index,
178 * and the subface_index. If no subface integration is needed, then the
179 * subface_index is numbers::invalid_unsigned_int) in addition to the usual
180 * ScratchData and CopyData objects.
181 *
182 * If the flag AssembleFlags::assemble_own_cells is passed, then the default
183 * behavior is to first loop over faces and do the work there, and then
184 * compute the actual work on the cell. It is possible to perform the
185 * integration on the cells after working on faces, by adding the flag
186 * AssembleFlags::cells_after_faces.
187 *
188 * If the flag AssembleFlags::assemble_own_interior_faces_once is specified,
189 * then each interior face is visited only once, and the @p face_worker is
190 * assumed to integrate all face terms at once (and add contributions to both
191 * sides of the face in a discontinuous Galerkin setting).
192 *
193 * This method is equivalent to the WorkStream::run() method when
194 * AssembleFlags contains only @p assemble_own_cells, and can be used as a
195 * drop-in replacement for that method.
196 *
197 * The two data types ScratchData and CopyData need to have a working copy
198 * constructor. ScratchData is only used in the worker function, while
199 * CopyData is the object passed from the worker to the copier. The CopyData
200 * object is reset to the value provided to this function every time this
201 * function visits a new cell (where it then calls the cell and face
202 * workers). In other words, no state carries over between calling the
203 * `copier` on one cell and the `cell_worker`/`face_worker`/`boundary_worker`
204 * functions on the next cell, and user code needs not reset the copy
205 * object either at the beginning of the cell integration or end of the
206 * copy operation. Resetting the state of the `copier ` inside of a
207 * `face_worker` or `boundary_worker` constitutes a bug, and may lead to
208 * some unexpected results. The following example shows what is not
209 * permissible, as the copier is potentially shared among numerous faces
210 * on a cell:
211 * @code
212 *
213 * using ScratchData = MeshWorker::ScratchData<dim, spacedim>;
214 * using CopyData = MeshWorker::CopyData<1, 1, 1>;
215 * using CellIteratorType = decltype(dof_handler.begin_active());
216 *
217 * ScratchData scratch(...);
218 * CopyData copy(...);
219 *
220 * std::function<void(const CellIteratorType &, ScratchData &, CopyData &)>
221 * empty_cell_worker;
222 *
223 * auto boundary_worker = [...] (
224 * const CellIteratorType &cell,
225 * const unsigned int face,
226 * ScratchData &scratch_data,
227 * CopyData &copy_data)
228 * {
229 * const auto &fe_face_values = scratch_data.reinit(cell, face);
230 * copy_data = CopyData(...); // This is an error, as we lose the
231 * // accumulation that has been performed on
232 * // other boundary faces of the same cell.
233 *
234 * for (unsigned int q_point = 0;
235 * q_point < fe_face_values.n_quadrature_points;
236 * ++q_point)
237 * {
238 * copy_data.vectors[0][0] += 1.0 * fe_face_values.JxW(q_point);
239 * }
240 * };
241 *
242 * double value = 0;
243 * auto copier = [...](const CopyData &copy_data)
244 * {
245 * value += copy_data.vectors[0][0]; // Contributions from some faces may
246 * // be missing.
247 * };
248 *
249 * MeshWorker::mesh_loop(dof_handler.active_cell_iterators(),
250 * empty_cell_worker, copier,
251 * scratch, copy,
252 * MeshWorker::assemble_boundary_faces,
253 * boundary_worker);
254 * @endcode
255 *
256 * The queue_length argument indicates the number of items that can be live at
257 * any given time. Each item consists of chunk_size elements of the input
258 * stream that will be worked on by the worker and copier functions one after
259 * the other on the same thread.
260 *
261 * If your data objects are large, or their constructors are expensive, it is
262 * helpful to keep in mind that queue_length copies of the ScratchData object
263 * and `queue_length*chunk_size` copies of the CopyData object are generated.
264 *
265 * @note The types of the function arguments and the default values (empty worker functions)
266 * displayed in the Doxygen documentation here are slightly simplified
267 * compared to the real types.
268 *
269 * @note More information about requirements on template types and meaning
270 * of @p queue_length and @p chunk_size can be found in the documentation of the
271 * WorkStream namespace and its members.
272 *
273 * @ingroup MeshWorker
274 */
275 template <typename CellIteratorType,
276 class ScratchData,
277 class CopyData,
278 typename CellIteratorBaseType =
279 typename internal::CellIteratorBaseType<CellIteratorType>::type>
280 void
281 mesh_loop(
282 #ifdef DOXYGEN
283 const CellIteratorType &begin,
284 const CellIteratorType &end,
285
286 const CellWorkerFunctionType &cell_worker,
287 const CopierType &copier,
288
289 const ScratchData &sample_scratch_data,
290 const CopyData &sample_copy_data,
291
292 const AssembleFlags flags = assemble_own_cells,
293
294 const BoundaryWorkerFunctionType &boundary_worker =
295 BoundaryWorkerFunctionType(),
296
297 const FaceWorkerFunctionType &face_worker = FaceWorkerFunctionType(),
298 const unsigned int queue_length = 2 * MultithreadInfo::n_threads(),
299 const unsigned int chunk_size = 8
300 #else
301 const CellIteratorType &begin,
302 const std_cxx20::type_identity_t<CellIteratorType> &end,
303
304 const std_cxx20::type_identity_t<std::function<
305 void(const CellIteratorBaseType &, ScratchData &, CopyData &)>>
306 &cell_worker,
307 const std_cxx20::type_identity_t<std::function<void(const CopyData &)>>
308 &copier,
309
310 const ScratchData &sample_scratch_data,
311 const CopyData &sample_copy_data,
312
313 const AssembleFlags flags = assemble_own_cells,
314
315 const std_cxx20::type_identity_t<
316 std::function<void(const CellIteratorBaseType &,
317 const unsigned int,
318 ScratchData &,
319 CopyData &)>> &boundary_worker =
320 std::function<void(const CellIteratorBaseType &,
321 const unsigned int,
322 ScratchData &,
323 CopyData &)>(),
324
325 const std_cxx20::type_identity_t<
326 std::function<void(const CellIteratorBaseType &,
327 const unsigned int,
328 const unsigned int,
329 const CellIteratorBaseType &,
330 const unsigned int,
331 const unsigned int,
332 ScratchData &,
333 CopyData &)>> &face_worker =
334 std::function<void(const CellIteratorBaseType &,
335 const unsigned int,
336 const unsigned int,
337 const CellIteratorBaseType &,
338 const unsigned int,
339 const unsigned int,
340 ScratchData &,
341 CopyData &)>(),
342
343 const unsigned int queue_length = 2 * MultithreadInfo::n_threads(),
344 const unsigned int chunk_size = 8
345 #endif
346 )
347 {
348 Assert(
349 (!cell_worker) == !(flags & work_on_cells),
350 ExcMessage(
351 "If you provide a cell worker function, you also need to request "
352 "that work should be done on cells by setting the 'work_on_cells' flag. "
353 "Conversely, if you don't provide a cell worker function, you "
354 "cannot set the 'work_on_cells' flag. One of these two "
355 "conditions is not satisfied."));
356
357 Assert((flags & (assemble_own_interior_faces_once |
358 assemble_own_interior_faces_both)) !=
359 (assemble_own_interior_faces_once |
360 assemble_own_interior_faces_both),
361 ExcMessage(
362 "If you provide a face worker function, you also need to request "
363 "that work should be done on interior faces by setting either the "
364 "'assemble_own_interior_faces_once' flag or the "
365 "'assemble_own_interior_faces_both' flag. "
366 "Conversely, if you don't provide a face worker function, you "
367 "cannot set either of these two flags. One of these two "
368 "conditions is not satisfied."));
369
370 Assert((flags & (assemble_ghost_faces_once | assemble_ghost_faces_both)) !=
371 (assemble_ghost_faces_once | assemble_ghost_faces_both),
372 ExcMessage(
373 "You can only 'specify assemble_ghost_faces_once' "
374 "OR 'assemble_ghost_faces_both', but not both of these flags."));
375
376 Assert(
377 !(flags & cells_after_faces) ||
378 (flags & (assemble_own_cells | assemble_ghost_cells)),
379 ExcMessage(
380 "The option 'cells_after_faces' only makes sense if you assemble on cells."));
381
382 Assert(
383 (!face_worker) == !(flags & work_on_faces),
384 ExcMessage(
385 "If you provide a face worker function, you also need to request "
386 "that work should be done on faces by setting the 'work_on_faces' flag. "
387 "Conversely, if you don't provide a face worker function, you "
388 "cannot set the 'work_on_faces' flag. One of these two "
389 "conditions is not satisfied."));
390
391 Assert(
392 (!boundary_worker) == !(flags & assemble_boundary_faces),
393 ExcMessage(
394 "If you provide a boundary face worker function, you also need to request "
395 "that work should be done on boundary faces by setting the 'assemble_boundary_faces' flag. "
396 "Conversely, if you don't provide a boundary face worker function, you "
397 "cannot set the 'assemble_boundary_faces' flag. One of these two "
398 "conditions is not satisfied."));
399
400 auto cell_action = [&](const CellIteratorBaseType &cell,
401 ScratchData &scratch,
402 CopyData &copy) {
403 // First reset the CopyData class to the empty copy_data given by the
404 // user.
405 copy = sample_copy_data;
406
407 // Store the dimension in which we are working for later use
408 const auto dim = cell->get_triangulation().dimension;
409
410 const bool ignore_subdomain =
411 (cell->get_triangulation().locally_owned_subdomain() ==
412 numbers::invalid_subdomain_id);
413
414 types::subdomain_id current_subdomain_id =
415 (cell->is_level_cell() ? cell->level_subdomain_id() :
416 cell->subdomain_id());
417
418 const bool own_cell =
419 ignore_subdomain ||
420 (current_subdomain_id ==
421 cell->get_triangulation().locally_owned_subdomain());
422
423 if ((!ignore_subdomain) &&
424 (current_subdomain_id == numbers::artificial_subdomain_id))
425 return;
426
427 if (!(flags & (cells_after_faces)) &&
428 (((flags & (assemble_own_cells)) && own_cell) ||
429 ((flags & assemble_ghost_cells) && !own_cell)))
430 cell_worker(cell, scratch, copy);
431
432 if (flags & (work_on_faces | work_on_boundary))
433 for (const unsigned int face_no : cell->face_indices())
434 {
435 if (cell->at_boundary(face_no) &&
436 !cell->has_periodic_neighbor(face_no))
437 {
438 // only integrate boundary faces of own cells
439 if ((flags & assemble_boundary_faces) && own_cell)
440 boundary_worker(cell, face_no, scratch, copy);
441 }
442 else
443 {
444 // interior face, potentially assemble
445 TriaIterator<typename CellIteratorBaseType::AccessorType>
446 neighbor = cell->neighbor_or_periodic_neighbor(face_no);
447
448 types::subdomain_id neighbor_subdomain_id =
449 numbers::artificial_subdomain_id;
450 if (neighbor->is_level_cell())
451 neighbor_subdomain_id = neighbor->level_subdomain_id();
452 // subdomain id is only valid for active cells
453 else if (neighbor->is_active())
454 neighbor_subdomain_id = neighbor->subdomain_id();
455
456 const bool own_neighbor =
457 ignore_subdomain ||
458 (neighbor_subdomain_id ==
459 cell->get_triangulation().locally_owned_subdomain());
460
461 // skip all faces between two ghost cells
462 if (!own_cell && !own_neighbor)
463 continue;
464
465 // skip if the user doesn't want faces between own cells
466 if (own_cell && own_neighbor &&
467 !(flags & (assemble_own_interior_faces_both |
468 assemble_own_interior_faces_once)))
469 continue;
470
471 // skip face to ghost
472 if (own_cell != own_neighbor &&
473 !(flags &
474 (assemble_ghost_faces_both | assemble_ghost_faces_once)))
475 continue;
476
477 // Deal with refinement edges from the refined side. Assuming
478 // one-irregular meshes, this situation should only occur if
479 // both cells are active.
480 const bool periodic_neighbor =
481 cell->has_periodic_neighbor(face_no);
482
483 if (dim > 1 && ((!periodic_neighbor &&
484 cell->neighbor_is_coarser(face_no) &&
485 neighbor->is_active()) ||
486 (periodic_neighbor &&
487 cell->periodic_neighbor_is_coarser(face_no) &&
488 neighbor->is_active())))
489 {
490 Assert(cell->is_active(), ExcInternalError());
491
492 // skip if only one processor needs to assemble the face
493 // to a ghost cell and the fine cell is not ours.
494 if (!own_cell && (flags & assemble_ghost_faces_once))
495 continue;
496
497 const std::pair<unsigned int, unsigned int>
498 neighbor_face_no =
499 periodic_neighbor ?
500 cell->periodic_neighbor_of_coarser_periodic_neighbor(
501 face_no) :
502 cell->neighbor_of_coarser_neighbor(face_no);
503
504 face_worker(cell,
505 face_no,
506 numbers::invalid_unsigned_int,
507 neighbor,
508 neighbor_face_no.first,
509 neighbor_face_no.second,
510 scratch,
511 copy);
512
513 if (flags & assemble_own_interior_faces_both)
514 {
515 // If own faces are to be assembled from both sides,
516 // call the faceworker again with swapped arguments.
517 // This is because we won't be looking at an adaptively
518 // refined edge coming from the other side.
519 face_worker(neighbor,
520 neighbor_face_no.first,
521 neighbor_face_no.second,
522 cell,
523 face_no,
524 numbers::invalid_unsigned_int,
525 scratch,
526 copy);
527 }
528 }
529 else if (dim == 1 && cell->level() > neighbor->level())
530 {
531 // In one dimension, there is no other check to do
532 const unsigned int neighbor_face_no =
533 periodic_neighbor ?
534 cell->periodic_neighbor_face_no(face_no) :
535 cell->neighbor_face_no(face_no);
536 Assert(periodic_neighbor ||
537 neighbor->face(neighbor_face_no) ==
538 cell->face(face_no),
539 ExcInternalError());
540
541 face_worker(cell,
542 face_no,
543 numbers::invalid_unsigned_int,
544 neighbor,
545 neighbor_face_no,
546 numbers::invalid_unsigned_int,
547 scratch,
548 copy);
549
550 if (flags & assemble_own_interior_faces_both)
551 {
552 // If own faces are to be assembled from both sides,
553 // call the faceworker again with swapped arguments.
554 face_worker(neighbor,
555 neighbor_face_no,
556 numbers::invalid_unsigned_int,
557 cell,
558 face_no,
559 numbers::invalid_unsigned_int,
560 scratch,
561 copy);
562 }
563 }
564 else
565 {
566 // If iterator is active and neighbor is refined, skip
567 // internal face.
568 if (dealii::internal::is_active_iterator(cell) &&
569 neighbor->has_children())
570 continue;
571
572 // Now neighbor is on the same refinement level.
573 // Double check.
574 Assert((!periodic_neighbor &&
575 !cell->neighbor_is_coarser(face_no)) ||
576 (periodic_neighbor &&
577 !cell->periodic_neighbor_is_coarser(face_no)),
578 ExcInternalError());
579
580 // If we own both cells only do faces from one side (unless
581 // AssembleFlags says otherwise). Here, we rely on cell
582 // comparison that will look at cell->index().
583 if (own_cell && own_neighbor &&
584 (flags & assemble_own_interior_faces_once) &&
585 (neighbor < cell))
586 continue;
587
588 // We only look at faces to ghost on the same level once
589 // (only where own_cell=true and own_neighbor=false)
590 if (!own_cell)
591 continue;
592
593 // now only one processor assembles faces_to_ghost. We let
594 // the processor with the smaller (level-)subdomain id
595 // assemble the face.
596 if (own_cell && !own_neighbor &&
597 (flags & assemble_ghost_faces_once) &&
598 (neighbor_subdomain_id < current_subdomain_id))
599 continue;
600
601 const unsigned int neighbor_face_no =
602 periodic_neighbor ?
603 cell->periodic_neighbor_face_no(face_no) :
604 cell->neighbor_face_no(face_no);
605 Assert(periodic_neighbor ||
606 neighbor->face(neighbor_face_no) ==
607 cell->face(face_no),
608 ExcInternalError());
609
610 face_worker(cell,
611 face_no,
612 numbers::invalid_unsigned_int,
613 neighbor,
614 neighbor_face_no,
615 numbers::invalid_unsigned_int,
616 scratch,
617 copy);
618 }
619 }
620 } // faces
621
622 // Execute the cell_worker if faces are handled before cells
623 if ((flags & cells_after_faces) &&
624 (((flags & assemble_own_cells) && own_cell) ||
625 ((flags & assemble_ghost_cells) && !own_cell)))
626 cell_worker(cell, scratch, copy);
627 };
628
629 // Submit to workstream
630 WorkStream::run(begin,
631 end,
632 cell_action,
633 copier,
634 sample_scratch_data,
635 sample_copy_data,
636 queue_length,
637 chunk_size);
638 }
639
640 /**
641 * Same as the function above, but for iterator ranges (and, therefore,
642 * filtered iterators).
643 *
644 * An example usage of the function for the serial case is given by
645 * @code
646 *
647 * using ScratchData = MeshWorker::ScratchData<dim, spacedim>;
648 * using CopyData = MeshWorker::CopyData<1, 1, 1>;
649 * using CellIteratorType = decltype(dof_handler.begin_active());
650 *
651 * ScratchData scratch(...);
652 * CopyData copy(...);
653 *
654 * auto cell_worker = [...] (
655 * const CellIteratorType &cell,
656 * ScratchData &scratch_data,
657 * CopyData &copy_data)
658 * {
659 * ...
660 * };
661 *
662 * auto copier = [...](const CopyData &copy_data)
663 * {
664 * ...
665 * };
666 *
667 * MeshWorker::mesh_loop(dof_handler.active_cell_iterators(),
668 * cell_worker, copier,
669 * scratch, copy,
670 * MeshWorker::assemble_own_cells);
671 * @endcode
672 *
673 * and an example usage of the function for the parallel distributed case,
674 * where the copier is only to be called on locally owned cells, is given by
675 * @code
676 *
677 * using ScratchData = MeshWorker::ScratchData<dim, spacedim>;
678 * using CopyData = MeshWorker::CopyData<1, 1, 1>;
679 * using CellIteratorType = decltype(dof_handler.begin_active());
680 *
681 * ScratchData scratch(...);
682 * CopyData copy(...);
683 *
684 * auto cell_worker = [...] (
685 * const CellIteratorType &cell,
686 * ScratchData &scratch_data,
687 * CopyData &copy_data)
688 * {
689 * ...
690 * };
691 *
692 * auto copier = [...](const CopyData &copy_data)
693 * {
694 * ...
695 * };
696 *
697 * const auto filtered_iterator_range =
698 * filter_iterators(dof_handler.active_cell_iterators(),
699 * IteratorFilters::LocallyOwnedCell());
700 *
701 * MeshWorker::mesh_loop(filtered_iterator_range,
702 * cell_worker, copier,
703 * scratch, copy,
704 * MeshWorker::assemble_own_cells);
705 * @endcode
706 *
707 * @ingroup MeshWorker
708 */
709 template <typename CellIteratorType,
710 class ScratchData,
711 class CopyData,
712 typename CellIteratorBaseType =
713 typename internal::CellIteratorBaseType<CellIteratorType>::type>
714 void
715 mesh_loop(
716 IteratorRange<CellIteratorType> iterator_range,
717 const std_cxx20::type_identity_t<std::function<
718 void(const CellIteratorBaseType &, ScratchData &, CopyData &)>>
719 &cell_worker,
720 const std_cxx20::type_identity_t<std::function<void(const CopyData &)>>
721 &copier,
722
723 const ScratchData &sample_scratch_data,
724 const CopyData &sample_copy_data,
725
726 const AssembleFlags flags = assemble_own_cells,
727
728 const std_cxx20::type_identity_t<
729 std::function<void(const CellIteratorBaseType &,
730 const unsigned int,
731 ScratchData &,
732 CopyData &)>> &boundary_worker =
733 std::function<void(const CellIteratorBaseType &,
734 const unsigned int,
735 ScratchData &,
736 CopyData &)>(),
737
738 const std_cxx20::type_identity_t<
739 std::function<void(const CellIteratorBaseType &,
740 const unsigned int,
741 const unsigned int,
742 const CellIteratorBaseType &,
743 const unsigned int,
744 const unsigned int,
745 ScratchData &,
746 CopyData &)>> &face_worker =
747 std::function<void(const CellIteratorBaseType &,
748 const unsigned int,
749 const unsigned int,
750 const CellIteratorBaseType &,
751 const unsigned int,
752 const unsigned int,
753 ScratchData &,
754 CopyData &)>(),
755
756 const unsigned int queue_length = 2 * MultithreadInfo::n_threads(),
757 const unsigned int chunk_size = 8)
758 {
759 // Call the function above
760 mesh_loop<typename IteratorRange<CellIteratorType>::IteratorOverIterators,
761 ScratchData,
762 CopyData,
763 CellIteratorBaseType>(iterator_range.begin(),
764 iterator_range.end(),
765 cell_worker,
766 copier,
767 sample_scratch_data,
768 sample_copy_data,
769 flags,
770 boundary_worker,
771 face_worker,
772 queue_length,
773 chunk_size);
774 }
775
776 /**
777 * This is a variant of the mesh_loop() function that can be used for worker
778 * and copier functions that are member functions of a class.
779 *
780 * The argument passed as @p end must be convertible to the same type as @p
781 * begin, but doesn't have to be of the same type itself. This allows to
782 * write code like <code>mesh_loop(dof_handler.begin_active(),
783 * dof_handler.end(), ...)</code> where the first is of type
784 * DoFHandler::active_cell_iterator whereas the second is of type
785 * DoFHandler::raw_cell_iterator.
786 *
787 * The @p queue_length argument indicates the number of items that can be
788 * live at any given time. Each item consists of @p chunk_size elements of
789 * the input stream that will be worked on by the worker and copier
790 * functions one after the other on the same thread.
791 *
792 * @note If your data objects are large, or their constructors are
793 * expensive, it is helpful to keep in mind that <tt>queue_length</tt>
794 * copies of the <tt>ScratchData</tt> object and
795 * <tt>queue_length*chunk_size</tt> copies of the <tt>CopyData</tt> object
796 * are generated.
797 *
798 * An example usage of the function is given by
799 * @code
800 *
801 * struct ScratchData;
802 * struct CopyData;
803 *
804 * template <int dim, int spacedim>
805 * class MyClass
806 * {
807 * public:
808 * void
809 * cell_worker(const CellIteratorType &cell, ScratchData &, CopyData &);
810 *
811 * void
812 * copier(const CopyData &);
813 *
814 * ...
815 * };
816 *
817 * ...
818 *
819 * MyClass<dim, spacedim> my_class;
820 * ScratchData scratch;
821 * CopyData copy;
822 *
823 * mesh_loop(tria.begin_active(),
824 * tria.end(),
825 * my_class,
826 * &MyClass<dim, spacedim>::cell_worker,
827 * &MyClass<dim, spacedim>::copier,
828 * scratch,
829 * copy,
830 * assemble_own_cells);
831 * @endcode
832 *
833 * @ingroup MeshWorker
834 */
835 template <typename CellIteratorType,
836 class ScratchData,
837 class CopyData,
838 class MainClass>
839 void
840 mesh_loop(const CellIteratorType &begin,
841 const std_cxx20::type_identity_t<CellIteratorType> &end,
842 MainClass &main_class,
843 void (MainClass::*cell_worker)(const CellIteratorType &,
844 ScratchData &,
845 CopyData &),
846 void (MainClass::*copier)(const CopyData &),
847 const ScratchData &sample_scratch_data,
848 const CopyData &sample_copy_data,
849 const AssembleFlags flags = assemble_own_cells,
850 void (MainClass::*boundary_worker)(const CellIteratorType &,
851 const unsigned int,
852 ScratchData &,
853 CopyData &) = nullptr,
854 void (MainClass::*face_worker)(const CellIteratorType &,
855 const unsigned int,
856 const unsigned int,
857 const CellIteratorType &,
858 const unsigned int,
859 const unsigned int,
860 ScratchData &,
861 CopyData &) = nullptr,
862 const unsigned int queue_length = 2 * MultithreadInfo::n_threads(),
863 const unsigned int chunk_size = 8)
864 {
865 std::function<void(const CellIteratorType &, ScratchData &, CopyData &)>
866 f_cell_worker;
867
868 std::function<void(
869 const CellIteratorType &, const unsigned int, ScratchData &, CopyData &)>
870 f_boundary_worker;
871
872 std::function<void(const CellIteratorType &,
873 const unsigned int,
874 const unsigned int,
875 const CellIteratorType &,
876 const unsigned int,
877 const unsigned int,
878 ScratchData &,
879 CopyData &)>
880 f_face_worker;
881
882 if (cell_worker != nullptr)
883 f_cell_worker = [&main_class,
884 cell_worker](const CellIteratorType &cell_iterator,
885 ScratchData &scratch_data,
886 CopyData &copy_data) {
887 (main_class.*cell_worker)(cell_iterator, scratch_data, copy_data);
888 };
889
890 if (boundary_worker != nullptr)
891 f_boundary_worker =
892 [&main_class, boundary_worker](const CellIteratorType &cell_iterator,
893 const unsigned int face_no,
894 ScratchData &scratch_data,
895 CopyData &copy_data) {
896 (main_class.*
897 boundary_worker)(cell_iterator, face_no, scratch_data, copy_data);
898 };
899
900 if (face_worker != nullptr)
901 f_face_worker = [&main_class,
902 face_worker](const CellIteratorType &cell_iterator_1,
903 const unsigned int face_index_1,
904 const unsigned int subface_index_1,
905 const CellIteratorType &cell_iterator_2,
906 const unsigned int face_index_2,
907 const unsigned int subface_index_2,
908 ScratchData &scratch_data,
909 CopyData &copy_data) {
910 (main_class.*face_worker)(cell_iterator_1,
911 face_index_1,
912 subface_index_1,
913 cell_iterator_2,
914 face_index_2,
915 subface_index_2,
916 scratch_data,
917 copy_data);
918 };
919
920 mesh_loop(
921 begin,
922 end,
923 f_cell_worker,
924 [&main_class, copier](const CopyData &copy_data) {
925 (main_class.*copier)(copy_data);
926 },
927 sample_scratch_data,
928 sample_copy_data,
929 flags,
930 f_boundary_worker,
931 f_face_worker,
932 queue_length,
933 chunk_size);
934 }
935
936 /**
937 * Same as the function above, but for iterator ranges (and, therefore,
938 * filtered iterators).
939 *
940 * An example usage of the function for the serial case is given by
941 * @code
942 *
943 * struct ScratchData;
944 * struct CopyData;
945 *
946 * template <int dim, int spacedim>
947 * class MyClass
948 * {
949 * public:
950 * void
951 * cell_worker(const CellIteratorType &cell, ScratchData &, CopyData &);
952 *
953 * void
954 * copier(const CopyData &);
955 *
956 * ...
957 * };
958 *
959 * ...
960 *
961 * MyClass<dim, spacedim> my_class;
962 * ScratchData scratch;
963 * CopyData copy;
964 *
965 * mesh_loop(tria.active_cell_iterators(),
966 * my_class,
967 * &MyClass<dim, spacedim>::cell_worker,
968 * &MyClass<dim, spacedim>::copier,
969 * scratch,
970 * copy,
971 * assemble_own_cells);
972 * @endcode
973 *
974 * and an example usage of the function for the parallel distributed case,
975 * where the copier is only to be called on locally owned cells, is given by
976 * @code
977 *
978 * struct ScratchData;
979 * struct CopyData;
980 *
981 * template <int dim, int spacedim>
982 * class MyClass
983 * {
984 * public:
985 * void
986 * cell_worker(const CellIteratorType &cell, ScratchData &, CopyData &);
987 *
988 * void
989 * copier(const CopyData &);
990 *
991 * ...
992 * };
993 *
994 * ...
995 *
996 * MyClass<dim, spacedim> my_class;
997 * ScratchData scratch;
998 * CopyData copy;
999 *
1000 * const auto filtered_iterator_range =
1001 * filter_iterators(distributed_tria.active_cell_iterators(),
1002 * IteratorFilters::LocallyOwnedCell());
1003 *
1004 * mesh_loop(filtered_iterator_range,
1005 * my_class,
1006 * &MyClass<dim, spacedim>::cell_worker,
1007 * &MyClass<dim, spacedim>::copier,
1008 * scratch,
1009 * copy,
1010 * assemble_own_cells);
1011 * @endcode
1012 *
1013 * @ingroup MeshWorker
1014 */
1015 template <typename CellIteratorType,
1016 class ScratchData,
1017 class CopyData,
1018 class MainClass,
1019 typename CellIteratorBaseType =
1020 typename internal::CellIteratorBaseType<CellIteratorType>::type>
1021 void
1022 mesh_loop(IteratorRange<CellIteratorType> iterator_range,
1023 MainClass &main_class,
1024 void (MainClass::*cell_worker)(const CellIteratorBaseType &,
1025 ScratchData &,
1026 CopyData &),
1027 void (MainClass::*copier)(const CopyData &),
1028 const ScratchData &sample_scratch_data,
1029 const CopyData &sample_copy_data,
1030 const AssembleFlags flags = assemble_own_cells,
1031 void (MainClass::*boundary_worker)(const CellIteratorBaseType &,
1032 const unsigned int,
1033 ScratchData &,
1034 CopyData &) = nullptr,
1035 void (MainClass::*face_worker)(const CellIteratorBaseType &,
1036 const unsigned int,
1037 const unsigned int,
1038 const CellIteratorBaseType &,
1039 const unsigned int,
1040 const unsigned int,
1041 ScratchData &,
1042 CopyData &) = nullptr,
1043 const unsigned int queue_length = 2 * MultithreadInfo::n_threads(),
1044 const unsigned int chunk_size = 8)
1045 {
1046 // Call the function above
1047 mesh_loop<typename IteratorRange<CellIteratorType>::IteratorOverIterators,
1048 ScratchData,
1049 CopyData,
1050 MainClass,
1051 CellIteratorBaseType>(iterator_range.begin(),
1052 iterator_range.end(),
1053 main_class,
1054 cell_worker,
1055 copier,
1056 sample_scratch_data,
1057 sample_copy_data,
1058 flags,
1059 boundary_worker,
1060 face_worker,
1061 queue_length,
1062 chunk_size);
1063 }
1064 } // namespace MeshWorker
1065
1066 DEAL_II_NAMESPACE_CLOSE
1067
1068 #endif