Optional compiled D-vine sampling

Prepare an accelerated sampler from an already fitted model:

sampler = fitted_model.prepare_sampler(
    backend="auto", num_threads=8,
    cache_dir="/path/to/writable/kernel/cache",
)
print(sampler.backend, sampler.fallback_reason)
samples = sampler.simulate(5000, seed=130)

Use no more threads than your CPU allocation. Preparation compiles a cached C++17/OpenMP kernel and packs the existing h tables. Repeated calls reuse those tables. backend="auto" uses NumPy when the compiler is unavailable, a build or load fails, the build fails its numerical check, the vine is unsupported, or packed memory exceeds the configured limit. The selected backend and fallback_reason make this visible. backend="compiled" raises on these failures; backend="numpy" skips compilation and packing. Existing model simulate and inverse_rosenblatt calls retain their NumPy behavior.

The handle requires an unchanged fitted vine. Reprepare after refitting or manually editing its tables. Saved models do not serialize compiled handles; prepare a fresh handle after loading. The sampler preserves the original seeded draws and global NumPy random-stream behavior. Call sampler.inverse_rosenblatt(uniforms) to supply independent uniforms yourself.

Build and identity tests

A GCC-compatible C++17 compiler with OpenMP is required for acceleration. Run compilation and tests on a compute node. Install from the source release or wheel; both contain the C++ source. The source distribution also includes this document and the preservation tests. Nothing is downloaded during kernel compilation. To build explicitly:

from vdc.vine.compiled_sampler import build_kernel
build_kernel("/path/to/cache/sampler.so", compiler="g++")
sampler = fitted_model.prepare_sampler(kernel="/path/to/cache/sampler.so",
                                      backend="auto", num_threads=8)

Automatic builds use cache_dir, then VDC_KERNEL_CACHE, then ~/.cache/vdc/sampler. Cache keys include source, compiler and platform; completed builds are published atomically. Each kernel undergoes a small NumPy-identity check once per process before automatic use. This check does not replace full qualification on a new platform. GCC 8.5.0 on the recorded Linux node is the measured camera-ready configuration.

From an unpacked source release, run:

python -m pytest tests/test_compiled_sampler.py tests/test_prepared_sampler.py tests/test_hfunc_vectorized_inverse.py

The kernel uses float64 and disables fast math and multiply-add contraction. Tests cover generated coordinates, edge orientations, truncation, boundaries, flat CDF sections, thread counts, RNG behavior, save/load, failed builds and loads, memory fallback and cache reuse. No estimator weights, density grids, likelihoods or h-function equations are changed by selecting this backend.

Supported models and memory

Acceleration supports legacy D-vines with default square cell-center grids, non-spline HFuncLookup objects, and hfunc_vectorized_inverse=True during fitting. It supports reversed edges and omitted independence edges in truncated vines. Other vine types, experimental exact-density models, splines and non-default grids use the fallback in automatic mode.

Packed tables require d * (d - 1) / 2 * 2 * m * m * 8 additional bytes. They are a copy of the fitted h tables: 64 KiB per edge at m=64, 309.375 MiB at d=100, and about 7.6 GiB at d=500. A 128-grid uses four times as much. The default max_table_bytes=512*1024**2 prevents those large allocations and falls back before compiling or packing. Set a larger limit explicitly only when the allocation permits it; None disables the cap. Validation can use additional temporary memory, so the cap is on packed storage, not total RSS.

The paper's sampling comparison uses 5,000 S&P100 draws at d=100: 0.72 s including packing versus 0.92 s for TLL, both with eight CPU threads. Kernel compilation was a separate one-time 0.37 s. VDC fits a D-vine and TLL fits a regular vine. This does not establish speed at d=200/500 or for the retrained exact-density models. The paper's scripts and saved outputs are in the paper reproduction guide.