STL_Extension: Add bisect_failures debugging utility

[lrineau]

Summary

This PR adds a new debugging utility bisect_failures to the STL_Extension package. This function helps identify minimal failing test cases from complex input data by using a bisection-like approach.

Small feature: bisect failures debugging utility

Features

• Multiple failure type support: Handles CGAL exceptions, std::exceptions, and exit codes
• Automatic granularity adjustment: Starts with ratio=0.5, automatically halves when no fault is found
• Debug output: Saves intermediate states (current, bad, error, final_bad)
• Template-based design: Works with any copyable/assignable data type

Testing

Added comprehensive test suite (test_bisect_failures.cpp) with 14 tests:

• ✅ Edge cases (empty data, no failures)
• ✅ Single element failures (CGAL exception, std::exception, exit code)
• ✅ Pair combinations (all 2-element permutations)
• ✅ Triple combinations (all 3 failure types together)

All tests pass in both Debug and Release configurations.

Use Case

This utility is particularly useful for:

• Debugging complex geometric algorithms with large input datasets
• Finding minimal reproducible test cases from failing inputs
• Isolating problematic elements in mesh processing, triangulation, etc.

Example Usage

auto get_size = [](const Mesh& m) { return m.number_of_faces(); };
auto simplify = [](Mesh& m, std::size_t start, std::size_t end) -> bool {
  // Remove faces from start to end
  for(std::size_t i = start; i < end && i < m.number_of_faces(); ++i) {
    m.remove_face(start);
  }
  return true;
};
auto run = [](const Mesh& m) -> int { return algorithm(m); };
auto save = [](const Mesh& m, const std::string& prefix) {
  std::ofstream out(prefix + ".off");
  out << m;
};

int result = bisect_failures(mesh, get_size, simplify, run, save);

Files Changed

• STL_Extension/include/CGAL/bisect_failures.h (new) - Main utility header
• STL_Extension/test/STL_Extension/test_bisect_failures.cpp (new) - Test suite
• STL_Extension/test/STL_Extension/CMakeLists.txt (modified) - Added test

Checklist

• Code compiles without errors (Debug and Release)
• All tests pass
• Comprehensive documentation with Doxygen comments
• Example usage in documentation
• Follows CGAL coding style conventions
• Deal with false positive in the testsuite

Release Management

• Affected package(s): STL_Extension
• Feature/Small Feature (if any): bisect failures debugging utility
• Link to compiled documentation (obligatory for small feature) doc
• License and copyright ownership: no change

[afabri]

/force-build:v0

[github-actions]

The documentation is built. It will be available, after a few minutes, here: https://cgal.github.io/9118/v0/Manual/index.html

[lrineau]

Seems to fail with ICPC. See here

ICPC version is 2025.1 on Christo, whereas the latest version is 2025.3. Maybe we should upgrade.

[lrineau]

/build:v2

[github-actions]

The documentation is built. It will be available, after a few minutes, here: https://cgal.github.io/9118/v2/Manual/index.html

[lrineau]

@afabri @sloriot Please re-review: CGAL bisect_failures v2.

[sloriot]

I like this version better! Still some occurrences of minimal and smallest remaining that I'd prefer being replaced with reduced for example.

[afabri]

I made suggestions for replacing minimal @lrineau

[lrineau]

I have applied all of your suggestions in the last commit.

[lrineau]

/build:v3

[github-actions]

The documentation is built. It will be available, after a few minutes, here: https://cgal.github.io/9118/v3/Manual/index.html