gym与gymnasium简介

gym

• gym（OpenAI Gym）和gymnasium是两个不同的Python库，它们都旨在为强化学习研究提供环境和工具

• gym出现的原因：不同于监督学习那样需要的是数据集，强化学习需要的是运行任务所需的环境，研究人员需要拥有标准化的环境和模块化的强化学习代码，方便复用以及方便研究人员能够在相同的环境和条件下测试算法

• gym通过提供一个统一的接口，

• gym（OpenAI Gym）是由OpenAI团队开发的，是最早和最广泛使用的强化学习环境库之一

• 用于开发和比较强化学习算法的工具包和测试平台，提供了一个统一的接口来控制和交互各种环境

• 截止2023年，Gym 已经不再更新或维护，最新版本为v0.26.2
  

• Gym的最新版本为v0.26.2，并且从这个版本开始，Gym的维护工作由Farama Foundation接手，并推出了Gymnasium

• gym官网
  

gymnasium

• 所有Gym的开发工作已经转移到Gymnasium
• gymnasium是一个较新的库，它试图解决gym中的一些限制和问题，并提供更现代化的接口
• gymnasium设计时考虑了与gym的兼容性。它提供了一个兼容层，使得大多数gym环境可以直接在gymnasium中使用，无需或只需很少的修改
• gymnasium官网
  

gymnasium的基本使用方法

暂时先略过，日后补上，先介绍gymnasium封装自定义环境

---

使用gymnasium封装自定义环境

• gymnasium官方介绍封装自定义环境的文档，本文主要基于此文档
• 官方提供了示例代码，链接在此
• 安装gymnasium命令：

pip install gymnasium

官方示例及代码

• 官方使用的示例代码结构，如下所示
  
• wrappers是指包装器，用于修改或增强现有环境的行为，而不需要直接修改环境的源代码
• 使用 wrappers 的一个关键优势是它们提供了一种灵活的方式来修改和扩展环境的功能，而不需要改变环境本身的实现。这使得研究人员可以专注于算法的开发，同时利用 wrappers 来适应不同的实验条件和研究目标。
• env文件夹下的文件是环境名字

• 在命令行中可使用tree 命令查看目录及文件结构，windows下需要使用/F参数来显示文件

tree /F C:\path\to\directory

编写环境文件

• 所有自定义环境必须继承抽象类gymnasium.Env
• 同时需要定义metadata，在 Gym 环境中，metadata 字典包含了环境的元数据，这些数据提供了关于环境行为和特性的额外信息

“render_modes”: 这个键的值是一个列表，指明了环境支持的渲染模式。在这个例子中，环境支持两种渲染模式：
“human”: 这种模式通常是指在屏幕上以图形界面的形式渲染环境，适合人类观察者观看。
“rgb_array”: 这种模式下，环境的渲染结果会以 RGB 数组的形式返回，这可以用于机器学习算法的输入，或者进行进一步的处理和分析。
“render_fps”: 这个键表示环境渲染的帧率，即每秒钟可以渲染的帧数。在这个例子中，4 表示环境将以每秒 4 帧的速率进行渲染。这通常用于控制渲染速度，使动画的播放更加平滑或符合特定的显示需

• 在环境文件中需要实现__init__(),reset().setp(),render(),close()等方法，确保环境能够按照强化学习的标准工作流程运行
• 定义action_space，智能体可以执行的动作类型和范围；定义observation_space，智能体可以观察到的状态的类型和范围
• from gymnasium import spaces
• 连续的空间使用spaces.Box 定义，low 和 high 参数指定了取值范围。
• 离散的空间使用spaces.Discrete，参数指定可能的数量

init()方法

• 初始化方法，用于设置环境的初始状态。这里可以定义环境参数、初始化状态空间和动作空间等
• 定义 action_space 和 observation_space时，需要从 Gymnasium 的 spaces 模块导入spaces
• spaces 模块提供了多种空间类型，用于表示强化学习环境中可能的动作和观察的类型和结构
  

import numpy as np
import pygame

import gymnasium as gym
from gymnasium import spaces


