麻雀ツモ確率計算システム (Mahjong Tsumo Probability Calculator)

注意: このREADMEファイルはCursorのAIアシスタントによって自動生成されました。

このプロジェクトは、麻雀の手牌からツモ確率を計算する高性能なシステムです。動的計画法（Dynamic Programming）を使用して、すべての可能な手牌パターンに対するツモ確率を事前計算し、リアルタイムでの確率分析を可能にします。

プロジェクト概要

このシステムは以下の3つの主要コンポーネントで構成されています：

• common: 麻雀の基本データ構造とユーティリティ
• dp: 動的計画法による確率計算エンジン
• backend: Web APIサーバー（分析結果の提供）

機能

主要機能

• ツモ確率計算: 13枚手牌と14枚手牌の両方に対応
• メンツ実現確率分析: 順子、刻子、対子、国士無双の実現確率を計算
• 高性能計算: 並列処理とメモリ効率的なデータ構造を使用
• Web API: RESTful APIによる分析結果の提供

計算対象

• 通常手（4面子1雀頭）
• 七対子
• 国士無双
• 各メンツタイプの実現確率

技術仕様

言語・フレームワーク

• 言語: Rust 2021 Edition
• Web フレームワーク: Axum
• 並列処理: Rayon
• データ構造: カスタムFlatFileVec（メモリ効率的なファイルベースベクター）

パフォーマンス最適化

• Link Time Optimization (LTO)
• コード生成ユニット数: 1
• panic = "abort"
• デバッグ情報の除去

データサイズ

• 13枚手牌: 322,565,293パターン
• 14枚手牌: 923,597,122パターン
• 計算ラウンド数: 18ラウンド

プロジェクト構造

tsumo_prob/
├── Cargo.toml              # ワークスペース設定
├── common/                 # 共通ライブラリ
│   ├── src/
│   │   ├── mahjong/       # 麻雀関連のデータ構造
│   │   ├── flat_file_vec.rs # メモリ効率的なベクター実装
│   │   └── io.rs          # I/Oユーティリティ
├── dp/                     # 動的計画法エンジン
│   ├── src/
│   │   ├── tsumo.rs       # ツモ確率計算
│   │   ├── metrics.rs     # メンツ実現確率計算
│   │   └── bin/
│   │       └── dp_main.rs # メイン計算プログラム
└── backend/               # Web APIサーバー
    ├── src/
    │   ├── main.rs        # サーバー起動
    │   └── analysis.rs    # 分析エンジン

セットアップ

前提条件

• Rust 1.70以上
• 十分なディスク容量（計算結果の保存用）

インストール

# リポジトリのクローン
git clone <repository-url>
cd tsumo_prob

# 依存関係のインストール
cargo build --release

使用方法

1. 確率データの事前計算

# dp_mainを実行して確率データを計算
cd dp
cargo run --release --bin dp_main

2. Web APIサーバーの起動

# バックエンドサーバーを起動
cd backend
cargo run --release

3. API使用例

# ツモ確率の取得
curl -X POST http://localhost:3000/analyze-tsumo \
  -H "Content-Type: application/json" \
  -d '{"hand": ["1m","2m","3m","4m","5m","6m","7m","8m","9m","1p","2p","3p","4p"]}'

# メンツ実現確率の取得
curl -X POST http://localhost:3000/analyze-mentsu \
  -H "Content-Type: application/json" \
  -d '{"hand": ["1m","2m","3m","4m","5m","6m","7m","8m","9m","1p","2p","3p","4p"], "draws_left": 5}'

データ形式

手牌表記

• 数牌: 1m, 2m, ..., 9m (萬子)
• 数牌: 1p, 2p, ..., 9p (筒子)
• 数牌: 1s, 2s, ..., 9s (索子)
• 字牌: 1z, 2z, ..., 7z (東南西北白發中)

API レスポンス例

{
  "probabilities": [
    {
      "draws_left": 1,
      "probability": 0.123456
    },
    {
      "draws_left": 2,
      "probability": 0.234567
    }
  ]
}

開発者向け情報

計算アルゴリズム

1. 初期化: 和了形の手牌を列挙
2. 動的計画法: 13枚→14枚→13枚の順で確率を計算
3. メンツ分析: 各メンツタイプの実現確率を計算
4. データ保存: 効率的なファイルベースストレージ

メモリ管理

• 大規模データセットの効率的な処理
• シャーディングによるメモリ使用量の制御
• ファイルベースの永続化

ライセンス

このプロジェクトはMITライセンスの下で公開されています。

貢献

プルリクエストやイシューの報告を歓迎します。大きな変更を行う場合は、まずイシューで議論してください。

謝辞

このプロジェクトは麻雀の数学的解析に基づいて開発されています。確率計算の理論的基盤は、麻雀の組み合わせ論と動的計画法の応用です。