quantlib_rs 0.1.0

A ground-up, idiomatic Rust quantitative finance library inspired by QuantLib.
Documentation
# `quantlib_rs` Roadmap

This roadmap outlines the planned evolution of `quantlib_rs` from foundation to an institutional-grade quantitative finance library for the Rust ecosystem.

---

## Phase 0: Foundation (Current Milestone)
**Goal**: Build a solid, well-tested, high-performance base for time and mathematics.

### In Scope
- **Time Infrastructure**:
  - `Date`: Proleptic Gregorian calendar date with serial integer representation ($O(1)$ difference and arithmetic), leap-year handling, month end detection and roll.
  - `Calendar`: Trait and implementations (`NullCalendar`, `WeekendsOnly`, `UnitedStates` Federal & NYSE).
  - Business day conventions: `Following`, `ModifiedFollowing`, `Preceding`, `ModifiedPreceding`, `Unadjusted`.
  - `DayCounter`: `Actual/360`, `Actual/365Fixed`, `Actual/Actual (ISDA)`, `Thirty/360 (Bond Basis)`.
  - `Schedule`: Bond and swap coupon schedule generation (`Forward`, `Backward`, `Zero`).
- **Math Toolkit**:
  - `LinearInterpolation` with flat/linear/error extrapolation policies.
  - `CubicSpline` (natural cubic spline via tridiagonal Thomas algorithm, $C^2$ continuous).
  - 1D Root Finders: `Bisection` and safeguarded `NewtonRaphson`.
  - Normal distribution: PDF, CDF, and high-precision Peter Acklam rational approximation for inverse CDF ($\Phi^{-1}$).

### Out of Scope for Phase 0
- Multi-dimensional root solvers / general non-linear optimizers (e.g. Levenberg-Marquardt, BFGS).
- International holiday calendars beyond United States and WeekendsOnly.
- Irregular coupon / ISDA-specific schedule stub adjustments.

---

## Phase 1: Vertical Slice (Current Milestone)
**Goal**: Validate the architecture end-to-end with an instrument, process, engine, and exact automatic differentiation Greeks.

### In Scope
- **Market Data & Handles**:
  - `Quote` trait and `SimpleQuote` with monotonic versioning.
  - Generational index identifiers (`QuoteId`) and `MarketEnvironment` registry.
- **Term Structures**:
  - `YieldTermStructure` trait and `FlatForward` constant zero rate.
  - `BlackVolTermStructure` trait and `BlackConstantVol` constant volatility.
- **Process**:
  - `GeneralizedBlackScholesProcess` bundling spot, risk-free curve, dividend curve, and volatility surface.
- **Instrument & Engine**:
  - `EuropeanOption` (Call/Put, strike, European expiry).
  - `AnalyticEuropeanEngine` implementing Black-Scholes-Merton formula.
  - Greeks: Forward-mode automatic differentiation with `Dual64` (first derivatives) and `HyperDual64` (exact Gamma and cross-Greeks) + central finite-difference bump engine for cross-validation.
- **Multi-Oracle Verification**:
  - Validated against Hull textbook reference, QuantLib C++ published test cases, put-call parity ($< 10^{-12}$), and Monte Carlo simulation ($500,000$ paths).

### Out of Scope for Phase 1
- Bootstrapped term structures from market instruments.
- American / Bermudan exercise styles.
- Finite difference grid PDE solvers or tree pricing engines.

---

## Phase 2: One Deep Vertical — Fixed Income or Derivatives
**Goal**: Choose one primary vertical and build institutional depth rather than shallow breadth.

### Candidate A: Fixed Income
- Bootstrapped zero-coupon yield curves (deposits, FRAs, interest rate swaps).
- Fixed-rate and floating-rate bonds with accrued interest, dirty/clean prices, yield-to-maturity, and duration/convexity.
- Vanilla fixed-float Interest Rate Swaps (IRS).
- Multi-curve framework (OIS discounting vs forward projection curves).

### Candidate B: Derivatives & Numerical Engines
- American options via binomial/trinomial trees (Cox-Ross-Rubinstein, Jarrow-Rudd) and Finite Difference PDE solvers.
- Monte Carlo engine framework with variance reduction (antithetic variates, control variates, Sobol low-discrepancy sequences).
- Local volatility and stochastic volatility models (Heston 1993, SABR).

### Out of Scope for Phase 2
- Cross-asset hybrid products (e.g. quanto swaptions, hybrid equity-FX-IR models).

---

## Phase 3: Breadth & Calibration
**Goal**: Broaden asset class coverage and provide robust model calibration.

### In Scope
- Complete coverage of both Fixed Income and Equity/FX Derivatives.
- Calibration engine using Levenberg-Marquardt and global optimization for Heston and SABR parameter fitting.
- Credit Default Swaps (CDS) and hazard rate term structures.
- Additional global calendars (TARGET/ECB, UK, Japan, Australia, China).

### Out of Scope for Phase 3
- Multi-factor Cheyette or Libor Market Model (LMM).

---

## Phase 4: Distribution & Integration
**Goal**: Bring `quantlib_rs` to quants, data scientists, and web platforms.

### In Scope
- **Python Bindings (`pyo3` / `maturin`)**: High-performance Python wrapper published to PyPI.
- **WASM / NPM Package**: Browser and Node.js execution via `wasm-bindgen`.
- **C ABI (`extern "C"`)**: Dynamic library bindings for Excel, C++, and C#.
- **Modern Data Stack**: Apache Arrow / Polars integration for schedule and curve dataframes.
- **Benchmark Suite**: Comprehensive benchmark against C++ QuantLib, RustQuant, and quantrs.

---

## Phase 5: Community & 1.0 Stability
**Goal**: Transition to long-term governance and stable API.

### In Scope
- `1.0` API stability guarantee with semantic versioning.
- Public architectural documentation book (`mdBook`), modeled after Luigi Ballabio's *Implementing QuantLib*.
- Community steering group, monthly release cadence, and production user case studies.