Extremum Sum Potential

[fsichetti]

Description

Adds the Extremum Sum Proximity Potential (ESP) as a new ipc/esp/ module, with supporting changes to barriers, candidates, collision meshes, friction and distance-type classification; also renames smooth_contact to gcp with appropriate compatibility aliases.

Mechanism

• ESPParameters: dhat, the near/far split parameter dbar_factor in [0, 2], the barrier (default NormalizedClampedLogBarrier), the 2D quad_order, an optional 3D face quadrature rule, area_weights and integration_type.
• ESPCollisions: builds the quadrature collision set from broad-phase candidates.
• ESPPotential: value, gradient and Hessian, with PSD projection.
  • 2D integrates over edges at Gauss-Lobatto points.
  • 3D integrates over faces (at their vertices or at face quadrature points) and at the closest points of nearby edge-edge pairs.
  • With use_near_far = true (the default), the 3D quadrature weights are normalized to sum to 1, split into near and far parts (NearFarBarrier) when dbar_factor > 0.
• ArbitraryPointESP<dim>: value, gradient and Hessian of the potential at an arbitrary point, with inclusion-exclusion weights for open and codimensional input.
• Friction: a TangentialCollisions::build overload that takes ESPCollisions; the existing FrictionPotential consumes the result.
• Exact distance-type classifiers (point_edge_distance_type_exact, point_triangle_distance_type_exact, edge_edge_distance_type_exact) built on three shared sign predicates, so their classifications agree.

Impact

• New optional dependency, geogram, on by default.
• Breaking: the smooth_contact → gcp rename removes most old header paths (see below).
• Additions to existing classes are defaulted, so existing calls compile unchanged.
• Python exposes ESPParameters (without the barrier and face-rule settings), ESPCollisions, ESPPotential, the GCP* names and Candidates.build(..., all_types=False); the rest of the new API is C++ only.

API changes

New public types outside ipc/esp/

• InversePowerBarrier(p): b(d) = h(d) / d^p, where h is a cubic B-spline that vanishes at dhat.
• NearFarBarrier(base, alpha): splits a barrier into a near and a far part, with a smooth step between alpha * dhat / 2 and alpha * dhat.
• DistanceTypeConfig, the *_distance_type_exact functions and is_parallel_edge_edge.

Additions to existing classes

• Candidates::build(..., all_types = false) and BroadPhase::detect_collision_candidates(..., all_types = false): in 3D, all_types also collects vertex-vertex, edge-vertex, edge-face and face-face candidates, for ESP only.
• Candidates: new ef_candidates, ff_candidates and adjacency sets (convert_candidates_to_sets(), vv_set() … ff_set()).
• CollisionMesh: a constructor overload with an obstacle_vertex mask; is_obstacle_vertex/edge/face(); face_areas().
• NormalCollisions::set_skip_obstacles(bool), default false.
• BarrierPotential(..., use_squared_distance = true): false evaluates the barrier on the unsquared distance, where force_magnitude() throws.
• CollisionStencil::name().

💥 Breaking changes

• ipc/smooth_contact/ is renamed to ipc/gcp/, and its classes to GCP*.
  • Deprecated aliases keep the old class names compiling: SmoothCollision, SmoothCollisionTemplate, SmoothCollisions, SmoothCollisionsBuilder, SmoothContactParameters, SmoothContactPotential.
  • TangentialPotential::smooth_contact_force* is renamed to gcp_force*, with deprecated forwarders.
  • Python keeps the old names as aliases of the new classes, without a warning.
  • Only smooth_contact/smooth_collisions.hpp and smooth_contact/smooth_contact_potential.hpp remain, as forwarding headers; the other 15 old headers (and two .tpp files) are gone.
  • TangentialCollision::smooth_collision is renamed to gcp_collision, without an alias.
• Code that takes the address of Candidates::build or BroadPhase::detect_collision_candidates with the old parameter list (e.g. py::overload_cast) must add the bool.

Known limitations

• ESP friction does not support gcp_force_jacobian, always area-weights, and ignores the InversePowerBarrier power that ESPPotential applies to edge-edge weights.
• Python cannot mark obstacle vertices, so integration_type has no effect there.

New dependencies

• geogram 1.10.1: BSD-3-Clause, fetched with CPM, behind IPC_TOOLKIT_WITH_GEOGRAM (default ON).
  • Linked PRIVATE and used only in distance_type_exact.cpp; no public header includes it.
  • Library-only build (graphics, Lua, TetGen, Triangle and HLBFGS off); its own warnings are silenced on GCC and Clang.
  • geogram's default platform settings build it as a shared library on Linux and macOS, so executables and the ipctk module there need libgeogram at run time.
  • On Linux, geogram also links tbb, and OpenMP when built with GCC.
  • Wheels rely on cibuildwheel's repair step to bundle libgeogram; no PR check builds a wheel.
  • With the option OFF, the classifiers use floating-point predicates and log a warning once; no CI job builds this configuration.

Other changes

• Fixes MSVC builds on AVX2 machines being compiled for AVX: FindSIMD.cmake no longer emits both /arch:AVX2 and /arch:AVX.

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?

New test files

• test_esp_potential.cpp (30 cases, one hidden): FD derivatives, PSD projection, zero potential on closed meshes, bounded edge-edge terms near edge endpoints, and continuity in dbar_factor.
• test_arbitrary_point_esp.cpp (8 cases): zero beyond dhat, FD derivatives, and inclusion-exclusion weights on open input.
• test_obstacles.cpp (5 cases): obstacle flags, obstacle skipping in NormalCollisions, and ESP integration types.
• test_vertex_matrix_view.cpp (5 cases).

New cases in existing files

• test_distance_type.cpp (+6): four random tests (10,000 samples each, geogram builds only) compare the classifiers with an exact geogram reference; two check mutual consistency and the use_standard fallback.
• test_force_jacobian.cpp (+4): ESP friction force against −∇D and friction Hessian against finite differences, in 2D and 3D.
• test_candidates.cpp (+1, adjacency sets), test_barrier_potential.cpp (+1, unsquared distance), test_barrier.cpp (InversePowerBarrier sections).
• Python: TestESPPotential and TestGCPAliases.

Reproduce

• cmake --preset=test && cmake --build --preset=test -j 8 && cd build/test && ctest
• pip install . && pytest python/tests/test_potentials.py

CI on 03c39d2

• All 18 checks pass; patch coverage 96.57%.
• Debug CTest time: 1010 s on Windows, 817 s on Linux, 869 s on macOS.
• Slowest test: "ESP potential 2D finite differences", 885 s on Windows Debug (59% of the 1500 s timeout).

Test Configuration:

• OS and Version: macOS 15.5 (24F74), arm64
• Compiler and Version: Apple clang 17.0.0 (clang-1700.0.13.5)
• CMake 4.2.3, IPC_TOOLKIT_WITH_GEOGRAM=ON, IPC_TOOLKIT_WITH_CUDA=OFF

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