From: Jean-Paul Pelteret Date: Thu, 30 Apr 2020 21:58:57 +0000 (+0200) Subject: Augment documentation of mesh_loop() X-Git-Tag: v9.2.0-rc1~123^2~3 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5143c8a1c3508b3772d729839c59038c1a41bdcf;p=dealii.git Augment documentation of mesh_loop() --- diff --git a/include/deal.II/meshworker/mesh_loop.h b/include/deal.II/meshworker/mesh_loop.h index 58f4d1e2f3..d3de968ed1 100644 --- a/include/deal.II/meshworker/mesh_loop.h +++ b/include/deal.II/meshworker/mesh_loop.h @@ -162,7 +162,55 @@ namespace MeshWorker * `copier` on one cell and the `cell_worker`/`face_worker`/`boundary_worker` * functions on the next cell, and user code needs not reset the copy * object either at the beginning of the cell integration or end of the - * copy operation. + * copy operation. Resetting the state of the `copier ` inside of a + * `face_worker` or `boundary_worker` constitutes a bug, and may lead to + * some unexpected results. The following example shows what is not + * permissible, as the copier is potentially shared among numerous faces + * on a cell: + * @code + * + * using ScratchData = MeshWorker::ScratchData; + * using CopyData = MeshWorker::CopyData<1, 1, 1>; + * using CellIteratorType = decltype(dof_handler.begin_active()); + * + * ScratchData scratch(...); + * CopyData copy(...); + * + * std::function + * empty_cell_worker; + * + * auto boundary_worker = [...] ( + * const CellIteratorType &cell, + * const unsigned int face, + * ScratchData &scratch_data, + * CopyData ©_data) + * { + * const auto &fe_face_values = scratch_data.reinit(cell, face); + * copy_data = CopyData(...); // This is an error, as we lose the + * // accumulation that has been performed on + * // other boundary faces of the same cell. + * + * for (unsigned int q_point = 0; + * q_point < fe_face_values.n_quadrature_points; + * ++q_point) + * { + * copy_data.vectors[0][0] += 1.0 * fe_face_values.JxW(q_point); + * } + * }; + * + * double value = 0; + * auto copier = [...](const CopyData ©_data) + * { + * value += copy_data.vectors[0][0]; // Contributions from some faces may + * // be missing. + * }; + * + * MeshWorker::mesh_loop(dof_handler.active_cell_iterators(), + * empty_cell_worker, copier, + * scratch, copy, + * MeshWorker::assemble_boundary_faces, + * boundary_worker); + * @endcode * * The queue_length argument indicates the number of items that can be live at * any given time. Each item consists of chunk_size elements of the input