How marceloanje/otimizador-rotas-foodservice works
1. Visão geral da arquitetura
Este repositório é um protótipo de otimização de rotas para food-service, focado no VRP com janelas de tempo. A aplicação é organizada como um pipeline: dados de pedidos entram, passam por geoprocessamento para virar instância do problema, e então são avaliados por um conjunto de algoritmos exatos/meta-heurísticos.
2. Ponto de entrada e orquestração
O fluxo principal parece ser iniciado por src/main.py, com apoio de src/comparador.py para executar e comparar métodos. A configuração global fica em src/config.py e src/config_experimento.py, que provavelmente controlam parâmetros de ambiente, execução e experimento.
3. Dados e insumos do problema
O repositório já inclui dados de exemplo em src/dados/, como pedidos_pequeno.csv e matriz_distancias.csv. Esses arquivos representam, respectivamente, a demanda/pedidos e a matriz de custos/distâncias usada pelos algoritmos.
4. Camada de geoprocessamento
O pacote src/geoprocessamento/ é a fronteira entre dados “crus” e a instância otimizada.
- geocodificador.py: indica transformação de endereços em coordenadas.
- preprocessamento.py: prepara dados para o solver, incluindo limpeza e montagem da instância.
- integracao_osrm.py: integra com o OSRM para obter distâncias reais por malha viária.
5. Dependência externa crítica: OSRM local
O README deixa claro que existe um serviço externo opcional/estratégico: um servidor OSRM rodando localmente via Docker. Ele é usado para construir a matriz de distâncias reais. Se o OSRM estiver indisponível, o sistema faz fallback para distância euclidiana. Isso é um boundary importante do desenho: o núcleo do otimizador não depende diretamente da internet, mas pode usar um serviço local para enriquecer os custos.
6. Modelo de domínio do VRP
O pacote src/modelos/ concentra a representação formal do problema e da solução.
- instancia.py: encapsula os dados do caso de teste.
- representacao.py: define como uma solução é codificada internamente.
- solucao.py: guarda a solução final, custo e métricas.
- objetivo_config.py: define os pesos/regras da função objetivo e restrições.
7. Geração de soluções e operadores auxiliares
src/utilitarios/ contém as rotinas reutilizáveis que alimentam os algoritmos.
- construtivas.py: gera soluções iniciais viáveis.
- local_search.py: aplica refinamento local sobre rotas.
- simulacao_rota.py: avalia a execução de uma rota, provavelmente verificando tempo/janelas/custos.
- graficos_experimento.py: produz visualizações e comparações dos resultados.
8. Algoritmos de otimização comparados
Em src/algoritmos/ estão as estratégias principais do projeto:
- busca_tabu.py
- colonia_formigas.py
- enxame_particulas.py
- solver_referencia.py
Esse conjunto sugere uma arquitetura de comparação entre um baseline/referência e três meta-heurísticas. Os algoritmos devem consumir a mesma instância e função objetivo para permitir comparação justa.
9. Fluxo de dados entre camadas
O fluxo típico é: arquivos CSV → geoprocessamento/preprocessamento → Instancia → codificação da solução → algoritmo de busca → avaliação em Solucao/função objetivo → comparação e gráficos. A matriz de distâncias é um artefato central no meio desse fluxo, pois liga os dados geográficos ao custo de otimização.
10. Saída analítica e experimento
O projeto não parece ser um sistema transacional; ele é orientado a experimento. Os principais produtos de saída são soluções de rota, métricas de qualidade e comparações entre algoritmos, possivelmente com gráficos e relatórios gerados por comparador.py e utilitarios/graficos_experimento.py.
11. Testes e validação
Há uma suíte simples em testes/, com teste.py, indicando validação automatizada das partes principais do pipeline. Isso é importante porque o projeto combina leitura de dados, cálculo de distâncias e heurísticas, onde regressões são fáceis de introduzir.
12. Leitura arquitetural resumida
Em termos de diagrama, o sistema deve ser visto como quatro blocos principais:
(a) entrada/preprocessamento de dados,
(b) modelo de domínio do VRP,
(c) motores de otimização,
(d) comparação/visualização de experimentos.
O OSRM fica fora do core e atua como serviço de infraestrutura para custos reais de deslocamento.
Main entry points: comparador.py Comparador · preprocessamento.py Preprocessamento · busca_tabu.py Tabu search · solucao.py Solução
Components 23
Entrada e dados
Insumos, preparação e integração geográfica.
- Pedidos · Dados de pedidos e demanda de exemplo.
src/dados/pedidos_pequeno.csv - Distâncias · Matriz de custos/distâncias usada pelos algoritmos.
src/dados/matriz_distancias.csv - Preprocessamento · Limpeza e montagem da instância do problema.
src/geoprocessamento/preprocessamento.py - Geocodificador · Transforma endereços em coordenadas.
src/geoprocessamento/geocodificador.py - OSRM integração · Consulta rotas reais e constrói distâncias por rede viária.
src/geoprocessamento/integracao_osrm.py
Domínio VRP
Modelos centrais da instância, solução e objetivo.
- Instância · Encapsula o caso de teste e seus dados estruturados.
src/modelos/instancia.py - Representação · Codificação interna da solução para os algoritmos.
src/modelos/representacao.py - Solução · Armazena solução final, custo e métricas.
src/modelos/solucao.py - Objetivo · Pesos, regras e restrições da função objetivo.
src/modelos/objetivo_config.py
Otimização
Solvers, heurísticas e operadores de busca.
- Construtivas · Gera soluções iniciais viáveis.
src/utilitarios/construtivas.py - Local search · Melhora rotas por busca local.
src/utilitarios/local_search.py - Simulador · Avalia execução de rotas, tempos e janelas.
src/utilitarios/simulacao_rota.py - Tabu search · Busca tabu para otimização de rotas.
src/algoritmos/busca_tabu.py - Ant colony · Colônia de formigas para construção iterativa de rotas.
src/algoritmos/colonia_formigas.py - Particle swarm · Enxame de partículas adaptado ao problema de rotas.
src/algoritmos/enxame_particulas.py - Baseline · Solver de referência para comparação experimental.
src/algoritmos/solver_referencia.py
Experimentos
Orquestração, comparação e visualização de resultados.
- Main · Ponto de entrada da aplicação e início do fluxo principal.
src/main.py - Comparador · Executa métodos e compara resultados entre algoritmos.
src/comparador.py - Config · Parâmetros globais de execução e ambiente.
src/config.py - Exp config · Configuração específica de experimentos e cenários.
src/config_experimento.py - Gráficos · Gera gráficos e comparações dos experimentos.
src/utilitarios/graficos_experimento.py - Testes · Validação automatizada do pipeline principal.
testes/teste.py
Infraestrutura externa
Serviço auxiliar de roteamento usado na construção de distâncias.
- OSRM server · Serviço local opcional para custos por rede viária.
Connections 37
- Main → Comparador: executa · A entrada dispara a comparação de métodos.
- Main → Config: lê · Carrega configuração global.
- Main → Exp config: lê · Carrega parâmetros experimentais.
- Comparador → Tabu search: roda · O comparador executa a busca tabu.
- Comparador → Ant colony: roda · O comparador executa a colônia de formigas.
- Comparador → Particle swarm: roda · O comparador executa o enxame de partículas.
- Comparador → Baseline: roda · O comparador executa o solver de referência.
- Pedidos → Preprocessamento: entrada · Pedidos alimentam o preprocessamento.
- Preprocessamento → Geocodificador: usa · O preprocessamento pode geocodificar endereços.
- Preprocessamento → OSRM integração: consulta · Pode buscar distâncias reais via OSRM.
- Geocodificador → OSRM integração: coordena · Coordenadas alimentam a integração de rotas.
- OSRM integração → OSRM server: requisições · A integração depende do servidor OSRM local.
- Preprocessamento → Distâncias: gera · O preprocessamento produz ou atualiza a matriz de distâncias.
- Preprocessamento → Instância: monta · Transforma dados preparados em instância VRP.
- Distâncias → Instância: alimenta · A matriz de custos compõe a instância.
- Instância → Representação: codifica · A instância é convertida em representação para busca.
- Instância → Objetivo: aplica · A instância usa a configuração do objetivo.
- Construtivas → Representação: cria · Constrói soluções iniciais na representação interna.
- Local search → Representação: refina · A busca local opera sobre a codificação da solução.
- Simulador → Solução: avalia · Simula e mede a qualidade da solução.
- Tabu search → Construtivas: inicia · A busca tabu parte de uma solução construtiva.
- Tabu search → Local search: refina · Usa vizinhança e busca local.
- Tabu search → Simulador: valida · Avalia custo e restrições durante a busca.
- Ant colony → Construtivas: constrói · A colônia usa heurísticas construtivas.
- Ant colony → Simulador: avalia · Pontua rotas com o simulador.
- Particle swarm → Construtivas: inicia · O enxame usa soluções iniciais.
- Particle swarm → Local search: ajusta · Explora melhorias locais nas partículas.
- Particle swarm → Simulador: avalia · Mede desempenho das partículas.
- Baseline → Simulador: compara · O baseline é avaliado pela mesma lógica.
- Tabu search → Solução: produz · A heurística retorna uma solução final.
- Ant colony → Solução: produz · A meta-heurística retorna uma solução final.
- Particle swarm → Solução: produz · A meta-heurística retorna uma solução final.
- Baseline → Solução: produz · O solver de referência retorna uma solução final.
- Solução → Comparador: resultados · Soluções e métricas voltam para comparação.
- Comparador → Gráficos: gera · A comparação alimenta gráficos experimentais.
- Testes → Preprocessamento: verifica · Os testes validam o preprocessamento e o pipeline.
- Testes → Tabu search: verifica · Os testes cobrem o comportamento dos algoritmos.