Modernize CGAL 6.2 integration for current best practices

[acgetchell]

Current v1.0.0 plan (2026-07-22)

Starts after: #74 and #101. Blocks: #88.

Audit and modernize production CGAL 6.2 surfaces only where needed for correctness, lifetime safety, deterministic reference behavior, and the supported build contract. The priorities are traits/TDS validity, handle invalidation, insertion/removal, cache consistency, flip preconditions, the applicable-move boundary, and the sequential/parallel configuration.

Do not change kernels, exact-arithmetic backends, or peripheral experiments without a reproduced defect and comparative evidence. #88 owns multithreaded behavior and scaling; #98 owns viewer restoration.

Native GitHub dependency metadata is the source of truth for ordering.

---

Summary

Perform a comprehensive audit and modernization of CDT++'s CGAL integration against CGAL 6.2 APIs, concepts, documented preconditions, and recommended usage patterns. Make the integration exemplary modern scientific C++ while preserving CDT semantics, deterministic reference behavior, numerical robustness, and performance.

CDT++ already resolves CGAL 6.2 from its pinned vcpkg baseline. This issue is therefore primarily about using CGAL correctly and intentionally, not merely increasing a version number.

Primary references:

• CGAL 6.2 release notes
• CGAL 6.2 3D Triangulations manual
• CGAL 6.2 3D Triangulation Data Structure reference
• CGAL 6.2 kernel manual
• CGAL 6.2 3D Triangulations deprecated list

Motivation

CGAL is the foundation of CDT++ topology and geometry. The repository currently wraps and exposes a substantial part of Delaunay_triangulation_3, stores CGAL handles in cached containers, composes custom vertex and cell bases with info(), conditionally selects Parallel_tag, performs range insertion and vertex removal, calls low-level TDS flips, uses iterator/circulator idioms, and contains separate periodic and d-dimensional experiments.

The recent causal 2-to-3 move defect illustrates the boundary that must be explicit: CGAL can prove combinatorial flippability, but it does not know the CDT causal admissibility contract. A reference implementation should clearly separate CGAL's guarantees from CDT's stronger scientific invariants and document the lifetime effects of every topology mutation.

Current integration surfaces

Audit at least:

• include/Triangulation_traits.hpp
• include/Foliated_triangulation.hpp
• include/Ergodic_moves_3.hpp
• bistellar-flip implementation and tests
• include/Periodic_3_complex.hpp
• include/Periodic_3_triangulations.hpp
• include/Torus_d.hpp
• CGAL serialization, visualization, timers, generators, and test fixtures
• CMake/vcpkg feature selection, TBB linkage, compiler definitions, and CI coverage

Scope

Version, support, and deprecations

• Confirm the repository-owned vcpkg baseline resolves the intended CGAL 6.2 release on every supported platform.
• Compile representative CGAL surfaces with deprecation warnings enabled where supported.
• Inventory deprecated, compatibility-only, legacy, or undocumented CGAL APIs and assumptions.
• Record the CGAL compiler, Boost, GMP/MPFR, and TBB support contract used by CDT++.
• Review each future CGAL upgrade against release notes and package-specific deprecated lists.

Kernel and numerical policy

• Document the predicates and constructions on which CDT++ scientific correctness depends.
• Re-evaluate the current Exact_predicates_inexact_constructions_kernel choice against those requirements.
• Compare exact-construction or other filtered-kernel alternatives only where a concrete robustness problem justifies them.
• Add adversarial near-degenerate and co-spherical fixtures before changing the kernel.
• Measure construction, insertion, move, memory, and simulation costs for any kernel change.
• Keep the existing kernel when it remains the best correctness/performance tradeoff; modernization does not require novelty.

Exact arithmetic backend

