From: David Wells Date: Wed, 23 Apr 2025 00:56:26 +0000 (-0400) Subject: Add a glossary entry for the combined orientation. X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6661884d38bb3baa4879acb0ba56141695719788;p=dealii.git Add a glossary entry for the combined orientation. While we're at it - delete the one for face orientations. We don't compute normal vectors this way any more. --- diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h index fad06d8fb5..da89ef6285 100644 --- a/doc/doxygen/headers/glossary.h +++ b/doc/doxygen/headers/glossary.h @@ -1013,50 +1013,47 @@ * p4est paper listed at their website. * * - * - *
@anchor GlossFaceOrientation Face orientation
- *
In a triangulation, the normal vector to a face - * can be deduced from the face orientation by - * applying the right hand side rule (x,y -> normal). We note, that - * in the standard orientation of faces in 2d, faces 0 and 2 have - * normals that point into the cell, and faces 1 and 3 have normals - * pointing outward. In 3d, faces 0, 2, and 4 - * have normals that point into the cell, while the normals of faces - * 1, 3, and 5 point outward. This information, again, can be queried from - * GeometryInfo::unit_normal_orientation. - * - * However, it turns out that a significant number of 3d meshes cannot - * satisfy this convention. This is due to the fact that the face - * convention for one cell already implies something for the - * neighbor, since they share a common face and fixing it for the - * first cell also fixes the normal vectors of the opposite faces of - * both cells. It is easy to construct cases of loops of cells for - * which this leads to cases where we cannot find orientations for - * all faces that are consistent with this convention. - * - * For this reason, above convention is only what we call the - * standard orientation. deal.II actually allows faces in 3d - * to have either the standard direction, or its opposite, in which - * case the lines that make up a cell would have reverted orders, and - * the normal vector would have the opposite direction. You can ask a - * cell whether a given face has standard orientation by calling - * cell->face_orientation(face_no): if the result is @p true, - * then the face has standard orientation, otherwise its normal vector - * is pointing the other direction. There are not very many places in - * application programs where you need this information actually, but - * a few places in the library make use of this. Note that in 2d, the - * result is always @p true. However, while every face in 2d is always - * in standard orientation, you can sometimes specify something to - * assume that this is not so; an example is the function - * DoFTools::make_periodicity_constraints(). - * - * There are two other flags that describe the orientation of a face: - * face_flip and face_rotation. Some documentation for these - * exists in the GeometryInfo class. An example of their use in user - * code is given in the DoFTools::make_periodicity_constraints function. + *
@anchor GlossCombinedOrientation Combined + * orientation
+ *
+ * A Triangulation contains cells as well as lower dimensional objects such as + * faces (which are either lines in 2d or quadrilaterals or triangles in 3d). In + * general, the vertices of each cell are numbered in a way which results in a + * mapping with a positive Jacobian. A consequence of this choice is that the + * vertices which define a face may be, from the perspective of an arbitrary + * cell, in a different order than the order given to that face by the + * neighboring cell. To resolve this inconsistency deal.II stores, for each face + * and (in 3d) line, a value which may be used to permute the vertices on both + * faces into a matching configuration. This encoding contains both the number + * of times a face should be rotated (relative to its neighbor) as well as + * whether or not the face should be viewed in an opposite orientation (e.g., + * for a Quadrilateral, whether or not vertices $1$ and $2$ should be swapped). + * + * This value is called the combined_orientation since it combines both + * the orientation (as defined above) as well as rotations. In some + * circumstances, to disambiguate between faces and lines, it may alternatively + * be called either the `combined_face_orientation` or the + * `combined_line_orientation`. These orientations are represented by + * types::geometric_orientation, which encodes how the vertices of the canonical + * definition of a face should be permuted so that they equal the current cell's + * definition of that face. The binary encoding (which is usually represented as + * a decomposition of three booleans called orientation, rotation, and flip) of + * that permutation is an internal library detail and is documented in + * @ref reordering "the cell reordering page". + * The default value (which corresponds to the identity permutation) is + * numbers::default_geometric_orientation. As lines only have two possible + * orientations (i.e., the vertices are either in the same order as the + * canonical line or are swapped), the other orientation is encoded as + * numbers::reverse_line_orientation. + * + * These values are taken into consideration by deal.II classes (such as + * QProjector) to ensure that quantities computed on two adjacent cells use the + * same quadrature points and shape function orderings. Unless you are working + * on deal.II internals or new FiniteElement classes, it is not necessary to + * consider these values. In practice, essentially no applications dependent on + * deal.II ever need to handle orientation problems. *
* - * *
@anchor GlossGeneralizedSupport Generalized support points
*
"Generalized support points" are, as the name suggests, a * generalization of @ref GlossSupport "support points". The latter diff --git a/include/deal.II/base/geometry_info.h b/include/deal.II/base/geometry_info.h index 8543184b0b..703f040d7e 100644 --- a/include/deal.II/base/geometry_info.h +++ b/include/deal.II/base/geometry_info.h @@ -1321,7 +1321,7 @@ struct GeometryInfo<0> * defaults to true, face_flip and face_rotation * default to false (standard orientation). In 2d only * face_flip is considered. See this - * @ref GlossFaceOrientation "glossary" + * @ref GlossCombinedOrientation "glossary" * article for more information. * * As the children of a cell are ordered according to the vertices of the @@ -1750,7 +1750,7 @@ struct GeometryInfo<0> * but a few places in the library make use of this. Note that in 2d, the * result is always @p true. More information on the topic can be found in * this - * @ref GlossFaceOrientation "glossary" + * @ref GlossCombinedOrientation "glossary" * article. * * In order to allow all kinds of meshes in 3d, including @@ -1766,7 +1766,7 @@ struct GeometryInfo<0> * cells and faces in 3d. Again, this is something that should be internal to * the library and application program will probably never have to bother * about it. For more information on this see also - * @ref GlossFaceOrientation "this glossary entry". + * @ref GlossCombinedOrientation "this glossary entry". * * *

