.. _commands-metrics:

**************************
Element Distortion Metrics
**************************

Sierra/SM can compute many element distortion metrics useful for assessing the quality of the solution as the mesh evolves over time. These  metrics are computed as element variables, and can be used for output or as criteria for element death, just like any other element variable. The solution quality generally deteriorates as elements approach inversion, and if they do invert, the analysis aborts. The distortion metrics measure how close an element is to inversion. For all metrics a value of 1.0 is an ideal element and a value of 0.0 is a degenerate element. The following distortion metrics are available:

- ``NODAL_JACOBIAN_RATIO`` is currently available only for 8 node hexahedra and four node quads. This metric evaluates the Jacobian function at each node of each element, and then computes the nodal Jacobian ratio as the smallest nodal Jacobian divided by the largest nodal Jacobian. An element shaped like a parallelepiped with equal angles between all adjacent edges has a nodal Jacobian ratio of 1.0. A negative nodal Jacobian ratio indicates that the element is becoming either concave or locally inverted. See :numref:`fig-nodal_jac_examples` for examples of quadrilateral elements with positive, zero, and negative nodal Jacobian ratios. The element calculations on poorly shaped elements (those with negative nodal Jacobian ratios) will generally be less accurate than those on well shaped elements (those with positive nodal Jacobian ratios). In addition, contact surfaces may become tangled and non-physical if elements start to invert.

.. _fig-nodal_jac_examples:

.. subfigure:: ABC
   :subcaptions: below
   :align: center

   .. image:: ../../_static/figures/nodalJac10.png
      :alt: (a) Nodal Jacobian = 1.0.
      :scale: 15 %

   .. image:: ../../_static/figures/nodalJac00.png
      :alt: (b) Nodal Jacobian = 0.0.
      :scale: 15 %

   .. image:: ../../_static/figures/nodalJacNeg.png
      :alt: (c) Nodal Jacobian < 0.0.
      :scale: 15 %

   Examples of elements with varying nodal Jacobians.

- ``SCALED_JACOBIAN`` is currently available only for 8 node hexahedra. This is the minimum value of the nodal Jacobian normalized by the element volume. An element with right angle edges will have a scaled Jacobian of 1.0. A value of 0.0 indicates concavity or inversion. The ``SCALED_JACOBIAN`` is  equivalent to the "scaled Jacobian" metric reported by cubit.

- ``ELEMENT_SHAPE`` computes a general shape metric for a variety of element topologies. This is currently defined for 8 node hexahedra, 4 node tetrahedra, 10 node tetrahedra, 4 node quadrilaterals, and 3 node triangles. A value of 1.0 is optimal. A value of 0.0 represents a degenerate element. A negative value represents either a severely warped element or inverted element. For the 8 node hexahedron, the element shape is a scaled Jacobian equivalent to the 'shape' metric reported by cubit. For a 4 node tetrahedron or 3 node triangle, the shape is proportional to the element aspect ratio. For the 10 node tetrahedron, the shape metric is equivalent to the mean ratio. For the 4 node quad element, the shape is proportional to the amount of warping of the quad. If a mesh contains elements with negative ``ELEMENT_SHAPE``, problems could arise in the material or contact computations.

- ``ASPECT_RATIO`` is available only for tetrahedral elements. A perfect equilateral tetrahedron has an aspect ratio of 1.0. A degenerate zero-volume tetrahedron has an aspect ratio of zero. An inverted tetrahedron has a negative aspect ratio. A thin element can have a extremely small aspect ratio.

- ``INRADIUS`` For all tets but 10-node tetrahedrons, the radius of the smallest, fully contained sphere of the linear tet. For 10-node tetrahedrons, the mid-edge nodes are used to subdivide the tet into 12 linear sub-tets. The inradius is the smallest inradius of the 12 linear sub-tets multiplied by 2.3

