From: Wolfgang Bangerth Date: Tue, 30 Aug 2022 03:21:40 +0000 (-0600) Subject: Doc update in GridTools. X-Git-Tag: v9.5.0-rc1~1000^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=156d2cfe2cdcb45388a592795ae3b36ebab7a543;p=dealii.git Doc update in GridTools. --- diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h index c754900a93..b04f3265c3 100644 --- a/include/deal.II/grid/grid_tools.h +++ b/include/deal.II/grid/grid_tools.h @@ -1896,7 +1896,13 @@ namespace GridTools * the given predicate is true, are completely enclosed in at least one of the * bounding boxes. Notice the cover is only guaranteed to contain all these * active cells but it's not necessarily exact i.e. it can include a bigger - * area than their union. + * area than their union. (This is of course unavoidable in any case if cells + * are not rectangular or brick-shaped, but it is also true if cells are + * since it is inefficient to create as many bounding boxes as there are + * cells; rather, the algorithm here tries to combine the bounding boxes + * of multiple cells into a cheaper representation, at the cost of a set + * of bounding boxes that may be larger than the union of the cells -- see + * the description of the relevant function arguments below.) * * For each cell at a given refinement level containing active cells for which @p predicate is true, * the function creates a bounding box of its children for which @p predicate is true. @@ -1905,30 +1911,42 @@ namespace GridTools * @p allow_merge and @p max_boxes are used to reduce the number of cells at a computational cost and * covering a bigger n-dimensional volume. * - * The parameters to control the algorithm are: - * - @p predicate : the property of the cells to enclose e.g. IteratorFilters::LocallyOwnedCell . - * The predicate is tested only on active cells. - * - @p refinement_level : it defines the level at which the initial bounding box are created. The refinement - * should be set to a coarse refinement level. A bounding box is created for - * each active cell at coarser - * level than @p refinement_level; if @p refinement_level is higher than the number of levels of the + * @param[in] mesh The mesh object this function is to work on. This + * is generally either a triangulation of some kind, or a DoFHandler + * object. + * @param[in] predicate A function-like object that returns true or + * false depending on whether the property of the cells to enclose + * is satisfied. An example is IteratorFilters::LocallyOwnedCell, + * but it can also be a lambda function or anything else that can be + * called with a cell as argument. + * This predicate is tested only on active cells. + * @param[in] refinement_level Defines the level at which the + * initial bounding boxes are created. The refinement should be set + * to a coarse refinement level. A bounding box is created for each + * active cell at a coarser level than @p refinement_level; if @p + * refinement_level is higher than the number of levels of the * triangulation an exception is thrown. - * - @p allow_merge : This flag allows for box merging and, by default, is false. The algorithm has a cost of - * O(N^2) where N is the number of the bounding boxes created from the - * refinement level; for this reason, if - * the flag is set to true, make sure to choose wisely a coarse enough @p refinement_level. - * - @p max_boxes : the maximum number of bounding boxes to compute. If more are created the smaller ones are - * merged with neighbors. By default after merging the boxes which can be - * expressed as a single one no more boxes are merged. See the - * BoundingBox::get_neighbor_type () function for details. - * Notice only neighboring cells are merged (see the @p get_neighbor_type function in bounding box class): if - * the target number of bounding boxes max_boxes can't be reached by merging - * neighbors an exception is thrown - * - * The following image describes an example of the algorithm with @p refinement_level = 2, @p allow_merge = true - * and @p max_boxes = 1. The cells with the property predicate are in red, the area of a bounding box is - * slightly orange. + * @param[in] allow_merge This flag allows for box merging and, by + * default, is false. The algorithm has a cost of O(N^2) where N is + * the number of the bounding boxes created from the refinement + * level; for this reason, if the flag is set to true, make sure to + * choose wisely a coarse enough @p refinement_level. + * @param[in] max_boxes The maximum number of bounding boxes to + * compute. If more are created the smaller ones are merged with + * neighbors. By default after merging the boxes which can be + * expressed as a single one no more boxes are merged. See the + * BoundingBox::get_neighbor_type () function for details. Notice + * only neighboring cells are merged (see the @p get_neighbor_type + * function in bounding box class): if the target number of + * bounding boxes max_boxes can't be reached by merging neighbors + * an exception is thrown. + * + * The following image describes an example of the algorithm with @p + * refinement_level = 2, @p allow_merge = true and @p max_boxes = + * 1. The cells with the property predicate are in red, the area of + * a bounding box is slightly orange. * @image html bounding_box_predicate.png + * * - 1. In black we can see the cells of the current level. * - 2. For each cell containing the red area a bounding box is created: by * default these are returned.