Arquitectura del sistema

Flujo de datos desde Overpass/TomTom hasta el dashboard

Principio de diseño

El sistema sigue una arquitectura de un escritor, múltiples lectores. El DAG de Airflow es el único proceso que escribe tango_state.json. FastAPI lo sirve como API REST, y tanGo_dashboard.html es el consumidor principal — centraliza todas las fuentes: intersecciones, métricas, contexto de clima, factor de tráfico TomTom y estado de la simulación. Hace fetch a la API cada 60 segundos de forma autónoma, sin recargar la página.

Streamlit (app.py) es el dashboard del compañero — consume la misma API pero es secundario. Ambos coexisten sin conflicto porque solo leen.

Stack tecnológico

Python 3.11 · WSL2 Debian · i3-11va · 20GB RAM

Tecnologías principales

Estructura del proyecto

36.TanGo/
├── core/              # Motor del algoritmo — independiente de UI
│   ├── algorithm.py   # TrafficAlgorithm (3 pasos)
│   ├── movement.py    # MovementEngine — Dijkstra + velocidades
│   ├── road.py        # Intersection, Phase, RoadSegment
│   ├── entities.py    # Vehicle, Pedestrian, VehicleType
│   ├── context.py     # TrafficContext (hora, clima, tráfico)
│   └── weight_engine.py  # Presión, ola verde, pesos
├── graph/
│   ├── city_graph.json   # 354 nodos, 672 aristas — GDL centro
│   ├── tango_state.json  # Estado horario generado por DAG
│   └── city_loader.py    # Overpass → JSON + pesos estáticos
├── dags/
│   └── tango_queries_dag.py  # Pipeline @hourly
├── dashboard/
│   ├── api.py        # FastAPI :8000
│   ├── app.py        # Streamlit :8501
│   └── tanGo_dashboard.html
├── tests/
│   ├── sim0/ sim1/ sim2/  # Evolución del simulador
│   └── sim3/
│       ├── tango_env.py   # TanGoEnv (gymnasium)
│       ├── train.py
│       ├── evaluate.py
│       └── tango_sim3.py  # Visualización PPO
└── docker/
    ├── Dockerfile.api / .airflow / .dashboard
    └── docker-compose.yml

El algoritmo

Tres pasos secuenciales por tick · Inspirado en SCOOT + coordinación vecinal

El corazón de tanGo es TrafficAlgorithm.run_tick(). Con cada llamada, el sistema ejecuta tres pasos secuenciales que transforman el estado de las entidades en la red en decisiones de fase para cada semáforo.

Paso 1 — Presión propia

WeightEngine.aggregate_pressure() · Función pura

La presión de una intersección es una medida escalar de cuánta urgencia existe para dar el verde. Se calcula únicamente a partir de las entidades presentes — sin considerar vecinos ni historial.

Factores de presión

Propiedad clave: statelesness

# Ejemplo simplificado de cálculo de presión
def aggregate_pressure(entities, inter, ctx):
    base = 0.0
    for e in entities:
        w = VEHICLE_WEIGHTS.get(e.vehicle_type, 1.0)
        base += w
    # Modificadores de contexto
    if ctx.is_rush_hour:  base *= 1.4
    if ctx.is_raining:    base *= 1.2
    # Amplificar por importancia del nodo
    return base * inter.node_weight

Paso 2 — Mente colmena

Coordinación vecinal + green wave anticipatoria

El paso más sofisticado del algoritmo. Cada nodo no solo reacciona a su propio tráfico — también escucha a sus vecinos upstream para anticipar el flujo que se aproxima.

Componentes

a) Señal vecinal de presión

La influencia de un vecino decae con la distancia. Un nodo a 50m tiene más influencia que uno a 500m. Los nodos tipo MASTER amplifican su señal ×1.3.

influence = neighbor_pressure / (1 + distance_m / speed_kmh)
combined  += influence * 0.25  # NEIGHBOR_WEIGHT

b) Boost anticipatorio

