RHYTHM: Reasoning with Hierarchical Temporal Tokenization for Human Mobility

The official implementation of RHYTHM: Reasoning with Hierarchical Temporal Tokenization for Human Mobility.

Contents

• RHYTHM: Reasoning with Hierarchical Temporal Tokenization for Human Mobility
  • 1. Introduction
  • 2. Prerequisites
  • 3. Data
  • 4. Usage
    • 4.1 Preprocess
    • 4.2 Training
    • 4.3 Evaluate
  • 5. Acknowledgement
  • 6. Citation
  • 7. Contact

Introduction

RHYTHM (Reasoning with Hierarchical Temporal Tokenization for Human Mobility) reframes mobility prediction through a foundation-model lens: it compresses long trajectories into structured temporal tokens, uses hierarchical attention to capture daily/weekly rhythms, and injects pre-computed prompt-guided semantic context—all while keeping the LLM backbone frozen for lightweight, scalable adaptation. The result is a simple, compute-efficient recipe that preserves LLM reasoning, travels well across cities, and hints at practical scaling behavior for spatio-temporal foundation models.

Prerequisites

• Python 3.10+
• PyTorch
• Hugging Face Transformers
• Other dependencies listed in requirements.txt

# create and activate virtual python environment
conda create -n rhythm python=3.10
conda activate rhythm
pip install transformers
pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu126

# install required packages
pip install -r requirements.txt

Data

Our experiments are conducted on the YJMob100k dataset.

Usage

1. Preprocess

First, preprocess your raw trajectory files and compute semantic embeddings offline:

# Preprocess raw data
bash scripts/preprocess.sh

2. Training

Trained model outputs, logs, and final metrics are saved under the log/ directory, and checkpoints are saved under the checkpoints/ directory. You can train the model on different cities by running the following scripts:

# Train on City B
bash scripts/b.sh

# Train on City C
bash scripts/c.sh

# Train on City D
bash scripts/d.sh

3. Evaluate

Coming soon...

Acknowledgement

We appreciate the following GitHub repos a lot for their valuable code and efforts.

• Time-Series-Library (https://github.com/thuml/Time-Series-Library)
• AutoTimes (https://github.com/thuml/AutoTimes)
• ST-MoE-BERT (https://github.com/he-h/ST-MoE-BERT)

Citation

If you have any questions regarding our paper or code, please feel free to start an issue.

If you use RHYTHM in your work, please kindly cite our paper:

@misc{he2025rhythmreasoninghierarchicaltemporal,
      title={RHYTHM: Reasoning with Hierarchical Temporal Tokenization for Human Mobility}, 
      author={Haoyu He and Haozheng Luo and Yan Chen and Qi R. Wang},
      year={2025},
      eprint={2509.23115},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2509.23115}, 
}

Contact

If you have any questions or want to use the code, feel free to contact:

• Haoyu He ([email protected])
• Robin Luo ([email protected])