market-wave 0.1.0__tar.gz

market_wave-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,40 @@
+name: Python
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run pytest
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

market_wave-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+__pycache__/
+*.py[cod]

market_wave-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Small Turtle 2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

market_wave-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: market-wave
+Version: 0.1.0
+Summary: Discrete mixture distribution market intent simulator
+Project-URL: Homepage, https://github.com/smturtle2/market-wave
+Project-URL: Repository, https://github.com/smturtle2/market-wave
+Author: Small Turtle 2
+License-Expression: MIT
+License-File: LICENSE
+Keywords: discrete-distribution,market,orderbook,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.8
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# market-wave
+
+<p align="center">
+  <img src="docs/assets/market-wave-hero.png" alt="market-wave abstract market intent simulation hero" />
+</p>
+
+<p align="center">
+  <strong>Aggregate market intent simulation with discrete mixture distributions.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/market-wave/"><img alt="PyPI" src="https://img.shields.io/pypi/v/market-wave"></a>
+  <a href="https://pypi.org/project/market-wave/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/market-wave"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <a href=".github/workflows/workflow.yml"><img alt="Tests" src="https://img.shields.io/badge/tests-pytest-2563eb"></a>
+</p>
+
+<p align="center">
+  English | <a href="README.ko.md">한국어</a>
+</p>
+
+`market-wave` is a Python library for simulating market-wide entry and exit intent
+without creating individual participants. It models aggregate buy/sell pressure,
+position exits, order-book depth, cancellations, taker flow, and execution-driven
+price movement on a discrete price grid.
+
+It is not a forecasting model. It is a lightweight simulation primitive for
+experiments, visualization, teaching, and strategy-environment prototyping.
+
+## Why market-wave?
+
+- **Aggregate intent, not agents**: market participants are represented by
+  probability mass over price, not by individual objects.
+- **Discrete mixture distributions**: entry and exit pressure are PMFs on the
+  current price grid.
+- **Execution-driven prices**: prices stay flat unless trades execute.
+- **Inspectable state**: every step returns a `StepInfo` snapshot with PMFs,
+  volumes, order book state, position mass, VWAP, spread, and imbalance.
+- **Built-in plotting**: `matplotlib` is included, with a clean light chart style
+  by default.
+
+## Install
+
+```bash
+pip install market-wave
+```
+
+For local development:
+
+```bash
+git clone https://github.com/smturtle2/market-wave.git
+cd market-wave
+uv sync --extra dev
+```
+
+Python `>=3.10` is supported.
+
+## Quickstart
+
+```python
+from market_wave import Market
+
+market = Market(initial_price=10_000, gap=10, popularity=1.0, seed=42)
+steps = market.step(100)
+
+last = steps[-1]
+print(last.price_before, "->", last.price_after)
+print(last.total_executed_volume)
+```
+
+`Market.step(n)` always returns `list[StepInfo]` and appends the same objects to
+`market.history`.
+
+## Visualization
+
+```python
+from market_wave import Market
+
+market = Market(initial_price=10_000, gap=10, popularity=1.0, seed=42)
+market.step(260)
+
+fig, ax = market.plot(last=180)
+```
+
+<p align="center">
+  <img src="docs/assets/market-wave-plot.png" alt="market-wave light pyplot chart showing price, volume, and imbalance" />
+</p>
+
+The default `market_wave` style uses a light three-panel chart: price/VWAP,
+executed volume, and order-flow imbalance. Dark overlay mode is still available:
+
+```python
+fig, ax = market.plot(layout="overlay", style="market_wave_dark")
+```
+
+## Core Concepts
+
+At every step, the market builds a price grid around the current price:
+
+```text
+price_grid = current_price +/- k * gap
+```
+
+The simulator maintains four probability mass functions on that grid:
+
+- `buy_entry_pmf`
+- `sell_entry_pmf`
+- `long_exit_pmf`
+- `short_exit_pmf`
+
+Each PMF is a normalized discrete mixture:
+
+```text
+pmf[x] = sum(component_weight * kernel(x, center_price, spread))
+kernel(x, center, spread) proportional to exp(-abs(x - center) / spread)
+```
+
+The PMFs generate aggregate intent. The order book and execution layer then turn
+that intent into limit flow, taker flow, cancellations, exits, matched volume, and
+price changes.
+
+## Execution Guarantee
+
+Price movement is execution-driven:
+
+- If a step has no executed volume, `price_after == price_before`.
+- If trades execute, `price_after` is derived from that step's execution
+  statistics.
+- `seed` makes the simulation reproducible for the same version and inputs.
+
+This is a simulator, not a market data replay engine and not financial advice.
+
+## API Overview
+
+```python
+from market_wave import (
+    Market,
+    MarketState,
+    IntensityState,
+    LatentState,
+    MixtureComponent,
+    DiscreteMixtureDistribution,
+    DistributionState,
+    OrderBookState,
+    PositionMassState,
+    StepInfo,
+)
+```
+
+Useful `StepInfo` fields include:
+
+- `price_before`, `price_after`, `price_change`
+- `buy_entry_pmf`, `sell_entry_pmf`, `long_exit_pmf`, `short_exit_pmf`
+- `buy_volume_by_price`, `sell_volume_by_price`
+- `executed_volume_by_price`, `total_executed_volume`, `trade_count`
+- `vwap_price`, `best_bid_before`, `best_ask_before`, `spread_after`
+- `orderbook_before`, `orderbook_after`
+- `position_mass_before`, `position_mass_after`
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run pytest
+uv build
+```
+
+## License
+
+MIT

market_wave-0.1.0/README.ko.md

@@ -0,0 +1,167 @@
+# market-wave
+
+<p align="center">
+  <img src="docs/assets/market-wave-hero.png" alt="market-wave 시장 의도 시뮬레이션 히어로 이미지" />
+</p>
+
+<p align="center">
+  <strong>이산 혼합분포로 시장 전체의 진입/탈출 의도를 시뮬레이션합니다.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/market-wave/"><img alt="PyPI" src="https://img.shields.io/pypi/v/market-wave"></a>
+  <a href="https://pypi.org/project/market-wave/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/market-wave"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <a href=".github/workflows/workflow.yml"><img alt="Tests" src="https://img.shields.io/badge/tests-pytest-2563eb"></a>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> | 한국어
+</p>
+
+`market-wave`는 개별 참여자를 만들지 않고 시장 전체의 진입 가격과 탈출 가격
+의도를 시뮬레이션하는 Python 라이브러리입니다. 집계된 매수/매도 압력, 포지션
+청산, 호가창 깊이, 주문 취소, taker flow, 체결 기반 가격 변화를 이산 가격
+그리드 위에서 다룹니다.
+
+이 라이브러리는 가격 예측 모델이 아닙니다. 실험, 시각화, 교육, 전략 환경
+프로토타이핑을 위한 가벼운 시뮬레이션 도구입니다.
+
+## 왜 market-wave인가?
+
+- **개별 agent가 아닌 집계 의도**: 참여자 객체를 만들지 않고 가격별 확률질량으로
+  시장 의도를 표현합니다.
+- **이산 혼합분포**: 진입/탈출 압력을 현재 `price_grid` 위의 PMF로 모델링합니다.
+- **체결 기반 가격**: 체결이 없으면 가격은 움직이지 않습니다.
+- **관찰 가능한 상태**: 매 step마다 PMF, 거래량, 호가창, 포지션 mass, VWAP,
+  spread, imbalance가 담긴 `StepInfo`를 반환합니다.
+- **내장 시각화**: `matplotlib` 기반의 깔끔한 light chart 스타일을 제공합니다.
+
+## 설치
+
+```bash
+pip install market-wave
+```
+
+로컬 개발:
+
+```bash
+git clone https://github.com/smturtle2/market-wave.git
+cd market-wave
+uv sync --extra dev
+```
+
+Python `>=3.10`을 지원합니다.
+
+## 빠른 시작
+
+```python
+from market_wave import Market
+
+market = Market(initial_price=10_000, gap=10, popularity=1.0, seed=42)
+steps = market.step(100)
+
+last = steps[-1]
+print(last.price_before, "->", last.price_after)
+print(last.total_executed_volume)
+```
+
+`Market.step(n)`은 항상 `list[StepInfo]`를 반환하고, 같은 객체들을
+`market.history`에 저장합니다.
+
+## 시각화
+
+```python
+from market_wave import Market
+
+market = Market(initial_price=10_000, gap=10, popularity=1.0, seed=42)
+market.step(260)
+
+fig, ax = market.plot(last=180)
+```
+
+<p align="center">
+  <img src="docs/assets/market-wave-plot.png" alt="가격, 거래량, imbalance를 보여주는 market-wave light pyplot 차트" />
+</p>
+
+기본 `market_wave` 스타일은 가격/VWAP, 체결량, order-flow imbalance를 분리한
+light 3-panel 차트입니다. Dark overlay 모드도 사용할 수 있습니다.
+
+```python
+fig, ax = market.plot(layout="overlay", style="market_wave_dark")
+```
+
+## 핵심 개념
+
+매 step마다 현재 가격 주변에 가격 그리드를 만듭니다.
+
+```text
+price_grid = current_price +/- k * gap
+```
+
+시뮬레이터는 이 그리드 위에 네 개의 확률질량함수를 유지합니다.
+
+- `buy_entry_pmf`
+- `sell_entry_pmf`
+- `long_exit_pmf`
+- `short_exit_pmf`
+
+각 PMF는 정규화된 이산 혼합분포입니다.
+
+```text
+pmf[x] = sum(component_weight * kernel(x, center_price, spread))
+kernel(x, center, spread) proportional to exp(-abs(x - center) / spread)
+```
+
+PMF는 집계 의도를 만들고, 호가창/체결 레이어가 이를 limit flow, taker flow,
+주문 취소, 청산, 체결량, 가격 변화로 바꿉니다.
+
+## 체결 보장
+
+가격 변화는 체결에 의해 발생합니다.
+
+- 해당 step의 체결량이 없으면 `price_after == price_before`입니다.
+- 체결이 있으면 `price_after`는 해당 step의 체결 통계에서 계산됩니다.
+- 같은 버전과 같은 입력에서 `seed`는 재현 가능한 시뮬레이션을 만듭니다.
+
+이 라이브러리는 시장 데이터 replay 엔진이 아니며, 금융 조언도 아닙니다.
+
+## API 개요
+
+```python
+from market_wave import (
+    Market,
+    MarketState,
+    IntensityState,
+    LatentState,
+    MixtureComponent,
+    DiscreteMixtureDistribution,
+    DistributionState,
+    OrderBookState,
+    PositionMassState,
+    StepInfo,
+)
+```
+
+자주 보는 `StepInfo` 필드:
+
+- `price_before`, `price_after`, `price_change`
+- `buy_entry_pmf`, `sell_entry_pmf`, `long_exit_pmf`, `short_exit_pmf`
+- `buy_volume_by_price`, `sell_volume_by_price`
+- `executed_volume_by_price`, `total_executed_volume`, `trade_count`
+- `vwap_price`, `best_bid_before`, `best_ask_before`, `spread_after`
+- `orderbook_before`, `orderbook_after`
+- `position_mass_before`, `position_mass_after`
+
+## 개발
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run pytest
+uv build
+```
+
+## 라이선스
+
+MIT

