Metadata-Version: 2.4
Name: orderwave
Version: 0.6.5
Summary: A compact aggregate order-book market simulator.
Project-URL: Homepage, https://github.com/smturtle2/quoteflow
Project-URL: Documentation, https://github.com/smturtle2/quoteflow/tree/main/docs/en
Project-URL: Repository, https://github.com/smturtle2/quoteflow
Project-URL: Issues, https://github.com/smturtle2/quoteflow/issues
Keywords: order-book,market-simulation,microstructure,synthetic-data,finance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"

# orderwave

Compact aggregate order-book simulation for Python, with readable built-in heatmaps.

`orderwave` keeps the runtime model small: a sparse bid/ask book, bounded mean-reverting fair value, and a regime-aware queue-reactive liquidity kernel that drives buy/sell flow clustering, side-specific cancel pressure, refill lag, execution episodes, and gap recovery without reintroducing the older heuristic stack.

![Overview](docs/assets/orderwave-built-in-overview.png)

## Install

```bash
pip install orderwave
```

## Quick Start

```python
from orderwave import Market

market = Market(seed=42, capture="visual")
result = market.run(steps=1_000)

snapshot = result.snapshot
history = result.history
overview = market.plot()
heatmap = market.plot_heatmap(anchor="price")
book = market.plot_book()
```

## Public API

- `Market(...)`: create a simulator with an initial price, tick size, visible depth, seed, optional `MarketConfig`, and `capture="summary" | "visual"`.
- `step()`: advance one step and return the latest snapshot.
- `gen(steps)`: run multiple steps and return the latest snapshot.
- `run(steps)`: return `SimulationResult(snapshot=..., history=...)`.
- `get()`: return the current snapshot as a `dict`.
- `get_history()`: return the summary history as a `pandas.DataFrame`.
- `plot()`: render the price path with a stable level-ranked signed-depth heatmap. Requires `capture="visual"`.
- `plot_heatmap(anchor="mid" | "price")`: render a standalone heatmap on stable level coordinates. Requires `capture="visual"`.
- `plot_book()`: render the current order book.

`capture="summary"` keeps the fast path lean. `capture="visual"` stores a fixed signed-depth window around the moving market center so the heatmap can show sweep, void, and refill structure clearly. Heatmap rows are always fixed visible ranks, laid out as `ask N ... ask 1 | bid 1 ... bid N`, so they do not drift vertically with price.

## Snapshot and History

Snapshot fields:

- `step`
- `last_price`
- `mid_price`
- `best_bid`
- `best_ask`
- `spread`
- `bids`
- `asks`
- `bid_depth`
- `ask_depth`
- `depth_imbalance`
- `buy_aggr_volume`
- `sell_aggr_volume`
- `fair_price`

History columns:

- `step`
- `last_price`
- `mid_price`
- `best_bid`
- `best_ask`
- `spread`
- `bid_depth`
- `ask_depth`
- `depth_imbalance`
- `buy_aggr_volume`
- `sell_aggr_volume`
- `fair_price`

## Model

- Fair price follows a bounded mean-reverting Gaussian process with short-memory flow feedback.
- Buy/sell market flow, bid/ask cancel flow, and bid/ask limit flow all use state-dependent Poisson intensities rather than one shared shuffled event pool.
- The internal kernel tracks buy/sell flow impulse, side-specific cancel pressure, side-specific refill lag, gap pressure, hidden liquidity regime, and persistent execution pressure.
- Limit placement is split into join, touch refill, gap fill, connected shelf, and isolated wall families so the book can hold holes and recover instead of being perfectly refilled every step.
- Repair is safety-only: it prevents one-sided or crossed books, but it no longer backfills every visible level.

## Realism Profiling

Profile generic microstructure behavior with:

```bash
python -m scripts.profile_realism --steps 5000
```

The profiler reports spread/impact persistence, trade-sign autocorrelation, top-rank gap frequency, per-rank depth shape, shock-side cancel/refill skew, hidden regime occupancy, and connected-vs-isolated deep liquidity structure.

## Documentation Assets

![Book](docs/assets/orderwave-built-in-current-book.png)

![Diagnostics](docs/assets/orderwave-built-in-diagnostics.png)

![Variants](docs/assets/orderwave-built-in-presets.png)

Regenerate the documentation images with:

```bash
python -m scripts.render_doc_images
```

Render the standalone heatmap example with:

```bash
python -m examples.plot_market_heatmap --output artifacts/orderwave_heatmap.png
```

More docs:

- English: [docs/en/README.md](docs/en/README.md)
- Korean: [README.ko.md](README.ko.md)
- Release process: [docs/en/releasing.md](docs/en/releasing.md)
