Quadruped RL Experiments

MuJoCo/MJX에서 4족 보행 강화학습을 실험한 코드를 한곳에 모은 저장소입니다. 과거에 알고리즘과 구현 언어별로 나뉘어 있던 quad_rl, walk_rl, rl_ars, rl_ppo의 실행 코드를 정리했습니다.

이 저장소는 하나의 완성형 프레임워크보다, 같은 로봇 모델을 여러 강화학습 스택으로 비교한 연구 기록에 가깝습니다.

무엇부터 보면 되나요?

경로	구현	알고리즘	용도
experiments/mjx-ars	Python, JAX, MJX	ARS	가장 작은 병렬 학습 예제
experiments/mujoco-rllib-ppo	Python, Ray RLlib	PPO	PPO 학습·평가·튜닝 실험
experiments/cpp-ars-ppo	C++17, LibTorch, MuJoCo	ARS/PPO	YAML 설정과 gait reference를 포함한 C++ 실험
experiments/cpp-ppo-libtorch	C++17, LibTorch, MuJoCo	PPO	체크포인트·rollout 재개를 포함한 초기 C++ 구현

처음 실행한다면 mjx-ars로 환경을 확인한 뒤 mujoco-rllib-ppo 또는 C++ 구현으로 넘어가는 순서를 권장합니다.

저장소 구조

quadruped-rl/
├── experiments/
│   ├── mjx-ars/              # JAX/MJX ARS
│   ├── mujoco-rllib-ppo/     # Ray RLlib PPO
│   ├── cpp-ars-ppo/          # C++ ARS/PPO + gait reference
│   └── cpp-ppo-libtorch/     # C++ PPO + rollout/checkpoint 관리
├── .gitignore
└── README.md

각 실험 폴더는 자체 모델 파일과 실행 안내를 포함합니다. 서로 다른 의존성 때문에 루트에서 한 번에 설치하거나 빌드하지 않습니다.

빠른 시작

MJX + ARS

cd experiments/mjx-ars
python -m venv .venv
source .venv/bin/activate
pip install numpy jax mujoco
python mjx_ars_train.py --help

MuJoCo + RLlib PPO

cd experiments/mujoco-rllib-ppo
python -m venv .venv
source .venv/bin/activate
pip install "ray[rllib]" gymnasium[mujoco] torch
python train_ppo.py --help

C++ 실험

두 C++ 폴더 모두 CMake, MuJoCo, LibTorch가 필요합니다. LibTorch 위치는 CMAKE_PREFIX_PATH 또는 LIBTORCH_HOME으로 지정합니다.

cd experiments/cpp-ars-ppo
cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/libtorch
cmake --build build -j
./build/train_mjppo config.yaml

데이터와 실험 산출물

Git에는 재현에 필요한 코드·설정·로봇 모델과 작은 예제만 보관합니다. 다음 항목은 새 커밋에 넣지 않습니다.

• build/, install/, 컴파일 캐시
• runs/, Ray 결과, TensorBoard/W&B 로그
• 대형 checkpoint, rollout, 영상

대형 학습 결과는 W&B artifact, GitHub Release, DVC 같은 별도 저장소에 두고 README나 실험 노트에서 링크하는 편이 좋습니다. 과거 대용량 rollout은 원본 저장소를 archive해 보존했습니다.

이전 저장소 대응표

이전 저장소	새 위치
quad_rl	experiments/cpp-ppo-libtorch
walk_rl	experiments/cpp-ars-ppo
rl_ars	experiments/mjx-ars
rl_ppo	experiments/mujoco-rllib-ppo

통합본은 각 저장소의 현재 실행 코드를 기준으로 만든 정리된 snapshot입니다. 이전 commit history와 대용량 산출물은 archive된 원본 저장소에 남아 있습니다.

현재 한계

• 네 실험은 공통 API로 통합된 상태가 아닙니다.
• 일부 하이퍼파라미터와 로봇 모델이 실험별로 다릅니다.
• C++ 코드는 로컬 MuJoCo/LibTorch 설치 환경에 따라 추가 설정이 필요합니다.
• Python PPO 코드는 Ray RLlib 버전 변화에 따라 API 수정이 필요할 수 있습니다.

다음 정리 우선순위는 공통 환경 계약, 의존성 lock, smoke test 자동화입니다.