New feature for ProcessJac in NekMesh. Output Jacobian information on the screen and into the log file

Issue/feature addressed

Histogram now can be plotted internally in ProcessJac of NekMesh. The Jacobian information, element IDs, connected boundary surface/edge IDs, coordinates of vertex are outputted into a text file

Proposed solution

A new option called "histo" is available to the user, which takes three value: The maximum value of Jacobian to be plotted, the number of positive bins in the histogram, the number of negative bins in the histogram. The Jacobians below the threshold will be counted and a histogram will be plotted on the screen. This helps the user to check the quality of the mesh visually. The Jacobian information, element IDs, boundary surface/edge IDs, vertex coordinates, neighbor element IDs will also be outputted into a text file. The text file can also be further used to create a histogram picture by a python script.

Another option called "quality" is introduced, which will show the distribution of Jacobians on the screen including the percentage of each bin of on-screen histogram. This helps the user to check the quality of the mesh in detail.

Implementation

The users can now use the following command to plot a histogram of Jacobian on the screen and output a text file with Jacobian information:

The x-axis of the histogram is the Jaobian, and the y-axis of the histogram is the number of elements. Option "histo" takes three values, separated by a comma. "value1" defines the maximum value of the Jacobian shown on the histogram. In other words, only elements with Jacobian below "value1" will be counted and will be shown on the histogram and will be outputted to a text file. "value2" is the number of bins with positive Jacobian values on the histogram. "value3" is the number of bins with negative Jacobian values on the histogram. The width of each bin is determined by "value1" and "value2": "value1/value2". The maximum value of the histogram is "value1", while the minimum value of the histogram is: "(value1/value2)*value3". It should be noted that the elements with Jacobian smaller than the minimum value will also be counted and be classified into the left-most bin. By default, the three values are 1,10,1. This means that the default histogram shows the Jacobian between 0.0 and 1.0, with a interval 0.1, and all the other elements with a Jacobian smaller than 1 will be counted and shown on the left-most bin with a name "invalid".

"histofile" is an option to set the name of the outputted file with jacobian information. By default, the name of the text file with Jacobian and other elemental information is "jacs.txt"

"detail" is another option which will also calculate the composite name and ID of each element in the outputted text file. This process takes long time when the mesh is big and not all the user need this information. And therefore this function is added using another tag.

Note that the output.xml is now updated, only the elements with Jacobian smaller than the threshold "value1" will be outputted. This will further help the user to find the elements with a bad quality.

The users can now use the following command to show the distribution of jacobians on the screen:

This function will list the distribution of the jacobian in the histogram, including the percentage of each bin. This can be regarded as the text description of the histogram, and therefore, the results of "quality" will correspond to the histogram. If "histo" is not set by user, the "quality" will follow the default value of "histo" and show the distribution between 0.0 and 1.0 with an interval 0.1.

"quality" also calculate the integration of Jacobians using the following equation:

\frac{\sum_{i=1}^{N}\sum_{j=1}^{Q_i}w_jJ_j*J_{Scaled_i}}{\sum_{i=1}^{N}\sum_{j=1}^{Q_i}w_jJ_j}

N is the number of elements of the mesh and Q_i is the number of quadrature points in each element, \omega_j is the weight function and J_j is the Jacobian of the mapping from reference space to the physical space. The denominator is the area(volume) of the mesh. The J_{scaled} is the scaled Jacobian of each element, calculated by the ratio between the minimum Jacobian of all the quadrature points and the maximum Jacobian of all quadrature points. The J_{scaled} is a variable below 1.0, and will be smaller than zero when tangled, and all the Jacobians on the histogram and the outputted file are also calculated this way. The more J_{scaled} is closer to 1.0, the better the mesh quality is. Therefore the above ratio is a value between 0.0% and 100% which evaluate the quality of the mesh.

Tests

1. 2D half circle test

The default results of this module is tested first, using the following command:

The results on the terminal screen are shown in the following picture, which is the default setting of option "histo" and "quality".It is seen that the histogram is shown on the screen, with a default scale between (0.0, 1.0). The elements with negative Jacobians are classified into one bin named as invalid. The information below the histogram is the results of quality, which is a text description of the histogram. It shows the percentage of each bin. At the end of the module, the Worst Jacobian is shown and the integration of the Jacobian over the whole mesh is calculated.

Below is the outputted Jacobian information file. The first three columns are ID of elements, Jacobian value of each element, element type. If this element is connected to a boundary, the boundary edge(face for 3D) ID will also be shown, following which is the vertex IDs and coordinates of each edge. When we have a bad element with a small Jacobian, these info can help the user to find the location of this element and find the edge and vertex IDs easily. As we set the "detail" option, the composite ID and name are also shown. The last column is the Id of the neighbor elements of each element. The information of each element is divided by "===" symbols for readability. As we set "histofile" to "output.txt", the name of the text file is modified instead of the default one.

*Another case with the same mesh using different "histo" values are also tested. The command we use is listed below. *

The maximum Jacobian we evaluated is set to 0.2, and the number of positive bins are 3, and the number of negative bins are 2. The screenshot is listed below. It is seen that only elements with a Jacobian below 0.2 is counted. There are 3 positive bins and 2 negative bins. The width of each bin is (0.2/3). The results of quality match that of the histogram.

The output file of this command is also listed. Only the elements with Jacobian lower than 0.2 are outputted, which match the "histo" setting.

2. 3D half sphere test

The default results using the following command are as follows:

The screenshot is listed below. The results of 3D are similar to that of 2D half circle, and are not described in detail here.

The output file is listed below. It can be seen that for 3D meshes, one more column with "boundary face ID" is added, for a tetrahedral element, the boundary face is a triangle and has three boundary edges, the boundary edge IDs and the vertex coordinates of them are also shown. In this case the composite name of the mesh is not set during generation, and is shown as NONE instead.

Another case with the same mesh using different "histo" values are also tested. The command we use is listed below.

The results on the screen are below. The histogram is separated with 3 positive bins and 2 negative bins. It is seen that we only have 2 elements which has a Jacobian below 0.5. The results of quality also match the histogram.

The output file is shown below. There are only two elements outputted and one of them is connected to a boundary and the boundary surface , edge, and vertex info are also outputted.

Suggested reviewers

Please suggest any people who would be appropriate to review your code.

Notes

Please add any other information that could be useful for reviewers.

Checklist

• Functions and classes, or changes to them, are documented.
• User guide/documentation is updated.
• Changelog is updated.
• Suitable tests added for new functionality.
• Contributed code is correctly formatted. (See the contributing guidelines).
• License added to any new files.
• No extraneous files have been added (e.g. compiler output or test data files).