physbound

PhysBound es un "Linter de Física" especializado para IA que valida de manera determinista afirmaciones de RF y termodinámica contra límites físicos estrictos, previniendo alucinaciones en flujos de trabajo de ingeniería.

GitHub
2

Documentación

PhysBound

PhysBound

Physical Layer Linter — un servidor MCP que valida cálculos de RF y física contra límites físicos estrictos, detectando alucinaciones de IA en flujos de trabajo de ingeniería.

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

PhysBound CLI catching a Shannon-Hartley violation

Los LLM generan cifras de RF que suenan plausibles pero violan la física fundamental: rendimiento por encima del límite de Shannon, ganancias de antena que ninguna apertura puede producir, alcances de radar que la ecuación de alcance prohíbe. PhysBound ofrece a cualquier asistente de IA compatible con MCP seis herramientas de cálculo validadas, respaldadas por constantes CODATA (vía SciPy) y análisis dimensional (vía Pint). Las afirmaciones imposibles devuelven respuestas estructuradas PhysicalViolationError con la ley violada, el límite calculado y una explicación en LaTeX, no fallos silenciosos.

HerramientaQué valida
rf_link_budgetPresupuestos de enlace de Friis: FSPL, potencia recibida, ganancias de antena frente a límites de apertura/Harrington
shannon_hartleyAfirmaciones de rendimiento frente a la capacidad del canal C = B log2(1 + SNR)
noise_floorRuido térmico kTB, cascadas de figura de ruido de Friis, sensibilidad del receptor
radar_rangeAfirmaciones de alcance de detección frente a la ecuación de alcance del radar monoestático
antenna_gainLímites de ganancia, ancho de haz y distancia de campo lejano para una antena individual
radar_ambiguityAlcance/velocidad inequívocos de pulso-Doppler, aliasing Doppler, resolución de alcance

Instalación

PhysBound es un servidor MCP estándar de stdio publicado en PyPI. El comando de lanzamiento recomendado es uvx physbound, que descarga y ejecuta la última versión en un entorno aislado, sin necesidad de instalación manual.

Primera ejecución: uvx descarga ~60 MB de dependencias (SciPy, NumPy) la primera vez. Ejecuta uvx physbound una vez en una terminal para precargarlas (Ctrl-C para salir); los inicios posteriores son instantáneos.

Claude Code

claude mcp add physbound -- uvx physbound

Claude Desktop

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

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

Cursor, Windsurf y otros clientes MCP

Usa la misma entrada JSON de servidor anterior en el archivo de configuración MCP de tu cliente (Cursor: ~/.cursor/mcp.json; Windsurf: ~/.codeium/windsurf/mcp_config.json).

Sin uv

Si prefieres una instalación Python simple (requiere Python 3.12+):

pip install physbound

luego establece "command": "physbound" (sin args) en la configuración del cliente.

Una vez configurado, haz a tu asistente una pregunta de RF — "¿Puede un canal de 20 MHz con 15 dB de SNR soportar 500 Mbps?" — y responderá con números validados por la física.

Uso desde la línea de comandos

Los mismos validadores están disponibles directamente desde la terminal, útiles en scripts y pipelines de CI, ya que una violación de física sale con 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 disponibles: check {link-budget, shannon, noise, radar-range, antenna, radar-ambiguity} (las banderas reflejan los parámetros de las herramientas MCP; añade --json para el resultado estructurado completo) y serve --transport {stdio,http} para ejecutar el servidor MCP sobre HTTP. Consulta physbound check --help para más detalles.

Lo que los LLM hacen mal

Dieciséis patrones reales de alucinación, cada uno detectado por el conjunto de pruebas de PhysBound:

