# microdrl

**Repository Path**: Zen07/microdrl

## Basic Information

- **Project Name**: microdrl
- **Description**: 本项目旨在以最直观的方式揭示现代 AI 框架（如 PyTorch）和强化学习环境（如 OpenAI Gym）背后的底层原理。它不依赖任何深度学习库，仅用约 300 行代码就实现了自动微分引擎、物理环境仿真以及神经网络训练。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2025-12-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: zen个人项目

## README

# MicroDRL 

**MicroDRL** (Micro Deep Reinforcement Learning) 是一个基于纯 Python 实现的极简深度强化学习框架。

本项目旨在以最直观的方式揭示现代 AI 框架（如 PyTorch）和强化学习环境（如 OpenAI Gym）背后的底层原理。它不依赖任何深度学习库，仅用约 300 行代码就实现了自动微分引擎、物理环境仿真以及神经网络训练。

（ **特别致谢** ：本项目深受 Andrej Karpathy 的 [micrograd](https://github.com/karpathy/micrograd) 项目启发。MicroDRL 将其扩展到了强化学习领域，增加了对数概率计算 (`log`, `exp`) 和策略梯度逻辑。）

![Result Plot](assets/drl_train_plot.png)
*(运行项目即可生成上述训练曲线)*

## ✨ 核心特性

*   **零依赖 (Zero Dependencies)**: 不需要安装 `torch`, `gym`, `numpy`。核心逻辑仅使用 Python 标准库 (`math`, `random`)。
*   **第一性原理 (First Principles)**: 从零构建计算图（Computational Graph）和反向传播（Backpropagation），让你彻底理解 `loss.backward()` 是如何工作的。
*   **内置物理引擎**: 手写复现了经典的 **CartPole-v1** (倒立摆) 物理动力学模型，无需安装庞大的 Gym 库。
*   **REINFORCE 算法**: 实现了基于策略梯度的强化学习算法，并包含基线减法（Baseline Subtraction）等数值稳定技巧。

## 🛠️ 快速开始

### 1. 克隆项目
```bash
git clone https://gitee.com/Zen07/microdrl.git
cd microdrl
```

### 2. 运行训练
直接运行主脚本。程序将启动训练，你会在终端看到智能体从“一无所知”到“精通平衡”的过程。
```bash
python microdrl.py
```

**训练日志示例:**
```text
Start Training CartPole (Pure Python)...
Episode   0 | Steps:  12 | Loss: 0.8123 | AvgReward: 10.5
...
Episode 200 | Steps:  85 | Loss: -0.4491 | AvgReward: 90.6
...
Episode 480 | Steps: 200 | Loss: -0.7108 | AvgReward: 166.8
Solved! Running Reward is now 166.8!
```
*训练结束后，数据会自动保存到 `training_stats.json` 文件中。*

### 3. 可视化结果
训练完成后，使用配套脚本绘制 Reward 和 Loss 曲线（此步需安装 `matplotlib`）：
```bash
pip install matplotlib
python plot_result.py
```

## 🧠 技术原理

MicroDRL 由三个核心部分组成，全部包含在一个文件中：

### 1. Autograd Engine (自动微分引擎)
模仿 PyTorch 的设计，定义了 `Value` 类。
- 每个 `Value` 对象存储一个标量 (`data`) 和它的梯度 (`grad`)。
- 动态构建 DAG (有向无环图)。
- 实现了 `__add__`, `__mul__`, `tanh`, `exp`, `log` 等算子及其对应的局部导数逻辑。
- 调用 `.backward()` 时，通过拓扑排序（Topological Sort）和链式法则自动计算梯度。

### 2. Neural Network (神经网络)
- 使用 `Value` 对象构建了神经元 (`Neuron`)、层 (`Layer`) 和多层感知机 (`MLP`)。
- 能够处理非线性的策略函数逼近。

### 3. Physics Simulation (物理仿真)
- 严格遵循经典力学公式（牛顿第二定律）复现 CartPole 动力学。
- 使用欧拉积分法（Euler Integration）更新状态：
  ```python
  x = x + tau * x_dot
  theta = theta + tau * theta_dot
  ```

## 📂 项目结构

```text
microdrl/
├── microdrl.py        # 核心代码：包含引擎、环境、模型和训练循环
├── plot_result.py     # 数据可视化脚本
├── requirements.txt   # 依赖说明 (仅 matplotlib)
├── training_stats.json # 运行时生成的训练数据
└── README.md          # 项目说明文档
```

## 🤝 致谢

本项目深受 Andrej Karpathy 的 [micrograd](https://github.com/karpathy/micrograd) 项目启发。MicroDRL 将其扩展到了强化学习领域，增加了对数概率计算 (`log`, `exp`) 和策略梯度逻辑。

## 📄 开源协议

MIT License