# CAKRA — evidence-constrained mathematical VDT studies

This guide is for users. No app installation, administrator access or AI upload is
required for the mathematical laboratory. A separately prepared Sionna runtime is
needed only when computing actual RF ray tracing. None is provisioned by these controls.

## 1. Preserve the measurement layer

Import your authorized G-Net log normally. In VDT → Field calibration → Measurements,
run the local audit. Use the complete `LTE:PLMN:ECI:EARFCN` mapping key, not a short
sector ID shared by different cells. Unknown/mixed RAT is not LTE calibration evidence.
SS-RSRP, CSI-RSRP and a generic 5G `Level` are not interchangeable measurements.
Repeated GPS and same-second observations remain visible; they are not extra independent
survey positions. A clock without an explicit offset is not assigned a timezone as fact.

Reconstruction uses a WGS84 direct geodesic from receiver GPS, logged Distance and
Bearing. Declare the original distance unit (`m` or `km`) and your minimum unique-GPS
count/P90 disagreement criterion. Distance/Bearing can derive from a loaded cellfile.
The result is a consistency check of that logged location, NOT proof of BTS position.
It does not manufacture missing equipment, power, frequency, height or tilt information.

## 2. Referenced-input Run

Evidence mode starts enabled. Complete the actual configuration and route, then download
the Input references template. Its `inputFingerprint` binds those exact inputs. Each
entry needs its exact value, source reference and basis (`measured`, `survey`, `datasheet`,
`configured` or `fit-only`), plus a model reference. A blank reference or null required
value stays unresolved. Modifying the configuration requires a new matching template.

Complete DEM cells/endpoint coverage, non-estimated building heights, environment and
material inputs, and explicit monotonic route timing are required by this mode. Missing
inputs stop Run BEFORE requesting credit. References are declarations, not independent
verification. Configured exploration is available only by intentionally disabling
Evidence mode and must not be reported as field-calibrated. All numerical models have
stated abstractions; a formula alone is not a measurement or proof of accuracy.

For calibration, pair the exact measured LTE serving cell with its mapped sector.
Use spatial fit/holdout blocks and a positive guard. Fit offsets only on fit data,
then Run again and evaluate actual holdout MAE/RMSE/P90. Do not tune against the holdout
or present the offset preview as acceptance. A separate repeat drive is still needed.
Acceptance targets start blank. Supply your study's MAE/RMSE/P90 limits and criteria
reference; no preset threshold is promoted to an evidence-backed acceptance decision.

## 3. Freeze the complete link matrix

In Results → Mathematical laboratory choose:

- **Use Run matrix**: powers already produced by the selected prediction. Old archives
  without all-sector powers require a new Run; missing powers are not reconstructed.
- **Use ray matrix**: the currently matched external ray result.
- **Import matrix**: a separately documented `cakra.link-study` JSON. It does not apply
  to your draft. Its full input hash and source references remain visible.
- **Hybrid · import mask**: identical analytic/ray physical inputs, route and spectrum,
  plus explicit fallback pairs: `[ {"sampleId":"rx-0","siteId":"YOUR_SECTOR"} ]`.
  A physical ray no-path is never silently filled. Each final link retains its provider.

The matrix includes sector order, occupied bandwidth, SCS, noise per RE, every receiver,
every sector power and timing. A no-path power is `null`, never an invented −160 dBm.
Existing Run costs apply to new propagation calculations; lab calculations do not rerun
propagation. Downloaded matrices contain location/network information: share carefully.

## 4. Sensitivity and Pareto

Select Sensitivity & Pareto and download its template. Fill all nulls explicitly:

| Field | Meaning / units |
| --- | --- |
| `reference` | Source of this experiment and decision criteria |
| `serviceThresholdDbm` | Your study's coverage criterion, dBm |
| `variants[].id` | Unique experiment variant |
| `candidate` | Candidate shared by its sensitivity variants |
| `powerDeltaDb[]` | Per-sector power change, dB, in exported sector order |
| `activity[]` | Explicit interferer activity fractions, 0–1, same sector order |
| `lossDeltaDb` | Added common link loss, dB |
| `noiseDeltaDb` | Added receiver noise relative to matrix, dB |
| `cost` | Nonnegative user-defined cost; same value for each candidate's variants |

Import & compute evaluates ONLY submitted variants. Best-server selection maximizes
received power. SINR sums interferer powers and noise in linear units, with rectangular
spectral overlap and SCS scaling between per-RE powers. This is not CRS/SSB collision,
ACLR/ACS or interference decoded from an idle G-Net bitrate.

Coverage = eligible receiver count / ALL receiver count, including no-path failures.
P10 SINR uses nearest-rank ordering among available SINR values. A completely unresolved
SINR candidate is not promoted to the Pareto set. Reports retain no-path counts; do not
hide them by quoting the conditional SINR statistic alone.

Pareto maximizes worst-case coverage and worst-case P10 SINR, minimizes declared cost
and maximum best-server transitions. There are no invented weights and no automatic
live-network action. A best-server change is not a decoded protocol handover. If your
input ranges have no calibrated probability distribution, outputs are finite sensitivity
ranges/stability, NOT confidence intervals or likelihood of real-world success.

