Add hemisphere shell particle cloud packing

[BCKim55]

Description

Adds a hemisphere-shell particle cloud packing option for immersed-boundary particle clouds.

This introduces particle_cloud(i)%packing_method = 3, which randomly places spherical/circular IBM particles inside a hemisphere-shell region while enforcing:

• inner and outer shell-radius clearance,
• hemisphere plane clearance,
• bounding-box clearance,
• particle-particle non-overlap using the existing spatial hash approach.

This also adds shell_inner_radius and shell_outer_radius particle cloud parameters. The local verification example was removed from this PR to avoid introducing a new golden test in the same change.

Type of change

• New feature

Testing

• ./mfc.sh format
• ./mfc.sh validate examples/*/case.py
• ./mfc.sh validate examples/3D_mibm_particle_cloud_hemi_shell/case.py
• ./mfc.sh run examples/3D_mibm_particle_cloud_hemi_shell/case.py --clean --no-debug

Additional local checks:

• Verified generated ib_state_0.dat particle positions.
• Confirmed no shell-boundary violations.
• Confirmed no particle overlap violations.
• Confirmed VF 0.2 succeeds with min_spacing=0.02.
• Confirmed VF 0.3 succeeds when min_spacing=0.0.

Checklist

• I added or updated tests for new behavior
• I updated documentation if user-facing behavior changed

GPU changes (expand if you modified src/simulation/)

• GPU results match CPU results
• Tested on NVIDIA GPU or AMD GPU

[wilfonba]

I don't think this is implemented quite right. The example you added highlights this fact. It defines a hemispherical particle cloud using a cubic domain. I think instead you should add a particle_cloud(i)%geometry variable, and then treat the particle cloud more like the fluid patches are treated. Also, a hemispherical shell is not a packing method in the same way that rejection sampling and lattice placement are packing methods, so using the existing acking_method variable for this isn't the right thing to do. You can place particles in a hemispherical shell using either rejection sampling, lattice placement, or some other packing method that's not implemented yet.

Edit: Your s_particle_cloud_random_hemi_shell routine appears to do rejection sampling, which adds to the confusion of what packing_method means.

[BCKim55]

Thanks Ben, that makes sense. I agree that the hemisphere shell should be treated as a particle-cloud geometry rather than a packing method.

I’ll refactor this so that particle_cloud(i)%packing_method remains responsible for the placement algorithm, e.g. rejection sampling or lattice, and add a separate particle_cloud(i)%geometry option for the cloud shape. Then the current hemisphere-shell implementation will become the rejection-sampling path for geometry = hemisphere shell, while unsupported combinations such as hemisphere-shell lattice packing can error out explicitly for now.

I’ll also remove or adjust the example so it does not imply that a cubic domain defines the hemispherical cloud.

[danieljvickers]

Forgive me if this seems dense, but do you not already have the size on this? You have zmin, zmax, xmin, ..., , which gives you some hypothetical upper size of the shell, but then you also have radii. It seems like redundant information. You either use the radii and ignore the [xyz][min/max] or use the shape size and ignore the outer radii. Seems like wasted lines of code otherwise.

[danieljvickers]

num_dims < 3 peferred in general. This likely does not affect things, but num_dims is a case-optimization parameter, and therefore the compiler can optimize this away if you make it a check on num_dims.

[danieljvickers]

This seems like a lot fo compute for your QOI. You do not use the [xyz]dir parameter at all after computing it. Again, either use it or do not computed.

[danieljvickers]

That said, you using a probability distribution function to weight your random seed is correct here. Just you are computing redundant quantities here that seem pointless.