task5

2025-09-26 16:55:57 +08:00
parent 57a7e9216e
commit 0597239207
12 changed files with 1412 additions and 4 deletions
--- a/task5_readme.md
+++ b/task5_readme.md
@@ -0,0 +1,177 @@
+# Task5: 短牌型EHS交叉验证系统
+
+## 概述
+
+Task5实现了一个完整的短牌型德州扑克EHS交叉验证系统，用于验证短牌型本地生成与xtask导出的EHS的一致性。
+
+## 核心功能
+
+### 验证目标
+从task5_main.py解析xtask导出的数据 → 短牌型生成器重新计算EHS/HIST → EMD距离比较一致性
+
+### 三阶段验证
+1. **River阶段**: EHS单值精确匹配验证
+2. **Turn阶段**: 30-bin直方图分布验证  
+3. **Flop阶段**: 465-bin直方图分布验证
+
+## 文件结构
+
+```
+├── task5_main.py                    
+├── task5_readme.md                  
+├── cross_validation/                
+│   ├── __init__.py
+│   ├── cross_validation.py          #交叉验证
+│   └── parse_data.py                # 导出数据解
+├── shortdeck/                       
+│   └── gen_hist.py                  # 生成直方图
+└── ehs_data/                        # xtask导出数据
+    ├── river_ehs.npy               
+    ├── turn_hist.npy               
+    └── flop_hist.npy              
+```
+
+## 关键特性
+
+
+###  数据类型
+用解析器将xtask导出的数据存储未以下结构：
+```python
+# River EHS记录
+RiverEHSRecord: board_id, player_id, ehs, board_cards, player_cards
+
+# Turn直方图记录  
+TurnHistRecord: board_id, player_id, bins[30], board_cards, player_cards
+
+# Flop直方图记录
+FlopHistRecord: board_id, player_id, bins[465], board_cards, player_cards
+```
+
+### 验证流程
+1. **数据解析**: 从.npy文件解析原始数据生成上述结构
+2. **牌面解码**: 在解析的数据中取样，使用样本的board_cards/player_cards组合成具体牌面
+3. **重新计算**: 使用短牌型生成器根据turn/flop/river（player_cards+board_cards）重算EHS/HIST
+4. **一致性比较**: EMD距离/数值差异分析
+5. **结果统计**: 通过率、平均误差、分布特征
+
+## 使用方法
+
+### 基本运行
+```bash
+python task5_main.py
+```
+
+### 参数配置
+```bash
+python task5_main.py --river-samples 10 --turn-samples 5 --flop-samples 3
+```
+
+### 参数说明
+- `--river-samples`: River阶段验证样本数（默认20）
+- `--turn-samples`: Turn阶段验证样本数（默认10）
+- `--flop-samples`: Flop阶段验证样本数（默认5）
+
+## 输出示例
+
+```
+========== OpenPQLDecoder (短牌型36张牌) ===============
+   初始化短牌型EHS直方图生成器，牌组大小: 36
+   牌型范围: SIX-ACE
+
+    验证River EHS样本 (最大样本数: 5)
+    样本 1: [Qd Ad] + [6s Th Qc Kd Ac]
+      原始EHS: 0.692118
+      重算EHS: 0.692118
+      差异: 0.000000 
+
+    验证Turn直方图样本 (最大样本数: 3)  
+    样本 1: [8h 8s] + [6s Qd Kd Kh]
+      原始直方图: bins=30, sum=13.640, 非零bins=30
+      生成直方图: bins=30, sum=13.677, 非零bins=30
+      归一化后EMD距离: 0.021985
+
+    验证Flop直方图样本 (最大样本数: 2)
+      样本 1: [Qd Kd] + [7h Qh Qs]
+        原始直方图: bins=465, sum=422.320, 非零bins=465
+        生成直方图: bins=465, sum=427.315, 非零bins=465
+        归一化后EMD距离: 1.509076
+
+
+```
+
+## 验证标准
+
+### River阶段
+- **成功标准**: 匹配率 > 80% 且平均差异 < 0.05
+- **评估方法**: 直接数值比较，容差1e-6
+
+### Turn/Flop阶段  
+- **成功标准**: 低EMD率 > 60% 且平均EMD < 0.5
+- **EMD阈值**: < 0.2视为低距离
+- **评估方法**: Wasserstein距离量化分布差异
+
+## 数据处理
+
+### 解码
+```python
+# Board ID → 公共牌组合
+board_cards = decoder.decode_board_id(board_id, num_cards)
+
+# Player ID → 手牌组合  
+player_cards = decoder.decode_player_id(player_id)
+```
+
+### 导出数据结构
+```python
+# river_ehs.npy
+{
+    'board': int64,    # 公共牌ID（5张牌的编码）
+    'player': int64,   # 玩家手牌ID（2张牌的编码）
+    'ehs': float64     # EHS值（0.0-1.0之间的浮点数）
+}
+
+# turn_hist.npy   
+{
+    'board': int64,    # 公共牌ID（4张牌的编码）
+    'player': int64,   # 玩家手牌ID（2张牌的编码）
+    'bins': ndarray    # 30维直方图数组
+}
+
+# flop_hist.npy 
+{
+    'board': int64,    # 公共牌ID（3张牌的编码）
+    'player': int64,   # 玩家手牌ID（2张牌的编码）
+    'bins': ndarray    # 465维直方图数组
+}
+```
+
+### 编码方式
+
+- **Card64编码（用于3-5张公共牌）：**
+64位，每个suit占16位
+每位表示对应rank的牌是否存在
+用于board_id（公共牌）编码
+
+- **Hand<2>编码（用于2张牌）：**
+16位，低8位和高8位分别编码两张牌
+每张牌用8位编码：高4位=suit，低4位=rank
+用于player_id（手牌）编码
+
+## 短牌型
+- **牌组**: 6, 7, 8, 9, T, J, Q, K, A (四花色，共36张)
+- **组合数**: Flop阶段C(31,2)=465, Turn阶段30种可能
+- **EHS计算**: 枚举所有对手组合，计算胜率期望
+
+
+## 版本信息
+
+- **Version**: 1.0
+- **Python**: 3.13+
+- **依赖**: numpy, scipy, dataclasses
+
+## 遗留
+1. **抽样优化**
+2. **牌面同构优化**
+3. **解析数据存储**
+4. **反向验证对比**
+