神经元扑克：用于德州扑克的 OpenAI Gym 环境

这是一个用于训练神经网络玩德州扑克的环境。请尝试构建您自己的玩家模型，并提交拉取请求，以便我们共同协作，打造出最优秀的扑克玩家。

使用方法：

运行：

• 安装 Python 3.11，同时建议安装 PyCharm。
• 使用命令 curl -LsSf https://astral.sh/uv/install.sh | sh 安装 uv。
• 创建虚拟环境并使用 uv sync 安装依赖项。
• 运行 6 名随机玩家相互对战：uv run poker-random-render；或
• 手动控制玩家：uv run poker-keypress-render。
• 自我改进的遗传算法示例：uv run poker-equity-improvement。
• 若要使用 C++ 版本的胜率计算器，还需安装 Visual Studio 2019（或者通过 Cygwin 使用 GCC 也可能可行）。使用时，在运行 main.py 时添加 -c 参数。
• 对于高级用户：uv run poker-dqn-train-cpp 将启动深度 Q 学习智能体的训练，采用 C++ 蒙特卡洛方法以加快计算速度。
• 运行所有测试：uv run pytest（使用 -n 参数可并行运行测试）。

.. figure:: doc/table.gif :alt:

运行分析

在每局游戏结束时，可以通过汇总图表观察玩家的表现。
|image0|

包和模块：

main.py：入口点及命令行解释器。它通过 gym 运行智能体。文件顶部的文档字符串描述了命令行选项，这些选项由 docopt 解析。

gym_env

- ``env.py``：德州扑克无限注版 OpenAI Gym 环境；
- ``rendering.py``：游戏过程中的图形渲染。

agents
~~~~~~
请在此处添加基于您模型的智能体。

- ``agent_random.py``：随机决策智能体。
- ``agent_keypress.py``：通过按键输入做出决策的智能体。
- ``agent_consider_equity.py``：考虑胜率信息的智能体。
- ``agent_keras_rl_dqn.py``：基于 Keras-RL 的深度强化学习智能体。
- ``agent_custom_q1.py``：自定义实现的深度 Q 学习智能体。

请注意，observation 属性是一个字典，包含可用于决策的所有玩家和牌桌信息。

自定义 Q 学习实现

强化学习的自定义实现。该包现已迁至独立仓库：www.github.com/dickreuter/tf_rl

tools

- ``hand_evaluator.py``：评估多名玩家的最佳牌型。
- ``helper.py``：辅助函数。
- ``montecarlo_numpy2.py``：基于 NumPy 的快速蒙特卡洛模拟，用于计算胜率。目前尚未完全正确，部分测试失败。欢迎修复。
- ``montecarlo_python.py``：相对较慢的 Python 版本蒙特卡洛胜率计算工具，支持为其他玩家预设范围。
- ``montecarlo_cpp``：C++ 实现的胜率计算器，速度约为 Python 版本的 500 倍。

tests
^^^^^

- ``test_gym_env.py``：针对环境的测试。
- ``test_montecarlo.py``：针对牌型评估器和 Python 版本胜率计算器的测试。
- ``test_montecarlo_numpy.py``：针对 NumPy 版本蒙特卡洛的测试。


路线图
-------

Agents

• 基于用户交互（按键）的智能体。
• 随机智能体。
• 基于胜率的策略（例如高于阈值时跟注或加注）。
• 结合遗传算法的胜率策略，根据获胜智能体调整阈值。
• 使用 C++ 实现的胜率计算器，显著提升运行速度。
• 基于经验回放的强化学习智能体（深度 Q 学习，基于 Keras-RL）。
• [/] 自定义智能体（详情见上文）。

强化学习：深度 Q 智能体

``neuron_poker.agents.agent_dqn`` 在 Keras-RL 的帮助下实现了深度 Q 学习智能体。可以设置以下参数：

- nb_max_start_steps = 20  # 开始阶段的最大随机动作次数。
- nb_steps_warmup = 75  # 训练开始前的预热步数，应大于 start steps。
- nb_steps = 10000  # 总步数。
- memory_limit = int(nb_steps / 3)  # 限制经验回放缓存大小。
- batch_size = 500  # 从缓存中采样的训练批次大小。

