File size: 4,168 Bytes
08099e9 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | ---
language:
- en
library_name: pytorch
tags:
- physics
- physical-simulation
- trajectory-prediction
- hamiltonian
- diffusion
datasets:
- HamiFormer/Hamiballs
---
# HamiFormer models
Inference weights for HamiFormer and baseline models on HamiBalls-1 and HamiBalls-2. HamiFormer combines whole-window diffusion prediction with Hamiltonian propagation through affine symplectic maps and regime-conditioned corrections.
[Code and instructions](https://github.com/HamiFormer/HamiFormer) · [HamiBalls datasets](https://huggingface.co/datasets/HamiFormer/Hamiballs)
## Available weights
| File under `weights/` | Dataset | Method | Evaluation argument |
|---|---|---|---|
| `hami1_ours.pt` | HamiBalls-1 | HamiFormer | `--dataset h1 --method ours` |
| `hami1_physiformer.pt` | HamiBalls-1 | PhysiFormer | `--dataset h1 --method physiformer` |
| `hami1_hgdpf.pt` | HamiBalls-1 | Hamiltonian-Guided Diffusion Fields | `--dataset h1 --method hgdpf` |
| `hami2_ours.pt` | HamiBalls-2 | HamiFormer | `--dataset h2 --method ours` |
| `hami2_physiformer.pt` | HamiBalls-2 | PhysiFormer | `--dataset h2 --method physiformer` |
| `hami2_dit.pt` | HamiBalls-2 | Diffusion Transformer | `--dataset h2 --method dit` |
| `hami2_transformer_ar1.pt` | HamiBalls-2 | Transformer-AR, context 1 | `--dataset h2 --method transformer_ar1` |
| `hami2_transformer_ar4.pt` | HamiBalls-2 | Transformer-AR, context 4 | `--dataset h2 --method transformer_ar4` |
Files contain tensor dictionaries loaded by the corresponding implementations in the code repository.
## Download and evaluate
Use Python 3.10–3.12, PyTorch 2.5.1, and a compatible CUDA environment.
```sh
git clone https://github.com/HamiFormer/HamiFormer.git
cd HamiFormer
python -m pip install -e ".[test,data,analysis]"
python -m pip install huggingface_hub
```
Download the weights and datasets from Python:
```python
from huggingface_hub import snapshot_download
snapshot_download(
repo_id="HamiFormer/HamiFormer-Assets",
allow_patterns="weights/*.pt",
local_dir="assets",
)
snapshot_download(
repo_id="HamiFormer/Hamiballs",
repo_type="dataset",
allow_patterns="*.h5",
local_dir="assets/data",
)
```
Run a small evaluation on each dataset:
```sh
python run.py evaluate --dataset h1 --method ours --data assets/data/hamiballs1.h5 --weights assets/weights --limit 2 --output results/h1_ours
python run.py evaluate --dataset h2 --method ours --data assets/data/hamiballs2.h5 --weights assets/weights --limit 2 --output results/h2_ours
```
Omit `--limit` to evaluate all 512 validation trajectories. The default protocol uses two noise seeds and 192 predicted transitions. HamiFormer predicts four consecutive 48-transition windows. The evaluator reports normalized state, position, and momentum MSE, contact-conditioned metrics, and disjoint-interval metrics, and writes `metrics.json` and `trajectories.npz` to the requested output directory. Use a new output directory for each run.
## Inputs and outputs
Inputs are an initial phase-space state, object attributes, and physical times. HamiBalls-2 additionally supplies object and spring-graph information. Each object's state is ordered as `[q, p]`, where `p` is momentum. The evaluation entry point handles normalization using the model's stored scales and returns trajectories in the dataset's physical coordinates.
For direct component loading:
```python
from hamiformer.models.hamiformer import HamiFormer
model = HamiFormer.from_pretrained("assets/weights", dataset="h2", device="cuda")
components = model.components()
```
## Intended use
These models support research on learned physical simulation and trajectory prediction in the HamiBalls spring-and-contact environments. The matching dataset conventions, physical time step, and object representation are described in the [dataset card](https://huggingface.co/datasets/HamiFormer/Hamiballs).
The project code is distributed under the [MIT license](https://github.com/HamiFormer/HamiFormer/blob/main/LICENSE). See [third-party notices](https://github.com/HamiFormer/HamiFormer/blob/main/THIRD_PARTY_NOTICES.md) for baseline references and attribution.
|