DiffLOB

KO | EN

gitlite — search

#python #react #ai #llm #golang #android #macos #java #awesome #security #ios #mcp #openai #open-source

(★ 13)

Official implementation of paper 'DiffLOB: Diffusion Models for Counterfactual Generation in Limit Order Books'

DiffLOB Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# DiffLOB: Diffusion Models for Counterfactual Generation in Limit Order Books

This repository contains the official implementation of **DiffLOB**, a score-based diffusion framework for **controllable and counterfactual generation of limit order book (LOB) trajectories** under future market regime interventions.

DiffLOB explicitly conditions the generative process on **future market regimes**—including **trend, volatility, liquidity, and order-flow imbalance**—and enables direct counterfactual queries of the form:

> *“If the future market regime were different, how would the LOB evolve?”*

---

## 🔍 Overview

Existing generative models for limit order books primarily focus on reproducing realistic market dynamics, but remain fundamentally **passive**: they model what typically happens, rather than what would happen under hypothetical future conditions.

DiffLOB addresses this limitation by:
- Formulating LOB generation as a **conditional score-based diffusion problem**
- Explicitly introducing **future market regimes** as control variables
- Enabling **counterfactual interventions** without relying on agent-based interaction
- Demonstrating the usefulness of counterfactual trajectories for downstream tasks

Model architecture is shown by following graph:

---

## ✨ Key Features

- **Score-based diffusion model (VP-SDE)** for LOB trajectories
- Explicit conditioning on **future market regimes**
- **ControlNet-style control module** for regime-aware intervention
- **Two-stage training strategy** for stable controllable generation
- **Classifier-free guidance** for flexible conditional sampling
- **Ancestral sampling** of the reverse-time SDE
- Joint modeling of **price and volume dynamics**
- Extensive evaluation on realism, counterfactual validity, and downstream usefulness

---

## Environment

This repo is managed with `uv` and `pyproject.toml`.

```bash
uv sync
```

You can then run commands through the managed environment:

```bash
uv run difflob-diffusion -c config/AMZN/Diffusion/wavenet_motion_control/train.py
```

Historical commands are available under `legacy/`, for example `python legacy/diffusion_main.py -c ...`.

---

## Repository Layout

The implementation lives under `src/difflob/`:

- `cli/`: command-line entrypoints
- `data/`: LOBSTER preprocessing
- `diffusion/`: SDEs, losses, and sampler utilities
- `models/`: diffusion and baseline architectures
- `training/`: model-family training loops
- `sampling/`: model-family sampling loops
- `utils/`: shared config, tensor, and dataloader helpers

Additional docs:

- `docs/quickstart.md`
- `docs/repo_structure.md`
- `docs/configs.md`
- `docs/data_format.md`
- `docs/experiments.md`

---

## 🧠 Building Conditioning Variables

DiffLOB requires future market regime conditions to be precomputed before counterfactual sampling.
These conditioning variables are constructed using the script:

```bash
uv run difflob-build-conditions
```

---

## ▶️ Running Training and Sampling Scripts

All training and sampling procedures are managed through scripts in the `scripts/` directory. Run:

```bash
bash scripts/AMZN/diff_wavenet_motion_control.sh
```

Or call the packaged entrypoint directly:

```bash
uv run difflob-diffusion -c config/AMZN/Diffusion/wavenet_motion_control/train.py
uv run difflob-diffusion -c config/AMZN/Diffusion/wavenet_motion_control/sample.py
```

---

## 🎲 Sampling Examples

Below we show representative sampled LOB trajectory snippets generated by DiffLOB.
Unless otherwise specified, figures are shown on **AMZN**.

DiffLOB

DiffLOB Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

DiffLOB

DiffLOB Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README