neural-sde 0.6.0

Probabilistic price forecasting via stochastic differential equations (GBM/OU/neural), with AIC model selection, Monte Carlo quantiles, and fan charts.

neural-sde

Probabilistic price forecasting via stochastic differential equations. Fit a GBM or OU (mean-reverting) model to a price series, generate Monte Carlo forecasts with quantified uncertainty, and answer questions like "what's the probability this is up 10% in 30 days?" — without pretending to know the future.

This library produces probabilistic forecasts, not point predictions. forecast() returns a distribution over future paths, not a single "the price will be X" answer. Treat every number it gives you — quantiles, prob_above(), the fan chart — as a statement about uncertainty, not a promise. Financial markets are not stationary; a model fit on last year's regime can be a poor guide to next month's.

Install

pip install -e .                 # core: numpy, scipy, matplotlib
pip install -e ".[torch,pandas]" # + neural SDE path and pandas Series input
pip install -e ".[demo]"         # + yfinance, to run demo_forecast.py on real data

Requires Python 3.9+. See requirements.txt / pyproject.toml for pinned dependency ranges.

Quickstart

from neural_sde.highlevel import fit, forecast

model = fit(prices)                        # auto: AIC picks GBM vs OU
fc = forecast(model, horizon=30)           # antithetic Monte Carlo
print(fc.prob_above(prices[-1] * 1.10))    # P(+10% by day 30)
print(fc.quantiles([0.05, 0.5, 0.95]))     # 5th/50th/95th percentile price
fc.plot("forecast.png")                    # fan chart: history -> forecast cone

prices is any 1-D array-like or pandas Series of price levels (not returns). fit(model="neural") routes to a torch-based NeuralSDETrainer when torch is installed — this path is experimental; the GBM/OU parametric paths use exact (unbiased) transition densities and are the production-quality default.

On regimes

fit() estimates parameters from whatever window of history you give it. A GBM fit on a 6-month bull run will forecast that drift forward; an OU fit on a period of active mean-reversion will forecast reversion. Neither model knows the regime changed the day after your training window ends. Re-fit periodically, and sanity-check model.summary() (drift/vol/theta) against what you'd expect for the asset before trusting the forecast.

What's inside

Module	Purpose
highlevel.py	Public API: fit/forecast/FittedModel/Forecast — start here
sde_core.py	Core SDE theory: drift/diffusion, Ito<->Stratonovich conversion
solvers.py / torch_solvers.py	Euler-Maruyama, Milstein, Heun solvers (numpy and torch backends)
multi_asset.py	Correlated multi-asset GBM/OU/CIR diffusion
neural_networks.py / trainer.py	Neural drift/diffusion networks and training loop (experimental path, requires torch)
likelihood.py	Score-matching / contrastive-divergence loss functions
forecasting.py	Path forecasting and option pricing utilities
api.py	Lower-level unified solver entry point

Demo

pip install -e ".[demo]"
python demo_forecast.py

With yfinance installed and network access, edit the top of the script to pull real data:

import yfinance as yf
from neural_sde.highlevel import fit, forecast

prices = yf.download("AAPL", period="2y")["Close"]
model = fit(prices)
fc = forecast(model, horizon=30)
print(fc.summary())
fc.plot("forecast.png")

Offline, the script instead demos against synthetic data with known dynamics, which doubles as a calibration test — it simulates GBM and OU paths with known parameters, fits them back, and checks:

1. fit() recovers the true GBM parameters and AIC selects GBM.
2. fit() recovers the true OU parameters and AIC selects OU.
3. Monte Carlo quantiles agree with the exact lognormal distribution to <1%.
4. The exact and euler (core-library) engines agree on the median to <3%.

forecast.png and forecast_example.png in this directory are pre-generated sample outputs from that script — regenerate them yourself with python demo_forecast.py.

Testing

pip install -e ".[dev]"
pytest test_convergence_rate.py test_adjoint_grad.py test_adjoint_verify.py \
       test_trainer_losses.py test_torch_solvers.py test_unified_entry.py \
       test_api_integration_v05.py test_edge_case_regression.py

archive/ holds superseded tests kept for historical reference (see archive/README.md); they aren't part of the suite.

License

MIT.

Credit

Built by Kevin Downie in collaboration with Claude (Anthropic).