Physbound

🚀 PhysBound

A Physical Layer Linter that validates RF and physics calculations against hard physical limits, catching AI hallucinations in engineering workflows.

🚀 Quick Start

📦 Installation

pip install physbound

💻 MCP Client Configuration

Add PhysBound to any MCP-compatible client. For example, in Claude Desktop (claude_desktop_config.json), Cursor, or Windsurf:

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

⚠️ Important Note

uvx downloads ~60 MB of dependencies (scipy, numpy) on first launch. Run uvx physbound once in your terminal to pre-cache them — subsequent starts will be instant.

Your AI assistant now has access to physics-validated RF calculations.

✨ Features

📊 What LLMs Get Wrong

LLMs routinely hallucinate physics. PhysBound catches it:

Generated automatically by pytest tests/test_marketing.py -s

🛠️ Tools

rf_link_budget

Computes a full RF link budget using the Friis transmission equation. Validates antenna gains against aperture limits.

Example: "What's the received power for a 2.4 GHz link at 100 m with 20 dBm TX, 10 dBi TX gain, 3 dBi RX gain?"

Returns: FSPL, received power, wavelength, and optional aperture limit checks. Rejects antenna gains that violate G_max = eta * (pi * D / lambda)^2.

shannon_hartley

Computes Shannon-Hartley channel capacity C = B * log2(1 + SNR) and validates throughput claims.

Example: "Can a 20 MHz channel with 15 dB SNR support 500 Mbps?"

Returns: Theoretical capacity, spectral efficiency, and whether the claim is physically possible. Flags violations with the exact percentage by which the claim exceeds the Shannon limit.

noise_floor

Computes thermal noise power N = k_B * T * B, cascades noise figures through multi-stage receivers using the Friis noise formula, and calculates receiver sensitivity.

Example: "What's the noise floor for a 1 MHz receiver at 290K with a two-stage LNA chain?"

Returns: Thermal noise in dBm and watts, cascaded noise figure, system noise temperature, and receiver sensitivity.

radar_range

Computes the monostatic radar range equation R_max = [P_t G^2 lambda^2 sigma / ((4pi)^3 S_min L)]^(1/4) and validates detection range claims.

Example: "Can a 1 kW X-band radar with 30 dBi gain detect a 0.01 m^2 drone at 200 km?"

Returns: Maximum detection range, minimum detectable signal, wavelength, and intermediate values. Catches the common fourth-root fallacy where doubling power is incorrectly assumed to double range.

⚛️ Physics Guarantees

Every calculation is validated against hard physical limits:

• Speed of light: c = 299,792,458 m/s — no exceptions
• Thermal noise floor: N = -174 dBm/Hz at 290K — the IEEE standard reference
• Shannon limit: C = B * log2(1 + SNR) — no throughput claim exceeds this
• Aperture limit: G_max = eta * (pi * D / lambda)^2 — antenna gain is bounded by physics
• Radar range equation: R_max = [P_t G^2 lambda^2 sigma / ((4pi)^3 S_min)]^(1/4) — range obeys the fourth-root law

Violations return structured PhysicalViolationError responses with LaTeX explanations, not silent failures.

💡 Examples

See PhysBound catching hallucinations in real time:

• Catching Hallucinations — walkthrough of four real LLM failure modes with full JSON responses
• Interactive Demo Notebook — hands-on Jupyter notebook calling the physics engines directly

🛠️ Development

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

# Run tests
uv run pytest tests/ -v

# Print hallucination delta table
uv run pytest tests/test_marketing.py -s

# Start MCP server locally
uv run physbound

❓ Why PhysBound?

AI coding assistants are increasingly used in RF engineering, telecommunications, and signal processing workflows. But LLMs have no intrinsic understanding of physics. They generate plausible-sounding numbers that can violate fundamental laws like Shannon-Hartley, thermodynamic noise limits, and antenna aperture bounds.

PhysBound acts as a physics guardrail for any MCP-compatible AI assistant. Every calculation is checked against CODATA physical constants via SciPy, with dimensional analysis enforced through Pint. Violations return structured errors with LaTeX explanations, not silent failures.

📋 Use cases

• RF system design review — validate link budgets, receiver sensitivity, and noise cascades
• Telecom proposal vetting — catch impossible throughput claims before they reach a customer
• Educational tools — teach Shannon-Hartley, Friis transmission, and thermal noise with verified calculations
• CI/CD for physics — integrate as a validation step in engineering pipelines

💖 Support

If PhysBound is useful in your work, consider buying me a coffee.

📄 License

MIT License. See LICENSE.

🔗 Related

• Model Context Protocol — the open standard for AI tool integration
• MCP Server Registry — official directory of MCP servers
• FastMCP — Python framework for building MCP servers