From 3af7dd3749a6315f55c4e4c28c83675a91ab804b Mon Sep 17 00:00:00 2001 From: bangerth Date: Fri, 12 Oct 2012 13:21:30 +0000 Subject: [PATCH] Write glossary entries for user flags and user data. Link to it. git-svn-id: https://svn.dealii.org/trunk@27080 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/doxygen/headers/glossary.h | 103 ++++++++++++++++++ .../include/deal.II/grid/filtered_iterator.h | 3 +- deal.II/include/deal.II/grid/grid_out.h | 9 +- deal.II/include/deal.II/grid/tria.h | 94 ++++++++-------- deal.II/include/deal.II/grid/tria_accessor.h | 22 ++++ 5 files changed, 180 insertions(+), 51 deletions(-) diff --git a/deal.II/doc/doxygen/headers/glossary.h b/deal.II/doc/doxygen/headers/glossary.h index c3dfe33c77..61e76626e0 100644 --- a/deal.II/doc/doxygen/headers/glossary.h +++ b/deal.II/doc/doxygen/headers/glossary.h @@ -1102,5 +1102,108 @@ Article{JK10, * in the interior of the unit line, square, or cube. * * + * + *
@anchor GlossUserFlags User flags
+ *
+ * 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::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 vector@. 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". + *
+ * + * + *
@anchor GlossUserData User pointers and user indices
+ *
+ * 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::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. + *
+ * * */ diff --git a/deal.II/include/deal.II/grid/filtered_iterator.h b/deal.II/include/deal.II/grid/filtered_iterator.h index 37f1a72969..32297b73c1 100644 --- a/deal.II/include/deal.II/grid/filtered_iterator.h +++ b/deal.II/include/deal.II/grid/filtered_iterator.h @@ -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 */ diff --git a/deal.II/include/deal.II/grid/grid_out.h b/deal.II/include/deal.II/grid/grid_out.h index 4fdc09c942..c79fae7bb0 100644 --- a/deal.II/include/deal.II/grid/grid_out.h +++ b/deal.II/include/deal.II/grid/grid_out.h @@ -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; /** diff --git a/deal.II/include/deal.II/grid/tria.h b/deal.II/include/deal.II/grid/tria.h index 366b45cdbd..98cf4aaf72 100644 --- a/deal.II/include/deal.II/grid/tria.h +++ b/deal.II/include/deal.II/grid/tria.h @@ -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 all 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 vector. 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 - * Triangulation<>::clear_user_flags() 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 * unsigned int or a void *, for * each line, quad, etc. You can access these through * the functions listed under User data 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. - * * *

Boundary approximation

* @@ -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 &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 &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 &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 &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 &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 &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 &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 &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 &v) const; /** * Read the information stored by * save_user_indices(). + * See also @ref GlossUserData . */ void load_user_indices (const std::vector &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 &v) const; /** * Read the information stored by * save_user_pointers(). + * See also @ref GlossUserData . */ void load_user_pointers (const std::vector &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 &v) const; /** * Load the user indices located * on lines. + * See also @ref GlossUserData . */ void load_user_indices_line (const std::vector &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 &v) const; /** * Load the user indices located * on quads. + * See also @ref GlossUserData . */ void load_user_indices_quad (const std::vector &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 &v) const; /** * Load the user indices located * on hexs. + * See also @ref GlossUserData . */ void load_user_indices_hex (const std::vector &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 &v) const; /** * Load the user pointers located * on lines. + * See also @ref GlossUserData . */ void load_user_pointers_line (const std::vector &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 &v) const; /** * Load the user pointers located * on quads. + * See also @ref GlossUserData . */ void load_user_pointers_quad (const std::vector &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 &v) const; /** * Load the user pointers located * on hexs. + * See also @ref GlossUserData . */ void load_user_pointers_hex (const std::vector &v); /*@}*/ diff --git a/deal.II/include/deal.II/grid/tria_accessor.h b/deal.II/include/deal.II/grid/tria_accessor.h index 047481289e..1b18b27dff 100644 --- a/deal.II/include/deal.II/grid/tria_accessor.h +++ b/deal.II/include/deal.II/grid/tria_accessor.h @@ -1129,34 +1129,40 @@ class TriaAccessor : public TriaAccessorBase */ /** * 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 * 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 * Triangulation::clear_user_data() * in between. * A *a=static_cast(cell->user_pointer());. + * + * See @ref GlossUserData for more information. */ void * user_pointer () const; @@ -1236,6 +1247,8 @@ class TriaAccessor : public TriaAccessorBase * 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 * 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 * 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 * 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 * 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 * said for the * recursively_set_user_index() * function. + * + * See @ref GlossUserData for more information. */ void recursively_clear_user_index () const; /** -- 2.39.5