python_simple_mppi

Controle MPPI deduzido e implementado em numpy, com quatro exemplos completos

Licença

MIT

Visão geral

O controle Model Predictive Path-Integral amostra milhares de sequências de entrada aleatórias, propaga cada uma por um modelo de dinâmica, pontua todas e as mistura num único comando por meio de uma ponderação vinda da teoria da informação. É o método por trás de boa parte do controle por amostragem moderno, e normalmente se o encontra ou como uma página de equações ou como um arcabouço de produção com o algoritmo enterrado lá dentro. Este repositório é o elo que faltava: quatro exemplos completos — seguimento de trajetória com um modelo de bicicleta cinemática, o mesmo com desvio de obstáculos, um pêndulo que se levanta e um carro-pêndulo — cada um um script executável acompanhado de um caderno Jupyter que deduz o algoritmo passo a passo em LaTeX, seguindo os algoritmos 1 e 2 do artigo de Williams et al. que ele cita. As únicas dependências são numpy, matplotlib e notebook.

O valor está no emparelhamento. Cada exemplo existe duas vezes: como script que você roda para ver a simulação, e como caderno onde o mesmo controlador é montado ao lado da matemática que o justifica — amostrar as sequências de entrada, propagar a dinâmica, acumular custos de estágio e terminal, deduzir os pesos a partir da teoria da informação e dobrar as amostras ponderadas de volta num único comando. Ler um enquanto o outro roda é uma experiência diferente de ler um artigo, e é exatamente para isso que o repositório existe. O autor diz isso sem rodeios na descrição: isto serve para entender a ideia básica.

A contenção é deliberada e é o que faz a coisa funcionar. Sem GPU, sem JAX, sem núcleo em C++, sem sistema de configuração — numpy e matplotlib, com ffmpeg apenas se você quiser gravar a animação em mp4. A instalação é um uv sync, ou um docker compose run se preferir não mexer no seu ambiente Python. Tudo que o leitor precisa segurar na cabeça é o algoritmo, que é justamente a intenção, e a implementação inteira é curta o bastante para se ler de uma sentada.

Também é a porta de entrada para um conjunto de trabalhos, não uma peça avulsa. O mesmo autor, pesquisador do AIST japonês em planejamento de movimento e controle, publicou o mppi_swerve_drive_ros, um controlador MPPI para robô de tração direcional apresentado na IROS 2024; o nullspace_mpc, um arcabouço de MPC multiobjetivo que lida com prioridades de tarefa em ROS; e o path_tracking_catalog, uma coleção de algoritmos de seguimento de trajetória tratados do mesmo jeito. Quem trabalhar este repositório sabe para onde ir depois, o que não vale para a maior parte do código didático.

Por que importa

O catálogo reúne os planejadores que as pessoas implantam — MuJoCo MPC, OMPL, MoveIt, NeuPAN — e quase nada que explique como funcionam os baseados em amostragem. O MPPI em especial costuma chegar ou como um artigo denso de 2018 ou como uma implementação otimizada que você usa mas não lê. Esta é a versão legível: pequena o bastante para acompanhar linha a linha, com a dedução ao lado do código, de alguém que desde então publicou trabalho revisado sobre MPPI em robôs reais. Setecentas estrelas para um repositório didático são uma medida justa do tamanho da lacuna que ele preenche.

Problema que resolve

Normalmente se encontra o MPPI ou como artigo de teoria da informação ou como implementação rápida com o algoritmo escondido dentro de um arcabouço, e nenhuma das duas ensina como ele funciona. Isto entrega o algoritmo num tamanho que dá para ler, com a dedução ao lado e quatro simulações que mostram o que cada parte dele faz.

Pontos principais

• Quatro exemplos completos: seguimento de trajetória com modelo de bicicleta cinemática, seguimento com desvio de obstáculos, pêndulo que se levanta e carro-pêndulo
• Cada exemplo vem duas vezes — como script executável e como caderno que deduz o algoritmo em LaTeX ao lado do mesmo código
• A dedução segue os algoritmos 1 e 2 de Williams et al., «Information-Theoretic Model Predictive Control», então caderno e artigo podem ser lidos juntos
• As dependências são numpy, matplotlib e notebook — nada além disso é preciso para rodar qualquer parte
• uv sync para instalação nativa, ou docker compose run para uma em contêiner; ffmpeg só se quiser saída em mp4
• Licenciado sob MIT, de um pesquisador do AIST que desde então publicou trabalho de MPPI na IROS 2024
• O exemplo com obstáculos torna o algoritmo visível: o leque de trajetórias amostradas e o comando ponderado traçado através dele

Para quem é

• Quem encontra o MPPI pela primeira vez e quer entendê-lo em vez de apenas chamá-lo
• Estudantes e professores de controle ótimo à procura de um exemplo trabalhado com a matemática junto
• Pesquisadores prototipando um controlador por amostragem que querem um ponto de partida correto e legível antes de otimizar
• Engenheiros avaliando se o MPPI serve ao seu problema e que precisam ver o comportamento dele num modelo de veículo antes de se comprometer

Limitações

• É código didático por projeto — a formulação do próprio autor é «para entender a ideia básica», e não foi construído para implantação nem garantias de tempo real
• numpy puro na CPU, então as contagens de amostras e os horizontes ficam bem abaixo do que um controlador MPPI implantado usaria
• Os exemplos são dinâmicas de brinquedo em 2D: sem contato, sem 3D, sem modelos de sensores e sem interface de hardware
• Último push em maio de 2026 e com algumas issues abertas; está terminado mais do que em desenvolvimento ativo, o que combina com uma implementação de referência mas significa não esperar correções
• Dois contribuidores, e na prática um — o repositório depende do tempo do autor
• São scripts e cadernos, não uma biblioteca importável, então reutilizar significa copiar o código para fora
• O GitHub marca a licença como não reconhecida porque o arquivo se chama LICENSE.txt; o conteúdo é o texto MIT padrão, copyright 2023 MizuhoAOKI