ns3-gym

OpenAI Gym 是一个广泛用于研究的强化学习（RL）工具包。网络模拟器 ns-3 是网络协议和通信技术领域的学术界与工业界研究的事实标准。ns3-gym 是一个集成了 OpenAI Gym 和 ns-3 的框架，旨在鼓励在网络研究中应用强化学习。

Installation

我们建议使用 Linux（例如 Ubuntu 22 或更高版本）。

1. 安装 ns-3 所需的所有依赖项。

# minimal requirements for C++:
apt-get install gcc g++ python3 python3-pip cmake

查看 ns-3 requirements

2. 安装 ZMQ、协议缓冲区（Protocol Buffers）和 pkg-config 库：

sudo apt-get update
apt-get install libzmq5 libzmq3-dev
apt-get install libprotobuf-dev
apt-get install protobuf-compiler
apt-get install pkg-config

3. 下载并安装 ns3

wget https://www.nsnam.org/releases/ns-allinone-3.40.tar.bz2
tar xf ns-allinone-3.40.tar.bz2
cd ns-allinone-3.40

4. 将 ns3-gym 仓库克隆到 contrib 目录并切换分支：

cd ./ns-3.40/contrib
git clone https://github.com/tkn-tub/ns3-gym.git ./opengym
cd opengym/
git checkout app-ns-3.36+

查看 working with cmake

重要的是使用 opengym 作为 ns3-gym 应用目录的名称。

5. 配置并构建 ns-3 项目：

cd ../../
./ns3 configure --enable-examples
./ns3 build

注意：Opengym 协议缓冲区（Protocol Buffer）消息（C++ 和 Python）是在配置期间构建的。

6. 安装位于 model/ns3gym 的 ns3gym（需要 Python3）

cd ./contrib/opengym/

pip3 install --user ./model/ns3gym

或者

python3 -m venv ns3gym-venv
source ./ns3gym-venv/bin/activate
pip3 install ./model/ns3gym

7. （可选）安装代理所需的所有库（如 tensorflow, keras 等）。

8. 运行示例：

cd ./contrib/opengym/examples/opengym/ 
./simple_test.py

9. （可选）在两个终端中分别启动 ns-3 模拟脚本和 Gym 代理（用于调试）：

# Terminal 1
./ns3 run "opengym"

# Terminal 2
cd ./contrib/opengym/examples/opengym/ 
./test.py --start=0

Examples

所有示例均可在 此处 找到。

Basic Interface

1. 示例 Python 脚本。注意，gym.make('ns3-v0') 会启动位于当前工作目录中的 ns-3 模拟脚本。

import gym
import ns3gym
import MyAgent
from ns3gym import ns3env

#env = gym.make('ns3-v0')  <--- causes some errors with the new OpenAI Gym framework, please use ns3env.Ns3Env()
env = ns3env.Ns3Env()
obs = env.reset()
agent = MyAgent.Agent()

while True:
  action = agent.get_action(obs)
  obs, reward, done, info = env.step(action)

  if done:
    break
env.close()

2. 任何 ns-3 模拟脚本都可以用作 Gym 环境。这只需要实例化 OpenGymInterface 并实现由以下函数组成的 ns3-gym C++ 接口：

Ptr<OpenGymSpace> GetObservationSpace();
Ptr<OpenGymSpace> GetActionSpace();
Ptr<OpenGymDataContainer> GetObservation();
float GetReward();
bool GetGameOver();
std::string GetExtraInfo();
bool ExecuteActions(Ptr<OpenGymDataContainer> action);

注意，通用的 ns3-gym 接口允许观察模拟中的任何变量或参数。

更详细的描述可在我们的 论文 中找到。

Cognitive Radio

我们考虑无线多信道环境（例如带有外部干扰的 802.11 网络）中的无线信道选择问题。代理的目标是为下一个时隙选择一个无干扰的信道。我们考虑一个简单的说明性示例，其中外部干扰遵循周期性模式，即按照表中所示的顺序遍历所有一到四号信道。

我们使用 ns-3 中的现有功能创建了此场景，即使用 WaveformGenerator 类创建干扰，并使用 SpectrumAnalyzer 类进行感知。

这种周期性干扰器可以被 RL 代理轻松学习，以便基于给定时间槽内每个信道的占用情况的当前观测，确定下一个时间槽的正确信道，从而避免与干扰器发生任何碰撞。

我们提出的 RL 映射如下：

• observation - 当前时隙中每个信道的占用情况，即宽带感知，
• actions - 设置下一个时隙要使用的信道，
• reward - 如果没有与干扰器发生碰撞则为 +1；否则为 -1，
• gameover - 如果过去十个时隙内发生了超过三次碰撞

下图显示了使用具有全连接输入和输出层的简单神经网络时的学习性能。 我们看到，在大约 80 个回合后，代理能够根据当前观测完美预测下一个信道状态，从而避免与干扰发生任何碰撞。

该示例的完整源代码可在 此处 找到。

注意，在更现实的场景中，本例中的简单波形生成器可以替换为真实的无线技术，如 LTE 非授权频段（LTE-U）。

RL-TCP

