From: Arezou Ghesmati Date: Tue, 19 Jan 2016 16:33:06 +0000 (-0600) Subject: Some modifications in the ducumentation of function build_triangulation_from_patch... X-Git-Tag: v8.4.0-rc2~40^2~1 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=830a94088ddc72629c05f431387b84466dd22423;p=dealii.git Some modifications in the ducumentation of function build_triangulation_from_patch() is done --- diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h index 7b429ea258..9718fe12b3 100644 --- a/include/deal.II/grid/grid_tools.h +++ b/include/deal.II/grid/grid_tools.h @@ -988,60 +988,97 @@ namespace GridTools /** - * This function takes a vector of active cells (here named as patch_cells) - * as input argument, and returns vector of their parent cells with the - * coarsest common level of refinement. - * The way that the function works, is as follows: - * first it computes the minimum refinement level of the given vector of - * active cells. Then loops over cells of the input vector of active cells. - * For each cell, if its refinement level is equal to the computted minimum - * refinement level, that cell is pushed back to the vector of output cells. - * Otherwise, the function looks for the parent cell of the current cell, - * with the level equal to the computed minimum refinement level, and - * then pushes back this parent cell to the vector of output cells. - * - * @tparam Container - * In C++, the compiler can not determine the type of Container - * from the function call. You need to specify it as an explicit template - * argument following the function name. - * @param[in] patch_cells This vector of cells, typically results from - * calling the function GridTools::get_patch_around_cell(). - * @return A list of cells with the coarsest common level of refinement + * This function takes a vector of active cells (hereafter named @p + * patch_cells) as input argument, and returns a vector of their + * parent cells with the coarsest common level of refinement. In + * other words, find that set of cells living at the same refinement + * level so that all cells in the input vector are children of the + * cells in the set, or are in the set itself. + * + * @tparam Container In C++, the compiler can not determine the type + * of Container from the function call. You need to + * specify it as an explicit template argument following the + * function name. This type has to satisfy the requirements of a + * mesh container (see @ref GlossMeshAsAContainer). + * + * @param[in] patch_cells A vector of active cells for which + * this function finds the parents at the coarsest common + * level. This vector of cells typically results from + * calling the function GridTools::get_patch_around_cell(). + * @return A list of cells with the coarsest common level of + * refinement of the input cells. * * @author Arezou Ghesmati, Wolfgang Bangerth, 2015 */ template - std::vector get_cells_at_coarsest_common_level( - const std::vector &patch_cells); - - /** - * The first element of input argument is a vector of active cells which we - * want to build local triangulation associated with this vector. - * Besides building triangulation for the given vector of cells, this - * function returns a map which actually pairs each cell of the local - * triangulation with their corresponding cell of type global DofHandler - * in the problem domain. The function loops over all cells of local - * triangulation to fill out the map. It actually asks from the map, - * if mutual pair of the given cell in the map - * has children in global DofHandler, then set_refine_flag() for that cell. - * After doing refinement the refined cell should not be in the map anymore. - * Instead, the children may be added into the map. - * Therefore, the next loop is over the children, so that they are inserted - * to the map and the parent cell will be erased from the map. This way the - * final map always contains the set of active cells of type triangulation, - * such that the key comes fromlocal triangulation and the value comes from - * cells of type global DofHandler. - * - * @tparam Container - * In C++, the compiler can not determine the type of Container - * from the function call. You need to specify it as an explicit template - * argument following the function name. - * @param[in] A vector of active cells - * @param[out] local triangulation corresponding to the given vector of active cells - * @param[out] patch_to_global_tria_map A map between the local triangulation which - * is built as explained above, and the cells of type global DofHandler. - * - * @author Arezou Ghesmati, 2015 + std::vector + get_cells_at_coarsest_common_level(const std::vector &patch_cells); + + /** + * This function constructs a Triangulation (named @p + * local_triangulation) from a given vector of active cells. This + * vector (which we think of the cells corresponding to a "patch") + * contains active cells that are part of an existing global + * Triangulation. The goal of this function is to build a local + * Triangulation that contains only the active cells given in + * @p patch (and potentially a minimum number of additional cells + * required to form a valid Triangulation). + * The function also returns a map that allows to identify the cells in + * the output Triangulation and corresponding cells in the input + * list. + * + * The operation implemented by this function is frequently used in + * the definition of error estimators that need to solve "local" + * problems on each cell and its neighbors. A similar construction is + * necessary in the definition of the Clement interpolation operator + * in which one needs to solve a local problem on all cells within + * the support of a shape function. This function then builds a + * complete Triangulation from a list of cells that make up such a + * patch; one can then later attach a DoFHandler to such a + * Triangulation. + * + * If the list of input cells contains only cells at the same + * refinement level, then the output Triangulation simply consists + * of a Triangulation containing only exactly these patch cells. On + * the other hand, if the input cells live on different refinement + * levels, i.e., the Triangulation of which they are part is + * adaptively refined, then the construction of the output + * Triangulation is not so simple because the coarsest level of a + * Triangulation can not contain hanging nodes. Rather, we first + * have to find the common refinement level of all input cells, + * along with their common parents (see + * GridTools::get_cells_at_coarsest_common_level()), build a + * Triangulation from those, and then adaptively refine it so that + * the input cells all also exist in the output Triangulation. + * + * A consequence of this procedure is that that output Triangulation + * may contain more active cells than the ones that exist in the + * input vector. On the other hand, one typically wants to solve + * the local problem not on the entire output Triangulation, but + * only on those cells of it that correspond to cells in the input + * list. In this case, a user typically wants to assign degrees of + * freedom only on cells that are part of the "patch", and somehow + * ignore those excessive cells. The current function supports this + * common requirement by setting the user flag for the cells in the + * output Triangulation that match with cells in the input + * list. Cells which are not part of the original patch will not + * have their user_flag set; we can then avoid assigning degrees of + * freedom using the FE_Nothing element. + * + * @tparam Container In C++, the compiler can not determine the type + * of Container from the function call. You need to + * specify it as an explicit template argument following the + * function name. This type that satisfies the requirements of a + * mesh container (see @ref GlossMeshAsAContainer). + * + * @param[in] patch A vector of active cells from a common triangulation. + * These cells may or may not all be at the same refinement level. + * @param[out] local_triangulation A triangulation whose active cells + * correspond to the given vector of active cells in @p patch. + * @param[out] patch_to_global_tria_map A map between the local triangulation + * which is built as explained above, and the cell iterators in the input list. + * + * @author Arezou Ghesmati, Wolfgang Bangerth, 2015 */ template void @@ -1051,9 +1088,6 @@ namespace GridTools std::map::active_cell_iterator, typename Container::active_cell_iterator> &patch_to_global_tria_map); - - - /*@}*/ /** * @name Lower-dimensional meshes for parts of higher-dimensional meshes diff --git a/source/grid/grid_tools.cc b/source/grid/grid_tools.cc index 628b9b3c6b..c5b302116a 100644 --- a/source/grid/grid_tools.cc +++ b/source/grid/grid_tools.cc @@ -3025,7 +3025,8 @@ next_cell: ExcInternalError()); } } - // The parent cell which its children are added into map, should be deleted from map + // The parent cell whose children were added + // into the map should be deleted from the map patch_to_global_tria_map_tmp.erase(cell); } }