orderwave 0.3.0

An order-flow-driven synthetic market simulator.

orderwave

Order-flow-driven synthetic market simulation for Python, with built-in visualization.

orderwave does not random-walk price directly. It simulates a sparse limit order book, stochastic limit arrivals, marketable flow, cancellations, and inside-spread quote improvement, then lets price emerge from those book changes. The same Market object can also render the path, the current book snapshot, and microstructure diagnostics without extra plotting glue.

English Docs | 한국어 README | 한국어 문서

Why orderwave

• Minimal public entry point: from orderwave import Market
• Price changes only as a consequence of book mechanics
• Hidden fair value biases order flow without directly overwriting price
• Same seed, same path
• Built-in figures for overview, current book, and diagnostics

Installation

pip install orderwave

For local development:

pip install -e .[dev]

Quick Start

from orderwave import Market

market = Market(seed=42, config={"preset": "trend"})
market.gen(steps=1_000)

snapshot = market.get()
history = market.get_history()
events = market.get_event_history()
overview = market.plot()
book = market.plot_book()
diagnostics = market.plot_diagnostics()

print(snapshot["mid_price"], snapshot["best_bid"], snapshot["best_ask"])
print(history.tail())
print(events.tail())

overview.savefig("orderwave-overview.png")

API Surface

API	Purpose
step()	Run one micro-batch and return the latest snapshot
gen(steps=n)	Run n micro-batches and return the latest snapshot
get()	Return the current snapshot
get_history()	Return compact pandas.DataFrame history
get_event_history()	Return the applied event log as a pandas.DataFrame
plot()	Render price, spread, trade strength, and visible-book heatmap
plot_book()	Render the current order book on a real price axis
plot_diagnostics()	Render spread, imbalance, volatility, and regime diagnostics

Advanced configuration is available through orderwave.config.MarketConfig.

Built-in Visualization

All plotting methods return matplotlib.figure.Figure and leave save/show control to the caller.

• plot() renders the main overview: price, spread, execution-only trade strength, and signed visible-depth heatmap
• plot_book() renders the current order book on a real price axis
• plot_diagnostics() renders spread, imbalance, non-zero absolute-return autocorrelation, and regime diagnostics

The overview heatmap keeps signed depth. Ask liquidity is red, bid liquidity is blue, 0 maps to a light gray midpoint, and missing levels render as blank background instead of black cells.

Presets At A Glance

balanced, trend, and volatile reuse the same public API while shifting spread behavior, flow pressure, cancellation pressure, and hidden fair-price dynamics.

Core Semantics

Market.get() returns a compact dictionary with prices, spread, visible depth, aggressive volume, trade strength, depth imbalance, and regime.

trade_strength is an execution-only signed imbalance. It is computed from an EWMA of realized aggressor buy and sell volume, so quote-only book changes do not move it.

Important distinction:

• mid_price can move when quotes improve, cancel, or get depleted
• last_price only changes when a trade actually executes

Core guarantees:

• Price is never random-walked directly
• Quote improvement, best-quote depletion, and market execution are the only price-moving mechanisms
• Visible history starts at step == 0 with the seeded initial book
• Applied limit, market, and cancel events are available through get_event_history()
• Aggregate depth is modeled without exposing per-order FIFO complexity in v1

Docs

• Documentation index
• Getting started
• API reference
• Examples
• Release guide
• 한국어 문서 인덱스