JeevaKeshav/UCINet0_PUCCH-Format-0-ML

UCINet0: PUCCH-Format-0-ML

This repository provides scripts and tools to generate, combine, train, and test PUCCH Format 0 datasets using MATLAB and Python. The workflow covers end‑to‑end signal generation, UCINet0 training, evaluation, and real‑world testing.

Overview

Two main stages:

1. 1.Dataset Generation (MATLAB) — Create PUCCH Format 0 frequency‑domain complex sample datasets.
2. 2.Model Training & Testing (Python) — Train and evaluate a neural network using the generated datasets.

PART 1: Generating Datasets (MATLAB)

Requirements

• —MATLAB 2024b
• —Add-ons required:
• —5G Toolbox
• —Parallel Computing Toolbox
• —Signal Processing Toolbox

Datasets/datagen_main.m

This is the main MATLAB script for dataset generation (.mat files). It includes built‑in transmitter and receiver implementations for PUCCH Format 0.

Key Configurable Parameters

<!-- - Most common configurable parameters are as follows:

• —Channel Model:
• —Default: TDLC300
• —Other tested options: TDLC30, TDLA30, TDLA300
• —To update from TDLC300 to TDLA30, change the channel_model = ['fading_TDLA30_',fd_str,'_Hz'] channel.DelayProfile = 'TDL-A' (at multiple locations) channel.DelaySpread = 30e-9 (at multiple locations)

• —Doppler frequency shift:
• —Default: fd = [0:400:2000]
• —Any range and granularity can be configured

• —Signal-to-Noise Ratio (SNR):
• —Default: SNR = (0:2:20)
• —Any range and granularity can be configured

• —No. of interations for each SNR:
• —num_iter_per_slot = 1000 set by default
• —So, 1000 slots with each of 168 PUCCH Format 0 instances are generated per configured parameter

• —parfor (parallel processing) with 32 workers is enabled by to speed up the data generation process
• —Run this datagen_main.m in Matlab once the parameters are configured as desired

• —The individual dataset (extracted PUCCH Format 0 frequency domain complex samples) of each permutation of the configuration parameters is run iteratively (automatically) and stored with appropriate folder and file names at Datasets/Datafiles/Simdata/PerSNR_data/ -->

Output Location

Datasets/Datafiles/Sim_data/Per_SNR_data/

Each dataset corresponds to a permutation of configuration parameters and stores extracted complex frequency‑domain PUCCH Format 0 samples.

Combining Datasets for Neural Network Input

Use combine_datasets.m to merge individual datasets into a unified format for training or inference.

Configuration Notes

• —Ensure the following match datagen_main.m:
• —SNR, num_iter_per_slot, channel_model
• —Choose data source:
• —out_data_format = 'sim' → Simulation (default)
• —out_data_format = 'hw' → Hardware dataset (indoor lab)

Example Scenarios

Training Scenario train_scenario = [3] is set to generate training dataset with parameters: SNR = 10 dB, nummuxUE = 0:12, fd=[0:400:2000], metadata_offset = 2

Testing Scenario test_scenario = [1:2] Generates the dataset per SNR, metadataoffset, and nummux_UE

Combined Dataset Output

Datasets/Datafiles/Sim_data/Data_for_NN/

<!--

• —Ensure that parameters like SNR, numiterperslot, channelmodel matches with the datagen_main.m parameters used while generating the samples

• —Choosing Simulation or hardware data generation:
• —out_data_format = 'sim' is chosen by default.
• —Change to 'hw' to generate hardware (indoor lab) dataset

• —Training:
• —train_scenario = [3] is set to generate training dataset with parameters: SNR = 10 dB, nummuxUE = 0:12, fd=[0:400:2000], metadata_offset = 2

• —Testing:
• —test_scenario = [1:2]
• —This generates the dataset per SNR per metadataoffset and per nummuxUE per metadataoffset

Other codes

• —combineaccuracyfd.m, combine_accuracy.m helps obtain the accuracy values for the combined dataset generated above.-->

Accuracy Scripts

• —combine_accuracy_fd.m
• —combine_accuracy.m Used to compute accuracy metrics from combined datasets.

PART 2: Model Training and Testing (Python)

Requirements

• —Python: 3.10.12
• —TensorFlow: 2.15.0
• —CUDA: 12.4
• —GPU: (e.g., NVIDIA A100 80GB PCIe)

Setup procedure

1. 1.Install python virtual env package: sudo apt install python3-venv
2. 2.Create a virtual env named tf: python3 -m venv tf
3. 3.Source and install tensorflow and other dependencies:
4. 4.source tf/bin/activate
5. 5.python -m pip install tensorflow==2.15
6. 6.or (for GPU) python3 -m pip install 'tensorflow[and-cuda]==2.15.0.post1'
7. 7.pip install -y numpy scipy math matplotlib seaborn scikit-learn mat73
8. 8.To exit the environment: deactivate

Training the Neural Network

Configuration file: config_params.py

Important Parameters

Ensure that the SNR, trainchannelmodel, trainnumitrperslot is set according to the parameters used for generating the dataset.

• —Run python train.py in the environment created above for training and validation
• —Loads datasets from .mat file
• —Compiles and fits NN model
• —Saves weights to h5 file
• —Plots train and val accuracy and loss, saves to Plots directory

Testing the Neural Network

Re‑use and modify config_params.py for test configurations.

Important Parameters

Ensure that the SNR, trainchannelmodel, trainnumitrperslot is set according to the parameters used for generating the dataset

• —Run python test.py for testing the model and obtaining the results
• —Builds NN model by calling the neuralnetmodel function
• —Loads weights from h5 file
• —Recompiles the model
• —Calls calc_acc_vs_snr and calc_acc_vs_ue functions for computing the accuracy for each SNR and each nummuxue
• —Calls calc_conf_matrices function to plot the confusion matrices for each scenario
• —Two separate scenarios of testing are supported
• —Separate Sim (test_data_format = 'sim')
• —Loads MATLAB simulated test data from mat files, separately for each SNR
• —Tests the NN performance, displays test accuracy, plots and saves confusion matrices for each SNR
• —Separate HW (test_data_format = 'hw')
• —Loads hardware capture mat files, saparately for each SNR
• —Tests the NN performance, displays test accuracy, plots and saves confusion matrices for each SNR

• —Run python test_shap.py to compute and store the shap values for the chosen configuration parameters

• —Run python test_qxdm.py to compute the accuracy values for data collected from a live 5G NR Basestation at IIT Madras.

Folder Structure

Notes

• —Always ensure MATLAB and Python configuration parameters are consistent.
• —For hardware dataset usage, replace out_data_format = 'sim' with 'hw' in both MATLAB and Python configs.
• —Parallel processing (parfor) with 32 workers is active by default for faster dataset creation.

Citation

If you use this repository or its datasets, please cite appropriately.

Author: Jeeva Keshav Sattianarayanin, Anil Kumar Yerrapragada, Radhakrishna Ganti Institution: Indian Institute of Technology Madras