README.md

---
base_model: Wan-AI/Wan2.1-T2V-1.3B
language:
- en
license: apache-2.0
pipeline_tag: text-to-video
tags:
- text-to-video
- video-generation
- human-motion
- reinforcement-learning
- lora
---

# PhyMotion — Causal Forcing 1.3B

LoRA adapter for **Causal Forcing 1.3B** (the autoregressive distilled version of Wan2.1 T2V-1.3B), post-trained with RL using the **PhyMotion** reward — a structured 3D motion reward grounded in SMPL recovery and MuJoCo inverse dynamics.

* **Paper:** [PhyMotion: Structured 3D Motion Reward for Physics-Grounded Human Video Generation](https://huggingface.co/papers/2605.14269)
* **Project Page:** https://phy-motion.github.io
* **Repository:** https://github.com/h6kplus/PhyMotion
* **Prompt Dataset:** [6kplus/PhyMotion-MotionX-Prompts](https://huggingface.co/datasets/6kplus/PhyMotion-MotionX-Prompts)

## Description
Generating realistic human motion is a central yet unsolved challenge in video generation. PhyMotion is a structured, fine-grained motion reward that grounds recovered 3D human trajectories in a physics simulator and evaluates motion quality along multiple dimensions of physical feasibility: kinematic plausibility, contact and balance consistency, and dynamic feasibility.

## What's in this repo

| File | Description |
|---|---|
| `adapter_model.bin` | PEFT LoRA weights (rank 256, targets `CausalWanAttentionBlock`) |
| `adapter_config.json` | LoRA configuration |

## Usage

To use this LoRA adapter, clone the [PhyMotion repository](https://github.com/h6kplus/PhyMotion), place the base model checkpoint and this LoRA, then run inference (full instructions available in the repository README):

```bash
git clone https://github.com/h6kplus/PhyMotion.git
cd PhyMotion

# Download this LoRA adapter
huggingface-cli download 6kplus/PhyMotion-CausalForcing-1.3B \
  --local-dir checkpoints/phymotion-causalforcing

# Download MotionX prompts (train + test)
huggingface-cli download 6kplus/PhyMotion-MotionX-Prompts \
  --repo-type dataset --local-dir dataset/motionx

# Inference
# Note: You still need the base Causal Forcing 1.3B checkpoint (causal_forcing.pt)
torchrun --nproc_per_node=1 scripts/inference_wan.py \
  --base_model checkpoints/causalforcing/chunkwise/causal_forcing.pt \
  --lora_path  checkpoints/phymotion-causalforcing \
  --prompt_file dataset/motionx/test.txt \
  --output_dir outputs/test \
  --num_frames 45 --height 480 --width 832 \
  --guidance_scale 3.0 \
  --denoising_steps "1000,750,500,250" \
  --num_frame_per_block 3 \
  --mixed_precision bf16 --seed 42
```

## Citation

```bibtex
@article{huang2026phymotion,
  title   = {PhyMotion: Structured 3D Motion Reward for Physics-Grounded Human Video Generation},
  author  = {Huang, Yidong and Wang, Zun and Lin, Han and Kim, Dong-Ki and
             Omidshafiei, Shayegan and Yoon, Jaehong and Cho, Jaemin and
             Zhang, Yue and Bansal, Mohit},
  journal = {arXiv preprint arXiv:2605.14269},
  year    = {2026}
}
```

## License

Apache 2.0. The base Wan2.1 / Causal Forcing weights retain their original license.