market_wave-0.1.0/README.md

@@ -0,0 +1,171 @@
+# market-wave
+
+<p align="center">
+  <img src="docs/assets/market-wave-hero.png" alt="market-wave abstract market intent simulation hero" />
+</p>
+
+<p align="center">
+  <strong>Aggregate market intent simulation with discrete mixture distributions.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/market-wave/"><img alt="PyPI" src="https://img.shields.io/pypi/v/market-wave"></a>
+  <a href="https://pypi.org/project/market-wave/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/market-wave"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <a href=".github/workflows/workflow.yml"><img alt="Tests" src="https://img.shields.io/badge/tests-pytest-2563eb"></a>
+</p>
+
+<p align="center">
+  English | <a href="README.ko.md">한국어</a>
+</p>
+
+`market-wave` is a Python library for simulating market-wide entry and exit intent
+without creating individual participants. It models aggregate buy/sell pressure,
+position exits, order-book depth, cancellations, taker flow, and execution-driven
+price movement on a discrete price grid.
+
+It is not a forecasting model. It is a lightweight simulation primitive for
+experiments, visualization, teaching, and strategy-environment prototyping.
+
+## Why market-wave?
+
+- **Aggregate intent, not agents**: market participants are represented by
+  probability mass over price, not by individual objects.
+- **Discrete mixture distributions**: entry and exit pressure are PMFs on the
+  current price grid.
+- **Execution-driven prices**: prices stay flat unless trades execute.
+- **Inspectable state**: every step returns a `StepInfo` snapshot with PMFs,
+  volumes, order book state, position mass, VWAP, spread, and imbalance.
+- **Built-in plotting**: `matplotlib` is included, with a clean light chart style
+  by default.
+
+## Install
+
+```bash
+pip install market-wave
+```
+
+For local development:
+
+```bash
+git clone https://github.com/smturtle2/market-wave.git
+cd market-wave
+uv sync --extra dev
+```
+
+Python `>=3.10` is supported.
+
+## Quickstart
+
+```python
+from market_wave import Market
+
+market = Market(initial_price=10_000, gap=10, popularity=1.0, seed=42)
+steps = market.step(100)
+
+last = steps[-1]
+print(last.price_before, "->", last.price_after)
+print(last.total_executed_volume)
+```
+
+`Market.step(n)` always returns `list[StepInfo]` and appends the same objects to
+`market.history`.
+
+## Visualization
+
+```python
+from market_wave import Market
+
+market = Market(initial_price=10_000, gap=10, popularity=1.0, seed=42)
+market.step(260)
+
+fig, ax = market.plot(last=180)
+```
+
+<p align="center">
+  <img src="docs/assets/market-wave-plot.png" alt="market-wave light pyplot chart showing price, volume, and imbalance" />
+</p>
+
+The default `market_wave` style uses a light three-panel chart: price/VWAP,
+executed volume, and order-flow imbalance. Dark overlay mode is still available:
+
+```python
+fig, ax = market.plot(layout="overlay", style="market_wave_dark")
+```
+
+## Core Concepts
+
+At every step, the market builds a price grid around the current price:
+
+```text
+price_grid = current_price +/- k * gap
+```
+
+The simulator maintains four probability mass functions on that grid:
+
+- `buy_entry_pmf`
+- `sell_entry_pmf`
+- `long_exit_pmf`
+- `short_exit_pmf`
+
+Each PMF is a normalized discrete mixture:
+
+```text
+pmf[x] = sum(component_weight * kernel(x, center_price, spread))
+kernel(x, center, spread) proportional to exp(-abs(x - center) / spread)
+```
+
+The PMFs generate aggregate intent. The order book and execution layer then turn
+that intent into limit flow, taker flow, cancellations, exits, matched volume, and
+price changes.
+
+## Execution Guarantee
+
+Price movement is execution-driven:
+
+- If a step has no executed volume, `price_after == price_before`.
+- If trades execute, `price_after` is derived from that step's execution
+  statistics.
+- `seed` makes the simulation reproducible for the same version and inputs.
+
+This is a simulator, not a market data replay engine and not financial advice.
+
+## API Overview
+
+```python
+from market_wave import (
+    Market,
+    MarketState,
+    IntensityState,
+    LatentState,
+    MixtureComponent,
+    DiscreteMixtureDistribution,
+    DistributionState,
+    OrderBookState,
+    PositionMassState,
+    StepInfo,
+)
+```
+
+Useful `StepInfo` fields include:
+
+- `price_before`, `price_after`, `price_change`
+- `buy_entry_pmf`, `sell_entry_pmf`, `long_exit_pmf`, `short_exit_pmf`
+- `buy_volume_by_price`, `sell_volume_by_price`
+- `executed_volume_by_price`, `total_executed_volume`, `trade_count`
+- `vwap_price`, `best_bid_before`, `best_ask_before`, `spread_after`
+- `orderbook_before`, `orderbook_after`
+- `position_mass_before`, `position_mass_after`
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run pytest
+uv build
+```
+
+## License
+
+MIT

market_wave-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "market-wave"
+version = "0.1.0"
+description = "Discrete mixture distribution market intent simulator"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Small Turtle 2" },
+]
+keywords = ["market", "simulation", "discrete-distribution", "orderbook"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "matplotlib>=3.8",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/smturtle2/market-wave"
+Repository = "https://github.com/smturtle2/market-wave"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/market_wave"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

market_wave-0.1.0/src/market_wave/__init__.py

@@ -0,0 +1,24 @@
+from .distribution import DiscreteMixtureDistribution, MixtureComponent
+from .market import Market
+from .state import (
+    DistributionState,
+    IntensityState,
+    LatentState,
+    MarketState,
+    OrderBookState,
+    PositionMassState,
+    StepInfo,
+)
+
+__all__ = [
+    "DiscreteMixtureDistribution",
+    "DistributionState",
+    "IntensityState",
+    "LatentState",
+    "Market",
+    "MarketState",
+    "MixtureComponent",
+    "OrderBookState",
+    "PositionMassState",
+    "StepInfo",
+]