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"]
cuda = ["dep:cudarc", "stochastic-rs-stochastic/cuda"]
metal       = ["dep:metal", "stochastic-rs-stochastic/metal"]
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 = "3.0.0-beta.3" }

Common gotchas

• Linear algebra needs no feature at all. Cholesky, SVD, eigen and least squares run on the pure-Rust faer and are always compiled in; the BLAS-backed feature flag from 2.x was removed in 3.0.
• cuda requires 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.