# Feature flags

URL: https://stochastic.rust-dd.com/docs/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

| Feature                             | Owner crate                | Pulls in                                            | Use when                                                                                                                                                                                                                   |
| ----------------------------------- | -------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ai`                                | umbrella                   | `stochastic-rs-ai`, `candle-core`                   | NN volatility surrogates                                                                                                                                                                                                   |
| `cuda`                              | `-stochastic`              | `cudarc` + cuFFT + NVRTC                            | NVIDIA GPU: FGN / fBM (cuFFT) and the Euler engine kernels every other process runs on (`Cuda` backend, `f32` or `f64`)                                                                                                    |
| `metal`                             | `-stochastic`              | `metal`                                             | Apple GPU: FGN / fBM and the Euler engine in hand-written MSL (`Metal` backend, `f32`)                                                                                                                                     |
| `accelerate`                        | `-stochastic`              | Apple vDSP (system framework)                       | macOS CPU-FFT FGN / fBM (`Accelerate` backend; a host device for every process)                                                                                                                                            |
| `python`                            | `-py` (cdylib)             | `pyo3`, `numpy`                                     | Building the wheel via maturin                                                                                                                                                                                             |
| `ai-metal`                          | umbrella                   | `candle-core/metal`                                 | candle'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` | `-py`                      | the sub-crate features above                        | Source-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 |
| `hotpath`                           | umbrella                   | `hotpath`                                           | Hot-path profiling: per-function timing of the instrumented paths                                                                                                                                                          |
| `hotpath-alloc`                     | umbrella                   | `hotpath` with allocation tracking                  | The same profiling plus per-function allocation counts                                                                                                                                                                     |
| `jemalloc`                          | umbrella                   | `tikv-jemallocator`                                 | jemalloc as the global allocator; it wins if `mimalloc` is enabled too                                                                                                                                                     |
| `mimalloc`                          | umbrella                   | `mimalloc`                                          | mimalloc as the global allocator                                                                                                                                                                                           |
| `viz`                               | umbrella → `-quant`, `-ai` | `plotly`                                            | HTML plots: the SABR smile calibrator's plots, and the surrogate fit plots when `ai` is on too (`viz` alone does not pull in `ai`)                                                                                         |
| `yahoo`                             | umbrella → `-quant`        | `yahoo_finance_api`, `polars`, `time`, `tokio-test` | Experimental: downloading Yahoo Finance market data into cleaned OHLCV series (`quant::yahoo`, `market::yahoo_provider`)                                                                                                   |
| `dual-stream-rng`                   | `-core`, `-distributions`  | none (additive)                                     | \~2–6 % bulk Normal-Ziggurat speedup on Apple Silicon (Exp at parity) — see [seeding](/docs/concepts/seeding#dual-stream-rng-feature)                                                                                      |

The GPU / accelerator features above select a sampling backend chosen at compile
time with `.on::<B>()` — see the [Backends](/docs/concepts/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`:

```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:

```toml
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](https://github.com/rust-dd/stochastic-rs/blob/main/.claude/skills/feature-flag-management/SKILL.md).
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.

