Metadata-Version: 2.4
Name: respolygp
Version: 0.1.0
Summary: ResPolyGP: Orthogonal Legendre Trajectory Gaussian Process Prior Model
Author: Haranadhg
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: torch
Requires-Dist: gpytorch

# 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:

```bash
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`.

```python
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`:

```python
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.
