Implement Preconditioner from Shen et al. [2024]

[zfergus]

Description

Implement CollisionStencil distance-vector utilities:

• compute_distance_vector
• compute_distance_vector_jacobian
• diag helpers
• Jacobian contraction routine

Add cumulative NormalPotential Gauss-Newton routines (diagonal and quadratic form), parallelized with TBB.

Expose the new APIs in Python bindings and add unit tests covering the distance-vector helpers and Gauss-Newton computations. Also, add a simple assert in local_to_global scatter for vertex ids.

Type of change

• New feature (non-breaking change which adds functionality)

[codecov]

Codecov Report

❌ Patch coverage is 99.07407% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.20%. Comparing base (6d3d38c) to head (cbb5076).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/ipc/potentials/normal_potential.cpp	98.50%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main     #221    +/-   ##
========================================
  Coverage   97.19%   97.20%            
========================================
  Files         160      160            
  Lines       24798    24906   +108     
  Branches      889      897     +8     
========================================
+ Hits        24103    24209   +106     
- Misses        695      697     +2     

Flag	Coverage Δ
unittests	97.20% <99.07%> (+<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.

[Copilot]

Pull request overview

This PR implements a preconditioner from Shen et al. [2024] based on the distance-vector formulation for IPC (Incremental Potential Contact) barrier potentials. It introduces efficient Gauss-Newton Hessian approximations that avoid forming full local Hessian matrices, which is useful for Jacobi preconditioning in iterative solvers and for computing quadratic forms in nonlinear CG methods.

Changes:

• Add compute_distance_vector, compute_distance_vector_jacobian, and static helper methods (diag_distance_vector_outer, diag_distance_vector_t_outer, contract_distance_vector_jacobian) to CollisionStencil for efficient distance-vector operations.
• Add gauss_newton_hessian_diagonal and gauss_newton_hessian_quadratic_form methods to NormalPotential (both single-collision and cumulative/parallelized versions), plus defensive assert additions in local_to_global.hpp.
• Expose all new APIs in Python bindings and add comprehensive unit tests covering the distance-vector helpers and Gauss-Newton computations.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/ipc/candidates/collision_stencil.hpp	Declares new distance-vector utility methods on CollisionStencil
src/ipc/candidates/collision_stencil.cpp	Implements compute_distance_vector, Jacobian, and static diagonal/contraction helpers
src/ipc/potentials/normal_potential.hpp	Declares Gauss-Newton Hessian diagonal and quadratic form methods (cumulative + single)
src/ipc/potentials/normal_potential.cpp	Implements the new GN methods with TBB parallelization for cumulative versions
src/ipc/utils/local_to_global.hpp	Adds assert(ids[i] >= 0) defensive checks in scatter functions
python/src/candidates/collision_stencil.cpp	Exposes new CollisionStencil methods in Python bindings
python/src/potentials/normal_potential.cpp	Exposes new NormalPotential GN methods in Python bindings
tests/src/tests/potential/test_distance_vector_methods.cpp	Unit tests for distance-vector helpers and Gauss-Newton computations
tests/src/tests/potential/CMakeLists.txt	Adds new test file to the build

---

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

You can also share your feedback on Copilot code review. Take the survey.