#CategoríaAlucinación del LLMVerdad de PhysBoundVeredicto
1Shannon-HartleyUn canal 802.11n de 20 MHz con 15 dB de SNR puede alcanzar 500 MbpsLímite de Shannon: 100.6 Mbps (no 500 Mbps)DETECTADO
2Shannon-HartleyUn canal 5G de 100 MHz con 20 dB de SNR entrega 2 GbpsLímite de Shannon: 665.8 Mbps (no 2000 Mbps)DETECTADO
3Apertura de antenaUna antena parabólica de 30 cm a 1 GHz proporciona 45 dBi de gananciaLímite físico: 12.1 dBi (Harrington); apertura eta=1: 9.9 dBi; parabólica típica: 7.4 dBi (eta=0.55) (no 45 dBi)DETECTADO
4Ruido térmicoPiso de ruido del receptor de -180 dBm/Hz a temperatura ambientePiso de ruido térmico: -174.0 dBm/Hz a 290K (no -180 dBm/Hz)DETECTADO
5Presupuesto de enlace / FSPLWi-Fi a 2.4 GHz con 20 dBm de TX alcanza 10 km con -40 dBm de potencia RXPotencia RX real a 10 km: -94.1 dBm (no -40 dBm)DETECTADO
6Presupuesto de enlace / FSPLUn transmisor de 1W a 12 GHz con antenas de 0 dBi alcanza GEO a -80 dBmPotencia RX real en GEO: -175.1 dBm (no -80 dBm)DETECTADO
7Presupuesto de enlace / FSPLBluetooth a 2.4 GHz con 0 dBm de TX y antenas de 0 dBi alcanza 1 km a -60 dBmPotencia RX real a 1 km: -100.1 dBm (no -60 dBm)DETECTADO
8Shannon-HartleyUn canal LTE de 10 MHz a 10 dB de SNR soporta 1 GbpsLímite de Shannon: 34.6 Mbps (no 1000 Mbps)DETECTADO
9Cascada de ruidoLa NF del receptor es la misma independientemente del orden de etapas: LNA(20dB/1.5dB) + Mezclador(10dB/8dB)LNA primero: 1.66 dB vs mezclador primero: 8.03 dB (penalización: 6.4 dB)DETECTADO
10Apertura de antenaUna antena de parche de 10 cm a 900 MHz proporciona 20 dBi de gananciaLímite físico: 4.4 dBi (Harrington, D < lambda); apertura eta=1: -0.5 dBi; típica: -3.1 dBi (eta=0.55) (no 20 dBi)DETECTADO
11Ecuación de alcance del radarDuplicar la potencia del transmisor duplica el alcance de detección del radarEl alcance aumenta por factor 1.189 (2^(1/4) = 1.189), no 2.0DETECTADO
12Ecuación de alcance del radarDron pequeño (RCS de 0.01 m^2) detectable a 200 km por radar de banda X de 1 kW con 30 dBi de gananciaAlcance máximo: 2.7 km para RCS de 0.01 m^2 a 1 kW en banda X (no 200 km)DETECTADO
13Ganancia de antenaUna antena parabólica de terminal de usuario de 0.5 m a 12 GHz da 50 dBi de gananciaLímite físico: 36.1 dBi (Harrington); parabólica típica: 33.4 dBi (eta=0.55) (no 50 dBi)DETECTADO
14Ganancia de antenaUna antena parabólica de 3 m a 10 GHz está en campo lejano a 10 m, por lo que la ganancia puede medirse allíDistancia de campo lejano 2D^2/lambda = 600 m; 10 m está en campo cercanoDETECTADO
15Ambigüedad de radarUn radar de 10 GHz a 10 kHz de PRF mide inequívocamente 500 m/sv_ua = lambda*PRF/4 = +/-74.9 m/s (velocidad ciega 149.9 m/s); 500 m/s se pliega (no 500 m/s)DETECTADO
16Ambigüedad de radarUn radar de pulso-Doppler de 10 GHz puede cubrir inequívocamente 150 km y +/-300 m/s a la vezR_uav_ua = clambda/8 = 1.123e+06 m^2/s para cualquier PRF; reclamado 4.5e+07 m^2/s (40x demasiado grande)DETECTADO

Generado automáticamente por pytest tests/test_marketing.py -s

Herramientas

Derivaciones completas, fuentes y ejemplos resueltos para cada fórmula están en docs/formulas.md.

rf_link_budget

Calcula un presupuesto de enlace RF completo usando la ecuación de transmisión de Friis y valida las ganancias de antena contra límites físicos.

Ejemplo: "¿Cuál es la potencia recibida para un enlace de 2.4 GHz a 100 m con 20 dBm de TX, 10 dBi de ganancia TX, 3 dBi de ganancia RX?"

Devuelve FSPL, potencia recibida, longitud de onda y — cuando se proporcionan diámetros de antena — comprobaciones de límite de ganancia. Las ganancias por encima del límite estricto G_max = max((pi D / lambda)^2, (ka)^2 + 2ka) (el valor de apertura eta = 1, o el límite de Harrington para antenas eléctricamente pequeñas) se rechazan; las ganancias por encima del valor típico de parabólica (eta = 0.55) se aceptan con una advertencia. También advierte dentro de la distancia de campo lejano 2D^2/lambda y rechaza pérdidas negativas.

shannon_hartley

Calcula la capacidad del canal de Shannon-Hartley C = B log2(1 + SNR) y valida afirmaciones de rendimiento.

Ejemplo: "¿Puede un canal de 20 MHz con 15 dB de SNR soportar 500 Mbps?"

Devuelve la capacidad teórica, la eficiencia espectral y si la afirmación es físicamente posible, incluyendo el porcentaje exacto en que una afirmación violadora excede el límite de Shannon.

noise_floor

Calcula la potencia de ruido térmico N = k_B T B, encadena figuras de ruido a través de receptores de múltiples etapas con la fórmula de ruido de Friis y calcula la sensibilidad del receptor.

Ejemplo: "¿Cuál es el piso de ruido para un receptor de 1 MHz a 290 K con una cadena LNA de dos etapas?"