Si un vecino upstream está en verde pero el flujo aún no llega (offset pendiente), se aplica un boost proporcional a la urgencia — cuanto más cerca está el flujo de llegar, mayor el boost.

urgency    = 1.0 / (1.0 + ticks_remaining * TICK_DURATION_S / 20.0)
wave_boost = neighbor_pressure * urgency
combined  += wave_boost * 0.15  # WAVE_BOOST_WEIGHT

c) Ola verde forzada (offset cumplido)

Cuando los ticks transcurridos desde que el vecino se puso en verde superan el offset_ticks (distancia / velocidad / TICK_DURATION_S), el flujo ya debería haber llegado. El nodo se marca _wave_forced=True y en el Paso 3 se fuerza a verde independientemente de la presión local.

Parámetros ajustables (knobs RL)

Paso 3 — Ajuste de fases

Máquina de estados con coordinación de cluster

Máquina de estados

Coordinación de cluster

Cuando dos o más intersecciones están a menos de 60m entre sí (p.ej. un cruce con camellón), forman un cluster de coordinación. Dentro del cluster, solo puede estar en verde una intersección a la vez. El ganador es el de mayor presión combinada.

# Ceder al ganador del cluster
winner_id = max(cluster_members, key=lambda n: pressures[n])
for node_id in cluster_members:
    if node_id != winner_id:
        pressures[node_id] *= 0.3  # CLUSTER_YIELD

Timeout de equidad

Ninguna intersección puede permanecer en rojo indefinidamente. Si un nodo lleva más de red_timeout_ticks en rojo y tiene entidades esperando, su presión se eleva artificialmente para garantizar que eventualmente reciba el verde.

Ola verde SCOOT

Coordinación temporal entre intersecciones · offset = distancia / velocidad

La ola verde es el mecanismo por el que los semáforos se sincronizan para que un vehículo que sale de una intersección en verde llegue a la siguiente cuando esta también esté en verde, sin necesidad de detenerse.

Cálculo del offset

# WeightEngine.compute_green_wave_offset()
offset_s = distance_m / (speed_kmh / 3.6)
# Convertir a ticks (1 tick ≈ 30s simulados)
offset_ticks = max(1, round(offset_s / TICK_DURATION_S))

Ejemplo en Guadalajara

Avenida Federalismo entre dos intersecciones separadas 350m, límite de velocidad 50km/h:

offset_s     = 350 / (50 / 3.6) = 25.2 segundos
offset_ticks = round(25.2 / 30) = 1 tick

Si la intersección upstream se pone en verde en el tick 5, la downstream debe ponerse en verde en el tick 6 — el flujo ya llegó.

Entidades y contexto

Los actores de la simulación

Tipos de entidades

TrafficContext

El contexto encapsula las condiciones del mundo real para un tick específico. En producción, se construye con datos reales de Open-Meteo y TomTom.

Pesos estáticos

5 dimensiones combinadas en media geométrica · calculados una vez por día

El node_weight de cada intersección cuantifica su importancia estructural en la red vial. Un nodo con peso alto amplifica su presión propia y la señal que envía a sus vecinos.

Las 5 dimensiones

# Media geométrica de las 5 dimensiones (α=β=γ=δ=ε=1)
node_weight = (degree_w * betweenness_w * pagerank_w
               * road_quality * itype_bonus) ** (1/5)

Evolución sim0 → sim3

Cuatro generaciones del simulador, cada una más sofisticada

sim0 — Timers fijos

Baseline · Todos los semáforos en verde permanente

El baseline más simple posible: todas las intersecciones con semáforo se fijan en verde. No hay lógica de coordinación ni reacción al tráfico. Sirve como referencia inferior.

sim1 — SCOOT greedy

TrafficAlgorithm completo · presión + ola verde

Primera versión del algoritmo completo. Introduce presión por entidades, coordinación vecinal y ola verde. Las entidades son sintéticas (sin rutas reales).

sim2 — Pesos + movimiento

node_weight · MovementEngine · Dijkstra · heatmap

