Sub-grid bubble model

[dgvacarevelo]

Description

We have integrated a sub-grid bubble model designed to address the dynamics of a cloud of bubbles within a host medium. The model currently operates under the assumption that the bubbles' positions remain static. This model was implemented in an old MFC version, so we migrated and fully adapted it to work in the current version. The dynamics of these Lagrangian bubbles are influenced by the hydrodynamic field of the host medium, with the presence of bubbles altering the properties of the Eulerian host. Comprehensive details regarding the physical model, governing equations, and the Euler-Lagrangian coupling approach can be found in the work of Kazuki and Colonius (https://doi.org/10.1016/j.jcp.2018.05.029).

Type of change

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

Scope

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

If you cannot check the above box, please split your PR into multiple PRs that each have a common goal.

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.
Provide instructions so we can reproduce.
Please also list any relevant details for your test configuration

• Test A: Dynamics of a bubble cloud
  A monodisperse cloud of bubbles initially of 10 μm of diameter contained in a 5mm cubic space interacts with a single sinusoidal acoustic wave of 0.1 MPa of amplitude and 300 kPa of frequency. The time evolution of the pressure at the center of the cloud (0,0,0) was compared with figure 3a reported by Bryngelson et al. (https://doi.org/10.1016/j.ijmultiphaseflow.2019.03.028).

• Test B: Dynamics of an isolated bubble
  An isolated bubble of 50 μm of diameter interacts with a single sinusoidal wave of 0.2 MPa of amplitude and 150 kHz of frequency. The time evolution of the bubble radius is compared to the analytical solution of the Keller-Miksis equation, similar to what is reported in figure 3a by Kazuki and Colonius (https://doi.org/10.1016/j.jcp.2018.05.029).

Test Configuration:
Test A: This test was implemented as an example case in the “examples” directory. The case.py file contains all the bubble properties and flags required. The functionality and physical meaning of these additional variables are commented in the ‘~/simulation/m_global_parameters.fpp’ file. The geometrical parameters of the bubbles are specified in ‘inputs/particles.dat’; the information it contains is x-location, y-location, z-location, x-velocity, y-velocity, z-velocity, bubble radius and interface velocity. The total number of particles is the number of rows in the file. Please run the post_process target with one processor (-N 1 -n 1), which will generate the ‘particles_data’ folder that stores the information from the bubble dynamics evolution at every t_step_save. Then, run the ‘convert_particlesData.m’ MATLAB script to populate a data file compatible with MATLAB which can be used to visualize the radius evolution of each bubble.

Test B: The case.py file from test A will run this test after correctly modifying the acoustic source amplitude and frequency. All the parameters in inputs/particles.dat are required to be equal to zero, except for the bubble radius which will be equal to 0.05. The instructions described for test A are suggested to follow in order to obtain the radius evolution of the bubble.

• What computers and compilers did you use to test this:

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
• I ran ./mfc.sh format before committing my code
• New and existing tests pass locally with my changes, including with GPU capability enabled 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

If your code changes any code source files (anything in src/)

To make sure the code is performing as expected on GPU devices, I have:

• Checked that the code compiles using NVHPC compilers
• Ran the code on either V100, A100, or H100 GPUs and ensured the new feature performed as expected (the GPU results match the CPU results)
• Enclosed the new feature via nvtx ranges so that they can be identified in profiles
• Ran a Nsight Systems profile using ./mfc.sh run XXXX --gpu -t simulation --nsys, and have attached the output file (.nsys-rep) and plain text results to this PR
• Ran my code using various numbers of different GPUs (1, 2, and 8, for example) in parallel and made sure that the results scale similarly to what happens if you run without the new code/feature

[sbryngelson]

Converting this to draft as much of the checklist is still to be completed. Also there is significant code duplication in the source code (not DRY).