Devuelve ruido térmico en dBm y vatios, figura de ruido en cascada, temperatura de ruido de entrada efectiva T_e = 290 K * (F - 1) y sensibilidad del receptor.

radar_range

Calcula la ecuación de alcance del radar monoestático R_max = [P_t G^2 lambda^2 sigma / ((4pi)^3 S_min L)]^(1/4) y valida afirmaciones de alcance de detección.

Ejemplo: "¿Puede un radar de banda X de 1 kW con 30 dBi de ganancia detectar un dron de 0.01 m^2 a 200 km?"

Devuelve el alcance máximo de detección, la señal mínima detectable, la longitud de onda y valores intermedios. Detecta la falacia común de la raíz cuarta de que duplicar la potencia duplica el alcance.

antenna_gain

Analiza una antena individual a partir de su diámetro o área física: límites de ganancia, ancho de haz y distancia de campo lejano, con validación opcional de una ganancia reclamada.

Ejemplo: "¿Puede una antena parabólica de 0.5 m a 12 GHz realmente dar 50 dBi? ¿Qué ancho de haz debería esperar?"

Devuelve el límite físico de ganancia (apertura o límite de Harrington, y cuál gobierna), ganancia típica a la eficiencia dada (por defecto 0.55), apertura efectiva, estimaciones de ancho de haz a media potencia, distancia de campo lejano 2D^2/lambda y — para una ganancia reclamada — la eficiencia de apertura implícita y su validez.

radar_ambiguity

Calcula los límites de ambigüedad de pulso-Doppler para una frecuencia portadora y PRF dadas.

Ejemplo: "¿Puede un radar de 10 GHz a 10 kHz de PRF medir inequívocamente un objetivo de 500 m/s hasta 150 km?"

Devuelve alcance inequívoco R_ua = c / (2 PRF), velocidad inequívoca v_ua = lambda PRF / 4, velocidad ciega, desplazamiento Doppler y velocidad aparente (con aliasing), resolución de alcance (c tau / 2, o c / 2B con compresión de pulsos), alcance mínimo, ciclo de trabajo y el invariante del dilema alcance-Doppler R_ua v_ua = c lambda / 8. Rechaza afirmaciones de alcance, velocidad o resolución que la PRF o el pulso no pueden soportar.

Garantías de física

Cada cálculo se valida contra límites físicos estrictos:

  • Velocidad de la luz: c = 299,792,458 m/s — sin excepciones
  • Piso de ruido térmico: N = -174 dBm/Hz a 290 K — la referencia estándar del IEEE
  • Límite de Shannon: C = B log2(1 + SNR) — ninguna afirmación de rendimiento excede esto
  • Límite de ganancia de antena: G_max = max((pi D / lambda)^2, (ka)^2 + 2ka) — el valor de apertura eta = 1 para aperturas planas y el límite de Harrington para cualquier antena en una esfera de diámetro D; eta = 0.55 es un umbral de advertencia, no un límite
  • Ecuación de alcance del radar: R_max = [P_t G^2 lambda^2 sigma / ((4pi)^3 S_min)]^(1/4) — el alcance obedece la ley de la raíz cuarta
  • Sensibilidad del receptor: S_min = k (T_A + T_0 (F - 1)) B * SNR con T_e = T_0 (F - 1) referenciado a 290 K
  • Alcance inequívoco: R_ua = c / (2 PRF) — los ecos más allá se pliegan en un intervalo de pulso posterior
  • Velocidad inequívoca: v_ua = lambda PRF / 4 — el Doppler se muestrea a la PRF, por lo que |f_d| <= PRF/2
  • Dilema alcance-Doppler: R_ua * v_ua = c lambda / 8 — ninguna elección de PRF lo supera para una portadora dada

Las violaciones devuelven respuestas estructuradas PhysicalViolationError con explicaciones en LaTeX, no fallos silenciosos.

Ejemplos y documentación

Desarrollo

Requiere uv y Python 3.12+ (CI cubre 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

Las contribuciones que amplíen el conjunto de dominios de física validados son bienvenidas — consulta CONTRIBUTING.md para la guía de arquitectura y la receta paso a paso para añadir un nuevo validador.

Casos de uso

  • Revisión de diseño de sistemas de RF — valide presupuestos de enlace, sensibilidad del receptor y cascadas de ruido
  • Evaluación de propuestas de telecomunicaciones — detecte afirmaciones de rendimiento imposibles antes de que lleguen a un cliente
  • Dimensionamiento de sistemas de radar — verifique el alcance de detección, la selección de PRF y las compensaciones de ambigüedad
  • Herramientas educativas — enseñe Shannon-Hartley, transmisión de Friis y ruido térmico con cálculos verificados
  • CI/CD para física — integre como un paso de validación en pipelines de ingeniería

Soporte

Si PhysBound es útil en su trabajo, considere invitarme un café.

Licencia

Licencia MIT. Consulte LICENCIA.

Relacionados