A radio network you can ask what if.

The seven required columns are cell_id, cell_lat, cell_lon, cell_az_deg, cell_carrier_freq_mhz, hTx, cell_el_deg. A made-up tilt gives a confident model of an antenna that does not exist.

The topology is static planning data. The config holds the one value that a what-if changes: the electrical tilt. The measurement report exists only in calibrated mode. The twin reduces it to ten numbers when it reads it.

Locale-tolerant parsing

Some measurement exports write counts ≥ 1,000 as comma-formatted text. Thus the weight column arrives as strings. A simple numeric conversion silently drops the heaviest devices, which carry a large share of the weight. It gives no error.

The reader removes the separators before the conversion. It counts the values that it cannot parse, and writes them to the log clearly. Silent loss of weight in the targets is the failure class that the refusal of defaults is there to stop.

The sample points are a traffic proxy. Users are not at tower bases or in far corners, so a uniform rectangle is a bad proxy.

The wrap-around tier is the surrounding city. It interferes but never serves, and we do not tune it.

Each random draw has its seed from blake2s(name). Thus the environment that a cell sees is a pure function of its id.

Path loss, line of sight and shadow fading (TR 38.901 UMa)

Sector antenna pattern (TR 38.901 §7.3)

The search

The loss is a weighted squared error. The 5th percentiles get more weight, because the guardrails read that tail. The twin calculates the loss through an argmax and a percentile. Thus the loss is piecewise-constant in the parameters and has no gradients.

For this reason the search uses differential evolution (a population search inside the bounds). A bounded Nelder-Mead polish follows. With the targets fixed, calibration is this minimisation:

The measurement report

A measurement report is a per-device export from the analytics tools of a network. Each row is one device and describes the whole day of that device on the network. The report is not a drive test, and it has no location.

The twin never learns from individual rows. It reduces the whole file to ten numbers: the 5th, 25th, 50th, 75th and 95th percentiles of RSRP, and the same five for SINR. These ten numbers are the targets. Two rules apply:

• Weight by report count. A device that sent twenty thousand reports counts twenty thousand times more than a device that sent three. Thus the percentiles describe the network across the traffic, and not across the list of handsets.
• Drop the sentinels. Values at or below −150 are placeholders for "no measurement". The twin removes them before it calculates the percentiles.

The targets are the answer key for the fit: which values of the twelve unknowns make the simulated estate give the same ten percentiles? After the fit, the acceptance gate reads the same ten numbers again.

Why a per-device average changes the physics

Each row is the average of one device over its whole day, at all the places it went. It is not a snapshot at one spot. The average makes the spread smaller, because the high values near the tower and the low values at the cell edge partly cancel.

Thus the raw point samples of the simulation have a distribution that is much too wide to compare with these targets. The twin groups its grid points into pseudo-devices of size agg. It averages them the same way before it calculates the percentiles. This step is the measurement operator, aggregate=True. Without it, the model predicts the wrong quantity, however good the physics is.

Out of sample

With holdout_frac, the twin splits the devices by seed. The fit sees only the training marginals. Then the twin calculates the gate again against the marginals of the unseen devices.

A match to the fitted distribution is necessary but not sufficient. Ten constraints cannot fix twelve parameters. The EIRP window exists because quantile matching alone can accept a power that is physically impossible.

The endpoints run the forward model and summarise the result. They differ only in what they override and how they scope the answer.

Device averaging makes the tilt response of a single cell several times weaker. For this reason an optimiser must read point_sample.

The filter is what a decision hub does with the KPI table before a person sees a recommendation.

Layer 1: the twin refuses

No estate: 409. No model: 409. Unknown cell_id: 422. Null geometry: 422. The twin refuses the whole request for an unknown cell_id. It never ignores the cell silently. Nothing downstream ever runs on a partial answer.

Layer 2: the model qualifies

Each response has its rung. A generic-rung number supports relative comparison only. The gate shows the soft checks but does not enforce them.

Layer 3: the hub guards

The guardrails on delta_vs_baseline have two parts:

• an absolute floor, for example coverage_rate ≥ 0.99
• a regression budget, for example Δ sinr_p5 ≥ −0.5 dB.

Both must hold. A pass goes to pending_approval for a person.

Floors and refits

A refit moves the baseline. Then an absolute floor that was tuned against the previous model refuses every candidate, improvements included. Regression budgets survive a refit, but you must tune absolute floors again with each refit.

The evaluation is also tick-invariant: the same config gives the same KPIs at any time step. Thus per-tick scoping in a UI is cosmetic.