stochastic-rs

Python bindings

stochastic-rs-py — Python coverage for distributions, processes, pricers, calibrators, copulas, stats. NumPy in / out, 308 entries.

The stochastic_rs Python package wraps the Rust crates via PyO3. The surface is 308 entries: 286 PyO3 classes plus 22 free functions across distributions, stochastic processes, pricers, calibrators, copulas, and stats — every class ships in every wheel (the linear algebra is the pure-Rust faer, so the 13 formerly BLAS-gated classes need no feature any more). Four more registrations — three surrogate classes and calibrate_surrogate — are behind the ai feature and reach only a source build.

Derivation: bun run python:parity (from website/) regenerates public/python-parity.json by parsing every m.add_class::<PyXxx>() and m.add_function(pyo3::wrap_pyfunction!(...)) call in stochastic-rs-py/src/lib.rs's #[pymodule] function — the single place that determines what the compiled module actually exposes. A #[pyclass] defined in a sub-crate but never registered there would not be a real Python entry, so this is the only correct place to count from.

Installation

See Installation (Python).

The neural surrogates (HestonNn, RBergomiNn, OneFactorNn) and calibrate_surrogate are not in the published wheels — candle is heavy — and come with a source build: maturin develop --features ai from the workspace root. The same goes for the device back-ends of the Euler engine and the fGN samplers: --features metal, cuda, accelerate.

NumPy interop

All sample() calls return numpy.ndarray. Bulk samplers (sample_par(m, n)) return (m, n)-shaped arrays. The default dtype is float64; pass dtype="f32" where the underlying sampler supports it.

End-to-end example — simulate, estimate, price

A single Python script that touches four crates:

import stochastic_rs as srs
import numpy as np

# 1. Simulate an OU path (stochastic crate)
ou = srs.PyOu(theta=2.0, mu=0.0, sigma=1.0, n=4096, x0=0.0, t=1.0, seed=42)
path = ou.sample()                    # shape (4096,)

# 2. Estimate the Hurst exponent of an fBM path (stats crate). RescaledRange
# takes a level series directly (its default take_differences=True handles
# the first-differencing) — unlike FukasawaHurst, which estimates a
# different quantity (latent-volatility roughness from a realized-variance
# series) and would silently return nonsense fed a raw path; see the
# statistics catalog page's Hurst section.
fgn = srs.PyFgn(hurst=0.4, n=4096, t=1.0, seed=42)
fbm = np.cumsum(fgn.sample())
hurst = srs.RescaledRange().estimate(fbm)
print(f"H = {hurst.hurst:.3f} (true 0.4)")

# 3. Price a Heston call (quant crate)
pricer = srs.HestonPricer(
    s=100, v0=0.04, k=100, r=0.03, kappa=2.0, theta=0.04, sigma=0.3,
    rho=-0.5, tau=1.0, q=0.0,
)
call, put = pricer.call_put()
print("Heston call =", call)

# 4. Sample from a Clayton copula (copulas crate). theta/tau are the only
# constructor args — seed is a sample()-time argument, and sample(n) returns
# one (n, 2) array rather than a (u, v) tuple.
cop = srs.Clayton(theta=2.0)
uv = cop.sample(10_000, seed=42)
u, v = uv[:, 0], uv[:, 1]
print("τ̂ =", srs.kendall_tau_matrix(np.column_stack([u, v]))[0, 1])

Bulk sampling — sample_par(m, n)

import stochastic_rs as srs

# 100_000 GBM paths × 252 daily steps in parallel
gbm = srs.PyGbm(mu=0.05, sigma=0.2, n=252, x0=100.0, t=1.0, seed=42)
paths = gbm.sample_par(100_000)       # shape (100_000, 252)

# Path-wise terminal payoff
payoffs = np.maximum(paths[:, -1] - 100.0, 0.0)
mc_call = np.exp(-0.05) * payoffs.mean()
print("MC call =", mc_call)

The models driven by Python callables — PyHullWhite(theta, …), PyAdg, PyHjm, PyCheyette — have sample_par too. They release the GIL while the paths are generated and re-acquire it for each callback evaluation, so the callables run from the worker threads one at a time. PyAdg.sample_par(m) returns an (m, factors, n) array and PyHjm.sample_par(m) three (m, n) arrays (short rate, bond price, forward rate).

Devices

