Lumina LOB

A production-grade, educational Limit Order Book (LOB) simulator with algorithmic market-making, reinforcement learning support, and real-time visualization.

Mission: Build the most complete open-source LOB simulator that demonstrates tick-level market microstructure — matching engines, market impact, adverse selection, inventory risk, RL-based market making, and replay against real tick data.

Why this matters

Quant firms like Jane Street, Citadel Securities, Optiver, and IMC make markets at the tick level. Most open-source simulators are either too academic or too toy-like. Lumina LOB fills the gap with realistic agents, performance benchmarks, calibration to real data, and RL training.

Documentation

Full docs site: https://satyamdas03.github.io/lumina-lob

Blog post

Draft: blog/build-a-lob-simulator.md — "Build a Limit Order Book Simulator from Scratch".
Social launch drafts: blog/social-launch.md — LinkedIn post + X/Twitter thread ready for human review/posting.

Install

pip install lumina-lob

The package is published to PyPI. If pip install lumina-lob is not yet live, the wheels/sdist are built and the release tag is ready; PyPI trusted publishing must be configured by the repository owner for the first upload.

First-time PyPI trusted publishing setup (repository owner only)

1. Log in to pypi.org as satyamdas03.
2. Go to Account settings → Publishing.
3. Add a new pending publisher:
   • PyPI project name: lumina-lob
   • Owner: satyamdas03
   • Repository name: lumina-lob
   • Workflow name: build.yml
   • Environment name: pypi
4. Save. The next push of a v*.*.* tag will automatically publish.
5. The v0.1.1 tag is already pushed; after configuring the publisher, re-run the failed Build wheels workflow run or push a new v*.*.* tag.

The GitHub Actions run for v0.1.1 confirmed that all 9 OS/Python matrix builds pass and produce both wheels and an sdist; only the final publish step fails until this configuration is done.

Optional visualization support:

pip install lumina-lob[viz]

Development install from source:

git clone https://github.com/satyamdas03/lumina-lob.git
cd lumina-lob
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev,viz,docs]"
pytest

The C++ accelerated core builds automatically when a compiler and pybind11 are available; otherwise the package falls back to the pure-Python engine.

Quickstart

from lumina_lob import Order, OrderBook, MatchingEngine, Side

book = OrderBook()
engine = MatchingEngine(book)

engine.process(Order(1, Side.BID, 100, 10))
engine.process(Order(2, Side.ASK, 100, 4))
engine.process(Order(3, Side.BID, 101, 6))

print(book.snapshot())
print(book.trades)

For an interactive walkthrough, open the first available notebook: notebooks/02_agents_and_impact.ipynb.

Features

Roadmap

The project is built in six phases:

Project spec

See PROJECT_SPEC.txt for the full vision, market gap, build phases, and interview talking points.

License

MIT © Satyam Das