"A man, remember, whether rich or poor, should do something in this world. No one can find happiness without work."
--The Adventures of Pinocchio (by Carlo Collodi).
Python repository for the magazine paper "Adaptive and Flexible Model-Based AI for Deep Receivers in Dynamic Channels".
Please cite our paper, if the code is used for publishing research.
Table of contents generated with markdown-toc
This repository implements deep receivers, with a bunch of different improvements, for SISO and MIMO channels. The deep receviers include the ViterbiNet equalizer and an RNN detector for the SISO case, and the DeepSIC receiver as well as a fully connected black-box network for the MIMO case. It includes the possibility of adding the communication drive augmentations of my previous augmentations paper, see this github repo for the code implementation. From the training prespective, you can choose between joint training (the receiver is trained offline in a pre-test phase, using data simulated from multitude of channel realizations. No additional training is done online in the test phase), online training (the receiver is trained online using the pilots batch at each time step) and meta-learning training taken from my previous meta-learning paper, code implementation for siso and mimo. In the paper we show that the gains from the different approaches add up individually over the two scenarios and a range of SNRs.
Main Run - Run the evaluate.py script after choosing approriate hyperparameters and setup in the config.yaml to run the eval.
The python simulations of the simplified communication chain: symbols generation, channel transmission and detection.
The proposed augmentations scheme suggested in my previous augmentations paper, see this github repo for the code implementation.
Includes all relevant channel functions and classes. The class in "channel_dataset.py" implements the main class for aggregating pairs of (transmitted,received) samples. In "channel.py", the SISO and MIMO channels are implemented. "channel_estimation.py" is for the calculation of the h values. Lastly, the channel BPSK/QPSK modulators lies in "channel_modulator.py".
The backbone detectors and their respective training: ViterbiNet, DeepSIC, Meta-ViterbiNet, Meta-DeepSIC, RNN BlackBox and FC BlackBox. The meta and non-meta detectors have slightly different API so they are seperated in the trainer class below. The meta variation has to receive the parameters of the original architecture for the training. The trainers are wrappers for the training and evaluation of the detectors. Trainer holds the training, sequential evaluation of pilot + info blocks. It also holds the main function 'eval' that trains the detector and evaluates it, returning a list of coded ber/ser per block. The train and test dataloaders are also initialized by the trainer. Each trainer is executable by running the 'evaluate.py' script after adjusting the config.yaml hyperparameters and choosing the desired method.
Features main plotting tools for the paper:
- plotter_main - main plotting script used to get the figures in the paper. Based on the chosen PlotType enum loads the relevant config and runs the experiment.
- plotter_config - holds a mapping from the PlotType enum to the experiment's hyperparameters and setup.
- plotter_utils - colors, markers and linestyles for all evaluated methods, and the main plotting functions.
- plotter_methods - additional methods used for plotting.
Extra utils for pickle manipulations and tensor reshaping; calculating the accuracy over FER and BER; several constants; and the config singleton class. The config works by the singleton design pattern. Check the link if unfamiliar.
The config is accessible from every module in the package, featuring the next parameters:
- seed - random number generator seed. Integer.
- channel_type - run either siso or mimo setup. Values in the set of ['SISO','MIMO']. String.
- channel_model - chooses the channel taps values, either synthetic or based on COST2100. String in the set ['Cost2100','Synthetic'].
- detector_type - selects the training + architecture to run. Short description of each option:
- 'joint_black_box - Joint training of the black-box fully connected detector in the MIMO case.
- 'online_black_box' - Online training of the black-box fully connected detector in the MIMO case.
- 'joint_deepsic' - Joint training of the DeepSIC detector in the MIMO case.
- 'online_deepsic' - Online training of the DeepSIC detector in the MIMO case.
- 'meta_deepsic' - Online meta-training of the DeepSIC detector in the MIMO case.
- 'joint_rnn' - Joint training of the RNN detector in the SISO case.
- 'online_rnn' - online training of the RNN detector in the SISO case.
- 'joint_viterbinet' - Joint training of the ViterbiNet equalizer in the SISO case.
- 'online_viterbinet' - Online training of the ViterbiNet equalizer in the SISO case.
- 'meta_viterbinet' - Online meta-training of the ViterbiNet equalizer in the SISO case.
- linear - whether to apply non-linear tanh at the channel output, not used in the paper but still may be applied. Bool. 6.fading_in_channel - whether to use fading. Relevant only to the synthetic channel. Boolean flag.
- snr - signal-to-noise ratio, determines the variance properties of the noise, in dB. Float.
- modulation_type - either 'BPSK' or 'QPSK', string.
- memory_length - siso channel hyperparameter, integer.
- n_user - mimo channel hyperparameter, number of transmitting devices. Integer.
- n_ant - mimo channel hyperparameter, number of receiving devices. Integer.
- block_length - number of coherence block bits, total size of pilot + data. Integer.
- pilot_size - number of pilot bits. Integer.
- blocks_num - number of blocks in the tranmission. Integer.
- loss_type - 'CrossEntropy', could be altered to other types 'BCE' or 'MSE'.
- optimizer_type - 'Adam', could be altered to other types 'RMSprop' or 'SGD'.
- joint_block_length - joint training hyperparameter. Offline training block length. Integer.
- joint_pilot_size - joint training hyperparameter. Offline training pilots block length. Integer.
- joint_blocks_num - joint training hyperparameter. Number of blocks to train on offline. Integer.
- joint_snrs - joint training hyperparameter. Number of SNRs to traing from offline. List of float values.
- aug_type - what augmentations to use. leave empty list for no augmentations, or add whichever of the following you like: ['geometric_augmenter','translation_augmenter','rotation_augmenter']
- online_repeats_n - if using augmentations, adds this factor times the number of pilots to the training batch. Leave at 0 if not using augmentations, if using augmentations try integer values in 2-5.
Keeps the COST channel coefficients vectors. Also holds config runs for the paper's numerical comparisons figures.
Definitions of relative directories.
To execute the code, first download and install Git, Anaconda and PyCharm.
Then install the environment, follow the installation setup below.
At last, open PyCharm in the root directory. You may run either the trainers or one of the plotters.
This code was simulated with GeForce RTX 3060 with CUDA 12.
-
Open git bash and cd to a working directory of you choice.
-
Clone this repository to your local machine.
-
Open Anaconda prompt and navigate to the cloned repository.
-
Run the command "conda env create -f environment.yml". This should install the required python environment.
-
Open the cloned directory using PyCharm.
-
After the project has been opened in PyCharm, go to settings, File -> Settings... (or CTRL ALT S)
-
In the opened window open the tab Project -> Project Interpreter
-
In the new window, click on the cog icon and then on Add...
-
In the add python interpreter window, click on the Conda Environment tab
-
Select Existing environment and navigate to where the python.exe executable of the deep_ensemble environment is installed under the interpreter setting
-
For windows its usually found at C:\users<username>\anaconda3\envs\environment\python.exe)
-
For linux its usually found at /home//anaconda3
-
Click OK
-
Done!