python_simple_mppi

La commande MPPI démontrée et implémentée en numpy, avec quatre exemples complets

Licence

MIT

Aperçu

La commande Model Predictive Path-Integral échantillonne des milliers de séquences d'entrée aléatoires, propage chacune à travers un modèle de dynamique, les note, puis les mélange en une seule commande par une pondération issue de la théorie de l'information. C'est la méthode qui sous-tend une bonne part de la commande par échantillonnage moderne, et on la rencontre d'ordinaire soit comme une page d'équations, soit comme un cadre de production où l'algorithme est enfoui. Ce dépôt est le chaînon manquant : quatre exemples complets — suivi de trajectoire avec un modèle de bicyclette cinématique, le même avec évitement d'obstacles, un pendule qu'on redresse et un chariot-pendule — chacun sous forme de script exécutable accompagné d'un carnet Jupyter qui démontre l'algorithme pas à pas en LaTeX, en suivant les algorithmes 1 et 2 de l'article de Williams et al. qu'il cite. Les seules dépendances sont numpy, matplotlib et notebook.

La valeur tient à l'appariement. Chaque exemple existe deux fois : une fois comme script que l'on lance pour regarder la simulation, une fois comme carnet où le même correcteur se construit à côté des mathématiques qui le justifient — échantillonnage des séquences d'entrée, propagation de la dynamique, cumul des coûts d'étape et terminal, dérivation des poids depuis la théorie de l'information, et repliement des échantillons pondérés en une commande unique. Lire l'un pendant que l'autre tourne n'a rien à voir avec la lecture d'un article, et c'est précisément la raison d'être du dépôt. L'auteur le dit sans détour dans la description : ceci sert à comprendre l'idée de base.

La retenue est délibérée et c'est ce qui fait que cela marche. Pas de GPU, pas de JAX, pas de cœur en C++, pas de système de configuration — numpy et matplotlib, ffmpeg seulement si l'on veut écrire l'animation en mp4. L'installation tient en un uv sync, ou un docker compose run si l'on préfère ne pas toucher à son environnement Python. Tout ce que le lecteur doit garder en tête, c'est l'algorithme, ce qui est bien le but, et l'implémentation entière est assez courte pour se lire d'une traite.

C'est aussi une porte d'entrée vers un ensemble de travaux plutôt qu'une pièce isolée. Le même auteur, chercheur à l'AIST japonais en planification de mouvement et commande, a publié mppi_swerve_drive_ros, un correcteur MPPI pour robot à roues directrices présenté à IROS 2024 ; nullspace_mpc, un cadre de MPC multi-objectif gérant les priorités de tâches sous ROS ; et path_tracking_catalog, une collection d'algorithmes de suivi de trajectoire traités de la même façon. Qui travaille ce dépôt sait où aller ensuite, ce qui est rare pour du code pédagogique.

Pourquoi c'est important

Le catalogue rassemble les planificateurs que l'on déploie — MuJoCo MPC, OMPL, MoveIt, NeuPAN — et presque rien qui explique le fonctionnement de ceux fondés sur l'échantillonnage. MPPI en particulier arrive soit sous la forme d'un article dense de 2018, soit sous celle d'une implémentation optimisée que l'on peut utiliser mais pas lire. Voici la version lisible : assez petite pour la suivre ligne à ligne, la démonstration à côté du code, signée par quelqu'un qui a depuis publié des travaux évalués sur MPPI avec de vrais robots. Sept cents étoiles pour un dépôt pédagogique mesurent assez bien l'ampleur du manque qu'il comble.

Le problème résolu

On rencontre normalement MPPI soit comme un article de théorie de l'information, soit comme une implémentation rapide où l'algorithme est caché dans un cadre logiciel, et ni l'un ni l'autre n'apprend comment il fonctionne. Ceci donne l'algorithme à une taille lisible, la démonstration à côté, et quatre simulations qui montrent ce que fait chacune de ses parties.

Points clés

• Quatre exemples complets : suivi de trajectoire avec modèle de bicyclette cinématique, suivi avec évitement d'obstacles, redressement d'un pendule et chariot-pendule
• Chaque exemple est fourni deux fois — en script exécutable et en carnet qui démontre l'algorithme en LaTeX à côté du même code
• La démonstration suit les algorithmes 1 et 2 de Williams et al., « Information-Theoretic Model Predictive Control », carnet et article se lisent donc ensemble
• Les dépendances sont numpy, matplotlib et notebook — rien d'autre n'est nécessaire pour exécuter quoi que ce soit
• uv sync pour une installation native, ou docker compose run pour une version conteneurisée ; ffmpeg seulement pour la sortie mp4
• Sous licence MIT, par un chercheur de l'AIST qui a depuis publié des travaux MPPI à IROS 2024
• L'exemple avec obstacles rend l'algorithme visible : l'éventail des trajectoires échantillonnées et la commande pondérée qui le traverse

Pour qui

• Quiconque découvre MPPI et veut le comprendre plutôt que se contenter de l'appeler
• Étudiants et enseignants en commande optimale cherchant un exemple travaillé avec les mathématiques jointes
• Chercheurs prototypant un correcteur par échantillonnage et voulant un point de départ correct et lisible avant d'optimiser
• Ingénieurs évaluant si MPPI convient à leur problème et devant voir son comportement sur un modèle de véhicule avant de s'engager

Limites

• C'est du code pédagogique par construction — la formule de l'auteur lui-même est « pour comprendre l'idée de base », et ce n'est pas conçu pour le déploiement ni pour des garanties temps réel
• Du numpy pur sur processeur : le nombre d'échantillons et les horizons restent très en deçà de ce qu'utiliserait un correcteur MPPI déployé
• Les exemples sont des dynamiques jouets en 2D : pas de contact, pas de 3D, pas de modèles de capteurs ni d'interface matérielle
• Dernière mise à jour en mai 2026, avec quelques tickets ouverts ; il est achevé plutôt qu'activement développé, ce qui convient à une implémentation de référence mais signifie qu'il ne faut pas attendre de correctifs
• Deux contributeurs, en pratique un seul — le dépôt dépend du temps de l'auteur
• Des scripts et des carnets plutôt qu'une bibliothèque importable : le réutiliser suppose d'en recopier le code
• GitHub signale la licence comme non reconnue parce que le fichier s'appelle LICENSE.txt ; son contenu est le texte MIT standard, copyright 2023 MizuhoAOKI