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

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

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.

• 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

# install pytorch with cuda support (change cu126 to your cuda version if needed)
pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu126

# install required packages
pip install -r requirements.txt

Our experiments are conducted on the YJMob100k dataset. To reproduce results, please download the dataset and place it under dataset/yj/.

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

# Preprocess raw data
bash scripts/preprocess.sh

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:

# Training
bash scripts/train.sh

You can evaluate the trained model on different cities by running the following scripts:

# Evaluation
bash scripts/evaluate.sh

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)

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:

@article{he2025rhythm,
  title={RHYTHM: Reasoning with Hierarchical Temporal Tokenization for Human Mobility},
  author={He, Haoyu and Luo, Haozheng and Chen, Yan and Wang, Qi R},
  journal={arXiv preprint arXiv:2509.23115},
  year={2025}
}

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

• Haoyu He (he.haoyu1@northeastern.edu)
• Robin Luo (hluo@u.northwestern.edu)