_{One 300-second run · seed 7 · N=64 · generated by render_run()}

Why Market Wave?

Market Wave generates a market from orders and executions—not from a latent price series that is corrected after the fact.

• Exact microstructure — continuous-time arrivals, maker-price execution, strict price-time priority, partial fills, resting remainders, and expiry.
• Adaptive order flow — an ensemble of predictive laws learns from every completed step at different memory scales.
• Visible-liquidity feedback — the live book can reshape marketable and spread-improving flow without moving prices directly.
• Native performance — the market, order book, RNG, flow, and projection solver run in Rust through PyO3.
• Reproducible experiments — explicit configuration, immutable results, and deterministic seeded sequences for the same release and platform target.
• Honest visualization — event-time fills, step-end states, real interval widths, shared comparison scales, and no invented midpoint.

Market Wave models aggregate market intent, not named traders. It is a research simulator, not a forecasting or venue-calibration product.

Installation

Published wheels include the native Rust engine and support CPython 3.10+.

pip install market-wave

Visualization is optional:

pip install "market-wave[visualization]"

Building from source requires Rust 1.83+.

Quick start

from market_wave import Market, MarketConfig, Trade

market = Market(
    MarketConfig(
        initial_price=100_000,
        tick_size=1,
        step_seconds=1.0,
        order_rate=20.0,
        mean_price_offset_ticks=4.0,
        mean_order_size_lots=3.0,
        mean_order_lifetime_seconds=5.0,
        flow_component_count=64,
        seed=7,
    )
)

steps = market.step(300)
last = steps[-1]
executed_lots = sum(
    event.quantity
    for step in steps
    for event in step.events
    if isinstance(event, Trade)
)

print("best bid:", last.book.best_bid)
print("best ask:", last.book.best_ask)
print("executed lots:", executed_lots)

step() and step(1) return one Step; step(0) returns (); values above one return tuple[Step, ...]. Use market.stream(count) when results should be consumed lazily.

Visualization

The optional visualization namespace exposes three focused renderers:

from market_wave.visualization import (
    render_book,
    render_comparison,
    render_run,
)

render_run(steps, "run.png", title="Reference run", level_count=10)
render_book(steps[-1], "book.png", level_count=10)
render_comparison(
    {"baseline": steps, "alternative": alternative_steps},
    "comparison.png",
    columns=2,
)

Rendering is non-mutating and writes an atomically replaced PNG. Prices are converted to integer tick offsets before float plotting, so very large absolute prices retain their local structure. Bilateral depth uses real step widths and the fixed row order Ask LN … Ask L1 | Bid L1 … Bid LN.

To regenerate the repository's 32-scenario factorial atlas:

uv run python benchmarks/visualize_32_scenarios.py

How it works

N predictive laws at different memory scales
                  │
                  ▼
combine side, price, quantity, and lifetime marginals
                  │
                  ▼
condition feasible order flow on visible liquidity
                  │
                  ▼
sample → submit → match → rest → expire
                  │
                  ▼
feed the completed Step back to every law

Adaptive ensemble

Law i retains rho_i = (i + 0.5) / N of its prior evidence. The evenly spaced retention spectrum supplies short and long memory without a hand-tuned decay schedule. Every law observes the same completed market step.

Direct marginal sampling

The engine combines the ensemble before each draw, then samples mathematically equivalent conditional components directly: discrete-Laplace price offsets, geometric quantities, and exponential resting lifetimes. Component selection is ephemeral and never decides which laws receive feedback.

Liquidity-aware flow

When the visible book admits a support-preserving solution, a minimum-KL projection reweights marketable, spread-improving, and neutral price regions. Conditional shapes remain intact. If projection is infeasible, the aggregate unconditioned distribution is used.

Exact matching lifecycle

Crossing orders consume resting liquidity at maker prices. Only the unfilled remainder rests, expiry begins at rest time, and fully filled orders cannot later cancel. Feedback is applied once, after the half-open step completes.

Configuration

Every MarketConfig field is explicit and required.

Prices and quantities remain exact Python integers throughout the public model.

Public API

Calling step() or consuming stream() mutates only the market's forward state. Returned events, steps, books, and distributions do not retain a mutable engine back-reference.

Performance and validation

The repository tests matching invariants, event lifecycles, seeded reproducibility, conditional marginal sampling, numerical boundaries, native batching, parallel markets, adaptive feedback, and visualization semantics.

uv run python benchmarks/benchmark_market.py

On the release validation host (Linux x86-64, CPython 3.14), the default flow_component_count=64 workload measured 4.04 ms/step after warm-up, or 247.6 steps/s. Treat this as a comparison point, not a runtime guarantee.

Development

uv sync --extra dev
uv run maturin develop --release --locked
uv run pytest
cargo test --manifest-path rust/Cargo.toml

Release artifacts are built for Linux glibc, Linux musl, macOS universal2, and Windows through GitHub Actions. See the changelog for versioned behavior changes.

Scope and license

Market Wave intentionally has no CLI, persistence layer, replay engine, hidden calibration state, named-agent model, or financial forecast. Callers decide which generated immutable results to retain.

Released under the MIT License.