Python之yahtzee-solve包语法、参数和实际应用案例

Python yahtzee-solve 完整使用指南

一、包基础概述

1. 简介

yahtzee-solve 是针对快艇骰子（Yahtzee，雅达西骰子） 的专用Python计算工具包，核心用于骰子点数计算、最优决策求解、得分模拟、概率分析、牌型判定，专为Yahtzee桌游规则设计，支持标准5骰子玩法、官方计分规则、概率推演、最优落子策略计算，是骰子博弈、规则模拟、小游戏开发、概率算法练习的轻量工具。

快艇骰子(Yahtzee)规则简述：掷5颗骰子，最多重掷2轮，按不同牌型计分，包含顺子、满堂红、四枚相同、五枚相同(Yahtzee)等十余种计分项。

2. 核心功能

二、安装方式

该包发布于 PyPI，支持 Python 3.7+ 全版本，Windows/Linux/macOS 通用。

1. 标准安装（推荐）

pip install yahtzee-solve

2. 国内镜像加速（安装失败时使用）

# 清华镜像
pip install yahtzee-solve -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 版本查看/升级

# 查看已安装版本
pip show yahtzee-solve

# 升级到最新版
pip install –upgrade yahtzee-solve

4. 验证安装

Python 终端执行导入，无报错即安装成功：

import yahtzee_solve

三、核心语法、模块、类与参数

yahtzee-solve 采用面向对象设计，核心分为：骰子对象、牌型判定器、计分器、策略求解器、概率模拟器五大模块。

包主入口：yahtzee_solve，常用别名建议：import yahtzee_solve as ys

（一）基础数据结构：骰子组合

Yahtzee 固定使用 5颗骰子，骰子点数范围 1~6，入参格式统一：

• 列表/元组：[1,2,3,4,5]、(6,6,6,2,2)
• 必须长度=5，元素为 1-6 整数

（二）核心类与常用方法（全参数详解）

1. Dice 骰子核心类

用于初始化骰子、重置、随机掷骰、修改点数。

from yahtzee_solve import Dice

# 构造方法
d = Dice(dice_list: list[int])

参数：

• dice_list：必传，长度为5的列表，元素 1~6

常用实例方法：

下标规则：骰子下标 0,1,2,3,4 对应第1~5颗骰子。

2. ScoreCalculator 计分器（核心）

按Yahtzee官方13项计分规则计算得分，是使用频率最高的类。

from yahtzee_solve import ScoreCalculator
sc = ScoreCalculator(dice: list[int])

参数：dice：5点骰子列表

13项官方计分方法（全语法+规则）

Yahtzee 标准13个计分项，一一对应：

调用语法：

sc.ones() # 计算1分项得分
sc.full_house() # 计算满堂红得分
sc.yahtzee() # 计算雅达西五连得分

3. HandAnalyzer 牌型分析器

判定当前骰子属于哪些牌型、统计点数分布，辅助决策。

from yahtzee_solve import HandAnalyzer
ha = HandAnalyzer(dice: list[int])

核心方法：

• .is_yahtzee()：是否五连相同 → bool
• .is_full_house()：是否满堂红 → bool
• .is_three_kind()：是否三条 → bool
• .is_four_kind()：是否四条 → bool
• .is_small_straight()：是否小顺子 → bool
• .is_large_straight()：是否大顺子 → bool
• .get_count()：统计每个点数出现次数 → dict

4. StrategySolver 最优策略求解器

输入当前骰子，返回最优保留/重掷方案（桌游核心决策工具）。

from yahtzee_solve import StrategySolver
ss = StrategySolver(current_dice: list[int])

核心方法：

• .get_best_keep()：返回建议保留的骰子下标列表
• .get_best_reroll()：返回建议重掷的骰子下标列表
• .estimate_max_score()：估算当前组合理论最高得分

5. Probability 概率计算器

计算重掷后达成目标牌型的概率。

from yahtzee_solve import Probability
pb = Probability()

核心方法：

• .calc_prob_yahtzee(keep_num)：保留keep_num颗骰子时，掷出五连的概率
• .calc_prob_straight(keep_dice)：基于现有骰子，达成顺子的概率

四、8个实战应用案例（可直接运行）

所有案例基于标准Yahtzee规则，代码完整、注释清晰，覆盖基础使用、计分、判型、策略、概率、模拟等全场景。

案例1：基础骰子初始化 + 随机掷骰

功能：创建骰子、全局重掷、查看点数

from yahtzee_solve import Dice

# 初始化5颗骰子
d = Dice([1, 2, 3, 4, 5])
print("初始骰子：", d.get_values())

# 全部重掷
d.roll()
print("重掷后骰子：", d.get_values())

案例2：单项计分计算（基础得分）

功能：计算1~6点数分项、机会牌得分

