stochastic-rs
Concepts

Feature flags

Cargo features in stochastic-rs — what each one pulls in, how they propagate across the workspace, and which features your crates need.

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

FeatureOwner cratePulls inUse when
aiumbrellastochastic-rs-ai, candle-coreNN volatility surrogates
cuda-stochasticcudarc + cuFFT + NVRTCNVIDIA GPU: FGN / fBM (cuFFT) and the Euler engine kernels every other process runs on (Cuda backend, f32 or f64)
metal-stochasticmetalApple GPU: FGN / fBM and the Euler engine in hand-written MSL (Metal backend, f32)
accelerate-stochasticApple vDSP (system framework)macOS CPU-FFT FGN / fBM (Accelerate backend; a host device for every process)
python-py (cdylib)pyo3, numpyBuilding the wheel via maturin
ai-metalumbrellacandle-core/metalcandle's Metal back-end for surrogate training (ai::device::best_available); CUDA comes from candle-core/cuda in the consuming manifest
ai, metal, cuda, accelerate-pythe sub-crate features aboveSource-build extras of the Python module (maturin develop --features …): the surrogates + calibrate_surrogate, and the device back-ends behind the process classes' device=; none of them is in the published wheels
hotpathumbrellahotpathHot-path profiling: per-function timing of the instrumented paths
hotpath-allocumbrellahotpath with allocation trackingThe same profiling plus per-function allocation counts
jemallocumbrellatikv-jemallocatorjemalloc as the global allocator; it wins if mimalloc is enabled too
mimallocumbrellamimallocmimalloc as the global allocator
vizumbrella → -quant, -aiplotlyHTML plots: the SABR smile calibrator's plots, and the surrogate fit plots when ai is on too (viz alone does not pull in ai)
yahooumbrella → -quantyahoo_finance_api, polars, time, tokio-testExperimental: downloading Yahoo Finance market data into cleaned OHLCV series (quant::yahoo, market::yahoo_provider)
dual-stream-rng-core, -distributionsnone (additive)~2–6 % bulk Normal-Ziggurat speedup on Apple Silicon (Exp at parity) — see seeding

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 = ["dep:stochastic-rs-ai", "stochastic-rs-ai/quant"]
cuda = ["dep:cudarc", "cudarc/cufft", "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-rc.4" }

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.
Edit on GitHub

Last updated on

On this page