Modelos de propagação — matriz auditável

Escopo. Esta página descreve, com fidelidade ao código fonte, os modelos de propagação RF efetivamente em produção no TELECOM-TOWER-POWER (TTP), a seleção entre eles, os limites de cada um e o estado atual de cada caminho. Substitui qualquer documento anterior que descreva o TTP como tendo um único modelo de propagação.

Resumo executivo

O TTP não usa um único modelo de propagação. A engine é selecionada explicitamente pelo campo engine da API (ou promovida automaticamente em modo engine='auto', sob critérios documentados abaixo). As três engines ativas são:

Engine	Método	Dimensionalidade	Tier mínimo	Caminho
fspl	FSPL + zona de Fresnel + knife-edge único (k=4/3)	2D (perfil 1D do terreno + envelope de Fresnel)	Free / Solo	Síncrono
p1812	ITU-R P.1812-7 (via Py1812, multi-knife-edge / Deygout)	2D (perfil 1D do terreno, regimes ITU-R)	Pro / Business	Síncrono
sionna_rt	Sionna RT — ray-tracing volumétrico (reflexão, difração UTD, espalhamento, materiais ITU-R P.2040)	3D real (cena Mitsuba: terreno + edificações + clutter)	Enterprise / Ultra	Assíncrono (AWS Batch GPU)

A engine fspl é o padrão quando o cliente não escolhe explicitamente e quando os pré-requisitos das engines superiores não estão presentes (cena 3D, tier, GPU). Ela continua ativa por desenho — é o caminho de baixo custo para previews e o fallback determinístico quando P.1812 ou Sionna RT estão indisponíveis.

Seleção da engine

A API expõe o campo engine em /coverage/predict e /coverage/interference. Valores aceitos:

