# CAKRA — on-demand RF ray tracing (integration prototype)

The VDT browser model and the external ray-tracing solver are separate. Toolbar Run
still computes the existing empirical / diffraction baseline through its credit gate.
External results are reviewed, not substituted into baseline maps, handover or capacity.
This adapter is not a deployed cloud service or an accuracy-certified digital twin.

## Hardware and runtime

CPU means the processor in a laptop/desktop. GPU means a parallel processor that can
accelerate bigger jobs. Runtime means Python plus the solver libraries and drivers.
You do not need an always-on machine: compute when required, save JSON, then stop it.
A separately chosen cloud notebook/VM is another option; prices and access are not
controlled by CAKRA. This workflow neither provisions nor pays for cloud resources.

The adapter targets **sionna-rt 2.2.0**. CPU uses the Mitsuba LLVM backend; GPU uses
CUDA. Follow the official installation and supported-platform requirements:
https://github.com/NVlabs/sionna-rt
https://nvlabs.github.io/sionna/rt/tutorials/Introduction.html

In a runtime you have chosen and authorized, install `sionna-rt==2.2.0`. Installation
is optional and is not performed by this application. LLVM / driver requirements
depend on platform; a Python install alone may not supply them. Start with a small
study. The adapter fails on unavailable backends instead of silently changing solver.

## Inputs needed

1. Authorized inventory: unique sector and measured serving-cell IDs, coordinates,
   height AGL, band/frequency, bandwidth/numerology, **per-port conducted power**,
   feeder loss, antenna gain/pattern and azimuth/electrical/mechanical tilt.
2. GPS route in WGS84 and paired LTE RSRP measurements for validation. NR SS-RSRP / CSI
   power allocation and beamforming require a separate verified radio convention;
   this single-port adapter does not model them.
3. A prepared **Sionna / Mitsuba scene XML and meshes**. Coordinates must use the job's
   WGS84 ENU origin, x=east, y=north, z=up, units=metres. A GeoJSON footprint collection
   alone is not a solver-ready 3D scene. Audit terrain datum, roofs, holes, heights,
   mesh normals, ground alignment and bounds. Do not substitute estimated geometry
   for surveyed geometry without documenting the difference.
4. Frequency-aware EM radio materials (permittivity, conductivity, thickness etc.)
   in the scene, from authorized measurements / material references. Existing manual
   penetration losses in dB are **not** complex EM materials. Review and document
   all approximations. No secretly assigned default concrete / glass parameters.
5. Scene manifest: copied origin, scene reference, alignment/material declarations,
   and SHA-256 of XML plus every local asset filename referenced by the XML.

The runner accepts only one XML, no XML includes. Each asset must stay inside the
scene folder. It reads authorized local files; use only scenes you trust.

Example **structure only** (replace placeholders; this is not test network data):

```json
{
  "sceneReference": "YOUR-SURVEY-REVISION",
  "coordinateSystem": "WGS84-local-ENU-metres",
  "origin": { "lat": 0, "lon": 0, "altitudeM": 0 },
  "geometryAligned": true,
  "materialsReviewed": true,
  "assets": {
    "scene.xml": "SHA256_OF_SCENE_XML",
    "buildings.ply": "SHA256_OF_MESH"
  }
}
```

Copy origin **exactly from the exported job**, not the zeros above. Declarations are
operator assertions, not automated survey certification. The scene digest includes
all declared asset hashes, not just the XML filename.

## Workflow

1. Import a real inventory through Import configuration. Choose an imported / saved
   GPS route; short studies are easier to verify. Inspect the configuration and map.
2. In Ray tracing, enter the scene revision and export `cakra-ray-job.json`.
3. Prepare and verify scene/manifest outside CAKRA. The job contains antenna inputs,
   route positions, terrain/building context and power conventions. No data is sent.
4. Run in your separately prepared CPU/GPU runtime:

```text
python cakra_sionna_runner.py --job cakra-ray-job.json --scene scene.xml --scene-manifest scene-manifest.json --output ray-result.json --device cpu --acknowledge-assumptions
```

CUDA: replace `--device cpu` with `--device cuda`. Default limits: 2,000 sector-receiver
links, batches of 16, 100,000 source samples. Raise limits only after inspecting
memory/time requirements. Existing output files are never overwritten.

5. Reopen that job JSON in CAKRA if needed. Restore its exact inputs first; changes to
   route, radio, antenna, environment or settings invalidate the job binding.
6. Import the result. CAKRA requires the exact job fingerprint, power convention,
   complete unique sector-receiver rows, finite power and explicit null for no path.
   The runner first checks the job hash and its canonical content; editing job fields
   without re-exporting the bound study is rejected before solver execution.
7. Review measured-serving comparisons. Matching uses exact cell IDs and sampled
   receiver coordinates, not arbitrary nearest BTS or a different strongest server.
   A geographic-block / guard holdout is kept separate from fit data.
8. Independently check free-space LoS, a surveyed reflecting wall, and repeat-drive
   residuals before operational use. Increase ray sampling until key results converge.

9. Optionally add `--export-paths` to the runner command. It exports passband-unscaled
   complex coefficients and absolute delays, capped at 4,096 paths/link, 250,000 paths
   total and 40 MB output. Doppler stays null because this adapter has no reviewed UE
   velocity input. Positive-time channel evolution is therefore unresolved, not zero
   motion. The browser checks that incoherent path powers match reported per-RE RSRP.
   Ray tracing review offers RMS delay spread and coherent response at explicit offset
   Hz/time s. Scalar-only results cannot supply phase or coherent response.
10. In Results → Mathematical laboratory select the ray matrix to perform bounded
    sensitivity/Pareto or explicit-traffic fluid DL studies. A hybrid matrix requires
    a matching baseline and an explicit receiver/sector fallback mask. Per-link provider
    provenance remains visible; no-path is not silently filled. These lab calculations
    do not replace the baseline map/handover model or rerun propagation. See
    [mathematical study guide](../twin-mathematics/README.md) for input contracts and limits.

## Model limits / verification status

The runner calls Sionna's actual PathSolver: LoS + specular reflection up to 3 bounces,
deterministic candidate generation, no diffuse scattering, transmission or diffraction
in this initial adapter. It is not a visual line animation. Output uses **incoherent
path-power summation**, not an instantaneous coherent channel realization. TX patterns
include gain and analytic/MSI attenuation; the MSI H/V envelope is not a measured full
complex 3D pattern. Polarization uses one declared slant and a vertical isotropic RX.
There are no NR beams, array precoding, scheduler, throughput or core-network dynamics.
No clutter term, calibration offset or planning margin is added to raw ray power.

TypeScript interchange / invalidation and Python syntax can be tested without a GPU.
Actual Sionna runtime and RF scene validation must be performed in a prepared runtime;
the source does not imply that an end-to-end solver job has already been certified.
SHA-256 binding detects mismatched content; it does not authenticate who created a
result or prove the source geometry/materials are real.

## Field-calibration workflow

Use measured data, inventory, antenna and receiver references in Field calibration.
Fit offsets on fit blocks only; never tune to holdout. Review errors per cell/band/area.
If applying an offset, Run again and inspect the **actual** holdout, not its preview.
Acceptance MAE/RMSE/P90 thresholds are study-specific and editable, not universal
industry guarantees. The record exports input + measurement fingerprints, settings,
split, fit/holdout metrics and the user-declared evidence. Incomplete evidence stays
incomplete. A temporal 70/30 split does not qualify as spatially independent evidence.
Repeat drives and independent survey audit are needed for a field-calibrated twin.