Feature flags

Cargo features in this workspace are opt-in. The default build links no GPU, no BLAS, no Python, no neural surrogates — just the pure Rust core.

The matrix

The GPU / accelerator features above select a sampling backend chosen at compile time with .on::<B>() — see the Backends concept page.

Propagation

A feature on the umbrella stochastic-rs crate maps to a feature on the relevant sub-crate. Example from the umbrella Cargo.toml:

[features]
default = []
ai      = ["stochastic-rs-ai"]
viz     = ["stochastic-rs-viz"]
cuda-native = ["dep:cudarc", "stochastic-rs-stochastic/cuda-native"]
metal       = ["dep:metal", "stochastic-rs-stochastic/metal"]
openblas = [
  "stochastic-rs-stats/openblas",
  "stochastic-rs-quant/openblas",
]
dual-stream-rng = [
  "stochastic-rs-core/dual-stream-rng",
  "stochastic-rs-distributions/dual-stream-rng",
]

If you depend on a sub-crate directly (recommended for lean builds), you enable the feature on that sub-crate:

stochastic-rs-stats = { version = "2.2.0", features = ["openblas"] }

Common gotchas

• openblas is platform-specific. On macOS use RUSTFLAGS=-L/opt/homebrew/opt/openblas/lib or the system linkage. On Linux apt install libopenblas-dev.
• cuda-native / gpu-cuda require the CUDA toolkit on the build machine. CI builds do not install it by default.
• ai is heavy. It pulls in candle-core, which is a substantial ML stack. Only enable when you actually need NN surrogates.

Defining a new feature

When adding a new optional dependency, follow the feature-flag-management SKILL. The short version:

1. Add the feature on the owner sub-crate (where the optional dependency lives).
2. Re-export the feature on the umbrella via feature_x = ["stochastic-rs-sub/feature_x"].
3. Update the matrix above and the per-feature CI job.
4. Add a cfg-gated module so default builds don't pull in the dep.