Source code for openworld_radio_twin.antennas

"""Antennas of a compiled scene: acquired from a source, selected, placed and recorded.

The Python loader, the web service and dataset generation all call
:func:`scene_antennas`, so a scene's antennas are the same wherever they are requested.
Each result is also written into the scene directory under ``antennas/`` as the record of
what the scene's transmitters were taken from; the compiled geometry does not change.

A Sionna run simulates one downlink channel: ``scene.frequency`` is its centre and
``scene.bandwidth`` its width. A channel is a downlink range an antenna registers, and an
antenna transmits on it when it registers a downlink range that contains it, at its own
power.
"""

from __future__ import annotations

import asyncio
import hashlib
import json
from collections.abc import Mapping, Sequence
from dataclasses import dataclass, replace
from pathlib import Path

import httpx

from openworld_radio_twin.compiler import _read_json, _scene_lock, _write_json_atomic
from openworld_radio_twin.config import Settings, get_settings
from openworld_radio_twin.jsonio import dump_json_with_compact_rows
from openworld_radio_twin.models import (
    SIONNA_FREQUENCY_RANGE_GHZ,
    AntennaDefaults,
    AntennaFeature,
    AntennaOperator,
    Channel,
    ChannelRange,
    FrequencyRange,
    TransmitterConfig,
)
from openworld_radio_twin.providers.base import ANTENNA_BOUNDARY_POLICY, AntennaQueryResult
from openworld_radio_twin.providers.map_data import MapDataProvider
from openworld_radio_twin.scene_format import SCENE_ANTENNAS_DIRECTORY, SCENE_INFO_PATH
from openworld_radio_twin.simulation.antenna_placement import (
    complete_antennas,
    keep_inside_scene,
    keep_inside_square,
    place_antennas,
)
from openworld_radio_twin.simulation.scene_builder import load_scene_assets
from openworld_radio_twin.spectrum import DOWNLINK_LINKS

# Version 2 renamed case_channels in a dataset scene's source_antennas.json.
ANTENNA_RECORD_SCHEMA_VERSION = 2


