Implement EGS_Mesh geometry for simulation inside CAD models

[mxxo]

This PR supersedes #556, #637, and #647.

This is a PR to integrate egs_mesh into the develop branch of Release 2022. The library should be considered a beta version, with the potential for latent bugs and implementation issues. The egs_mesh library has been completely rewritten from scratch by me from the initial Mevex implementation (#556). In particular, the use of volume and surface octrees in this implementation means this new version of egs_mesh is much better able to simulate large million-element meshes.

This version of egs_mesh has been mostly stable for about four months. It can simulate large and complex meshes such as the ICRP 145 adult human mesh reference phantoms, and preliminary testing have concluded that it has obtained similar results to Geant4 for these phantoms. Preliminary measurements suggest the performance of egs_mesh is competitive with the other transport codes that are capable of simulating tetrahedral meshes (Geant4, MCNP6, PHITS).

There is some basic user documentation here: https://mxxo.github.io/egs_mesh/docs/ (with more planned, including a STEP file simulation guide).

Currently, the two supported mesh input files are Gmsh msh4.1 and TetGen node and ele pairs.

There are some basic unit tests that can be run by:

cd $HEN_HOUSE/egs++/geometry/egs_mesh && make test_egs_mesh && ./test_egs_mesh

The expected output is that all 37 tests pass:

test test_howfar_interior_regular(two_elt_mesh)... ok
test test_howfar_interior_outside_thick_plane(two_elt_mesh)... ok
test test_howfar_interior_lost_particle(two_elt_mesh)... ok
test test_howfar_interior_tolerance(two_elt_mesh)... ok
test test_howfar_interior_reentry()... ok
test test_howfar_interior_boundary_straddle()... ok
test test_howfar_interior_stuck_on_boundary()... ok
test test_howfar_interior_thick_plane_negative_intersection()... ok
test test_unknown_node()... ok
test test_isWhere()... ok
test test_medium()... ok
test test_boundary()... ok
test test_neighbours()... ok
test test_hownear_interior()... ok
test test_hownear_exterior()... ok
test test_howfar_interior_basic()... ok
test test_howfar_exterior()... ok
test test_mesh_scaling()... ok
test test_mesh_scale_key_errors()... ok
test test_tetrahedron_face_eq()... ok
test test_tetrahedron_errors()... ok
test test_tetrahedron_neighbours()... ok
test test_parse_msh_version()... ok
test test_parse_msh41_groups()... ok
test test_parse_msh41_node_bloc()... ok
test test_parse_msh41_nodes()... ok
test test_parse_msh41_entities()... ok
test test_parse_msh41_element_bloc()... ok
test test_parse_msh41_elements()... ok
test test_parse_msh41_file_errors(mesh_file)... ok
test test_parse_msh41_file(mesh_file)... ok
test test_parse_tetgen_nodes()... ok
test test_parse_tetgen_elements()... ok
test test_tetgen_elt_media()... ok
test test_parse_tetgen_file_errors()... ok
test test_parse_tetgen_file()... ok
test test_unknown_mesh_file_extension()... ok

test result: 37 out of 37 tests passed

[mxxo]

This is ready for review and edits. There is a fairly convoluted commit history, and I would say squashing everything might be the easiest way to integrate it. I tried to comment as best I could, and I think where history will become more valuable is tracking changes to this initial version.

[ftessier]

This is ready for review and edits. There is a fairly convoluted commit history, and I would say squashing everything might be the easiest way to integrate it. I tried to comment as best I could, and I think where history will become more valuable is tracking changes to this initial version.

Understood. I will take a peek at the commit history and perhaps keep a few key waypoints, but otherwise will squash away!

[ftessier]

@mxxo I am building a cleaned up version of this branch, so please do not force-push anything here for the moment. I am keeping a lot of the commits (only squashing some smaller and related ones), because the log messages you wrote are really insightful and valuable for anyone working on egs_mesh in the future! 🙏🏻

[ftessier]

Trimmed down to 89 commits, keeping all the insighful development comments provided by @mxxo. Reorganized commits, adjusted commit titles and messages, squashed together some smaller related commits. Null diff when compared to the previous pull request point (commit 51831ea5), so no code change at this point.

One squash inadvertenly attributed a commit to me (7639706), but all these commits are authored by @mxxo. I am only cleaning up the branch!

[ftessier]

This is safe to merge, since apart from entering egs_mesh in the top-level Makefile and Doxyfile, and an new method in egs_genvelope, all changes are restricted to new directories for the geometry and for the application.

[ftessier]

Applied astyle to egs_mesh .cpp and .h files.

[ftessier]

Applied astyle version 3.1, minor tweaks.

[ftessier]

@mxxo I attempted to capture what you add noted in the pull request message #556, regarding the historical account of EGS_Mesh development. Is that fine by you? In particular I don't know the nature of contributions by Pascal Micheau, so not sure if he is to be listed under Contributors or simply acknowledged. At any rate, adjust as you see fit!

[ftessier]

For the record and perfect clarity, here is the permission from the publisher for the implementation of closest_point_triangle and closest_point_tetrahedron, as mentioned in the file headers:

from: Permissions Mailbox date: 24 Mar 2020, 12:50 subject: RE: Source code reproduction permission

I reached out to the editor of this book and here’s what he had to say…

There does not seem to be a copyright issue. I applaud this requestor’s overly-cautious approach to and respect for copyright protection but he is not asking to reproduce the text, rather he wants to implement ideas generated from the algorithms presented, which in and of themselves are not patented nor subject to copyright, as I see it. My response would be to let him know he does not need permission for the type of use described.

So, you’re fine to proceed with your project.

Kind Regards, Diana Taylor Permissions Coordinator | US Books Permissions Department

[mxxo]

Hi @ftessier, everything looks great, thank you for that!

[ftessier]

Adjusted the authorship in Makefiles, which according to other egs++ files follows the authorship of the associated code.

[ftessier]

Adjusted authorsip again in mevegs Makefile. In the case of apps, it appears that the usage is to preserve the original author. Anyways, cosmetic changes only.