respolygp 0.1.0

ResPolyGP: Orthogonal Legendre Trajectory Gaussian Process Prior Model

ResPolyGP

ResPolyGP is a Python library for Gaussian Process (GP) trajectory modeling that resolves standard exact GP computational bottlenecks and non-convex initialization challenges on non-stationary, cyclical sequence extrapolation.

By formulating secular polynomial trends as a structured finite-rank prior over Legendre orthogonal basis functions ($K = \Phi A \Phi^\top + \sigma_n^2 I$), ResPolyGP utilizes the Woodbury Matrix Identity and Matrix Determinant Lemma to project the standard cubic exact GP complexity onto a tiny basis space.

This accelerates exact GP polynomial trend inference from $O(N^3)$ time and $O(N^2)$ memory to $O(ND^2 + D^3)$ time and $O(ND + D^2)$ memory (where $D$ is the active basis degree, typically $D \le 5 \ll N$), delivering up to a 1000x computational speedup without any approximation.

---

Key Features

1. Orthogonal Bounded Legendre Kernels: Replaces standard unstable monomial trend kernels with recursively computed Legendre orthogonal polynomials mapped onto $x \in [-1, 1]$ to prevent floating-point underflow/overflow and preserve conditioning.
2. True $O(ND^2 + D^3)$ Woodbury Solver: Employs Woodbury matrix inversion and matrix determinant lemma in low-rank space, bypassing the Cholesky bottleneck and completely preventing NotPSDError.
3. Sequential Significance Early Stopping: Filters polynomial degrees dynamically via a variance-explained significance threshold ($q_d < 0.01$) to prevent overfitting to local noise crests.
4. Simplex-Constrained Softmax Priors: Normalizes and refines components on the simplex ($\sum \alpha_k = 1.0$), ensuring structural regularization.
5. Shape Parameter Freezing / Weights-Only Tuning: Locks shape parameters (e.g. Lomb-Scargle periods and ACF stochastic decay lengths) at their analytical time-domain values, optimizing only mixture weights to eliminate optimization drift.
6. Spectral Healing: Detrends secular trends analytically to restore stationarity before Lomb-Scargle periodic detection, reducing periodic extrapolation error by over 80%.

---

Installation

You can install ResPolyGP locally in editable mode for development:

pip install -e .

Dependencies

• Python >= 3.8
• numpy
• scipy
• torch
• gpytorch

---

Quickstart

Below is a simple example showing how to initialize, fit, and predict with ResPolyGPModel.

import numpy as np
from respolygp import ResPolyGPModel

# 1. Generate a noisy cubic trajectory
np.random.seed(42)
t_raw = np.linspace(10, 50, 100)
# Standardized time mapping to [-1, 1]
t_norm = (t_raw - 10) / 40.0 * 2.0 - 1.0
y_raw = 5.0 + 3.0 * t_norm - 2.0 * t_norm**2 + 4.0 * t_norm**3 + np.random.normal(0, 0.1, 100)

# 2. Instantiate and run Legendre trend decomposition
model = ResPolyGPModel(max_degree=5, sig_threshold=0.01, use_robust_scale=True)
decomp = model.fit_decomposition(t_raw, y_raw)
print(f"Active Legendre degrees: {decomp['parameters']['active_degrees']}")

# 3. Initialize hyperparameters from analytical time-domain components
model.initialize_hyperparameters(t_raw, y_raw)

# 4. Refine simplex weights via Adam optimizer
history = model.fit_gp(t_raw, y_raw, lr=0.05, epochs=15, verbose=True)

# 5. Predict out-of-sample in raw physical scale units
t_test = np.array([55.0, 60.0])
mean, var, lower, upper = model.predict_raw(t_test)
print(f"Extrapolated mean: {mean}")
print(f"Extrapolated variance: {var}")
print(f"95% Confidence Bounds: [{lower}, {upper}]")

For additive systems combining both Legendre trends and Lomb-Scargle periodic components, use MostlyFinalAdditiveGPModel:

from respolygp import MostlyFinalAdditiveGPModel

model = MostlyFinalAdditiveGPModel(max_degree=5, sig_threshold=0.01, use_robust_scale=True)
# Runs the full Sequential Reversal (Periodic-First) pipeline and initializes hyperparameters
model.initialize_hyperparameters(t_raw, y_raw)
# Refines simplex weights and noise under shape constraint
model.fit_gp(t_raw, y_raw, lr=0.05, epochs=15)

---

License

This project is licensed under the MIT License.