Skip to content

Draft: Feature/processjac histograms

Jingtian Zhou requested to merge feature/ProcessJac_Histograms into master

Issue/feature addressed

This improvement links to Issue #19. A new feature which shows the histogram of Jacobian is added.

Proposed solution

A new option called histo is introduced, which can output the Jacobian information of each element into a text file. The user can then use a python script to show the Jacobians in a histogram.

Another function called quality is also added in ProcessJac, which is able to show the distribution of Jacobians on the screen. This helps the user to check the quality of the mesh based on the Jacobians of elements.


  1. The user can now use the following command to output a text file with Jacobian information:

    NekMesh -m jac:histo=num inputfile.xml outputfile.xml

In order to get the histogram and other information of each element, we output some information including 1. Element ID 2. Jacobian value 3. Type of element. If this element is a boundary element, the boundary edge (for 2D) or face (for 3D) ID, and the coordinates of boundary vertex, and the ID of the element which connected to this boundary element will also be outputted.

The “num” in the command line should be a number below 1.0, and only the information of elements whose jacobian is smaller than “num” will be outputted. By default, num = 1.0

  1. In order to make it easier for the user to locate the low Jacobian element, there is another option which can output the boundary composite ID and name:

    NekMesh -m jac:histo:detail inputfile.xml outputfile.xml

When dealing with a large 3D mesh, locating Composite ID will take a lot of time, and therefore we set this to a new option. When both “histo” and “detail” are set in the command, the boundary composite ID and name will also be outputted into the text file.

  1. In order to get the quality of the mesh. We output a rough histogram on the screen. In a scale from 0.0 to 1.0, with a interval equal to 0.1, the number of elements whose Jacobian is in the scale is shown.

    NekMesh -m jac:quality inputfile.xml outputfile.xml

  2. When using quality, a value for the integration of all Jacobians is calculated to give a single number quality matrix which can be used for a rough assesment of the overall mesh quality. The integral is calculated by \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} The denominator is the Area/Volume of the mesh. The integral of each element is the Area/Volume * (scaled Jacobian). For an ideal mesh, scaled Jacobian will reach 1 and the ratio should be 1


1. 2D half circle test

(1) Below is the result with the command: “NekMesh -m jac:histo”.


In the text file named “jac.txt”, the first three columns are “Element ID”, “Jacobian value” and “Element type”. If the element is not a boundary element, these will be the only information outputted in the file.

If the element is connected to boundary, the boundary edge ID will be shown in Column 4. Each edge corresponds to two boundary vertex, whose ID and coordinates are shown in column 5 to 7.

The last column is the ID of elements which connected to this boundary edge.

There is a line of "===" below each boundary elements as there are too much information in each line, in order to help the user to focus on the information in a single line.

(2) Below is the result with the command: “NekMesh -m jac:histo=0.9”. It is seen that only elements with Jacobian < 0.9 are outputted in the text file.


(3) Below is the result with the command: “NekMesh -m jac:histo:detail”.

The boundary composite ID and name of the boundary element are also shown. As this test mesh has no composite name, the composite name column is empty.


(4) Below is the result with the following command: “NekMesh -m jac:quality”

The histogram shows the distribution of the Jacobian of the mesh and the percentage in each interval is also listed. The last line shows the lowest Jacobian value of the mesh.


  1. 3D half sphere test

Below is the result with the command: “NekMesh -m jac:histo”. In 3D test, boundary face ID and its boundary edge ID will be presented.


Below is the result with “NekMesh -m jac:histo=0.9”. Also, only the elements with Jacobian less than 0.9 are outputted.


Below is the result with “NekMesh -m jac:histo:detail”. The Composite ID and name are also listed.


Next is the result with “NekMesh -m jac:quality” and the distribution of Jacobians.



With the result from "NekMesh -m jac:histo", we can also get the histogram using a python script like the following picture:


Suggested reviewers

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


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


  • 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).
Edited by Mashy Green

Merge request reports