OpenQuant

Rust implementations of the methods in Advances in Financial Machine Learning, with Python bindings.

Documentation · Quickstart · Issues

Choose your documentation path

• For humans: Quickstart for a first result, then the module index.
• For agents: Agent guide for source files, research safeguards and validation commands. Read it alongside AI-DLC.md when changing the repository.

Status

Pre-release (0.1.0, unpublished). The Rust core covers most AFML chapters and is tested in CI. The module index lists the current Rust and Python surfaces. The installation below builds from source so the examples and extension use the same revision. Open work is tracked in issues; the reasoning behind it is in docs/design/production-readiness-brief.md.

Install

Requires a Rust toolchain (pinned by rust-toolchain.toml), Python 3.11+ and uv.

git clone https://github.com/Open-Quant/openquant.git && cd openquant
uv venv --python 3.13 .venv
uv sync --group dev
uv run --python .venv/bin/python maturin develop --manifest-path crates/pyopenquant/Cargo.toml
uv run --python .venv/bin/python python -c "import openquant; print('ok')"

The Python distribution name is pyopenquant; the import name is openquant. Check the release notes for packaged release availability; the commands above do not depend on a published wheel. Do not pip install openquant - that name on PyPI belongs to an unrelated project. The extension crate (crates/pyopenquant) is built into a wheel with maturin and is never published to crates.io.

Quick Start

# Fast validation (what CI runs on every PR)
cargo test --workspace --lib --tests --all-features -- --skip test_sadf_test

# Long-running SADF hotspot (explicit; CI runs it nightly and on release tags)
cargo test -p openquant --test structural_breaks test_sadf_test -- --ignored

# Benchmarks
cargo bench -p openquant --bench perf_hotspots --bench synthetic_ticker_pipeline

# Collect + check benchmark thresholds against the committed baseline (machine-specific;
# CI instead compares a PR's head with its base on the same runner)
python3 scripts/collect_bench_results.py --criterion-dir target/criterion --out benchmarks/latest_benchmarks.json --allow-list benchmarks/benchmark_manifest.json
python3 scripts/check_bench_thresholds.py --baseline benchmarks/baseline_benchmarks.json --latest benchmarks/latest_benchmarks.json --max-regression-pct 35 --overrides benchmarks/threshold_overrides.json

Research Flywheel (Python + Rust)

# Python env + bindings
uv venv --python 3.13 .venv
uv sync --group dev
uv run --python .venv/bin/python maturin develop --manifest-path crates/pyopenquant/Cargo.toml

# Notebook logic smoke + reproducible experiment run
uv run --python .venv/bin/python python notebooks/python/scripts/smoke_all.py
uv run --python .venv/bin/python python experiments/run_pipeline.py --config experiments/configs/futures_oil_baseline.toml --out experiments/artifacts

# Rust notebook-companion smoke
cargo run -p openquant --example research_notebook_smoke

# Python pipeline micro-benchmark (for speed demos)
uv run --python .venv/bin/python python python/benchmarks/benchmark_pipeline.py --iterations 30 --bars 2048

# Python data-processing benchmark (per-function throughput/latency + JSON output)
uv run --python .venv/bin/python python python/benchmarks/benchmark_data_processing.py --rows-per-symbol 200000 --symbols 4 --iterations 7 --out benchmarks/data_processing/latest.json

Crate Layout

• crates/openquant/src/: core library modules
• crates/openquant/tests/: Rust test suite
• crates/openquant/benches/: criterion benchmarks
• tests/fixtures/: shared fixtures
• benchmarks/: baseline + latest benchmark snapshots
• notebooks/: Python notebooks + Rust Evcxr companions
• experiments/: config-driven experiment runner + artifacts

Publish Readiness

• Publishing checklist: docs/publishing.md
• Stabilization + productionization checklist: docs/stabilization_productionization.md
• Latest benchmark report: docs/benchmark_snapshot.md
• Python bindings quickstart + API map: docs/python_bindings.md
• Notebook-first workflow + promotion checklist: docs/research_workflow.md

Docs site

The documentation at https://open-quant.github.io/openquant/ is built from docs-site/ (Astro + Starlight).

cd docs-site
bun install
bun run dev

Build output is published by GitHub Actions workflow: .github/workflows/docs-pages.yml.

Contributing

See CONTRIBUTING.md for setup, the test and docs gates, and pull request conventions, and tests/FIXTURES.md for where the test fixtures come from. Report security problems privately (SECURITY.md).

License

MIT (LICENSE)