* coordinate system to another.
*
* This function is used in order to
- * determine how distorted a cell is: if
- * all of the determinants are of roughly
- * equal value and on the order of
- * $h^\text{dim}$ then the cell is
- * well-shaped. For example, a square
- * cell or face has determinants equal to
- * $h^\text{dim}$ whereas a strongly
- * sheared parallelogram has a
- * determinant much smaller. Similarly, a
- * cell with very unequal edge lengths
- * will have widely varying
- * determinants. Finally, an inverted
- * cell will have negative determinants.
+ * determine how distorted a cell is (see
+ * the entry on
+ * @ref GlossDistorted "distorted cells"
+ * in the glossary).
*/
static
void
* <h3>Dealing with distorted mesh cells</h3>
*
* For each of the mesh reading functions, the last call is always to
- * Triangulation::create_triangulation(). That function checks whether
- * all the cells it creates as part of the coarse mesh are distorted or
- * not (where distortion here means that the Jacobian of the mapping
- * from the reference cell to the real cell has a non-positive determinant,
- * i.e. the cell is pinched or twisted). If it finds any such cells, it
- * throws an exception. This exception is not caught in the grid reader
- * functions of the current class, and so will propagate through to the
- * function that called it. There, you can catch and ignore the
- * exception if you are certain that there is no harm in dealing with
- * such cells. If you were not aware that your mesh had such cells, your
- * results will likely be of dubious quality at best if you ignore the
- * exception.
+ * Triangulation::create_triangulation(). That function checks whether all the
+ * cells it creates as part of the coarse mesh are distorted or not (where
+ * distortion here means that the Jacobian of the mapping from the reference
+ * cell to the real cell has a non-positive determinant, i.e. the cell is
+ * pinched or twisted; see the entry on @ref GlossDistorted "distorted cells"
+ * in the glossary). If it finds any such cells, it throws an exception. This
+ * exception is not caught in the grid reader functions of the current class,
+ * and so will propagate through to the function that called it. There, you
+ * can catch and ignore the exception if you are certain that there is no harm
+ * in dealing with such cells. If you were not aware that your mesh had such
+ * cells, your results will likely be of dubious quality at best if you ignore
+ * the exception.
*
*
* @ingroup grid
/**
* A structure that is used as an
* exception object by the
- * create_triangulation()
- * function to indicate which
- * cells among the coarse mesh
- * cells are inverted or severely
- * distorted.
+ * create_triangulation() function to
+ * indicate which cells among the coarse
+ * mesh cells are inverted or severely
+ * distorted (see the entry on
+ * @ref GlossDistorted "distorted cells"
+ * in the glossary).
*
* Objects of this kind are
* thrown by the
* operation, this function walks
* over all cells and verifies
* that none of the cells is
- * deformed, where we call a cell
+ * deformed (see
+ * the entry on @ref GlossDistorted in
+ * the glossary), where we call a cell
* deformed if the determinant of
* the Jacobian of the mapping
* from reference cell to real
* FiniteElementData::n_components() and the documentation of
* FiniteElement</dd>
*
+ *
+ * <dt class="glossary">@anchor GlossDistorted Distorted cells</dt>
+ *
+ * <dd>A <i>distorted cell</i> is a cell for which the mapping from
+ * the reference cell to real cell has a Jacobian whose determinant is
+ * non-positive somewhere in the cell. Typically, we only check the sign
+ * of this determinant at the vertices of the cell. The function
+ * GeometryInfo::jacobian_determinants_at_vertices computes these
+ * determinants at the vertices, and the function
+ * Triangulation::create_triangulation (along with the various grid
+ * readers in the GridIn class) will reject meshes with distorted cells
+ * by default.
+ *
+ * By way of example, if all of the determinants are of roughly equal value
+ * and on the order of $h^\text{dim}$ then the cell is well-shaped. For
+ * example, a square cell or face has determinants equal to $h^\text{dim}$
+ * whereas a strongly sheared parallelogram has a determinant much
+ * smaller. Similarly, a cell with very unequal edge lengths will have widely
+ * varying determinants. Conversely, a pinched cell in which the location of
+ * two or more vertices is collapsed to a single point has a zero determinant
+ * at this location. Finally, an inverted or twisted cell in which the
+ * location of two vertices is out of order will have negative determinants.
+ *
+ * The following two images show a well-formed, a pinched, and a twisted cell
+ * for both 2d and 3d:
+ *
+ * @image html distorted_2d.png "A well-formed, a pinched, and a twisted cell in 2d."
+ *
+ * @image html distorted_3d.png "A well-formed, a pinched, and a twisted cell in 3d."
+ * </dd>
+ *
+ *
* <dt class="glossary">@anchor GlossFaceOrientation Face orientation</dt>
* <dd>In a triangulation, the normal vector to a face
* can be deduced from the face orientation by
--- /dev/null
+#FIG 3.2 Produced by xfig version 3.2.5
+Landscape
+Center
+Metric
+A4
+100.00
+Single
+-2
+1200 2
+2 3 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+ 4050 450 4050 1800 5400 450 5400 1800 4050 450
+2 3 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+ 2250 450 2250 1800 3600 1800 2250 450
+2 3 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+ 450 450 450 1800 1800 1800 1800 450 450 450
--- /dev/null
+#FIG 3.2 Produced by xfig version 3.2.5
+Landscape
+Center
+Metric
+A4
+100.00
+Single
+-2
+1200 2
+2 3 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+ 495 2205 495 3555 1845 3555 1845 2205 495 2205
+2 3 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+ 3600 2250 3600 3600 4950 3600 3600 2250
+2 3 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+ 6750 2250 6750 3600 8100 2250 8100 3600 6750 2250
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 7
+ 1845 3555 2430 2880 2430 1530 1845 2205 2430 1530 1080 1530
+ 495 2205
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 7
+ 4950 3600 5535 2925 5535 1575 4950 3600 5535 1575 4185 1575
+ 3600 2250
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 7
+ 8100 2250 8685 2925 8685 1575 8100 3600 8685 1575 7335 1575
+ 6750 2250
+2 1 2 1 0 7 50 -1 -1 3.000 0 0 -1 0 0 5
+ 495 3555 1080 2880 2430 2880 1080 2880 1080 1530
+2 1 2 1 0 7 50 -1 -1 3.000 0 0 -1 0 0 5
+ 3600 3600 4185 2925 5535 2925 4185 2925 4185 1575
+2 1 2 1 0 7 50 -1 -1 3.000 0 0 -1 0 0 5
+ 6750 3600 7335 2925 8685 2925 7335 2925 7335 1575
accepted input meshes with inverted cells (i.e. cells with a zero or negative
determinant of the Jacobian of the mapping from the reference cell to the
real cell). This has been changed now: The function checks whether cells
- are distorted or inverted, and may throw a list of cells for which this
- is the case as an exception. If you know that this is harmless, for example
+ are distorted or inverted (see the entry on @ref GlossDistorted "distorted cells"
+ in the glossary), and may throw an exception containing a list of cells for which this
+ is the case. If you know that this is harmless, for example
if you have cells with collapsed vertices in your mesh but you do not intend
to integrate on them, then you can catch and ignore this message. In all
other cases, the output of your computations are likely to be wrong anyway.