Add barrier stiffness and simplify tangential API

[zfergus]

Description

• Introduce a barrier stiffness (kappa) to BarrierPotential: new constructors, member, getters/setters, and scale operator/gradient/hessian by stiffness.
• Remove the redundant normal_stiffness parameter from tangential collision constructors and tangential potential interfaces, updating all call sites, headers, and implementations accordingly.
• Update Python bindings, tutorials, examples (ogc, solver), and tests (test_ipc) to match the new API and default stiffness usage; also move a notebook to python/examples.
• Miscellaneous formatting/import cleanups and adjustments to pybind argument lists to reflect the simplified tangential API.

Type of change

• Breaking change (fix or feature that would cause existing functionality to not work as expected)

[Copilot]

Pull request overview

This PR updates IPC’s contact modeling APIs by embedding barrier stiffness directly into BarrierPotential and simplifying the tangential/friction interfaces by removing the redundant normal-stiffness parameter, with corresponding updates across C++, Python bindings, docs, examples, and tests.

Changes:

• Add barrier stiffness (kappa) as state in ipc::BarrierPotential and apply it internally when evaluating energy/derivatives.
• Remove normal_stiffness from tangential collision construction and tangential potential/force interfaces, updating call sites accordingly.
• Update Python bindings, tutorials/examples, and tests to use the new signatures and stiffness behavior.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
tests/src/tests/potential/test_friction_potential.cpp	Updates friction potential test for new barrier/tangential APIs (currently still passes removed arg).
tests/src/tests/potential/test_barrier_potential.cpp	Updates barrier potential tests for new BarrierPotential(dhat, kappa, ...) ctor.
tests/src/tests/potential/test_adhesion_potentials.cpp	Updates adhesion tests for new normal potential force-magnitude signature.
tests/src/tests/friction/test_friction.cpp	Updates friction test construction to pass stiffness via BarrierPotential.
tests/src/tests/friction/test_force_jacobian.cpp	Updates force-jacobian test call sites (currently still passes removed arg to tangential build).
tests/src/tests/collisions/test_normal_collisions.cpp	Updates barrier usage in collision tests to pass stiffness.
tests/src/tests/barrier/test_barrier.cpp	Adjusts barrier derivative testing approach and FD settings (tolerance risk).
src/ipc/potentials/tangential_potential.hpp	Removes normal_stiffness from tangential force/jacobian API.
src/ipc/potentials/tangential_potential.cpp	Implements tangential force/jacobian changes using new normal potential API.
src/ipc/potentials/normal_potential.hpp	Removes barrier_stiffness parameter from the normal-potential force magnitude interfaces.
src/ipc/potentials/normal_adhesion_potential.hpp	Updates adhesion potential overrides to match new interface.
src/ipc/potentials/normal_adhesion_potential.cpp	Implements updated overrides for new interface.
src/ipc/potentials/barrier_potential.hpp	Adds stiffness member/accessors; updates ctor and normal-force magnitude overrides.
src/ipc/potentials/barrier_potential.cpp	Stores stiffness and applies it internally to energy/derivatives and force magnitude.
src/ipc/collisions/tangential/*.{hpp,cpp}	Removes stiffness argument from tangential collision initialization and propagation.
python/tests/test_ipc.py	Updates Python test to construct BarrierPotential with stiffness.
python/src/potentials/tangential_potential.cpp	Updates pybind signatures/docs for tangential potential API change.
python/src/potentials/normal_potential.cpp	Updates exposed argument list but leaves stale doc references (needs cleanup).
python/src/potentials/barrier_potential.cpp	Updates ctor binding but does not expose stiffness property and needs kw-only consideration.
python/src/collisions/tangential/*.cpp	Updates pybind constructors/build overloads for removed stiffness arg.
python/examples/solver.py	Updates example to new stiffness semantics (currently has enum typo).
python/examples/ogc.py	Updates example to pass stiffness into BarrierPotential instead of scaling forces externally.
docs/source/tutorials/simulation.rst	Updates tutorial snippets for new ctor and tangential build signature (stiffness not introduced in snippet).
docs/source/tutorials/getting_started.rst	Updates tutorial snippets/text for stiffness (equation/snippet consistency issues).

Comments suppressed due to low confidence (2)

python/src/potentials/barrier_potential.cpp:36

• C++ adds BarrierPotential::stiffness() and set_stiffness(), but the Python bindings only expose dhat and barrier properties. Consider adding a .def_property("stiffness", ...) so Python users can read/update the stiffness after construction (consistent with the new C++ API).

        .def_property(
            "dhat", &BarrierPotential::dhat, &BarrierPotential::set_dhat,
            "Barrier activation distance.")
        .def_property(

python/src/potentials/normal_potential.cpp:82

• The Python docstring for NormalPotential.force_magnitude_gradient() still mentions barrier_stiffness, but the exposed signature is now (distance_squared, distance_squared_gradient, dmin). Please remove/update the stale parameter description to avoid confusing Python users.

            "force_magnitude_gradient",
            &NormalPotential::force_magnitude_gradient,
            R"ipc_Qu8mg5v7(
            Compute the gradient of the force magnitude for a collision.

            Parameters:
                distance_squared: The squared distance between elements.
                distance_squared_gradient: The gradient of the squared distance.
                dmin: The minimum distance offset to the barrier.
                barrier_stiffness: The stiffness of the barrier.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

TangentialCollisions::build() no longer takes a separate normal/barrier stiffness for normal-force magnitude. This call still passes barrier_stiffness as an extra argument, which will not compile and also double-specifies stiffness (it’s already embedded in BarrierPotential(dhat, barrier_stiffness)). Remove the extra barrier_stiffness argument and pass only mu after the normal potential.

[Copilot]

ipctk.PSDProjectionMethod does not have a CLAM value (the enum is CLAMP, ABS, NONE). This will raise at runtime. Use ipctk.PSDProjectionMethod.CLAMP here.

Suggested change

	project_hessian_to_psd=ipctk.PSDProjectionMethod.CLAM,
	project_hessian_to_psd=ipctk.PSDProjectionMethod.CLAMP,

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.96%. Comparing base (8377ff7) to head (750b592).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #215   +/-   ##
=======================================
  Coverage   96.96%   96.96%           
=======================================
  Files         158      158           
  Lines       24659    24663    +4     
  Branches      883      883           
=======================================
+ Hits        23910    23914    +4     
  Misses        749      749           

Flag	Coverage Δ
unittests	96.96% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 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.