haodongcui/HaM_World

[NeurIPS 2026] HaM-World

Soft-Hamiltonian World Models with Selective Memory for Planning

Haoyun Tang¹*, Haodong Cui²*, Keyao Xu³, Zhandong Mei¹†, Kun Wang⁴†

¹ Xi'an Jiaotong University    ² Huazhong University of Science and Technology
³ Nankai University    ⁴ Nanyang Technological University

* Equal contribution. † Corresponding authors.

Hugging Face release

This model repository contains the HaM-World code, baseline code, raw runs, checkpoints, logs, and paper results. It preserves the repository-relative paths used by the scripts and result manifests. The source-code repository and its Git history are maintained at HaoyunT/HaM_World.

Download the complete release to keep those paths intact:

hf download haodongcui/HaM_World --local-dir ./HaM_World
cd HaM_World

HaM-World checkpoints are under runs/main/model_based/runs/hamworld/<task>/<seed_run>/checkpoints/. For example, the final Cartpole checkpoint for seed 7 is runs/main/model_based/runs/hamworld/cartpole_swingup/seed_7_20260415-144740/checkpoints/checkpoint_100000.pt. The matching run configuration, logs, and analysis files remain beside it. These .pt files are project-specific PyTorch training checkpoints, not Transformers from_pretrained() packages; load them with this repository's code.

After installing the dependencies below, this command reads the preserved run manifest and checkpoint paths to render a Cartpole evaluation rollout:

python scripts/render_hamworld_checkpoints.py --tasks cartpole_swingup

This rendering script also needs Pillow (pip install Pillow). Run Python checkpoint files only from sources you trust, since PyTorch checkpoints may contain pickled objects.

News

• Sep. 2026: 🎉 HaM-World has been accepted by NeurIPS 2026.
• May 2026: HaM-World is available on arXiv, with the research code released.

About

Hugging Face model and artifact repository for the NeurIPS 2026 paper HaM-World: Soft-Hamiltonian World Models with Selective Memory for Planning. The canonical source-code repository is on GitHub.

Overview

HaM-World is a world-model framework for long-horizon planning. It combines a soft-Hamiltonian latent dynamics model with a selective memory mechanism so that the planner can preserve useful history while maintaining a structured latent state for imagined rollouts.

The latent state is decomposed into a Hamiltonian state and a semantic context:

• the Hamiltonian state models structured position/momentum-like dynamics;
• the semantic context carries task-relevant information that is not captured by the physical state alone;
• selective memory summarizes long histories and filters irrelevant observations;
• energy, residual/control dynamics, and value estimation are exposed through a planner-facing latent interface.

The repository contains the canonical implementation, baseline agents, paper result exports, mechanism-analysis traces, and scripts used to rebuild the paper-facing figures and tables.

Repository Contents

The maintained comparison includes:

• HaM-World
• DreamerV3
• TD-MPC2
• PPO
• SAC

The repository keeps full raw runs for the main comparison and compact, paper-facing exports for OOD, ablation, and mechanism analyses. Exploratory sweeps and failed reruns are intentionally excluded.

Results

Paper-facing results are available directly in the repository:

• Main comparison table
• Main learning curves
• Long-horizon table
• OOD retention table
• Ablation table
• Mechanism figures
• Rollout overview

Installation

The reference environment uses Python 3.11. uv is recommended for a local editable environment:

uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt

The Conda environment is also provided:

conda env create -f environment.yml
conda activate ham_world

The main dependencies are PyTorch 2.2 or newer, Gymnasium with MuJoCo, dm-control, NumPy, PyYAML, tqdm, and Matplotlib. GPU execution is recommended for training and long-horizon evaluation.

Quick Start

List supported algorithms, presets, and configurations:

python launch.py list

Dry-run a HaM-World training plan:

python launch.py train \
  --algo hamworld \
  --preset compare_dmcontrol \
  --seed 7 \
  --output-root outputs \
  --dry-run

Train HaM-World on the Finger and Reacher preset:

python launch.py train \
  --algo hamworld \
  --preset finger_reacher \
  --seed 7 \
  --output-root outputs

Run all five maintained algorithms for one comparison preset:

python launch.py train \
  --algo all \
  --preset compare_dmcontrol \
  --seed 7 \
  --output-root outputs

The shell entrypoints under scripts/train/ provide equivalent paper-run commands. Set PYTHON_BIN when the environment uses a non-default Python executable.

Rebuild Paper Assets

Rebuild the main and analysis summaries with:

python scripts/rebuild_main_return_table.py
python scripts/rebuild_long_horizon_table.py
python scripts/replot_main_curves.py
python scripts/rebuild_ablation_core_table.py
python scripts/rebuild_ood_summaries.py
python scripts/rebuild_rollout_overview.py

For mechanism figures:

python scripts/replot_h_freerun.py
python scripts/replot_phase_portrait.py
python scripts/replot_pqc.py

Paths in result manifests are repository-relative, so the repository can be moved without manually rewriting experiment roots.

Repository Layout

HaM_World/
├── launch.py
├── environment.yml
├── requirements.txt
├── hamworld/                  # canonical HaM-World implementation
├── baselines/                 # DreamerV3 / TD-MPC2 / PPO / SAC
├── runs/main/                 # raw runs for the main comparison
├── results/
│   ├── main/                  # main curves, tables, and manifests
│   ├── ood/                   # compact OOD exports
│   ├── ablation/              # compact ablation exports
│   ├── mechanism/             # mechanism figures and trace bundles
│   └── appendix/              # appendix-only assets
├── assets/                    # architecture figures
└── scripts/                   # training, rebuild, and plotting utilities

launch.py is a convenience wrapper around the individual training modules. It selects algorithms and presets, applies seeds and output roots, expands multi-task configurations, and optionally resumes from checkpoints.

Citation

If you use HaM-World in your research, please cite:

@inproceedings{tang2026hamworld,
  title={HaM-World: Soft-Hamiltonian World Models with Selective Memory for Planning},
  author={Tang, Haoyun and Cui, Haodong and Xu, Keyao and Mei, Zhandong and Wang, Kun},
  booktitle={Advances in Neural Information Processing Systems},
  year={2026}
}

Acknowledgements

This repository includes implementations and comparison code for the baselines listed above. Please consult the corresponding source files and configuration headers for upstream attribution and usage requirements before redistribution.