akon1995 commited on
Commit
827964d
·
verified ·
1 Parent(s): 1920902

Add ControlRadio model card and figures

Browse files
.gitattributes CHANGED
@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
33
  *.zip filter=lfs diff=lfs merge=lfs -text
34
  *.zst filter=lfs diff=lfs merge=lfs -text
35
  *tfevents* filter=lfs diff=lfs merge=lfs -text
 
 
 
33
  *.zip filter=lfs diff=lfs merge=lfs -text
34
  *.zst filter=lfs diff=lfs merge=lfs -text
35
  *tfevents* filter=lfs diff=lfs merge=lfs -text
36
+ assets/controlradio_framework.png filter=lfs diff=lfs merge=lfs -text
37
+ assets/controlradio_results.png filter=lfs diff=lfs merge=lfs -text
README.md CHANGED
@@ -1,3 +1,147 @@
1
  ---
2
  license: openrail++
 
 
 
 
 
 
 
 
 
 
3
  ---
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
  license: openrail++
3
+ base_model: stabilityai/stable-diffusion-2-1-base
4
+ tags:
5
+ - controlnet
6
+ - stable-diffusion
7
+ - diffusion
8
+ - radio-map
9
+ - wireless-communications
10
+ - pytorch-lightning
11
+ - research
12
+ - "arxiv:2608.09357"
13
  ---
