python_simple_mppi

Control MPPI deducido e implementado en numpy, con cuatro ejemplos completos

Licencia

MIT

Resumen

El control Model Predictive Path-Integral muestrea miles de secuencias de entrada aleatorias, propaga cada una por un modelo dinámico, las puntúa y las mezcla en una sola orden mediante una ponderación de teoría de la información. Es el método que sostiene buena parte del control por muestreo moderno, y normalmente uno se lo encuentra o como una página de ecuaciones o como un marco de producción con el algoritmo enterrado dentro. Este repositorio es el eslabón que faltaba: cuatro ejemplos completos —seguimiento de trayectoria con un modelo de bicicleta cinemática, lo mismo con evitación de obstáculos, un péndulo que se levanta y un carro-péndulo— cada uno un script ejecutable acompañado de un cuaderno Jupyter que deduce el algoritmo paso a paso en LaTeX, siguiendo los algoritmos 1 y 2 del artículo de Williams et al. que cita. Las únicas dependencias son numpy, matplotlib y notebook.

El valor está en el emparejamiento. Cada ejemplo existe dos veces: como script que ejecutas para ver la simulación, y como cuaderno donde el mismo controlador se construye junto a las matemáticas que lo justifican: muestrear las secuencias de entrada, propagar la dinámica, acumular costes de etapa y terminal, deducir los pesos a partir de la teoría de la información y plegar las muestras ponderadas en una única orden. Leer uno mientras corre el otro es una experiencia distinta de leer un artículo, y es para lo que existe el repositorio. El autor lo dice sin rodeos en la descripción: esto sirve para entender la idea básica.

La contención es deliberada y es lo que hace que funcione. Sin GPU, sin JAX, sin núcleo en C++, sin sistema de configuración: numpy y matplotlib, con ffmpeg solo si quieres escribir la animación en mp4. La instalación es un uv sync, o un docker compose run si prefieres no tocar tu entorno de Python. Todo lo que el lector debe retener es el algoritmo, que es justamente la intención, y la implementación entera es lo bastante corta para leerla de una sentada.

También es la puerta de entrada a un cuerpo de trabajo, no una pieza suelta. El mismo autor, investigador del AIST japonés en planificación de movimiento y control, ha publicado mppi_swerve_drive_ros, un controlador MPPI para un robot de tracción orientable presentado en IROS 2024; nullspace_mpc, un marco de MPC multiobjetivo que maneja prioridades de tarea en ROS; y path_tracking_catalog, una colección de algoritmos de seguimiento de trayectoria tratados del mismo modo. Quien se trabaje este repositorio sabe adónde ir después, cosa que no ocurre con la mayoría del código docente.

Por qué importa

El catálogo reúne los planificadores que la gente despliega —MuJoCo MPC, OMPL, MoveIt, NeuPAN— y casi nada que explique cómo funcionan los que se basan en muestreo. MPPI en particular suele llegar o como un artículo denso de 2018 o como una implementación optimizada que puedes usar pero no leer. Esta es la versión que sí puedes leer: lo bastante pequeña para seguirla línea a línea, con la deducción junto al código, de alguien que desde entonces ha publicado trabajo revisado sobre MPPI en robots reales. Setecientas estrellas para un repositorio docente son una medida justa de cuánta falta hacía llenar ese hueco.

Qué problema resuelve

A MPPI se lo encuentra uno normalmente o como artículo de teoría de la información o como implementación rápida con el algoritmo escondido dentro de un marco, y ninguna de las dos enseña cómo funciona. Esto te da el algoritmo en un tamaño que puedes leer, con la deducción al lado y cuatro simulaciones que muestran qué hace cada una de sus partes.

Puntos clave

• Cuatro ejemplos completos: seguimiento de trayectoria con modelo de bicicleta cinemática, seguimiento con evitación de obstáculos, péndulo que se levanta y carro-péndulo
• Cada ejemplo viene por duplicado: como script ejecutable y como cuaderno que deduce el algoritmo en LaTeX junto al mismo código
• La deducción sigue los algoritmos 1 y 2 de Williams et al., «Information-Theoretic Model Predictive Control», así que cuaderno y artículo se leen juntos
• Las dependencias son numpy, matplotlib y notebook: no hace falta nada más para ejecutar ninguna parte
• uv sync para una instalación nativa, o docker compose run para una en contenedor; ffmpeg solo si quieres salida en mp4
• Licencia MIT, de un investigador del AIST que desde entonces ha publicado trabajo sobre MPPI en IROS 2024
• El ejemplo con obstáculos hace visible el algoritmo: el abanico de trayectorias muestreadas y la orden ponderada trazada a través de él

Para quién es

• Quien se encuentre con MPPI por primera vez y quiera entenderlo en vez de limitarse a invocarlo
• Estudiantes y docentes de control óptimo que buscan un ejemplo trabajado con las matemáticas incluidas
• Investigadores que prototipan un controlador por muestreo y quieren un punto de partida correcto y legible antes de optimizar
• Ingenieros que evalúan si MPPI encaja en su problema y necesitan ver su comportamiento en un modelo de vehículo antes de comprometerse

Limitaciones

• Es código docente por diseño: la fórmula del propio autor es «para entender la idea básica», y no está construido para despliegue ni garantías de tiempo real
• numpy puro sobre CPU, así que el número de muestras y los horizontes quedan muy por debajo de lo que usaría un controlador MPPI desplegado
• Los ejemplos son dinámicas de juguete en 2D: sin contacto, sin 3D, sin modelos de sensores y sin interfaz de hardware
• Última actualización en mayo de 2026 y con unas pocas incidencias abiertas; está terminado más que en desarrollo activo, lo que encaja con una implementación de referencia pero significa no esperar arreglos
• Dos colaboradores, y en la práctica uno: el repositorio depende del tiempo del autor
• Son scripts y cuadernos, no una biblioteca importable, así que reutilizarlo implica copiar código fuera
• GitHub marca la licencia como no reconocida porque el archivo se llama LICENSE.txt; su contenido es el texto MIT estándar, copyright 2023 MizuhoAOKI