# Workspace migration — végrehajtási napló
Ez a dokumentum a `stochastic-rs` mono-crate-ből Cargo workspace-szé alakítás konkrét lépéseit írja le. A struktúra **top-level sub-crate-ekkel** működik (nem `crates/` alkönyvtárban), és a fő `stochastic-rs` crate csak `pub use` re-exportokkal továbbítja a típusokat.
---
## Végrehajtott fázisok
| 0 | Workspace skeleton + 9 sub-crate stub | ✅ |
| 1 | `simd_rng.rs` → `stochastic-rs-core` | ✅ |
| 2 | `distributions/` + `FloatExt`, `SimdFloatExt`, `Fn1D`, `Fn2D`, `CallableDist`, `DistributionExt`, `DistributionSampler` → `stochastic-rs-distributions` | ✅ |
| 3 | `stochastic/` + `ProcessExt`, `MalliavinExt`, `Malliavin2DExt` → `stochastic-rs-stochastic` | ✅ |
| 4 | `copulas/` + `BivariateExt`, `MultivariateExt`, `NCopula2DExt` → `stochastic-rs-copulas`; `stats/` → `stochastic-rs-stats` | ✅ |
| 5 | `quant/` + `PricerExt`, `TimeExt`, `ToModel`, `ModelPricer` → `stochastic-rs-quant` | ✅ |
| 6 | `ai/` → `stochastic-rs-ai`; `visualization.rs` → `stochastic-rs-viz`; `python.rs` + `macros.rs` átköltöztetve `stochastic-rs-py/`-be `.pending` fájlként | ⚠️ python feature átmenetileg no-op |
| 7 | Umbrella `prelude` modul, facade `pub use` re-exportok | ✅ |
**Default build:** ✅ tisztán épül (`cargo check --workspace --no-default-features`)
**ai feature:** ✅ (`cargo check -p stochastic-rs --features ai`)
**python feature:** ⚠️ jelenleg no-op (lásd lent)
---
## Új struktúra
```
stochastic-rs/ (workspace root + umbrella crate)
├── Cargo.toml (workspace + [package] = stochastic-rs)
├── src/
│ ├── lib.rs — pub use re-exportok + prelude
│ └── traits.rs — facade (pub use a sub-crate trait modulokból)
├── stochastic-rs-core/ — simd_rng (foundation)
├── stochastic-rs-distributions/ — disztribúciók + FloatExt/SimdFloatExt
├── stochastic-rs-stochastic/ — process típusok + ProcessExt
├── stochastic-rs-copulas/ — copulák + BivariateExt
├── stochastic-rs-stats/ — statisztikai becslők
├── stochastic-rs-quant/ — pricing + calibration + vol_surface + PricerExt
├── stochastic-rs-ai/ — neural surrogates (feature = "ai")
├── stochastic-rs-viz/ — Plotly grid plotter
└── stochastic-rs-py/ — placeholder (Phase 6 follow-up)
```
## Függőségi gráf
```
core
└→ distributions
├→ stochastic
│ ├→ stats
│ ├→ ai
│ ├→ viz
│ └→ quant
├→ copulas → quant
└→ stats → quant
```
A `stochastic-rs` umbrella mindegyikre hivatkozik, és csak `pub use` re-exportokat tartalmaz — **0 saját implementáció a `src/`-ben** (kivéve `lib.rs` és `traits.rs`, ami csak re-export).
---
## Mit használ a felhasználó
### A meglévő útvonalak változatlanok maradnak
```rust
// Mind működik a tests/, examples/, benches/ kódban:
use stochastic_rs::stochastic::diffusion::gbm::GBM;
use stochastic_rs::distributions::normal::SimdNormal;
use stochastic_rs::quant::pricing::heston::HestonPricer;
use stochastic_rs::stats::heston_mle::nmle_heston;
use stochastic_rs::traits::{ProcessExt, FloatExt, ModelPricer};
```
### Új: prelude (P0 javaslat 1.)
```rust
use stochastic_rs::prelude::*;
// hozza: BivariateExt, DistributionExt, DistributionSampler, FloatExt,
// ModelPricer, PricerExt, ProcessExt, SimdFloatExt, TimeExt, ToModel,
// Moneyness, OptionStyle, OptionType
```
### Új: közvetlen sub-crate használat (csak distributions kell)
```toml
# Cargo.toml
[dependencies]
stochastic-rs-distributions = "2.0.0-beta.1"
```
```rust
use stochastic_rs_distributions::normal::SimdNormal;
```
Ez a workspace-split fő ergonomikus nyeresége: aki csak a sampling oldalt használja, **nem fizet** a quant/ai/viz fordítási költségéért.
---
## Strukturális változtatások részletei
### Modulközti átköltöztetés (struktúra-szintű, nem implementáció)
| `simd_rng.rs` | `src/` | `stochastic-rs-core/src/` | Foundation RNG, mindenki használja |
| `non_central_chi_squared.rs` | `src/stats/` | `stochastic-rs-distributions/src/` | Sampler funkció, nem statisztikai becslő (audit P1/8 javaslat) |
| Fn1D, Fn2D, CallableDist | `src/traits.rs` | `stochastic-rs-distributions/src/traits.rs` | Generikus `T: FloatExt` követelmény miatt distributions-be költözött a FloatExt-tel együtt |
### `pub(crate)` → `pub` változtatások
A `pub(crate)` láthatóság `pub`-bá lett alakítva 18 helyen a `stochastic-rs-distributions/src/`-ben (pl. `from_seed_source` segédfüggvények). **Indok:** korábban ugyanazon umbrella crate-en belül a `pub(crate)` látható volt a többi modulnak (pl. `stochastic`/svcgmy.rs → `distributions`/uniform.rs). Külön sub-crate-ben már nem; szükséges a `pub`. Az API publikus felülete továbbra is a `stochastic-rs` umbrella-n keresztül van kontrollálva (`pub use`).
### Trait megosztás
A `src/traits.rs` 654 soros trait-monolit szét lett darabolva 5 sub-crate közt:
| `FloatExt`, `SimdFloatExt`, `Fn1D`, `Fn2D`, `CallableDist`, `DistributionExt`, `DistributionSampler` | `stochastic-rs-distributions/src/traits.rs` |
| `ProcessExt`, `MalliavinExt`, `Malliavin2DExt` | `stochastic-rs-stochastic/src/traits.rs` |
| `BivariateExt`, `MultivariateExt`, `NCopula2DExt` | `stochastic-rs-copulas/src/traits.rs` |
| `PricerExt`, `TimeExt`, `ToModel`, `ModelPricer` | `stochastic-rs-quant/src/traits.rs` |
Az umbrella `src/traits.rs` mostantól **csak `pub use` re-exportok** — a felhasználói API útvonalak változatlanok.
### Macro shimek
Minden sub-crate-be került egy `src/macros.rs` üres-test (`($($tt:tt)*) => {}`) verzióval az alábbi makrókhoz:
- `py_distribution!`, `py_distribution_int!`
- `py_process_1d!`, `py_process_2x1d!`, `py_process_2d!`
A makró-invokációk a sub-crate forráskódjában (pl. `uniform.rs:py_distribution!(...)`) **no-op-okká válnak**. A tényleges Python wrapper kódgenerálás a `stochastic-rs-py` sub-crate-be költözik (Phase 6 follow-up).
---
## ⚠️ Phase 6 follow-up — `stochastic-rs-py`
Az átalakítás során a Python (pyo3) bindingek **átmenetileg no-op**-okká váltak. A umbrella `python` feature build-el, de nem generál tényleges Python osztályokat.
A teendő:
1. `stochastic-rs-py/src/lib.rs.pending` (régi `src/python.rs`) → `stochastic-rs-py/src/lib.rs`
2. `stochastic-rs-py/src/macros.rs.pending` (régi `src/macros.rs`) → `stochastic-rs-py/src/macros.rs`
3. A makrókban szereplő `crate::python::IntoF32` / `IntoF64` útvonalakat áthelyezni `stochastic-rs-core::python::*`-be vagy `stochastic-rs-py::python::*`-be, és a sub-crate makró-shimeket lecserélni a tényleges (nem üres) makrókra
4. A `py_distribution!(PyXxx, SimdXxx, ...)` invokációkat **vagy** átmozgatni a `stochastic-rs-py`-be (egy nagy fájlba), **vagy** mindegyik sub-crate-ben aktiválni a `python` feature mögött
5. Az umbrella `Cargo.toml` `[lib] crate-type = ["lib", "cdylib"]` cdylib részét a `stochastic-rs-py` Cargo.toml-jébe áttenni
6. A `pyproject.toml` (maturin config) szintén a `stochastic-rs-py`-re mutasson
A `.pending` fájlokat **direkt nem aktiváltam** — ezek dokumentált seed a follow-up számára.
---
## Mit nem tettem (bár az audit javaslata volt)
A user kérése szerint **csak strukturális** változtatás — implementációs javítás nincs. A következőket **nem** csináltam:
- `DistributionExt` 12 metódusának implementálása a 19 disztribúción (audit P0/2)
- `ToModel` lyukak betöltése (`SabrCapletCalibrator`, `HullWhiteSwaptionCalibrator` — audit P0/3)
- Builder pattern bevezetése a 6+ paraméteres pricerekre (audit P2/11)
- Stats input‑típus egységesítés (audit P1/6)
- Copula duplikáció megszüntetése (audit P1/8)
- Naming inkonzisztencia rendezése (audit P1/5)
Ezek mind külön következő körnél jönnek.
---
## Mi viszont megtörtént Phase 0–7-en kívül
A workspace-szétdarabolás **mellékhatásaként** néhány P0/P1 audit javaslat is teljesült:
- ✅ **P0/4** — facade re-exportok minden modul-rootban (`pub use` minden sub-crate `lib.rs`-ben + umbrella-ban)
- ✅ **P0/1** — prelude (`stochastic_rs::prelude`)
- ✅ **P1/9** — `traits.rs` szétdarabolása sub-crate-ekre
- ✅ **P1/10** — egy stat-utility (`non_central_chi_squared`) átköltöztetve a megfelelő helyre
- ✅ **P3/16** — workspace-szé alakítás (felső 4 fázis fő eredménye)
---
## Verifikáció
```bash
cargo check --workspace --no-default-features # ✅ tiszta
cargo build --workspace --no-default-features # ✅ 5.7s
cargo check -p stochastic-rs --features ai # ✅ tiszta
cargo check --benches --no-default-features # ✅ 1 pre-existing dead_code warning
cargo check --examples --no-default-features # ✅ tiszta
cargo check --tests --no-default-features # ⚠️ openblas-gated test (pre-existing)
```
A `tests/`, `examples/`, `benches/` mind a `use stochastic_rs::xxx::yyy` útvonalat használják — **nem törött el egyik sem**. 58 fájlból 0 igényelt módosítást a workspace-átállás miatt.
---
## Sub-crate súlyok (publikus felület)
| `core` | 1 + lib.rs | ~600 | `SimdRng`, `SeedExt`, `Unseeded`, `Deterministic` |
| `distributions` | 21 + lib + traits + float_impls | ~3500 | 19 `Simd*` disztribúció, `FloatExt`, `SimdFloatExt`, `DistributionExt`, `DistributionSampler` |
| `stochastic` | ~140 + lib + traits | ~25000 | `BM`, `FBM`, `GBM`, `Heston`, `OU`, `Vasicek`, `CIR`, …, `ProcessExt`, `MalliavinExt` |
| `copulas` | ~10 + lib + traits | ~3000 | `Clayton`, `Gumbel`, `Frank`, `Gaussian`, `BivariateExt`, `MultivariateExt` |
| `stats` | ~20 + lib + traits | ~5000 | `nmle_heston`, `FOUParameterEstimationV1..V4`, `fukasawa_hurst::estimate`, normality/stationarity tests |
| `quant` | ~120 + lib + traits | ~30000 | `HestonPricer`, `BSMPricer`, `SabrModel`, `ImpliedVolSurface`, `OptionType`, `PricerExt`, `ModelPricer`, `TimeExt`, `ToModel` |
| `ai` | ~5 + lib + traits | ~1200 | `HestonNn`, `OneFactorNn`, `RoughBergomiNn`, `DataSet`, `TrainConfig` |
| `viz` | 1 (lib.rs) | ~1000 | `GridPlotter`, `Plottable` |
| `py` | placeholder | (pending) | (Phase 6 follow-up) |
---
## Build idő várható nyeresége
A monolit umbrella `cargo build --no-default-features` ~30s volt cold cache-szel.
A workspace-szétbontás után:
- Aki **csak** `stochastic-rs-distributions`-t használ: ~3-5s (kihagyja `quant`-ot, `stats`-ot, `gauss-quad`-et, `argmin`-t, `levenberg-marquardt`-t, `kendalls`-t, …)
- Aki **csak** `stochastic-rs-stochastic`-ot használ: ~10-15s
- Aki a teljes umbrella-t pulleli: ~30s (mint korábban, csak most már párhuzamosan fordul a 9 crate)
A `cargo check --workspace` ~2.4s incrementálisan, ami **lényegesen jobb** mint a monolit ~7-10s volt.
---
*Migráció kelt: 2026-04-26*
