Add user guide entry and update CHANGELOG

CHANGELOG.md

@@ -41,6 +41,7 @@ v4.4.0
 
 **FieldConvert:**
 - Allow equi-spaced output for 1D and 2DH1D fields (!613)
+- Update quality metric to include scaled Jacobian output (!695)
 
 **NekMesh:**
 - Modify curve module to allow for spline input (!628)

docs/refs.bib

@@ -427,3 +427,17 @@ year={2011}
   volume = {33},
   year = {2000}
 }
+
+@article{GaRoPeSa15,
+  title        = {Distortion and quality measures for validating and generating
+                  high-order tetrahedral meshes},
+  author       = {Gargallo-Peir{\'o}, Abel and Roca, Xevi and Peraire, Jaime and
+                  Sarrate, Josep},
+  journal      = {Engineering with Computers},
+  volume       = 31,
+  number       = 3,
+  pages        = {423--437},
+  year         = 2015,
+  publisher    = {Springer London}
+}
+

docs/user-guide/utilities/fieldconvert.tex

@@ -122,6 +122,7 @@ possibly also Reynolds stresses) into single file;
 \item \inltt{interppoints}: Interpolates a set of points to another, requires fromfld and fromxml to be defined, a line or plane of points can be defined;
 \item \inltt{isocontour}: Extract an isocontour of ``fieldid'' variable and at value ``fieldvalue''. Optionally ``fieldstr'' can be specified for a string defiition or ``smooth'' for smoothing;
 \item \inltt{jacobianenergy}: Shows high frequency energy of Jacobian;
+\item \inltt{qualitymetric}: Evaluate a quality metric of the underlying mesh to show mesh quality;
 \item \inltt{meanmode}: Extract mean mode (plane zero) of 3DH1D expansions;
 \item \inltt{pointdatatofld}: Given discrete data at quadrature points
   project them onto an expansion basis and output fld file; 
@@ -629,6 +630,38 @@ The output file \inltt{jacenergy.fld} can be processed in a similar
 way as described in section \ref{s:utilities:fieldconvert:sub:convert}
 to visualise the result either in Tecplot, Paraview or VisIt. 
 
+\subsection{Calculate mesh quality: \textit{qualitymetric} module}
+
+The \inltt{qualitymetric} module assesses the quality of the mesh by calculating
+a per-element quality metric and adding an additional field to any resulting
+output. This does not require any field input, therefore an example usage looks
+like
+
+\begin{lstlisting}[style=BashInputStyle]
+FieldConvert -m qualitymetric mesh.xml mesh-with-quality.dat
+\end{lstlisting}
+
+Two quality metrics are implemented that produce scalar fields $Q$:
+
+\begin{itemize}
+  \item By default a metric outlined in~\cite{GaRoPeSa15} is produced, where all
+  straight sided elements have quality $Q = 1$ and $Q < 1$ shows the deformation
+  between the curved element and the straight-sided element. If $Q = 0$ then the
+  element is invalid. Note that $Q$ varies over the volume of the element but is
+  not guaranteed to be continuous between elements.
+  \item Alternatively, if the \inlsh{scaled} option is passed through to the
+  module, then the scaled Jacobian
+  \[
+    J_s =
+    \frac{\min_{\xi\in\Omega_{\text{st}}}J(\xi)}{\max_{\xi\in\Omega_{\text{st}}}J(\xi)}
+  \]
+  (i.e. the ratio of the minimum to maximum Jacobian of each element) is
+  calculated. Again $Q = 1$ denotes an ideal element, but now invalid elements
+  are shown by $Q < 0$. Any elements with $Q$ near zero are determined to be low
+  quality.
+\end{itemize}
+
+
 %
 %
 %