examples: add geometric inference of convex bodies benchmarking tool

[edish-github]

Summary

Adds a benchmarking example that measures how well the convex hull of uniform random samples approximates the original convex body. Uses support function gaps as a proxy for Hausdorff distance.

What the example does

• Samples N uniform points from a known convex body using volesti's CDHRWalk
• Measures the support function gap h_K(u) - ĥ_n(u) across 100 random directions as a Hausdorff distance proxy
• Tracks approximate hull vertex count via support function maximizer scanning with epsilon deduplication
• Detects body type (polyhedral vs smooth) from vertex count growth rate using log-log regression
• Measures holdout miss rate as a volume coverage diagnostic
• Fits empirical convergence exponents and compares to theoretical rates

Bodies tested

• Cube [-1,1]^d (polyhedral): expected d_H rate O((log n / n)^{1/d})
• Unit ball B^d (smooth): expected d_H rate O((log n / n)^{2/(d+1)})

Sample output (d=3, 10 trials per sample size)

╔══════════════════════════════════════════════════════════════════╗
║  volesti benchmarking: Convex Hull Approximation                 ║
║                                                                  ║
║  Demonstrates: measuring how well the convex hull of N uniform   ║
║  samples approximates the original convex body, using support    ║
║  function gaps as a proxy for Hausdorff distance.                ║
╚══════════════════════════════════════════════════════════════════╝


===========================================================================
  Experiment 1: Cube [-1,1]^d (polyhedral)
  d=3, directions=100, trials=10
===========================================================================
       n  hull_verts   max_gap (±std)  mean_gap (±std)     miss_rate
---------------------------------------------------------------------------
     100        24.9    0.6039 ± 0.0750    0.27691 ± 0.0307    0.109
     500        37.6    0.3578 ± 0.0311    0.16583 ± 0.0197    0.022
    1000        40.9    0.2878 ± 0.0324    0.13046 ± 0.0066    0.015
    5000        50.7    0.1673 ± 0.0218    0.07514 ± 0.0070    0.005

  Body type detection for Cube [-1,1]^3:
    Log-log slope of vertex count vs n: 0.1799
    → Classified as POLYHEDRAL (slope ≈ 0, logarithmic growth)
    → Use O((log n / n)^{1/d}) convergence rate
    → Expect faster convergence with fewer samples

===========================================================================
  Experiment 2: Unit Ball B^d (smooth)
  d=3, directions=100, trials=10
===========================================================================
       n  hull_verts   max_gap (±std)  mean_gap (±std)     miss_rate
---------------------------------------------------------------------------
     100        37.2    0.2484 ± 0.0278    0.10062 ± 0.0127    0.143
     500        79.4    0.1111 ± 0.0140    0.04563 ± 0.0028    0.038
    1000       107.4    0.0780 ± 0.0123    0.03183 ± 0.0017    0.020
    5000       196.7    0.0361 ± 0.0035    0.01434 ± 0.0008    0.004

  Body type detection for Unit Ball B^3:
    Log-log slope of vertex count vs n: 0.4260
    → Classified as SMOOTH (slope > 0.25, polynomial growth)
    → Use O((log n / n)^{2/(d+1)}) convergence rate
    → Expect slower convergence, needs more samples

===========================================================================
  Convergence Rate Analysis (d=3)
===========================================================================

  Cube [-1,1]^3:
    Empirical exponent: -0.3358
    Theory (ignoring log): -0.3333 = -1/3
    Match: YES

  Unit Ball B^3:
    Empirical exponent: -0.5043
    Theory (ignoring log): -0.5000 = -2/4
    Match: YES

===========================================================================
  Summary
===========================================================================
  Dimension:           3
  Sample sizes tested: 100 500 1000 5000 
  Trials per size:     10
  Directions per trial: 100
  Total runtime:       172.0 seconds

  Key findings:
    1. Convex hull gap decreases as sample size grows (confirmed)
    2. Cube (polyhedral) and ball (smooth) converge at different rates (confirmed)
    3. Vertex count growth distinguishes body types (confirmed)
    4. Holdout miss rate decreases with n (confirmed)

  These results demonstrate that support function gaps
  are an effective proxy for Hausdorff distance in
  convex hull approximation quality assessment.
===========================================================================

Files added

examples/geometric_inference/
├── CMakeLists.txt                   (build config, links lp_solve)
├── geometric_inference_poc.cpp      (main benchmark, ~350 lines)
└── README.md                        (documentation + math background)

Build

cd examples/geometric_inference
mkdir build && cd build
cmake ..
make
./geometric_inference_poc

Tested on macOS 15.x, AppleClang 17.(required workaround for #436 to build successfully).

References

• Bárány & Larman, "Convex bodies, economic cap coverings, random polytopes", Mathematika 35, 1988
• Brunel, "Methods for Estimation of Convex Sets", Statistical Science, 2018
• Chalkis & Fisikopoulos, "volesti: Volume Approximation and Sampling for Convex Polytopes in R", R Journal, 2021

---

This example relates to the "Geometric Inference of Convex Bodies from Random Sampling" project idea on the GeomScale GSoC 2026 ideas page.

[vissarion]

Thanks for the PR.

So the point of this is to distinguish between different bodies using sample. And you do it for 3-cube vs 3-ball. What happens in higher dimensions? (this is the interesting question here, e.g. d>20). Can you distinguish between a ball and a Birkhoff polytope or a random polytope (points selected uniformly from the surface of a Ball)?