Skip to content

Initial exploration of contact: Kamensky potential, point sets, pair search, interface seam - #1

Draft
mattjolley wants to merge 1 commit into
mainfrom
contact-potential
Draft

mattjolley wants to merge 1 commit into
mainfrom
contact-potential

Conversation

@mattjolley

@mattjolley mattjolley commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

An initial exploration of contact for FEBio-Warp, built on the previous work: Kamensky's volume potential as Steve implemented it in FEBio, which has carried the lab's valve papers and the TPVR simulations, and an earlier design note and prototype, circulated to the group in October, that verified the pair kernel. It is opened as a draft so that it can be reviewed before anything builds on it. I am a clinician, not a numerical analyst; please read it as a starting point to be corrected or replaced, not a finished component. @SteveMaas1978, the FEBio semantics and the two questions below are yours to judge. @shi-eric, I would value a look at whether the Warp usage (HashGrid, graph capture, tape, warp.sparse) is idiomatic and where it is not. @ryanblack129, the operator and PhysicsTerm shape is meant to fit what your MFEM work expects; tell me where it does not.

What this adds

The volume-potential contact of Kamensky et al. (2018), as FEBio implements it in FEContactPotential, in the repository's layout:

  • contact/points.py: contact points interpolated from nodes, built from quad and tri facets (FEBio's default and higher-order rules, or a densifying lattice), 2-node segments (chordae, beam centerlines) and nodes; optional radius offset per point.
  • contact/search.py: float64 wp.HashGrid pair list, count-and-fill with a device scan, fixed-capacity buffer; exclusion by body, reference distance (R0_min), same element or shared node (exclude_neighbors), and w_tol; pair classes per body pair.
  • contact/potential.py: the FEBio force law with per-class parameters; energy, force, full and PSD-projected tangent action; device BSR assembly through warp.sparse; r_min guard; reference or current (FEBio) integration weights; Wu 2022 contact area and Zelonis 2026 contact fraction; from_febio_block to map a .feb contact block one to one.
  • contact/enforcement.py and contact/interface.py: the potential behind contracts.PhysicsTerm and a FEBio-style ContactInterface protocol, so sliding, sticky and tied laws can follow without touching the solver; energy_and_gradient as the entry point for PyTorch and JAX custom ops.
  • tests/test_contact_potential.py: 32 tests (force against finite differences of the energy and tangent action against finite differences of the force, in the blend region, in the stiff core and with radius offsets; tape gradient; parameter adjoint; exclusion rules; guards; pair classes; current weights; BSR against matrix-free; FEBio block translation; the check from FEBio's FEContactDiagnostic applied to the potential). 31 run on CPU; one CUDA graph-capture test runs only on a GPU.
  • examples/contact/point_spacing.py, docs/CONTACT.md, and a CPU GitHub Actions workflow.

What it does not do yet, and where it is not FEBio

  • Sliding-elastic with friction, sticky and tied contact: the interface is there, the laws are not.
  • No integration with a solver loop.
  • It has been run on CPU only. The kernels are written for CUDA and the tests take a device from WARP_FEBIO_TEST_DEVICE, but I have not had a GPU run of them yet; I would be grateful if someone with one could try.
  • w_tol and R0_min are applied per point pair here; FEBio applies them as element-pair activation gates. check_intersections is not implemented. A facet-level match with FEBio at w_tol > 0 should not be expected yet.
  • FP64 only.

Two things for FEBio review

Both are in docs/CONTACT.md. I may have read the source wrong on either; that is the point of asking.

  1. Pair multiplicity in self-contact. Reading FEContactPotential::Update and LoadVector/ElementForce, when one surface is both primary and secondary each pair appears to be activated from both sides and added to both elements, so self-contact enters twice relative to an unordered sum. PotentialParams(scale=2) reproduces that; the default is 1. Is the double count intended?
  2. How k_c should be specified across pair classes, since the stiffness at the core boundary scales as R_in^-5 at fixed k_c. The module offers per-point radius offsets as one way out; the question is left open.

Testing

python -m unittest discover -s tests on CPU with Warp 1.19.0: 40 tests, 38 pass, 2 skipped (GPU only). python examples/contact/point_spacing.py runs in under a second. No new dependencies.

References

Kamensky et al., CMAME 2018, doi:10.1016/j.cma.2017.11.007. Wu et al., J Biomech Eng 2022, doi:10.1115/1.4054485. FEBio source: FEBioMech/FEContactPotential.cpp, FEEdgeToSurfaceContactPotential.cpp, FEBioTest/FEContactDiagnostic.cpp (develop).


Generated by Claude Code

…search, interface seam

An initial approach to contact, built on Kamensky et al. (2018) and FEBio's
FEContactPotential, for review by the FEBio and Warp teams.

ContactPoints from quad/tri facets, segments and nodes; float64 HashGrid
pair search with body, reference-distance, same-element or shared-node, and
w_tol exclusion and pair classes; the FEBio force law with per-class
parameters, pair multiplicity and capsule radius offsets; energy, force,
full and projected tangent action, device BSR assembly (warp.sparse), r_min
guard, reference or current (FEBio) weights, and the published contact
metrics. ContactPotentialTerm behind PhysicsTerm and a FEBio-style
ContactInterface protocol, with tape-gradient and parameter-adjoint entry
points. from_febio_block maps a FEBio contact potential block. 32 tests
(31 CPU, 1 GPU-only), a CPU workflow, and docs/CONTACT.md, which lists
where the module differs from FEBio and two questions for FEBio review.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019P2qELf6sFRDViEYZpJCoh
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant