]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Write glossary entries for user flags and user data. Link to it.
authorbangerth <bangerth@0785d39b-7218-0410-832d-ea1e28bc413d>
Fri, 12 Oct 2012 13:21:30 +0000 (13:21 +0000)
committerbangerth <bangerth@0785d39b-7218-0410-832d-ea1e28bc413d>
Fri, 12 Oct 2012 13:21:30 +0000 (13:21 +0000)
git-svn-id: https://svn.dealii.org/trunk@27080 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/doc/doxygen/headers/glossary.h
deal.II/include/deal.II/grid/filtered_iterator.h
deal.II/include/deal.II/grid/grid_out.h
deal.II/include/deal.II/grid/tria.h
deal.II/include/deal.II/grid/tria_accessor.h

index c3dfe33c77bb7639b4f8bad135fffb652b2aa27b..61e76626e007dfda4e3596be380f1c96bfba0a7a 100644 (file)
@@ -1102,5 +1102,108 @@ Article{JK10,
  * in the interior of the unit line, square, or cube.
  * </dd>
  *
+ *
+ * <dt class="glossary">@anchor GlossUserFlags <b>User flags</b></dt>
+ * <dd>
+ *   A triangulation offers one bit per line, quad, etc for user flags.
+ *   This field can be
+ *   accessed as all other data using iterators, using the syntax
+ *   @code
+ *      cell->set_user_flag();                // set the user flag of a cell
+ *      if (cell->user_flag_set() == false)   // if cell hasn't been flagged yet
+ *        {
+ *           cell->face(0)->set_user_flag();  // flag its first face
+ *        }
+ *   @endcode
+ *   Typically, this user flag is
+ *   used if an algorithm walks over all cells and needs information whether
+ *   another cell, e.g. a neighbor, has already been processed. Similarly,
+ *   it can be used to flag faces, quads or lines at the boundary for which
+ *   some operation has already been performed. The latter is often useful
+ *   since a loop such as
+ *   @code
+ *      // in 3d
+ *      for (cell=dof_handler.begin_active();
+ *           cell!=dof_handler.end(); ++cell)
+ *        for (unsigned int line=0; line<GeometryInfo<dim>::lines_per_cell; ++l)
+ *          if (cell->line(l)->at_boundary())
+ *            {
+ *               do something with this line
+ *            }
+ *   @endcode
+ *   encounters some boundary lines more than once. Consequently, one would
+ *   set the user flag of the line in the body of the loop, and only enter the
+ *   body if the user flag had not previously been set. There are a number of
+ *   additional functions that can be accessed through the iterator interface;
+ *   see the TriaAccessor class for more information. Note that there are no
+ *   user flags that can be associated with vertices; however, since vertices
+ *   are numbered consecutively, this can easily be emulated in user code
+ *   using a vector of bools.
+ *
+ *   There are two functions, Triangulation::save_user_flags and
+ *   Triangulation::load_user_flags which
+ *   write and read these flags to and from a stream or a vector of bools. Unlike
+ *   Triangulation::save_refine_flags and Triangulation::load_refine_flags,
+ *   these two functions store
+ *   and read the flags of all used lines, quads, etc, i.e., not only of the
+ *   active ones.
+ *
+ *   If you want to store more specific user flags, you can use the functions
+ *   Triangulation::save_user_flags_line and Triangulation::load_user_flags_line
+ *   and the similarly for quads, etc.
+ *
+ *   As for the refinement and coarsening flags, there exist two versions of these
+ *   functions, one which reads/writes from a stream and one which does so from
+ *   a <tt>vector@<bool@></tt>. The latter is used to store flags temporarily, while the
+ *   first is used to store them in a file.
+ *
+ *   It is good practice to clear the user flags using the
+ *   Triangulation::clear_user_flags() function before usage, since it is
+ *   often necessary to use the flags in more than one function. If the flags may
+ *   be in use at the time a function that needs them is called, then this function
+ *   should save and restore the flags as described above.
+ *
+ *   @note If more information than just a single boolean flag needs to be stored
+ *   with a cell, line, or face, then see about @ref GlossUserData "user data".
+ * </dd>
+ *
+ *
+ * <dt class="glossary">@anchor GlossUserData <b>User pointers and user indices</b></dt>
+ * <dd>
+ *   Just like the @ref GlossUserFlags "user flags", the Triangulation class offers a
+ *   field for each line, quad and hex in which to store more descriptive data than just
+ *   a single boolean flag. This is called "user data" and the data that can be stored
+ *   in it is either a single unsigned integer or a void pointer. Both are typically
+ *   used to index into a bigger array that contains more detailed data an application
+ *   wants to attach to a mesh entity.
+ *
+ *   User data is stored and retrieved in the following manner:
+ *   @code
+ *      for (cell=dof_handler.begin_active();
+ *           cell!=dof_handler.end(); ++cell)
+ *        for (unsigned int line=0; line<GeometryInfo<dim>::lines_per_cell; ++l)
+ *          if (cell->line(l)->at_boundary())
+ *            {
+ *              cell->line(l)->set_user_index(42);
+ *            }
+ *   @endcode
+ *   Similarly, there are functions TriaAccessor::set_user_pointer to set a pointer, and
+ *   TriaAccessor::user_index and TriaAccessor::user_pointer to retrieve the index
+ *   and pointer. To clear all user indices or pointers, use Triangulation::clear_user_data().
+ *   As with flags, there are functions that allow to save and restore user data,
+ *   either for all entities of the mesh hierarchy or for lines, quads or hexes
+ *   separately. There are a number of additional functions that can be accessed
+ *   through the iterator interface; see the TriaAccessor class for more information.
+ *
+ *   @note User pointers and user indices are stored in the same
+ *   place. In order to avoid unwanted conversions, Triangulation
+ *   checks which one of them is in use and does not allow access to
+ *   the other one, until Triangulation::clear_user_data() has been called.
+ *
+ *   @note The usual warning about the missing type safety of @p void pointers are
+ *   obviously in place here; responsibility for correctness of types etc
+ *   lies entirely with the user of the pointer.
+ * </dd>
+ *
  * </dl>
  */
index 37f1a729693904f5471c7f740c4b31b0a5c26224..32297b73c1a858074a8c26294e58adf01fcd00d7 100644 (file)
@@ -64,7 +64,8 @@ namespace IteratorFilters
                                     * either the iterator points to an
                                     * object for which the user flag
                                     * is set or an iterator past the
-                                    * end.
+                                    * end. See @ref GlossUserFlags
+                                   * for information about user flags.
                                     *
                                     * @ingroup Iterators
                                     */
index 4fdc09c9429942b0227cf12a08b2178214e4588b..c79fae7bb0238a11c43b66c39ca8f48dacdd29f7 100644 (file)
@@ -373,10 +373,11 @@ namespace GridOutFlags
       double line_width;
 
                                        /**
-                                        * Should lines with a set
-                                        * @p user_flag be drawn in a
-                                        * different color (red)?
-                                        */
+                                        * Should lines with a set @p user_flag
+                                        * be drawn in a different color (red)?
+                                        * See @ref GlossUserFlags for
+                                        * information about user flags.
+                                       */
       bool color_lines_on_user_flag;
 
                                        /**
index 366b45cdbd00d80a0ec85a3afdde605c888161d8..98cf4aaf72784b22fa0e090e563bf1686b47462f 100644 (file)
@@ -860,52 +860,20 @@ namespace internal
  *   This field can be
  *   accessed as all other data using iterators. Normally, this user flag is
  *   used if an algorithm walks over all cells and needs information whether
- *   another cell, e.g. a neighbor, has already been processed. It can also
- *   be used to flag the lines subject to constraints in 2D, as for example the
- *   functions in the DoFHandler classes do.
- *
- *   There are two functions, @p save_user_flags and @p load_user_flags which
- *   write and read these flags to and from a stream. Unlike
- *   @p save_refine_flags and @p load_refine_flags, these two functions store
- *   and read the flags of all used lines, quads, etc, not only of the
- *   active ones (well, activity is a concept which really only applies to
- *   cells, not for example to lines in 2D, so the abovementioned generalization
- *   to <em>all</em> lines, quads, etc seems plausible).
- *
- *   If you want to store more specific user flags, you can use the functions
- *   @p save_user_flags_line and @p load_user_flags_line and the generalizations
- *   for quads, etc.
- *
- *   As for the refinement and coarsening flags, there exist two versions of these
- *   functions, one which reads/writes from a stream and one which does so from
- *   a <tt>vector<bool></tt>. The latter is used to store flags temporarily, while the
- *   first is used to store them in a file.
- *
- *   It is convention to clear the user flags using the
- *   <tt>Triangulation<>::clear_user_flags()</tt> function before usage, since it is
- *   often necessary to use the flags in more than one function consecutively and
- *   is then error prone to dedicate one of these to clear the flags.
- *
- *   It is recommended that a functions using the flags states so in
- *   its documentation. For example, the
- *   execute_coarsening_and_refinement() function uses some of the user
- *   flags and will therefore destroy any content stored in them.
+ *   another cell, e.g. a neighbor, has already been processed.
+ *   See @ref GlossUserFlags "the glossary for more information".
  *
  *   There is another set of user data, which can be either an
  *   <tt>unsigned int</tt> or a <tt>void *</tt>, for
  *   each line, quad, etc. You can access these through
  *   the functions listed under <tt>User data</tt> in
- *   the accessor classes. These pointers are not used nor changed in
- *   many places of the library, and those classes and functions that
- *   do use them should document this clearly; the most prominent user
- *   of these pointers is the SolutionTransfer class which uses the
- *   cell->user_pointers.
+ *   the accessor classes.
+ *   Again, see @ref GlossUserData "the glossary for more information".
  *
  *   The value of these user indices or pointers is @p NULL by default. Note that
  *   the pointers are not inherited to children upon
  *   refinement. Still, after a remeshing they are available on all
- *   cells, where they were set on the previous mesh (unless, of
- *   course, overwritten by the SolutionTransfer class).
+ *   cells, where they were set on the previous mesh.
  *
  *   The usual warning about the missing type safety of @p void pointers are
  *   obviously in place here; responsibility for correctness of types etc
@@ -916,10 +884,6 @@ namespace internal
  *   checks which one of them is in use and does not allow access to
  *   the other one, until clear_user_data() has been called.
  *
- *   Just like the user flags, this field is not available for vertices,
- *   which does no harm since the vertices have a unique and continuous number
- *   unlike the structured objects lines and quads.
- *
  *
  *   <h3>Boundary approximation</h3>
  *
@@ -2362,6 +2326,7 @@ class Triangulation : public Subscriptor
                                      /*@{*/
                                      /**
                                       *  Clear all user flags.
+                                     *  See also @ref GlossUserFlags .
                                       */
     void clear_user_flags ();
 
@@ -2371,36 +2336,42 @@ class Triangulation : public Subscriptor
                                       *  and the documentation for the
                                       *  @p save_refine_flags for more
                                       *  details.
+                                     *  See also @ref GlossUserFlags .
                                       */
     void save_user_flags (std::ostream &out) const;
 
                                      /**
-                                      * Same as above, but store the flags to
-                                      * a bitvector rather than to a file.
-                                      * The output vector is resized if
-                                      * necessary.
+                                      *  Same as above, but store the flags to
+                                      *  a bitvector rather than to a file.
+                                      *  The output vector is resized if
+                                      *  necessary.
+                                     *  See also @ref GlossUserFlags .
                                       */
     void save_user_flags (std::vector<bool> &v) const;
 
                                      /**
                                       *  Read the information stored by
                                       *  @p save_user_flags.
+                                     *  See also @ref GlossUserFlags .
                                       */
     void load_user_flags (std::istream &in);
 
                                      /**
                                       *  Read the information stored by
                                       *  @p save_user_flags.
+                                     *  See also @ref GlossUserFlags .
                                       */
     void load_user_flags (const std::vector<bool> &v);
 
                                      /**
                                       *  Clear all user flags on lines.
+                                     *  See also @ref GlossUserFlags .
                                       */
     void clear_user_flags_line ();
 
                                      /**
                                       * Save the user flags on lines.
+                                     * See also @ref GlossUserFlags .
                                       */
     void save_user_flags_line (std::ostream &out) const;
 
@@ -2409,26 +2380,31 @@ class Triangulation : public Subscriptor
                                       * a bitvector rather than to a file.
                                       * The output vector is resized if
                                       * necessary.
+                                     * See also @ref GlossUserFlags .
                                       */
     void save_user_flags_line (std::vector<bool> &v) const;
 
                                      /**
                                       * Load the user flags located on lines.
+                                     * See also @ref GlossUserFlags .
                                       */
     void load_user_flags_line (std::istream &in);
 
                                      /**
                                       * Load the user flags located on lines.
+                                     * See also @ref GlossUserFlags .
                                       */
     void load_user_flags_line (const std::vector<bool> &v);
 
                                      /**
                                       *  Clear all user flags on quads.
+                                     * See also @ref GlossUserFlags .
                                       */
     void clear_user_flags_quad ();
 
                                      /**
                                       * Save the user flags on quads.
+                                     * See also @ref GlossUserFlags .
                                       */
     void save_user_flags_quad (std::ostream &out) const;
 
@@ -2437,27 +2413,32 @@ class Triangulation : public Subscriptor
                                       * a bitvector rather than to a file.
                                       * The output vector is resized if
                                       * necessary.
+                                     * See also @ref GlossUserFlags .
                                       */
     void save_user_flags_quad (std::vector<bool> &v) const;
 
                                      /**
                                       * Load the user flags located on quads.
+                                     * See also @ref GlossUserFlags .
                                       */
     void load_user_flags_quad (std::istream &in);
 
                                      /**
                                       * Load the user flags located on quads.
+                                     * See also @ref GlossUserFlags .
                                       */
     void load_user_flags_quad (const std::vector<bool> &v);
 
 
                                      /**
-                                      *  Clear all user flags on quads.
+                                      * Clear all user flags on quads.
+                                     * See also @ref GlossUserFlags .
                                       */
     void clear_user_flags_hex ();
 
                                      /**
                                       * Save the user flags on hexs.
+                                     * See also @ref GlossUserFlags .
                                       */
     void save_user_flags_hex (std::ostream &out) const;
 
@@ -2466,16 +2447,19 @@ class Triangulation : public Subscriptor
                                       * a bitvector rather than to a file.
                                       * The output vector is resized if
                                       * necessary.
+                                     * See also @ref GlossUserFlags .
                                       */
     void save_user_flags_hex (std::vector<bool> &v) const;
 
                                      /**
                                       * Load the user flags located on hexs.
+                                     * See also @ref GlossUserFlags .
                                       */
     void load_user_flags_hex (std::istream &in);
 
                                      /**
                                       * Load the user flags located on hexs.
+                                     * See also @ref GlossUserFlags .
                                       */
     void load_user_flags_hex (const std::vector<bool> &v);
 
@@ -2483,6 +2467,7 @@ class Triangulation : public Subscriptor
                                       * Clear all user pointers and
                                       * indices and allow the use of
                                       * both for next access.
+                                     * See also @ref GlossUserData .
                                       */
     void clear_user_data ();
 
@@ -2491,6 +2476,7 @@ class Triangulation : public Subscriptor
                                       * clear_user_data() instead.
                                       *
                                       *  Clear all user pointers.
+                                     *  See also @ref GlossUserData .
                                       */
     void clear_user_pointers ();
 
@@ -2498,12 +2484,14 @@ class Triangulation : public Subscriptor
                                       * Save all user indices. The
                                       * output vector is resized if
                                       * necessary.
+                                     * See also @ref GlossUserData .
                                       */
     void save_user_indices (std::vector<unsigned int> &v) const;
 
                                      /**
                                       * Read the information stored by
                                       * save_user_indices().
+                                     * See also @ref GlossUserData .
                                       */
     void load_user_indices (const std::vector<unsigned int> &v);
 
@@ -2511,12 +2499,14 @@ class Triangulation : public Subscriptor
                                       * Save all user pointers. The
                                       * output vector is resized if
                                       * necessary.
+                                     * See also @ref GlossUserData .
                                       */
     void save_user_pointers (std::vector<void *> &v) const;
 
                                      /**
                                       * Read the information stored by
                                       * save_user_pointers().
+                                     * See also @ref GlossUserData .
                                       */
     void load_user_pointers (const std::vector<void *> &v);
 
@@ -2524,12 +2514,14 @@ class Triangulation : public Subscriptor
                                       * Save the user indices on
                                       * lines. The output vector is
                                       * resized if necessary.
+                                     * See also @ref GlossUserData .
                                       */
     void save_user_indices_line (std::vector<unsigned int> &v) const;
 
                                      /**
                                       * Load the user indices located
                                       * on lines.
+                                     * See also @ref GlossUserData .
                                       */
     void load_user_indices_line (const std::vector<unsigned int> &v);
 
@@ -2537,12 +2529,14 @@ class Triangulation : public Subscriptor
                                       * Save the user indices on
                                       * quads. The output vector is
                                       * resized if necessary.
+                                     * See also @ref GlossUserData .
                                       */
     void save_user_indices_quad (std::vector<unsigned int> &v) const;
 
                                      /**
                                       * Load the user indices located
                                       * on quads.
+                                     * See also @ref GlossUserData .
                                       */
     void load_user_indices_quad (const std::vector<unsigned int> &v);
 
@@ -2550,24 +2544,28 @@ class Triangulation : public Subscriptor
                                       * Save the user indices on
                                       * hexes. The output vector is
                                       * resized if necessary.
+                                     * See also @ref GlossUserData .
                                       */
     void save_user_indices_hex (std::vector<unsigned int> &v) const;
 
                                      /**
                                       * Load the user indices located
                                       * on hexs.
+                                     * See also @ref GlossUserData .
                                       */
     void load_user_indices_hex (const std::vector<unsigned int> &v);
                                      /**
                                       * Save the user indices on
                                       * lines. The output vector is
                                       * resized if necessary.
+                                     * See also @ref GlossUserData .
                                       */
     void save_user_pointers_line (std::vector<void *> &v) const;
 
                                      /**
                                       * Load the user pointers located
                                       * on lines.
+                                     * See also @ref GlossUserData .
                                       */
     void load_user_pointers_line (const std::vector<void *> &v);
 
@@ -2575,12 +2573,14 @@ class Triangulation : public Subscriptor
                                       * Save the user pointers on
                                       * quads. The output vector is
                                       * resized if necessary.
+                                     * See also @ref GlossUserData .
                                       */
     void save_user_pointers_quad (std::vector<void *> &v) const;
 
                                      /**
                                       * Load the user pointers located
                                       * on quads.
+                                     * See also @ref GlossUserData .
                                       */
     void load_user_pointers_quad (const std::vector<void *> &v);
 
@@ -2588,12 +2588,14 @@ class Triangulation : public Subscriptor
                                       * Save the user pointers on
                                       * hexes. The output vector is
                                       * resized if necessary.
+                                     * See also @ref GlossUserData .
                                       */
     void save_user_pointers_hex (std::vector<void *> &v) const;
 
                                      /**
                                       * Load the user pointers located
                                       * on hexs.
+                                     * See also @ref GlossUserData .
                                       */
     void load_user_pointers_hex (const std::vector<void *> &v);
                                      /*@}*/
index 047481289e7de99c90b5560fc7ba27a443672d49..1b18b27dff55f72f6d2092d82b79ecafa02fe6a6 100644 (file)
@@ -1129,34 +1129,40 @@ class TriaAccessor : public TriaAccessorBase<structdim, dim, spacedim>
                                       */
                                      /**
                                       *  Read the user flag.
+                                     *  See @ref GlossUserFlags for more information.
                                       */
     bool user_flag_set () const;
 
                                      /**
                                       *  Set the user flag.
+                                     *  See @ref GlossUserFlags for more information.
                                       */
     void set_user_flag () const;
 
                                      /**
                                       *  Clear the user flag.
+                                     *  See @ref GlossUserFlags for more information.
                                       */
     void clear_user_flag () const;
 
                                      /**
                                       *  Set the user flag for this
                                       * and all descendants.
+                                     *  See @ref GlossUserFlags for more information.
                                       */
     void recursively_set_user_flag () const;
 
                                      /**
                                       *  Clear the user flag for this
                                       * and all descendants.
+                                     *  See @ref GlossUserFlags for more information.
                                       */
     void recursively_clear_user_flag () const;
 
                                      /**
                                       * Reset the user data to zero,
                                       * independent if pointer or index.
+                                     * See @ref GlossUserData for more information.
                                       */
     void clear_user_data () const;
 
@@ -1171,12 +1177,15 @@ class TriaAccessor : public TriaAccessorBase<structdim, dim, spacedim>
                                       * you call
                                       * Triangulation::clear_user_data()
                                       * in between.
+                                     *
+                                     * See @ref GlossUserData for more information.
                                       */
     void set_user_pointer (void *p) const;
 
                                      /**
                                       * Reset the user pointer
                                       * to a @p NULL pointer.
+                                     * See @ref GlossUserData for more information.
                                       */
     void clear_user_pointer () const;
 
@@ -1199,6 +1208,8 @@ class TriaAccessor : public TriaAccessorBase<structdim, dim, spacedim>
                                       * Triangulation::clear_user_data()
                                       * in between.
                                       * <tt>A *a=static_cast<A*>(cell->user_pointer());</tt>.
+                                     *
+                                     * See @ref GlossUserData for more information.
                                       */
     void * user_pointer () const;
 
@@ -1236,6 +1247,8 @@ class TriaAccessor : public TriaAccessorBase<structdim, dim, spacedim>
                                       * you call
                                       * Triangulation::clear_user_data()
                                       * in between.
+                                     *
+                                     * See @ref GlossUserData for more information.
                                       */
     void recursively_set_user_pointer (void *p) const;
 
@@ -1246,6 +1259,7 @@ class TriaAccessor : public TriaAccessorBase<structdim, dim, spacedim>
                                       * said for the
                                       * recursively_set_user_pointer()
                                       * function.
+                                     * See @ref GlossUserData for more information.
                                       */
     void recursively_clear_user_pointer () const;
 
@@ -1260,11 +1274,13 @@ class TriaAccessor : public TriaAccessorBase<structdim, dim, spacedim>
                                       * you call
                                       * Triangulation::clear_user_data()
                                       * in between.
+                                     * See @ref GlossUserData for more information.
                                       */
     void set_user_index (const unsigned int p) const;
 
                                      /**
                                       * Reset the user index to 0.
+                                     * See @ref GlossUserData for more information.
                                       */
     void clear_user_index () const;
 
@@ -1279,6 +1295,8 @@ class TriaAccessor : public TriaAccessorBase<structdim, dim, spacedim>
                                       * you call
                                       * Triangulation::clear_user_data()
                                       * in between.
+                                     *
+                                     * See @ref GlossUserData for more information.
                                       */
     unsigned int user_index () const;
 
@@ -1307,6 +1325,8 @@ class TriaAccessor : public TriaAccessorBase<structdim, dim, spacedim>
                                       * you call
                                       * Triangulation::clear_user_data()
                                       * in between.
+                                     *
+                                     * See @ref GlossUserData for more information.
                                       */
     void recursively_set_user_index (const unsigned int p) const;
 
@@ -1317,6 +1337,8 @@ class TriaAccessor : public TriaAccessorBase<structdim, dim, spacedim>
                                       * said for the
                                       * recursively_set_user_index()
                                       * function.
+                                     *
+                                     * See @ref GlossUserData for more information.
                                       */
     void recursively_clear_user_index () const;
                                      /**

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.