Collapse star reuse

[IasonManolas]

Summary

Profiling the collapse pass found four independent costs, all coming from re-walking or
re-collecting the same handful of cells and vertices around a candidate collapse edge. Four
commits:

• memoize surface_patch_index over the collapse scan: can_be_collapsed() calls
  surface_patch_index(v) for both endpoints of every non-boundary edge, and it walks a
  vertex's whole incident-facet star with no early exit. collapse_short_edges()'s initial
  scan over all finite edges reaches the same vertex once per incident edge, so its star gets
  walked as many times as it has edges. The scan does not modify the mesh, so a cache scoped to
  the scan replaces the repeats with a hash lookup after the first. The cache is opt-in via a
  pointer defaulting to null, since can_be_collapsed() is also called after individual
  collapses (when the cache would be stale) to re-evaluate newly-incident edges.
• settle a collapse's ring test once for all three attempts: collapse_edge() calls
  is_valid_collapse(edge, type, new_pos, c3t3), which walks the star of v0 and/or v1 into
  a heap vector, runs an orientation predicate per cell, and then runs a ring test over the
  cells around the edge. On failure with TO_MIDPOINT the whole thing repeats for TO_V0 and
  again for TO_V1. Further down, the manifold test and CollapseTriangulation build
  cells_to_insert from those same two stars a fourth time. The ring test depends on neither
  the collapse type nor the new position, so it is hoisted ahead of the orientation cascade (it
  is also the cheap one: one cell circulation, no allocation, no orientation predicate), and
  each star is now collected once, lazily, into a small_vector and handed to every attempt and
  to cells_to_insert.
• read incident_subdomains straight off the star walk: incident_subdomains(v) collected
  the whole incident-cell star into a heap vector and then read nothing from it but
  subdomain_index(). Emitting straight to the output iterator as the star is walked removes
  one heap allocation per call on the hottest star-walk site in the profile
  (nb_incident_subdomains <- topology_test <- collapse_edge).
• nb_incident_subdomains(v, c3t3) > 1 without counting the whole star: the count walks
  every cell around v to build a set of distinct subdomain indices, and topology_test's only
  use of it is the > 1 comparison. A traversal that stops at the second distinct index -
  reusing the TDS's own conflict-mark flags for the walk, the same traversal
  TDS_3::incident_cells_3() performs - answers the same question after a handful of cells
  instead of the whole star.

Testing

Verdict equivalence. All four changes are pure reorderings, caches, or streaming
equivalents over read-only predicates; none change which collapse is ultimately selected or in
what order. Full test suite (ctest, all executables in test/Tetrahedral_remeshing) passes
with all four commits applied.

Byte-identical output, all four commits applied to cgal/main:

mesh	tets	byte-identical
bear	~90K	YES
bunny00	~260K	YES
101556.mesh (Thingi10K)	3,521,237	YES

Performance. perf stat -e instructions, Linux, Release, sequential, against plain
cgal/main.

mesh	iterations	cgal/main instr	this PR	Δ instr	this PR wall
bear	10	67.01 G	64.66 G	-3.51%	23.06 s
bunny00	10	148.80 G	142.08 G	-4.52%	66.80 s
101556.mesh	3	2441.77 G	2349.47 G	-3.78%	1183.75 s

Release Management

• Affected package(s): Tetrahedral_remeshing
• License and copyright ownership: unchanged