Agrega movimiento real de entidades con rutas calculadas por Dijkstra, pesos estáticos por nodo (betweenness, pagerank, road_quality) y partículas animadas en el mapa.

Casos experimentales

sim3 — Agente PPO

Reinforcement Learning · PPO · 550 episodios · checkpoint_00550

El agente PPO observa 10 features por cada semáforo (presión, fase, entidades, hora, vecinos…) y decide en cada tick si mantener o cambiar la fase de cada semáforo. Entrenado durante ~5 días en CPU.

Espacio de observación (10 features × N_semáforos)

Función de recompensa

reward = w_flow   × (entidades_en_verde / total)
       - w_wait   × (espera_acumulada / (total × n_ticks))
       - w_emerg  × emergencias_detenidas
       + w_arrived × (llegadas_este_tick / total)
# Pesos: w_flow=1.0, w_wait=0.5, w_emerg=5.0, w_arrived=2.0

Resultados comparativos

60 ticks · escenario rush_hour

DAG de Airflow

Pipeline horario · tango_traffic_pipeline · @hourly

Comandos de operación

# Levantar Airflow
source ~/airflow_env/bin/activate
export AIRFLOW_HOME=~/airflow
export AIRFLOW__CORE__DAGS_FOLDER="/mnt/c/.../36.TanGo/dags"
export AIRFLOW__WEBSERVER__WEB_SERVER_PORT=8082
airflow standalone

# Trigger manual
airflow dags trigger tango_traffic_pipeline

# Ver logs de una tarea
airflow tasks logs tango_traffic_pipeline correr_simulacion <run_id>

VisionIngester YOLO

KAN-16 + KAN-17 · YOLOv8n · Kafka · César Adrián Santos Santacruz

YOLO_PID/semaforo_detector.py es la capa de visión por computadora del sistema. Detecta vehículos detenidos en video usando YOLOv8n y publica eventos a Kafka cuando un vehículo lleva más de 2 segundos quieto, sugiriendo un cambio a verde en el semáforo correspondiente.

Clases detectadas

Parámetros clave

Evento Kafka emitido

{
  "evento":     "objeto_quieto",
  "objeto_id":  42,
  "clase":      "car",
  "posicion":   {"x": 320, "y": 240},
  "seg_quieto": 3.5,
  "timestamp":  1715000000.123,
  "accion":     "cambiar_verde"
}

Setup y ejecución

# Windows — setup automático
cd YOLO_PID
setup.bat

# Correr el detector
python semaforo_detector.py

FastAPI :8000

Endpoints REST que consume el dashboard

Correr localmente

source ~/airflow_env/bin/activate
cd "/mnt/c/.../36.TanGo"
uvicorn dashboard.api:app --reload --port 8000

Docker

3 contenedores · 1 volumen compartido · docker compose up

Comandos

# Primera vez (o después de cambiar código)
docker compose up --build

# Demos posteriores (sin reconstruir)
docker compose up

# Apagar
docker compose down

# Trigger manual del DAG dentro de Docker
docker compose exec tango-airflow airflow dags trigger tango_traffic_pipeline

KANs completados

Registro de hitos del proyecto

Trabajo pendiente

En orden de prioridad

Referencias

Fundamentos teóricos de tanGo

Algoritmo de semáforos

SCOOT — Robertson, D.I. & Bretherton, R.D. (1991). Optimizing networks of traffic signals in real time — the SCOOT method. IEEE Transactions on Vehicular Technology, 40(1), 11–15.

FUSION — TRL / Transport for London (2019). FUSION: Multi-source data fusion for urban traffic management. Aplicación de múltiples fuentes de datos en tiempo real para coordinación de semáforos en Londres.

Reinforcement Learning

PPO — Schulman, J., Wolski, F., Dhariwal, P., Radford, A., & Klimov, O. (2017). Proximal Policy Optimization Algorithms. arXiv:1707.06347.

