IBM+STL

[haochey]

Description

This PR enables complex geometry (in STL format) in immersed boundary method. Also, analytical levelset for cuboid is added.

For 2D STL files, boundary vertices are grouped to determine the levelset and levelset normals. For 3D STL files, all the vertices are boundary vertices so the procedure to group boundary vertices are skipped.

Here is the procedure implemented:

1. Check and group boundary vertices.
   • 2D case: use an edge manifoldness algorithm to recursively check if an edge is shared by more than one triangle facets.
     If so the end vertices of the edge are considered inner vertices.
   • 3D case: skipped
2. Check if interpolation of the STL vertices is required.
   • 2D case: interpolation is required if the length of any boundary edge is longer than the cell width.
   • 3D case: interpolation is required if the length of any boundary edge is longer than the cell width or the area of any
     triangle facet is larger than the face area of the cell.
3. Interpolate the STL vertices
   • 2D case: add constant multiples of vertices along the boundary edges with even distribution.
   • 3D case: add constant multiples of vertices along the boundary edges with even distribution and triangle facets with
     random distribution based on barycentric coordinates.
4. If the STL file is interpolated, use the updated boundary vertex group and perform the following; otherwise, directly
   perform the following.
   • 2D case: use shortest pair algorithm to find the distance (levelset) between each cell center and the boundary of the
     model and the normals (levelset_norm) associated with the boundary edge.
   • 3D case: use shortest pair algorithm to find the distance (levelset) between each cell center and the boundary of the
     model and the normals (levelset_norm) associated with the triangle facets.
5. Correct the signs of the levelset and levelset_norm.
   • 2D case: negative if it's inside the immersed boundary, flip the normals if it's outside the immersed boundary.
   • 3D case: same as the 2D case.

Test suite adds two tests: 2D->IBM->STL and 3D->IBM->STL

Type of change

• New feature (non-breaking change which adds functionality)

Scope

• This PR comprises a set of related changes with a common goal

How Has This Been Tested?

Compared the 2D IBM (rectangles and circles) and 3D (cubes and spheres) between analytical method and STL+IBM method.

Test Configuration:

2D Comparison (Rectangles)
https://github.com/user-attachments/assets/6948d404-96ff-4219-8464-a768d1b3b530

3D Comparison (Cuboid)
https://github.com/user-attachments/assets/e852a124-3ce7-4e84-8e2c-a6c9f55fdae9

2D New Geo
https://github.com/user-attachments/assets/1e405a1a-9aff-40d2-8d99-dc2ea3a12df8

2D Subsonic flow over MFC Character
https://github.com/user-attachments/assets/f56b8df9-1035-43bf-ba87-b7fb03338aca

3D New Geo
https://github.com/user-attachments/assets/635ad04c-dcd1-470b-8311-d114f0593a66

Mach 1.5 over a Mexican pyramid
https://github.com/user-attachments/assets/88d7731d-e660-47aa-9c29-b866f34ea21d
X-Y section view
https://github.com/user-attachments/assets/719557a6-d45b-4638-9957-1f3bba1f1aa7

• What computers and compilers did you use to test this: MacOS/gcc, Phoenix-cpu/gcc, Phoenix-gpu/NVHPC

Checklist

• I have added comments for the new code
• I added Doxygen docstrings to the new code
• I have made corresponding changes to the documentation (docs/)
• I have added regression tests to the test suite so that people can verify in the future that the feature is behaving as expected
• I have added example cases in examples/ that demonstrate my new feature performing as expected.
  They run to completion and demonstrate "interesting physics"
• I ran ./mfc.sh format before committing my code
• New and existing tests pass locally with my changes, including with GPU capability enabled (both NVIDIA hardware with NVHPC compilers and AMD hardware with CRAY compilers) and disabled
• This PR does not introduce any repeated code (it follows the DRY principle)
• I cannot think of a way to condense this code and reduce any introduced additional line count

[codecov]

Codecov Report

Attention: Patch coverage is 33.57016% with 374 lines in your changes missing coverage. Please review.

Project coverage is 43.63%. Comparing base (cf249d3) to head (6efcdb3).
Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/pre_process/m_model.fpp	36.16%	156 Missing and 17 partials ⚠️
src/pre_process/m_patches.fpp	30.66%	78 Missing and 26 partials ⚠️
src/pre_process/m_compute_levelset.fpp	13.33%	76 Missing and 2 partials ⚠️
src/pre_process/m_initial_condition.fpp	40.00%	12 Missing ⚠️
src/pre_process/m_check_ib_patches.fpp	66.66%	4 Missing ⚠️
src/pre_process/m_check_patches.fpp	0.00%	2 Missing ⚠️
src/simulation/m_ibm.fpp	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #730      +/-   ##
==========================================
+ Coverage   42.97%   43.63%   +0.66%     
==========================================
  Files          61       61              
  Lines       16492    16893     +401     
  Branches     1890     1948      +58     
==========================================
+ Hits         7087     7372     +285     
- Misses       8356     8404      +48     
- Partials     1049     1117      +68     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[wilfonba]

I think there should be STL IBM cases added to the test suite, although I'm not sure how this would be done given the current test suite framework. As we've seen in your updates, even minor changes to any step in the process of generating the levelset can lead to significant differences in results. I'd also be interested in seeing a comparison for "exact" (I'm not sure it's actually exact) vs. STL level set with an airfoil, at least in 2D. Maybe something wild like a NACA 9510 to add some weird curvature. I'm not sure I'd expect the wakes to be the same, but some sort of integral quantity like lift or drag could be compared. I'll let @sbryngelson give his opinion on if this is worthwhile though.

[sbryngelson]

I think there should be STL IBM cases added to the test suite, although I'm not sure how this would be done given the current test suite framework. As we've seen in your updates, even minor changes to any step in the process of generating the levelset can lead to significant differences in results. I'd also be interested in seeing a comparison for "exact" (I'm not sure it's actually exact) vs. STL level set with an airfoil, at least in 2D. Maybe something wild like a NACA 9510 to add some weird curvature. I'm not sure I'd expect the wakes to be the same, but some sort of integral quantity like lift or drag could be compared. I'll let @sbryngelson give his opinion on if this is worthwhile though.

I agree, there needs to be something in the test suite for this.

[haochey]

Thanks for all the reviews. I've made the requested changes. It'll be great if it can get merged by the 1st MFC5.0 draft.

[sbryngelson]

Thanks for all the reviews. I've made the requested changes. It'll be great if it can get merged by the 1st MFC5.0 draft.

Great! I think I can merge, will have a final look today (or very soon). Thanks @haochey