]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
improve documentation
authorkanschat <kanschat@0785d39b-7218-0410-832d-ea1e28bc413d>
Mon, 17 May 2010 15:13:08 +0000 (15:13 +0000)
committerkanschat <kanschat@0785d39b-7218-0410-832d-ea1e28bc413d>
Mon, 17 May 2010 15:13:08 +0000 (15:13 +0000)
git-svn-id: https://svn.dealii.org/trunk@21134 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/deal.II/include/numerics/mesh_worker.h
deal.II/deal.II/include/numerics/mesh_worker_info.h
deal.II/deal.II/include/numerics/mesh_worker_loop.h

index 06a007af4b6acb48bb4190daf6da561070e159d9..dfdaf772b50f98e0c25d9864f7ec9a7a53675b9a 100644 (file)
@@ -50,6 +50,106 @@ template<int,int> class MGDoFHandler;
  * structures. Therefore, base classes for workers assembling into
  * global data are provided in the namespace Assembler.
  *
+ * <h3>Template argument types</h3>
+ *
+ * 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.
+ *
+ * <h4>ITERATOR</h4>
+ *
+ * Any object that has an <tt>operator++()</tt> and points to a
+ * TriaObjectAccessor.
+ *
+ * <h4>DOFINFO</h4>
+ *
+ * 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 <class CellIt>
+ *     void reinit(const CellIt& c);
+ *
+ *     template <class CellIt, class FaceIt>
+ *     void reinit(const CellIt& c, const FaceIt& f, unsigned int n);
+ *
+ *     template <class CellIt, class FaceIt>
+ *     void reinit(const CellIt& c, const FaceIt& f, unsigned int n,
+ *     unsigned int s);
+ *
+ *   friend template class DoFInfoBox<int dim, DOFINFO>;
+ * };
+ * @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.
+ *
+ * <h4>INFOBOX</h4>
+ *
+ * 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 <int dim, class DOFINFO>
+ *     void post_cell(const DoFInfoBox<dim, DOFINFO>&);
+ *     
+ *     template <int dim, class DOFINFO>
+ *     void post_faces(const DoFInfoBox<dim, DOFINFO>&);
+ *
+ *     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.
+ *
+ * <h4>INFO</h4>
+ *
+ * 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
+ *
  * <h3>Simplified interfaces</h3>
  *
  * Since the loop() is fairly general, a specialization
@@ -171,12 +271,6 @@ namespace MeshWorker
                                        */
       typedef IntegrationInfo<dim, dim> CellInfo;
 
-                                      /**
-                                       * The info type expected by a
-                                       * face integrator.
-                                       */
-      typedef IntegrationInfo<dim, dim> FaceInfo;
-
                                       /**
                                        * Initialize default values.
                                        */
index a44c6eae6c2b5f91e6d268bc542181845a885889..6a9c797ae28a3cfaca6cce4a1d5ca538d581e306 100644 (file)
@@ -730,7 +730,7 @@ namespace MeshWorker
 /// The type of the info object for cells
       typedef IntegrationInfo<dim, spacedim> CellInfo;
 
-/// The type of the info objects for faces.
+/// @deprecated The type of the info objects for faces.
       typedef IntegrationInfo<dim, spacedim> 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;
   };
 
 
index 7b47a4e8b821016e1ca78b3f358603be3181cd6d..95aacaecf874727a4be5781c02338613b6d77079 100644 (file)
@@ -83,18 +83,20 @@ namespace MeshWorker
  * than its neighbor. If this parameter is <tt>false</tt> these faces
  * are processed from both cells.
  *
- * @author Guido Kanschat, 2010
+ * @ingroup MeshWorker
+ * @author Guido Kanschat
+ * @date 2010
  */
   template<class INFOBOX, class DOFINFO, int dim, int spacedim, class ITERATOR>
   void cell_action(
     ITERATOR cell,
     DoFInfoBox<dim, DOFINFO>& dof_info,
     INFOBOX& info,
-    const std_cxx1x::function<void (DoFInfo<dim, spacedim>&, typename INFOBOX::CellInfo &)> &cell_worker,
-    const std_cxx1x::function<void (DoFInfo<dim, spacedim>&, typename INFOBOX::FaceInfo &)> &boundary_worker,
-    const std_cxx1x::function<void (DoFInfo<dim, spacedim>&, DoFInfo<dim, spacedim>&,
-                                   typename INFOBOX::FaceInfo &,
-                                   typename INFOBOX::FaceInfo &)> &face_worker,
+    const std_cxx1x::function<void (DOFINFO&, typename INFOBOX::CellInfo&)>& cell_worker,
+    const std_cxx1x::function<void (DOFINFO&, typename INFOBOX::CellInfo&)>& boundary_worker,
+    const std_cxx1x::function<void (DOFINFO&, DOFINFO&,
+                                   typename INFOBOX::CellInfo&,
+                                   typename INFOBOX::CellInfo&)>& 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<ITERATOR>::type end,
            DOFINFO& dinfo,
            INFOBOX& info,
-           const std_cxx1x::function<void (DOFINFO&, typename INFOBOX::CellInfo &)> &cell_worker,
-           const std_cxx1x::function<void (DOFINFO&, typename INFOBOX::FaceInfo &)> &boundary_worker,
+           const std_cxx1x::function<void (DOFINFO&, typename INFOBOX::CellInfo&)> &cell_worker,
+           const std_cxx1x::function<void (DOFINFO&, typename INFOBOX::CellInfo&)> &boundary_worker,
            const std_cxx1x::function<void (DOFINFO&, DOFINFO&,
-                                           typename INFOBOX::FaceInfo &,
-                                           typename INFOBOX::FaceInfo &)> &face_worker,
+                                           typename INFOBOX::CellInfo&,
+                                           typename INFOBOX::CellInfo&)> &face_worker,
            ASSEMBLER &assembler,
            bool cells_first = true)
   {

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.