]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Add a glossary entry for the combined orientation.
authorDavid Wells <drwells@email.unc.edu>
Wed, 23 Apr 2025 00:56:26 +0000 (20:56 -0400)
committerDavid Wells <drwells@email.unc.edu>
Wed, 23 Apr 2025 22:02:22 +0000 (18:02 -0400)
While we're at it - delete the one for face orientations. We don't compute
normal vectors this way any more.

12 files changed:
doc/doxygen/headers/glossary.h
include/deal.II/base/geometry_info.h
include/deal.II/base/types.h
include/deal.II/dofs/dof_tools.h
include/deal.II/fe/fe.h
include/deal.II/fe/fe_poly_tensor.h
include/deal.II/fe/fe_q_base.h
include/deal.II/fe/fe_raviart_thomas.h
include/deal.II/fe/fe_system.h
include/deal.II/grid/grid_tools.h
include/deal.II/grid/reference_cell.h
include/deal.II/grid/tria_accessor.h

index fad06d8fb5684256ccf54ad0c3d1e06caee8cbb5..da89ef628566847b359a31ec144c5aed9b41e14d 100644 (file)
  * p4est paper listed at their website.
  * </dd>
  *
- *
- * <dt class="glossary">@anchor GlossFaceOrientation <b>Face orientation</b></dt>
- * <dd>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<dim>::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
- * <em>standard orientation</em>. 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
- * <tt>cell->face_orientation(face_no)</tt>: 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.
+ * <dt class="glossary">@anchor GlossCombinedOrientation <b>Combined
+ * orientation</b></dt>
+ * <dd>
+ * 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 <em>combined_orientation</em> 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.
  * </dd>
  *
- *
  * <dt class="glossary">@anchor GlossGeneralizedSupport <b>Generalized support points</b></dt>
  * <dd>"Generalized support points" are, as the name suggests, a
  * generalization of @ref GlossSupport "support points". The latter
index 8543184b0b20563e8e92ab3ece7ae15ce1516db2..703f040d7e02bdcb829fbe4e2083fd143a6593b8 100644 (file)
@@ -1321,7 +1321,7 @@ struct GeometryInfo<0>
    * defaults to <tt>true</tt>, <tt>face_flip</tt> and <tt>face_rotation</tt>
    * default to <tt>false</tt> (standard orientation). In 2d only
    * <tt>face_flip</tt> 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".
  *
  *
  * <h4>Children</h4>
@@ -2234,7 +2234,7 @@ struct GeometryInfo
    * defaults to <tt>true</tt>, <tt>face_flip</tt> and <tt>face_rotation</tt>
    * default to <tt>false</tt> (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 <tt>true</tt>, <tt>face_flip</tt> and <tt>face_rotation</tt>
    * default to <tt>false</tt> (standard orientation). In 2d only
    * <tt>face_flip</tt> 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<int, faces_per_cell> 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<Tensor<1, dim>, 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<Tensor<1, dim>, faces_per_cell, dim - 1>
index 999c80943f9439b9d17195bac0688d67ea69e2df..286930552bf869500052211b851e8cb0ea29152a 100644 (file)
@@ -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 =
index 612803d97c7d5d70e3ec50b0e90bca596b39059e..c4b59dfcd3880071e95476d0e402565c83fcd343 100644 (file)
@@ -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 <code>2*dimension</code> and boundary indicator @p b_id
@@ -1052,9 +1048,9 @@ namespace DoFTools
    * index <code>2*dimension+1</code> 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
index ad8743fdc4bea2f6cd837f490341464d6e9ea829..188b2d177157d8643f993c77e422d05fc6ec02c2 100644 (file)
@@ -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.
index 377ae3f30c5160f2839cd7f2a7a0925f06335086..1a66c682c0a393449aadd7eb1883430a498e8348 100644 (file)
@@ -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<dim> 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
index aad7da51a1862ed836f7f4b4ca7a8e151a70143a..4280e2575616191418f8edace96867fcd826cefc 100644 (file)
@@ -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.
index 8dedc6b0267fda0899010ea4b1851457ae640329..5f0464fb696fd0b8ee8d325d6a168497836c0986 100644 (file)
@@ -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<dim> and
    * this
-   * @ref GlossFaceOrientation "glossary entry on face orientation".
+   * @ref GlossCombinedOrientation "glossary entry on face orientations".
    *
    * <h3>Example: Raviart-Thomas Elements of order 2 (tensor polynomial
    * degree 3)</h3>
index ce895be7b11965c3d27361d9d69909aac3c96bf7..4bb6cd14cb9bea436ddcbef21aaf1bcc187c8fdc 100644 (file)
@@ -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.
index ed61b87975b8d94c8d9b83b59f141ab23dbcb8eb..df298799cad047619e61737f6a0c4d94c52f7c5e 100644 (file)
@@ -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<types::geometric_orientation>, in which the stored value is
-   * the same orientation bit format used elsewhere in the library. More
+   * std::optional<types::geometric_orientation>. More
    * information on that topic can be found in the
-   * @ref GlossFaceOrientation
+   * @ref GlossCombinedOrientation
    * "glossary" article.
    */
   template <typename FaceIterator>
@@ -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 <code>2*direction</code> 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<MeshType>}
    */
index 4ab3293bf39b3ebfe5f3be3257c5ebc30a7998a0..6a45af7aa408e30ee98ab9d4c6afdd4dac35687d 100644 (file)
@@ -508,14 +508,14 @@ public:
    * handles faces oriented in the standard and non-standard orientation. It
    * represents a bit-code for the overall <tt>face_orientation</tt>,
    * <tt>face_flip</tt> and <tt>face_rotation</tt> 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 <typename T>
   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<unsigned int, 3, 2> 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),
index c07b5d7f378ace8c0e82210201a81126aabd0349..c096b1c711b331a96c2969961d19a468397fb2b8 100644 (file)
@@ -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
    */

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.