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.

Known operational caveat: launching several independent THOR runs that all construct CGAL Voronoi tessellations at the same time can deadlock inside CGAL, even though the runs are separate process instances. Avoid concurrent mesh construction on the same node; build once with mesh_cache_mode: "auto" or "save" and reuse the cached mesh for repeated runs. See Troubleshooting.

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.