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. Dataset Generation (MATLAB) — Create PUCCH Format 0 frequency‑domain complex sample datasets.
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

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, num_mux_UE = 0:12, fd=[0:400:2000], metadata_offset = 2

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

Combined Dataset Output

Datasets/Datafiles/Sim_data/Data_for_NN/

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

Training the Neural Network

Configuration file: config_params.py

Important Parameters

Ensure that the SNR, train_channel_model, train_num_itr_per_slot 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, train_channel_model, train_num_itr_per_slot 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 neural_net_model 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 num_mux_ue
  • 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