From 3cc225560c5573093d534e16ebdee93864b5235e Mon Sep 17 00:00:00 2001 From: bangerth Date: Fri, 25 Apr 2014 03:19:55 +0000 Subject: [PATCH] Augment documentation somewhat. git-svn-id: https://svn.dealii.org/trunk@32825 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/include/deal.II/grid/grid_tools.h | 11 +++--- deal.II/include/deal.II/grid/tria_accessor.h | 36 +++++++++++++++++++- 2 files changed, 41 insertions(+), 6 deletions(-) diff --git a/deal.II/include/deal.II/grid/grid_tools.h b/deal.II/include/deal.II/grid/grid_tools.h index 09377b3774..d37f30ffe4 100644 --- a/deal.II/include/deal.II/grid/grid_tools.h +++ b/deal.II/include/deal.II/grid/grid_tools.h @@ -184,14 +184,15 @@ namespace GridTools * pointer to the function. In * either case, argument and * return value have to be of - * type Point. + * type Point@. * - * Note: if you are using a parallel::distributed::Triangulation you will have + * @note If you are using a parallel::distributed::Triangulation you will have * hanging nodes in your local Triangulation even if your "global" mesh has * no hanging nodes. This will cause issues with wrong positioning of hanging - * nodes in ghost cells. The active cells will be correct, but keep in mind that - * computations like KellyErrorEstimator will give wrong answers. A safe bet is - * to use this function prior to any refinement in parallel. + * nodes in ghost cells. The vertices of all locally owned cells will be correct, + * but the vertices of some ghost cells may not. This means that + * computations like KellyErrorEstimator may give wrong answers. A safe bet is + * to use this function prior to any refinement in parallel, if that is possible. * * This function is used in the * "Possibilities for extensions" section diff --git a/deal.II/include/deal.II/grid/tria_accessor.h b/deal.II/include/deal.II/grid/tria_accessor.h index 4a45fd4c5e..17e78fd2b7 100644 --- a/deal.II/include/deal.II/grid/tria_accessor.h +++ b/deal.II/include/deal.II/grid/tria_accessor.h @@ -777,7 +777,41 @@ public: /** * Return a reference to the - * @p ith vertex. + * @p ith vertex. The reference is not const, i.e., it is possible + * to call this function on the left hand side of an assignment, + * thereby moving the vertex of a cell within the triangulation. Of + * course, doing so requires that you ensure that the new location + * of the vertex remains useful -- for example, avoiding inverted + * or otherwise distorted (see also @ref GlossDistorted). + * + * @note When a cell is refined, its children inherit the position + * of the vertex positions of those vertices they share with the mother + * cell (plus the locations of the new vertices on edges, faces, and + * cell interiors that are created for the new child cells). If the + * vertex of a cell is moved, this implies that its children will also + * use these new locations. On the other hand, imagine a 2d situation + * where you have one cell that is refined (with four children) and then + * you move the central vertex connecting all four children. If you + * coarsen these four children again to the mother cell, then the + * location of the moved vertex is lost and if, in a later step, you + * refine the mother cell again, the then again new vertex will be + * placed again at the same position as the first time around -- i.e., + * not at the location you had previously moved it to. + * + * @note The behavior described in the previous note is relevant if + * you have a parallel::distributed::Triangulation object. There, + * refining a mesh always involves a re-partitioning. In other words, + * vertices of locally owned cells (see @ref GlossLocallyOwnedCell) + * that you may have moved to a different location on one processor + * may be moved to a different processor upon mesh refinement (even + * if these particular cells were not refined) which will re-create + * their position based on the position of the coarse cells they + * previously had, not based on the position these vertices had on + * the processor that previously owned them. In other words, in + * parallel computations, you will probably have to move nodes + * explicitly after every mesh refinement because vertex positions + * may or may not be preserved across the re-partitioning that + * accompanies mesh refinement. */ Point &vertex (const unsigned int i) const; -- 2.39.5