Children

@@ -2234,7 +2234,7 @@ struct GeometryInfo * defaults to true, face_flip and face_rotation * default to false (standard orientation) and has no effect in 2d. * The concept of face orientations is explained in this - * @ref GlossFaceOrientation "glossary" + * @ref GlossCombinedOrientation "glossary" * entry. * * In the case of anisotropically refined cells and faces, the @p @@ -2280,7 +2280,7 @@ struct GeometryInfo * defaults to true, face_flip and face_rotation * default to false (standard orientation). In 2d only * face_flip is considered. See this - * @ref GlossFaceOrientation "glossary" + * @ref GlossCombinedOrientation "glossary" * article for more information. * * As the children of a cell are ordered according to the vertices of the @@ -2594,7 +2594,7 @@ struct GeometryInfo * least in 3d, actual faces of cells in a triangulation can also have the * opposite orientation, depending on a flag that one can query from the * cell it belongs to. For more information, see the - * @ref GlossFaceOrientation "glossary" + * @ref GlossCombinedOrientation "glossary" * entry on face orientation. */ static constexpr std::array unit_normal_orientation = @@ -2607,7 +2607,7 @@ struct GeometryInfo * least in 3d, actual faces of cells in a triangulation can also have the * opposite orientation, depending on a flag that one can query from the * cell it belongs to. For more information, see the - * @ref GlossFaceOrientation "glossary" + * @ref GlossCombinedOrientation "glossary" * entry on face orientation. */ static constexpr std::array, faces_per_cell> @@ -2624,7 +2624,7 @@ struct GeometryInfo * least in 3d, actual faces of cells in a triangulation can also have the * opposite orientation, depending on a flag that one can query from the * cell it belongs to. For more information, see the - * @ref GlossFaceOrientation "glossary" + * @ref GlossCombinedOrientation "glossary" * entry on face orientation. */ static constexpr ndarray, faces_per_cell, dim - 1> diff --git a/include/deal.II/base/types.h b/include/deal.II/base/types.h index 999c80943f..286930552b 100644 --- a/include/deal.II/base/types.h +++ b/include/deal.II/base/types.h @@ -34,7 +34,7 @@ namespace types * The type used to represent face and line orientations. * * See the - * @ref GlossFaceOrientation "glossary" + * @ref GlossCombinedOrientation "glossary" * for more information. */ using geometric_orientation = unsigned char; @@ -346,7 +346,7 @@ namespace numbers * Value indicating that a face or line is in its default orientation. * * See the - * @ref GlossFaceOrientation "glossary" + * @ref GlossCombinedOrientation "glossary" * for more information. */ constexpr types::geometric_orientation default_geometric_orientation = @@ -359,7 +359,7 @@ namespace numbers * line orientations. * * See the - * @ref GlossFaceOrientation "glossary" + * @ref GlossCombinedOrientation "glossary" * for more information. */ constexpr types::geometric_orientation reverse_line_orientation = diff --git a/include/deal.II/dofs/dof_tools.h b/include/deal.II/dofs/dof_tools.h index 612803d97c..c4b59dfcd3 100644 --- a/include/deal.II/dofs/dof_tools.h +++ b/include/deal.II/dofs/dof_tools.h @@ -1041,10 +1041,6 @@ namespace DoFTools /** - * This compatibility version of make_periodicity_constraints only works on - * grids with cells in - * @ref GlossFaceOrientation "standard orientation". - * * Instead of defining a 'first' and 'second' boundary with the help of two * boundary_ids this function defines a 'left' boundary as all faces with * local face index 2*dimension and boundary indicator @p b_id @@ -1052,9 +1048,9 @@ namespace DoFTools * index 2*dimension+1 and boundary indicator @p b_id. Faces with * coordinates only differing in the @p direction component are identified. * - * @note This version of make_periodicity_constraints will not work on + * @warning This version of make_periodicity_constraints will not work on * meshes with cells not in - * @ref GlossFaceOrientation "standard orientation". + * @ref GlossCombinedOrientation "the default orientation". * * @note This function is a convenience wrapper. It internally calls * GridTools::collect_periodic_faces() with the supplied parameters and diff --git a/include/deal.II/fe/fe.h b/include/deal.II/fe/fe.h index ad8743fdc4..188b2d1771 100644 --- a/include/deal.II/fe/fe.h +++ b/include/deal.II/fe/fe.h @@ -1512,7 +1512,8 @@ public: * @param face The number of the face this degree of freedom lives on. This * number must be between zero and GeometryInfo::faces_per_cell. * @param combined_orientation The combined orientation flag containing the - * orientation, rotation, and flip of the face. See @ref GlossFaceOrientation. + * orientation, rotation, and flip of the face. See + * @ref GlossCombinedOrientation. * @return The index of this degree of freedom within the set of degrees of * freedom on the entire cell. The returned value will be between zero and * dofs_per_cell. diff --git a/include/deal.II/fe/fe_poly_tensor.h b/include/deal.II/fe/fe_poly_tensor.h index 377ae3f30c..1a66c682c0 100644 --- a/include/deal.II/fe/fe_poly_tensor.h +++ b/include/deal.II/fe/fe_poly_tensor.h @@ -252,7 +252,7 @@ protected: * no sign change at all. Derived finite element classes have to * fill this Table with the correct values, see the documentation in * GeometryInfo and this - * @ref GlossFaceOrientation "glossary entry on face orientation". + * @ref GlossCombinedOrientation "glossary entry on face orientations". * * The table must be filled in finite element classes derived * from FE_PolyTensor in a meaningful way since the permutation diff --git a/include/deal.II/fe/fe_q_base.h b/include/deal.II/fe/fe_q_base.h index aad7da51a1..4280e25756 100644 --- a/include/deal.II/fe/fe_q_base.h +++ b/include/deal.II/fe/fe_q_base.h @@ -184,7 +184,8 @@ public: * @param face The number of the face this degree of freedom lives on. This * number must be between zero and GeometryInfo::faces_per_cell. * @param combined_orientation The combined orientation flag containing the - * orientation, rotation, and flip of the face. See @ref GlossFaceOrientation. + * orientation, rotation, and flip of the face. See + * @ref GlossCombinedOrientation. * @return The index of this degree of freedom within the set of degrees of * freedom on the entire cell. The returned value will be between zero and * dofs_per_cell. diff --git a/include/deal.II/fe/fe_raviart_thomas.h b/include/deal.II/fe/fe_raviart_thomas.h index 8dedc6b026..5f0464fb69 100644 --- a/include/deal.II/fe/fe_raviart_thomas.h +++ b/include/deal.II/fe/fe_raviart_thomas.h @@ -226,7 +226,7 @@ private: * faces. These are given in the form three flags (face_orientation, * face_flip, face_rotation), see the documentation in GeometryInfo and * this - * @ref GlossFaceOrientation "glossary entry on face orientation". + * @ref GlossCombinedOrientation "glossary entry on face orientations". * *

Example: Raviart-Thomas Elements of order 2 (tensor polynomial * degree 3)

diff --git a/include/deal.II/fe/fe_system.h b/include/deal.II/fe/fe_system.h index ce895be7b1..4bb6cd14cb 100644 --- a/include/deal.II/fe/fe_system.h +++ b/include/deal.II/fe/fe_system.h @@ -880,7 +880,8 @@ public: * @param face The number of the face this degree of freedom lives on. This * number must be between zero and GeometryInfo::faces_per_cell. * @param combined_orientation The combined orientation flag containing the - * orientation, rotation, and flip of the face. See @ref GlossFaceOrientation. + * orientation, rotation, and flip of the face. See + * @ref GlossCombinedOrientation. * @return The index of this degree of freedom within the set of degrees of * freedom on the entire cell. The returned value will be between zero and * dofs_per_cell. diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h index ed61b87975..df298799ca 100644 --- a/include/deal.II/grid/grid_tools.h +++ b/include/deal.II/grid/grid_tools.h @@ -2366,10 +2366,9 @@ namespace GridTools * * If the matching was successful, the _relative_ orientation of @p face1 with * respect to @p face2 is returned a - * std::optional, in which the stored value is - * the same orientation bit format used elsewhere in the library. More + * std::optional. More * information on that topic can be found in the - * @ref GlossFaceOrientation + * @ref GlossCombinedOrientation * "glossary" article. */ template @@ -2455,10 +2454,6 @@ namespace GridTools /** - * This compatibility version of collect_periodic_faces() only works on - * grids with cells in - * @ref GlossFaceOrientation "standard orientation". - * * Instead of defining a 'first' and 'second' boundary with the help of two * boundary_ids this function defines a 'left' boundary as all faces with * local face index 2*direction and boundary indicator @p b_id @@ -2472,9 +2467,9 @@ namespace GridTools * * See above function for further details. * - * @note This version of collect_periodic_faces() will not work on - * meshes with cells not in - * @ref GlossFaceOrientation "standard orientation". + * @warning This version of collect_periodic_faces() will not work on + * meshes with faces not in the + * @ref GlossCombinedOrientation "default orientation". * * @dealiiConceptRequires{concepts::is_triangulation_or_dof_handler} */ diff --git a/include/deal.II/grid/reference_cell.h b/include/deal.II/grid/reference_cell.h index 4ab3293bf3..6a45af7aa4 100644 --- a/include/deal.II/grid/reference_cell.h +++ b/include/deal.II/grid/reference_cell.h @@ -508,14 +508,14 @@ public: * handles faces oriented in the standard and non-standard orientation. It * represents a bit-code for the overall face_orientation, * face_flip and face_rotation and defaults to the standard - * orientation. The concept of face orientations is explained in this - * @ref GlossFaceOrientation "glossary" - * entry. + * orientation. The concept of combined orientations is explained in this + * @ref GlossCombinedOrientation "glossary" entry. */ unsigned int - child_cell_on_face(const unsigned int face, - const unsigned int subface, - const types::geometric_orientation face_orientation) const; + child_cell_on_face( + const unsigned int face, + const unsigned int subface, + const types::geometric_orientation combined_orientation) const; /** * For a given vertex in a cell, return a pair of a face index and a @@ -870,10 +870,9 @@ public: * The size of the input arrays must be equal to the number of vertices of * the current entity. * - * @returns A number that describes a relative orientation. How exactly - * this index is defined is not important, but it is consistent with the - * understanding the permute_by_combined_orientation() has of - * these orientation indices. + * @returns A number that describes a relative orientation. For more + * information see @ref GlossCombinedOrientation "the combined orientation + * glossary entry". */ template types::geometric_orientation @@ -2165,7 +2164,7 @@ inline unsigned int ReferenceCell::child_cell_on_face( const unsigned int face, const unsigned int subface, - const types::geometric_orientation combined_face_orientation) const + const types::geometric_orientation combined_orientation) const { AssertIndexRange(face, n_faces()); AssertIndexRange(subface, face_reference_cell(face).n_isotropic_children()); @@ -2183,12 +2182,11 @@ ReferenceCell::child_cell_on_face( static constexpr ndarray subcells = { {{{0, 1}}, {{1, 2}}, {{2, 0}}}}; - Assert(combined_face_orientation == + Assert(combined_orientation == numbers::default_geometric_orientation || - combined_face_orientation == - numbers::reverse_line_orientation, + combined_orientation == numbers::reverse_line_orientation, ExcInternalError()); - return subcells[face][combined_face_orientation == + return subcells[face][combined_orientation == numbers::default_geometric_orientation ? subface : 1 - subface]; @@ -2196,7 +2194,7 @@ ReferenceCell::child_cell_on_face( case ReferenceCells::Quadrilateral: { const auto [face_orientation, face_rotation, face_flip] = - internal::split_face_orientation(combined_face_orientation); + internal::split_face_orientation(combined_orientation); return GeometryInfo<2>::child_cell_on_face( RefinementCase<2>(RefinementPossibilities<2>::isotropic_refinement), @@ -2216,7 +2214,7 @@ ReferenceCell::child_cell_on_face( case ReferenceCells::Hexahedron: { const auto [face_orientation, face_rotation, face_flip] = - internal::split_face_orientation(combined_face_orientation); + internal::split_face_orientation(combined_orientation); return GeometryInfo<3>::child_cell_on_face( RefinementCase<3>(RefinementPossibilities<3>::isotropic_refinement), diff --git a/include/deal.II/grid/tria_accessor.h b/include/deal.II/grid/tria_accessor.h index c07b5d7f37..c096b1c711 100644 --- a/include/deal.II/grid/tria_accessor.h +++ b/include/deal.II/grid/tria_accessor.h @@ -1816,6 +1816,8 @@ private: * Set the combined face orientation (i.e., the integer that uniquely encodes * the orientation, flip, and rotation). This function is only implemented for * objects which have faces, i.e., for structdim == dim. + * For more information see the + * @ref GlossCombinedOrientation "combined orientation glossary entry". * * @ingroup reordering */