O que é leonard e penny e por que você provavelmente já ouviu falar disso de forma errada
leonard e penny é um framework de simulação baseado em agentes desenvolvido no Centro de Pesquisa de Sistemas Complexos da Universidade de Indiana. Não é um software comercial. Não tem interface gráfica oficial. Você roda ele no terminal, geralmente através do Python, e os resultados aparecem como séries temporais e visualizações que você precisa montar manualmente ou com bibliotecas de terceiros. Muita gente confunde com qualquer modelo de simulação social, mas especificamente se trata da implementação moderna dos modelos clássicos de segregação de Schelling, expandidos para múltiplas variáveis de preferência, mobilidade e interação.
como começar a usar leonard e penny na prática
A instalação básica é direta se você já tem Python 3.9 ou superior. O repositório principal fica no GitHub e pode ser clonado diretamente. Eu recomendo criar um ambiente virtual antes porque as dependências do package são um pouco agressivas com versões de numpy e mesa. Rodar sem isolar o ambiente costuma quebrar instalações anteriores do scipy no seu sistema. Depois de clonado, um pip install -e . dentro do diretório resolve a maioria dos casos. Se der erro de compilação do Cython, atualize o Cython para a versão mais recente e tente novamente. Funcionou na maior parte das vezes. O modelo básico funciona assim: você define um grid, popula com agentes de diferentes tipos, configura uma função de utilidade que determina o quão satisfeito cada agente está com seus vizinhos, e roda o simulador passo a passo. Cada passo envolve revisar todos os agentes, calcular a satisfação deles baseada nos vizinhos imediatos, e reposicionar os insatisfeitos em células vazias aleatórias. O padrão é rodar entre 100 e 500 passos e observar a convergência. Em média, um grid 100x100 com 2.000 agentes leva cerca de 3 a 5 minutos num laptop comum. A memória consumida fica na faixa de 400 a 800 MB dependendo da densidade.
o problema que eu encontrei e como resolvi
A primeira vez que tentei rodar uma simulação com mais de 5.000 agentes num grid 200x200, o processo travou completamente após aproximadamente 80 passos. O sistema operacional não matou o processo, mas a CPU ficava em 100% e a simulação basicamente parava de avançar. Após investigar o log, percebi que o problema era um gargalo na função de varredura dos vizinhos do grid. O código original faz uma verificação quadrada de raio 1 para cada agente a cada passo, e com milhares de agentes isso escala de forma quadrática. A solução que encontrei foi substituir a verificação por uma estrutura de KD-tree para consulta de vizinhança, o que reduziu o tempo de cada passo de aproximadamente 45 segundos para cerca de 2 segundos. Não é um fix oficial do projeto, mas o código é aberto e a modificação é relativamente simples se você tiver familiaridade com scipy.spatial.KDTree. Publiquei um gist com o patch caso alguém mais precise.
👉 Clique no botão abaixo para saber mais sobre o assunto!
insights que não estão manuais introdutórios
A coisa mais contra-intuitiva que eu aprendi depois de rodar dezenas de simulações é que o parâmetro de tolerância que parece inofensivo em valores baixos tem um efeito desproporcional nos resultados finais. Um threshold de satisfação de 0,3 pode parecer baixo, mas na prática gera segregação quase total em poucas centenas de passos. A curva não é linear. Pequenos aumentos nesse parâmetro entre 0,3 e 0,5 produzem mudanças qualitativas enormes no padrão de agregação. Comece sempre com 0,6 se quiser ver coexistência misturada, e suba gradualmente se quiser testar segregação. Outro ponto que ninguém menciona bastante: a escolha do esquema de reposição importa muito. O padrão usa reposição aleatória em células vazias, mas isso pode criar artefatos de borda onde agentes ficam presos em regiões periféricas do grid por muitos passos. Se você estiver estudando dinâmicas de mobilidade realista, considere usar reposição baseada em distância mínima, onde agentes insatisfeitos migram para a célula vazia mais próxima. O resultado visual é muito mais plausível e os tempos de convergência mudam significativamente.
limitações reais que você precisa saber antes de confiar nos resultados
leonard e penny não é adequado para simulações em larga escala geográfica ou com dados empíricos diretamente importáveis. O framework foi construído para pesquisa acadêmica em sistemas complexos, não para análise de dados urbanos reais. Se você precisa rodar simulações com mais de 50.000 agentes, o tempo de execução fica impraticável mesmo com otimizações. Para esses casos, alternativas como o NetLogo ou implementações em Julia com CUDA oferecem melhor escalabilidade. Também não há suporte nativo para entrada de dados georeferenciados ou integração direta com APIs de dados abertos. Tudo precisa ser preparado manualmente em formato de matriz ou lista de coordenadas. Um problema frequente é que o framework não faz validação automática de condições de parada. Você precisa definir sozinho quando interromper a simulação, seja por número fixo de passos, estabilidade da métrica de segregação, ou convergência visual. Sem esse controle, você pode gastar horas rodando simulações que já chegaram ao equilíbrio estatístico há centenas de passos. Implementar um detector de convergência baseado na variação do índice de Moran a cada 10 passos é uma prática comum no meio e resolve esse problema na maior parte dos casos.
A documentação oficial é funcional mas enxuta. Os exemplos são mínimo viáveis e não cobrem cenários mais elaborados como múltiplas camadas de agentes, heterogeneidade nas funções de utilidade por tipo de agente, ou acoplamento com modelos externos. A comunidade é pequena mas ativa, e o histórico de issues no GitHub é o melhor recurso para problemas específicos. Se você estiver preso num bug ou num comportamento inesperado, vale a pena passar algumas horas lendo threads antigas antes de abrir uma nova issue. Muitas vezes o problema já foi discutido e resolvido.
