A.T.O.M

Ankara Telecom Optimization Model | Deterministic RF Planning and Network Analysis

---

Overview

A.T.O.M is a full-stack spatial planning engine for visualizing and evaluating cellular networks across multiple generations (4G LTE, 5G mmWave, and an experimental 6G research profile at 140 GHz) in dense urban environments. Built on OpenStreetMap (OSM) and OpenCellID-derived data, it combines deterministic RF estimation with interactive geospatial analysis so telecommunications engineers and students can compare coverage, antenna configurations, interference, demand impact, and network topology in Ankara, Turkey.

The engine combines bounded Go worker pools, spatial indexing, deterministic ray tracing, and demand-aware search to evaluate urban RF planning scenarios. Results are planning estimates derived from static OSM and OpenCellID data; they are not drive-test, UE, or PHY measurements.

---

Key Features

• Focused Map Workspace: Organizes setup, propagation, interference, 5G Core, results, data assumptions, and reports in a compact workflow rail while keeping the map primary.

• Multi-Generation Planning Presets: Evaluates 4G (2.6 GHz) and 5G (28 GHz) with the explicit urban_short_range LOS/NLOS baseline, keeps legacy_fspl_walls selectable, and labels 6G (140 GHz) as the research_sub_thz planning profile.

• Segmented Heatmap Raytracing: Generates GeoJSON ray segments that change color based on modeled signal strength (Rx dBm), providing interactive visual feedback on coverage quality.

• Explainable Propagation Modes: Shared model dispatch, applicability checks, deterministic height-aware footprint LOS/NLOS classification with explicit height provenance, conservative unknown-height handling, terrain status, explicit legacy fallback, and per-response model identity keep urban NLOS path loss separate from legacy wall-event loss.

• Sector Planning: Fast sector simulation with adjustable azimuth and beam width. The sector engine uses analytic antenna presets and does not model reflection-heavy multipath, fading, multiple-edge diffraction, or MIMO scheduling.

• 2.5D Path Profiles: Optional COG/GeoTIFF terrain, building-height obstruction, LOS/Fresnel evidence, selected single knife-edge diffraction, inspectable fidelity components, and a vertical cross section.

• Experiments And Surfaces: Asynchronous reproducible parameter matrices, Pareto evidence, regular coverage rasters/isolines, and GeoTIFF/GeoJSON/CSV interchange.

• Per-Cell RF Inventory: Places, drags, duplicates, imports, validates, and persists cells with independent technology, band/channel, duplex, power, gain/loss, antenna geometry and patterns, load/reuse, PCI, and receiver assumptions.

• Interference Analysis: Produces planning-grade RSRP, SINR, RSRQ, RSSI, serving-cell, and strongest-interferer surfaces for selected 4G and 5G cells.

• Deterministic Network Optimization: Sweeps candidate azimuths and scores sectors or two-to-six-cell clusters using POI demand, residential-density demand, coverage, and overlap penalties.

• Coverage Gap Finder: Flags demand-weighted buildings inside the active beam whose raw received power does not exceed the separate -100 dBm building-service threshold, helping planners see underserved residential and POI targets instead of only raw ray distance.

• Building Entry Analysis: Estimates deterministic 2.6/28 GHz low-loss and high-loss service immediately inside representative building facades with one batched request, optional material evidence, and no indoor or whole-building claim.

• 5G Communication Paths: Separately visualizes direct Xn-C/Xn-U coordination, N2 fallback through AMF, and N3 user-plane routing through UPF when the optional 5G Core Lab overlay is enabled.

• Operational Safeguards: Uses request cancellation, latest-response protection, bounded worker pools, request-size limits, readiness probes, and explicit 429 overload responses.

• Local Projects and Scenario Comparison: Autosaves planning drafts in IndexedDB, exports versioned project files, retains reproducibility metadata, and compares two saved RF scenarios without adding another workspace tool.

• Candidate Cell Recommendations: Ranks known, unselected planning records inside a drawn search area by marginal coverage, POI/residential demand, and overlap. Recommendations do not claim site availability, cost, backhaul, or permitting feasibility.

• Measurement Validation: Imports up to 5,000 4G/5G RSRP samples, maps model residuals, reports MAE/RMSE/bias, and offers an explicitly labeled holdout-checked global dB correction when enough valid samples exist.

• Dataset Pack Studio: Inspects, repairs, reprojects, crops, and packages arbitrary-region local data into schema-v2 packs with hashes, licenses, confidence, coverage/field QA, and optional terrain, clutter, height, and material layers.

• Validated Dataset Switching: Lists only packs installed beneath ATOM_DATASETS_ROOT and atomically activates a fully validated pack by manifest ID, retaining the current immutable pack if validation fails.

---

Architecture & Tech Stack

Component	Technology	Purpose
Backend	Go (Golang)	Bounded RF worker execution, validation, resource controls, and in-memory R-Tree spatial queries
Frontend	React + Leaflet	GeoJSON and canvas-backed map layers with interactive simulation controls
Data Pipeline	Python + OSMnx	Local tower/building extraction and demand-surface enrichment
Runtime Data	Schema-v2 manifest + geospatial files	Validated local dataset packs loaded into immutable in-memory snapshots; no database required
Deployment	Docker	Multi-stage build compiling both React and Go into a single, lightweight Alpine container

