Added model card

README.md

@@ -1,3 +1,177 @@
 ---
 license: mit
 ---
+
+# Model Card — GenAI Channel Modeling Models
+
+Pre-trained checkpoints for the paper:
+
+> **Site-Specific MIMO Channel Generation via Diffusion and Flow Matching: Fidelity, Efficiency, and Downstream Utility**  
+> Sina Beyraghi, Masoud Sadeghian, Firdous Bin Ismail, Angel Lozano, Paul Almasan, and Giovanni Geraci  
+> [[arXiv:2510.10190](https://arxiv.org/abs/2510.10190)]
+
+---
+
+## Model overview
+
+Two conditional generative model architectures are provided:
+
+| Abbreviation | Full name | Inference mechanism |
+|---|---|---|
+| **cDDIM** | Conditional Denoising Diffusion Implicit Model | Reverse diffusion, `n_T = 150` steps |
+| **cFMM** | Conditional Flow Matching Model | Euler integration, `steps = 10` |
+
+Both share the same **Context U-Net** backbone (~15.6 M parameters, `n_feat = 256`) and are conditioned on 3-dimensional UE coordinates (`n_classes = 3`). Channels are represented in beamspace as two-channel real tensors of shape `(2, 4, 32)` (real and imaginary parts; 4 Rx × 32 Tx beams for a 2×2 Rx UPA and 4×8 Tx UPA).
+
+---
+
+## Available checkpoints
+
+Checkpoints are organised under `logs/` using the naming convention:
+
+```
+{MODEL}_{dataset}_{freq}_{scenario}_{guide_w}_{N_train}_{date}/
+```
+
+where `N_train` is the number of real training samples used.
+
+### cDDIM — 3.5 GHz, LoS
+
+| `N_train` | Directory |
+|---|---|
+| 200 | `logs/CDDIM_sina_dataset_3.5GHz_LoS_0.0_200_14_05_2026_10_19/` |
+| 500 | `logs/CDDIM_sina_dataset_3.5GHz_LoS_0.0_500_19_05_2026_09_32/` |
+| 1 000 | `logs/CDDIM_sina_dataset_3.5GHz_LoS_0.0_1000_19_05_2026_09_33/` |
+| 2 000 | `logs/CDDIM_sina_dataset_3.5GHz_LoS_0.0_2000_19_05_2026_09_46/` |
+| 5 000 | `logs/CDDIM_sina_dataset_3.5GHz_LoS_0.0_5000_19_05_2026_10_00/` |
+| 10 000 | `logs/CDDIM_sina_dataset_3.5GHz_LoS_0.0_10000_20_05_2026_09_55/` |
+
+### cDDIM — 3.5 GHz, NLoS + LoS
+
+| `N_train` | Directory |
+|---|---|
+| 200 | `logs/CDDIM_sina_dataset_3.5GHz_NLoS+LoS_0.0_200_15_05_2026_14_55/` |
+| 500 | `logs/CDDIM_sina_dataset_3.5GHz_NLoS+LoS_0.0_500_19_05_2026_11_51/` |
+| 1 000 | `logs/CDDIM_sina_dataset_3.5GHz_NLoS+LoS_0.0_1000_19_05_2026_11_57/` |
+| 2 000 | `logs/CDDIM_sina_dataset_3.5GHz_NLoS+LoS_0.0_2000_19_05_2026_11_57/` |
+| 5 000 | `logs/CDDIM_sina_dataset_3.5GHz_NLoS+LoS_0.0_5000_19_05_2026_11_58/` |
+| 10 000 | `logs/CDDIM_sina_dataset_3.5GHz_NLoS+LoS_0.0_10000_19_05_2026_11_58/` |
+
+### cDDIM — 28 GHz, LoS
+
+| `N_train` | Directory |
+|---|---|
+| 200 | `logs/CDDIM_sina_dataset_28GHz_LoS_0.0_200_13_05_2026_15_07/` |
+| 500 | `logs/CDDIM_sina_dataset_28GHz_LoS_0.0_500_28_05_2026_09_33/` |
+| 1 000 | `logs/CDDIM_sina_dataset_28GHz_LoS_0.0_1000_27_05_2026_08_52/` |
+
+### cFMM — 3.5 GHz, LoS
+
+| `N_train` | Directory |
+|---|---|
+| 200 | `logs/FMM_sina_dataset_3.5GHz_LoS_0.0_200_14_05_2026_10_21/` |
+| 500 | `logs/FMM_sina_dataset_3.5GHz_LoS_0.0_500_19_05_2026_12_22/` |
+| 1 000 | `logs/FMM_sina_dataset_3.5GHz_LoS_0.0_1000_19_05_2026_12_23/` |
+| 2 000 | `logs/FMM_sina_dataset_3.5GHz_LoS_0.0_2000_19_05_2026_12_23/` |
+| 5 000 | `logs/FMM_sina_dataset_3.5GHz_LoS_0.0_5000_19_05_2026_13_10/` |
+| 10 000 | `logs/FMM_sina_dataset_3.5GHz_LoS_0.0_10000_20_05_2026_09_57/` |
+
+### cFMM — 3.5 GHz, NLoS + LoS
+
+| `N_train` | Directory |
+|---|---|
+| 200 | `logs/FMM_sina_dataset_3.5GHz_NLoS+LoS_0.0_200_15_05_2026_14_57/` |
+| 500 | `logs/FMM_sina_dataset_3.5GHz_NLoS+LoS_0.0_500_19_05_2026_14_28/` |
+| 1 000 | `logs/FMM_sina_dataset_3.5GHz_NLoS+LoS_0.0_1000_19_05_2026_14_28/` |
+| 2 000 | `logs/FMM_sina_dataset_3.5GHz_NLoS+LoS_0.0_2000_19_05_2026_14_29/` |
+| 5 000 | `logs/FMM_sina_dataset_3.5GHz_NLoS+LoS_0.0_5000_19_05_2026_14_29/` |
+| 10 000 | `logs/FMM_sina_dataset_3.5GHz_NLoS+LoS_0.0_10000_19_05_2026_14_30/` |
+
+### cFMM — 28 GHz, LoS
+
+| `N_train` | Directory |
+|---|---|
+| 200 | `logs/FMM_sina_dataset_28GHz_LoS_0.0_200_13_05_2026_15_08/` |
+| 500 | `logs/FMM_sina_dataset_28GHz_LoS_0.0_500_28_05_2026_09_34/` |
+| 1 000 | `logs/FMM_sina_dataset_28GHz_LoS_0.0_1000_27_05_2026_08_55/` |
+
+---
+
+## Checkpoint contents
+
+Each model directory contains:
+
+| File | Description |
+|---|---|
+| `model.pth` | PyTorch state-dict of the trained model |
+| `training_config.txt` | Hyperparameters used during training |
+| `training_log.txt` | Loss curves and validation metrics logged during training |
+| `indices.npy` | Shuffled dataset indices defining the train/val/test split |
+| `train.npy` / `val.npy` / `test.npy` | Pre-processed channel arrays for each split |
+| `train_coords.npy` / `val_coords.npy` / `test_coords.npy` | Corresponding UE coordinates |
+
+> **Important:** The `indices.npy` file fixes the data split. cFMM checkpoints reuse the indices from the corresponding cDDIM run to ensure identical splits across both models.
+
+---
+
+## Downloading the checkpoints
+
+```bash
+git clone https://huggingface.co/PaulAlm/GenAI_Channel_Modeling_Models
+cd GenAI_Channel_Modeling_Models
+unzip logs.zip
+```
+
+---
+
+## Running inference
+
+After downloading, set the `save_dir` variable in the inference script to the desired model directory and run:
+
+```bash
+# cDDIM — LoS
+python infer_cDDIM_LoS.py generate
+
+# cFMM — LoS
+python infer_cFMM_LoS.py generate
+```
+
+Full instructions are in the [code repository](https://github.com/Telefonica-Scientific-Research/GenAI_Channel_Modeling/tree/main/cDDIM_and_cFMM).
+
+---
+
+## Training details
+
+| Hyperparameter | cDDIM | cFMM |
+|---|---|---|
+| Epochs | 3 000 | 2 000 |
+| Batch size | 100 | 100 |
+| Learning rate | 1 × 10⁻⁴ | 1 × 10⁻⁴ |
+| Inference steps | 150 (DDIM) | 10 (Euler) |
+| Conditioning | 3D UE coordinates | 3D UE coordinates |
+| Guidance weight | 0.0 | 0.0 |
+| Model parameters | ~15.6 M | ~15.6 M |
+
+---
+
+## Datasets
+
+The corresponding channel datasets are available at:  
+**[https://huggingface.co/datasets/PaulAlm/GenAI_Channel_Modeling_Datasets](https://huggingface.co/datasets/PaulAlm/GenAI_Channel_Modeling_Datasets)**
+
+---
+
+## Citation
+
+If you use these models, please cite:
+
+```bibtex
+@article{beyraghi2025sitespecific,
+  title   = {Site-Specific MIMO Channel Generation via Diffusion and Flow Matching:
+             Fidelity, Efficiency, and Downstream Utility},
+  author  = {Beyraghi, Sina and Sadeghian, Masoud and Bin Ismail, Firdous and
+             Lozano, Angel and Almasan, Paul and Geraci, Giovanni},
+  journal = {arXiv preprint arXiv:2510.10190},
+  year    = {2025}
+}
+```