perf: opt-in (EnableFast) order-relaxed threading — cutter + contour

[akaszynski]

Opt-in non-exact fast mode — default stays byte-exact

By default fvtk remains a byte-exact drop-in: this cutter runs serial and matches stock VTK exactly. Users opt in to the threaded fast path with fvtk.EnableFast() (or FVTK_FAST=1). This addresses the contract concern on the earlier revision — non-exactness is now strictly opt-in, not default.

import fvtk
fvtk.EnableFast()      # opt in to non-exact threaded fast paths
# ... vtkCutter on a linear UG now threads (order-relaxed) ...
fvtk.DisableFast()     # back to byte-exact (default)

Mechanism

• fvtk::FastModeEnabled() / fvtk::RunFastFilterParallel() (Common/Core): the latter threads via the re-entrancy-guarded RunSafeFilterParallel only when fast mode is on (env FVTK_FAST, read live → runtime-toggleable); otherwise runs serially (byte-exact).
• vtk3DLinearGridPlaneCutter's EXECUTE_SMPFOR macro now uses RunFastFilterParallel.
• fvtk.EnableFast() / DisableFast() / IsFastEnabled() Python API set/clear FVTK_FAST.

Why opt-in (the non-exactness)

Profiling (py-spy --native) put 35% of vtkCutter self-time in this filter's ExtractEdges. Threading it reorders the per-thread triangle buffers, so output cell order differs from stock and varies run-to-run. Points, interpolated point scalars, and the constant plane normal are thread-invariant. So fast mode trades cell-order reproducibility for the speedup — your call, per call site.

Validation (in-container)

• Default (no EnableFast): byte-exact — cutter runs serial, identical to stock.
• EnableFast: order-relaxed gate passes — op_cutter_linear (f32/f64 × sizes 30/40) sets FVTK_FAST=1; fvtk threads, stock stays serial; compared order-relaxed (points/point-data strict; same triangle multiset carrying cell-data). Thread-count invariance (1/4/8) holds.
• strict compare (seq vs threaded) fails — confirms threading actually engages.

Test infra

• compare.py: order-relaxed mesh-equality mode (per-op order_relaxed flag via the manifest).
• ops.py: op_cutter_linear, order_relaxed=True.
• test_smp_determinism.py: cutter_linear in THREADED_OPS.

Deferred

Contour (vtkContour3DLinearGrid): surface-normal averaging is reduction-order-dependent → threading perturbs normal values, not just order → not order-relaxable even with EnableFast. Left serial.

🤖 Generated with Claude Code

[akaszynski]

Added contour (vtkContour3DLinearGrid, 44% of vtkContourFilter self-time) to the same EnableFast lane.

Gated on !ComputeNormals: a contour that computes normals stays serial / byte-exact (its normal averaging sums cell-normals at shared points in cell order, so reordered threaded cells would perturb normal values, not just order). Normals-off threads order-relaxed like the cutter.

Validated in-container:

• bitexact: 284 passed (+6 contour_linear: 4 order-relaxed + 2 thread-count-invariance).
• Gate proof: contour with normals + EnableFast → deterministic run-to-run + byte-exact; without normals → threads (conn varies run-to-run).

PR now covers cutter + contour under one opt-in contract.