可通过 TensorBoard 观察训练过程（在命令行中运行 ``tensorboard --logdir=./Graph``）。
|image2|


如何贡献
-----------------

从 main.py 启动
~~~~~~~~~~~~~~~~~~~~~~

在 ``main.py`` 中，智能体的启动方式如下（此处向牌桌添加 6 名随机智能体）。若要编辑通过命令行传递给 main.py 的内容，只需在 main.py 文件顶部的文档字符串中添加一行即可。

.. code:: python

    def random_action(render):
        """创建一个有 6 名随机玩家的环境"""
        env_name = 'neuron_poker-v0'
        stack = 500
        self.env = gym.make(env_name, num_of_players=6, initial_stacks=stack)
        for _ in range(num_of_plrs):
            player = RandomPlayer(500)
            self.env.add_player(player)

        self.env.reset()

如您所见，首先需要创建环境，其次将不同智能体添加到牌桌上，最后通过 reset 方法启动游戏。设置 autoplay 为 True 的智能体会自动进行游戏，调用其类中的 action 方法。此外，您也可以使用 PlayerShell 类，此时环境会要求您手动调用 step 函数并循环执行。这在使用其他专为与 gym 接口设计的包时可能很有帮助，例如 Keras-RL。

添加新模型/智能体
^^^^^^^^^^^^^^^^^^^^^^^^^^

示例智能体可在 random_agent.py 中找到。

要构建新的智能体，需创建一个智能体类，并修改以下方法。您需要使用 observation 参数——它包含了当前牌桌、玩家以及智能体自身的状态——作为决定最佳行动的依据。

.. code:: python

    def action(self, action_space, observation):  # pylint: disable=no-self-use
        """必须的方法，根据观察数组和动作空间计算下一步行动。"""
        _ = observation  # 不使用观察结果进行随机决策
        this_player_action_space = {Action.FOLD, Action.CHECK, Action.CALL, Action.RAISE_POT, Action.RAISE_HAlF_POT}
        possible_moves = this_player_action_space.intersection(set(action_space))
        action = random.choice(list(possible_moves))
        return action

观察状态
~~~~~~~~~~~~~~~~~~~

状态以 NumPy 数组的形式表示，包含以下信息：

.. code:: python

class 社区数据:
        def __init__(self, num_players):
            self.current_player_position = [False] * num_players  # ix[0] = 底池庄家
            self.stage = [False] * 4  # one hot：翻牌前、翻牌圈、转牌圈、河牌圈
            self.community_pot: float: 当前牌局的总底池金额
            self.current_round_pot: float: 本轮加入的底池金额
            self.active_players = [False] * num_players  # one hot 编码，0 = 底池庄家
            self.big_blind
            self.small_blind


    class 局面数据：# 以列表形式存在，共8次：
        """翻牌前、翻牌圈、转牌圈和河牌圈，每轮各2次"""

        def __init__(self, num_players):
            self.calls = [False] * num_players  # ix[0] = 底池庄家
            self.raises = [False] * num_players  # ix[0] = 底池庄家
            self.min_call_at_action = [0] * num_players  # ix[0] = 底池庄家
            self.contribution = [0] * num_players  # ix[0] = 底池庄家
            self.stack_at_action = [0] * num_players  # ix[0] = 底池庄家
            self.community_pot_at_action = [0] * num_players  # ix[0] = 底池庄家


    class 玩家数据：
        “玩家特定信息”

        def __init__(self):
            self.position: one hot 编码，0=底池庄家
            self.equity_to_river: 蒙特卡洛模拟
            self.equity_to_river_2plr: 蒙特卡洛模拟
            self.equity_to_river_3plr: 蒙特卡洛模拟
            self.stack: 当前玩家筹码量

如何在 GitHub 上集成你的代码

单靠一个人很难在扑克比赛中战胜世界顶尖水平。因此，这个仓库旨在创建一个协作环境，允许大家添加和评估不同的模型。

要贡献代码，请按照以下步骤操作：

