Simulador de Federated Learning para Tráfego Urbano

Visão geral

Este projeto implementa um simulador/benchmark de federated learning (FL) para previsão de tráfego urbano. Ele inclui:

• Estratégias de federação com agregadores avançados (FedAvg/FedProx/FedNova/RFA, FedDyn, SCAFFOLD, FedOpt) e controle completo do ciclo de treino por rounds, incluindo checkpoints e fallback automático para a simulação local quando Flower não está disponível (src/federation.py, src/runtime.py).
• Pipeline de dados com geração de janelas, normalização, construção de adjacência para modelos baseados em grafos e cache reutilizável entre experimentos com a mesma configuração (src/data_pipeline.py).
• Modelos e baselines que cobrem RNNs, Transformers, MLPs, variantes baseadas em grafos (GCN temporal) e blocos auxiliares reutilizáveis (src/federation.py, src/baselines.py, src/codificadores.py).
• Métricas, avaliação e relatórios integrados com comparações entre variantes, métricas de justiça/comunicação e orçamento de privacidade aproximado (src/metrics.py, src/evaluation.py, src/reporting.py, src/analysis.py).
• Validação de configuração, versionamento de datasets e rastreamento opcional em MLflow/JSON (src/config_loader.py, src/schema_validation.py, src/versioning.py, src/tracking.py).
• Testes abrangentes para componentes de federação, pipeline e relatórios (tests/).

Diagramas e descrições arquiteturais estão em docs/.

Instalação

Pré-requisitos: Python 3.x e (opcional) CUDA.

# clone
git clone <este-repo>.git
cd <este-repo>

# com Poetry (recomendado)
poetry install

# ou com pip
python -m venv .venv && source .venv/bin/activate  # (Linux/macOS)
# .venv\Scripts\activate                           # (Windows)
pip install -r requirements.txt  # gerado via `poetry export --without-hashes --with dev`

Estrutura de pastas (essencial para navegar e modificar)

src/
  analysis.py
  baselines.py
  codificadores.py
  config_loader.py
  data_pipeline.py
  evaluation.py
  federation.py
  main.py
  metrics.py
  privacy.py
  reporting.py
  runtime.py
  schema_validation.py
  tracking.py
  versioning.py
configs/
  config.yaml           # único arquivo de configuração com experiment_groups
docs/
  arquitetura_do_software.md
  Descricao_do_artigo_IEEE.md
  Mobility_HFL_VFL_Simulator_architecture.mmd
tests/
  test_federation_components.py
data/
  raw/TaxiBJ21.npy   # exemplo de dado cru

Como executar (mínimo viável)

1. Configure o experimento em configs/config.yaml. O arquivo concentra todos os cenários em experiment_groups: benchmark (variações completas com múltiplos agregadores) e quickstart (cenários leves para smoke tests). Ajuste global.execution para escolher o device (cpu, cuda, mps ou auto), habilitar cache, checkpoints e paralelismo. Para rodar apenas um subconjunto, duplique o YAML e mantenha somente o(s) grupos desejados.
2. Execute o runner:

# com Poetry
poetry run python -m src.main --config configs/config.yaml

# ou sem Poetry
python -m src.main --config configs/config.yaml

Execução via Docker

O Dockerfile usa Python 3.11 e instala todas as dependências listadas em requirements.txt (incluindo Flower). Para construir e rodar:

docker build -t fl-traffic .
docker run --rm -v $(pwd)/artifacts:/app/artifacts fl-traffic \
  python -m src.main --config configs/config.yaml

No contêiner, global.execution.engine: auto utilizará Flower quando disponível e retornará automaticamente ao modo local caso a biblioteca falhe. Fora do Docker, basta manter a chave como local ou auto; o código detecta a ausência de Flower e exibe um aviso antes de continuar em modo local.

Saídas típicas:

• Logs de progresso por rodada/cliente com custos de comunicação reais, dispersão de perdas e estatísticas de privacidade.
• Artefatos de avaliação (métricas agregadas), relatórios consolidados por variante e exportação automática de comparações (tabelas/gráficos) gerados por src/evaluation.py e src/reporting.py.
• Checagens de esquema, versão do experimento e checkpoints opcionais para retomada (src/schema_validation.py, src/versioning.py, src/federation.py).

Como os dados são preparados e particionados

O arquivo src/data_pipeline.py centraliza:

• Leitura dos datasets suportados;
• Normalização/escala e janelas temporais;
• Particionamento em clientes (para simular FL) e reconstrução do grafo de sensores (normalização e persistência da matriz de adjacência) reutilizada por arquiteturas GNN e pelo fluxo VFL.

Para regenerar partições/dados processados de acordo com seu config.yaml, reexecute o comando acima após ajustar as chaves de dados e partições. O pipeline refaz automaticamente as janelas e splits quando o arquivo YAML muda e, quando global.execution.data_cache.enabled está ativo, reutiliza resultados em memória para cenários idênticos.