• fspl — força a engine FSPL/Fresnel 2D.
• itm / itmlogic — NTIA Longley-Rice (Irregular Terrain Model) v1.2.2 via itmlogic. Modo ponto (point mode); cobertura em grid via ITM está no roadmap.
• p1812 — força ITU-R P.1812.
• sionna_rt / sionna-rt — força ray-tracing 3D. Exige bbox e scene_s3_uri (s3:// para o bundle Mitsuba da cena).
• auto — promove para sionna_rt automaticamente quando o tier é Enterprise/Ultra e bbox + scene_s3_uri estão presentes. Caso contrário cai em fspl (preview) ou p1812 (Pro+).

Validação no código: telecom_tower_power_api.py descreve textualmente: "ENTERPRISE / ULTRA tiers are promoted automatically when both bbox and scene_s3_uri are supplied with engine='auto'". Sem scene_s3_uri, não há ray-tracing.

Engine 1 — FSPL + Fresnel 2D + knife-edge único

Implementação. worker.py, sqs_lambda_worker.py e pdf_generator.py.

Fórmulas.

• Perda em espaço livre: $L_{\text{FSPL}} = 20\log_{10}(d) + 20\log_{10}(f) - 147{,}55$ dB.
• Raio da primeira zona de Fresnel ao longo do perfil: $r_n = \sqrt{\dfrac{n \lambda d_1 d_2}{d_1 + d_2}}$, com $n=1$.
• Bulge da Terra com fator $k = 4/3$ ($R_{\text{eff}} = 6371 \cdot k$ km).
• Single knife-edge: a clearance é avaliada pelo ponto de maior intrusão do terreno no envelope de Fresnel ao longo do perfil 1D.

Para que serve. Preview rápido, geração do PDF padrão, fallback determinístico. Não é o modelo recomendado para decisão de projeto onde existir terreno acidentado, múltiplos obstáculos ou clutter denso.

Limites declarados (auditáveis).

• Não captura múltiplos obstáculos sucessivos (single knife-edge).
• Não captura reflexões nem espalhamento.
• Não captura materiais (ITU-R P.2040) nem perdas por clutter urbano.
• Envelope de Fresnel calculado em 1D ao longo do azimute do enlace; não é ellipsoide 3D.

Engine 2 — ITU-R P.1812 (multi-knife-edge / Deygout)

Implementação. itu_p1812.py — wrapper sobre o pacote Py1812 (eeveetza/Py1812), conformante à Recomendação ITU-R P.1812-7. Mapas digitais N050.TXT / DN50.TXT provisionados por boot a partir de S3 (licença ITU não permite redistribuição).

O que P.1812 cobre que a engine FSPL não cobre.

• Difração multi-knife-edge (Deygout) sobre o perfil real.
• Refração troposférica com gradiente $\Delta N$ regional (mapa N050).
• Dispersão troposférica de longo alcance.
• Zonas radiometeorológicas (Inland / Coastal Land / Sea) por chamada.
• Polarização horizontal/vertical e percentis de tempo/localização.
• Cache: in-process LRU(2048) → Redis 7 d TTL, indexado pelo hash do perfil + parâmetros (≈ 30–80 ms por chamada não-cacheada).

Limites declarados.

• Continua sendo cálculo sobre perfil 1D (a recomendação é inerentemente baseada em perfil). Não substitui ray-tracing 3D para geometrias urbanas densas em mmWave.
• Requer cobertura por mapas digitais ITU; fora da grade cai para interpolação degradada.

Engine 3 — Sionna RT (ray-tracing 3D)

Implementação. rf_engines/sionna_rt_engine.py, handler de interferência em rf_engines/interference_engine.py, worker GPU em batch_gpu_interference_worker.py.

O que faz.

• Ray-tracing volumétrico em cena Mitsuba (terreno + edificações + clutter), GPU NVIDIA via Docker Dockerfile.gpu.
• Reflexão especular, difração UTD (Uniform Theory of Diffraction), espalhamento difuso.
• Materiais por ITU-R P.2040 (concreto, vidro, vegetação, metal etc.).
• Suporte mmWave (frequências altas onde a geometria 3D domina).
• Validado contra drive-tests reais (ver Validação do modelo e o validador interno scripts/coverage_diff_*).

Restrições operacionais.

• Opt-in explícito. Não é a engine default. Tier mínimo: Enterprise / Ultra. Auto-promoção só com bbox + scene_s3_uri.
• Assíncrono. O endpoint responde HTTP 202 + job_id; o cálculo roda em AWS Batch GPU. Cliente faz polling em /coverage/jobs/{id}.
• Custo / latência. Ordens de magnitude superiores às engines 1 e 2 (minutos a dezenas de minutos por cena, vs. dezenas de ms para FSPL e P.1812).

Sionna ML (engine secundária, atualmente bloqueada)

Existe uma engine sionna adicional baseada em modelo ML treinado (features extraídas do perfil + clutter, TFLite servido em ECS). Status atual:

• Artefato v2 atual: s3://telecom-tower-power-results/models/sionna/current/ (feature_dim=30, schema_version=v2).
• Guard-rail ativo em produção. rf_engines/sionna_engine.py::_load() recusa registrar o modelo quando o sidecar declara synthetic_only=True, ou quando training_rows < SIONNA_MIN_TRAINING_ROWS (default 500).
• Efeito hoje: o artefato v2 atual foi treinado 100% em dados sintéticos (imitação de P.1812). O guard-rail trip, a engine sionna fica invisível em /coverage/engines e /coverage/engines/compare, e o registry faz fallback automático para P.1812.
• Liberação automática quando o re-treino Fase-2 produzir ≥500 linhas reais de link_observations e synthetic_only=false no sidecar.

Esta engine não é apresentada ao cliente como ativa enquanto o guard-rail estiver acionado.

O que a auditoria de propagação geralmente alega — e a resposta

"Fresnel/knife-edge simplificado (não 3D)."

Procedente apenas para a engine fspl. É deliberado: ela existe como modelo de baixo custo para preview, PDF padrão e fallback. As decisões operacionais em Pro+ usam P.1812 (multi-knife-edge Deygout, regulatório ITU-R) ou Sionna RT 3D (ray-tracing volumétrico com materiais P.2040). A seleção é explícita no campo engine da API e auditável nos logs da request (/coverage/predict registra engine_used na resposta).

"O PDF mostra apenas Fresnel 2D mesmo quando a engine 3D foi usada."

Procedente. O gráfico em pdf_generator.py é, por desenho, uma projeção 2D do perfil terreno + envelope de Fresnel. Ele é uma representação ilustrativa do enlace, não o resultado numérico. O valor numérico de perda total no PDF (signal_dbm, fresnel_clearance) provém da engine selecionada. A partir desta revisão, o título do plot e a legenda do PDF deixam isso explícito: "Projeção 2D ilustrativa — valores numéricos provêm da engine <X>".

Evidência reproduzível

• Engines registradas em runtime: GET /coverage/engines retorna a lista efetivamente carregada (fspl sempre presente; p1812 se mapas ITU disponíveis; sionna_rt se bundle GPU acessível; sionna ML somente se guard-rail liberar).
• Comparação lado-a-lado: POST /coverage/engines/compare executa o mesmo cenário em todas as engines disponíveis e retorna a tabela de resultados. Usado pelos clientes Enterprise como evidência interna de modelo.
• Validação contra drive-test: ver Validação do modelo.

Histórico de mudanças relevantes

• 2026-05-11 — Promoção Sionna v2 (SIONNA_FEATURES_VERSION=v2, feature_dim=30). Guard-rail real-data introduzido (commit 23ac54b, ECS rev 145): artefato v2 atual fica bloqueado por ser sintético; engine sionna ML invisível até re-treino com ≥500 linhas reais.
• Maio/2026 — Sionna RT 3D em AWS Batch GPU promovido a engine pública para tiers Enterprise/Ultra com scene_s3_uri. FSPL/P.1812 mantidos como engines anteriores; nenhum modelo foi removido.