class GridWorldEnv(gym.Env):
    metadata = {"render_modes": ["human", "rgb_array"], "render_fps": 4}

    def __init__(self, render_mode=None, size=5):
        self.size = size  # The size of the square grid
        self.window_size = 512  # The size of the PyGame window

        # Observations are dictionaries with the agent's and the target's location.
        # Each location is encoded as an element of {0, ..., `size`}^2, i.e. MultiDiscrete([size, size]).
        self.observation_space = spaces.Dict(
            {
                "agent": spaces.Box(0, size - 1, shape=(2,), dtype=int),
                "target": spaces.Box(0, size - 1, shape=(2,), dtype=int),
            }
        )

        # We have 4 actions, corresponding to "right", "up", "left", "down"
        self.action_space = spaces.Discrete(4)

        """
        The following dictionary maps abstract actions from `self.action_space` to
        the direction we will walk in if that action is taken.
        I.e. 0 corresponds to "right", 1 to "up" etc.
        """
        self._action_to_direction = {
            0: np.array([1, 0]),
            1: np.array([0, 1]),
            2: np.array([-1, 0]),
            3: np.array([0, -1]),
        }

        assert render_mode is None or render_mode in self.metadata["render_modes"]
        self.render_mode = render_mode

        """
        If human-rendering is used, `self.window` will be a reference
        to the window that we draw to. `self.clock` will be a clock that is used
        to ensure that the environment is rendered at the correct framerate in
        human-mode. They will remain `None` until human-mode is used for the
        first time.
        """
        self.window = None
        self.clock = None

reset()方法

• 用于重置环境状态，在每个训练周期（episode）开始时，reset() 方法被调用以重置环境到一个初始状态
• 每次训练周期结束并且接收到结束信号（done 标志）时，会调用 reset 方法来重置环境状态
• 用户可以通过 reset 方法传递一个 seed 参数，用于初始化环境使用的任何随机数生成器，确保环境行为的确定性和可复现性

def reset(self, seed=None, options=None):
    # We need the following line to seed self.np_random
    super().reset(seed=seed)

    # Choose the agent's location uniformly at random
    self._agent_location = self.np_random.integers(0, self.size, size=2, dtype=int)

    # We will sample the target's location randomly until it does not coincide with the agent's location
    self._target_location = self._agent_location
    while np.array_equal(self._target_location, self._agent_location):
        self._target_location = self.np_random.integers(
            0, self.size, size=2, dtype=int
        )

    observation = self._get_obs()
    info = self._get_info()

    if self.render_mode == "human":
        self._render_frame()

    return observation, info

step()方法

• step()方法是环境与智能体交互的核心，包含了环境逻辑的核心部分
• step()方法处理动作，更新环境状态，并返回五个值组成的元组(observation, reward, terminated, truncated, info)：观察（observation）、奖励（reward）、是否终止（terminated）、是否截断（truncated）和附加信息（info）

五元组的含义(observation, reward, terminated, truncated, info)

观察（Observation）：这是环境状态的表示，智能体根据这个观察来选择动作。观察可以是状态的一部分或全部，也可以是经过加工的信息，如图像、向量等。观察是智能体与环境交互的直接输入。
奖励（Reward）：这是一个标量值，表示智能体执行动作后从环境中获得的即时反馈。奖励用于指导智能体学习哪些行为是好的，哪些是不好的。在许多任务中，智能体的目标是最大化其获得的总奖励。
是否终止（Terminated/Done）：这是一个布尔值，表示当前周期（episode）是否结束。如果为 True，则表示智能体已经完成了任务，或者环境已经达到了一个终止状态，智能体需要重新开始新的周期。
是否截断（Truncated）：这也是一个布尔值，与 done 相似，但表示周期结束的原因可能不是任务完成，而是其他原因，如超时、达到某个特定的中间状态或违反了某些规则。在某些实现中，truncated 可能与 done 相同或不被使用。
附加信息（Info）：这是一个字典，包含除观察、奖励、终止和截断之外的额外信息。这些信息可以包括关于状态转换的元数据，如是否处于探索阶段、环境的内部计数器、额外的性能评估指标等。

def step(self, action):
    # Map the action (element of {0,1,2,3}) to the direction we walk in
    direction = self._action_to_direction[action]
    # We use `np.clip` to make sure we don't leave the grid
    self._agent_location = np.clip(
        self._agent_location + direction, 0, self.size - 1
    )
    # An episode is done iff the agent has reached the target
    terminated = np.array_equal(self._agent_location, self._target_location)
    reward = 1 if terminated else 0  # Binary sparse rewards
    observation = self._get_obs()
    info = self._get_info()

    if self.render_mode == "human":
        self._render_frame()

    return observation, reward, terminated, False, info

• info可通过_get_info方法获取，该方法用于收集和返回除了观察和奖励之外的其他有用信息。这些信息可以包括关于环境状态的额外数据
• _get_obs方法负责将环境的内部状态转换为智能体可以观察的形式，通常涉及到从环境状态中提取相关信息，并将其格式化为智能体能够理解和使用的数据结构

def _get_obs(self):
    return {"agent": self._agent_location, "target": self._target_location}

def _get_info(self):
    return {
        "distance": np.linalg.norm(
            self._agent_location - self._target_location, ord=1
        )
    }

render()方法

