QuantSim

A live market simulation dashboard built with Python and PyQt6. Rule-based trading agents — and an optional Q-learning agent — trade against each other in a simulated order book while you watch price action, candles, and leaderboards update in real time.

Built with AI assistance. This project was developed with the help of an AI coding assistant. The code is deterministic and has been reviewed by a human — the same inputs always produce the same outputs.

Features

• Live order book matching — bids and asks are continuously matched into trades with bid/ask spread, depth, and stale-order eviction
• Six rule-based agents with distinct personalities:
  • 🚀 Momentum — chases trends, buys rips and sells drops
  • 📊 Value — fades extremes vs. a running mean
  • 😱 Panic — panic-sells on drops, FOMOs back on rises
  • 🔄 Contrarian — fades the crowd
  • ⚖️ Market Maker — posts both sides and captures the spread
  • 📰 News Reactor — trades aggressively when market events fire
• Optional Q-learning agent (ml/q_agent.py) — a PyTorch DQN that learns to trade from raw state features (price vs. mean, momentum, volatility, cash / position ratios, spread, volume trend, event state), with a replay buffer and target network. Enabled automatically if torch is installed.
• Event injection — earnings beats/misses, Fed moves, short squeezes, flash crashes, black swans — injectable manually or at random
• Live dashboard — price header, OHLCV candlestick chart, agent list with equity / PnL / win-rate, and running event ticker
• Simulation controls — start / pause, reset, and 0.5x–4x speed control

How it works

Every tick (Market.tick, core/market.py):

1. Stale orders are evicted from the book.
2. Each agent returns one or more limit orders (agent.act(market)).
3. New orders are submitted to the order book and matched against resting orders, producing trades.
4. Price is nudged by the active event's bias, or drifts by random-walk noise.
5. OHLCV candles (10 ticks each) are built and pushed to the UI.

The SimulationThread (core/simulation.py) drives the loop in a background QThread so the UI stays responsive.

Getting Started

Requirements

• Python 3.10+
• Install dependencies:

pip install -r requirements.txt

For the neural trading agent, also install PyTorch:

pip install torch

QuantSim still runs without torch — the ML agent shows as OFF in the status bar and the simulated agents trade using rule-based logic only.

Run it

python main.py

Project Layout

QuantSim/
├── main.py                # Entry point + PyQt6 dashboard
├── requirements.txt
├── agents/
│   ├── base_agent.py      # BaseAgent, Portfolio
│   └── rule_agents.py     # Momentum, Value, Panic, Contrarian, MM, News
├── core/
│   ├── market.py          # Market ticking, candles, events
│   ├── order_book.py      # OrderBook, Order, Trade, matching engine
│   └── simulation.py      # Background simulation thread
├── ml/
│   └── q_agent.py         # PyTorch Q-learning agent (optional)
└── ui/
    ├── chart_widget.py    # Candlestick + volume chart
    ├── leaderboard.py     # Agent standings
    └── theme.py           # Colors and stylesheet

Controls

Control	What it does
▶ Start / ⏸ Pause	Start and pause the simulation
↺ Reset	Reset market price, agent portfolios, and candles
🎲 Random Event	Inject a random market event
Event dropdown → Inject	Inject a specific event
Speed slider	Run simulation at 0.5x–2x speed

Disclaimer

This is an educational simulation. No real money, feeds, or market data are involved — price paths are synthetic.

License

MIT