README.md

---
license: apache-2.0
tags:
  - wireless
  - foundation-model
  - multimodal
  - pytorch
  - vit
library_name: pytorch
paperswithcode_id: multimodal-wireless-foundation-models
paper:
  - https://arxiv.org/abs/2511.15162
---

# WavesFM v1.0

## Summary
WavesFM is a multimodal wireless foundation model for IQ streams and image-like modalities (spectrograms, CSI), plus CIR. It uses a ViT backbone with modality-specific input embeddings and a masked wireless modeling objective.

## Model Details
- Architecture: ViT encoder + modality-specific input embeddings + lightweight task heads.
- Modalities: IQ, spectrograms, CSI, CIR.
- Objective: masked wireless modeling (MAE-style reconstruction).

## Links
- Benchmarks: [wavesfm.waveslab.ai/benchmarks](https://wavesfm.waveslab.ai/benchmarks)
- Reproduce: [wavesfm.waveslab.ai/docs/reproduce](https://wavesfm.waveslab.ai/docs/reproduce)
- GitHub: [github.com/AhmedTarek62/wavesfm](https://github.com/AhmedTarek62/wavesfm)
- Quickstart notebook: [wavesfm_demo.ipynb](https://colab.research.google.com/github/AhmedTarek62/wavesfm/blob/main/wavesfm_demo.ipynb)

## Intended Use
- Research on multimodal wireless representation learning.
- Fine-tuning on downstream wireless tasks.

## Downstream Tasks
- RF fingerprinting (IQ)
- Interference detection/classification (IQ)
- Human activity sensing (CSI)
- RF signal classification (spectrograms)
- 5G NR positioning (CSI)
- DeepMIMO LoS/NLoS and beam prediction (CSI)
- RADCOM signal/modulation classification (IQ)
- UWB indoor and industrial localization (CIR)

## HF Usage
Clone the training repo:
```bash
git clone https://github.com/AhmedTarek62/wavesfm.git
cd wavesfm
```

Download the checkpoint:
```bash
pip install -U huggingface_hub
huggingface-cli download ahmedaboulfo/wavesfm wavesfm-v1p0.pth --local-dir ./checkpoints
```

Fine-tune:
```bash
python main_finetune.py \
  --task <task_name> \
  --train-data <path/to/train.h5> \
  --val-split 0.2 \
  --finetune ./checkpoints/wavesfm-v1p0.pth \
  --output-dir <run_dir>
```

Evaluate:
```bash
python main_finetune.py \
  --task <task_name> \
  --train-data <path/to/train.h5> \
  --val-split 0.2 \
  --eval-only \
  --download-pretrained \
  --hf-repo ahmedaboulfo/wavesfm \
  --hf-file wavesfm-v1p0.pth
```

Refer to the [WavesFM website](https://wavesfm.waveslab.ai) for more detailed instructions.

## Citation
```
@article{aboulfotouh2025multimodal,
  title = {Multimodal Wireless Foundation Models},
  author = {Aboulfotouh, Ahmed and Abou-Zeid, Hatem},
  journal = {arXiv preprint arXiv:2511.15162},
  year = {2025},
  url = {https://arxiv.org/abs/2511.15162}
}
```