physbound

PhysBound é um "Linter de Física" especializado para IA que valida deterministicamente afirmações de RF e termodinâmicas contra limites físicos rigorosos, prevenindo alucinações em fluxos de trabalho de engenharia.

GitHub
2

Documentação

PhysBound

PhysBound

Physical Layer Linter — um servidor MCP que valida cálculos de RF e física contra limites físicos rígidos, detectando alucinações de IA em fluxos de trabalho de engenharia.

CI codecov PyPI MCP Registry License: MIT Python 3.12+ MCP Badge Ko-fi

PhysBound CLI catching a Shannon-Hartley violation

LLMs geram números de RF que parecem plausíveis, mas violam a física fundamental — vazão acima do limite de Shannon, ganhos de antena que nenhuma abertura pode produzir, alcances de radar que a equação de alcance proíbe. O PhysBound oferece a qualquer assistente de IA compatível com MCP seis ferramentas de cálculo validadas, respaldadas por constantes CODATA (via SciPy) e análise dimensional (via Pint). Reivindicações impossíveis retornam respostas estruturadas PhysicalViolationError com a lei violada, o limite calculado e uma explicação em LaTeX — não falhas silenciosas.

FerramentaO que valida
rf_link_budgetOrçamentos de link de Friis: FSPL, potência recebida, ganhos de antena vs. limites de abertura/Harrington
shannon_hartleyReivindicações de vazão contra a capacidade do canal C = B log2(1 + SNR)
noise_floorRuído térmico kTB, cascatas de figura de ruído de Friis, sensibilidade do receptor
radar_rangeReivindicações de alcance de detecção contra a equação de alcance do radar monostático
antenna_gainLimites de ganho, largura de feixe e distância de campo distante para uma única antena
radar_ambiguityAlcance/velocidade inequívocos de pulso-Doppler, aliasing Doppler, resolução de alcance

Instalação

O PhysBound é um servidor MCP stdio padrão publicado no PyPI. O comando de inicialização recomendado é uvx physbound, que busca e executa a versão mais recente em um ambiente isolado — sem etapa de instalação manual.

Primeira execução: uvx baixa ~60 MB de dependências (SciPy, NumPy) na primeira vez. Execute uvx physbound uma vez em um terminal para pré-cacheá-las (Ctrl-C para sair); as inicializações subsequentes são instantâneas.

Claude Code

claude mcp add physbound -- uvx physbound

Claude Desktop

Adicione a claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "physbound": {
      "command": "uvx",
      "args": ["physbound"]
    }
  }
}

Cursor, Windsurf e outros clientes MCP

Use a mesma entrada JSON de servidor acima no arquivo de configuração MCP do seu cliente (Cursor: ~/.cursor/mcp.json; Windsurf: ~/.codeium/windsurf/mcp_config.json).

Sem uv

Se você preferir uma instalação Python simples (requer Python 3.12+):

pip install physbound

depois defina "command": "physbound" (sem args) na configuração do cliente.

Uma vez configurado, pergunte ao seu assistente uma questão de RF — "Um canal de 20 MHz com SNR de 15 dB suporta 500 Mbps?" — e ele responderá com números validados pela física.

Uso via Linha de Comando

Os mesmos validadores estão disponíveis diretamente no terminal — úteis em scripts e pipelines de CI, já que uma violação de física sai com código 1:

$ physbound check shannon --bandwidth-hz 20e6 --snr-db 15 --claimed-throughput-bps 500e6
PHYSICS VIOLATION [Shannon-Hartley Theorem]
  Claimed throughput 500000000.0 bps exceeds Shannon limit of 100556153.5 bps by 397.2%
  Computed limit: 1.00556e+08 bps
  Claimed value:  5e+08 bps
$ echo $?
1

$ physbound check shannon --bandwidth-hz 20e6 --snr-db 15 --claimed-throughput-bps 100e6
Shannon-Hartley Capacity: ...   # exit code 0

Subcomandos disponíveis: check {link-budget, shannon, noise, radar-range, antenna, radar-ambiguity} (as flags espelham os parâmetros da ferramenta MCP; adicione --json para o resultado estruturado completo) e serve --transport {stdio,http} para executar o servidor MCP via HTTP. Veja physbound check --help para detalhes.

O Que os LLMs Erram

Dezesseis padrões reais de alucinação, cada um capturado pela suíte de testes do PhysBound:

