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. Measured real-world propagation accuracy is not yet established.
A first planning question: does changing a small urban Cell plan's azimuths better serve the configured demand? Configure two to eight Cells, evaluate a baseline, inspect propagation and 4G/5G interference, run bounded azimuth optimization, compare the recommendation and its explanations, then export the planning evidence. The recommendation reflects the model, inputs and priorities; it is not deployment approval. Start with the first planning workflow.
Version 0.13.1 refreshes contributor and planning guides, adds a reproducible two-Cell Ankara walkthrough, improves documentation readability, and patches frontend development dependency advisories. Application behavior is unchanged.
| Workflow | Current scope |
|---|---|
| Sector propagation and auto-optimization | One active cell |
| Network evaluation, interference, and azimuth optimization | Two to eight selected cells; interference is available for 4G/5G |
| Candidate cell recommendations | Up to five existing cells in the input network |
| Measurement validation | One to six cells and up to 5,000 4G/5G RSRP samples |
The eight-cell operational qualification covers the Ankara2026.07 dataset at 120 rays, 400 m radius, 30 dBm, a 120° beam, and 2.6/28 GHz with the legacy two-pass search on Profile A (2 CPUs, 4 GiB, Go 1.26.6 Linux/arm64). Capacity at heavier settings or on other datasets and hardware depends on the workload. See the qualification report for the measured scope.
-
Map-First Workflow: Four stages—Plan, Simulate, Analyze, and Review—organize cells, scenarios, propagation, diagnostics, results, and reports around the map. Separate Inspect and Select cells modes provide contextual cell, building, and interference-sample details.
-
Light, Dark, and System Appearance: Persists local appearance preferences, with Alidade Smooth light/dark basemaps, selectable OpenStreetMap, and consistent RF palettes.
-
Multi-Generation Planning Presets: Evaluates 4G (2.6 GHz) and 5G (28 GHz) with the explicit
urban_short_rangeLOS/NLOS baseline, keepslegacy_fspl_wallsselectable, and labels 6G (140 GHz) as theresearch_sub_thzplanning profile. -
Signal Surfaces and Diagnostic Rays: Displays received-power surfaces independently from segmented GeoJSON rays colored by modeled Rx dBm. Show all, selected, or hidden rays and focus a cell without launching new RF work.
-
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. P.526/path-profile diffraction and terrain evidence are diagnostic and do not add loss to canonical urban RF evaluation.
-
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. Co-located sectors can be placed and managed together as a site group while remaining ordinary Cells in RF requests.
-
Inspectable Link Budgets and Receiver Thresholds: Distinguishes conducted power, EIRP, absolute antenna gain, pattern attenuation, receiver gain, and polarization loss. Manual sensitivity remains available alongside opt-in thermal-noise-derived per-cell thresholds, separate from building-service and interference criteria.
-
Interference Analysis: Produces planning-grade RSRP, SINR, RSRQ, RSSI, serving-cell, and strongest-interferer surfaces for selected 4G and 5G cells.
-
Deterministic Network Optimization: Optimizes sectors or two-to-eight-cell networks using POI demand, residential demand, propagation reach, and overlap. Network results include a normalized 0–100 score, configurable priorities and constraints, feasible Pareto solutions, baseline impact, and per-cell explanations. Optional multistart and Pareto-archive search policies and a 4G/5G radio-quality objective support deeper analysis.
-
Coverage Gap Finder: Flags demand-weighted buildings inside the active beam whose raw received power does not exceed the separate
-100 dBmbuilding-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
429overload responses. The request budget retains 20 ordinary attempts per client IP per 60 seconds, with up to eight shared, input-bound verified follow-up units for eligible network-map and azimuth refreshes. -
Local Projects, Scenario Versions, and Run History: Autosaves drafts in IndexedDB, saves immutable scenario Versions, supports branching and input comparisons, and retains Run lineage with explicit current, stale, and historical result context. Project schema-v3 exports preserve retained Scenario results and Version/embedded Run provenance, with valid v1/v2 imports supported. They exclude the separate Run History database, generated report files, coverage surfaces and transient view/Undo state; download reports separately. Imports retain a 16 MiB file ceiling and decoded-content limits; large ray-bearing exports can still exceed those guards.
-
Reproducible Planning Reports: Generates local Markdown/HTML report artifacts from current or historical Runs, with exact scenario Version/Run lineage, SHA-256 verification, baseline/Pareto evidence, and offline downloads. A saved Version can also be exported as a review ZIP with its report, project, map, and integrity manifest; reports can include area-scoped network KPIs and plan-difference maps.
-
Candidate Cell Recommendations: Ranks known, unselected 4G/5G planning records inside a drawn search area by marginal coverage, POI/residential demand, and overlap, using up to five existing cells. Recommendations do not claim site availability, cost, backhaul, or permitting feasibility.
-
Measurement Validation: Evaluates up to 5,000 4G/5G RSRP samples against one to six cells, maps residuals, and reports MAE/RMSE/bias, spatially blocked validation, and uncertainty evidence. An explicitly labeled holdout-checked global dB correction is available when enough valid samples exist.
-
Research and Reference Diagnostics: Provides isolated applicability-gated sub-THz atmospheric, P.1411, material/facade, measurement-evidence, and single-bounce reflection reference workflows. These tools expose their provenance and limits without automatically changing canonical network RF.
-
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_ROOTand atomically activates a fully validated pack by manifest ID, retaining the current immutable pack if validation fails.
| 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 |
backend-go/ Go API, in-memory R-tree, ray tracing, azimuth optimization
core-lab-adapter/ Optional 5G Core Lab status and scenario bridge
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
examples/ Importable local planning projects
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.
The screenshots below show the 0.12.0 workspace on the Ankara dataset with the 5G mmWave preset at 28 GHz.
Eight selected cells, their antenna directions, the planning area, and received-power ray colors remain visible alongside the command bar and map key.
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.
The Simulate stage keeps ray count, radius, azimuth, and beam width in Planning, with specialist options under Advanced analysis and Research / reference.
The Review stage shows the recommendation's score, baseline deltas, raw metrics, feasible non-dominated solutions, and source Run. Values in this screenshot belong to the illustrated scenario.
Single mode provides Run Sector and Auto-Optimize Sector actions for the active cell, with the same propagation controls and diagnostic disclosures.
4G uses the 2.6 GHz planning preset; 6G uses the experimental 140 GHz research_sub_thz profile. Interference, building-entry analysis, recommendations, and standard measurement validation remain restricted to 4G/5G. See the capability reference and model limitations for workflow-specific applicability.
- Docker with Compose
- Git and Git LFS
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 atomOpen http://localhost:8080 and verify readiness with curl http://localhost:8080/readyz.
For a settings-first verification without bundled analysis output, choose Open sample network project on the first-run card (it opens examples/ankara-sample.atom-project.json as a new project and selects the two Cells nearest the pre-selected sector), then run Evaluate Network. You can also import the file from the project menu and select two local Cells yourself.
Validate the bundled dataset pack independently:
cd backend-go
go run ./cmd/validate-dataset ../data-pipelineTo 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.
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 --buildThis 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 |
Start with the static documentation hub, then use:
- System architecture for runtime components, request lifecycles, spatial data, reliability controls, and model boundaries.
- Product roadmap for workflow priorities and the independent evidence gates; check linked GitHub issues for current status.
- Download and use for Docker, source development, Core Lab, troubleshooting, and guided workflows.
- Getting started for the Markdown onboarding reference.
- Two-Cell planning walkthrough for a fixed Ankara baseline, recommendation, overlap trade-off and reviewable project/report exports.
- 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.
Read the contribution guide for a complete Git LFS checkout, Docker and Go/Vite development, focused tests and the full validation matrix. Start with an existing GitHub issue and use the PR template to describe impact and validation.
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 checkResolved defects and their regression coverage are tracked in the bug-fix register.
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.