Source code for openworld_radio_twin.spectrum

"""Link direction of registered frequency ranges, from the 3GPP operating bands.

Registers list the frequency ranges an antenna is licensed for, often uplink and downlink
together and without saying which is which. A radio map is a downlink product, so each
range is classified against the operating bands of 3GPP TS 36.101 (E-UTRA) and TS 38.104
(NR), which also cover GSM and UMTS deployments in the same bands, and the railway GSM bands
of TS 45.005.

The same frequencies are uplink in one region and downlink in another (band 1 uplink
overlaps band 2 downlink), so a range is classified in two steps. The bands containing the
range decide when they agree. When they disagree, another range of the same antenna at a
band's duplex spacing, its uplink or downlink partner, decides. A range whose bands all carry
a downlink, TDD in one and downlink in another, is downlink. A range that neither step
resolves, such as a typing error spanning uplink and downlink, stays ``unknown``.
"""

from __future__ import annotations

from dataclasses import dataclass
from functools import lru_cache
from typing import Literal

Link = Literal["downlink", "uplink", "tdd", "unknown"]
# Ranges that carry a downlink radio map.
DOWNLINK_LINKS: frozenset[str] = frozenset({"downlink", "tdd"})
# Registers round frequencies to 0.1 MHz; ranges and duplex spacings match within this.
MATCH_TOLERANCE_MHZ = 0.15


[docs] @dataclass(frozen=True) class OperatingBand: """A 3GPP operating band. FDD bands have both links, TDD bands one shared range, supplementary downlink (SDL) bands a downlink only.""" name: str uplink: tuple[float, float] | None downlink: tuple[float, float] | None @property def tdd(self) -> bool: return self.uplink is not None and self.uplink == self.downlink @property def duplex_spacing_mhz(self) -> float | None: if self.uplink is None or self.downlink is None or self.tdd: return None return self.downlink[0] - self.uplink[0]
def _fdd(name: str, uplink: tuple[float, float], downlink: tuple[float, float]): return OperatingBand(name, uplink, downlink) def _tdd(name: str, extent: tuple[float, float]): return OperatingBand(name, extent, extent) def _sdl(name: str, downlink: tuple[float, float]): return OperatingBand(name, None, downlink) # TS 36.101 Table 5.5-1 and TS 38.104 Table 5.2-1, bands with commercial deployments, and # the railway GSM bands of TS 45.005 (R-GSM, ER-GSM), whose uplinks fall in band 5 downlink. OPERATING_BANDS: tuple[OperatingBand, ...] = ( _fdd("1", (1920, 1980), (2110, 2170)), _fdd("2", (1850, 1910), (1930, 1990)), _fdd("3", (1710, 1785), (1805, 1880)), _fdd("4", (1710, 1755), (2110, 2155)), _fdd("5", (824, 849), (869, 894)), _fdd("7", (2500, 2570), (2620, 2690)), _fdd("8", (880, 915), (925, 960)), _fdd("11", (1427.9, 1447.9), (1475.9, 1495.9)), _fdd("12", (699, 716), (729, 746)), _fdd("13", (777, 787), (746, 756)), _fdd("14", (788, 798), (758, 768)), _fdd("17", (704, 716), (734, 746)), _fdd("18", (815, 830), (860, 875)), _fdd("19", (830, 845), (875, 890)), _fdd("20", (832, 862), (791, 821)), _fdd("21", (1447.9, 1462.9), (1495.9, 1510.9)), _fdd("25", (1850, 1915), (1930, 1995)), _fdd("26", (814, 849), (859, 894)), _fdd("28", (703, 748), (758, 803)), _sdl("29", (717, 728)), _fdd("30", (2305, 2315), (2350, 2360)), _fdd("31", (452.5, 457.5), (462.5, 467.5)), _sdl("32", (1452, 1496)), _tdd("33", (1900, 1920)), _tdd("34", (2010, 2025)), _tdd("38", (2570, 2620)), _tdd("39", (1880, 1920)), _tdd("40", (2300, 2400)), _tdd("41", (2496, 2690)), _tdd("42", (3400, 3600)), _tdd("43", (3600, 3800)), _tdd("46", (5150, 5925)), _tdd("48", (3550, 3700)), _fdd("65", (1920, 2010), (2110, 2200)), _fdd("66", (1710, 1780), (2110, 2200)), _sdl("67", (738, 758)), _fdd("68", (698, 728), (753, 783)), _sdl("69", (2570, 2620)), _fdd("70", (1695, 1710), (1995, 2020)), _fdd("71", (663, 698), (617, 652)), _fdd("72", (451, 456), (461, 466)), _sdl("75", (1432, 1517)), _sdl("76", (1427, 1432)), _fdd("85", (698, 716), (728, 746)), _tdd("n77", (3300, 4200)), _tdd("n78", (3300, 3800)), _tdd("n79", (4400, 5000)), _tdd("n257", (26500, 29500)), _tdd("n258", (24250, 27500)), _tdd("n260", (37000, 40000)), _tdd("n261", (27500, 28350)), _fdd("R-GSM", (876, 915), (921, 960)), _fdd("ER-GSM", (873, 915), (918, 960)), ) def _inside(frequency_range: tuple[float, float], extent: tuple[float, float] | None) -> bool: return ( extent is not None and extent[0] - MATCH_TOLERANCE_MHZ <= frequency_range[0] and frequency_range[1] <= extent[1] + MATCH_TOLERANCE_MHZ ) def _table_links(frequency_range: tuple[float, float]) -> set[str]: links = set() for band in OPERATING_BANDS: if band.tdd: if _inside(frequency_range, band.uplink): links.add("tdd") continue if _inside(frequency_range, band.uplink): links.add("uplink") if _inside(frequency_range, band.downlink): links.add("downlink") return links def _paired(first: tuple[float, float], second: tuple[float, float]) -> set[str]: """Links of ``first`` when ``second`` is its partner at some band's duplex spacing.""" width = first[1] - first[0] if abs((second[1] - second[0]) - width) > MATCH_TOLERANCE_MHZ: return set() links = set() for band in OPERATING_BANDS: spacing = band.duplex_spacing_mhz if spacing is None: continue offset = second[0] - first[0] if ( abs(offset - spacing) <= MATCH_TOLERANCE_MHZ and _inside(first, band.uplink) and _inside(second, band.downlink) ): links.add("uplink") if ( abs(offset + spacing) <= MATCH_TOLERANCE_MHZ and _inside(first, band.downlink) and _inside(second, band.uplink) ): links.add("downlink") return links
[docs] @lru_cache(maxsize=8192) def classify_ranges(ranges: tuple[tuple[float, float], ...]) -> tuple[Link, ...]: """The link of each of one antenna's distinct registered ranges (low, high) in MHz.""" links: list[Link] = [] for index, frequency_range in enumerate(ranges): candidates = _table_links(frequency_range) if len(candidates) > 1: # Pairing can only narrow the bands' answer: a partner at a duplex spacing # places the range inside one of those bands. paired = set().union( *( _paired(frequency_range, other) for other_index, other in enumerate(ranges) if other_index != index ) ) candidates = paired or candidates if len(candidates) == 1: links.append(candidates.pop()) elif candidates and candidates <= DOWNLINK_LINKS: links.append("downlink") else: links.append("unknown") return tuple(links)