MultiPathFormer

MultiPathFormer is a foundation model for multipath wireless propagation. Given transmitter/receiver geometry and compact scene/corridor descriptors, it autoregressively predicts path-level delay, power, phase, angles of arrival/departure, and interaction labels.

This repository is the clean release companion for the paper:

MultiPathFormer: A Foundation Model for Multipath Wireless Propagation

Model weights and the Hugging Face model card are available at:

https://huggingface.co/gblessed/multipathformer

What Is Included

• A reusable multipathformer Python package.
• scripts/train_foundation.py for training the first-step residual corridor-concat model.
• scripts/infer_single_scenario.py for inference from a released checkpoint.
• configs/foundation_27scenarios.yaml with the foundation scenario list and architecture.
• Weight download/conversion helpers.

The large checkpoint is not stored in Git history. Use the Hugging Face model repo for the released weights.

Installation

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

DeepMIMO scenarios must be installed/resolvable in the same way as in your DeepMIMO workflow.

Download Weights

After the Hugging Face model repo is created:

python scripts/download_weights.py \
  --repo-id gblessed/multipathformer \
  --local-dir weights

The expected checkpoint filename is:

first_step_residual_corridor_concat_27scenarios_44710a4a_best_model_checkpoint.pth

Inference

The simplest inference path uses an already constructed augmented prompt and first-step baseline:

python scripts/infer_single_scenario.py \
  --checkpoint weights/first_step_residual_corridor_concat_27scenarios_44710a4a_best_model_checkpoint.pth \
  --artifacts weights/preprocessing_artifacts.json \
  --augmented-prompt-json examples/augmented_prompt.json \
  --first-step-baseline-json examples/first_step_baseline.json \
  --max-steps 25 \
  --output outputs/predicted_paths.csv

The output CSV contains one row per generated path with delay, scaled power, phase, AoA/AoD angles, and interaction indicators.

Training

To train the released foundation variant:

python scripts/train_foundation.py \
  --config configs/foundation_27scenarios.yaml \
  --checkpoint-dir checkpoints \
  --artifact-dir weights

For a quick single-scenario run:

python scripts/train_foundation.py \
  --scenario city_23_beijing_3p5 \
  --epochs 2 \
  --checkpoint-dir checkpoints_smoke \
  --artifact-dir weights_smoke \
  --skip-generation-eval

Released Foundation Configuration

The paper checkpoint uses:

• Model family: first-step residual corridor-concat.
• Hidden dimension: 1024.
• Decoder layers: 12.
• Attention heads: 8.
• Prefix tokens: 4.
• Maximum generated paths: 25.
• AOD prediction: enabled.
• Foundation training scenarios: the 27 scenarios listed in configs/foundation_27scenarios.yaml.

Notes For Reproducibility

The model expects the same feature construction used during training:

• TX/RX position prompt.
• First-step delay/power baseline and standard deviation from training-set cluster assignment.
• Local RX/TX building descriptors.
• TX-RX corridor descriptors.
• Prompt standardization using preprocessing_artifacts.json.

If you use a different baseline/std assignment rule at inference time, report it clearly because it changes the conditioning distribution.

Limitations

The released checkpoint is trained on DeepMIMO ray-tracing scenarios. Real-world measurement validation, dynamic mobility effects, and direct phase-accurate channel synthesis remain important future directions.

Citation

@inproceedings{multipathformer2026,
  title={MultiPathFormer: A Foundation Model for Multipath Wireless Propagation},
  year={2026}
}