Market Wave

Adaptive order flow. Exact price-time matching. No hidden price path.

A seeded, in-memory continuous double auction for market-microstructure experiments and synthetic scenario generation.

PyPI Python CI License

Quick start · Visualization · Model · API · Development

Market Wave run report with quotes, maker-price fills, bilateral depth, spread, and order flow

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,
)
Renderer Question answered
render_run() How did quotes, fills, depth, spread, and order flow evolve?
render_book() What exactly was resting at one selected step?
render_comparison() How do several runs differ on shared price and depth scales?

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.

Field Contract
initial_price positive integer, aligned to tick_size
tick_size positive integer
step_seconds finite seconds greater than zero
order_rate finite expected orders/second, at least zero
mean_price_offset_ticks finite mean absolute offset, at least zero
mean_order_size_lots finite mean quantity, at least one
mean_order_lifetime_seconds finite mean resting lifetime greater than zero
flow_component_count positive ensemble size N
seed integer

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

Public API

Surface Contract
Market.step(n=1) eagerly advances consecutive feedback intervals
Market.stream(count) lazily advances the same market
Step.events chronological Submission, Trade, and Cancellation values
Step.book immutable step-end BookSnapshot
Market.book current immutable book snapshot
Market.buy_distribution, sell_distribution current aggregate price laws
EntryDistribution.probability(), .cdf() exact aggregate price PMF and CDF
market_wave.visualization optional run, book, and comparison PNG renderers

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.

Project links

Data verified by PyPI on Jul 12, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for smturtle2 from gravatar.com smturtle2

Credits

Author: market-wave

GitHub Statistics

Data verified by PyPI on Jul 12, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev visualization

Tags

limit-order-book market-microstructure market-simulation stochastic-simulation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

market_wave-2.2.0.tar.gz (45.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

market_wave-2.2.0-cp310-abi3-win_amd64.whl (266.7 kB view details)

Uploaded CPython 3.10+Windows x86-64

market_wave-2.2.0-cp310-abi3-musllinux_1_2_x86_64.whl (570.2 kB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ x86-64

market_wave-2.2.0-cp310-abi3-musllinux_1_2_aarch64.whl (515.2 kB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

market_wave-2.2.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (364.4 kB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

market_wave-2.2.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (339.5 kB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

market_wave-2.2.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (613.4 kB view details)

Uploaded CPython 3.10+macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

File details

Details for the file market_wave-2.2.0.tar.gz.

File metadata

  • Download URL: market_wave-2.2.0.tar.gz
  • Upload date:
  • Size: 45.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for market_wave-2.2.0.tar.gz
Algorithm Hash digest
SHA256 0acc11c7f948dc40ce4d3be65aaa0277370397a8c6b81c9cf1a7b02d11a6b55d
MD5 ea13084f379440b53cb02b823ab853e6
BLAKE2b-256 3c7b757dc9085be130982ac1bb1b2c38f2e4aabea98c402e96d8dd454950af12

See more details on using hashes here.

Provenance

The following attestation bundles were made for market_wave-2.2.0.tar.gz:

Publisher: workflow.yml on smturtle2/market-wave

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file market_wave-2.2.0-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: market_wave-2.2.0-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 266.7 kB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for market_wave-2.2.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 567369a81822a77da3891175e64006cd1226190834c32f968347d84fb893fe10
MD5 d1387670381d63257b1ea116acb68557
BLAKE2b-256 ed2ee120234acbf1428e0abad60afff1b785abb61190283cd494ed29a7eec5f9

See more details on using hashes here.

Provenance

The following attestation bundles were made for market_wave-2.2.0-cp310-abi3-win_amd64.whl:

Publisher: workflow.yml on smturtle2/market-wave

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file market_wave-2.2.0-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for market_wave-2.2.0-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 74ef350cae147c50e4148dc0a50cfc83113d6751750287f77622ebda669f0d1e
MD5 1a99f756aaee5f349120a8071663abf4
BLAKE2b-256 b798d0cc0188b98a5917e53df7fa166ba35f8438901958f85d18047baa88cd56

See more details on using hashes here.

Provenance

The following attestation bundles were made for market_wave-2.2.0-cp310-abi3-musllinux_1_2_x86_64.whl:

Publisher: workflow.yml on smturtle2/market-wave

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file market_wave-2.2.0-cp310-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for market_wave-2.2.0-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 e617d6b4469252f670e2b20a74909e535f13a3b1e5396c57b5d5f93f1f89b9b9
MD5 36f5c1d90d87f0027d750c2364709598
BLAKE2b-256 47b37857abfd99075185695c6ba147514e2e80032288db6b5029a22d938e3c0d

See more details on using hashes here.

Provenance

The following attestation bundles were made for market_wave-2.2.0-cp310-abi3-musllinux_1_2_aarch64.whl:

Publisher: workflow.yml on smturtle2/market-wave

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file market_wave-2.2.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for market_wave-2.2.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a316c5189cea1b8091c84f3e1cc1c797923762941196b67e11490ffca501397c
MD5 8b89684dedaf0d1c56a4b98b47efa673
BLAKE2b-256 8ae53cb5b6a85475c1b395b385fb39569a3632623628fb4e7c3209e5850073d4

See more details on using hashes here.

Provenance

The following attestation bundles were made for market_wave-2.2.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: workflow.yml on smturtle2/market-wave

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file market_wave-2.2.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for market_wave-2.2.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 2fb65f7763a99ca54ebe2a0270de0d2e212d3dd94ca225e523385a75a5fa9188
MD5 73fac23c03946233168fb569ed7da107
BLAKE2b-256 bcce6290819cce02d853f83fb8bbc5e69c4a7a40ccaf7c82468ee9ae35be4545

See more details on using hashes here.

Provenance

The following attestation bundles were made for market_wave-2.2.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: workflow.yml on smturtle2/market-wave

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file market_wave-2.2.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for market_wave-2.2.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 7afb0392964bd716f474b656ad33b5fdca261b8fb986e9dbba55fd4d5e7c2453
MD5 6e1ec2b16c3894f0d8ee354fa6ece283
BLAKE2b-256 45e122021ff9c2975f367f612ab88cc80200767681e858ad8728697a5ac11538

See more details on using hashes here.

Provenance

The following attestation bundles were made for market_wave-2.2.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl:

Publisher: workflow.yml on smturtle2/market-wave

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

2.2.0 This release

7 files

2.1.0

7 files

2.0.0

2 files

1.0.0

2 files

0.5.0

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.1

2 files

0.3.0

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page