python_simple_mppi

MPPI 제어를 numpy로 유도하고 구현한 저장소, 완성된 예제 넷과 함께

라이선스

MIT

개요

모델 예측 경로적분(MPPI) 제어는 입력 시퀀스를 수천 개 무작위로 표본화하고, 각각을 동역학 모델로 앞으로 굴려 점수를 매긴 뒤, 정보이론적 가중으로 하나의 명령으로 섞어 낸다. 현대 표본 기반 제어의 상당 부분이 이 방법 위에 서 있지만, 보통은 수식으로 가득한 한 쪽이거나 알고리즘이 안쪽에 묻힌 상용 프레임워크로만 만나게 된다. 이 저장소는 그 사이의 빠진 자리를 채운다. 완성된 예제 넷 — 기구학 자전거 모델을 쓴 경로 추종, 같은 과제에 장애물 회피를 더한 것, 진자 흔들어 세우기, 그리고 카트-폴 — 이 각각 실행 가능한 스크립트로, 그리고 LaTeX로 알고리즘을 단계별로 유도하는 주피터 노트북으로 제공되며, 인용한 Williams 등의 논문 알고리즘 1과 2를 따라간다. 의존성은 numpy, matplotlib, notebook뿐이다.

값어치는 짝지어 둔 데 있다. 예제마다 두 벌이 있다. 하나는 돌려서 시뮬레이션을 보는 스크립트, 다른 하나는 같은 제어기를 그것을 정당화하는 수학과 나란히 쌓아 올리는 노트북이다. 입력 시퀀스 표본화, 동역학 전방 전개, 단계 비용과 종단 비용의 누적, 정보이론에서 가중치 유도, 그리고 가중된 표본을 하나의 명령으로 되접기까지. 한쪽을 읽으며 다른 쪽을 돌리는 일은 논문을 읽는 것과 다른 경험이고, 저장소가 존재하는 이유가 바로 그것이다. 작성자는 설명에 대놓고 적어 두었다. 기본 개념을 이해하기 위한 것이라고.

절제는 의도된 것이고, 그것이 이 저장소가 작동하는 이유다. GPU도, JAX도, C++ 코어도, 설정 시스템도 없다. numpy와 matplotlib뿐이고, ffmpeg는 애니메이션을 mp4로 쓰고 싶을 때만 필요하다. 설치는 uv sync 한 줄, 아니면 자기 파이썬 환경을 건드리기 싫다면 docker compose run. 읽는 사람이 머리에 담아야 하는 것은 알고리즘뿐이고 그게 요점이며, 구현 전체가 한자리에서 읽어 낼 만한 크기다.

또한 일회성 결과물이 아니라 한 갈래 연구로 들어가는 입구다. 같은 작성자는 일본 산업기술종합연구소(AIST)에서 운동 계획과 제어를 연구하며, IROS 2024에 낸 스워브 드라이브 로봇용 MPPI 제어기 mppi_swerve_drive_ros, ROS에서 작업 우선순위를 다루는 다목적 MPC 프레임워크 nullspace_mpc, 그리고 같은 방식으로 구현한 경로 추종 알고리즘 모음 path_tracking_catalog를 공개해 두었다. 이 저장소를 끝까지 읽은 사람에게는 다음 갈 곳이 있고, 이는 대부분의 교육용 코드에는 해당하지 않는 말이다.

중요한 이유

이 카탈로그에는 사람들이 실제로 배치하는 계획기들 — MuJoCo MPC, OMPL, MoveIt, NeuPAN — 이 있지만, 표본 기반 방법이 어떻게 작동하는지 설명해 주는 것은 거의 없다. 특히 MPPI는 빽빽한 2018년 논문이거나, 쓸 수는 있어도 읽히지는 않는 최적화 구현으로 도착하기 마련이다. 이것은 읽을 수 있는 판본이다. 한 줄씩 따라갈 만큼 작고, 유도가 코드 옆에 있으며, 쓴 사람은 그 뒤 실제 로봇에서 심사를 거친 MPPI 연구를 발표했다. 교육용 저장소에 별이 칠백 개 붙었다는 것 자체가 이 빈자리를 메울 값어치가 얼마였는지를 알려 준다.

해결하는 문제

MPPI는 보통 정보이론 논문으로 만나거나 알고리즘이 프레임워크 안에 숨은 빠른 구현으로 만나는데, 둘 다 그것이 어떻게 작동하는지는 가르쳐 주지 않는다. 이 저장소는 읽어 낼 수 있는 크기의 알고리즘을 유도와 나란히 놓아 주고, 각 부분이 무엇을 하는지 보여 주는 시뮬레이션 넷을 함께 준다.

핵심 요점

완성된 예제 넷: 기구학 자전거 모델 경로 추종, 장애물 회피를 더한 경로 추종, 진자 흔들어 세우기, 카트-폴
예제마다 두 벌로 온다 — 실행 가능한 스크립트, 그리고 같은 코드 옆에서 LaTeX로 알고리즘을 유도하는 노트북
유도가 Williams 등의 「Information-Theoretic Model Predictive Control」 알고리즘 1과 2를 따르므로 노트북과 논문을 나란히 읽을 수 있다
의존성은 numpy, matplotlib, notebook뿐이다. 어느 것을 돌리든 그 밖에는 필요 없다
네이티브 환경은 uv sync, 컨테이너는 docker compose run. ffmpeg는 mp4 출력을 원할 때만
MIT 라이선스이며, 작성자는 AIST 연구자로 이후 IROS 2024에서 MPPI 연구를 발표했다
장애물 회피 예제가 알고리즘을 눈에 보이게 만든다. 표본 궤적이 부채처럼 퍼지고 그 사이를 가중된 명령이 지나간다

대상

MPPI를 처음 만나 호출만 하는 대신 이해하고 싶은 사람
수학이 함께 붙은 최적 제어 예제를 찾는 학생과 가르치는 사람
표본 기반 제어기를 시제품으로 만들면서 최적화 전에 정확하고 읽히는 출발점을 원하는 연구자
MPPI가 자기 문제에 맞는지 가늠하며 결정 전에 차량 모델에서의 거동을 먼저 봐야 하는 엔지니어

한계

설계부터 교육용 코드다. 작성자 본인의 표현이 '기본 개념을 이해하기 위한 것'이며, 배치나 실시간 보장을 위해 만들어지지 않았다
CPU 위의 순수 numpy라서 표본 수와 예측 구간이 실제 배치되는 MPPI 제어기보다 훨씬 작다
예제는 모두 2차원 장난감 동역학이다. 접촉도, 3차원도, 센서 모델도, 하드웨어 인터페이스도 없다
마지막 푸시가 2026년 5월이고 열린 이슈도 몇 건 남아 있다. 활발히 개발 중이라기보다 완성된 상태이며, 참조 구현으로는 알맞지만 수정을 기대해서는 안 된다
기여자는 둘, 사실상 하나다. 이 저장소는 작성자의 시간에 달려 있다
가져다 쓸 수 있는 라이브러리가 아니라 스크립트와 노트북이므로, 재사용하려면 코드를 베껴 내야 한다