RLlib — Liang, E., et al. (2018). RLlib: Abstractions for Distributed Reinforcement Learning. ICML. Ray 2.55 con api_stack clásica (enable_rl_module_and_learner=False).

Grafo de la ciudad

OpenStreetMap — datos viales de Guadalajara ZMG descargados via Overpass API. Coordenadas de intersecciones, tipos de vía, límites de velocidad y sentido del tráfico.

Betweenness centrality — Freeman, L.C. (1977). A set of measures of centrality based on betweenness. Sociometry, 40(1), 35–41.

PageRank — Page, L., Brin, S., Motwani, R., & Winograd, T. (1999). The PageRank citation ranking: Bringing order to the web. Stanford InfoLab.

Datos en tiempo real

Open-Meteo — API meteorológica de código abierto. Temperatura, precipitación, viento y visibilidad en tiempo real sin API key.

TomTom Traffic API — Datos de velocidades actuales por segmento vial. Requiere API key.

Contacto

tanGo · mayo 2026

Proyecto académico desarrollado en mayo 2026. Hecho con mucho café y algo de paciencia.

                   ##
                  _[]_
                 [____]
             .----'  '----.
         .===|    .==.    |===.
         \   |   /####\   |   /
         /   |   \####/   |   \
         '===|    `""`    |==='
         .===|    .==.    |===.
         \   |   /::::\   |   /
         /   |   \::::/   |   \
         '===|    `""`    |==='
         .===|    .==.    |===.
         \   |   /&&&&\   |   /
         /   |   \&&&&/   |   \
         '===|    `""`    |==='
      jgs    '--.______.--'

⠀⠀⠀⠀⠀⠀⠀⠀⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡾⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⡼⠙⣧⡀⠀⠀⠀⠀⠀⠀⠀⠀⢠⣿⠃⢹⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢰⠃⠀⠘⣿⡄⠀⠀⠀⠀⠀⠀⢀⣿⡇⠀⠘⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⡎⠀⠀⠀⢹⣿⣆⠀⠀⠀⠀⠀⣼⣿⠁⠀⠀⣷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⡇⠀⠀⢀⠞⢻⣿⡆⠀⠀⠀⢰⣿⣿⡀⠀⠀⢹⡄⠀⠀⠀⠀⢀⣤⣤⡄⠀⠀⣀⣤⣤⣀
⠀⠀⠀⠀⠀⠀⡇⠀⢰⠋⠀⠈⣿⣿⡄⠀⠀⣾⣿⡇⠹⡄⠀⢨⡇⠀⠀⠀⢸⣿⣿⣿⣿⣾⣿⣿⣿⣿⡇
⠀⠀⠀⠀⠀⠀⡇⢀⡏⠀⢀⣴⣿⣿⣿⣿⣾⣿⣿⣧⡀⢳⠀⢸⡁⠀⠀⠀⠻⣿⣿⣿⣿⣿⣿⣿⣿⠟⠀
⠀⠀⠀⠀⠀⠀⢣⠸⣅⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣾⡀⣸⠀⠀⠀⠀⠀⠀⠙⠻⣿⣿⡿⠋⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠘⣦⣿⣿⡿⠛⠻⢿⣿⣿⣿⣿⡟⠉⠙⢿⣿⣇⠀⠀⠀⣀⣠⡄⠀⠀⠀⠉⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⣿⣿⡿⠀⠀⣿⡟⣿⣿⣿⣿⢸⣷⠀⠈⣿⣿⣤⠶⠋⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠚⠉⠉⠉⠙⠒⠲⣿⣿⣷⠀⠀⠙⢡⣿⣿⣽⣿⣌⠁⠀⣰⣿⣿⣀⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⢀⣠⠽⢿⣿⣿⣶⣶⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠃⠀⠀⠀⠉⠑⠒⠠⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⣀⠴⠚⠉⠀⠀⠀⠙⠿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠊⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⣿⣿⣿⣿⣿⣿⡍⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢰⣿⣿⣿⣿⣿⣿⣷⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⣿⣿⣿⣿⣿⣿⣿⣿⣷⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