Dica: mantenha hashes e seeds dentro do YAML para reprodutibilidade. O projeto já possui validação de esquema em src/schema_validation.py.

Ciclo de federação (o que acontece de fato)

A lógica de rounds/seleção de clientes/agregação ocorre em:

• src/federation.py: define componentes de federação, incluindo agregação de pesos/gradientes com FedAvg, FedProx, FedOpt (FedAdam/FedYogi/FedAdagrad), FedDyn, SCAFFOLD, FedNova e RFA, além de checkpoints e métricas de comunicação/justiça.
• src/runtime.py: orquestra a execução (ordem das etapas, hooks, seleção de device, checkpoints e paralelismo).

Para alterar o comportamento de seleção de clientes, agregação ou número de rounds, modifique o YAML e/ou os métodos em src/federation.py.

Modos de federação suportados

• HFL (Horizontal FL): aplica run_hfl com agregadores como FedAvg, FedProx, FedNova, RFA, FedDyn, SCAFFOLD e FedOpt (FedAdam/FedYogi/FedAdagrad). Os clientes são construídos por _build_hfl_clients, respeitando distribuição iid, non_iid ou dirichlet definida no YAML e parâmetros como participation_rate, dropout probabilístico, simulação de stragglers e secure aggregation.
• VFL (Vertical FL): cada parte treina um codificador local, compartilhando embeddings para um cabeçalho comum em run_vfl; a preparação aloca colunas por parties, garantindo que ao menos uma possua holds_labels: true para gerar o vetor alvo.
• Modo híbrido: combina HFL para grupos horizontais e VFL para partes verticais no mesmo dataset. _prepare_hybrid monta clusters de clientes por horizontal_groups, enquanto run_hybrid sincroniza o resultado HFL com o treinamento vertical subsequente para compor o estado final do modelo, incluindo repasse da adjacência e personalização opcional.

Métricas e avaliação

• src/metrics.py implementa métricas como MAE, RMSE, MAPE e R², além de funções de dispersão interclientes e testes estatísticos para comparar variantes.
• src/evaluation.py executa a avaliação padronizada após o treino, salvando indicadores e, quando configurado, comparativos entre cenários e amostras de incerteza via MC-dropout.
• src/reporting.py e src/analysis.py geram tabelas e gráficos consolidados, incluindo métricas de justiça pré/pós-personalização, estatísticas de comunicação (bytes por rodada), estimativas de orçamento de privacidade (quando DP está ativo) e relatório agregado de variantes.

Para rodar apenas a avaliação (por exemplo, a partir de pesos salvos), importe as funções em src/evaluation.py e src/reporting.py em um notebook/script e utilize reconstruct_model + generate_reports com os artefatos desejados.

Como modificar: extensões comuns (com ponteiros de arquivo)

• Adicionar/alterar um baseline: edite src/baselines.py.
• Criar nova arquitetura: cadastre o identificador em src/config_loader.py e implemente o caso correspondente em _build_model (há instruções no docstring explicando como usar adjacência e hiperparâmetros extras).
• Criar novo codificador/transformação: src/codificadores.py.
• Incluir/ajustar métrica: src/metrics.py (e registre em src/evaluation.py).
• Nova estratégia de federação: src/federation.py (adicione classe/método e exponha no config.yaml).
• Rastrear informações extras durante o treino: src/tracking.py.

Sempre alinhe o YAML com src/schema_validation.py para que a validação capture erros cedo.

Testes

Há testes para componentes de federação em tests/test_federation_components.py. Execute:

pytest --cov=src

Mantenha novos recursos acompanhados por testes mínimos (ex.: seleção de clientes, agregação, métricas regressando valores esperados).

Documentação complementar

• Arquitetura de software: docs/arquitetura_do_software.md
• Descrição associada ao artigo IEEE: docs/Descricao_do_artigo_IEEE.md
• Diagrama Mermaid (HFL/VFL): docs/Mobility_HFL_VFL_Simulator_architecture.mmd

Datasets incluídos

• metr_la – série de velocidades para sensores rodoviários de Los Angeles, com frequência de 5 minutos, janelas para cinco segmentos e previsão da via 767542. Metadata inclui limites de congestionamento, comprimento médio e velocidade de livre fluxo, úteis para métricas de mobilidade.
• sunt_boardings – embarques diários no sistema de ônibus de Salvador com atributos diferenciais (order, diff_nb) e alvo dif_boarding. A configuração marca o modo de transporte, velocidade média e estrutura viária, reutilizadas em relatórios de desempenho operacional.
• taxi_beijing – cubo temporal de fluxo de táxis na malha de Beijing, com agregados (grid_mean, grid_sum, grid_max, grid_min) por hora e alvo target_flow. As propriedades de malha e congestionamento orientam análises de resiliência em cenários com straggler_simulation.