#CategoriaAlucinação do LLMVerdade do PhysBoundVeredito
1Shannon-HartleyUm canal 802.11n de 20 MHz com SNR de 15 dB pode atingir 500 MbpsLimite de Shannon: 100,6 Mbps (não 500 Mbps)PEGO
2Shannon-HartleyUm canal 5G de 100 MHz com SNR de 20 dB entrega 2 GbpsLimite de Shannon: 665,8 Mbps (não 2000 Mbps)PEGO
3Abertura de AntenaUma antena parabólica de 30 cm a 1 GHz fornece 45 dBi de ganhoLimite físico: 12,1 dBi (Harrington); abertura eta=1: 9,9 dBi; parabólica típica: 7,4 dBi (eta=0,55) (não 45 dBi)PEGO
4Ruído TérmicoPiso de ruído do receptor de -180 dBm/Hz à temperatura ambientePiso de ruído térmico: -174,0 dBm/Hz a 290K (não -180 dBm/Hz)PEGO
5Orçamento de Link / FSPLWi-Fi a 2,4 GHz com TX de 20 dBm alcança 10 km com potência RX de -40 dBmPotência RX real a 10 km: -94,1 dBm (não -40 dBm)PEGO
6Orçamento de Link / FSPLUm transmissor de 1W a 12 GHz com antenas de 0 dBi alcança GEO a -80 dBmPotência RX real em GEO: -175,1 dBm (não -80 dBm)PEGO
7Orçamento de Link / FSPLBluetooth a 2,4 GHz com TX de 0 dBm e antenas de 0 dBi alcança 1 km a -60 dBmPotência RX real a 1 km: -100,1 dBm (não -60 dBm)PEGO
8Shannon-HartleyUm canal LTE de 10 MHz com SNR de 10 dB suporta 1 GbpsLimite de Shannon: 34,6 Mbps (não 1000 Mbps)PEGO
9Cascata de RuídoA NF do receptor é a mesma independentemente da ordem dos estágios: LNA(20dB/1,5dB) + Mixer(10dB/8dB)LNA primeiro: 1,66 dB vs mixer primeiro: 8,03 dB (penalidade: 6,4 dB)PEGO
10Abertura de AntenaUma antena patch de 10 cm a 900 MHz fornece 20 dBi de ganhoLimite físico: 4,4 dBi (Harrington, D < lambda); abertura eta=1: -0,5 dBi; típica: -3,1 dBi (eta=0,55) (não 20 dBi)PEGO
11Equação de Alcance do RadarDobrar a potência do transmissor dobra o alcance de detecção do radarO alcance aumenta por um fator de 1,189 (2^(1/4) = 1,189), não 2,0PEGO
12Equação de Alcance do RadarDrone pequeno (RCS de 0,01 m^2) detectável a 200 km por radar de banda X de 1 kW com ganho de 30 dBiAlcance máximo: 2,7 km para RCS de 0,01 m^2 a 1 kW em banda X (não 200 km)PEGO
13Ganho de AntenaUma antena parabólica de terminal de usuário de 0,5 m a 12 GHz dá 50 dBi de ganhoLimite físico: 36,1 dBi (Harrington); parabólica típica: 33,4 dBi (eta=0,55) (não 50 dBi)PEGO
14Ganho de AntenaUma antena parabólica de 3 m a 10 GHz está em campo distante a 10 m, então o ganho pode ser medido láDistância de campo distante 2D^2/lambda = 600 m; 10 m está em campo próximoPEGO
15Ambiguidade de RadarUm radar de 10 GHz com PRF de 10 kHz mede inequivocamente 500 m/sv_ua = lambda*PRF/4 = +/-74,9 m/s (velocidade cega 149,9 m/s); 500 m/s sofre aliasing (não 500 m/s)PEGO
16Ambiguidade de RadarUm radar de pulso-Doppler de 10 GHz pode cobrir inequivocamente 150 km e +/-300 m/s ao mesmo tempoR_uav_ua = clambda/8 = 1,123e+06 m^2/s para qualquer PRF; reivindicado 4,5e+07 m^2/s (40x maior)PEGO

Gerado automaticamente por pytest tests/test_marketing.py -s

Ferramentas

Derivações completas, fontes e exemplos trabalhados para cada fórmula estão em docs/formulas.md.

rf_link_budget

Calcula um orçamento de link de RF completo usando a equação de transmissão de Friis e valida ganhos de antena contra limites físicos.

Exemplo: "Qual é a potência recebida para um link de 2,4 GHz a 100 m com TX de 20 dBm, ganho TX de 10 dBi, ganho RX de 3 dBi?"

Retorna FSPL, potência recebida, comprimento de onda e — quando diâmetros de antena são fornecidos — verificações de limite de ganho. Ganhos acima do limite rígido G_max = max((pi D / lambda)^2, (ka)^2 + 2ka) (o valor de abertura eta = 1, ou o limite de Harrington para antenas eletricamente pequenas) são rejeitados; ganhos acima do valor típico de parabólica (eta = 0,55) são aceitos com um aviso. Também avisa dentro da distância de campo distante 2D^2/lambda e rejeita perdas negativas.

shannon_hartley

Calcula a capacidade do canal de Shannon-Hartley C = B log2(1 + SNR) e valida reivindicações de vazão.

Exemplo: "Um canal de 20 MHz com SNR de 15 dB pode suportar 500 Mbps?"

Retorna capacidade teórica, eficiência espectral e se a reivindicação é fisicamente possível, incluindo a porcentagem exata pela qual uma reivindicação violadora excede o limite de Shannon.

noise_floor

Calcula a potência de ruído térmico N = k_B T B, cascateia figuras de ruído através de receptores de múltiplos estágios com a fórmula de ruído de Friis e calcula a sensibilidade do receptor.

Exemplo: "Qual é o piso de ruído para um receptor de 1 MHz a 290 K com uma cadeia LNA de dois estágios?"

