python_simple_mppi

Controllo MPPI ricavato e implementato in numpy, con quattro esempi svolti

Licenza

MIT

Panoramica

Il controllo Model Predictive Path-Integral campiona migliaia di sequenze di ingressi casuali, le fa evolvere una per una attraverso un modello dinamico, assegna a ciascuna un punteggio e le combina in un unico comando con una ponderazione basata sulla teoria dell'informazione. È il metodo alla base di buona parte del controllo moderno basato sul campionamento, e di solito lo si incontra o come una pagina di equazioni o come un framework di produzione con l'algoritmo sepolto all'interno. Questo repository è l'anello mancante: quattro esempi svolti (inseguimento del percorso con un modello cinematico a bicicletta, lo stesso con evitamento degli ostacoli, lo swing-up di un pendolo e un cartpole), ciascuno uno script eseguibile affiancato da un notebook Jupyter che ricava l'algoritmo passo per passo in LaTeX, seguendo gli Algoritmi 1 e 2 dell'articolo di Williams et al. che cita. Le uniche dipendenze sono numpy, matplotlib e notebook.

Il valore sta nell'abbinamento. Ogni esempio esiste due volte: una come script da eseguire per guardare la simulazione, e una come notebook in cui lo stesso controller viene costruito insieme alla matematica che lo giustifica: il campionamento delle sequenze di ingressi, l'evoluzione in avanti della dinamica, l'accumulo dei costi di stadio e terminali, la derivazione dei pesi dalla teoria dell'informazione e la ricomposizione dei campioni ponderati in un unico comando. Leggere l'uno mentre si esegue l'altro è un'esperienza diversa dalla lettura di un articolo, ed è ciò a cui il repository serve davvero. L'autore lo dice chiaramente nella descrizione: serve a capire l'idea di base.

La sobrietà è voluta ed è ciò che lo fa funzionare. Niente GPU, niente JAX, niente nucleo in C++, niente sistema di configurazione: numpy e matplotlib, con ffmpeg necessario solo se si vuole salvare l'animazione in mp4. La configurazione è un uv sync, oppure un docker compose run se si preferisce non toccare il proprio ambiente Python. Tutto ciò che il lettore deve tenere a mente è l'algoritmo, che è proprio lo scopo, e l'intera implementazione è abbastanza piccola da leggersi in una sola seduta.

È anche il punto di ingresso a un insieme di lavori correlati, non un caso isolato. Lo stesso autore, un ricercatore dell'AIST giapponese che si occupa di pianificazione del movimento e controllo, ha pubblicato mppi_swerve_drive_ros, un controller MPPI presentato a IROS 2024 per un robot a trazione swerve; nullspace_mpc, un framework di controllo predittivo basato su modello (MPC) multi-obiettivo che gestisce le priorità dei compiti in ROS; e path_tracking_catalog, una raccolta di algoritmi di inseguimento del percorso implementati allo stesso modo. Chi studia questo repository ha un posto dove andare dopo, cosa che non vale per la maggior parte del codice didattico.

Perché è importante

Il catalogo contiene i pianificatori che le persone mettono in produzione (MuJoCo MPC, OMPL, MoveIt, NeuPAN) e quasi nulla che spieghi come funzionano quelli basati sul campionamento. MPPI in particolare tende ad arrivare o come un denso articolo del 2018 o come un'implementazione ottimizzata che si può usare ma non leggere. Questa è la versione che si può leggere: abbastanza piccola da seguirla riga per riga, con la derivazione accanto al codice, da parte di qualcuno che da allora ha pubblicato lavori su MPPI sottoposti a revisione paritaria su robot reali. Settecento stelle per un repository didattico sono una misura onesta di quanto valesse colmare quella lacuna.

Il problema che risolve

Di solito MPPI si incontra o come un articolo di teoria dell'informazione o come un'implementazione veloce con l'algoritmo nascosto dentro un framework, e nessuno dei due insegna come funziona. Questo repository offre l'algoritmo in una dimensione leggibile, con la derivazione accanto al codice e quattro simulazioni che mostrano che cosa fa ciascuna sua parte.

Punti chiave

• Quattro esempi svolti: inseguimento del percorso con un modello cinematico a bicicletta, inseguimento del percorso con evitamento degli ostacoli, swing-up di un pendolo e cartpole
• Ogni esempio è fornito due volte: come script eseguibile e come notebook che ricava l'algoritmo in LaTeX accanto allo stesso codice
• La derivazione segue gli Algoritmi 1 e 2 di Williams et al., 'Information-Theoretic Model Predictive Control', così il notebook e l'articolo si possono leggere insieme
• Le dipendenze sono numpy, matplotlib e notebook: non serve nient'altro per eseguire nulla
• uv sync per un'installazione nativa, o docker compose run per una in container; ffmpeg solo se si vuole l'output in mp4
• Con licenza MIT, da un ricercatore dell'AIST che da allora ha pubblicato lavori su MPPI a IROS 2024
• L'esempio con evitamento degli ostacoli rende visibile l'algoritmo: il ventaglio di traiettorie campionate e il comando ponderato tracciato in mezzo

A chi si rivolge

• Chiunque incontri MPPI per la prima volta e voglia capirlo anziché limitarsi a chiamarlo
• Studenti e docenti di controllo ottimo che cercano un esempio svolto con la matematica allegata
• Ricercatori che prototipano un controller basato sul campionamento e vogliono un punto di partenza corretto e leggibile prima di ottimizzare
• Ingegneri che valutano se MPPI è adatto al loro problema e devono vederne il comportamento su un modello di veicolo prima di impegnarsi

Limiti

• È codice didattico per scelta: l'autore stesso lo presenta come 'to understand the basic idea', e non è costruito per la messa in produzione né per garanzie di tempo reale
• Puro numpy su CPU, quindi il numero di campioni e gli orizzonti sono molto inferiori a quelli che userebbe un controller MPPI in produzione
• Gli esempi sono dinamiche giocattolo in 2D: niente contatti, niente 3D, niente modelli di sensori e nessuna interfaccia hardware
• Ultimo push a maggio 2026, con una manciata di issue aperte; è un lavoro concluso più che in sviluppo attivo, il che si addice a un'implementazione di riferimento ma significa non aspettarsi correzioni
• Due collaboratori, e di fatto uno: il repository dipende interamente dal tempo dell'autore
• Script e notebook anziché una libreria importabile, quindi riutilizzarlo significa copiarne il codice
• GitHub segnala la licenza come non riconosciuta perché il file si chiama LICENSE.txt; il file in sé è il testo MIT standard, copyright 2023 MizuhoAOKI