io.github.JonesRobM/physbound

Calculate antenna aperture gain limits, beamwidth, far-field distance; validate gain claims. For a circular aperture of diameter D (or an aperture of area A, converted to the equivalent circular diameter D = sqrt(4A/pi)) computes the planar-aperture directivity D_0 = 4*pi*A/lambda^2 = (pi*D/lambda)^2 (aperture efficiency eta = 1), Harrington's bound D_max = (ka)^2 + 2ka (k = 2*pi/lambda, a = D/2) for any antenna enclosed in a sphere of diameter D, the hard physical gain limit max(D_0, D_max) (numerically D_max; equal to D_0 to within 0.1 dB for D >> lambda, but several dB higher for electrically small antennas D < lambda, e.g. a 2.15 dBi dipole in a 0.1 m footprint at 900 MHz is valid although D_0 = -0.5 dBi), and the typical gain G = eta*D_0 at the given efficiency (default eta = 0.55, parabolic dish). The limiting_bound field reports 'harrington' for D < lambda and 'aperture' for D >= lambda. Also returns the effective aperture A_e = eta*A, a half-power beamwidth estimate (HPBW ~ 70*lambda/D degrees for a tapered reflector; 58.4*lambda/D for a uniformly illuminated circular aperture) and the far-field (Fraunhofer) distance 2*D^2/lambda. If claimed_gain_dbi is given it is validated: a claim above the physical limit is rejected as a physics violation; a claim between the typical gain and the physical limit is accepted with a warning and the implied planar-aperture efficiency eta = G_claim / D_0 is reported. Use this tool when you need to: - Check whether a quoted antenna gain is consistent with its size and frequency - Estimate the gain, beamwidth or effective aperture of a dish of known diameter - Find the minimum far-field range for antenna measurements or Friis validity - Size an antenna for a required gain at a given frequency Returns a PhysicalViolationError dict if any input violates physics or the claimed gain exceeds the aperture limit.

Calculate thermal noise power (kTB), cascaded noise figure, and receiver sensitivity. Computes the fundamental thermal noise floor N = k_B * T * B, which is -174 dBm/Hz at the IEEE standard temperature of 290K. Optionally cascades multiple amplifier/filter stages using the Friis noise figure formula F_total = F_1 + (F_2-1)/G_1 + (F_3-1)/(G_1*G_2) + ..., the receiver's effective input noise temperature T_e = T_0*(F-1) with T_0 = 290 K (the IEEE reference at which noise figure is defined, independent of temperature_k), and receiver sensitivity S_min = k_B*(T_A + T_e)*B*SNR_required, which reduces to N_floor + NF + SNR_required when temperature_k = 290 K. Use this tool when you need to: - Determine the thermal noise floor for a receiver bandwidth - Cascade noise figures through a multi-stage receiver chain - Calculate minimum detectable signal / receiver sensitivity - Validate that a claimed noise figure is physically plausible Returns a PhysicalViolationError dict if inputs violate thermodynamic limits.

Calculate pulse-Doppler radar ambiguity limits and validate range/velocity claims. Computes the maximum unambiguous range R_ua = c / (2 * PRF), the first blind speed lambda * PRF / 2, the unambiguous velocity v_ua = +/- lambda * PRF / 4 (Doppler within +/- PRF/2), the Doppler shift f_d = 2 * v_r / lambda of a target (closing velocity positive) and whether it aliases, and — when a pulse width is given — the duty cycle, eclipsing minimum range c * tau / 2 and the range resolution c * tau / 2 (or c / (2 B) when a compressed bandwidth is supplied). Reports the range-Doppler dilemma invariant R_ua * v_ua = c * lambda / 8, which no choice of PRF can beat (Skolnik, Introduction to Radar Systems, Ch. 2-3; Richards, Fundamentals of Radar Signal Processing, Ch. 1, 3, 5). Use this tool when you need to: - Find the unambiguous range and velocity coverage of a given PRF - Check whether a claimed unambiguous range or velocity is possible at that PRF - Check whether a claimed range resolution is possible for the pulse/bandwidth - Determine whether a target's Doppler will alias or fall at a blind speed - Expose claims that silently violate the range-Doppler dilemma Returns both human-readable summary and machine-readable JSON with all intermediate values. Returns a PhysicalViolationError dict if any input violates physics (PRF <= 0, tau <= 0, duty cycle >= 1) or a claim exceeds its limit.

Calculate maximum monostatic radar detection range and validate range claims. Computes the radar range equation R_max = [P_t * G^2 * lambda^2 * sigma / ((4*pi)^3 * S_min * L)]^(1/4) for a monostatic radar (same antenna for transmit and receive). Validates that claimed detection ranges do not exceed the theoretical maximum. Catches the common fourth-root fallacy where LLMs incorrectly state that doubling transmit power doubles radar range (it only increases range by a factor of 2^(1/4) = 1.19x). Use this tool when you need to: - Calculate the maximum detection range of a radar system - Validate whether a claimed radar detection range is physically achievable - Determine minimum detectable signal power for a radar receiver - Check if radar performance claims account for the R^4 path loss - Verify that RCS assumptions are reasonable for the target class Returns both human-readable summary and machine-readable JSON with all intermediate values. Returns a PhysicalViolationError dict if any input violates physics or the claimed range exceeds R_max.

Calculate a complete RF link budget using the Friis transmission equation. Computes free-space path loss (FSPL), received power, and validates antenna gains against the physical gain limit. The hard bound is G_max = max((pi*D/lambda)^2, (ka)^2 + 2ka) with k = 2*pi/lambda and a = D/2, i.e. the larger of the eta = 1 aperture value and Harrington's bound for an antenna enclosed in a sphere of diameter D (numerically the Harrington value, which converges to the aperture value for D >> lambda and matters for electrically small antennas, D < lambda); a claimed gain above it is rejected. A claimed gain above the typical-efficiency value eta*(pi*D/lambda)^2 (eta = 0.55 by default) but below the physical bound is accepted with a warning. Negative losses are rejected (conservation of energy). Use this tool when you need to: - Estimate received signal strength for a wireless link - Validate whether a claimed link budget is physically achievable - Check if antenna gain claims are consistent with antenna dimensions - Compute free-space path loss at a given frequency and distance Returns both human-readable summary and machine-readable JSON with all intermediate values. Returns a PhysicalViolationError dict if any input violates physics.

Calculate Shannon-Hartley channel capacity and validate throughput claims. Computes the theoretical maximum data rate C = B * log2(1 + SNR) for an AWGN channel. If a claimed throughput is provided, validates it against this limit. Any claim exceeding the Shannon limit is a physical impossibility. Use this tool when you need to: - Calculate maximum achievable throughput for a given bandwidth and SNR - Validate whether a throughput claim is physically possible - Determine spectral efficiency limits - Check if a modulation/coding scheme claim is realistic Returns a PhysicalViolationError dict when a claim exceeds the Shannon limit.