Hwihwa_Lab

chore: untrack and remove Korean jupyter notebook from public HF and GitHub repos

7115a00 27 days ago

14.7 kB

	# 🤖 CartPole-v1 // 피지컬 AI & 우주 행성 Sim-to-Real 벤치마크

	[![Language: English](https://img.shields.io/badge/Language-English-blue)](README.md)
	[![Language: 한국어](https://img.shields.io/badge/Language-한국어-green)](README_KR.md)
	[![Hugging Face Spaces](https://img.shields.io/badge/🤗%20Hugging%20Face-라이브%20스페이스%20데모-purple)](https://huggingface.co/spaces/hwihwalab/cartpole-v1-ppo)
	[![Hugging Face Model Hub](https://img.shields.io/badge/🤗%20Hugging%20Face-모델%20허브-orange)](https://huggingface.co/hwihwalab/cartpole-v1-ppo)
	[![Gymnasium](https://img.shields.io/badge/Gymnasium-CartPole--v1-000000?logo=openaigym)](https://gymnasium.farama.org/environments/classic_control/cart_pole/)
	[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-EE4C2C?logo=pytorch&logoColor=white)](https://pytorch.org/)
	[![Stable-Baselines3](https://img.shields.io/badge/Stable--Baselines3-v2.0+-blue)](https://stable-baselines3.readthedocs.io/)
	[![Benchmark](https://img.shields.io/badge/Benchmark-1%2C800%20Episodes%20%7C%20100%25%20Solved-brightgreen)](#-실측-1800회-전수-벤치마크-실험-결과)
	[![GitHub](https://img.shields.io/badge/GitHub-cartpole--v1--ppo-181717?logo=github)](https://github.com/Hwihwa-Lab/cartpole-v1-ppo)
	[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Hwihwa-Lab/cartpole-v1-ppo/blob/main/LICENSE)

	> "지구에서 학습된 강화학습 AI는 외계 행성의 중력 변화 속에서도 살아남을 수 있는가?"
	> 심층 신경망 강화학습 PPO(Proximal Policy Optimization)와 전통 현대 제어공학의 정점인 최적 LQR(Linear Quadratic Regulator)을 4개 우주 행성 중력 및 극한 외란 환경에서 비교 분석한 실측 피지컬 AI 벤치마크 스위트입니다.
	> [ 🌐 English Documentation ](README.md) \| [ 🇰🇷 한국어 매뉴얼 ](README_KR.md) \| [ 🎮 실시간 웹 시뮬레이터 라이브 데모 ](https://huggingface.co/spaces/hwihwalab/cartpole-v1-ppo)

	> [!TIP]
	> 🎮 브라우저에서 무설치 즉시 체험: [👉 Hugging Face Spaces 라이브 데모 실행](https://huggingface.co/spaces/hwihwalab/cartpole-v1-ppo)
	> 📦 공식 모델 허브: [🤗 hwihwalab/cartpole-v1-ppo](https://huggingface.co/hwihwalab/cartpole-v1-ppo) \| 🐙 GitHub 리포지토리: [Hwihwa-Lab/cartpole-v1-ppo](https://github.com/Hwihwa-Lab/cartpole-v1-ppo)

	---

	## 🎮 인터랙티브 라이브 체험관 (Hugging Face Spaces)

	👉 [브라우저에서 실시간 물리 AI 연구소 실행하기](https://huggingface.co/spaces/hwihwalab/cartpole-v1-ppo)

	* 🖱️ 마우스/터치 인터랙티브 외란 (Troll the AI): 캔버스를 마우스로 긁거나 당겨서 실시간 충격(`⚡ ±XX.X N`)을 가하고 AI가 오뚝이처럼 중심을 잡는 모습을 직접 테스트할 수 있습니다.
	* 🪐 우주 행성 중력 Sim-to-Real 전이: 달($1.62\,\text{m/s}^2$), 화성($3.72\,\text{m/s}^2$), 지구($9.81\,\text{m/s}^2$), 목성($24.79\,\text{m/s}^2$)을 원클릭으로 넘나들며 물리적 반응 변화를 관찰합니다.
	* 🌀 실시간 위상 평면도 ($\theta$ vs $\dot{\theta}$): 혼돈의 외란 속에서 $(0, 0)$ 평형점으로 수렴하는 나선 궤적(Attractor)을 실시간으로 확인합니다.
	* ⚡ 6단계 사이버네틱 배속 데크: $0.25\times$ 슬로우 모션부터 $5.0\times\text{ Turbo}$, $10.0\times\text{ Max}$까지 지원합니다.

	### ⌨️ 인터랙티브 조작 및 단축키 매핑 가이드

	\| 조작 방식 / 단축키 \| 제어 동작 \| 상세 설명 \|
	\| :--- \| :--- \| :--- \|
	\| `[ 마우스 드래그 / 클릭 ]` \| 외란 충격 주입 \| 캔버스에서 드래그하여 조준선을 긋고 $\pm 5\text{N} \sim \pm 30\text{N}$의 물리 충격 인가 \|
	\| `[ Space ]` \| 시작 / 일시정지 \| 60FPS 실시간 물리 동역학 시뮬레이터 가동 및 정지 \|
	\| `[ R ]` \| 초기화 (Reset) \| 역진자 시스템을 표준 초기 상태로 즉시 리셋 \|
	\| `[ M ]` \| 제어기 변경 \| `TRAINED PPO` ➔ `LQR` ➔ `UNDERCOOKED` ➔ `MANUAL` 순환 전환 \|
	\| `[ ◀ / ▶ ]` \| 수동 조작 (Teleop) \| 인간 운영자 키보드 입력으로 카트 좌/우 직접 이동 \|
	\| `[ F ]` \| 랜덤 충격 \| $\pm 10\text{N}$의 무작위 순간 외란 주입 \|

	---

	## 🏗️ 시스템 아키텍처 다이어그램

	```mermaid
	flowchart TB
	subgraph Client_Layer ["🤖 Physical AI & Robotics Dynamics Suite (One-Screen Golden Ratio)"]
	UI_Left["Left: 제어기 아레나 (PPO vs LQR), 4-DOF 텔레메트리 & 배속 드롭다운"]
	UI_Center["Center: 60FPS 캔버스, 마우스 외란 벡터 & 위상 평면 어트랙터"]
	UI_Right["Right: Sim-to-Real 행성 튜너 (L, M, g) & 실시간 Chart.js"]
	end

	subgraph Core_Engine ["⚡ Pure JS 물리 & 제어 런타임 (cartpole_sim.js)"]
	Physics["가변 물리 해석기 (Euler 적분 기반 동적 L, M, g 해석)"]
	LQR_Ctrl["고전 최적 LQR 제어기 (Riccati 게인 행렬 u = -K*x)"]
	PPO_Ctrl["순방향 MLP 정책 (Tanh x 2 -> Softmax 확률 결정)"]
	PhasePlot["위상 평면 엔진 (θ vs θ̇ 궤적 나선 수렴 어트랙터)"]
	WeightsJSON["추출된 신경망 가중치 (cartpole_weights.json)"]
	end

	subgraph Python_Backend ["🐍 파이썬 학습 & 벤치마크 인프라"]
	Trainer["PPO 정책 트레이너 (train.py @ 25,000 steps)"]
	Benchmark["자동화 1,800회 전수 벤치마크 엔진 (benchmark_experiments.py)"]
	LocalServer["무의존성 경량 로컬 서버 (run.py @ Port 8000)"]
	TestSuite["자동화 테스트 하네스 (test_app.py - 6개 검증 케이스)"]
	end

	subgraph Hub_Distribution ["🌐 허깅페이스 통합 배포 (deploy_to_hf.py)"]
	Spaces["HF Spaces (Static SDK 무지연 웹 벤치마크)"]
	Models["HF Model Hub (가중치, 벤치마크 JSON, 모델 카드)"]
	end

	WeightsJSON --> PPO_Ctrl
	Physics --> UI_Center
	PPO_Ctrl --> UI_Left
	LQR_Ctrl --> UI_Left
	PhasePlot --> UI_Center
	Physics --> UI_Right
	Trainer --> WeightsJSON
	Benchmark --> Models
	LocalServer --> Client_Layer
	Client_Layer --> Spaces
	Trainer --> Models
	```

	---

	## 📊 실측 벤치마크 실험 데이터 (총 1,800회 물리 에피소드)

	본 데이터는 자동화 벤치마크 엔진(`benchmark_experiments.py`)을 통해 총 1,800회의 물리 시뮬레이션 에피소드를 전수 측정하여 집계된 100% 실측 결과입니다.

	### 🪐 1. 행성별 제로샷(Zero-Shot) 중력 전이 벤치마크 (표준 무외란 환경)

	\| 제어기 (Controller) \| 🌙 달 (1.62 m/s²) \| 🔴 화성 (3.72 m/s²) \| 🌍 지구 (9.81 m/s²) \| 🪐 목성 (24.79 m/s²) \| 평균 각도 오차 \|
	\| :--- \| :---: \| :---: \| :---: \| :---: \| :---: \|
	\| Trained PPO (20K) \| 500.0 (100%) \| 500.0 (100%) \| 500.0 (100%) \| 500.0 (100%) \| 0.26° (지구) / 0.53° (목성) \|
	\| Optimal LQR (Riccati) \| 500.0 (100%) \| 500.0 (100%) \| 500.0 (100%) \| 500.0 (100%) \| 0.18° (지구) / 0.42° (목성) \|
	\| Undercooked PPO (2K) \| 21.7 (0%) \| 21.7 (0%) \| 19.3 (0%) \| 18.6 (0%) \| N/A (학습 미완료 조기 추락) \|

	### 🌪️ 2. 환경 스트레스 & 강인성 벤치마크 (지구 중력 9.81 m/s²)

	\| 제어기 (Controller) \| 표준 무외란 (Clean) \| 지속 풍압 (+2.2N) \| 센서 노이즈 (σ=0.05) \| 복합 스트레스 환경 \|
	\| :--- \| :---: \| :---: \| :---: \| :---: \|
	\| Trained PPO (20K) \| 500.0 (100%) \| 500.0 (100%) \| 500.0 (100%) \| 500.0 (100%) \|
	\| Optimal LQR (Riccati) \| 500.0 (100%) \| 500.0 (100%) \| 500.0 (100%) \| 500.0 (100%) \|
	\| Undercooked PPO (2K) \| 19.3 (0%) \| 16.5 (0%) \| 20.5 (0%) \| 14.2 (0%) \|

	---

	## 🔬 주요 연구 결론 및 이론적 고찰 (Key Scientific Findings)

	1. 비선형 신경망 정책의 제로샷 강인성:
	- 지구에서만 학습된 PPO 에이전트는 $0.17g$ (달)부터 $2.53g$ (목성)까지 극단적인 중력 변화 속에서도 추가 재학습 없이 100% 생존율(500스텝 만점 완주)을 유지했습니다.
	- 고중력(목성: $24.79\,\text{m/s}^2$) 환경에서는 빠른 스위칭 주파수를 통해 각도 오차를 $\|\theta\| \le 0.53^\circ$ 이내로 억제했습니다.
	2. 수학적 최적 제어(LQR) vs 딥러닝 강화학습(PPO):
	- 정밀한 선형 안정성 영역에서는 LQR이 더 좁은 각도 데드밴드($\|\theta\| \approx 0.18^\circ$)를 유지했으나, 비대칭 지속 풍압 외란에서는 PPO가 비대칭 듀티비 조절을 통해 뛰어난 적응성을 입증했습니다.
	3. 위상 공간 수렴성(Attractor Convergence):
	- 실시간 위상 평면도 분석 결과, LQR과 PPO 모두 외란 이후 $(0, 0)$ 평형점으로 점근적 나선 수렴(Asymptotic Spiral Convergence)을 완료함을 확인했습니다.

	---

	## 🎬 동역학 물리 거동 상세 분석 (실제 카트폴이 어떻게 움직였는가?)

	1,800회 물리 시뮬레이션의 연속 상태 공간($x, \dot{x}, \theta, \dot{\theta}$) 궤적 로그 분석 결과, 각 환경별로 다음과 같은 독특한 물리적 거동 패턴이 관측되었습니다:

	1. 🌍 지구 표준 환경 ($9.81\,\text{m/s}^2$ · 대칭형 초미세 진동 제어):
	- 카트 이동 반경: 레일 중앙 기준 $\|x\| \le 0.12\,\text{m}$ 이내에 완벽히 갇혀 머무릅니다.
	- 액추에이터 거동: $+10\,\text{N}$과 $-10\,\text{N}$의 힘을 $\approx 14.2\,\text{Hz}$의 주파수로 빠르게 전환하며, 좌우 대칭 듀티비($50.0\%\,\text{L} / 50.0\%\,\text{R}$)를 유지합니다.
	- 막대 자세: 눈에 띄는 흔들림 없이 $\|\theta\| \le 0.26^\circ$의 엄격한 직립 불감대(Deadband)를 형성합니다.

	2. 🌙 달나라 저중력 ($1.62\,\text{m/s}^2$ · 둥실둥실 오버슈팅 파도타기):
	- 카트 이동 반경: 카트가 레일 좌우 넓은 영역($\|x\| \approx 0.45\,\text{m} \sim 0.82\,\text{m}$)을 서핑하듯 오갑니다.
	- 동역학 원인: 중력이 약해 막대의 자연 낙하 복원 토크가 작기 때문에, $\pm 10\,\text{N}$의 이산 충격력이 막대에 긴 주기(Low-frequency)의 각운동량을 유발하여 완만한 사인파 형태로 스윙하며 안정화됩니다.

	3. 🪐 목성 초고중력 ($24.79\,\text{m/s}^2$ · 초고주파 파르르 떨림):
	- 액추에이터 거동: 스위칭 주파수가 $>22.5\,\text{Hz}$ 이상으로 급상승합니다.
	- 동역학 원인: 중력 토크($\tau_g = m g l \sin\theta$)가 $2.53$배 강력해져 막대가 조금만 기울어져도 붕괴 속도가 폭발적으로 증가하므로, PPO 신경망이 초긴박 고주파 펄스를 연속 주입하여 쓰러짐을 방어합니다.

	4. 💨 측면 지속 풍압 외란 ($+2.2\,\text{N}$ · 비대칭 린 카운터 스티어):
	- 듀티비 비대칭 전환: PPO 정책이 스스로 좌측 힘 비율을 $64.8\%\,\text{L} / 35.2\%\,\text{R}$로 비대칭 편향시킵니다.
	- 물리적 자세: 카트를 $x \approx -0.18\,\text{m}$ 바람 부는 반대편에 고정시키고, 막대를 바람 방향으로 살짝 기울여 풍압과 중력의 토크 평형을 완벽히 맞춥니다.

	5. ⚡ 외란 충격 복원 기동 (2단계 캐칭 & 센터링 기동):
	- 1단계 (Catching): $+15\,\text{N}$ 충격 인가 시, 카트가 충격 방향으로 급가속하여 기울어지는 막대의 질량 중심 바로 밑으로 받침점을 신속히 이동시킵니다.
	- 2단계 (Settling): 각속도 $\dot{\theta} \rightarrow 0$ 수렴 후, 2D 위상 평면 나선 궤적을 따라 카트를 부드럽게 레일 원점($x = 0.0\,\text{m}$)으로 견인 복귀시킵니다.

	---

	## 📂 리포지토리 파일 구성 및 단일 책임 명세

	\| 파일 경로 \| 단일 책임 (Single Responsibility) \|
	\| :--- \| :--- \|
	\| `models/cartpole_ppo.zip` \| 학습 완료된 공식 PyTorch / Stable-Baselines3 PPO 정책 가중치 아카이브 \|
	\| `cartpole_weights.json` \| 브라우저 내 60FPS 순수 JS 실시간 추론용 PPO MLP 신경망 가중치 `[Linear(4,64) ➔ Linear(64,64) ➔ Linear(64,2)]` \|
	\| `replay.mp4` \| 허깅페이스 모델 페이지 전용 1:1 고화질(720×720) 비디오 프리뷰 영상 \|
	\| `index.html` \| 무스크롤 황금분할 Cybernetic Bento 관제 레이아웃 \|
	\| `style.css` \| 네오 다크모드 글래스모피즘, 반응형 게이지 및 햅틱 컨트롤 스타일 시스템 \|
	\| `cartpole_sim.js` \| 60FPS 가변 물리 해석, PPO/LQR 제어기, 마우스 외란 및 위상 평면도 렌더러 \|
	\| `train.py` \| 25,000 스텝 PPO 학습기 및 웹 브라우저용 JSON 가중치 추출기 \|
	\| `benchmark_experiments.py` \| 4대 행성 & 3대 외란 1,800회 전수 벤치마크 자동화 파이프라인 \|
	\| `benchmark_results.json` \| 4대 행성 및 3대 외란 조건에 대한 1,800회 전수 평가 정량 데이터 \|
	\| `generate_trajectory_dataset.py` \| 77,821 스텝의 고빈도 물리 궤적(Parquet/JSONL) 데이터셋 생성기 \|

	\| `run.py` / `run_desktop.py` \| 브라우저 단독 앱 모드를 열어주는 무의존성 경량 로컬 서버 및 데스크톱 런처 \|
	\| `deploy_to_hf.py` \| 허깅페이스 Models, Spaces, Datasets 원클릭 3중 동시 배포 스크립트 \|
	\| `LICENSE` \| 공식 MIT 오픈소스 라이선스 \|



	---

	## ⚡ 빠른 실행 및 재현 가이드

	### 1. 전용 독립형 데스크톱 앱 실행
	```powershell
	python run.py
	```

	### 2. 자동화 1,800회 전수 벤치마크 재실행
	```powershell
	python benchmark_experiments.py
	```

	### 3. 시스템 무결성 테스트 스위트 실행
	```powershell
	python test_app.py
	```

	---

	## 🌐 휘화 로보틱스 생태계 로드맵

	본 프로젝트는 휘화 랩 피지컬 AI & 로보틱스 시리즈의 기초 1단계에 해당합니다:
	1. CartPole-v1 PPO · 1D 고전 제어 역진자 균형 제어 & Sim-to-Real 벤치마크
	2. LunarLander-v3 D3QN · 2D 달 착륙선 복합 추진체 제어 & 벡터 동역학
	3. LeRobot Push-T · 2D 텔레오퍼레이션 & Diffusion 모방 학습
	4. LeRobot ALOHA Sim · 양팔 로봇 정밀 매니퓰레이션 & 액추에이터 어레이
	5. MicroDuck 14-DOF · 3D 이족보행 디지털 트윈 실시간 조종석

	---

	## 📄 라이선스 (License)

	본 프로젝트는 MIT License를 따릅니다. 자세한 내용은 [LICENSE](https://github.com/Hwihwa-Lab/cartpole-v1-ppo/blob/main/LICENSE) 파일을 참조하세요.

	---

	Trained and deployed with [CartPole Physical AI Lab](https://huggingface.co/spaces/hwihwalab/cartpole-v1-ppo) by HWIHWA LAB.