orderwave 0.4.16

An order-flow-driven synthetic market simulator.

orderwave

Order-flow-driven aggregate order-book market-state simulation for Python, with built-in visualization.

orderwave does not random-walk price directly. It simulates a sparse aggregate order book, participant-conditioned limit flow, marketable flow, cancellations, latent meta-orders, exogenous shocks, and session-aware state changes, then lets price emerge from those book mechanics. The same Market object can render the path, the current book snapshot, and built-in market-state diagnostics without extra plotting glue.

orderwave is an aggregate order-book market-state simulator. It is designed to generate believable intraday market paths, book states, and regime changes for research, visualization, and sandbox experimentation. It does not try to present itself as an order-level matching or fill-precision simulator.

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

Why orderwave

• Minimal public entry point: from orderwave import Market
• Market is the supported public API; engine and model internals are implementation details
• Price changes only as a consequence of book mechanics
• Hidden fair value, session clock, shocks, and meta-orders bias flow without directly overwriting price
• Same seed, same path
• Built-in figures for overview, current book, and diagnostics
• Thin public event history plus optional latent debug history

Installation

pip install orderwave

For local development:

pip install -e .[dev]

Quick Start

from orderwave import Market

market = Market(seed=42, preset="trend")
result = market.run(steps=1_000)

snapshot = market.get_snapshot()
history = market.get_history()
events = market.get_labeled_event_history()
overview = market.plot()
book = market.plot_book()
diagnostics = market.plot_diagnostics()

print(snapshot.session_phase, snapshot.mid_price, snapshot.best_bid, snapshot.best_ask)
print(history.tail())
print(events.tail())
print(result.debug_history.tail())

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

For lighter long runs where you only need summary history, visible book snapshots, and trade strength:

fast_market = Market(seed=7, preset="balanced", logging_mode="history_only")
summary = fast_market.run(steps=10_000).history
figure = fast_market.plot()

Performance Measurement

Use the single performance runner when you want a quick throughput check plus a full vs history_only logging comparison.

python -m scripts.measure_performance --preset balanced --seeds 20 --steps 20000 --outdir artifacts/performance

The runner writes:

• performance_metrics.csv
• performance_summary.csv
• performance_logging_modes.csv
• performance_summary.md

Validation Sweep

The repository also includes a validation runner for preset sweeps, knob sensitivity, reproducibility checks, and soak tests.

python -m scripts.validate_orderwave --profile quality_regression --jobs 4 --outdir artifacts/validation

The runner writes:

• validation_summary.md
• run_metrics.csv
• preset_summary.csv
• sensitivity_summary.csv
• invariant_failures.csv
• acceptance_decision.md
• diagnostics_<preset>_<seed>.png when diagnostics rendering is enabled

Release builds run a separate Release Validation job that executes the shorter --profile release_smoke regression and compares it against tests/golden/validation_release_baseline.json before PyPI publish. That smoke profile is intentionally kept small so the CI validation gate stays fast.

The current engine roadmap is broader market-state fidelity: stronger preset separation, richer time structure, cleaner sensitivity control, and better validation artifacts.

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
run(steps=n)	Run n micro-batches and return a bundled typed result
get()	Return the current snapshot
get_snapshot()	Return the current snapshot as a typed dataclass
get_history()	Return compact pandas.DataFrame history
get_event_history()	Return the applied event log as a pandas.DataFrame
get_debug_history()	Return event-aligned latent debug history for advanced inspection
get_labeled_event_history()	Return event history joined with latent debug labels
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 session, excitation, imbalance, spread/volatility, resiliency, and occupancy diagnostics

Advanced configuration is available through orderwave.config.MarketConfig. Common settings can also be passed directly as Market(..., preset="trend", logging_mode="history_only", liquidity_backstop="off").

logging_mode="history_only" keeps summary history plus overview/book plotting data, but disables get_event_history(), get_debug_history(), and plot_diagnostics(). Default liquidity_backstop="on_empty" restores a missing side without forcing minimum visible depth after every step. Use "always" when you want a more aggressively stabilized book, or "off" when you want to allow thinner post-step liquidity.

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, realized-trade imbalance, and signed visible-depth heatmap
• plot_book() renders the current order book on a real price axis
• plot_diagnostics() renders session phase profile, imbalance lead, market-flow excitation, spread-volatility coupling, depletion resiliency, and regime or shock occupancy

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 session clock fields, prices, spread, visible depth, aggressive volume, trade strength, depth imbalance, and regime.

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

Market.run() returns a SimulationResult bundle with the typed snapshot plus whichever tables are available for the current logging mode.

Important distinction:

• mid_price can move when quotes improve, cancel, or get depleted
• last_price only changes when a trade actually executes
• day, session_step, and session_phase expose the synthetic intraday clock

Core guarantees:

• Price is never random-walked directly
• Quote improvement, best-quote depletion, and market trades 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()
• Participant type, meta-order progress, burst state, and shock state are available through get_debug_history()
• Aggregate depth is modeled without exposing per-order FIFO complexity in v1

Docs

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

orderwave.validation is also a supported advanced API for reproducibility checks, sensitivity sweeps, and validation pipelines.