---
language:
- en
- ko
tags:
- reinforcement-learning
- stable-baselines3
- ppo
- continuous-control
- mujoco
- humanoid-v5
- robotics
- robot
- bipedal-robot
- neuromotion
pipeline_tag: reinforcement-learning
library_name: stable-baselines3
license: mit
---

# 🤖 NeuroMotion // Humanoid-v5 PPO Continuous Control

[![Language: English](https://img.shields.io/badge/Language-English-blue)](https://huggingface.co/hwihwalab/neuromotion-humanoid-v5-ppo/blob/main/README.md)
[![Language: 한국어](https://img.shields.io/badge/Language-한국어-green)](https://huggingface.co/hwihwalab/neuromotion-humanoid-v5-ppo/blob/main/README_KR.md)
[![Hugging Face Model Hub](https://img.shields.io/badge/🤗%20Hugging%20Face-Model%20Hub-orange)](https://huggingface.co/hwihwalab/neuromotion-humanoid-v5-ppo)
[![GitHub Repository](https://img.shields.io/badge/GitHub-Repository-181717?style=flat&logo=github)](https://github.com/Hwihwa-Lab/neuromotion-humanoid-v5-ppo)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Hwihwa-Lab/neuromotion-humanoid-v5-ppo/blob/main/LICENSE)
[![Gymnasium](https://img.shields.io/badge/Gymnasium-MuJoCo%20Humanoid--v5-0080FF)](https://gymnasium.farama.org/environments/mujoco/humanoid/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-EE4C2C?style=flat&logo=pytorch)](https://pytorch.org)
[![Stable-Baselines3](https://img.shields.io/badge/Stable--Baselines3-PPO-brightgreen)](https://stable-baselines3.readthedocs.io)

> **MuJoCo Humanoid-v5 Continuous Control Telemetry & PPO Reinforcement Learning System**  
> *[ 🌐 English Documentation ](https://huggingface.co/hwihwalab/neuromotion-humanoid-v5-ppo/blob/main/README.md) | [ 🇰🇷 한국어 매뉴얼 ](https://huggingface.co/hwihwalab/neuromotion-humanoid-v5-ppo/blob/main/README_KR.md)*

This repository contains an advanced continuous reinforcement learning system (PPO) and a real-time engineering telemetry dashboard for bipedal robotic continuous control in [Gymnasium](https://gymnasium.farama.org/environments/mujoco/humanoid/) MuJoCo `Humanoid-v5`.

---

## 📊 Model Specifications & Benchmark Results

| Parameter | Specification |
| :--- | :--- |
| **Environment** | Gymnasium MuJoCo `Humanoid-v5` |
| **Observation Space** | 378-dimensional continuous vector |
| **Action Space** | 17-dimensional continuous joint torques (Box[-1.0, 1.0]) |
| **Algorithm** | Proximal Policy Optimization (PPO) |
| **Framework** | Stable-Baselines3 / PyTorch |
| **Architecture** | Actor-Critic MLP Policy (MlpPolicy) |
| **Average Survival Steps** | **`88.5 steps`** *(Peak: `109 steps`)* |
| **Average Cumulative Reward** | **`+455.52`** *(Peak: `+549.18`)* |

---

## 🚀 Quick Start (Inference & Evaluation)

### 1. Download & Load with Stable-Baselines3

```python
import gymnasium as gym
from stable_baselines3 import PPO
from huggingface_hub import hf_hub_download

# Download model weights from Hugging Face Hub
model_file = hf_hub_download(
    repo_id="hwihwalab/neuromotion-humanoid-v5-ppo",
    filename="humanoid_ppo_model.zip"
)

# Initialize MuJoCo Humanoid-v5 environment
env = gym.make("Humanoid-v5", render_mode="human")
model = PPO.load(model_file, env=env)

# Run evaluation episodes
obs, info = env.reset()
for _ in range(1000):
    action, _states = model.predict(obs, deterministic=True)
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        obs, info = env.reset()

env.close()
```

---

## 🖥️ Real-time Telemetry Dashboard (NeuroMotion Studio)

The repository also includes a native 60fps Pygame telemetry cockpit:

```powershell
python run_gui.py
```

### Features:
* **7-Panel Telemetry Layout**: 17-DOF Actuator Torque Bars, Learning Diagnostics (Policy/Value Loss, Entropy), Reward Telemetry Curves, Top Bento KPI Cards.
* **Interactive Controls**: Real-time Physics Speed Multipliers (1x, 2x, 4x, 8x), Disturbance Force Injection (15N, 30N, 50N), Checkpoint Save/Load.

---

## 📂 Repository Contents

* `README.md`: Hugging Face model card, specifications, and telemetry manual.
* `README_KR.md`: Dedicated Korean manual ([한국어 매뉴얼](https://github.com/Hwihwa-Lab/neuromotion-humanoid-v5-ppo/blob/main/README_KR.md)).
* `humanoid_ppo_model.zip`: Pre-trained PPO neural network weights.
* `simulation_engine.py`: Gymnasium MuJoCo physical engine & 17-DOF torque extractor.
* `train_rl.py`: Stable-Baselines3 PPO incremental trainer & diagnostics.
* `run_gui.py`: Pygame real-time telemetry cockpit.
* `mujoko_humanoid.py`: Multi-mode CLI execution and visualization script.

---

## 📄 License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/Hwihwa-Lab/neuromotion-humanoid-v5-ppo/blob/main/LICENSE) file for details.

---

*Trained and deployed with [NeuroMotion Studio](https://huggingface.co/hwihwalab/neuromotion-humanoid-v5-ppo) by **hwihwalab**.*