New-LTPP is a modern and flexible framework for learning, simulating, and analyzing Temporal Point Processes (TPP). It is built on PyTorch and PyTorch Lightning for scalability and research efficiency.
New-LTPP is designed to be a comprehensive toolkit for TPP research, covering the entire lifecycle from training to advanced evaluation.
- Multi-Model Support: Train various Neural TPP models (NHP, THP, ODETPP, etc.) on standard or custom datasets.
- PyTorch Lightning: Benefits from distributed training, automatic checkpointing, and robust logging.
- Flexible Configs: Easy hyperparameter tuning via YAML files or CLI overrides.
- Synthetic Data Generation: Generate event sequences using known processes (Hawkes, Self-Correcting) for controlled experiments.
- Path Simulation: Simulate entire future trajectories (event sequences) from trained models to analyze long-term dynamics, not just next-step predictions.
- Distribution Matching: Evaluate models by comparing the distributions of simulated sequences against real data (e.g., inter-event times, event types).
- Prediction Metrics: Standard metrics for next-event prediction (RMSE, Accuracy).
- 🚧 Goodness of Fit (WIP): We are currently developing statistical tests (e.g., KS test, QQ plots) to rigorously quantify model fit.
Prerequisites: Python 3.11+
This project uses uv for dependency management.
# Install dependencies
uv syncpip install -e .To verify everything is working, use the Makefile target that runs a quick end-to-end pipeline (Train → Test → Predict):
make run-demoCreates artifacts in artifacts/test/NHP_.../
You can run experiments directly using the new-ltpp command (or scripts/cli.py).
# Using the installed script entry point
new-ltpp run --model THP --dataset-id taxi --phase train --epochs 50
# OR using the python script directly
python scripts/cli.py run --model THP --dataset-id taxi --phase train --epochs 50If you are unsure about parameters, use the interactive wizard:
new-ltpp setup
# Follow the prompts to configure your experimentThe framework provides a unified CLI new-ltpp (or python scripts/cli.py).
| Command | Description | Example |
|---|---|---|
run |
Run a TPP experiment (train/test/predict). | new-ltpp run --model NHP --phase all |
inspect |
Inspect and visualize dataset statistics. | new-ltpp inspect data/taxi --save |
generate |
Generate synthetic TPP data (Hawkes, etc.). | new-ltpp generate --model hawkes --num-sim 1000 |
benchmark |
Run naïve benchmarks. | new-ltpp benchmark --dataset-id test |
setup |
Launch interactive configuration wizard. | new-ltpp setup |
info |
Display system and environment info. | new-ltpp info |
Implemented models in new_ltpp/models/:
| Model | Paper | Implementation |
|---|---|---|
| RMTPP | KDD'16 | rmtpp.py |
| NHP | NeurIPS'17 | nhp.py |
| FullyNN | NeurIPS'19 | fullynn.py |
| SAHP | ICML'20 | sahp.py |
| THP | ICML'20 | thp.py |
| IntFree | ICLR'20 | intensity_free.py |
| ODETPP | ICLR'21 | ode_tpp.py |
| AttNHP | ICLR'22 | attnhp.py |
We use a hierarchical YAML configuration system located in yaml_configs/configs.yaml.
You can override configurations via CLI arguments (e.g., --training-config quick_test) or by creating your own YAML files.
Key Config Sections:
- Data Config: Dataset paths and formats (
test,taxi,retweet). - Model Config: Hyperparameters for each model (
NHP,THP). - Training Config: Epochs, batch size, learning rate (
quick_test,full_training).
All results are saved in the artifacts/ directory by default (configurable via --save-dir).
- Checkpoints: Best model weights.
- Logs: TensorBoard logs (view with
tensorboard --logdir artifacts). - Results: JSON files with metrics and prediction outputs.
MIT License