orderwave 0.2.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()
figure = market.plot()

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

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

Public API

from orderwave import Market

market = Market(
    init_price=100.0,
    tick_size=0.01,
    levels=5,
    seed=42,
    config={"preset": "balanced"},
)

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
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

Market.plot() is the default overview figure. It combines the quote-driven path, last-trade path, trade strength, and a signed visible-depth heatmap.

market = Market(seed=42)
market.gen(steps=1_000)

overview = market.plot()
book = market.plot_book()
diagnostics = market.plot_diagnostics()

Overview

Current Book Snapshot

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.

Snapshot Semantics

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

Important distinction:

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

Docs

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

Design 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
• Aggregate depth is modeled without exposing per-order FIFO complexity in v1