CSI-CLIP / README.md

Link reference data generation pipeline

5418fda verified about 18 hours ago

5.49 kB

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.

Code: GREAT-ISAC/CSI-CLIP
Reference data generation: GREAT-ISAC/Channel-Simulation-Data
Paper: arXiv:2502.11965
IEEE: ICMLCN 2025

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:

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:

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

Expected output:

CSI embedding shape: (1, 256)

Run feature extraction on a complex cfr.npy sample:

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. 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 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

@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.