Model the direct path with Okumura-Hata and derate towers under the beam

[jehanazad]

Follows from the home-installation PSD comparison: received_power_dbm was EIRP + 6 dBi − free-space loss, and against measurements it ran 20 to 50 dB high. The part of that gap that is the same for every node has a textbook model; the part that is this installation's whip, polarisation and walls does not, and stays the node's to measure (sweep calibration in #30, feedback rows via #32).

What changes

Two terms on the direct path, both in a new propagation config section (shipped in tower_config.json, documented in the README):

• Okumura-Hata excess over free space. Mast height, receiver height (rx_height_m, shipped 5 m) and environment (open / suburban / urban, shipped suburban). Never negative, so a tower in plain view is still free space away. FM, masts over 200 m and ranges under 1 km are clamped to the formula's edge rather than refused. model: "free_space" is the old behaviour.
• Under-beam derating. A broadcast beam is a few degrees tall and tilted about a degree down; 3 km from a 300 m mast is 6° under it. Parabolic main lobe, 12·(angle/beamwidth)², per-band vertical_beamwidth_deg (FM 8°, VHF 4°, UHF 2°), capped at max_underbeam_loss_db (20) for null fill. Height is above ground, so a hilltop mast is derated less than it should be, never more.

A record with no antenna height (common on FCC low-power records, which carry 0) borrows the tallest height within the 200 m channel-sharing radius, so the LD channels on a shared mast get the same derating as the full-power record. Indexed on a 0.01° grid; the radius decides, the grid only narrows the search.

Additive fields per tower: path_loss_db, excess_path_loss_db, underbeam_loss_db. Nothing existing changes shape. Overlays that predate the section get the terrestrial model without a config PUT.

Against the measurements

Live query for the home site, model versus the sheet's tinySA and SDRConnect reference readings (mean over-prediction, dB):

Band	Before	After
FM	24	3
VHF	44	19
UHF	53	25

Per tower, WGGB-TV at 3.6 km goes from −4.8 to −35.6 dBm (measured −54): 11 dB of Hata excess, 20 dB under the beam. WSHM-LD on the same mast, height 0 on record, now borrows WGGB's 320 m and moves from rank 4 to 12. The TV remainder is consistent with a vertical whip receiving horizontally polarised ATSC indoors, which no site-independent model should try to absorb.

Verification

• 424 backend tests (43 new in test_propagation.py), ruff check and format clean. The existing ranking tests pass unchanged: Hata is monotonic in distance and its excess is near flat across TV bands, so the orderings they pin still hold.
• Benchmark, 3000 synthetic records half without a height: process_and_rank 660 ms end to end (unchanged code dominates), the mast index plus 1500 lookups 4 ms.

Not in this PR

• Rank illuminators by expected bistatic detection area, with diversity, sweep calibration and fleet feedback #30's tower_scoring computes its own direct-path power with free space; when it rebases it should call path_loss and underbeam_loss for the direct path and keep free space for the target echo, which is air-to-ground.
• Site elevation above the receiver is not in the FCC record at ranking time; the elevation enrichment runs after. Folding it into the depression angle would sharpen the derating for hilltop masts.

🤖 Generated with Claude Code

[claude]

Claude finished @jehanazad's task in 2m 49s —— View job

---

Reviewing PR #33

Todo list

• Gather context (PR diff, changed files, repo guidelines)
• Understand the request (code review)
• Read tower_ranking.py, tower_config.json, README, test_propagation.py diffs
• Post findings

Note: I wasn't able to execute pytest/ruff in this sandbox (Bash commands required approval that wasn't available), so this review is static — I couldn't independently verify the "424 tests / ruff clean" claim.

---

Summary

This is a well-structured, well-tested addition. The Hata formula and derating math check out against the standard textbook equations, the clamping logic is sound, and the test suite is thorough (including the tricky "borrow neighbour's mast height" case). Two things worth a look before merge:

1. model: "free_space" doesn't fully restore the old behaviour, despite what the docs claim

backend/services/tower_ranking.py:539-561 (underbeam_loss) never checks PROPAGATION_MODEL — it only looks at MAX_UNDERBEAM_LOSS_DB. So setting propagation.model: "free_space" alone still applies up to 20 dB of under-beam derating on top of the free-space loss.

That contradicts both the README (README.md:60: "model: "free_space" is the previous behaviour, one line away") and the PR body ("model: "free_space" is the old behaviour"). The PR's own test proves the gap — test_free_space_model_reproduces_the_old_formula (backend/tests/test_propagation.py:153-155) has to set both model="free_space" and max_underbeam_loss_db=0 to actually reproduce eirp + gain - fspl:

def test_free_space_model_reproduces_the_old_formula(self, restore_config):
    _propagation(restore_config, model="free_space", max_underbeam_loss_db=0)
    assert received_power(80, 20, 550) == pytest.approx(...)

If under-beam derating is meant to be an independent knob (a distinct antenna-pattern effect, not part of "path loss"), that's a reasonable design — but the docs currently overstate it as a full revert. Worth either (a) gating underbeam_loss() on PROPAGATION_MODEL != "free_space", or (b) fixing the README/PR wording to say "one line away" really means two settings.

Fix this →

2. path_loss() and underbeam_loss() are each computed twice per tower

In process_and_rank (backend/services/tower_ranking.py:944-948):

pwr = received_power(eirp, dist, freq_val, tx_height, band)   # internally calls path_loss() + underbeam_loss()
if pwr < SENSITIVITY_DBM:
    continue
total_loss, excess_loss = path_loss(dist, freq_val, tx_height)   # recomputes Hata
underbeam = underbeam_loss(dist, tx_height, band)                 # recomputes derating

received_power() (tower_ranking.py:563-577) already computes both internally to derive pwr, then the loop recomputes them a second time just to get the breakdown fields for the response. It's not a correctness bug — and the benchmark numbers in the PR (250 ms / 3000 records) suggest it's not currently a problem — but it doubles the Hata/derating math for every surviving tower for no reason. Simplest fix: have received_power return (power, total_loss, excess_loss, underbeam) (or compute the breakdown once and derive pwr from it), and use that single result in the loop.

Minor

• underbeam_loss()'s fallback for an unrecognized band (tower_ranking.py:559) uses the hardcoded DEFAULT_VERTICAL_BEAMWIDTH_DEG["VHF"] rather than the currently-configured VERTICAL_BEAMWIDTH_DEG.get("VHF", ...). In practice this path is unreachable from process_and_rank (bands are classified and None is filtered out earlier), so it only matters for direct callers of received_power/underbeam_loss with a custom band that isn't in the config — low impact, but slightly inconsistent with "config always wins."
• Hata's formal validity range tops out around 20 km, but hata_excess_loss clamps the minimum distance (1 km) without an upper clamp, and the default search radius is 80 km. Excess loss is extrapolated well past the formula's tested range at longer distances. This may be intentional (it's monotonic and the PR doesn't claim accuracy beyond the formula's validity), but it's not mentioned in the README's list of clamped inputs, worth a one-line callout if it's a known tradeoff.

Nice work on the docstrings and the "reason why" comments throughout — they make the physical reasoning easy to follow and cross-check.