English | 简体中文

CSRR (ChangShuoRadioRecognition) is an open source Automatic Modulation Classification (AMC) toolbox based on PyTorch and MMEngine.

• Config-Driven: All experiments are configured via Python config files
• Multiple AMC Methods: Supports 20+ state-of-the-art AMC algorithms
• Performance Analysis: Built-in tools for generating publication-ready figures and tables
• Minimal Dependencies: Only depends on MMEngine, no other MM-family packages required

• Python >= 3.8
• PyTorch >= 1.8
• MMEngine >= 0.7.0

# Create conda environment
conda create -n csrr python=3.10 -y
conda activate csrr

# Install PyTorch (adjust cuda version as needed)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# Install MMEngine
pip install mmengine

# Install CSRR
git clone https://github.com/Singingkettle/ChangShuoRadioRecognition.git
cd ChangShuoRadioRecognition
pip install -e .

# Train CNN2 on DeepSig RadioML.2016.10A
python tools/train.py configs/cnn2/cnn2_iq-deepsig-201610A.py

# Train with custom work directory
python tools/train.py configs/cnn2/cnn2_iq-deepsig-201610A.py --work-dir work_dirs/my_exp

# Override config options
python tools/train.py configs/cnn2/cnn2_iq-deepsig-201610A.py \
    --cfg-options train_cfg.max_epochs=100

After training, generate predictions for performance analysis:

# Test and save predictions
python tools/test.py configs/cnn2/cnn2_iq-deepsig-201610A.py \
    work_dirs/cnn2_iq-deepsig-201610A/best_accuracy_top1_epoch_*.pth \
    --work-dir work_dirs/cnn2_iq-deepsig-201610A

This saves paper.pkl containing predictions, ground truth, and SNR values.

Generate publication-ready figures by comparing multiple trained models:

Step 1: Configure method registry in configs/_base_/performance_info/amc.py:

info = dict(
    work_dir='work_dirs',
    methods={
        'CNN2': 0,    # Index determines color/marker
        'CNN4': 1,
        'DensCNN': 2,
    },
    publish=dict(
        deepsig201610A=dict(
            CNN2='cnn2_iq-deepsig-201610A',      # method_name -> work_dir_name
            CNN4='cnn4_iq-deepsig-201610A',
            DensCNN='denscnn_iq-deepsig-201610A',
        ),
    ),
)

Step 2: Create a plot config (e.g., configs/cnn2/cnn2_plot.py):

_base_ = ['../_base_/performance_info/amc.py']

performance = dict(
    type='Classification',
    Figures=[
        dict(
            type='SNRVsAccuracy',
            dataset=dict(
                deepsig201610A=dict(
                    comparison=['CNN2', 'CNN4', 'DensCNN'],
                ),
            ),
        ),
        dict(
            type='ConfusionMap',
            dataset=dict(deepsig201610A=['CNN2']),
        ),
    ],
)

Step 3: Generate figures:

python tools/analyze.py configs/cnn2/cnn2_plot.py

Output PDFs are saved to work_dirs/performance/.

ChangShuoRadioRecognition/
├── configs/                 # Model and experiment configs
│   ├── _base_/             # Base configs (datasets, schedules, etc.)
│   ├── cnn2/               # CNN2 model configs
│   └── ...
├── csrr/                   # Core library
│   ├── datasets/           # Dataset classes
│   ├── models/             # Model implementations
│   ├── engine/             # Training hooks
│   ├── evaluation/         # Metrics
│   ├── performance/        # Plotting and analysis tools
│   └── ...
├── tools/                  # Command-line tools
│   ├── train.py           # Training script
│   ├── test.py            # Testing/inference script
│   └── analyze.py         # Performance analysis script
└── work_dirs/             # Output directory (created during training)

If you use this toolbox in your research, please cite:

@article{chang2021multi,
  title={Multi-task learning based deep neural network for automatic modulation classification},
  author={Chang, Shuo and Huang, Sai and Zhang, Ruiyun and Feng, Zhiyong and Liu, Liang},
  journal={IEEE Internet of Things Journal},
  year={2021},
  publisher={IEEE}
}

@article{chang2022hcgdnn,
  author={Chang, Shuo and Zhang, Ruiyun and Ji, Kejia and Huang, Sai and Feng, Zhiyong},
  journal={IEEE Transactions on Wireless Communications}, 
  title={A Hierarchical Classification Head based Convolutional Gated Deep Neural Network for Automatic Modulation Classification}, 
  year={2022},
  doi={10.1109/TWC.2022.3168884}
}

@article{chang2023fastmldnn,
  title={A Fast Multi-Loss Learning Deep Neural Network for Automatic Modulation Classification},
  author={Chang, Shuo and others},
  journal={IEEE Transactions},
  year={2023}
}

This project is released under the Apache 2.0 license.

This project is maintained by Shuo Chang (@Singingkettle).