A.T.O.M Docs Ankara Telecom Optimization Model
Product reference

Capabilities

A structured inventory of planning modes, analyses, map evidence, reports, and supported radio technologies.

View Markdown source System architecture

A.T.O.M is a local-first, deterministic RF planning workspace for comparing urban 4G, 5G, and a 6G research profile. Its outputs are planning estimates, not UE or PHY measurements.

Focused Planning Workspace

The workspace has 14 tools in four stages, matching the current tool rail:

Stage Tools
Plan Setup, Inventory, Scenarios
Simulate Propagation, Experiments, Signal surface
Analyze Interference, RF Diagnostics, Building entry, 5G Core
Review Results, Run history, Data, Report
  • Each stage opens one focused tool at a time.
  • A compact command bar keeps the current project, cell context, technology, RF summary, and primary run action visible.
  • The map remains full size while tool and Inspector drawers overlay it.
  • Contextual layers appear only when their results exist.
  • Towers, gaps, communication paths, interference samples, candidate sites, and measurement residuals open persistent Inspector details.

Projects And Scenarios

  • Native browser IndexedDB persistence with automatic last-workspace restoration.
  • Named scenarios preserve exact inputs, selected cells, RF settings, result summaries, model metadata, and recent GeoJSON layers.
  • Rename, duplicate, delete, import, and export bounded project evidence as versioned .atom-project.json files.
  • Result-bearing six-Cell projects use lossless project file v3 with bounded import and preserved Version provenance; valid v1/v2 files remain readable. Scenario Undo restores the same saved identity durably across reload.
  • Input changes mark saved results stale instead of presenting them as current.
  • After a reload, the newest retained Run that computed exactly the restored plan (same request, dataset and model version) is shown as HISTORICAL with its summary; a working draft offers Restore map layers, one explicit RF run, because drafts keep inputs only. When no Run matches, Results says why. Saving a Version right after a run records that Run as the Version's source when the plan is unchanged.
  • Where the plans differ: for two network plans on the current dataset and model (saved Versions, the current plan, or an optimization's baseline and solutions), Results → Compare can show on the map which demand buildings become newly served or lost and where overlap changes, with counts that reconcile with the aggregate KPI deltas. It runs only when you choose Show where they differ (one RF request), and reports include the counts and a static map.
  • Compare any two states in Results → Compare: the current result, the optimization baseline and recommended solution, the inspected Pareto alternative, or any saved Version. One view shows KPI deltas from retained summaries, the input differences and an A/B map switch; states with a different dataset or model version show an incompatibility notice instead of deltas. Baseline vs Recommended stays the default after an optimization, and choosing sources never starts RF work.
  • Promote either comparison side to the active plan without modifying the source snapshot.

Project history is local to the browser. A.T.O.M does not provide accounts, shared editing, or server-side project storage.

Cell Inventory And RF Profiles

Cells and imported tower records are planning inputs. See Cell, sector, site, and tower record terminology before interpreting a Cell as a physical site.

  • Place cells manually on the map, drag editable cells, edit coordinates, duplicate or delete them, and import bounded CSV or GeoJSON inventories.
  • Search the inventory and select cells without losing their per-cell overrides.
  • Configure technology, band, frequency, bandwidth, channel, duplex mode, conducted TX power, absolute TX boresight gain, scalar RX gain, system loss, deterministic polarization loss, radius, beam width, height, mechanical/electrical downtilt, orientation, horizontal/vertical pattern, load, reuse, PCI, receiver height, and either manual receiver sensitivity or a derived receiver mode with noise bandwidth, noise figure, required SNR, and receiver margin independently for every cell.
  • Validate technology/frequency compatibility and all numeric/text limits before RF execution.
  • Persist the complete inventory and profile overrides in schema-v2 project drafts and scenarios; schema-v1 files remain importable.
  • Include resolved per-cell profiles and effective receiver-threshold metadata in simulation, network, interference, recommendation, measurement, and planning-report contracts.

Legacy top-level RF controls remain request defaults. A nested rf_profile overrides those defaults for its cell, so older API clients continue to work while heterogeneous networks can be modeled explicitly.

Propagation And Coverage

Supported Modes

Mode Default frequency Intended use
4G LTE 2.6 GHz Wider urban coverage planning
5G NR mmWave 28 GHz Directional high-capacity planning
6G research profile 140 GHz Comparative planning overlay; not standardized project-level RF quality

The backend exposes explicit propagation modes. urban_short_range is the default at 2.6/28 GHz, legacy_fspl_walls remains selectable, and research_sub_thz is the 140 GHz research-only profile. The separate Building entry analysis estimates service immediately inside a representative facade at 2.6/28 GHz with deterministic low-loss/high-loss O2I scenarios; it does not claim indoor or whole-building coverage. The legacy mode uses free-space path loss with meter/GHz units:

FSPL(dB) = 32.45 + 20log10(distance_m) + 20log10(frequency_GHz)

The urban mode applies the 3GPP UMa LOS/NLOS median path-loss formula after shared 2D footprint classification; it does not add the legacy wall heuristic to empirical NLOS. Every mode applies the explicit link ledger: conducted TX power, absolute TX boresight gain, relative TX pattern attenuation, propagation/building loss, scalar RX gain, system loss, polarization loss, and calibration. Boresight and directional EIRP are reported separately; the legacy effective-transmit alias is retained only for compatibility. Rays are segmented and returned as GeoJSON with model identity, antenna semantics, and explainability metadata.

The ideal-sector, cosine-sector, and panel presets preserve their deterministic analytic equations and hard beam eligibility. The optional 3gpp-single-element preset is a full-azimuth single-element reference based on 3GPP TR 38.901 §7.3/Table 7.3-1; it combines bounded horizontal and vertical cuts with a 30 dB cap and does not model an array factor, beamforming, MIMO, codebooks, vendor diagrams, or measured sidelobes. Positive mechanical downtilt points the antenna boresight downward; mechanical and electrical tilt remain distinct inputs and sum for the current analytic/reference evaluation.

The selected urban_short_range model uses deterministic height-aware footprint centerline obstruction with explicit height provenance. It does not use terrain in the current Ankara network evaluator, Fresnel clearance, diffraction, reflection-heavy multipath, fast fading, MIMO scheduling, or uplink behavior; unknown building heights are conservative NLOS. Static usable reach applies the effective per-cell receiver threshold strictly. A separate path-profile-diagnostic-v1 point-to-point workflow adds terrain/building profiles, LOS and Fresnel classification, material-specific wall planning losses, and an explicitly selected single knife-edge approximation; its result is isolated from network RF. See the Concept 4F.1 design note and the Concept 4G.2 receiver-noise note.

2.5D Path Profiles And Fidelity

  • Loads an optional north-up EPSG:4326 COG/GeoTIFF terrain layer lazily by strip/tile, or a declared standard HGT posting layer, and samples it bilinearly.
  • Combines ground elevation, inferred or explicit building height, transmitter/receiver height above ground, direct geometric LOS, 60% first-Fresnel clearance, and a dominant obstruction. Fresnel concern never changes geometric LOS/NLOS.
  • Provides terrain-profile (30 MHz–6 GHz), urban-short-range (300 MHz–100 GHz), and explicitly out-of-range research profiles. These applicability labels are tracked against ITU-R P.1812-8 (2025-09) and ITU-R P.1411-13 (2025-09); the implementation is an inspectable planning approximation, not either complete method.
  • Exposes free-space, antenna-pattern, conducted-power, TX boresight-gain, directional-EIRP, RX-gain, system, polarization, wall, diffraction, clutter, vegetation, atmospheric-gas, rain, calibration, and shadow-sensitivity components rather than hiding them in one total.
  • Uses the isolated Concept 4F.2 P.526-16 single-edge diagnostic only when explicit or levels-derived roof evidence is available. Generic fallback heights are unavailable for diffraction; the diagnostic is never added to canonical UMa NLOS. Material, gas, and rain controls are planning inputs informed by ITU-R P.2040, ITU-R P.676, and ITU-R P.838, not automatic weather or construction-data inference.
  • Displays a vertical terrain/building/LOS/Fresnel cross section with the loss budget and P50/P90-style shadow-sensitivity bounds.

Demand-Aware Planning

  • Coverage gaps identify demand-building centroids that are inside a sector but below the service threshold.
  • Demand scoring distinguishes POI and residential signals from empty geometry.
  • Single-sector optimization performs a deterministic azimuth sweep.
  • Network evaluation scores two to eight selected cells using coverage, unique demand, and overlap.
  • Network optimization coordinates selected-cell azimuths using selected objectives/weights, optional minimum coverage/demand and maximum-overlap constraints, feasibility violations, and an explained Pareto frontier. Tilt, power, and site selection are not silently adjusted.
  • Optionally report network KPIs inside one drawn area of interest: served demand, residential buildings served and overlap inside the area appear beside the network-wide values in Results and reports. The area scopes reporting only; objectives, scores and the evaluated network are unchanged.
  • Results → Solutions plots the retained Pareto frontier on two selectable objectives (or the optimization score), marking Recommended with a diamond and Selected with a ring. Choosing a point by pointer or keyboard inspects that solution without an RF request; a table lists every plotted solution, and the list shows the top five until you ask for all.

Batch Experiments

  • Sweeps frequency, conducted TX power, beam width, azimuth, and calibration offset across at most 64 deterministic combinations.
  • Executes through bounded asynchronous jobs with progress, cancellation, a dataset/model/request fingerprint, and a small result cache.
  • Compares runs in a scenario table and Pareto view and exports the exact experiment definition.
  • Runs headlessly through go run ./cmd/run-experiment -definition experiment.json or the process/job API.
  • Follows the asynchronous execution shape of OGC API Processes without claiming a complete conformance class implementation.

Analytical Surfaces And GIS Interchange

  • Evaluates bounded regular received-power grids with a 100,000-cell ceiling and produces unsmoothed marching-square isolines.
  • Returns a raw single-cell received-power surface: valid cells below receiver sensitivity remain numeric, while NoData is reserved for radius/beam geometry exclusion; the effective threshold is metadata/statistics, not a mask.
  • Renders the raster below the cell/measurement overlays with opacity and minimum-display-threshold controls.
  • Exports the regular grid as float32 EPSG:4326 GeoTIFF, valid grid cells as CSV, and isolines as GeoJSON.
  • Queries building footprints through mandatory viewport bbox, pagination, a 50 km diagonal ceiling, and a 5,000-feature page ceiling; outputs GeoJSON or CSV/WKT.
  • Provides an opt-in material/height-tinted map overlay at zoom 12 or closer; panning cancels stale requests and loads only the current bounded viewport.
  • Uses OGC API Features-style collections and query parameters, informed by OGC API Features. Vector tiles and GeoPackage export remain future work; OGC API Tiles and GeoPackage are the intended interoperability references.

Interference And Radio Quality

Planning-grade 4G and 5G interference analysis calculates:

  • Serving-cell selection by strongest modeled RSRP, or an explicit serving-cell diagnostic override.
  • RSRP, SINR, RSRQ, RSSI, noise, strongest interferer, and contributing-cell count.
  • Co-channel loading and reuse-factor behavior using linear power addition.
  • Adaptive spatial sampling capped to keep requests bounded.
  • Serviceable, interference-limited, and affected-demand statistics.
  • SINR, RSRP, and RSRQ map surfaces with threshold-specific legends.
  • Uses separate serviceability thresholds (RSRP >= -110 dBm, SINR >= 0 dB, RSRQ >= -20 dB), not receiver sensitivity or the -100 dBm building-service threshold.
  • Keeps receiver noise-equivalent bandwidth and per-RE interference noise separate; receiver sensitivity gates carrier admission but is not added as a second SINR noise term.
  • Exposes raw received carrier power separately from planning RSRP, a linear-domain desired/interference/noise ledger, exact co-channel exclusion reasons, and deterministic scenario fingerprints.

Near-equal co-channel powers can correctly produce SINR near 0 dB; the Inspector explains this and other no-signal or poor-quality states.

Candidate Cell Recommendations

  • Starts from Find an additional Cell in Simulate → Propagation (Network mode) or Results → Candidates, which list the prerequisites (2–5 selected Cells, a search area, a 4G/5G plan) and how to meet each one. Candidates keeps its own Results tab, next to Solutions after a Pareto optimization.
  • Draw search area records the candidate search area without replacing the selected Cells; ordinary area drawing still selects up to eight Cells.
  • Uses unselected towers from the active dataset as candidate records.
  • Restricts candidates to the user-drawn planning area.
  • Prefilters at most 50 records by proximity to unmet demand and evaluates a bounded subset.
  • Accepts up to five existing input Cells; keeps their azimuths fixed and optimizes only the candidate in v1.
  • Returns up to five deterministic options with recommended azimuth, marginal KPIs, score components, and reasons.
  • Applies a recommendation as a new scenario without overwriting the baseline.

Recommendations are RF planning options, not claims of rooftop availability, ownership, permitting, cost, or deployment approval. Candidate scoring intentionally excludes interference; analyze it after applying an option.

CSV Measurement Validation

  • Has its own section in Review → Data, separate from the research campaign evidence workflow in Analyze → RF Diagnostics.
  • Accepts one to six selected 4G/5G Cells, independently of normal network8 and Recommendation5 limits.
  • Imports up to 5,000 CSV records with ID, longitude, latitude, technology, measured RSRP, and optional cell ID.
  • Predicts RSRP at each measurement location using the active selected cells and RF assumptions.
  • Reports residual GeoJSON, MAE, RMSE, mean/median bias, no-signal count, and per-cell statistics.
  • With at least 20 valid points, requires at least five distinct 50 m spatial areas spanning at least 100 m, then evaluates a robust global bias through deterministic spatially blocked five-fold validation.
  • Reports per-cell and per-band residuals, residual-versus-distance and residual-versus-obstruction bins, robust MAD outliers, P50/P90 errors, a median-adjustment confidence interval, fold evidence, and provenance/expiration state.
  • Applies correction only after explicit user confirmation and stores the profile with the project.
  • Invalidates calibration when technology, frequency, model version, or dataset changes.

This is global path-loss bias correction, not full propagation calibration.

Validated Dataset Packs

  • ATOM_DATASET_DIR selects the initial dataset directory; Ankara remains the default.
  • Dataset Pack Studio previews source CRS, coverage, geometry repair/drop counts, and missing fields before building an arbitrary-region pack.
  • Schema v2 records dataset identity, EPSG:4326 bounds, sources, licenses, confidence, generation date, filenames, SHA-256 hashes, per-layer metadata, and quality evidence.
  • Optional terrain, clutter, building-height, and material layers can be packaged and validated for provenance and future model versions.
  • The validator checks hashes, required properties, geometry, coordinate bounds, duplicate IDs, and building-index viability.
  • Invalid packs keep /readyz unavailable with an explanatory error.
  • Active dataset identity and provenance appear in Data, scenarios, reports, and /api/meta.
  • ATOM_DATASETS_ROOT enables a local installed-pack catalog. Switching accepts a manifest ID rather than a path, rejects root escapes and duplicate IDs, validates the whole candidate, and swaps the immutable runtime snapshot only after success.

Schema-v1 packs remain loadable. The application does not perform arbitrary-city live ingestion or large browser uploads; building is an explicit local CLI workflow. The optional terrain layer is consumed only by the 2.5D point-to-point profile. Clutter and material controls can be selected explicitly, but raster clutter and separate height/material sidecar layers are not yet automatically joined into every RF workflow.

5G Communication Paths

The optional 5G Core Lab applies only to 5G mmWave and remains independent from RF interference:

  • Xn-C and Xn-U for eligible neighboring gNB coordination and forwarding.
  • N2 fallback through AMF when Xn is degraded or unavailable.
  • N3 session traffic through UPF.
  • AMF, SMF, UPF, NRF, UDM/UDR, AUSF, PCF, and NSSF status.
  • Deterministic health and Xn scenarios, sessions, and events.
  • Optional probing of configured Open5GS status/metrics endpoints.

It is a planning overlay, not an LTE/EPC model or a complete bundled Open5GS deployment.

Reproducibility And Reports

  • /api/meta exposes application version, build commit, default propagation model and catalog, the RF semantic contract, supported technology capabilities, and active dataset identity.
  • Network responses preserve request-level defaults alongside normalized effective per-cell RF profiles.
  • Scenarios and reports retain exact request inputs and runtime metadata.
  • Markdown and printable PDF reports include RF assumptions, radio quality, communication paths, calibration evidence, recommendations, and scenario comparison where available. The report reader guide explains KPI populations, source identity and PDF print settings.
  • Review package (Review → Report) downloads one local .zip for the current saved Version: the HTML and Markdown reports, the project file, the report map (SVG) and manifest.json with each file's SHA-256, dataset and model identity, Version/Run lineage and the report's limitations. It is built in the browser without an RF request; unsaved drafts are refused until a Version is saved. Hashes support integrity checks, not signing.
  • The downloadable OpenAPI 3.1 specification documents current REST routes and error envelopes.
  • RF requests support cancellation, latest-response protection, a 1 MiB body limit, bounded workers, and 429 overload behavior.

Deliberately Out Of Scope

  • Full 3D reflection-heavy ray tracing, multiple-obstacle diffraction, fading, MIMO scheduling, PHY/MCS/throughput modeling, and UE conformance sensitivity validation.
  • Live network control, LTE/EPC integration, and 6G Core integration.
  • Cloud accounts, multi-user collaboration, and hosted project storage.
  • Guessed cost, fiber, equity, or emergency-priority scoring without authoritative data.
  • Live OSM/OpenCellID ingestion from the browser.

See System Architecture, REST API, RF Algorithms, and Model Limitations.