gp-tempest 0.1.2

Gaussian Process Temporal Embedding for Protein Simulations and Transitions

GP-TEMPEST

Gaussian Process Temporal Embedding for Protein Simulations and Transitions

Documentation • Tutorial • Features • Installation • Usage • Citation

---

GP-TEMPEST is a PyTorch implementation of the Gaussian Process Variational Autoencoder (GP-VAE) framework for time-aware dimensionality reduction of molecular dynamics (MD) simulations. The method leverages physics-informed Gaussian Process priors to capture temporal correlations in the latent space, enabling the recovery of hidden or kinetically relevant degrees of freedom in complex biomolecular systems.

Features

• Physics-informed dimensionality reduction using Gaussian Processes as temporal priors
• Flexible kernel selection with support for the Matérn kernel (ν = 0.5, 1.5, 2.5)
• Sparse GP inference with inducing points for scalability to large molecular trajectories
• Recovery of hidden degrees of freedom not accessible in any projection of the input data
• Free-energy landscapes and kinetic insight from GP-smoothed, physically interpretable latent coordinates

Installation

pip install gp-tempest

Note: PyTorch is listed as a dependency but pip will install the CPU version by default. For GPU support install torch manually first:

pip install torch --index-url https://download.pytorch.org/whl/cu118
pip install gp-tempest

From source:

git clone https://github.com/moldyn/GP-TEMPEST.git
cd GP-TEMPEST
pip install -e .

Usage

Command-line interface

Fully-connected variant:

# Generate a default config file
python tempest_main.py --generate_config

# Run with your config
python tempest_main.py --config my_config.yaml

Python API

import numpy as np
import torch
from gptempest import TEMPEST, MaternKernel, load_prepare_data

# Set up kernel and model
kernel = MaternKernel(scale=10.0, nu=1.5, dtype=torch.float64)
inducing_points = np.linspace(0, 1, 50)

model = TEMPEST(
    cuda=False,
    kernel=kernel,
    dim_input=dim_input,
    dim_latent=2,
    layers_hidden_encoder=[128, 64],
    layers_hidden_decoder=[64, 128],
    inducing_points=inducing_points,
    beta=1.0,
    N_data=N_data,
    dtype=torch.float64,
)

# Train
model.train_model(dataset, train_size=1.0, learning_rate=1e-3,
                  weight_decay=1e-5, batch_size=512, n_epochs=100)

# Extract latent space
embedding = model.extract_latent_space(dataset, batch_size=512)

Configuration file

GP-TEMPEST is configured via YAML files. Generate a template with --generate_config and adjust the following key parameters. The discussion of these parameters can be found in the paper.

Parameter	Description
dim_latent	Dimensionality of the latent space (typically 2)
layers_hidden	Hidden layer sizes for encoder/decoder
kernel_nu	Matérn kernel smoothness (0.5, 1.5, or 2.5)
kernel_scale	Time-scale of the GP prior
beta	Weight of the GP regularization term
inducing_points	Path to inducing point time coordinates

Citation

If you use GP-TEMPEST in your research, please cite:

@article{diez2025gptempest,
  title   = {Recovering Hidden Degrees of Freedom Using Gaussian Processes},
  author  = {Diez, Georg and Dethloff, Nele and Stock, Gerhard},
  journal = {J. Chem. Phys.},
  volume  = {163},
  pages   = {124105},
  year    = {2025},
  doi     = {10.1063/5.0282147}
}

G. Diez, N. Dethloff, G. Stock, "Recovering Hidden Degrees of Freedom Using Gaussian Processes," J. Chem. Phys. 163, 124105 (2025), https://doi.org/10.1063/5.0282147

License

This project is licensed under the MIT License — see the LICENSE file for details.