anomaly-detection-material-parameters-calibration

README.md (6488B)

---

 # Overview
 
 This repository contains materials and source code used in Sionna material calibration for jammer/spectrum anomaly detection with the measurements from ["Leveraging the Digital Twin Channel for Spectrum Anomaly Detection: An Experimental Study"](https://doi.org/10.1109/JCS64661.2025.10880629)
 
 The calibration method is taken from ["Learning Radio Environments by
 Differentiable Ray Tracing"](https://doi.org/10.1109/TMLCN.2024.3474639)[1], from [this notebook](https://github.com/NVlabs/diff-rt-calibration/blob/main/notebooks/Learned_Materials.ipynb).
 
 The environment scene can be found [here](https://github.com/akdd11/anomaly-detection-calibrated-raytracing/tree/main/scenes/scene0). Experiments demonstrated better performance, rate of training, and results if a simplyfied scene is used (no furniture, no redundant polygons, only 4 generic materials). Find it in the `scene` directory, along with the blender project file.
 
 **Note**: Sionna has received a major update since the NVidia calibration paper release (see above), so implementation of the method suggested in the related notebook is problematic. Thus this work is done with the older Sionna version (before major 1).
 
 # Physical measurements set up
 
 An automatic moving device travels along a linear trajectory with a constant speed, transmitting a Zhadoff-Chu sequence signal. 3 access points (APs) are located at 3 constant positions, recording the received CIRs along 512 subcarrier frequences. Sampling frequency is 1 sample per millisecond.
 
 Find the eact parameters in the code (`src/??_paths.py`). Unfortunately, the measurement data is not publically available. Please contact [Anton Schösser](https://github.com/akdd11) for the data.
 
 # Repository structure
 
 - `scene`: **Simplified** version of the [scene](https://github.com/akdd11/anomaly-detection-calibrated-raytracing/tree/main/scenes/scene0).
 - `src/measurements.py`: loader function for the measurements dataset.
 - `src/np_paths.py`: numpy-based implementation of the method. Note that the gradient is calculated naively, what is a serious performance bottleneck. This solution can be used for testing, but strugles with production of any results in a reasonable time with bigger parameter domain size.
 - `src/tf_paths.py`: same, but the gradient is calculated using Tensorflow's tape, is in the [NVidia material calibration notebook](https://github.com/NVlabs/diff-rt-calibration/blob/main/notebooks/Learned_Materials.ipynb). Slightly more convoluted than the numpy version and a pain to debug. Currently the graph mode is broken leading to the gradient not being calculated. Finding a way to fix it would solve the np solution's performance issue.
 - `src/v.py`: visualization script. Described below.
 
 # Algorithm
 
 1. Trace paths for N random points along the trajectory. Each of the positions relate to exacly one sample in the measuremnets.
 2. Initialize the trainable parameters, *omega*, which is 2x4x[number of materials]x[number of embeddings], where 2 is [read-out vectors and embeddings vector (*v* and *w*)], 4 is for [conductivity, relative permitivity real part, scattering coefficient, XPD coefficient], number of the materials used by active objects in the scene, and hyperparameter defining the size of the *omega*. See the NVidia paper mentioned above for details. The authors suggest number of embeddings 32.
 3. Fitting:
     1. Compute the gains and delays by calling `Scene.compute_fields`.
     2. Claculate loss between the calculated CIRs (`Scene.cir`), by avaraging along the paths and applying eq. 38 from [1].
     3. Calculate gradient of the objective functon *f* (d*f* / d*omega*) and apply to omega via Adam optimizer.
     4. Calculate the material parameters from *omega* and set into the scene.
     5. If the difference between the current and the previous losses are lower than a certain threshold, assume that the convergance is reached.
 
 # How to use
 
 1. Set up a virtual environment. Note that python version is lower than 3.12 because the next step may not work with this version. 3.10 and 3.11 might also work, but not tested.
 ```bash
 python3.9 -m venv env
 source env/bin/activate
 ```
 2. Install the dependencies. This is important because old versions of Sionna and Tensorflow are used.
 ```bash
 pip install -r req.txt
 ```
 3. Configure the script. Open `??_paths.py` and go through each of the `g_cfg_*` variables. Scroll to the `Scene loading and set up` section and adjust the scene path. Scroll to the `Load the measurements` section and adjust the data path.
 4. `python src/np_paths.py`. Good luck! "Issues" tab is the second from the left.
 5. If `g_cfg_record_loss` and `g_cfg_record_omegas` are set to `True`, `losses.npy` and `omegas.npy` should be created (or **overwritten**). They can be used with `v.py` for visualization.
 ```bash
 python src/v.py ./
 ```
 
 3. Use the results in your code by loading the saved `omega` into the scene. Load the scene with `sionna.rt.load_scene`, read the `omegas.npy` file with `np.load`, take the last `omega`, get the material parameters with the `calc_material_parameters(omega[1], omega[0])` and use the same code as in `set_omega`:
 ```python
 for idx, mat in enumerate(g_trainable_materials):
         g_scene._radio_materials[mat.name].conductivity = cond[idx]
         g_scene._radio_materials[mat.name].relative_permittivity = perm[idx]
         g_scene._radio_materials[mat.name].scattering_coefficient = scat[idx]
         g_scene._radio_materials[mat.name].xpd_coefficient = xpd[idx]
 ```
 
 # Notes
 
 - Main bottleneck of the numpy version is the gradient computation. Other method or parallelization should be considered. Otherwise, allocation for more than 1 CPU is questionable.
 - The computed paths may appear heavy. The number of 150 samples was chosen to fit them all in the 32GB RAM of the system where the implementation was tested.
 - Scene alteration proved to have a noticable impact on the results, both negative and posiitve. Oversimplification demonstrated undesirable effects.
 
 # Vendored code notice
 
 This repository contains a vendored version of [Sionna v0.19.2](https://github.com/NVlabs/sionna/tree/v0.19.2), licensed under the Apache License 2.0. Find the original LICENSE file in `src/sionna/LICENSE`.
 
 # References
 
 [1] - J. Hoydis et al., "Learning Radio Environments by Differentiable Ray Tracing," in IEEE Transactions on Machine Learning in Communications and Networking, vol. 2, pp. 1527-1539, 2024, doi: 10.1109/TMLCN.2024.3474639.