14
+
15
+ # ControlRadio
16
+
17
+ ## Prompt-Driven Controllable Diffusion for Cross-Modal Radio Map Generation
18
+
19
+ **Kangjun Liu · Xiying Pan · Shuhang Zhang · Xiang Xiang · Ke Chen · Yaowei Wang**
20
+
21
+ [Paper](https://arxiv.org/abs/2608.09357) · [HTML](https://arxiv.org/html/2608.09357v1) · [PDF](https://arxiv.org/pdf/2608.09357) · [Code](https://github.com/AkonLau/ControlRadio) · [RadioMapSeer](https://radiomapseer.github.io/)
22
+
23
+ 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.
24
+
25
+ > This repository hosts the pretrained weights. Training, evaluation, and inference code is maintained in the [ControlRadio GitHub repository](https://github.com/AkonLau/ControlRadio).
26
+
27
+ <p align="center">
28
+ <img src="assets/controlradio_framework.png" alt="ControlRadio framework" width="100%">
29
+ </p>
30
+
31
+ ## Model Description
32
+
33
+ ControlRadio builds on [Stable Diffusion 2.1 Base](https://huggingface.co/stabilityai/stable-diffusion-2-1-base) and introduces:
34
+
35
+ - prompt-guided semantic conditioning with a frozen OpenCLIP text encoder;
36
+ - a Layout-Aware ControlNet for building, transmitter, and optional car conditions;
37
+ - a Noise Controller for controlling the latent prior used at inference time; and
38
+ - decoupled two-stage fine-tuning of a radio-domain VAE followed by the U-Net and ControlNet.
39
+
40
+ 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()`.
41
+
42
+ ## Released Checkpoints
43
+
44
+ | Model | Setting | `--carsInput` | Checkpoint | Size |
45
+ |---|---|---:|---|---:|
46
+ | ControlRadio-SRM | Static radio maps without cars | `no` | [`epoch=99-step=337499.ckpt`](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) | 13.7 GB |
47
+ | ControlRadio-DRM | Dynamic radio maps with cars | `yes` | [`epoch=99-step=506249.ckpt`](experiments/prompt_v6/RadioMapSeer_RadioDiff-Seer-carsInput/control_sd21_3ch_1e-05_3_100_sd_tune_seed1230/lightning_logs/version_0/checkpoints/epoch=99-step=506249.ckpt) | 13.7 GB |
48
+
49
+ 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.
50
+
51
+ ## Installation and Download
52
+
53
+ Clone the code repository and create the reference environment:
54
+
55
+ ```bash
56
+ git clone https://github.com/AkonLau/ControlRadio.git
57
+ cd ControlRadio
58
+ conda env create -f environment.yaml
59
+ conda activate control
60
+ ```
61
+
62
+ Install a Hugging Face Hub CLI version compatible with the reference Transformers environment, then download both checkpoints into the project root:
63
+
64
+ ```bash
65
+ pip install "huggingface_hub>=0.30,<1.0"
66
+ hf download akon1995/ControlRadio --include "experiments/**" --local-dir .
67
+ ```
68
+
69
+ The resulting layout is:
70
+
71
+ ```text
72
+ ControlRadio/
73
+ `-- experiments/
74
+ `-- prompt_v6/
75
+ |-- RadioMapSeer_RadioDiff-Seer-no-carsInput/
76
+ | `-- control_sd21_3ch_1e-05_3_100_sd_tune_seed1230/
77
+ | `-- lightning_logs/version_0/checkpoints/
78
+ | `-- epoch=99-step=337499.ckpt
79
+ `-- RadioMapSeer_RadioDiff-Seer-carsInput/
80
+ `-- control_sd21_3ch_1e-05_3_100_sd_tune_seed1230/
81
+ `-- lightning_logs/version_0/checkpoints/
82
+ `-- epoch=99-step=506249.ckpt
83
+ ```
84
+
85
+ ## Evaluation and Inference
86
+
87
+ For both checkpoints, use the following checkpoint-selection arguments:
88
+
89
+ ```text
90
+ --simulation Seer
91
+ --prompt_type v6
92
+ --batch_size 3
93
+ --learning_rate 1e-5
94
+ --max_epochs 100
95
+ --sd_locked False
96
+ --seed 1230
97
+ ```
98
+
99
+ 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.
100
+
101
+ See the [GitHub evaluation and inference instructions](https://github.com/AkonLau/ControlRadio#evaluation-and-inference) for complete commands and data preparation.
102
+
103
+ ## Results
104
+
105
+ <p align="center">
106
+ <img src="assets/controlradio_results.png" alt="Qualitative ControlRadio results" width="90%">
107
+ </p>
108
+
109
+ Results reported in the paper on the RadioMapSeer benchmark are:
110
+
111
+ | Scenario | RMSE ↓ | NMSE ↓ | PSNR ↑ | SSIM ↑ |
112
+ |---|---:|---:|---:|---:|
113
+ | SRM (DPM without cars) | **0.0166** | **0.0024** | **35.86** | **0.9787** |
114
+ | DRM (DPM with cars) | **0.0180** | **0.0028** | **35.29** | **0.9759** |
115
+ | IRT4 (without cars) | **0.0210** | **0.0040** | **33.46** | **0.9688** |
116
+
117
+ ## Training Data
118
+
119
+ The models were trained and evaluated with [RadioMapSeer](https://radiomapseer.github.io/). 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.
120
+
121
+ ## Intended Use and Limitations
122
+
123
+ 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.
124
+
125
+ - The released checkpoints have not been validated as replacements for site-specific electromagnetic solvers or field measurements.
126
+ - Performance should not be interpreted as sim-to-real validation or strict electromagnetic equivalence.
127
+ - Predictions depend on data preprocessing, prompt construction, coordinate conventions, and inference settings matching the released code.
128
+ - Users are responsible for validating generated maps before applying them to safety-critical or operational wireless-network decisions.
129
+
130
+ ## License
131
+
132
+ The model weights are released under the `openrail++` license metadata, consistent with the [Stable Diffusion 2.1 Base](https://huggingface.co/stabilityai/stable-diffusion-2-1-base) foundation model. The ControlRadio source code is separately released under the [MIT License](https://github.com/AkonLau/ControlRadio/blob/main/LICENSE).
133
+
134
+ ## Citation
135
+
136
+ ```bibtex
137
+ @article{liu2026controlradio,
138
+ title = {ControlRadio: Prompt-Driven Controllable Diffusion for Cross-Modal Radio Map Generation},
139
+ author = {Liu, Kangjun and Pan, Xiying and Zhang, Shuhang and Xiang, Xiang and Chen, Ke and Wang, Yaowei},
140
+ journal = {arXiv preprint arXiv:2608.09357},
141
+ year = {2026}
142
+ }
143
+ ```
144
+
145
+ ## Acknowledgements
146
+
147
+ This work builds upon [ControlNet](https://github.com/lllyasviel/ControlNet), [Stable Diffusion](https://github.com/CompVis/stable-diffusion), [OpenCLIP](https://github.com/mlfoundations/open_clip), and [RadioMapSeer](https://radiomapseer.github.io/).
assets/controlradio_framework.png ADDED

Git LFS Details

  • SHA256: 44ac1fc00d57d16bb1b4d8ad89c30076d75fa17a7893c74575b6fe8fcf7b266d
  • Pointer size: 131 Bytes
  • Size of remote file: 861 kB
assets/controlradio_results.png ADDED

Git LFS Details

  • SHA256: 2d6bcc41bb1b3e54c32ab935d849f81b82a12143020d92ad226764144b3536c9
  • Pointer size: 132 Bytes
  • Size of remote file: 1.01 MB