• 安装 PyCharm 并搭建虚拟 Python 环境。可以使用命令 uv sync。
• 如果你想使用快 500 倍的基于 C++ 的胜率计算器，还需要安装 Visual Studio，但这不是必需的。
• 将你的 Fork 复制到本地机器上。你可以在 PyCharm 中直接操作：VCS --> 从版本控制检出 --> Git。
• 添加原始仓库作为远程仓库，并命名为 upstream（与你的 Fork 的连接应称为 origin）。这可以通过 VCS --> Git --> Remotes 来完成。
• 创建新分支：点击右下角的 master，然后选择“新建分支”。
• 进行代码修改。
• 确保所有测试都通过。在 File --> Settings --> Python 集成工具中切换到 pytest（见截图）。|image1| 之后，只需右键点击 tests 文件夹并运行所有测试即可。所有测试必须全部通过。记得为你的代码添加相应的测试，只需将函数命名为 test_...。
• 确保所有测试都成功通过。最好按照上述方法运行 pytest（在 PyCharm 中右键点击 tests 文件夹并执行）。如果测试失败，可以通过右键点击测试并设置断点来调试，甚至可以在断点处打开控制台：https://stackoverflow.com/questions/19329601/interactive-shell-debugging-with-pycharm。
• 提交更改（CTRL+K）。
• 将更改推送到你的 origin（即你的 Fork）（CTRL+SHIFT+K）。
• 若要使你的分支与上游 master 保持同步，尤其是当上游 master 发生更新时：执行 rebase 操作，将你的分支变基到 upstream master。这可能需要解决一些冲突。完成后，务必使用强制推送（ctrl+shift+k），而不是普通的推送。可以通过选择推送旁边的下拉菜单，然后选择“强制推送”来完成（重要提示：不要简单地推送并合并变基后的分支）。
• 在 your.github.com 上创建一个 Pull Request，将你的分支合并到 upstream master。
• 当你的 Pull Request 被批准后，它将会被合并到 upstream/master 中。

.. |image0| image:: doc/pots.png .. |image1| image:: doc/pytest.png .. |image2| image:: doc/tensorboard-example.png

Neuron Poker 快速上手指南

Neuron Poker 是一个基于 OpenAI Gym 的德州扑克环境，专为训练神经网络玩德州扑克而设计。本指南将帮助你快速搭建环境并运行示例。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统: Windows, macOS 或 Linux
• Python 版本: Python 3.11 (必须)
• 推荐 IDE: PyCharm (可选，但推荐用于开发和调试)
• 可选依赖 (高性能模式):
  • 若需使用速度提升约 500 倍的 C++ 胜率计算器，Windows 用户需安装 Visual Studio 2019 (包含 C++ 构建工具)。
  • Linux/Mac 用户可尝试通过 Cygwin 安装 GCC。

安装步骤

本项目推荐使用 uv 进行依赖管理和虚拟环境创建，以获得更快的安装速度。

1. 安装 uv 工具 在终端中运行以下命令安装 uv：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   (注：国内用户若下载缓慢，可手动访问 https://astral.sh/uv/install.sh 下载脚本后本地运行)

2. 克隆项目并同步依赖 进入项目目录，创建虚拟环境并安装所有依赖：

   uv sync
   

基本使用

安装完成后，你可以尝试以下几种运行模式：

1. 运行随机玩家对战（最简单示例）

启动一个包含 6 个随机决策玩家的局，并渲染图形界面：

uv run poker-random-render

2. 手动键盘控制

通过键盘按键手动控制玩家决策：

uv run poker-keypress-render

3. 遗传算法自我进化示例

运行基于遗传算法的胜率改进示例：

uv run poker-equity-improvement

4. 高级：训练深度 Q 学习代理 (DQN)

如果你已安装 C++ 编译环境，可以使用蒙特卡洛加速训练深度强化学习代理：

uv run poker-dqn-train-cpp

提示：训练过程可通过 TensorBoard 观察，运行 tensorboard --logdir=./Graph 即可查看可视化图表。

5. 运行测试

确保所有功能正常：

uv run pytest

(可使用 -n 参数并行运行测试以加快速度)

---

下一步建议： 查看 agents 文件夹中的现有代理实现（如 agent_random.py），复制并修改 action 方法来创建你自己的智能扑克玩家，然后提交 Pull Request 参与协作。