README.md

---
pipeline_tag: other
---

# PhysiFormer: Learning to Simulate Mechanics in World Space

PhysiFormer (pronounced *fizzy-former*) is a diffusion transformer for physically-plausible 3D object motion. Unlike video world models that operate in view-dependent pixel space, PhysiFormer represents objects as 3D meshes expressed in world coordinates. Given the initial vertex positions and velocities, as well as object material type (rigid or elastic), the model samples future vertex trajectories directly in world coordinates.

* **Paper:** [PhysiFormer: Learning to Simulate Mechanics in World Space](https://huggingface.co/papers/2606.27364)
* **Project Page:** [https://yimingc9.github.io/physiformer](https://yimingc9.github.io/physiformer)
* **GitHub Repository:** [https://github.com/yimingc9/PhysiFormer](https://github.com/yimingc9/PhysiFormer)
* **Demo:** [Hugging Face Space](https://huggingface.co/spaces/yslan/PhysiFormer)

## ⚙️ Setup

```bash
# Create conda environment
conda create -n physiformer python=3.10 -y
conda activate physiformer

# Install PyTorch (CUDA 12.4)
pip install torch==2.5.1 torchvision==0.20.1 --index-url https://download.pytorch.org/whl/cu124

# Install remaining requirements, including the prebuilt flash-attn wheel.
pip install -r requirements.txt
```

## 🤗 Model Access & Inference

Download the checkpoint from Hugging Face before running scripts:

```bash
huggingface-cli download yslan/physiformer checkpoint-best.pt --local-dir checkpoints
```

Run in-distribution test set inference:

```bash
bash scripts/run_indistri_example.sh
```

Run OOD inference for generalisation to complex geometries:

```bash
bash scripts/run_ood_example.sh
```

## Citation

```bibtex
@article{chen2026physiformer,
  title={PhysiFormer: Learning to Simulate Mechanics in World Space},
  author={Chen, Yiming and Lan, Yushi and Vedaldi, Andrea},
  journal={arXiv preprint arXiv:2606.27364},
  year={2026}
}
```