Skip to content

IBM: opt-in friction slip regularisation for soft-sphere collisions - #2354

Open
sbryngelson wants to merge 4 commits into
MFlowCode:masterfrom
sbryngelson:ib-friction-slip-eps
Open

sbryngelson wants to merge 4 commits into
MFlowCode:masterfrom
sbryngelson:ib-friction-slip-eps

Conversation

@sbryngelson

@sbryngelson sbryngelson commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Contribution Policy

All contributions are expected to demonstrate:

  • A clear understanding of the codebase
  • Alignment with product direction
  • Thoughtful reasoning behind changes
  • Evidence of real-world usage or hands-on experience with the problem

If these expectations are not met, we would prefer to implement the changes ourselves rather than spend time reviewing low-effort submissions.

Summary

The soft-sphere collision friction direction is the normalised slip velocity, guarded by f_approx_equal(norm2(v_t), 0), which is an exact-zero test. For a head-on contact the true slip is zero, so a round-off slip (1e-17) becomes a unit vector and the friction force is a full mu*|F_n| in an arbitrary direction. Two consequences:

  1. The tangential force flips sign every few steps (chatter), with magnitude mu*|F_n|, on a contact that should have no friction.
  2. Which direction is chosen depends on round-off, hence on the rank layout and on which body is pid1, so a contact split across an MPI seam differs from the 1-rank result.

This PR adds an opt-in ib_friction_slip_eps (velocity, default 0). With eps > 0 the friction force is -mu*|F_n| v_t / max(|v_t|, eps_eff) with eps_eff = max(eps, mu*|F_n|*dt/m_t), applied at both the body-body and the wall site through one shared routine (s_ib_friction_direction). For |v_t| >= eps_eff it is the present Coulomb force; below it, it ramps linearly to zero. The floor mu*|F_n|*dt/m_t (m_t = effective tangential mass of the contact from mass, moment, radius) is the stick limit: below it the ramp equals m_t |v_t|/dt, which cannot overshoot, so a too-small eps is raised to the floor instead of making the contact chatter. eps = 0 runs the previous code path unchanged (floor not applied, existing exact-zero guard). The routine reads dt and the body properties it already had access to, so no new arguments were needed. New parameter: definitions, descriptions, validator (>= 0, > 0 needs collision_model > 0), default, GPU declaration and update, case.md table row and paragraph. Guidance in the docs: about 1e-3 to 1e-2 of the impact speed; in single precision it must stay well above the velocity round-off.

Evidence

Machine: one CPU core per rank, MPI CPU build, double precision, base 4cadc3610 (rebased onto current master afterwards, not rebuilt). Case: two circles (diameter 1, mass 1) closing head-on at 0.3 each in still gas, periodic 20x20 box, 80x80 cells, mu = 0.1, centres on either side of the x = 10 rank seam (the pair that differed in a scaling study). Compared D/ib_forces.dat for 1 vs 2 ranks.

1 rank vs 2 ranks
ib_friction_slip_eps = 0 y force has opposite sign from step 80 on (+0.064 vs -0.066, difference 0.13); tangential force alternates sign
ib_friction_slip_eps = 0.003 friction-induced difference gone; y force stays about 1e-4 on both

Chatter (1 rank, a separate oblique head-on pair, not in the test): at eps = 0 the tangential force is 1.000 x mu*|F_n| at every step of the contact (up to 45 of a 150 normal force) and alternates in sign; with eps = 0.005 it is below 0.03.

Remaining difference, not fixed here: a single-step transient in the x force of body 2 at step 46 (0.056 between 1 and 2 ranks, 0.0275 vs 0.0835). It is identical with friction off (mu = 0: 0.0560), so it is not the friction direction. Outside that step the 1-rank/2-rank difference is at most about 5e-3. A larger earlier study reported a 2.6e-4 residual with friction off; its cause is not explained.

Tests

  • New 2-rank test IBM -> Collision -> Friction slip regularisation across a rank seam (the case above, eps = 0.003; 1 and 2 fluid variants), golden generated from the fixed build and rerun clean; override_tol = 3e-4: the golden was made with Cray Fortran on one host; the GNU, Intel and macOS CI lanes agree with each other to 1e-13 and differ from it by up to 3.2e-5 (1 fluid) and 9.1e-6 (2 fluids), absolute, in the energy, so the tolerance is about 10x that. It is still far below the O(0.1) force sign flip the case guards. The test is sensitive at the contact step. The golden is checked against itself at 2 ranks; the 1-rank/2-rank comparison above is by hand and is not in CI.
  • Single-precision (--single) build: the new test passes against the double golden.
  • Default eps = 0 leaves existing results unchanged: ./mfc.sh test --only IBM plus the mibm_sphere_head_on_collision and mibm_particle_cloud examples: 114 passed, 0 failed, no golden changed (chemistry cases excluded).

Limitations

  • Not run: A100, MI250X/MI300A GPU, GPU suite (CPU only here; the routine follows the existing GPU_ROUTINE(seq) pattern with scalar/array arguments like s_cross_product).
  • 4-rank seam case not in CI (at most 2 ranks); not re-run here.
  • Evidence is on head-on, near-zero-slip contacts, the worst case. Oblique collisions with real slip are unchanged above eps_eff. The change targets resting/sticking contacts and reproducibility.
  • The wall site shares the routine but has no dedicated test in this PR.
  • The unexplained seam transient (step 46) and the 2.6e-4 friction-off residual remain.

This PR was made with Claude Code (AI).