• Audit which selected CGAL kernel, number types, and package features require GMP and MPFR rather than assuming the historical dependency remains necessary.
• Evaluate Boost.Multiprecision alternatives only where CGAL 6.2 explicitly supports them for CDT++ production surfaces.
• Benchmark representative CDT++ workloads for compile time, runtime, and peak memory before changing the exact-arithmetic backend.
• Verify numerical robustness and scientific correctness with the same adversarial near-degenerate, co-spherical, deterministic move, and simulation fixtures used to justify the kernel policy.
• Retain GMP/MPFR unless Boost.Multiprecision demonstrates equivalent correctness and acceptable performance; dependency reduction alone is not sufficient justification.
• If a transition is justified, update vcpkg features, CMake linkage, CI coverage, documentation, and the recorded dependency/support contract together.

Traits and triangulation data structure

• Audit Triangulation_vertex_base_with_info_3, Triangulation_cell_base_with_info_3, the Delaunay cell-base requirements, and custom TDS composition against current concepts.
• Determine whether CDT metadata should remain scalar info() values or use richer invariant-preserving types from Adopt parse-don't-validate architecture for domain invariants #101.
• Prefer CGAL's canonical Delaunay::Vertex_handle, Cell_handle, Facet, and Edge types over parallel std::pair or CGAL::Triple aliases where that removes ambiguity.
• Verify rebind, copy, move, swap, allocator, and concurrency behavior of the selected bases and TDS.
• Make the ownership and validity of cached handles explicit.

Traversal, lookup, and ranges

• Review every vertex, cell, edge, facet, incident-simplex, and circulator traversal.
• Use CGAL's handle ranges such as finite_vertex_handles(), finite_cell_handles(), finite_edges(), and finite_facets() where they improve type correctness and clarity.
• Retain iterator or circulator forms when they are semantically necessary or measurably better.
• Remove wrapper functions that merely forward to CGAL without adding a CDT invariant, safer ownership, or a useful abstraction boundary.
• Check lookup, point-location, and insertion-hint use against current APIs and workload characteristics.

Insertion, removal, and construction

• Verify bulk insertion of point/info pairs follows the efficient CGAL range-insertion path and preserves the required association between points and time labels.
• Audit spatial sorting, duplicate-point behavior, insertion ordering, location hints, and deterministic fixture expectations.
• Document which vertex, cell, edge, facet, iterator, and circulator handles become invalid after each insertion, removal, copy, swap, and repair operation.
• Ensure no cached topology survives an invalidating operation without a mandatory rebuild or generation check.
• Review causality-repair loops that remove vertices and retriangulate cavities for current preconditions and failure behavior.

Flips and CDT move semantics

• Verify every facet and edge flip against the CGAL 6.2 TDS preconditions and handle-invalidation rules.
• Separate CGAL combinatorial flippability from CDT topological, foliation, simplex-type, and causal admissibility.
• Use checked flip() where applicability is not proven.
• Consider flip_flippable() only when an invariant-preserving applicable-move type from Adopt parse-don't-validate architecture for domain invariants #101 proves the full CGAL precondition and tests demonstrate equivalence.
• Never infer CDT legality solely from a successful CGAL flip.
• Make failed and successful mutations atomic from the public manifold API.

Concurrency and lock ownership

• Resolve Fix parallel insertion/deletion into Delaunay triangulations #74 as the focused parallel insertion/deletion prerequisite.
• Make sequential versus parallel TDS selection an intentional repository option rather than an incidental consequence of CGAL_LINKED_WITH_TBB.
• Verify TBB and scalable-allocator linkage on every supported platform.
• Audit Lock_data_structure construction, ownership, lifetime, and association with triangulations returned or moved from helper functions.
• Test lock-failure outcomes and ensure failed concurrent operations leave state unchanged.
• Benchmark parallel construction/removal at representative sizes and retain it only where it is correct and beneficial.

Integration boundary and ownership

• Review mutable raw access to the underlying Delaunay triangulation and prevent callers from silently invalidating CDT geometry or cached handles.
• Define which operations belong in a thin CGAL adapter, in invariant-preserving CDT domain types, or directly at the call site.
• Keep CGAL types available where they are the clearest zero-overhead representation; do not add abstraction layers solely to hide the dependency.
• Coordinate handle-bearing applicable-move types and mutation boundaries with Adopt parse-don't-validate architecture for domain invariants #101.
• Coordinate portable persistence decisions with Make simulations reproducible and persistence portable #93 rather than treating CGAL stream output as a stable interchange format without evidence.

