README.md

---
license: cc-by-nc-4.0
library_name: pytorch
pipeline_tag: feature-extraction
tags:
  - wireless
  - channel-state-information
  - channel-foundation-model
  - contrastive-learning
  - resnet
---

# CSI-CLIP ResNet-50

CSI-CLIP is a channel foundation model that aligns channel state information
(CSI/CFR) and channel impulse response (CIR) representations through
contrastive pre-training. This repository contains the official model-only
ResNet-50 weights associated with
[*A MIMO Wireless Channel Foundation Model via CIR-CSI Consistency*](https://arxiv.org/abs/2502.11965).

- Code: [GREAT-ISAC/CSI-CLIP](https://github.com/GREAT-ISAC/CSI-CLIP)
- Reference data generation: [GREAT-ISAC/Channel-Simulation-Data](https://github.com/GREAT-ISAC/Channel-Simulation-Data)
- Paper: [arXiv:2502.11965](https://arxiv.org/abs/2502.11965)
- IEEE: [ICMLCN 2025](https://ieeexplore.ieee.org/abstract/document/11140262/)

## Weight files

Both files contain the same pre-trained model parameters. They do not contain
an optimizer, scheduler, training data, or a downstream task head.

| File | Type | Intended use |
| --- | --- | --- |
| `model.safetensors` | Model-only pre-trained weights | Recommended for safe standalone loading and feature extraction |
| `model.pth` | Model-only PyTorch checkpoint with a `model` key | Compatibility with the existing fine-tuning scripts |

These are channel-foundation-model pre-training weights, not task-specific checkpoints
for positioning, beam management, or LOS/NLOS classification. A downstream
head must be trained before task-level inference.

The original checkpoint used the legacy names `cfr_backbone`, `cir_backbone`,
`proj_cfr`, and `proj_cir`. They were mapped to the names in the public
`CSICLIP` class without changing the tensors. The public class additionally
expects `logit_scale`; because the original checkpoint predates that parameter,
it is initialized to the documented CLIP default of `log(1 / 0.07)`. This does
not affect CSI encoder feature extraction. Exact SHA-256 values are recorded in
`manifest.json`.

## Input contract

| Property | Value |
| --- | --- |
| Input shape | `[batch, 2, 256, 256]` |
| Channel order | Real, imaginary |
| Dtype | `float32` |
| Normalization | Per-sample, per-channel min-max normalization to `[0, 1]` |
| Normalization epsilon | `1e-8` |
| CIR construction | IFFT of the normalized complex CSI along the last axis |
| CSI embedding size | 256 |

The same preprocessing must be used during training, fine-tuning, and
inference. The repository implementation is authoritative; see
`build_cir_cfr_pair` in `augmentations.py`.

## Usage

Install the code and its minimal dependencies:

```bash
git clone https://github.com/GREAT-ISAC/CSI-CLIP.git
cd CSI-CLIP
pip install -r requirements.txt
```

After downloading `model.safetensors`, run the model-loading smoke test:

```bash
python load_pretrained.py \
  --checkpoint /path/to/model.safetensors
```

Expected output:

```text
CSI embedding shape: (1, 256)
```

Run feature extraction on a complex `cfr.npy` sample:

```bash
python load_pretrained.py \
  --checkpoint /path/to/model.safetensors \
  --input /path/to/scenario/cfr.npy \
  --sample-index 0
```

## Training data

The model was pre-trained on simulated DeepMIMO CSI covering multiple wireless
scenarios. Generated training arrays are not included in this model repository.
A **reproducible, model-compatible reference data-generation pipeline** is
available in [Channel Simulation Data](https://github.com/GREAT-ISAC/Channel-Simulation-Data).
Its committed O1_60 configuration is one runnable reference example; it does
not reconstruct the complete multi-scenario checkpoint training data.

## Intended use

- Research on wireless/channel foundation models.
- CSI representation and feature extraction.
- Initialization for positioning, beam management, and LOS/NLOS classifiers.
- Non-commercial evaluation and reproducibility studies.

## Limitations and out-of-scope use

- The model was trained on simulated data; performance on measured channels is
  not guaranteed.
- Inputs with different antenna/subcarrier layouts require an explicitly
  validated adaptation rather than an assumed reshape.
- The released weights do not provide task predictions without a trained
  downstream head.
- The model is not intended for safety-critical deployment or commercial use.
- Results depend on reproducing the documented preprocessing exactly.

## License

The original CSI-CLIP code, these model weights, and the repository-owned
data-generation scripts are released under the
[Creative Commons Attribution-NonCommercial 4.0 International](https://creativecommons.org/licenses/by-nc/4.0/)
license (**CC BY-NC 4.0**). Attribution is required and commercial use is not
permitted without prior written authorization from the copyright holders.
Third-party software, simulators, datasets, and scenario assets remain subject
to their respective licenses.

## Citation

```bibtex
@inproceedings{jiang2025csi_clip,
  title={A MIMO Wireless Channel Foundation Model via CIR-CSI Consistency},
  author={Jiang, Jun and Yu, Wenjun and Li, Yunfan and Gao, Yuan and Xu, Shugong},
  booktitle={2025 IEEE International Conference on Machine Learning for Communication and Networking (ICMLCN)},
  pages={1--6},
  year={2025},
  doi={10.1109/ICMLCN64995.2025.11140262}
}
```

## Contact

For questions, contact Jun Jiang at
[Jun.Jiang25@student.xjtlu.edu.cn](mailto:Jun.Jiang25@student.xjtlu.edu.cn).