@sbryngelson sbryngelson added the ci:phoenix Run the Phoenix (NVHPC GPU) jobs on this PR; push after adding label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Claude Code Review

Head SHA: c860387

Files changed:

  • 8
  • docs/documentation/case.md
  • src/simulation/m_collisions.fpp
  • src/simulation/m_global_parameters.fpp
  • toolchain/mfc/case_validator.py
  • toolchain/mfc/params/definitions.py
  • toolchain/mfc/params/descriptions.py
  • toolchain/mfc/params/generators/fortran_gen.py
  • toolchain/mfc/test/cases.py

Findings:
No issues found. Checked m_collisions.fpp, m_global_parameters.fpp, descriptions.py and fortran_gen.py against their surrounding code. The new helpers divide by patch%mass only where the existing collision code already does, and the default of 0 keeps the old behaviour.

@github-actions

Copy link
Copy Markdown

Lines of Code

File Lines Diff
src/simulation/m_collisions.fpp 332 +19
src/simulation/m_global_parameters.fpp 962 +1
Directory Lines Diff
simulation 40906 +20
total 60970 +20

@sbryngelson

Copy link
Copy Markdown
Member Author

Hand test of c860387 (rebased on current master, double precision, MPI CPU build, Cray Fortran 19, one CPU core per rank).

  • ./mfc.sh test --only D8BC2E49 474D6E2B (the two new tests, 2 ranks): 2 passed. Before the rebase, --only IBM plus the mibm_sphere_head_on_collision and mibm_particle_cloud examples: 114 passed, 0 failed, no golden changed (chemistry cases excluded; default ib_friction_slip_eps = 0).
  • 1 vs 2 ranks, D/ib_forces.dat, same case: with ib_friction_slip_eps = 0 the y force has opposite sign on 1 and 2 ranks from step 80 (+0.064 vs -0.066); with 0.003 that difference is gone (both about 1e-4).
  • Golden is from Cray Fortran. The GNU, Intel and macOS CI lanes agree with each other to 1e-13 and differ from it by up to 3.2e-5 (1 fluid) and 9.1e-6 (2 fluids), absolute, in the energy, so override_tol is 3e-4.
  • A single-precision build on the pre-rebase tree passed the 1-fluid test against the double golden; the single-precision CI lane passed.

Not covered: GPU runs (A100, MI250X, MI300A), a 4-rank seam case, a dedicated wall-site test, and the one-step x-force transient of body 2 at step 46 (0.056 between 1 and 2 ranks, identical with friction off), whose cause is unexplained.

@sbryngelson
sbryngelson marked this pull request as ready for review November 21, 2026 00:28
@sbryngelson
sbryngelson requested a review from a team as a code owner November 21, 2026 00:28
@sbryngelson
sbryngelson requested review from danieljvickers and removed request for a team November 21, 2026 00:28
@codecov

codecov Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 64.28571% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.86%. Comparing base (aae503e) to head (d8a43d3).
⚠️ Report is 12 commits behind head on master.

Files with missing lines Patch % Lines
src/simulation/m_collisions.fpp 61.53% 3 Missing and 2 partials ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master    #2354      +/-   ##
==========================================
+ Coverage   65.75%   65.86%   +0.11%     
==========================================
  Files         111      111              
  Lines       30480    30559      +79     
  Branches     4663     4673      +10     
==========================================
+ Hits        20041    20128      +87     
+ Misses       6687     6655      -32     
- Partials     3752     3776      +24     

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

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@sbryngelson

Copy link
Copy Markdown
Member Author

Added a 1-rank wall-site test on d8a43d3: IBM -> Collision -> Friction slip regularisation at a wall (1 and 2 fluids; circle pressed into a slip wall at 0.1 with a 1e-4 slide, mu = 0.3, ib_friction_slip_eps = 3e-4, override_tol = 3e-4, golden from Cray Fortran on one CPU core). The two seam tests still pass unchanged.

Hand run of the wall case (1 rank, CPU, Cray Fortran), D/ib_forces.dat:

tangential force sign flips (steps 2-40) max abs slide velocity after step 30 tangential force
ib_friction_slip_eps = 0 37 of 38 9.2e-3 0.25 to 0.43 (`mu*
ib_friction_slip_eps = 3e-4 3 1.7e-5 below 1e-3

Not covered: GPU runs of the wall test, other compilers' spread for it (CI lanes will show it).

@sbryngelson

Copy link
Copy Markdown
Member Author

Re-verified after merging master (merge commit 32086fb, which brings in #2201, the collision optimisation): the friction routine's two call sites in m_collisions.fpp are intact in the restructured loops (tangential vector, |F_n| and the mass floor are still computed per pair as the routine expects; pair order and the contact-point ownership test are unchanged).

Cray Fortran, MPI CPU build, one CPU core per rank: ./mfc.sh test --only IBM plus the mibm_sphere_head_on_collision and mibm_particle_cloud examples: 121 passed, 0 failed, no golden changed, including the four friction tests (seam and wall, 1 and 2 fluids) and master's wall-collision tests (chemistry cases excluded).

One more finding on the seam test: listing the two bodies in the opposite order in a 1-rank run gives a bitwise identical result, so the 1-vs-2-rank difference on CPU is not caused by which body's patch is applied last in overlapped cells.

Not covered: Frontier and other GPU runs of this tree (not run), a 4-rank seam case, and the one-step x-force transient at step 46 on the seam test (unexplained, identical with friction off).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:phoenix Run the Phoenix (NVHPC GPU) jobs on this PR; push after adding

Development

Successfully merging this pull request may close these issues.

1 participant