* 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
* 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
* 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
* 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>
* 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
* 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
* 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 =
* 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>
* 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>
* 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;
* 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 =
* line orientations.
*
* See the
- * @ref GlossFaceOrientation "glossary"
+ * @ref GlossCombinedOrientation "glossary"
* for more information.
*/
constexpr types::geometric_orientation reverse_line_orientation =
/**
- * 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
* 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
* @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.
* 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
* @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.
* 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>
* @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.
*
* 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>
/**
- * 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
*
* 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>}
*/
* 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
* 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
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());
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];
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),
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),
* 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
*/