probe_device(name) opens a device ("cpu", "accelerate", "cuda", "metal", optionally with an ordinal: "cuda:1") and returns a dict with backend, name, precisions and ordinal; a device this build does not carry raises ValueError with a rebuild hint, one that is compiled in but cannot be opened raises RuntimeError with the runtime's own message. Without an ordinal the handle's default applies (STOCHASTIC_RS_DEVICE, else 0). A device failure while sampling is a RuntimeError too.

srs.probe_device("metal")             # {'backend': 'Metal', 'name': 'Apple M2 Max', 'precisions': ['f32'], 'ordinal': 0}
srs.PyGbm(0.05, 0.2, 253, x0=100.0, t=1.0, seed=7, device="cuda:1")   # second CUDA GPU

Every class whose process reaches a device takes device= — all 81 of them, the Euler engine's families and the fGN family alike: PyGbm(..., dtype="f32", device="metal"). (Until September 2026 only 47 did, and the other 34 — the jump laws, the subordinators, the conditional-variance models, PyHawkes, PyPoisson — were host-only from Python although their Rust processes had kernels.) The name is checked against the build (ValueError with a rebuild hint), a single-precision device needs dtype="f32" (ValueError otherwise), and the device is probed when the object is built (RuntimeError if it cannot be opened), so sample() / sample_par(m) then run on it and return arrays in the class's dtype. device="cpu" is the default and samples exactly as before. Two fGN-driven processes stay on the host from Python: PyJumpFou and PyJumpFOUCustom carry a Python callable as their jump law, which cannot travel to a kernel, and Sde has no Python class because it takes Rust closures for its drift and diffusion. The device classes hand the launch buffer over as one NumPy array without re-laying it into rows.

srs.probe_device("metal")   # {'backend': 'Metal', 'name': 'Apple M2 Max', 'precisions': ['f32'], 'ordinal': 0}

Credit curves

SurvivalCurve is the term structure of default: build it from hazard rates, survival probabilities or default probabilities on a pillar grid (SurvivalCurve.flat(h) for one rate everywhere), and pass it anywhere a flat hazard rate is accepted — ExposureProfile.cva / dva / bilateral_cva, the (weight, recovery, hazard) triplets of CdsIndex and CdoTranche.

curve = srs.SurvivalCurve([1.0, 3.0, 5.0], [0.010, 0.015, 0.020])
curve.survival_probability(4.0)                    # exp(-0.010 - 0.030 - 0.020)
profile.cva(curve, discount, lgd=0.6)              # same call as with a float
index = srs.CdsIndex([(0.5, 0.4, curve), (0.5, 0.4, 0.02)], 0.01, 1e7, "2026-03-20", "2031-06-20")

Four pipelines

There are four ways a Rust type ends up in the Python package:

  1. py_distribution! / py_distribution_int! macros — distributions wrap automatically when you invoke the macro at the bottom of the source file.
  2. py_process_*! macros — processes use py_process_1d!, py_process_2x1d!, or py_process_2d! depending on shape.
  3. py_bivariate! macro — bivariate copulas, in stochastic-rs-copulas/src/python.rs.
  4. Hand-written #[pyclass] blocks — pricers, calibrators, vol surfaces, and estimators are wrapped by hand across the stochastic-rs-quant/src/python/ and stochastic-rs-stats/src/python/ directories (one file per topic — pricing_analytic.rs, calibration_basic.rs, stationarity.rs, hurst.rs, …).

For the file-by-file recipe see the python-bindings SKILL (comprehensive) or adding-python-binding (quickstart).

Common gotchas

  • Seed reproducibility. Every process and distribution wrapper supports __init__(..., seed=None). Bivariate copulas differ: theta/ tau are the only constructor arguments, and the seed is instead an optional argument to .sample(n, seed=None). Either way, pass an explicit seed for tests; rely on the thread-local default for production sampling.
  • Dtype shims. IntoF32 / IntoF64 shims convert Python float parameters to the requested dtype. All distribution parameters are f64-typed in the macro — the shim handles down-conversion to f32 when dtype="f32".
  • sample_par(m, n) shape. The returned array is (m, n), with m independent paths along axis 0. This matches NumPy's row-major default for downstream .mean(axis=0) reductions.
  • Errors are ordinary exceptions. A constructor that rejects its arguments raises ValueError, and a process, distribution or copula whose sampling fails raises RuntimeError, both carrying the Rust message, so except Exception catches them. Other methods (densities, pricing, calibration, estimation) raise ValueError where they check their inputs; an unchecked failure inside one still surfaces as pyo3_runtime.PanicException, which derives from BaseException.
Edit on GitHub

Last updated on

On this page