README.md

---
language:
- en
license: apache-2.0
base_model:
- Qwen/Qwen3-VL-4B-Instruct
- Wan-AI/Wan2.2-TI2V-5B
tags:
- world-model
- physical-language
- video-generation
- image-to-video
- motion-transfer
- qwen3-vl
- wan2.2
- arxiv:2607.28624
---

# PhiZero

Official checkpoints for **PhiZero: A World Model Built Around Physical
Language**.

PhiZero reasons about future dynamics in a discrete **Physical Language**
before rendering those dynamics as video.

- [Project page](https://phi-zero.github.io/)
- [Paper](https://arxiv.org/abs/2607.28624)
- [Code](https://github.com/yaoyao-jpg/PhiZero)

## Repository contents

```text
.
├── reasoner/
│   ├── config.json
│   ├── model-00001-of-00002.safetensors
│   ├── model-00002-of-00002.safetensors
│   ├── model.safetensors.index.json
│   └── tokenizer and processor files
└── tokenizer/
    ├── tokenizer.safetensors
    └── model_config.json
```

### Physical Language Reasoner

`reasoner/` contains the Qwen3-VL-based Physical Language Reasoner. Given a
first frame and an English motion caption, it predicts:

```text
<bom> + 256 Physical Language symbols + <eom>
```

The Physical Language vocabulary contains 25,000 symbols, from `<m_0>` through
`<m_24999>`.

### Physical Language Tokenizer and diffusion decoder

`tokenizer/tokenizer.safetensors` contains:

- the Physical Language Tokenizer;
- the inverse-FSQ and context-conditioning modules;
- the PhiZero DiT LoRA weights.

Keep `tokenizer/model_config.json` beside the checkpoint. The official
Wan2.2-TI2V-5B base DiT and VAE are not included here. They are resolved
separately by the PhiZero code or supplied through local Wan checkpoint paths.

## Download

While this repository is private, authenticate with an account that has access:

```bash
hf auth login
```

Clone the PhiZero code and download all checkpoints into the layout expected by
the release:

```bash
git clone https://github.com/yaoyao-jpg/PhiZero
cd PhiZero

hf download ShuyaoShang/PhiZero --local-dir ckpt
```

The resulting directory is:

```text
PhiZero/
└── ckpt/
    ├── reasoner/
    └── tokenizer/
```

Download only the tokenizer/decoder checkpoint:

```bash
hf download ShuyaoShang/PhiZero \
  tokenizer/tokenizer.safetensors \
  tokenizer/model_config.json \
  --local-dir ckpt
```

Download only the reasoner:

```bash
hf download ShuyaoShang/PhiZero \
  --include "reasoner/*" \
  --local-dir ckpt
```

## Usage

Follow the installation, training, and inference instructions in the
[PhiZero code repository](https://github.com/yaoyao-jpg/PhiZero).

The default local checkpoint paths are:

```bash
export PHIZERO_REASONER_CHECKPOINT="${PWD}/ckpt/reasoner"
export PHIZERO_DECODER_CHECKPOINT="${PWD}/ckpt/tokenizer/tokenizer.safetensors"
```

## Important note for motion transfer

The included `tokenizer/tokenizer.safetensors` is a general initialization
checkpoint and cannot be used directly for robot-domain or sim-to-real motion
transfer. First fine-tune it with videos from the same domain as the source
motion.

If no additional domain-matched data are available, the source videos can be
used directly through reconstruction training. Target videos and paired
source-target data are not required. See the source-domain adaptation section
in the PhiZero code repository before running motion transfer.

## Model settings

- Output resolution: 896 x 512
- Output length: 33 frames
- Frame rate: 8 FPS
- Physical Language length: 256 symbols
- Physical Language codebook size: 25,000
- Default diffusion steps: 50

## Intended use and limitations

PhiZero is intended for research on physical-dynamics reasoning, video world
models, reconstruction, and motion transfer.

It is not a guaranteed physical simulator. Generated dynamics can be
inaccurate, unstable, or inconsistent with real-world constraints. Results
should not be used directly for safety-critical control or decision-making.

Inference requires the custom PhiZero code. These checkpoints are not intended
to run through the standard hosted Hugging Face inference widget. Users must
also comply with the licenses and terms of the upstream base models.

## Citation

```bibtex
@article{shang2026phizero,
  title   = {PhiZero: A World Model Built Around Physical Language},
  author  = {Shang, Shuyao and Wang, Yuqi and Gao, Ruopeng and Chen, Xu and
             Tan, Tieniu and Fan, Lue and Zhang, Zhaoxiang},
  journal = {arXiv preprint arXiv:2607.28624},
  year    = {2026}
}
```