- ``NORMALIZED_INRADIUS`` is available only for 10-node tetrahedron elements. This metric provides a measure of the deviation from an ideal equilateral tetrahedron and accounts for distortions which stem from both corner and mid-edge nodes. Inradii  are calculated for the 12 sub-tetrahedra comprising the composite tetrahedron and  normalized by the outer radius of the four nodes forming the parent, 4-node linear  tetrahedron. Normalization factors scale the metric appropriately where values less  than zero indicate an degenerate sub-tetrahedron and a value of 1.0 corresponds to  a equilateral tetrahedron. The ``normalized_inradius`` is the minimum of the 12 normalized  inradii.

- ``MEAN_RATIO`` The mean ratio quality metric was developed to aid schemes that employ element death for tetrahedral discretizations. A value of 1.0 is optimal, while valuesnear 0.0 may indicate unacceptable element distortion. This metric is availablefor both 4-node and 10-node tetrahedrons. The Mean ratio quality metric measuresthe deviation of a tetrahedral element from an equilateral tetrahedron through the root-mean-squared edge length. In this context, we employ a volume ratio. For a 4-node tet, we have a single measure comparing the volume to the cube of root-mean-squared length of the six edges. For the 10-node tet, we form 12 sub-tets and find the minimum mean ratio of all sub-tetrahedra. Unlike the normalized inradius, the mean ratio is quite sensitive to a single, highly-elongated sub-tet. We note that for an equilateral 10-node tetrahedral element, there are two families of sub-tetrahedra. Sub-tets connected to the corner nodes or parent nodes of the 4-node tet have a mean ratio of 1 by construction. They are equilateral tets. The other family of sub-tets are not equilateral tets. These interior sub-tets connected entirely to mid-edge nodes are scaled such that all sub-tetrahedra have a mean ratio of 1 for an equilateral tet. 

- ``SOLID_ANGLE`` computes the minimum or maximum angle between edges of an element as compared to optimal angles. The optimal solid angle for tetrahedra and triangles is 60 degrees; for hexahedra and quadrilaterals, it is 90 degrees. This error metric is 1.0 for an element in which all angles are optimal. Severely distorted or twisted elements have values of this metric near 0.0, and it is negative for inverted elements. This metric is 0 for degenerate elements. The ``SOLID ANGLE`` metric functions with hexahedron, tetrahedron, triangle, and quadrilateral elements. Note that 10-node tetrahedral elements compute the solid angle using only the four  vertices, so highly distorted mid-side nodes will not be represented with the solid_angle distortion metric.

- ``PERIMETER_RATIO`` measures the ratio of the deformed perimeter of an element to the undeformed perimeter of the element. This metric initially has a value of 1.0, and assumes values either greater than or lower than 1 as the mesh deforms. The ``PERIMETER_RATIO`` metric only works with triangle and quad elements.

- ``DIAGONAL_RATIO`` measures the ratio of the deformed maximum diagonal of an element to the undeformed maximum diagonal of the element. This metric initially has a value of 1.0, and assumes values either greater than or lower than 1 as the mesh deforms. The ``DIAGONAL_RATIO`` metric only works with hex and quad elements.

The results from any of these distortion metrics can be requested by specifying an ``ELEMENT VARIABLES`` command line (:numref:`output-variables`) in the ``RESULTS OUTPUT`` command block (:numref:`output-results-exodus`) for each metric for which the results are of interest. For example, to request the ``ASPECT_RATIO`` metric to be output as an element variable named ``aspect`` in the results output file, the following syntax can be included in a ``RESULTS OUTPUT`` command block:

.. code-block:: sierrainput

   ELEMENT ASPECT_RATIO as aspect

The distortion metrics can also be used for element death (:numref:`elements-death`). For example, to kill all elements in which the value of the ``SOLID_ANGLE`` metric is less than 0.2, the following line can be used in an ``ELEMENT DEATH`` command block:

.. code-block:: sierrainput

   CRITERION IS ELEMENT VALUE OF SOLID_ANGLE < 0.2

For more information about the use of element variables for element death, see :numref:`elements-death-criterion-element`.