适当的 RL-TCP 代理示例仍在开发中。然而，我们已经实现并发布了两个版本（即时基和事件基）的接口，允许监控 TCP 实例的参数并控制其 拥塞窗口 和 慢启动阈值 -- 详见 此处。注意，这两个版本都继承自 TcpCongestionOps，因此可以作为 ns3::TcpL4Protocol::SocketType 的参数使用。

此外，使用事件基接口，我们已经有示例 Python Gym 代理实现了 TCP NewReno，并使用 ns3gym 与 ns-3 模拟进程通信 -- 见 此处。该示例可作为实现基于 RL 的 TCP 拥塞控制算法的起点。

为了运行它，请执行：

cd ./contrib/opengym/examples/rl-tcp/
./test_tcp.py

或在两个终端中：

# Terminal 1:
./ns3 run "rl-tcp --transport_prot=TcpRl"

# 终端 2：
cd ./contrib/opengym/examples/rl-tcp/
./test_tcp.py --start=0

请注意，我们的 Python TCP NewReno（一种 TCP 拥塞控制算法）实现所传输的数据包数量与在 ns3（网络仿真工具）中实现的版本相同（参见 ns-3 仿真输出，即两种情况下均为 RxPkts: 5367）。请执行以下命令进行交叉验证：

./ns3 run "rl-tcp --transport_prot=TcpNewReno"

联系方式

• Piotr Gawlowicz, TU-Berlin, gawlowicz@tkn
• Anatolij Zubow, TU-Berlin, zubow@tkn
• tkn = tkn.tu-berlin.de

如何引用 ns3-gym？

请使用以下 bibtex（参考文献引用格式）：

@inproceedings{ns3gym,
  Title = {{ns-3 meets OpenAI Gym: The Playground for Machine Learning in Networking Research}},
  Author = {Gaw{\l}owicz, Piotr and Zubow, Anatolij},
  Booktitle = {{ACM International Conference on Modeling, Analysis and Simulation of Wireless and Mobile Systems (MSWiM)}},
  Year = {2019},
  Location = {Miami Beach, USA},
  Month = {November},
  Url = {http://www.tkn.tu-berlin.de/fileadmin/fg112/Papers/2019/gawlowicz19_mswim.pdf
}

ns3-gym 快速上手指南

ns3-gym 是一个将 OpenAI Gym 与 ns-3 网络模拟器集成的框架，旨在促进强化学习（RL）在网络协议和通信技术研究中应用。

环境准备

• 操作系统: 推荐使用 Linux (例如 Ubuntu 22 或更高版本)。
• 基础依赖: 确保已安装 C++ 编译工具链及 Python 环境。

apt-get install gcc g++ python3 python3-pip cmake

• 第三方库: 安装 ZeroMQ、Protocol Buffers 和 pkg-config。

sudo apt-get update
apt-get install libzmq5 libzmq3-dev
apt-get install libprotobuf-dev
apt-get install protobuf-compiler
apt-get install pkg-config

安装步骤

1. 下载并解压 ns-3

   wget https://www.nsnam.org/releases/ns-allinone-3.40.tar.bz2
   tar xf ns-allinone-3.40.tar.bz2
   cd ns-allinone-3.40
   

2. 克隆 ns3-gym 插件 必须将仓库克隆到 contrib 目录下，且目录名需为 opengym。同时切换到指定分支。

   cd ./ns-3.40/contrib
   git clone https://github.com/tkn-tub/ns3-gym.git ./opengym
   cd opengym/
   git checkout app-ns-3.36+
   

3. 配置并构建 ns-3 此步骤会生成 Opengym Protocol Buffer 消息文件。

   cd ../../
   ./ns3 configure --enable-examples
   ./ns3 build
   

4. 安装 Python 模块 进入 model/ns3gym 目录进行安装。

   cd ./contrib/opengym/
   pip3 install --user ./model/ns3gym
   

   (可选) 如需使用虚拟环境：

   python3 -m venv ns3gym-venv
   source ./ns3gym-venv/bin/activate
   pip3 install ./model/ns3gym
   

5. 安装强化学习库 (可选) 根据代理需求安装如 tensorflow、keras 等库。

基本使用

编写 Agent 脚本

核心逻辑是实例化 Ns3Env，通过 step 动作与环境交互。注意不要直接使用 gym.make('ns3-v0')，建议使用 ns3env.Ns3Env()。

import gym
import ns3gym
import MyAgent
from ns3gym import ns3env

# 初始化环境
env = ns3env.Ns3Env()
obs = env.reset()
agent = MyAgent.Agent()

while True:
  action = agent.get_action(obs)
  obs, reward, done, info = env.step(action)

  if done:
    break
env.close()

运行示例

安装完成后，可运行官方提供的简单测试脚本验证环境是否正常工作。

cd ./contrib/opengym/examples/opengym/ 
./simple_test.py

(调试建议) 若需单独启动 ns-3 模拟器和 Gym 代理以便调试，可在两个终端分别执行：

# Terminal 1
./ns3 run "opengym"

# Terminal 2
cd ./contrib/opengym/examples/opengym/ 
./test.py --start=0