from yahtzee_solve import ScoreCalculator

dice = [3, 3, 3, 2, 5]
sc = ScoreCalculator(dice)

print("点数3总分：", sc.threes())
print("机会牌总分：", sc.chance())
print("点数2总分：", sc.twos())

案例3：特殊牌型计分（满堂红/三条/四条）

功能：判定并计算组合牌型得分

from yahtzee_solve import ScoreCalculator

# 满堂红 3+2
d1 = [6,6,6,2,2]
sc1 = ScoreCalculator(d1)
print("满堂红得分：", sc1.full_house())

# 四条
d2 = [5,5,5,5,1]
sc2 = ScoreCalculator(d2)
print("四条得分：", sc2.four_of_a_kind())

# 三条
d3 = [2,2,2,4,6]
sc3 = ScoreCalculator(d3)
print("三条得分：", sc3.three_of_a_kind())

案例4：顺子 & Yahtzee五连计分

功能：大小顺子、五连雅达西计分

from yahtzee_solve import ScoreCalculator

# 大顺子 1,2,3,4,5
d1 = [1,2,3,4,5]
sc1 = ScoreCalculator(d1)
print("大顺子得分：", sc1.large_straight())
print("小顺子得分：", sc1.small_straight())

# Yahtzee 五连6
d2 = [6,6,6,6,6]
sc2 = ScoreCalculator(d2)
print("Yahtzee五连得分：", sc2.yahtzee())

案例5：牌型自动识别（HandAnalyzer）

功能：批量判断当前骰子所有牌型属性

from yahtzee_solve import HandAnalyzer

dice = [4,4,4,4,2]
ha = HandAnalyzer(dice)

print("是否五连：", ha.is_yahtzee())
print("是否四条：", ha.is_four_kind())
print("是否满堂红：", ha.is_full_house())
print("点数统计：", ha.get_count())

案例6：最优重掷策略求解（桌游实战）

功能：工具给出「保留/重掷骰子」最优方案

from yahtzee_solve import StrategySolver

# 当前骰子：[1,1,2,3,5]
current = [1,1,2,3,5]
ss = StrategySolver(current)

print("建议保留骰子下标：", ss.get_best_keep())
print("建议重掷骰子下标：", ss.get_best_reroll())
print("理论预估最高分：", ss.estimate_max_score())

案例7：指定下标局部重掷骰子

功能：只重掷部分骰子（模拟桌游二次掷骰）

from yahtzee_solve import Dice

d = Dice([2,2,3,4,6])
print("原始骰子：", d.get_values())

# 重掷下标 2、4 的两颗骰子
d.roll_selected([2, 4])
print("局部重掷后：", d.get_values())

案例8：概率计算 + 整局简单模拟

功能：计算凑出Yahtzee五连的概率，模拟一轮游戏流程

from yahtzee_solve import Dice, Probability, ScoreCalculator

# 1. 概率计算
pb = Probability()
# 保留3颗相同骰子，求掷出五连的概率
prob = pb.calc_prob_yahtzee(3)
print("保留3颗同点，凑出Yahtzee概率：", prob)

# 2. 单局模拟
d = Dice([1,1,2,2,3])
d.roll_selected([4]) # 重掷第5颗
final_dice = d.get_values()
sc = ScoreCalculator(final_dice)
print("最终骰子：", final_dice)
print("本局机会牌得分：", sc.chance())

五、常见错误、报错原因与解决方案

1. ValueError: Dice length must be 5

• 原因：传入的骰子列表长度不是5（Yahtzee固定5颗骰子）
• 解决：保证入参列表/元组严格为 len=5

2. ValueError: Dice value out of range (1-6)

• 原因：骰子点数出现 0、7、负数、小数、字符串
• 解决：所有元素必须是 1~6 的整数

3. ModuleNotFoundError: No module named 'yahtzee_solve'

• 原因：未安装包 / 安装环境与运行环境不一致（多Python版本、虚拟环境）
• 解决：
• 确认使用当前环境的 pip 安装：python -m pip install yahtzee-solve
• 检查是否开启虚拟环境

4. IndexError: list index out of range（重掷时报错）

• 原因：roll_selected() 传入的下标超出 0~4 范围
• 解决：骰子下标仅支持 0,1,2,3,4

5. 计分结果始终为0（预期高分却得0）

• 原因：当前骰子不满足对应牌型规则（如非满堂红调用 full_house()）
• 解决：先用 HandAnalyzer 判定牌型，再对应计分。

6. 导入包名称混淆

• 错误写法：import yahtzee_solve as yahtzee 无语法问题，但不要写成：# 错误：包名带横杠不能直接导入
  import yahtzee–solve

• 正确：横杠在Python包名中转为下划线：yahtzee_solve

六、使用注意事项

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。