From: Timo Heister Date: Sat, 12 Sep 2020 00:37:07 +0000 (-0400) Subject: improve documentation and arg naming of cell neighbor*() X-Git-Tag: v9.3.0-rc1~1126^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F10908%2Fhead;p=dealii.git improve documentation and arg naming of cell neighbor*() My students rightfully got confused about the documentation and the confusing argument name i. Try to fix things. --- diff --git a/include/deal.II/grid/tria_accessor.h b/include/deal.II/grid/tria_accessor.h index 9022adfade..f54176e70f 100644 --- a/include/deal.II/grid/tria_accessor.h +++ b/include/deal.II/grid/tria_accessor.h @@ -2924,10 +2924,13 @@ public: const unsigned int subface_no) const; /** - * Return a pointer to the @p ith neighbor. If the neighbor does not exist, + * Return an iterator to the neighboring cell on the other side of the face + * with number @p face_no. If the neighbor does not exist, * i.e., if the @p ith face of the current object is at the boundary, then * an invalid iterator is returned. * + * Consequently, the index @p face_no must be less than n_faces(). + * * The neighbor of a cell has at most the same level as this cell. For * example, consider the following situation: * @image html limit_level_difference_at_vertices.png "" @@ -2940,40 +2943,46 @@ public: * * On the other hand, if you were at the top right cell of the four small * cells at the top left, and you asked for the right neighbor (which is - * associated with index i=1), then you would get the large + * associated with index face_no=1), then you would get the large * cell at the top right which in this case has a lower refinement level and * no children of its own. */ TriaIterator> - neighbor(const unsigned int i) const; + neighbor(const unsigned int face_no) const; /** - * Return the index of the @p ith neighbor. If the neighbor does not exist, - * its index is -1. + * Return the cell index of the neighboring cell on the other side of the face + * with index @p face_no. If the neighbor does not exist, this function returns -1. + * + * This function is equivalent to cell->neighbor(face_no)->index(). + * See neighbor() for more details. */ int - neighbor_index(const unsigned int i) const; + neighbor_index(const unsigned int face_no) const; /** - * Return the level of the @p ith neighbor. If the neighbor does not exist, - * its level is -1. + * Return the level of the neighboring cell on the other side of the face with + * number @p face_no. If the neighbor does not exist, this function returns -1. + * + * This function is equivalent to cell->neighbor(face_no)->level(). + * See neighbor() for more details. */ int - neighbor_level(const unsigned int i) const; + neighbor_level(const unsigned int face_no) const; /** * Return the how-many'th neighbor this cell is of - * cell->neighbor(neighbor), i.e. return the @p face_no such that - * cell->neighbor(neighbor)->neighbor(face_no)==cell. This function - * is the right one if you want to know how to get back from a neighbor to - * the present cell. + * cell->neighbor(face_no), i.e. return the @p other_face_no such that + * cell->neighbor(face_no)->neighbor(other_face_no)==cell. This + * function is the right one if you want to know how to get back from a + * neighbor to the present cell. * * Note that this operation is only useful if the neighbor is not coarser * than the present cell. If the neighbor is coarser this function throws an * exception. Use the @p neighbor_of_coarser_neighbor function in that case. */ unsigned int - neighbor_of_neighbor(const unsigned int neighbor) const; + neighbor_of_neighbor(const unsigned int face_no) const; /** * Return, whether the neighbor is coarser then the present cell. This is @@ -2986,7 +2995,7 @@ public: * the finer face is either a child or a grandchild of the coarser face. */ bool - neighbor_is_coarser(const unsigned int neighbor) const; + neighbor_is_coarser(const unsigned int face_no) const; /** * This function is a generalization of the @p neighbor_of_neighbor function diff --git a/include/deal.II/grid/tria_accessor.templates.h b/include/deal.II/grid/tria_accessor.templates.h index a9b3b15cb9..e38575a64a 100644 --- a/include/deal.II/grid/tria_accessor.templates.h +++ b/include/deal.II/grid/tria_accessor.templates.h @@ -3230,11 +3230,12 @@ CellAccessor::face_index(const unsigned int i) const template inline int -CellAccessor::neighbor_index(const unsigned int i) const +CellAccessor::neighbor_index(const unsigned int face_no) const { - AssertIndexRange(i, this->n_faces()); + AssertIndexRange(face_no, this->n_faces()); return this->tria->levels[this->present_level] - ->neighbors[this->present_index * GeometryInfo::faces_per_cell + i] + ->neighbors[this->present_index * GeometryInfo::faces_per_cell + + face_no] .second; } @@ -3242,11 +3243,12 @@ CellAccessor::neighbor_index(const unsigned int i) const template inline int -CellAccessor::neighbor_level(const unsigned int i) const +CellAccessor::neighbor_level(const unsigned int face_no) const { - AssertIndexRange(i, this->n_faces()); + AssertIndexRange(face_no, this->n_faces()); return this->tria->levels[this->present_level] - ->neighbors[this->present_index * GeometryInfo::faces_per_cell + i] + ->neighbors[this->present_index * GeometryInfo::faces_per_cell + + face_no] .first; } @@ -3521,11 +3523,11 @@ CellAccessor::clear_coarsen_flag() const template inline TriaIterator> -CellAccessor::neighbor(const unsigned int i) const +CellAccessor::neighbor(const unsigned int face_no) const { TriaIterator> q(this->tria, - neighbor_level(i), - neighbor_index(i)); + neighbor_level(face_no), + neighbor_index(face_no)); Assert((q.state() == IteratorState::past_the_end) || q->used(), ExcInternalError()); diff --git a/source/grid/tria_accessor.cc b/source/grid/tria_accessor.cc index d14bfcdb6e..0720118b28 100644 --- a/source/grid/tria_accessor.cc +++ b/source/grid/tria_accessor.cc @@ -2360,9 +2360,9 @@ CellAccessor::neighbor_of_neighbor_internal( template unsigned int CellAccessor::neighbor_of_neighbor( - const unsigned int neighbor) const + const unsigned int face_no) const { - const unsigned int n2 = neighbor_of_neighbor_internal(neighbor); + const unsigned int n2 = neighbor_of_neighbor_internal(face_no); Assert(n2 != numbers::invalid_unsigned_int, TriaAccessorExceptions::ExcNeighborIsCoarser()); @@ -2374,9 +2374,9 @@ CellAccessor::neighbor_of_neighbor( template bool CellAccessor::neighbor_is_coarser( - const unsigned int neighbor) const + const unsigned int face_no) const { - return neighbor_of_neighbor_internal(neighbor) == + return neighbor_of_neighbor_internal(face_no) == numbers::invalid_unsigned_int; }