From 99bb88ac0f3f4b98bc41da083aaa20a7c0fc4cc0 Mon Sep 17 00:00:00 2001 From: kanschat Date: Mon, 17 May 2010 15:13:08 +0000 Subject: [PATCH] improve documentation git-svn-id: https://svn.dealii.org/trunk@21134 0785d39b-7218-0410-832d-ea1e28bc413d --- .../deal.II/include/numerics/mesh_worker.h | 106 +++++++++++++++++- .../include/numerics/mesh_worker_info.h | 10 +- .../include/numerics/mesh_worker_loop.h | 29 ++--- 3 files changed, 120 insertions(+), 25 deletions(-) diff --git a/deal.II/deal.II/include/numerics/mesh_worker.h b/deal.II/deal.II/include/numerics/mesh_worker.h index 06a007af4b..dfdaf772b5 100644 --- a/deal.II/deal.II/include/numerics/mesh_worker.h +++ b/deal.II/deal.II/include/numerics/mesh_worker.h @@ -50,6 +50,106 @@ template class MGDoFHandler; * structures. Therefore, base classes for workers assembling into * global data are provided in the namespace Assembler. * + *

Template argument types

+ * + * The functions loop() and cell_action() take some arguments which + * are template parameters. Let us list the minimum requirements for + * these classes here and describe their properties. + * + *

ITERATOR

+ * + * Any object that has an operator++() and points to a + * TriaObjectAccessor. + * + *

DOFINFO

+ * + * For an example implementation, refer to the class template DoFInfo. + * In order to work with cell_action() and loop(), DOFINFO needs to + * follow the following interface. + * @code + * class DOFINFO + * { + * private: + * DOFINFO(); + * DOFINFO(const DOFINFO&); + * DOFINFO& operator=(const DOFINFO&); + * + * public: + * template + * void reinit(const CellIt& c); + * + * template + * void reinit(const CellIt& c, const FaceIt& f, unsigned int n); + * + * template + * void reinit(const CellIt& c, const FaceIt& f, unsigned int n, + * unsigned int s); + * + * friend template class DoFInfoBox; + * }; + * @endcode + * + * The three private functions are called by DoFInfoBox and should not + * be needed elsewhere. Obviously, they can be made public and then + * the friend declaration at the end may be missing. + * + * Additionally, you will need at least one public constructor. Furthermore + * DOFINFO is pretty useless yet: functions to interface with + * INTEGRATIONINFO and ASSEMBLER are needed. + * + * DOFINFO objects are gathered in a DoFInfoBox. In those objects, we + * store the results of local operations on each cel and its + * faces. Once all this information has been gathered, an ASSEMBLER is + * used to assemble it into golbal data. + * + *

INFOBOX

+ * + * This type is exemplified in IntegrationInfoBox. It collects the + * input data for actions on cells and faces in INFO objects (see + * below). It provides the following interface to loop() and + * cell_action(): + * + * @code + * class INFOBOX + * { + * public: + * template + * void post_cell(const DoFInfoBox&); + * + * template + * void post_faces(const DoFInfoBox&); + * + * INFO cell; + * INFO boundary; + * INFO face; + * INFO subface; + * INFO neighbor; + * }; + * @endcode + * + * The main purpose of this class is gathering the five INFO objects, + * which contain the temporary data used on each cell or face. The + * requirements on these objects are listed below. Here, we only note + * that there need to be these 5 objects with the names listed above. + * + * The two function templates are call back functions called in + * cell_action(). The first is called before the faces are worked on, + * the second after the faces. + * + *

INFO

+ * + * See IntegrationInfo for an example of these objects. They contain + * the temporary data needed on each cell or face to compute the + * result. The MeshWorker only uses the interface + * + * @code + * class INFO + * { + * public: + * void reinit(const DOFINFO& i); + * }; + * @endcode + * *

Simplified interfaces

* * Since the loop() is fairly general, a specialization @@ -171,12 +271,6 @@ namespace MeshWorker */ typedef IntegrationInfo CellInfo; - /** - * The info type expected by a - * face integrator. - */ - typedef IntegrationInfo FaceInfo; - /** * Initialize default values. */ diff --git a/deal.II/deal.II/include/numerics/mesh_worker_info.h b/deal.II/deal.II/include/numerics/mesh_worker_info.h index a44c6eae6c..6a9c797ae2 100644 --- a/deal.II/deal.II/include/numerics/mesh_worker_info.h +++ b/deal.II/deal.II/include/numerics/mesh_worker_info.h @@ -730,7 +730,7 @@ namespace MeshWorker /// The type of the info object for cells typedef IntegrationInfo CellInfo; -/// The type of the info objects for faces. +/// @deprecated The type of the info objects for faces. typedef IntegrationInfo FaceInfo; /** @@ -828,13 +828,13 @@ namespace MeshWorker /// The info object for a cell CellInfo cell; /// The info object for a boundary face - FaceInfo boundary; + CellInfo boundary; /// The info object for a regular interior face, seen from the first cell - FaceInfo face; + CellInfo face; /// The info object for the refined side of an interior face seen from the first cell - FaceInfo subface; + CellInfo subface; /// The info object for an interior face, seen from the other cell - FaceInfo neighbor; + CellInfo neighbor; }; diff --git a/deal.II/deal.II/include/numerics/mesh_worker_loop.h b/deal.II/deal.II/include/numerics/mesh_worker_loop.h index 7b47a4e8b8..95aacaecf8 100644 --- a/deal.II/deal.II/include/numerics/mesh_worker_loop.h +++ b/deal.II/deal.II/include/numerics/mesh_worker_loop.h @@ -83,18 +83,20 @@ namespace MeshWorker * than its neighbor. If this parameter is false these faces * are processed from both cells. * - * @author Guido Kanschat, 2010 + * @ingroup MeshWorker + * @author Guido Kanschat + * @date 2010 */ template void cell_action( ITERATOR cell, DoFInfoBox& dof_info, INFOBOX& info, - const std_cxx1x::function&, typename INFOBOX::CellInfo &)> &cell_worker, - const std_cxx1x::function&, typename INFOBOX::FaceInfo &)> &boundary_worker, - const std_cxx1x::function&, DoFInfo&, - typename INFOBOX::FaceInfo &, - typename INFOBOX::FaceInfo &)> &face_worker, + const std_cxx1x::function& cell_worker, + const std_cxx1x::function& boundary_worker, + const std_cxx1x::function& face_worker, const bool cells_first, const bool unique_faces_only) { @@ -226,12 +228,11 @@ namespace MeshWorker * cells in an iterator range, in which cell_action() is called for * each cell. Unilaterally refined interior faces are handled * automatically by the loop. - * - * Most of the work in this loop is done in cell_action(), whic halso - * reeived most of the parameters of this function. See the + * Most of the work in this loop is done in cell_action(), which also + * receives most of the parameters of this function. See the * documentation there for mor details. * - * If you don't want integration on cells, interior or boundary faces + * If you don't want anything to be done on cells, interior or boundary faces * to happen, simply pass the Null pointer to one of the function * arguments. * @@ -243,11 +244,11 @@ namespace MeshWorker typename identity::type end, DOFINFO& dinfo, INFOBOX& info, - const std_cxx1x::function &cell_worker, - const std_cxx1x::function &boundary_worker, + const std_cxx1x::function &cell_worker, + const std_cxx1x::function &boundary_worker, const std_cxx1x::function &face_worker, + typename INFOBOX::CellInfo&, + typename INFOBOX::CellInfo&)> &face_worker, ASSEMBLER &assembler, bool cells_first = true) { -- 2.39.5