# Debug Environment Variables
Comprehensive reference for all `DELAUNAY_*` environment variables used for
runtime diagnostics and debugging.
**Build mode**: most variables are **debug-only** — gated behind
`#[cfg(debug_assertions)]` and have no effect in release builds. Variables
marked `[release]` in the tables below are also active in release builds
(read without a debug-assertions gate). `[diagnostics]` additionally requires
the `diagnostics` Cargo feature, in either build mode.
This matters for large-scale investigations that need to run under
`cargo test --release` or `cargo bench`.
**Activation**: most variables are presence-activated (any value works, e.g.
`DELAUNAY_DEBUG_CAVITY=1`). Variables that read a **value** are marked below.
**Initialization and threads**: set diagnostic variables before launching the
process. Several hot-path switches are cached on first use with `OnceLock` or
`LazyLock`, so they are not live per-owner or per-thread settings. Concurrent
calls share these cached values. One-shot traces select one caller across the
process; scheduling determines which caller wins, and claiming a trace does not
mean its output has finished. Tests should inject configuration directly rather
than mutate the process environment.
**Output**: all diagnostic output uses the `tracing` crate. Enable with a
`tracing-subscriber` (e.g. `RUST_LOG=debug`).
---
## Contents
- [Construction & Insertion](#construction--insertion)
- [Point Location](#point-location)
- [Conflict Region](#conflict-region)
- [Cavity & Hull](#cavity--hull)
- [Orientation](#orientation)
- [Neighbor Wiring](#neighbor-wiring)
- [Flip Repair](#flip-repair)
- [Predicates & Validation](#predicates--validation)
- [Point Generation](#point-generation)
- [Large-Scale Debug Test Harness](#large-scale-debug-test-harness)
- [Proptest Configuration](#proptest-configuration)
- [Benchmarks](#benchmarks)
- [Miscellaneous](#miscellaneous)
---
## Construction & Insertion
| `DELAUNAY_INSERT_TRACE` | presence | `delaunay/construction.rs` | `[release]` Per-insertion summary (vertex index, location, conflict size, suspicion flags) |
| `DELAUNAY_BULK_PROGRESS_EVERY` | **value** (integer) | `delaunay/construction.rs` | `[release]` Periodic batch progress for post-simplex bulk vertices. |
| `DELAUNAY_DEBUG_CAVITY_REDUCTION_ONCE` | presence | `triangulation/insertion.rs` | `[release]` One-shot cavity-reduction trace. |
| `DELAUNAY_DEBUG_RETRYABLE_SKIP` | presence | `triangulation/insertion.rs` | `[release]` Retryable conflict skip trace with attempt and rollback context. |
| `DELAUNAY_DEBUG_SHUFFLE` | presence | `delaunay/construction.rs` | Logs vertex shuffle order during batch construction |
| `DELAUNAY_DUPLICATE_METRICS` | presence | `triangulation/insertion.rs` | `[release]` Duplicate-detection metrics (spatial hash grid stats) |
## Point Location
| `DELAUNAY_DEBUG_LOCATE` | presence | `triangulation/insertion.rs` | Locate stats (walk steps, hint usage, fallback) |
| `DELAUNAY_DEBUG_VALIDATE_LOCATE` | presence | `core/algorithms/locate.rs` | Cross-validates locate result against brute-force scan |
## Conflict Region
| `DELAUNAY_DEBUG_CONFLICT` | presence | `core/algorithms/locate.rs` | Per-simplex insphere classification during BFS, including BFS boundary simplices |
| `DELAUNAY_DEBUG_CONFLICT_PROGRESS` | presence | `core/algorithms/locate.rs` | Periodic progress during large BFS traversals |
| `DELAUNAY_DEBUG_CONFLICT_PROGRESS_EVERY` | **value** (integer) | `core/algorithms/locate.rs` | Interval for progress logging (default: dimension-dependent) |
| `DELAUNAY_DEBUG_CONFLICT_VERIFY` | presence | `triangulation/insertion.rs` | `[release]` `[diagnostics]` Brute-force BFS conflict-region completeness check |
| `DELAUNAY_DEBUG_RIDGE_FAN_ONCE` | presence | `core/algorithms/locate.rs` | `[release]` One-shot ridge-fan dump (ridge verts, boundary facets, extras) |
## Cavity & Hull
| `DELAUNAY_DEBUG_CAVITY` | presence | `core/algorithms/insertion.rs`, `core/algorithms/locate.rs` | Cavity boundary, simplex provenance, orientation |
| `DELAUNAY_DEBUG_HULL` | presence | `core/algorithms/insertion.rs`, `triangulation/insertion.rs` | Hull extension visibility, locate stats, neighbor summary |
| `DELAUNAY_DEBUG_HULL_DETAIL` | presence | `core/algorithms/insertion.rs` | Per-facet orientation details during visibility computation |
## Orientation
| `DELAUNAY_DEBUG_ORIENTATION` | presence | `triangulation/orientation.rs`, `triangulation/insertion.rs` | Orientation canonicalization and insertion audit |
## Neighbor Wiring
| `DELAUNAY_DEBUG_NEIGHBORS` | presence | `core/algorithms/insertion.rs`, `triangulation/insertion.rs` | Neighbor symmetry after cavity/hull wiring |
| `DELAUNAY_DEBUG_RIDGE_LINK` | presence | `core/algorithms/insertion.rs`, `triangulation/insertion.rs`, `topology/manifold.rs` | Ridge-link checks |
| `DELAUNAY_FORCE_GLOBAL_NEIGHBOR_REBUILD` | presence | `triangulation/repair.rs` | `[release]` Bypass local repair; use global rebuild for A/B isolation. |
## Flip Repair
| `DELAUNAY_REPAIR_TRACE` | presence | `flips/` | Per-flip trace: enqueue, skip, apply, context details |
| `DELAUNAY_REPAIR_DEBUG_FACETS` | presence | `flips/` | Facet-level flip skip reasons (degenerate, duplicate, non-manifold, existing simplex) |
| `DELAUNAY_REPAIR_DEBUG_POSTCONDITION_FACET` | presence | `flips/` | `[release]` One-shot snapshot of the first unresolved k=2 facet with last-flip overlap |
| `DELAUNAY_REPAIR_DEBUG_PREDICATES` | presence | `flips/` | Insphere classification details for k=2 and k=3 violation checks |
| `DELAUNAY_REPAIR_DEBUG_RIDGE` | presence | `flips/` | Ridge context snapshots during k=3 repair |
| `DELAUNAY_REPAIR_DEBUG_RIDGE_LIMIT` | **value** (integer) | `flips/` | Maximum ridge debug snapshots (default: 64) |
| `DELAUNAY_REPAIR_DEBUG_RIDGE_MIN_MULTIPLICITY` | **value** (integer) | `flips/` | `[release]` Skip low-mult; emit when `found >= N` (default: 0). |
| `DELAUNAY_REPAIR_DEBUG_SUMMARY` | presence | `flips/` | Per-attempt repair summary (flips, checks, cycles, ambiguous, skips) |
## Predicates & Validation
| `DELAUNAY_STRICT_INSPHERE_CONSISTENCY` | presence | `geometry/robust_predicates.rs` | `[release]` Cached exact-vs-distance insphere diagnostic |
| `DELAUNAY_DEBUG_LU_FALLBACK` | presence | `geometry/util/circumsphere.rs` | Logs when a near-singular LU solve falls back to an exact rational solve |
## Point Generation
| `DELAUNAY_DEBUG_RANDOM_BUILDER` | presence | `geometry/util/triangulation_generation.rs` | Random builder generation and retry traces |
| `DELAUNAY_DEBUG_RANDOM_POINTSET_RETRIES` | presence | `geometry/util/triangulation_generation.rs` | Retry attempts during random point set generation |
## Large-Scale Debug Test Harness
These variables configure `tests/large_scale_debug.rs` and run in both debug
and release builds.
| `DELAUNAY_LARGE_DEBUG_N` | **value** | Number of vertices (global default) |
| `DELAUNAY_LARGE_DEBUG_N_{D}D` | **value** | Per-dimension vertex count override (e.g. `_N_3D=35`) |
| `DELAUNAY_LARGE_DEBUG_SEED` | **value** (hex) | Master RNG seed |
| `DELAUNAY_LARGE_DEBUG_CASE_SEED` | **value** (hex) | Per-case RNG seed (global default) |
| `DELAUNAY_LARGE_DEBUG_CASE_SEED_{D}D` | **value** (hex) | Per-dimension case seed override |
| `DELAUNAY_LARGE_DEBUG_DISTRIBUTION` | **value** | `ball` or `box` |
| `DELAUNAY_LARGE_DEBUG_BALL_RADIUS` | **value** | Radius for ball distribution |
| `DELAUNAY_LARGE_DEBUG_BOX_HALF_WIDTH` | **value** | Half-width for box distribution |
| `DELAUNAY_LARGE_DEBUG_CONSTRUCTION_MODE` | **value** | `new` (batch) or `incremental` |
| `DELAUNAY_LARGE_DEBUG_INITIAL_SIMPLEX` | **value** | Batch initial simplex strategy: `max-volume` (default), `balanced`, or `first` |
| `DELAUNAY_LARGE_DEBUG_DEBUG_MODE` | **value** | `cadenced` (ridge-link) or `strict` (per-insertion vertex-link) |
| `DELAUNAY_LARGE_DEBUG_SHUFFLE_SEED` | **value** | Vertex shuffle seed |
| `DELAUNAY_LARGE_DEBUG_PROGRESS_EVERY` | **value** | Incremental progress interval; batch fallback if the canonical knob is unset |
| `DELAUNAY_LARGE_DEBUG_VALIDATE_EVERY` | **value** | Validation interval |
| `DELAUNAY_LARGE_DEBUG_VALIDATION` | **value** | Scope: `full` (Levels 1-5), `realization` (Level 4), or `construction` (Levels 1-3 + 5) |
| `DELAUNAY_LARGE_DEBUG_REPAIR_EVERY` | **value** | Batch/incremental repair interval (default: 1) |
| `DELAUNAY_LARGE_DEBUG_REPAIR_MAX_FLIPS` | **value** | Flip budget override |
| `DELAUNAY_LARGE_DEBUG_MAX_RUNTIME_SECS` | **value** | Timeout, plus up to 100 ms waiting for diagnostics (0 = no cap) |
| `DELAUNAY_LARGE_DEBUG_MAX_SKIP_PCT` | **value** | Maximum skipped-vertex percentage before failing (default: 5.0) |
| `DELAUNAY_LARGE_DEBUG_ALLOW_SKIPS` | presence | Allow any number of vertex insertion skips |
| `DELAUNAY_LARGE_DEBUG_SKIP_FINAL_REPAIR` | presence | Skip final global repair pass |
| `DELAUNAY_LARGE_DEBUG_FALLBACK_REBUILD` | presence | Allow final conversion to rebuild after bounded flip repair fails (disabled by default) |
| `DELAUNAY_BATCH_REPAIR_TRACE` | presence | Trace cadenced batch-repair seed counts, flips, queues, and elapsed time |
The runtime-cap guard cancels and joins its watchdog on normal return or panic.
Once the timeout wins, a separate reporter gets a 100 ms grace period to write
and flush the final diagnostic. The watchdog then aborts without joining that
reporter, even if stderr or logging is blocked. The final message may therefore
be missing or incomplete; a reporting failure must not suppress the abort.
## Proptest Configuration
These variables configure property tests in `tests/proptest_*.rs`.
| `DELAUNAY_PROPTEST_REJECT_STATS` | presence | Log rejection statistics |
| `DELAUNAY_PROPTEST_COVERAGE_LOGS` | presence | Log coverage statistics |
| `DELAUNAY_ALLOW_SLOW_COSPHERICAL_FILTER` | presence | Allow slow cospherical point filtering |
| `DELAUNAY_EMPTY_CIRCUMSPHERE_MAX_VERTICES_{D}D` | **value** | Cap 4D or 5D vertices in empty-circumsphere properties |
## Benchmarks
### CI Performance Suite
These variables configure `benches/ci_performance_suite.rs` and run in
release builds only.
| `DELAUNAY_BENCH_DISCOVER_SEEDS` | presence | Seed-discovery mode: find and print stable seeds instead of running benchmarks |
| `DELAUNAY_BENCH_DISCOVER_SEEDS_LIMIT` | **value** (integer) | Maximum seeds to try per (dim, count) pair during discovery or fallback (default: 2000) |
| `DELAUNAY_BENCH_EXPORT_METRICS` | presence | Metric-only mode: print `api_benchmark_metric` vertex/simplex counts; optional `tds_new` filter |
### Profiling Suite
These variables configure `benches/profiling_suite.rs`.
| `DELAUNAY_BENCH_SEED` | **value** (decimal or hexadecimal integer) | Deterministic base seed for random point generation |
| `DELAUNAY_BENCH_RETRY_ATTEMPTS` | **value** (positive integer) | Shuffled construction retry count (default: 6; zero is clamped to 1) |
### Pachner Stress Diagnostics and Benchmarks
`benches/pachner_stress.rs` now benchmarks stable 4D move fixtures and
forward/inverse round trips. Use `just bench-pachner-stress*` for Criterion
timing, or run `pachner-stress` / `just pachner-stress*` for
direct 3D/4D diagnostic workloads with explicit command-line arguments.
| `MOVES_PER_SAMPLE` | **value** (integer) | `[release]` Number of independent fixture clones per Pachner stress Criterion sample |
## Miscellaneous
| `DELAUNAY_DEBUG_UNUSED_IMPORTS` | presence | `geometry/util/` | Internal call traces for measures, circumspheres, and point/triangulation generators |