---

Codebase Structure

backend-go/       Go API, in-memory R-tree, ray tracing, azimuth optimization
frontend-react/   React/Vite/Leaflet dashboard and RF heatmap UI
policy/           Canonical Core Lab, RF default, technology, and validation policy
data-pipeline/    Python scripts for local tower/building data generation
docs/             GitHub Pages documentation, search index, references, canonical assets
Dockerfile        Production multi-stage build for the static in-memory app

Generated artifacts such as frontend-react/dist/, local virtual environments, OSMnx responses in data-pipeline/cache/, and build caches are intentionally ignored and excluded from Docker build contexts. The large Ankara building GeoJSON is stored through Git LFS.

Runtime policy bindings are generated from policy/rf-policy.json. After changing that source, run python3 scripts/generate_policy.py; CI runs the same command with --check so backend, adapter, and frontend policy copies cannot drift.

---

Focused Workspace

The current interface uses a compact command bar, workflow rail, overlay tool drawer, contextual result summary, independent map layers, and persistent inspectors. The map's RF controls separate the received-power surface from diagnostic rays, with explicit all/selected/hidden ray scope and a map-focus cell that is independent from Pareto solution inspection. Radio-parameter edits mark existing results as stale without submitting hidden requests, while Run Sector, Evaluate Network, and tool-specific analysis actions keep execution visible.

---

Propagation Visualization

4G Coverage

5G Coverage

6G Research Profile Coverage (140 GHz)

Auto-Optimized 5G Beamforming

Visualizing multi-generation RF propagation patterns and deterministic antenna-placement recommendations in urban environments.

---

Getting Started with Docker

Prerequisites

• Docker with Compose
• Git and Git LFS

Clone, Build, and Run

The 111 MB Ankara building dataset is managed by Git LFS, so clone the repository with LFS enabled:

git lfs install
git clone https://github.com/Berk-Unsal/atom.git
cd atom
git lfs pull
docker compose up --build -d atom

Open http://localhost:8080 and verify readiness with curl http://localhost:8080/readyz.

For a settings-first verification without bundled analysis output, import examples/ankara-sample.atom-project.json from the project menu, select two local cells, and run Evaluate Network.

Validate the bundled dataset pack independently:

cd backend-go
go run ./cmd/validate-dataset ../data-pipeline

To build another geography, use the local Dataset Pack Studio, validate its output, and set ATOM_DATASET_DIR to the initial pack. Mount a parent directory as ATOM_DATASETS_ROOT to list and safely switch among installed packs from the Data tool without restarting.

Optional Core Lab Mode

Core Lab Mode is opt-in. The default app does not start any 5G Core containers or require Open5GS.

export CORE_LAB_API_KEY="$(openssl rand -hex 32)"
docker compose -f docker-compose.yml -f docker-compose.core-lab.yml --profile core-lab up --build

This starts A.T.O.M with CORE_LAB_ENABLED=true and a lightweight core-lab-adapter sidecar reachable only over the Compose service network. Scenario mutation requires CORE_LAB_API_KEY; a same-origin gateway should inject the key for browser requests instead of exposing it to JavaScript. The adapter runs as a non-root user with a read-only filesystem and exposes stable Core Lab JSON for AMF, SMF, UPF, UDM/UDR, AUSF, PCF, NRF, and NSSF status. If no Open5GS endpoint is configured, scenario effects are marked as a deterministic simulated_overlay; point OPEN5GS_STATUS_URL or OPEN5GS_METRICS_URL at a real Open5GS lab to bridge external emulator state.

Suggested Docker memory allocation:

Profile	Memory	Use
core-lite	4-6 GB	A.T.O.M + adapter status bridge
core-demo	8-12 GB	Adapter + simulated gNB/UE session overlays
core-observe	12-16 GB	Full Open5GS lab plus metrics/observability

---

Documentation

Start with the static documentation hub, then use:

• System architecture for runtime components, request lifecycles, spatial data, reliability controls, and model boundaries.
• Product compass for enduring product strengths, capability horizons, feature-admission criteria, and deliberate non-goals.
• Download and use for Docker, source development, Core Lab, troubleshooting, and guided workflows.
• Getting started for the Markdown onboarding reference.
• REST API, downloadable OpenAPI 3.1 contract, RF algorithms, Dataset Pack Studio, and model limitations for implementation details.
• Map interpretation guide for reading propagation and radio-quality evidence.

Versions and Release Notes

A.T.O.M uses Semantic Versioning. VERSION is the canonical application version and CHANGELOG.md records user-visible additions, changes, and bug fixes under Unreleased until a release is prepared.

The same release history is available as a searchable documentation changelog.

Creating a matching vX.Y.Z tag runs consistency checks, publishes multi-architecture GHCR images, and creates a GitHub Release announcement from that version's changelog section. Contributors can verify the release metadata locally with:

python3 scripts/versioning.py check

Resolved defects and their regression coverage are tracked in the bug-fix register.

---

Author & Credits

Architected and Developed by Berk Ünsal

This project demonstrates the practical intersection of spatial algorithms, bounded concurrent systems design in Go, and planning-grade telecommunications simulation.

---

Deterministic, inspectable, and explicit about model limits.