[docs] @dataclass(frozen=True) class SceneAntennas: """Selected antennas of a scene or map area, with the operators and radios it holds; ``record`` is the file written into a compiled scene, None for a map area.""" result: AntennaQueryResult operators: list[AntennaOperator] radios: list[str] defaults: AntennaDefaults record: Path | None
[docs] def select_antennas( result: AntennaQueryResult, *, operator: str | None = None, radio: str | None = None, ) -> AntennaQueryResult: """Keep the antennas of one operator (PLMN or name) and radio technology.""" antennas = result.antennas if operator: wanted = operator.strip().casefold() antennas = [ antenna for antenna in antennas if wanted in {(antenna.plmn or "").casefold(), (antenna.operator or "").casefold()} ] if radio: antennas = [antenna for antenna in antennas if radio.upper() in antenna.radios] return replace(result, antennas=antennas)
[docs] def summarize_antennas( antennas: Sequence[AntennaFeature], ) -> tuple[list[AntennaOperator], list[str], list[Channel]]: """Operators, radios and downlink channels present among ``antennas``.""" operators: dict[str, list[str | int]] = {} radios: set[str] = set() for antenna in antennas: if antenna.operator and antenna.plmn: name = f"{antenna.operator} ({antenna.plmn})" else: name = antenna.operator or antenna.plmn or "Unknown operator" operators.setdefault(antenna.operator_id, [name, 0])[1] += 1 radios.update(antenna.radios) return ( sorted( ( AntennaOperator(id=identifier, name=str(name), count=int(count)) for identifier, (name, count) in operators.items() ), key=lambda item: (-item.count, item.name), ), sorted(radios), downlink_channels(antennas), )
[docs] def as_channel(value: ChannelRange | Mapping[str, float] | Sequence[float]) -> ChannelRange: """A channel given as a range, a ``{"low_mhz", "high_mhz"}`` mapping or ``(low, high)``.""" if isinstance(value, FrequencyRange): return ChannelRange(low_mhz=value.low_mhz, high_mhz=value.high_mhz) if isinstance(value, Mapping): return ChannelRange.model_validate(dict(value)) low, high = value return ChannelRange(low_mhz=low, high_mhz=high)
[docs] def select_channel( result: AntennaQueryResult, channel: ChannelRange | Mapping[str, float] | Sequence[float] ) -> AntennaQueryResult: """Keep the antennas that transmit on ``channel``: those registering a downlink or TDD range that contains it, whatever operator or technology, at their own power. An antenna that registers no frequencies, as with OpenCelliD, is assumed to transmit on it and is counted in a warning.""" channel = as_channel(channel) unregistered = [antenna for antenna in result.antennas if not antenna.bands] kept = [ antenna for antenna in result.antennas if not antenna.bands or antenna.transmits_on(channel) ] warnings = list(result.warnings) if unregistered: warnings.append( f"{len(unregistered)} antennas register no frequencies; they are assumed to " "transmit on the selected channel." ) return replace(result, antennas=kept, warnings=warnings, channel=channel)
[docs] def transmitter_config( antenna: AntennaFeature, *, frequency_ghz: float, antenna_pattern: str, ) -> TransmitterConfig: """A placed antenna as a transmitter of a simulation request, with its provenance.""" return TransmitterConfig.model_validate( { "position": { "latitude": antenna.latitude, "longitude": antenna.longitude, "altitude_m": antenna.height_agl_m, }, "frequency_ghz": frequency_ghz, "power_dbm": antenna.power_dbm, "azimuth_deg": antenna.azimuth_deg, "downtilt_deg": antenna.downtilt_deg, "antenna_pattern": antenna_pattern, "source": { "feature_id": antenna.feature_id, "source": antenna.source, "release": antenna.source_release, "basis": antenna.basis, }, } )
def _record_payload(result: AntennaQueryResult, query: Mapping[str, object]) -> dict: return { "schema_version": ANTENNA_RECORD_SCHEMA_VERSION, "query": dict(query), "source_selection": result.source_selection, "provider": result.provider, "release": result.release, "attribution": result.attribution, "license": result.license, "license_url": result.license_url, "boundary_policy": ANTENNA_BOUNDARY_POLICY, "boundary_excluded_count": result.boundary_excluded_count, "warnings": result.warnings, "channel": result.channel.model_dump(mode="json") if result.channel else None, "antennas": [antenna.model_dump(mode="json") for antenna in result.antennas], }
[docs] def write_antenna_record( directory: Path, result: AntennaQueryResult, query: Mapping[str, object] ) -> Path: """Write the selection into ``antennas/`` and list it in ``scene_info.json``.""" identity = json.dumps( {"query": query, "source_selection": result.source_selection, "release": result.release}, sort_keys=True, default=str, ) resolved = str(result.source_selection.get("resolved", "none")) name = f"{resolved}-{hashlib.sha256(identity.encode()).hexdigest()[:16]}.json" target = directory / SCENE_ANTENNAS_DIRECTORY / name with _scene_lock(directory): target.parent.mkdir(exist_ok=True) dump_json_with_compact_rows(target, _record_payload(result, query), "antennas") info_path = directory / SCENE_INFO_PATH if info_path.is_file(): info = _read_json(info_path) shared = info.setdefault("shared_assets", {}) relative = target.relative_to(directory).as_posix() records = [item for item in shared.get("antenna_records", []) if item != relative] shared["antenna_records"] = [*records, relative] _write_json_atomic(info_path, info) return target
[docs] def write_antenna_source( path: Path, result: AntennaQueryResult, query: Mapping[str, object], channels: Sequence[ChannelRange], ) -> None: """Persist a dataset scene's selected source records, before any placement, with the channels its radio maps draw from.""" payload = { **_record_payload(result, query), "radio_map_channels": [channel.model_dump(mode="json") for channel in channels], } dump_json_with_compact_rows(path, payload, "antennas")
[docs] def load_antenna_source( path: Path, ) -> tuple[AntennaQueryResult, dict[str, object], list[ChannelRange]]: """Read records written by :func:`write_antenna_source`, with the query that chose them and the channels of the scene's radio maps.""" value = _read_json(path) result = AntennaQueryResult( antennas=[AntennaFeature.model_validate(item) for item in value["antennas"]], provider=str(value["provider"]), release=value.get("release"), warnings=[str(item) for item in value.get("warnings", [])], boundary_excluded_count=int(value.get("boundary_excluded_count", 0)), source_selection=value.get("source_selection", {}), attribution=str(value.get("attribution", "")), license=str(value.get("license", "")), license_url=str(value.get("license_url", "")), ) channels = [ ChannelRange.model_validate(item) for item in value.get("radio_map_channels", []) ] return result, dict(value.get("query", {})), channels
[docs] async def scene_antennas( directory: Path, provider: MapDataProvider, *, source: str = "auto", operator: str | None = None, radio: str | None = None, channel: ChannelRange | Mapping[str, float] | Sequence[float] | None = None, defaults: AntennaDefaults | Mapping[str, object] | None = None, ) -> SceneAntennas: """Acquire, place and select the antennas inside a compiled scene, and record them.""" if not isinstance(defaults, AntennaDefaults): defaults = AntennaDefaults.model_validate(dict(defaults or {})) channel = as_channel(channel) if channel is not None else None assets = await asyncio.to_thread(load_scene_assets, directory) acquired = await provider.antennas( assets.origin_latitude, assets.origin_longitude, assets.radius_m, source=source ) inside = keep_inside_scene(acquired, assets) operators, radios, channels = summarize_antennas(inside.antennas) chosen = select_antennas(inside, operator=operator, radio=radio) if channel is not None: chosen = select_channel(chosen, channel) selected = await asyncio.to_thread(place_antennas, chosen, assets, defaults) selected = replace(selected, channels=channels) query = { "source": source, "operator": operator, "radio": radio, "channel": channel.model_dump(mode="json") if channel else None, "defaults": defaults.model_dump(mode="json"), } record = await asyncio.to_thread(write_antenna_record, directory, selected, query) return SceneAntennas(selected, operators, radios, defaults, record)
[docs] async def area_antennas( provider: MapDataProvider, latitude: float, longitude: float, radius_m: float, *, source: str = "auto", operator: str | None = None, radio: str | None = None, channel: ChannelRange | Mapping[str, float] | Sequence[float] | None = None, defaults: AntennaDefaults | Mapping[str, object] | None = None, ) -> SceneAntennas: """Antennas inside a square on the map, completed with defaults but not placed. Placement needs the terrain and buildings of a compiled scene; this view needs neither, so the explorer can show a source's antennas before a scene exists. Nothing is recorded. """ if not isinstance(defaults, AntennaDefaults): defaults = AntennaDefaults.model_validate(dict(defaults or {})) channel = as_channel(channel) if channel is not None else None acquired = await provider.antennas(latitude, longitude, radius_m, source=source) inside = keep_inside_square(acquired, longitude, latitude, radius_m) operators, radios, channels = summarize_antennas(inside.antennas) chosen = select_antennas(inside, operator=operator, radio=radio) if channel is not None: chosen = select_channel(chosen, channel) selected = complete_antennas(chosen, defaults) return SceneAntennas(replace(selected, channels=channels), operators, radios, defaults, None)
[docs] async def load_scene_antennas( directory: Path, *, settings: Settings | None = None, provider: MapDataProvider | None = None, **selection: object, ) -> SceneAntennas: """:func:`scene_antennas` with a provider of its own when the caller has none.""" if provider is not None: return await scene_antennas(directory, provider, **selection) runtime_settings = settings or get_settings() async with httpx.AsyncClient( follow_redirects=True, timeout=runtime_settings.http_request_timeout_seconds ) as client: return await scene_antennas( directory, MapDataProvider(runtime_settings, client), **selection )