Divide and Truncate

[zfergus]

Description

This pull request introduces the Planar-DAT (Divide and Truncate) method for trust-region filtering in the OGC solver, providing a direction-aware alternative to isotropic filtering that reduces artificial damping and deadlock in dense-contact scenarios. It adds both C++ and Python bindings for the new planar_filter_step method, comprehensive documentation and usage examples, and includes minor code cleanups and improvements to type signatures.

This is based on the follow-up work by Chen et al. [2026]: https://arxiv.org/abs/2604.15513

Planar-DAT Trust Region Filtering:

• Added the planar_filter_step method to the TrustRegion class, which implements the Planar-DAT algorithm for direction-aware truncation of vertex displacements during optimization. This method computes a division plane per collision pair and only truncates motion toward the opposing primitive, allowing for larger and less damped steps in dense contact scenarios. [1] [2] [3]
• Exposed planar_filter_step to Python via pybind11, including detailed docstrings describing its usage and parameters.

Documentation and Tutorials:

• Added a comprehensive section to the OGC tutorial explaining Planar-DAT, its motivation, algorithmic steps, and how to use it in both C++ and Python. Includes guidance on when to use isotropic vs. planar filtering and code examples for both languages.
• Added a new BibTeX reference for the DAT paper to the bibliography.

Code Quality and Maintenance:

• Improved function signatures in pybind11 bindings by passing string arguments as const std::string& instead of by value, reducing unnecessary copies. [1] [2]
• Removed unused includes from several C++ source files for cleaner code. [1] [2] [3] [4] [5]

Type of change

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

How Has This Been Tested?

• New unit tests

Checklist

• I have followed the project style guide
• My code follows the clang-format style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[Copilot]

Pull request overview

Introduces Planar-DAT (Divide and Truncate) trust-region filtering to the OGC solver’s trust-region step filtering, adds Python bindings, and documents the method with examples and references.

Changes:

• Added ipc::ogc::TrustRegion::planar_filter_step() (Planar-DAT) plus supporting helpers.
• Exposed planar_filter_step to Python and added unit tests covering FV/EE cases.
• Updated OGC tutorial + bibliography; minor C++ include cleanup and pybind signature copy-avoidance.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/ipc/ogc/trust_region.hpp	Declares Planar-DAT API and documents behavior (currently has parameter/doc mismatches).
src/ipc/ogc/trust_region.cpp	Implements Planar-DAT filtering and refactors isotropic clamping into a helper.
python/src/ogc/trust_region.cpp	Adds pybind11 binding + docstring for planar_filter_step (currently documents non-existent args).
tests/src/tests/ogc/test_trust_region.cpp	Adds Planar-DAT-focused tests for separating/tangential/approaching FV and EE scenarios.
docs/source/tutorials/ogc.rst	Adds a Planar-DAT tutorial section and usage examples (one statement currently misdescribes filter_step radius).
docs/source/references.bib	Adds BibTeX entry for Chen et al. (2026).
python/src/collisions/normal/normal_collisions.cpp	Avoids string copies in pybind helper signatures.
tests/src/tests/utils.hpp	Adds // NOLINT to Matrix Market loader decls.
src/ipc/collisions/normal/normal_collision.hpp	Removes unused include.
src/ipc/candidates/vertex_vertex.cpp	Removes unused include.
src/ipc/candidates/face_vertex.cpp	Removes unused include.
src/ipc/candidates/edge_vertex.cpp	Removes unused include.
src/ipc/broad_phase/lbvh.hpp	Removes unused include.

---

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

[codecov]

Codecov Report

❌ Patch coverage is 98.93333% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.85%. Comparing base (1db208d) to head (1ba3274).

Files with missing lines	Patch %	Lines
src/ipc/ogc/trust_region.cpp	96.33%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #228      +/-   ##
==========================================
- Coverage   95.85%   95.85%   -0.01%     
==========================================
  Files         160      160              
  Lines       16664    16638      -26     
  Branches      948      932      -16     
==========================================
- Hits        15974    15948      -26     
  Misses        690      690              

Flag	Coverage Δ
unittests	95.85% <98.93%> (-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.