Retorna ruído térmico em dBm e watts, figura de ruído em cascata, temperatura efetiva de ruído de entrada T_e = 290 K * (F - 1) e sensibilidade do receptor.

radar_range

Calcula a equação de alcance do radar monostático R_max = [P_t G^2 lambda^2 sigma / ((4pi)^3 S_min L)]^(1/4) e valida reivindicações de alcance de detecção.

Exemplo: "Um radar de banda X de 1 kW com ganho de 30 dBi pode detectar um drone de 0,01 m^2 a 200 km?"

Retorna alcance máximo de detecção, sinal mínimo detectável, comprimento de onda e valores intermediários. Captura a falácia comum da raiz quarta de que dobrar a potência dobra o alcance.

antenna_gain

Analisa uma única antena a partir de seu diâmetro ou área física: limites de ganho, largura de feixe e distância de campo distante, com validação opcional de um ganho reivindicado.

Exemplo: "Uma antena parabólica de 0,5 m a 12 GHz pode realmente dar 50 dBi? Qual largura de feixe devo esperar?"

Retorna o limite físico de ganho (limite de abertura ou Harrington, e qual governa), ganho típico na eficiência dada (padrão 0,55), abertura efetiva, estimativas de largura de feixe de meia potência, distância de campo distante 2D^2/lambda e — para um ganho reivindicado — a eficiência de abertura implícita e validade.

radar_ambiguity

Calcula limites de ambiguidade de pulso-Doppler para uma frequência de portadora e PRF dadas.

Exemplo: "Um radar de 10 GHz com PRF de 10 kHz pode medir inequivocamente um alvo a 500 m/s até 150 km?"

Retorna alcance inequívoco R_ua = c / (2 PRF), velocidade inequívoca v_ua = lambda PRF / 4, velocidade cega, deslocamento Doppler e velocidade aparente (com aliasing), resolução de alcance (c tau / 2, ou c / 2B com compressão de pulso), alcance mínimo, ciclo de trabalho e o invariante do dilema alcance-Doppler R_ua v_ua = c lambda / 8. Rejeita reivindicações de alcance, velocidade ou resolução que a PRF ou o pulso não podem suportar.

Garantias de Física

Cada cálculo é validado contra limites físicos rígidos:

  • Velocidade da luz: c = 299,792,458 m/s — sem exceções
  • Piso de ruído térmico: N = -174 dBm/Hz a 290 K — a referência padrão IEEE
  • Limite de Shannon: C = B log2(1 + SNR) — nenhuma reivindicação de vazão excede isso
  • Limite de ganho de antena: G_max = max((pi D / lambda)^2, (ka)^2 + 2ka) — o valor de abertura eta = 1 para aberturas planas e o limite de Harrington para qualquer antena em uma esfera de diâmetro D; eta = 0,55 é um limite de aviso, não um limite
  • Equação de alcance do radar: R_max = [P_t G^2 lambda^2 sigma / ((4pi)^3 S_min)]^(1/4) — o alcance obedece à lei da raiz quarta
  • Sensibilidade do receptor: S_min = k (T_A + T_0 (F - 1)) B * SNR com T_e = T_0 (F - 1) referenciado a 290 K
  • Alcance inequívoco: R_ua = c / (2 PRF) — ecos além dele se dobram em um intervalo de pulso posterior
  • Velocidade inequívoca: v_ua = lambda PRF / 4 — o Doppler é amostrado na PRF, então |f_d| <= PRF/2
  • Dilema alcance-Doppler: R_ua * v_ua = c lambda / 8 — nenhuma escolha de PRF supera isso para uma dada portadora

Violações retornam respostas estruturadas PhysicalViolationError com explicações em LaTeX, não falhas silenciosas.

Exemplos e Documentação

Desenvolvimento

Requer uv e Python 3.12+ (CI cobre 3.12–3.14):

# Clone and install
git clone https://github.com/JonesRobM/physbound.git
cd physbound
uv sync --all-extras

# Run checks
uv run pytest tests/ -v
uv run ruff check src/ tests/
uv run mypy src/physbound/

# Regenerate the hallucination table above
uv run pytest tests/test_marketing.py -s

# Start the MCP server locally
uv run physbound

Contribuições que expandam o conjunto de domínios de física validados são bem-vindas — veja CONTRIBUTING.md para o guia de arquitetura e a receita passo a passo para adicionar um novo validador.

Casos de Uso

  • Revisão de projeto de sistema de RF — valide orçamentos de link, sensibilidade do receptor e cascatas de ruído
  • Avaliação de propostas de telecomunicações — identifique alegações impossíveis de throughput antes que cheguem ao cliente
  • Dimensionamento de sistemas de radar — verifique alcance de detecção, seleção de PRF e compensações de ambiguidade
  • Ferramentas educacionais — ensine Shannon-Hartley, transmissão de Friis e ruído térmico com cálculos verificados
  • CI/CD para física — integre como etapa de validação em pipelines de engenharia

Suporte

Se o PhysBound for útil no seu trabalho, considere me pagar um café.

Licença

Licença MIT. Consulte LICENSE.

Relacionados