README.md

---
license: mit
library_name: pytorch
tags:
  - wireless
  - channel-modeling
  - foundation-model
  - deepmimo
---

# MultiPathFormer Foundation Checkpoint

This model card accompanies the released foundation checkpoint for:

**MultiPathFormer: A Foundation Model for Multipath Wireless Propagation**

Code release:

https://github.com/gblessed/MultiPathFormer

Hugging Face model repo:

https://huggingface.co/gblessed/multipathformer

## Model

- Architecture: first-step residual corridor-concat MultiPathFormer.
- Hidden dimension: 1024.
- Decoder layers: 12.
- Attention heads: 8.
- Prefix tokens: 4.
- Maximum generated paths: 25.
- Outputs: delay, scaled power, phase, AoA azimuth/elevation, AoD azimuth/elevation, and interaction labels.

## Training Data

The checkpoint was trained on 27 DeepMIMO ray-tracing scenarios listed in `configs/foundation_27scenarios.yaml`.

## Intended Use

The model is intended for research on geometry-aware wireless propagation modeling and downstream task reuse. It should be used with the preprocessing artifacts released alongside the checkpoint.

## Quick Inference Example

Install the code release and dependencies:

```bash
git clone https://github.com/gblessed/MultiPathFormer.git
cd MultiPathFormer
python -m pip install -r requirements.txt
```

Run inference from an already constructed augmented prompt and first-step baseline:

```python
import json
from pathlib import Path

import numpy as np
from huggingface_hub import hf_hub_download

from multipathformer.inference import MultiPathFormerPredictor, prediction_to_rows

repo_id = "gblessed/multipathformer"
checkpoint = hf_hub_download(
    repo_id=repo_id,
    filename="first_step_residual_corridor_concat_27scenarios_44710a4a_best_model_checkpoint.pth",
)
artifacts = hf_hub_download(repo_id=repo_id, filename="preprocessing_artifacts.json")

augmented_prompt = np.asarray(
    json.loads(Path("examples/augmented_prompt.json").read_text()),
    dtype=np.float32,
)
first_step_baseline = np.asarray(
    json.loads(Path("examples/first_step_baseline.json").read_text()),
    dtype=np.float32,
)

predictor = MultiPathFormerPredictor(checkpoint, artifacts_path=artifacts)
prediction = predictor.predict_from_augmented_prompt(
    augmented_prompt,
    first_step_baseline,
    max_steps=25,
)

for row in prediction_to_rows(prediction)[:5]:
    print(row)
```

The augmented prompt follows the released corridor-concat recipe: TX/RX position, first-step delay/power baseline, first-step standard deviation, and scene/corridor descriptors. The helper script `inference_example.py` in this model repo contains the same flow.

## Limitations

The checkpoint is trained on simulated ray-tracing data. It has not yet been validated as a standalone replacement for real-world measurement campaigns. Phase-accurate channel synthesis is especially sensitive and should be evaluated carefully for each use case.

## Files

- `first_step_residual_corridor_concat_27scenarios_44710a4a_best_model_checkpoint.pth`
- `preprocessing_artifacts.json`
- Optional: `model.safetensors`