Repository navigation
Initial exploration of contact: Kamensky potential, point sets, pair search, interface seam - #1
Draft
mattjolley wants to merge 1 commit into
Draft
mattjolley wants to merge 1 commit into
mattjolley wants to merge 1 commit into
Conversation
…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
mattjolley
requested review from
SteveMaas1978,
aslanseda9,
ryanblack129 and
shi-eric
November 20, 2026 00:11
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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: float64wp.HashGridpair 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), andw_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 throughwarp.sparse;r_minguard; reference or current (FEBio) integration weights; Wu 2022 contact area and Zelonis 2026 contact fraction;from_febio_blockto map a.febcontact block one to one.contact/enforcement.pyandcontact/interface.py: the potential behindcontracts.PhysicsTermand a FEBio-styleContactInterfaceprotocol, so sliding, sticky and tied laws can follow without touching the solver;energy_and_gradientas 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'sFEContactDiagnosticapplied 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
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_tolandR0_minare applied per point pair here; FEBio applies them as element-pair activation gates.check_intersectionsis not implemented. A facet-level match with FEBio atw_tol > 0should not be expected yet.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.FEContactPotential::UpdateandLoadVector/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?k_cshould be specified across pair classes, since the stiffness at the core boundary scales asR_in^-5at fixedk_c. The module offers per-point radius offsets as one way out; the question is left open.Testing
python -m unittest discover -s testson CPU with Warp 1.19.0: 40 tests, 38 pass, 2 skipped (GPU only).python examples/contact/point_spacing.pyruns 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