• render 方法用于将环境的状态可视化
• 使用 Gymnasium 创建自定义环境时，PyGame 是一种流行的库，用于渲染环境的视觉表示。PyGame 允许创建图形窗口，并将环境的状态绘制到屏幕上，这对于需要视觉反馈的强化学习任务非常有用

渲染模式：

• “human”：以图形界面的形式渲染，适用于人类观察者。
• “rgb_array”：返回一个 RGB 图像数组，可以用于机器学习模型或进一步处理。
• 下面为示例代码中的render方法

def render(self):
    if self.render_mode == "rgb_array":
        return self._render_frame()

def _render_frame(self):
    if self.window is None and self.render_mode == "human":
        pygame.init()
        pygame.display.init()
        self.window = pygame.display.set_mode(
            (self.window_size, self.window_size)
        )
    if self.clock is None and self.render_mode == "human":
        self.clock = pygame.time.Clock()

    canvas = pygame.Surface((self.window_size, self.window_size))
    canvas.fill((255, 255, 255))
    pix_square_size = (
        self.window_size / self.size
    )  # The size of a single grid square in pixels

    # First we draw the target
    pygame.draw.rect(
        canvas,
        (255, 0, 0),
        pygame.Rect(
            pix_square_size * self._target_location,
            (pix_square_size, pix_square_size),
        ),
    )
    # Now we draw the agent
    pygame.draw.circle(
        canvas,
        (0, 0, 255),
        (self._agent_location + 0.5) * pix_square_size,
        pix_square_size / 3,
    )

    # Finally, add some gridlines
    for x in range(self.size + 1):
        pygame.draw.line(
            canvas,
            0,
            (0, pix_square_size * x),
            (self.window_size, pix_square_size * x),
            width=3,
        )
        pygame.draw.line(
            canvas,
            0,
            (pix_square_size * x, 0),
            (pix_square_size * x, self.window_size),
            width=3,
        )

    if self.render_mode == "human":
        # The following line copies our drawings from `canvas` to the visible window
        self.window.blit(canvas, canvas.get_rect())
        pygame.event.pump()
        pygame.display.update()

        # We need to ensure that human-rendering occurs at the predefined framerate.
        # The following line will automatically add a delay to keep the framerate stable.
        self.clock.tick(self.metadata["render_fps"])
    else:  # rgb_array
        return np.transpose(
            np.array(pygame.surfarray.pixels3d(canvas)), axes=(1, 0, 2)
        )

close()方法

• close 方法用于在环境不再使用时进行清理操作，例如关闭图形界面窗口、释放资源或执行其他必要的清理任务
• 是一个没有参数也没有返回值的方法
• 如果环境使用 PyGame 或其他图形库创建了渲染窗口，close 方法应该关闭这些窗口。

def close(self):
    if self.window is not None:
        pygame.display.quit()
        pygame.quit()

注册环境

• 编写完上述与环境相关的代码后，需要注册自定义环境
• 注册自定义环境是为了使gymnasium检测到该环境

from gymnasium.envs.registration import register

register(
     id="gym_examples/GridWorld-v0",
     entry_point="gym_examples.envs:GridWorldEnv",
     max_episode_steps=300,
)

• environment ID由三部分组成，①命名空间gym_examples（可选） ②强制名称GridWorld ③版本v0（可选）
• entry_point参数在注册自定义环境时使用，它指定了如何导入这个环境类
• 格式通常是module:classname
• module 是包含环境类的 Python 模块的路径。
  classname 是环境中具体的类的名称
• 其他可指定的参数如下所示：

• 经过注册的自定义环境GridWorldEnv可由以下命令创建

env = gymnasium.make('gym_examples/GridWorld-v0')

• gym-examples/gym_examples/envs/init.py 文件中需要包含以下的内容

from gym_examples.envs.grid_world import GridWorldEnv

创建包 Package（最后一步）

• 将代码构建为python的包，方便地在不同项目中重用自定义的环境代码
• 在gym-examples/setup.py中写入以下内容

from setuptools import setup

setup(
    name="gym_examples",
    version="0.0.1",
    install_requires=["gymnasium==0.26.0", "pygame==2.1.0"],
)

此处可以将"==“改为”>=",如果不打算做图形化可以删去pygame==2.1.0

安装自定义环境（在包含 setup.py 的目录中执行）

pip install -e .

• 安装成功后会生成gym_examples.egg-info文件夹

创建自定义环境示例

• 使用以下命令

import gym_examples
env = gymnasium.make('gym_examples/GridWorld-v0')

• 传参的版本

import gym_examples
env = gymnasium.make('gym_examples/GridWorld-v0', size=10)

参考文献

1. Gymnasium Documentation:Make your own custom environment
2. 深度强化学习：gymnasium下创建自己的环境（保姆式教程）