Geometry/frequency/pattern/tilt changes require separate propagation Runs and should be
compared using the existing A/B workflow. Frozen-link power perturbations do not replace
those RF calculations. Limits: 5,000 receivers, 50 sectors, 200 variants and bounded work.

## 5. UE trajectories and scheduler

Select UE trajectories & scheduler and download its template. Provide:

- `reference` for traffic/trajectory inputs and `curveReference` for BLER provenance.
- `slotMs`, `slots`, `resourceChunks`, `averagingSlots`, positive `initialAverageMbps`.
- `targetBler`, explicit `overheadFraction`, `layers`, per-sector `initialActivity[]`.
- Each MCS curve: `mcs`, `spectralEfficiency` (bits/s/Hz), increasing `sinrDb` points and
  non-increasing `bler` values in [0,1]. Curves must match the studied RAT/receiver/decoder.
- Each UE: unique `id`, nonnegative `initialQueueBits`, and exactly `slots` entries in
  both `sampleIndices[]` and `arrivalBits[]`. Indices are ZERO-BASED matrix receiver
  positions. Arrivals are new bits in that slot; do not mix bytes, Mbps and bits.

Curves are linearly interpolated ONLY in their provided SINR domain. A missing usable
curve/no-path leaves the UE unresolved for that slot and retains its queue. It does not
silently claim zero BLER. The available raw-rate abstraction is:

`occupiedBandwidthHz × spectralEfficiency × layers × (1 − overheadFraction)`.

Proportional-fair allocation uses expected goodput / EWMA delivered throughput, with
intra-slot fairness. All UEs associated with a sector share its bounded resource chunks.
Attempted bits consume airtime; expected BLER bits remain queued for later opportunities.
The invariant is initial queued bits + arrivals = delivered bits + final queued bits.
Interference uses previous-slot activity with your explicit initial activity, not a
fully converged same-slot solution.

This is a deterministic expected-value **fluid DL abstraction**, not complete Sionna SYS,
TBS, HARQ ACK/timing/combining, RLC, packet latency, carrier aggregation or RRC emulation.
`expectedFailedBits` counts expected failed attempts, not unique lost packets. Do not
claim observed service outcomes from this calculation. Up to 2,000 slots/100 UEs are
accepted subject to the operation budget; split large studies deliberately.

## 6. UL power control

Select UL power control; a link matrix is not needed. Fill the template's reference,
UL `pathLossDb`, `p0Dbm`, `alpha`, `resourceBlocks`, `numerology`, `deltaTfDb`,
`closedLoopDb`, and `pMaxDbm`. The implemented, traceable control abstraction is:

`Ptx = min(Pmax, P0 + 10 log10(2^mu × M_RB) + alpha × PL + deltaTF + f)`.

Headroom uses Pmax minus the requested uncapped power; negative means power-limited.
This is not an UL SINR/coverage/BLER prediction. DL RSRP is NOT automatically converted
to UL path loss; reciprocity and reference-power conventions require actual evidence.
Download the full inputs and calculation for review.

## 7. Complex ray paths

The optional runner's `--export-paths` includes passband-unscaled complex coefficients,
absolute delays and explicit Doppler (null when unavailable). Import consistency checks
bind the path-power sum to the declared per-RE RSRP. In Ray tracing review select receiver
and sector, enter frequency offset Hz and elapsed time seconds explicitly, then calculate.

`H(Δf,t) = Σ a_p exp(−j2π(fc+Δf)τ_p) exp(j2πν_p t)`.

RMS delay spread uses incoherent |a_p|² weights. Coherent |H|² is dimensionless channel
gain, not throughput or a fabricated field measurement. Unknown Doppler blocks t>0
instead of treating a moving UE as stationary. Path phases cannot be recovered from
scalar RSRP; scalar-only imports remain scalar-only. The runner does not invent velocity.

## 8. Projects, jobs and computation plans

In History export a named project revision. Configuration, complete DEM and buildings
are bundled with checksum, parent revision and engine/math versions. Opening is review
only; Apply is separate. Save lab results and calibration evidence alongside the project.
Files are local, not persistent hosted city projects. Checksums bind content, not truth.

Tile-plan export uses your explicit metre size and local ENU frame. It partitions
receivers while retaining ALL transmitters and full geometry/settings dependencies.
Unchanged receiver groups can retain keys; changed physical inputs invalidate keys.
This is a manifest, not an automatically deployed or computed city-wide solver.

Math jobs are cancellable browser-worker tasks with exact-input, algorithm-versioned,
session-memory LRU cache. A changed request is not a cache hit. No persistent cloud job
queue, billing or external upload is activated. A reload discards this session cache.

## Mathematical checks are not field validation

Golden formula tests, parser audits and deterministic replay demonstrate software
consistency only. Real-world accuracy still needs verified equipment, aligned environment,
paired field data and independent holdout/repeat validation. Without those inputs CAKRA
can audit your measurements and prepare the workflow, but cannot honestly certify an
operational, city-scale 1:1 twin. AI does not override this evidence boundary.

Primary references: [G-NetTrack manual](https://gyokovsolutions.com/manual-g-nettrack/),
[Sionna RT path conventions](https://nvlabs.github.io/sionna/rt/api/paths.html),
[Sionna SYS scheduling](https://nvlabs.github.io/sionna/sys/api/scheduling.html),
[Sionna SYS power control](https://nvlabs.github.io/sionna/sys/api/power_control.html).