Channel estimation test bed (CeBed) is a suite of implementations and benchmarks for OFDM channel estimation in Tensorflow.

The goal of CeBed is to unify and facilitate the replication, refinement and design of new deep channel estimators. CeBed can also be used as a baseline to create and build new projects and compare with existing algorithms in the litterature. It is simple to add a new dataset or a model to our package and we welcome the community to update or add exisiting algorithms or datasets.

For now, CeBed provides a simple interface to train and evaluate various deep channel estimation models.

Setup

Clone repo and install the requirements in a Python>=3.8.0 environment.

git clone https://github.com/SAIC-MONTREAL/CeBed
cd CeBed
pip install -e .

Using CeBed

Datasets

Sionna dataset

For now, CeBed uses the link-level simulator [Sionna](https://nvlabs.github.io/sionna/) for data generation. CeBed provides an interface to generate datasets using different channel models, system parameters, pilot patterns, etc.

Here is an example to generate a SISO dataset using one SNR level (by default = 0 dB) :

python scripts/generate_datasets_from_sionna.py --size 10000 --num_rx_antennas 1 --path_loss

The generated dataset contains:

• x: Transmitted symbols, a complex tensor with shape [batch_size, num_tx, num_tx_ant, num_ofdm_symbols, num_subcarriers]
• h: The channel impulse response, a complex tensor with shape [batch size, num_rx, num_rx_ant, num_tx, num_tx_ant, num_ofdm_symbols, num_subcarriers]
• y: The received symbols, a complex tensor with shape [batch size, num_rx, num_rx_ant, num_ofdm_symbols, num_subcarriers]

Here is another example on how to generate a multi-domain dataset where each SNR level is a different domain:

python scripts/generate_datasets_from_sionna.py --size 10000 --scenario umi --num_rx_antennas 1 --path_loss --num_domains 5 start_ds 0 end_ds 25

Custom dataset

It is easy to add a new dataset to CeBed. The dataset can be generated offline using any link-level simulator like MATLAB.

Please check the tutorial in notebooks/cusotm_dataset.ipynb, detailing how to use CeBed with your dataset.

Training

Single model training

The command below will train and evaluate a single model

python scripts/train.py --experiment_name EXPERIMENT_NAME --seed SEED --data_dir DATADIR --epochs 100 --dataset_name SionnaOfflineMD --model_name ReEsNet --input_type low

Model hyperparameters

The model hyperprameters are defined in yaml files under hyperparams. Make sure that the EXPERIMENT_NAME exists in the yaml files of the model(s) you would like to train. Here is an example configuration of the ReEsNet model:

MyExperimentName:
  default:
    hidden_size: 16
    input_type: low
    kernel_size: 3
    lr: 0.001
    n_blocks: 4
    upsamling_mode: deconv

Benchmarking all models

To reproduce the benchamrking results from our paper:

python scripts/benchmark.py --seed SEED --data_dir DATADIR --epochs 100 --experiment_name EXPERIMENT_NAME --gpus GPU_IDS

Note: The model inputs and outputs are expects to have the following shape [batch_size, num_ofdm_symbols, num_ofdm_subcarriers, num_channels] where num_channels = num_rx_ant*num_tx*2.

Evaluation

**Evaluate a trained model**

To evaluate a model trained with CeBed,

python scripts/evaluate.py PATH_TO_MODEL

Evaluate model and baselines

You can provide a list of baselines to compare the model to :

python scripts/evaluate.py PATH_TO_MODEL LS LMMSE ALMMSE

Citation

If you use our code, please cite our work.

@article{cebed,
  author  = {Amal Feriani and Di Wu and Steve Liu and Greg Dudek},
  title   = {CeBed: A Benchmark for Deep Data-Driven OFDM Channel Estimation},
  url     = {https://github.com/SAIC-MONTREAL/cebed.git}
  year   = {2023}
}

License

The code is licensed under the Creative Commons Attribution 4.0 License (CC BY).