PointCloud Voronoi Construction Options

These options live under pointcloud_voronoi.construction: and control how the Voronoi tessellation is built once particles are loaded. All keys are optional; the defaults match the long-standing CGAL-only behavior.

dataset_type: 'pointcloud_voronoi'

pointcloud_voronoi:
  hilbert_bits: 8
  loader: "gadget"
  gadget:
    path: ./snapdir_099
    fields: ["PositionX", "PositionY", "PositionZ", "Density"]

  construction:
    bounded_tesselation: false           # debug-only; see below
    ghost_thickness: -1.0                # PBC/CUBE_OLD only; -1 = auto
    min_face_area: -1.0                  # -1 = no face-area filter
    post_cleanup_sanity_checks: true     # validate cell topology after build

    # SYCL Voronoi (experimental; default false)
    use_sycl_voronoi: false
    use_cgal_fallback: true              # only meaningful when use_sycl_voronoi=true

Default backend: CGAL

With use_sycl_voronoi: false (the default), the Voronoi mesh is built by CGAL's exact-predicates Delaunay triangulation. This path is the long-standing production backend and is the safe choice for any new dataset.

Construction options on the CGAL path:

Key	Type	Default	Description
`bounded_tesselation`	bool	`false`	Drop infinite-vertex cells from the convex hull. Debug only — typical pipelines need either `CUBE_OLD` (clipped to box) or `PERIODIC` (with ghosts). Selected here as the BoundaryCondition.
`ghost_thickness`	float	`-1.0`	Width of the ghost shell appended around the box for `PERIODIC` and `CUBE_OLD`. `-1` lets the code pick a safe value from the local cell density.
`min_face_area`	float	`-1.0`	If ≥ 0, drop Voronoi face contributions below this area to suppress slivers from near-collinear configurations. Off by default.
`post_cleanup_sanity_checks`	bool	`true`	After ghost-cleanup, run a few O(N) checks (no self-neighbors, no infinite faces, neighbor symmetry). Costs ~5 % wall; recommended on.

SYCL Voronoi (experimental)

use_sycl_voronoi: true selects a SYCL-native implementation of Ray et al. 2018 Meshless Voronoi on the GPU: each cell clips against its K nearest neighbors with a security-radius termination test, growing K via tiered retries. Cells that exhaust the tiers fall through to a per-cell CGAL fallback so the final neighbor list stays geometrically correct — currently this fallback path is unoptimized and, when it fires on a non-trivial fraction of cells, can take time comparable to a CGAL-only construction.

This backend will offer a consistent, SYCL-first parallelization within THOR.

Status: experimental

Validated against CGAL byte-identically on the unit-test suite (thor_tests "[voronoi][sycl][periodic]") and on bench_voronoi at N = 1 M and N = 3 M for both CUBE_OLD and PERIODIC boundary modes.
End-to-end on TNG50-4 (18.5 M particles, PBC) completes on both OMP and a 24 GB CUDA GPU, with the final neighbor list matching the CGAL reference on all converged cells. Residual cells (a few hundred) are routed to the per-cell CGAL fallback automatically.
Not yet recommended as the default: we have not tested this on production, high-resolution cosmological simulations with highly inhomogeneous point distributions yet.

For a production rollout, leave use_sycl_voronoi: false per-config and opt in case-by-case after spot-checking the SYCL output against CGAL on the specific dataset.

Construction options on the SYCL path

Key	Type	Default	Description
`use_sycl_voronoi`	bool	`false`	Opt in to the SYCL-native Ray et al. 2018 implementation. When `false`, all keys below are ignored.
`use_cgal_fallback`	bool	`true`	When the SYCL kernel + retry tiers leave any cell un-converged (`!= OK_SECURITY_CLOSED`), replace those cells' neighbor lists with CGAL's exact output. Set `false` to emit the SYCL best-effort output instead — faster but those cells' neighbor lists may be a superset of the true Voronoi neighbors. Only set `false` for benchmarking the SYCL path in isolation.

The other CGAL-path keys (bounded_tesselation, ghost_thickness, min_face_area, post_cleanup_sanity_checks) apply unchanged on the SYCL path — ghost_thickness controls ghost shell width on both backends, and post_cleanup_sanity_checks validates the final merged CSR regardless of which backend produced each cell.