# SMSS Demo — Quick Start Guide

## What is SMSS?

SMSS (Stock Market Simulation System) is a computational finance research platform that simulates **10,000 adaptive trading agents** in a Limit Order Book (LOB). Agents learn market microstructure through stochastic approximation and converge toward computational equilibrium.

This demo lets you observe the learning process in real time through two synchronized GUIs:
- **Exchange GUI** (left window): Market price, order book, trade flow
- **Trader GUI** (right window): Agent beliefs, learning convergence, wealth dynamics

## System Requirements

- Windows 10/11 (64-bit)
- 8 GB RAM recommended (10,000 agents use ~5 GB)
- No additional software required (all dependencies included)

## How to Run

### Step 1: Launch the System
Double-click **`SMSS_Demo.exe`** (or run `run.bat`).

A splash screen will appear showing the startup sequence:
1. Starting Exchange Engine
2. Initializing market
3. Starting Exchange Monitor (GUI server)
4. Loading Exchange GUI
5. Starting 10,000 Trader Agents
6. Starting Trader Monitor (GUI server)
7. Opening Trader GUI

After ~20 seconds, two windows will appear side by side.

### Step 2: Observe

**Exchange GUI (left window)**:
- Price chart updates in real time
- Order book shows buy/sell depth
- Trade flow shows market activity

**Trader GUI (right window)**:
- **BELIEF PROFILE**: Watch beliefs evolve from flat (no knowledge) to structured
- **BELIEF CONVERGENCE**: WAD convergence test runs automatically — watch the curve decline toward the threshold
- **BW PHASE**: Orbital motion shows market self-correction
- **WEALTH DISTRIBUTION**: Wealth inequality emerges as agents learn differently
- **AGENT SPOTLIGHT**: Track individual agents' P&L and holdings

### Step 3: Interact

In the Trader GUI sidebar, you can:
- **Switch language**: EN / 中文 (DISPLAY section, bottom)
- **Slow down**: Adjust simulation speed for detailed observation (SIM CONTROL section)
- **Switch mode**: Learn → Practice (freeze beliefs, validate)
- **Run WAD Test**: Click "Run Test" in the convergence panel to check equilibrium
- **Track agents**: Enter specific agent IDs in Agent Spotlight

### Step 4: Shut Down

**Close the main (Exchange) window** — this will automatically stop all background processes.

If for any reason processes remain running after closing:
1. Open Task Manager (Ctrl+Shift+Esc)
2. End these processes if present: `smss-engine.exe`, `smss-monitor.exe`, `smss-trader.exe`, `smss-trader-monitor.exe`

The demo automatically stops after **30 minutes**.

## What You're Seeing

### The Learning Process
10,000 agents start with identical, uninformed beliefs (miu_b = miu_s = 1.0, Tvalue = 100). Through millions of order submissions and trade outcomes, they learn:
- **miu_b**: "What is the probability my buy order at price X gets filled?"
- **miu_s**: "What is the probability my sell order at price X gets filled?"
- **Tvalue**: "What profit can I expect from buying at price X?"

### Convergence
The WAD (Weighted Absolute Difference) test measures whether beliefs have stabilized. When the WAD score drops below the threshold line (0.001 for miu, 0.01 for Tvalue), agents have reached **computational equilibrium** — they've learned the market's microstructure.

### Price-Value Dynamics
The fundamental value (Vt) follows an exogenous random walk. The market price tracks Vt through agent learning — this convergence is visible in the Price vs Vt chart in the sidebar.

## About This Demo

This is a **demonstration version** of the SMSS research platform. The full system includes:
- Data persistence (Parquet format, three-stream architecture)
- 6-phase market scheduling (opening/closing auctions)
- Multi-configuration experiment management
- Offline belief convergence analysis tools
- Python SDK for custom trader adapters

**For the full research version, please contact the author.**

## Technical Details

- **Engine**: Rust, price-time priority matching, 14,800 orders/sec
- **Trader Model**: Rust, 10,000 agents with BW/SW decision engine + P&M stochastic approximation
- **GUIs**: React + TypeScript, served via Axum (Rust) web servers
- **Desktop Shell**: Tauri v2 (WebView2)
- **Communication**: ZeroMQ (4-channel: order/feedback/monitor/control)

---

*SMSS — Stock Market Simulation System*
*Developed by Zhu Yu, Renmin University of China*
*Contact: [email placeholder]*
