README.md

metadata

license: openrail++
base_model: stabilityai/stable-diffusion-2-1-base
tags:
  - controlnet
  - stable-diffusion
  - diffusion
  - radio-map
  - wireless-communications
  - pytorch-lightning
  - research
  - arxiv:2608.09357

ControlRadio

Prompt-Driven Controllable Diffusion for Cross-Modal Radio Map Generation

Kangjun Liu · Xiying Pan · Shuhang Zhang · Xiang Xiang · Ke Chen · Yaowei Wang

Paper · HTML · PDF · Code · RadioMapSeer

ControlRadio is a prompt-driven controllable diffusion framework for cross-modal radio map generation. It combines natural-language descriptions with environmental layouts, including building morphology, transmitter locations, and optional dynamic-object cues, to synthesize structurally consistent and propagation-plausible radio maps.

This repository hosts the pretrained weights. Training, evaluation, and inference code is maintained in the ControlRadio GitHub repository.

Model Description

ControlRadio builds on Stable Diffusion 2.1 Base and introduces:

• prompt-guided semantic conditioning with a frozen OpenCLIP text encoder;
• a Layout-Aware ControlNet for building, transmitter, and optional car conditions;
• a Noise Controller for controlling the latent prior used at inference time; and
• decoupled two-stage fine-tuning of a radio-domain VAE followed by the U-Net and ControlNet.

The released files are PyTorch Lightning checkpoints used by the research code. They are not standalone Diffusers or Transformers checkpoints and cannot be loaded directly with from_pretrained().

Released Checkpoints

Model	Setting	--carsInput	Checkpoint	Size
ControlRadio-SRM	Static radio maps without cars	no	epoch=99-step=337499.ckpt	13.7 GB
ControlRadio-DRM	Dynamic radio maps with cars	yes	epoch=99-step=506249.ckpt	13.7 GB

Each experiment directory also contains the corresponding hparams.yaml. Keep the downloaded directory structure unchanged because the evaluation and inference scripts construct checkpoint paths from the command-line configuration.

Installation and Download

Clone the code repository and create the reference environment:

git clone https://github.com/AkonLau/ControlRadio.git
cd ControlRadio
conda env create -f environment.yaml
conda activate control

Install a Hugging Face Hub CLI version compatible with the reference Transformers environment, then download both checkpoints into the project root:

pip install "huggingface_hub>=0.30,<1.0"
hf download akon1995/ControlRadio --include "experiments/**" --local-dir .

The resulting layout is:

ControlRadio/
`-- experiments/
    `-- prompt_v6/
        |-- RadioMapSeer_RadioDiff-Seer-no-carsInput/
        |   `-- control_sd21_3ch_1e-05_3_100_sd_tune_seed1230/
        |       `-- lightning_logs/version_0/checkpoints/
        |           `-- epoch=99-step=337499.ckpt
        `-- RadioMapSeer_RadioDiff-Seer-carsInput/
            `-- control_sd21_3ch_1e-05_3_100_sd_tune_seed1230/
                `-- lightning_logs/version_0/checkpoints/
                    `-- epoch=99-step=506249.ckpt

Evaluation and Inference

For both checkpoints, use the following checkpoint-selection arguments:

--simulation Seer
--prompt_type v6
--batch_size 3
--learning_rate 1e-5
--max_epochs 100
--sd_locked False
--seed 1230

Select ControlRadio-SRM with --carsInput no or ControlRadio-DRM with --carsInput yes. Use --test_simulation DPM, IRT2, or IRT4 to select the evaluation target. The paper uses Noise Controller settings --means -0.1 --vars 0.001 selected on the validation set.

See the GitHub evaluation and inference instructions for complete commands and data preparation.

Results

Results reported in the paper on the RadioMapSeer benchmark are:

Scenario	RMSE ↓	NMSE ↓	PSNR ↑	SSIM ↑
SRM (DPM without cars)	0.0166	0.0024	35.86	0.9787
DRM (DPM with cars)	0.0180	0.0028	35.29	0.9759
IRT4 (without cars)	0.0210	0.0040	33.46	0.9688

Training Data

The models were trained and evaluated with RadioMapSeer. The code follows the paper's map-level split: maps 0–499 for training, 500–599 for validation, and 600–700 for testing. Refer to the dataset provider for its terms and documentation.

Intended Use and Limitations

ControlRadio is released for research on prompt- and layout-conditioned radio-map generation. The reported results compare generated maps with WinProp-derived references on simulated, previously unseen layouts.

• The released checkpoints have not been validated as replacements for site-specific electromagnetic solvers or field measurements.
• Performance should not be interpreted as sim-to-real validation or strict electromagnetic equivalence.
• Predictions depend on data preprocessing, prompt construction, coordinate conventions, and inference settings matching the released code.
• Users are responsible for validating generated maps before applying them to safety-critical or operational wireless-network decisions.

License

The model weights are released under the openrail++ license metadata, consistent with the Stable Diffusion 2.1 Base foundation model. The ControlRadio source code is separately released under the MIT License.

Citation

@article{liu2026controlradio,
  title   = {ControlRadio: Prompt-Driven Controllable Diffusion for Cross-Modal Radio Map Generation},
  author  = {Liu, Kangjun and Pan, Xiying and Zhang, Shuhang and Xiang, Xiang and Chen, Ke and Wang, Yaowei},
  journal = {arXiv preprint arXiv:2608.09357},
  year    = {2026}
}

Acknowledgements

This work builds upon ControlNet, Stable Diffusion, OpenCLIP, and RadioMapSeer.