[zfergus]

Description

Adds rigid and affine body dynamics as reusable library components (src/ipc/dynamics/), glTF scene I/O (src/ipc/io/), and a demo simulator (demo/) that assembles them, touching CCD, the LBVH broad phase, and the Python bindings along the way.

Mechanism

• ipc::rigid — Pose, RigidBody, and RigidBodies (a CollisionMesh of all bodies, built from per-body meshes). Each body is re-centered on its center of mass and expressed in its principal frame. This follows Rigid IPC (Ferguson et al. 2021).
• ipc::rigid::RigidCandidates — finds body pairs with a bounding-sphere broad phase, then queries each pair with two-tree LBVH queries in one body's rest frame. Narrow-phase CCD follows the curved rigid trajectories through NonlinearCCD, with a conservative bound on how far each piece strays from its chord.
• ipc::affine — the body terms are written once in affine coordinates y = [p; vec(A)]: InertialTerm, BodyForces, OrthogonalityPotential, an AugmentedLagrangian that drives kinematic bodies, and linear JointConstraints. This follows ABD (Lan et al. 2022), with joints as in Chen et al. 2022, §4.1.
• ipc::dynamics — a ToAffine change of variables lets the same terms serve both models. RigidToAffine maps [p; θ] to A = R(θ); AffineToAffine is the identity. BodyPotentials sums the terms and applies the chain rule once, and BDF provides orders 1–6.
• demo/ (ipc_toolkit_demo, not part of the library) — a polysolve-based Simulator with adaptive barrier stiffness, lagged friction, and static/kinematic bodies. It is exposed in Python as ipctk.demo.

Impact

• Downstream simulators can build rigid or affine body dynamics from library parts. The core library still depends on no solver; only the demo links polysolve.
• NonlinearCCD can now use any NarrowPhaseCCD for its per-piece linear CCD; the demo uses AdditiveCCD.
• Scenes load from and animations save to glTF when IPC_TOOLKIT_WITH_GLTF=ON.
• Top-level builds now build the demo by default, which fetches polysolve. Projects that include the toolkit as a subproject are unaffected.

API changes

• New CMake options: IPC_TOOLKIT_BUILD_DEMO (ON at top level, OFF as a subproject) and IPC_TOOLKIT_WITH_GLTF (OFF).
• NarrowPhaseCCD: every query takes a trailing NarrowPhaseCCDMode mode = STANDALONE. COMPONENT and COMPONENT_NO_ZERO_TOI tell a method it is the per-piece CCD inside a piecewise driver, so it returns the raw time of impact. The mode is passed per call, so a shared narrow-phase object is never modified.
• NonlinearCCD: the constructor is now NonlinearCCD(narrow_phase_ccd = nullptr, conservative_rescaling); null selects a TightInclusionCCD. Also new: set_narrow_phase_ccd() and narrow_phase_ccd().
• LBVH: new two-tree queries detect_*_candidates(const LBVH& other, can_collide, candidates) between two separately built trees.
• CollisionMesh: the destructor and vertices(full_positions) are now virtual, so RigidBodies can map poses to vertices.
• Smaller additions: nearest_rotation, sinc (scalar and interval), ipc::PI (<ipc/math/constants.hpp>), and a 2D cross_product_matrix(double).
• Logger: the default ipctk logger is no longer registered in spdlog's global registry. Previously, two Python modules that each embed the toolkit failed on the duplicate name.
• Python:
  • Bindings for RigidBodies, RigidBody, Pose/Poses, AffinePose, JointConstraints, read_gltf/write_gltf, and NarrowPhaseCCDMode.
  • The CCD classes are now held by std::shared_ptr.
  • Python NarrowPhaseCCD subclasses written without a mode parameter keep working.

💥 Breaking changes

• C++ subclasses of NarrowPhaseCCD must add the mode parameter to their four overrides.
• NonlinearCCD::tolerance and NonlinearCCD::max_iterations are removed. Configure the TightInclusionCCD you pass in instead.
• Deprecated, but still working with a warning:
  • NonlinearCCD(tolerance, max_iterations, conservative_rescaling) in C++ and Python. It builds the equivalent TightInclusionCCD.
  • Candidates::save_obj, renamed to write_obj, in C++ and Python.
  • <ipc/utils/save_obj.hpp>, which forwards to <ipc/io/write_candidates_obj.hpp>.

New dependencies

• polysolve (MIT), fetched with CPM at a pinned commit.
  • Linked only by ipc_toolkit_demo, never by ipc_toolkit.
  • Its optional backends (CHOLMOD, MKL, AMGCL, …) are disabled, so it uses only Eigen's solvers and adds no transitive system dependencies.
• TinyGLTF 2.9.6 (MIT), fetched with CPM.
  • Compiled as one translation unit and linked PRIVATE.
  • Fetched only when IPC_TOOLKIT_WITH_GLTF=ON.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Enhancement (non-breaking change which improves existing functionality)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

• ipc_toolkit_tests "~[!benchmark]": all 518 test cases pass. This includes 86 new cases in tests/src/tests/{dynamics,demo,io}:
  • Finite-difference checks of every body term, the ToAffine chain rule, and rigid pose derivatives.
  • Analytic checks of mass properties, BDF exactness and derivatives, and external torques applied at arbitrary orientations.
  • Rigid candidates and CCD along curved trajectories.
  • glTF round-trips, including node hierarchies, multi-primitive meshes, and faceless bodies.
  • Simulator scenes: free flight, friction stick/slip and deceleration, static and kinematic bodies, joints, 2D, and codimensional contact.
• python -m nose2 in python/tests: all 106 tests pass. These include the new NarrowPhaseCCDMode and backward-compatibility tests.
• A compile-only check of src/ipc/math/sinc.cpp with IPC_TOOLKIT_WITH_FILIB off.

Test Configuration:

• OS and Version: macOS 26 (Apple Silicon)
• Compiler and Version: AppleClang 21.0, Release, Python 3.13

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

[codecov]

Codecov Report

❌ Patch coverage is 91.07597% with 316 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.25%. Comparing base (b9d0325) to head (14d78d1).

Files with missing lines	Patch %	Lines
src/ipc/io/write_gltf.cpp	65.84%	97 Missing ⚠️
src/ipc/io/read_gltf.cpp	76.96%	47 Missing ⚠️
src/ipc/dynamics/rigid/rigid_candidates.cpp	87.41%	36 Missing ⚠️
demo/src/simulator.cpp	94.51%	32 Missing ⚠️
.../ipc/dynamics/time_integration/time_integrator.cpp	77.94%	15 Missing ⚠️
demo/src/kinematics.cpp	85.86%	13 Missing ⚠️
src/ipc/dynamics/affine/joints.cpp	94.25%	10 Missing ⚠️
src/ipc/dynamics/rigid/mass.cpp	93.67%	10 Missing ⚠️
src/ipc/candidates/candidates.cpp	0.00%	9 Missing ⚠️
src/ipc/dynamics/affine/affine_dof.cpp	82.92%	7 Missing ⚠️
... and 12 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #184      +/-   ##
==========================================
- Coverage   96.97%   96.25%   -0.73%     
==========================================
  Files         221      264      +43     
  Lines       22426    25883    +3457     
  Branches     1540     1976     +436     
==========================================
+ Hits        21748    24913    +3165     
- Misses        678      970     +292     

Flag	Coverage Δ
unittests	96.25% <91.07%> (-0.73%)	⬇️

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

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