# Workspace layout

URL: https://stochastic.rust-dd.com/docs/getting-started/workspace-layout

> How the stochastic-rs Cargo workspace is organised — sub-crates, dependency topology, and how the umbrella re-exports preserve v1.x import paths.

`stochastic-rs` is a Cargo workspace with **8 sub-crates** as siblings
under the workspace root. The `stochastic-rs` umbrella crate keeps the
v1.x public API by re-exporting everything via `pub use`.

```
stochastic-rs/                        (workspace root + umbrella crate)
├── stochastic-rs-core/               simd_rng (foundation)
├── stochastic-rs-distributions/      FloatExt, SimdFloatExt, 18 of 29 distributions
├── stochastic-rs-stochastic/         ProcessExt, 127 processes
├── stochastic-rs-copulas/            BivariateExt, MultivariateExt, 21 copulas (13 + 8)
├── stochastic-rs-stats/              MLE, Hurst, realised, stationarity, …
├── stochastic-rs-quant/              ModelPricer, calibration, vol surface
├── stochastic-rs-ai/                 Neural surrogates (feature-gated)
└── stochastic-rs-py/                 PyO3 cdylib (308 entries)
```

## Dependency topology

```
        stochastic-rs-core (simd_rng)
                  │
                  ▼
   stochastic-rs-distributions (FloatExt, SimdFloatExt)
        ┌─────────┬─────────┐
        ▼         ▼         ▼
   stochastic   copulas   stats
        │                   │
        └────────┬──────────┘
                 ▼
            stochastic-rs-quant
                 │
                 ▼
                 ai
```

The PyO3 crate (`stochastic-rs-py`) sits on the side: it depends on the
producer crates and re-exports `#[pyclass]`-wrapped types via the
`py_distribution!` / `py_process_*!` macros plus hand-written
`#[pyclass]` blocks for pricers and estimators.

## Why the workspace split

1. **Compile time**. Pulling only `stochastic-rs-distributions` for a
   distribution-sampling job avoids compiling the quant + AI surface.
2. **Feature gating**. `ai`, `cuda`, `metal` live on
   the crates that own the optional dependency, so a default
   `cargo build` never tries to link CUDA on a laptop with no GPU.
3. **Versioning**. Sub-crates can ship patch releases independently when
   needed — the umbrella tracks the highest sub-crate version.

## Path preservation across the workspace split

If your code imports via `stochastic_rs::stochastic::diffusion::*` or
`stochastic_rs::quant::pricing::*`, **no change is required** when
upgrading across the workspace split. The umbrella `pub use`s every
sub-crate's public surface under the historical paths.

