/**
- * 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 <code>Container</code>
- * 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 <code>Container</code> 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 <class Container>
- std::vector<typename Container::cell_iterator> get_cells_at_coarsest_common_level(
- const std::vector<typename Container::active_cell_iterator> &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 <code>Container</code>
- * 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<typename Container::cell_iterator>
+ get_cells_at_coarsest_common_level(const std::vector<typename Container::active_cell_iterator> &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<dim> element.
+ *
+ * @tparam Container In C++, the compiler can not determine the type
+ * of <code>Container</code> 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 <class Container>
void
std::map<typename Triangulation<Container::dimension,Container::space_dimension>::active_cell_iterator,
typename Container::active_cell_iterator> &patch_to_global_tria_map);
-
-
-
/*@}*/
/**
* @name Lower-dimensional meshes for parts of higher-dimensional meshes
projects / dealii.git / commitdiff