Peripheral CGAL packages

• Audit periodic triangulation, torus, d-dimensional, visualization, random-generator, timer, and I/O code against current package documentation.
• Either modernize and test supported surfaces or clearly mark/remove experimental and unsupported ones.
• Do not let unused legacy experiments determine the production kernel, dependency, or concurrency design.

Performance and observability

• Establish repeatable baselines for triangulation construction, causality repair, point location, bulk insertion, vertex removal, move preparation/execution, memory use, and representative simulations.
• Compare before/after topology and scientific observables, not only wall-clock time.
• Use CGAL profiling or diagnostic facilities where useful without making them runtime dependencies for normal builds.
• Document intentional deviations from current CGAL examples when CDT invariants require them.

Suggested PR sequence

1. Publish the complete CGAL usage/deprecation/lifetime inventory and performance baseline.
2. Correct build configuration, feature selection, TBB linkage, and lock-data-structure ownership; resolve Fix parallel insertion/deletion into Delaunay triangulations #74.
3. Modernize traits, base classes, canonical handle/simplex types, and kernel policy with focused robustness tests.
4. Modernize traversal, lookup, range insertion, removal, and cache invalidation.
5. Modernize flip integration together with the applicable-move boundary from Adopt parse-don't-validate architecture for domain invariants #101.
6. Audit or retire peripheral periodic, d-dimensional, visualization, generator, timer, and I/O surfaces.
7. Publish benchmarks, supported CGAL patterns, upgrade guidance, and final verification evidence.

Each PR must preserve a coherent buildable intermediate state and include behavior-level tests for any changed CGAL interaction.

Acceptance criteria

• Every production CGAL use is reviewed against CGAL 6.2 documentation and classified as retained, modernized, replaced, or removed with a reason.
• No CDT++ production path depends on a deprecated or undocumented CGAL API or unspecified invalid-handle behavior.
• Kernel choice is justified by documented predicate/construction requirements and adversarial numerical tests.
• The GMP/MPFR versus Boost.Multiprecision decision is documented with CGAL support evidence, reproducible compile-time/runtime/memory measurements, and adversarial correctness results; removal requires demonstrated equivalence.
• Vertex/cell bases and TDS composition satisfy current CGAL concepts and preserve CDT metadata correctly across copy, move, swap, insertion, removal, and flips.
• Traversal uses the clearest current CGAL handle/range/circulator API without unnecessary materialization.
• Bulk insertion, point/info association, spatial sorting, removal, and repair behavior are deterministic where the reference contract requires it.
• CGAL combinatorial validity and CDT causal admissibility are separate, explicit checks.
• Flip preconditions and cell-handle invalidation are encoded or documented at the mutation boundary.
• Mutable CGAL access cannot silently leave canonical geometry or caches stale.
• Sequential and parallel modes have intentional configuration, correct lock ownership, supported linkage, and focused tests; Fix parallel insertion/deletion into Delaunay triangulations #74 is resolved.
• Supported CI, sanitizer, and deterministic reference suites pass.
• Before/after benchmarks show no unexplained performance or memory regression; beneficial changes include reproducible measurements.
• Documentation explains the selected kernel, TDS composition, metadata storage, concurrency model, mutation/lifetime rules, and CGAL upgrade process.
• Scientific results remain unchanged unless a pre-existing defect is identified, independently reproduced, corrected, and covered by a deterministic regression.

Related work

• Fix parallel insertion/deletion into Delaunay triangulations #74 owns the existing parallel insertion/deletion and TBB-linkage defect.
• Correct Metropolis-Hastings transitions and Regge action calculations #92 corrects the scientific transition semantics that the integration must preserve.
• Adopt parse-don't-validate architecture for domain invariants #101 owns invariant-preserving CDT domain types and the applicable-move boundary.
• Make simulations reproducible and persistence portable #93 owns portable persistence and reproducibility.
• Publish deterministic C++ reference fixtures for Rust comparison #94 should verify the modernized integration using deterministic fixtures, cross-implementation comparisons, and sanitizers.