pilot-optimizer 0.1.0__tar.gz

pilot_optimizer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sattam Altwaim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pilot_optimizer-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: pilot-optimizer
+Version: 0.1.0
+Summary: PILOT: Policy-Informed Learned Optimization for Adaptive Deep Network Training
+Author-email: Sattam Altuuaim <sattam.tuuaim@kaust.edu.sa>, Lama Ayash <lama.ayash@kaust.edu.sa>, Muhammad Mubashar <muhammad.mubashar@strath.ac.uk>, Naeemullah Khan <naeemullah.khan@kaust.edu.sa>
+License: MIT
+Project-URL: Homepage, https://sattamaltwaim.github.io/PILOT/
+Project-URL: Repository, https://github.com/SattamAltwaim/PILOT
+Project-URL: Paper, https://arxiv.org/abs/submit/7629402
+Keywords: optimizer,deep-learning,pytorch,meta-learning,adaptive-optimization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Dynamic: license-file
+
+# PILOT: Policy-Informed Learned Optimization for Adaptive Deep Network Training
+
+> **PILOT** is an online adaptive optimizer that adjusts its update behavior during training using gradient-direction agreement as a signal of local optimization stability.
+
+---
+
+## Overview
+
+Most optimizers use a fixed update structure throughout training — a static balance between momentum, normalization, and sign-based updates that cannot respond to how the loss landscape evolves.
+
+**PILOT** introduces a learnable policy that continuously modulates three core update primitives:
+- **Momentum reliance** — how much to rely on accumulated gradient history vs. the current gradient
+- **Variance-normalization strength** — how aggressively to apply adaptive scaling
+- **Sign-based behavior** — how much to compress gradient magnitudes toward ±1
+
+The policy is conditioned on a smoothed gradient-direction agreement signal, which serves as a compact online descriptor of local update consistency. It is updated online during training using a one-step meta-gradient estimate — no offline search, no meta-training phase, no second-order estimation.
+
+![Loss Landscape — CIFAR-10 / SmallCNN](fig2_landscape.png)
+*PILOT follows a distinct trajectory through the loss surface and converges to a lower-loss region compared to Adam, AdamW, Lion, and Sophia.*
+
+---
+
+## Key Results
+
+### CNN Architecture
+
+| Dataset | Optimizer | Accuracy (%) ↑ | Val Loss ↓ | Loss Var. ↓ |
+|---|---|---|---|---|
+| FashionMNIST | Adam | 93.28 | 0.1957 | **0.0033** |
+| FashionMNIST | AdamW | 93.22 | 0.1944 | 0.0034 |
+| FashionMNIST | Lion | 92.91 | 0.2091 | 0.0041 |
+| FashionMNIST | AdaBelief | 93.66 | 0.1822 | 0.0046 |
+| FashionMNIST | **PILOT (Ours)** | **94.13** | **0.1719** | 0.0045 |
+| CIFAR-10 | Adam | 79.91 | 0.5794 | 0.0103 |
+| CIFAR-10 | Lion | 80.87 | 0.5487 | 0.0105 |
+| CIFAR-10 | **PILOT (Ours)** | **81.94** | **0.5302** | **0.0073** |
+
+### ResNet-18 Architecture
+
+| Dataset | Optimizer | Accuracy (%) ↑ | Val Loss ↓ | Loss Var. ↓ |
+|---|---|---|---|---|
+| FashionMNIST | AdaBelief | 95.33 | 0.1711 | 0.0056 |
+| FashionMNIST | **PILOT (Ours)** | **95.71** | 0.2690 | 0.0030 |
+| CIFAR-10 | Adam | 93.18 | **0.2140** | 0.0073 |
+| CIFAR-10 | AdamW | 92.90 | 0.2514 | 0.0066 |
+| CIFAR-10 | **PILOT (Ours)** | **93.42** | 0.2496 | **0.0001** |
+
+---
+
+## Method
+
+### Gradient-Direction Agreement
+
+At each step, PILOT computes the cosine similarity between successive gradients:
+
+$$r_t = \frac{g_t^\top g_{t-1}}{\|g_t\|_2 \, \|g_{t-1}\|_2 + \epsilon}$$
+
+This is smoothed via an exponential moving average:
+
+$$\rho_t = \gamma \rho_{t-1} + (1 - \gamma) r_t$$
+
+Positive values indicate stable, aligned gradients. Values near zero indicate noise. Negative values indicate directional disagreement.
+
+### Learnable Policy
+
+The smoothed signal $\rho_t$ is fed through polynomial functions followed by sigmoid activations to produce three scalar control variables:
+
+$$p_{m,t} = \sigma(f(\rho_t; \phi_m)), \quad p_{v,t} = \tfrac{1}{2}\sigma(f(\rho_t; \phi_v)), \quad p_{s,t} = \sigma(f(\rho_t; \phi_s))$$
+
+The total number of learnable policy parameters is $3(d+1)$, where $d$ is the polynomial degree.
+
+### Update Rule
+
+$$\theta_{t+1} = \theta_t - \eta \frac{(|n_t| + \epsilon_n)^{1 - p_{s,t}} \odot \text{sign}(n_t)}{\hat{v}_t^{\,p_{v,t}} + \epsilon}$$
+
+where $n_t = p_{m,t} \hat{m}_t + (1 - p_{m,t}) g_t$ is the policy-controlled blend of momentum and current gradient.
+
+This formulation recovers Adam ($p_m=1, p_v=0.5, p_s=0$) and sign-based updates ($p_s=1, p_v=0$) as special cases.
+
+---
+
+## Installation
+
+```bash
+pip install pilot-optimizer
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/SattamAltwaim/PILOT.git
+cd PILOT
+pip install -e .
+```
+
+---
+
+## Usage
+
+```python
+from pilot import PILOT
+
+optimizer = PILOT(
+    model.parameters(),
+    lr=1e-3,
+    betas=(0.9, 0.999),
+    weight_decay=1e-4,
+    gamma=0.95,        # smoothing coefficient for agreement signal
+    lr_phi=0.01,       # policy learning rate
+    degree=2           # polynomial degree
+)
+
+for batch in dataloader:
+    loss = criterion(model(x), y)
+    optimizer.zero_grad()
+    loss.backward()
+    optimizer.step()
+```
+
+---
+
+## Hyperparameters
+
+| Parameter | Description | Typical Range |
+|---|---|---|
+| `lr` | Model learning rate | `1e-4` – `1e-3` |
+| `betas` | Moment coefficients | `(0.9, 0.999)` |
+| `gamma` | Agreement signal smoothing | `0.85` – `0.99` |
+| `lr_phi` | Policy learning rate | `5e-4` – `5e-2` |
+| `degree` | Polynomial degree | `1` – `4` |
+
+### Configuration-Specific Selections
+
+| Dataset | Architecture | γ | η_φ | Degree |
+|---|---|---|---|---|
+| CIFAR-10 | CNN | 0.882 | 0.00312 | 1 |
+| CIFAR-10 | ResNet-18 | 0.950 | 0.00500 | 2 |
+| FashionMNIST | CNN | 0.950 | 0.01000 | 2 |
+| FashionMNIST | ResNet-18 | 0.957 | 0.00273 | 3 |
+
+---
+
+## Experiments
+
+Experiments use 30 epochs, cross-entropy loss, cosine annealing LR schedule, batch size 128, and AMP. ResNet-18 configurations include a 3-epoch linear warmup.
+
+```bash
+# CNN on CIFAR-10
+python train.py --dataset cifar10 --arch cnn --optimizer pilot
+
+# ResNet-18 on FashionMNIST
+python train.py --dataset fashionmnist --arch resnet18 --optimizer pilot
+```
+

pilot_optimizer-0.1.0/README.md

@@ -0,0 +1,154 @@
+# PILOT: Policy-Informed Learned Optimization for Adaptive Deep Network Training
+
+> **PILOT** is an online adaptive optimizer that adjusts its update behavior during training using gradient-direction agreement as a signal of local optimization stability.
+
+---
+
+## Overview
+
+Most optimizers use a fixed update structure throughout training — a static balance between momentum, normalization, and sign-based updates that cannot respond to how the loss landscape evolves.
+
+**PILOT** introduces a learnable policy that continuously modulates three core update primitives:
+- **Momentum reliance** — how much to rely on accumulated gradient history vs. the current gradient
+- **Variance-normalization strength** — how aggressively to apply adaptive scaling
+- **Sign-based behavior** — how much to compress gradient magnitudes toward ±1
+
+The policy is conditioned on a smoothed gradient-direction agreement signal, which serves as a compact online descriptor of local update consistency. It is updated online during training using a one-step meta-gradient estimate — no offline search, no meta-training phase, no second-order estimation.
+
+![Loss Landscape — CIFAR-10 / SmallCNN](fig2_landscape.png)
+*PILOT follows a distinct trajectory through the loss surface and converges to a lower-loss region compared to Adam, AdamW, Lion, and Sophia.*
+
+---
+
+## Key Results
+
+### CNN Architecture
+
+| Dataset | Optimizer | Accuracy (%) ↑ | Val Loss ↓ | Loss Var. ↓ |
+|---|---|---|---|---|
+| FashionMNIST | Adam | 93.28 | 0.1957 | **0.0033** |
+| FashionMNIST | AdamW | 93.22 | 0.1944 | 0.0034 |
+| FashionMNIST | Lion | 92.91 | 0.2091 | 0.0041 |
+| FashionMNIST | AdaBelief | 93.66 | 0.1822 | 0.0046 |
+| FashionMNIST | **PILOT (Ours)** | **94.13** | **0.1719** | 0.0045 |
+| CIFAR-10 | Adam | 79.91 | 0.5794 | 0.0103 |
+| CIFAR-10 | Lion | 80.87 | 0.5487 | 0.0105 |
+| CIFAR-10 | **PILOT (Ours)** | **81.94** | **0.5302** | **0.0073** |
+
+### ResNet-18 Architecture
+
+| Dataset | Optimizer | Accuracy (%) ↑ | Val Loss ↓ | Loss Var. ↓ |
+|---|---|---|---|---|
+| FashionMNIST | AdaBelief | 95.33 | 0.1711 | 0.0056 |
+| FashionMNIST | **PILOT (Ours)** | **95.71** | 0.2690 | 0.0030 |
+| CIFAR-10 | Adam | 93.18 | **0.2140** | 0.0073 |
+| CIFAR-10 | AdamW | 92.90 | 0.2514 | 0.0066 |
+| CIFAR-10 | **PILOT (Ours)** | **93.42** | 0.2496 | **0.0001** |
+
+---
+
+## Method
+
+### Gradient-Direction Agreement
+
+At each step, PILOT computes the cosine similarity between successive gradients:
+
+$$r_t = \frac{g_t^\top g_{t-1}}{\|g_t\|_2 \, \|g_{t-1}\|_2 + \epsilon}$$
+
+This is smoothed via an exponential moving average:
+
+$$\rho_t = \gamma \rho_{t-1} + (1 - \gamma) r_t$$
+
+Positive values indicate stable, aligned gradients. Values near zero indicate noise. Negative values indicate directional disagreement.
+
+### Learnable Policy
+
+The smoothed signal $\rho_t$ is fed through polynomial functions followed by sigmoid activations to produce three scalar control variables:
+
+$$p_{m,t} = \sigma(f(\rho_t; \phi_m)), \quad p_{v,t} = \tfrac{1}{2}\sigma(f(\rho_t; \phi_v)), \quad p_{s,t} = \sigma(f(\rho_t; \phi_s))$$
+
+The total number of learnable policy parameters is $3(d+1)$, where $d$ is the polynomial degree.
+
+### Update Rule
+
+$$\theta_{t+1} = \theta_t - \eta \frac{(|n_t| + \epsilon_n)^{1 - p_{s,t}} \odot \text{sign}(n_t)}{\hat{v}_t^{\,p_{v,t}} + \epsilon}$$
+
+where $n_t = p_{m,t} \hat{m}_t + (1 - p_{m,t}) g_t$ is the policy-controlled blend of momentum and current gradient.
+
+This formulation recovers Adam ($p_m=1, p_v=0.5, p_s=0$) and sign-based updates ($p_s=1, p_v=0$) as special cases.
+
+---
+
+## Installation
+
+```bash
+pip install pilot-optimizer
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/SattamAltwaim/PILOT.git
+cd PILOT
+pip install -e .
+```
+
+---
+
+## Usage
+
+```python
+from pilot import PILOT
+
+optimizer = PILOT(
+    model.parameters(),
+    lr=1e-3,
+    betas=(0.9, 0.999),
+    weight_decay=1e-4,
+    gamma=0.95,        # smoothing coefficient for agreement signal
+    lr_phi=0.01,       # policy learning rate
+    degree=2           # polynomial degree
+)
+
+for batch in dataloader:
+    loss = criterion(model(x), y)
+    optimizer.zero_grad()
+    loss.backward()
+    optimizer.step()
+```
+
+---
+
+## Hyperparameters
+
+| Parameter | Description | Typical Range |
+|---|---|---|
+| `lr` | Model learning rate | `1e-4` – `1e-3` |
+| `betas` | Moment coefficients | `(0.9, 0.999)` |
+| `gamma` | Agreement signal smoothing | `0.85` – `0.99` |
+| `lr_phi` | Policy learning rate | `5e-4` – `5e-2` |
+| `degree` | Polynomial degree | `1` – `4` |
+
+### Configuration-Specific Selections
+
+| Dataset | Architecture | γ | η_φ | Degree |
+|---|---|---|---|---|
+| CIFAR-10 | CNN | 0.882 | 0.00312 | 1 |
+| CIFAR-10 | ResNet-18 | 0.950 | 0.00500 | 2 |
+| FashionMNIST | CNN | 0.950 | 0.01000 | 2 |
+| FashionMNIST | ResNet-18 | 0.957 | 0.00273 | 3 |
+
+---
+
+## Experiments
+
+Experiments use 30 epochs, cross-entropy loss, cosine annealing LR schedule, batch size 128, and AMP. ResNet-18 configurations include a 3-epoch linear warmup.
+
+```bash
+# CNN on CIFAR-10
+python train.py --dataset cifar10 --arch cnn --optimizer pilot
+
+# ResNet-18 on FashionMNIST
+python train.py --dataset fashionmnist --arch resnet18 --optimizer pilot
+```
+

pilot_optimizer-0.1.0/pilot/__init__.py

@@ -0,0 +1,4 @@
+from .optimizer import PILOT
+
+__all__ = ["PILOT"]
+__version__ = "0.1.0"

pilot_optimizer-0.1.0/pilot/diagnostics.py

@@ -0,0 +1,54 @@
+"""
+Diagnostics tracker for the PILOT optimizer.
+
+Only records data when explicitly enabled. Zero overhead when disabled.
+"""
+
+
+class DiagnosticsTracker:
+    """Stores per-step optimizer internals for analysis."""
+
+    def __init__(self, *, degree: int = 2):
+        self._degree = degree
+        n_phi = 3 * (degree + 1)
+        self._phi_keys = [f"phi_{i}" for i in range(n_phi)]
+        self._history = {
+            "step": [],
+            "r": [],
+            "rho": [],
+            "p_m": [],
+            "p_v": [],
+            "p_s": [],
+        }
+        for key in self._phi_keys:
+            self._history[key] = []
+
+    def record(self, step, r, rho, pm, pv, ps, phi):
+        """Record diagnostics for one step."""
+        self._history["step"].append(step)
+        self._history["r"].append(float(r))
+        self._history["rho"].append(float(rho))
+        self._history["p_m"].append(float(pm))
+        self._history["p_v"].append(float(pv))
+        self._history["p_s"].append(float(ps))
+        phi_vals = phi.detach().cpu().tolist()
+        for i, key in enumerate(self._phi_keys):
+            self._history[key].append(phi_vals[i])
+
+    def get_history(self):
+        """Return full history as dict of lists."""
+        return dict(self._history)
+
+    def summary(self, last_n=5):
+        """Print a summary of the last N recorded steps."""
+        h = self._history
+        if not h["step"]:
+            return "No data recorded."
+        lines = [f"Last {min(last_n, len(h['step']))} steps:"]
+        for i in range(-last_n, 0):
+            idx = len(h["step"]) + i
+            lines.append(
+                f"  step={h['step'][idx]} r={h['r'][idx]:.4f} rho={h['rho'][idx]:.4f} "
+                f"pm={h['p_m'][idx]:.4f} pv={h['p_v'][idx]:.4f} ps={h['p_s'][idx]:.4f}"
+            )
+        return "\n".join(lines)

pilot_optimizer-0.1.0/pilot/meta_grads.py

@@ -0,0 +1,104 @@
+"""
+Analytic meta-gradient computation for the PILOT optimizer.
+
+Pure function that computes the 3*(degree+1) meta-gradients (dL/dphi_i)
+from stored detached intermediates. No autograd graph, no state.
+"""
+
+import torch
+
+
+def _safe_pow(base, exp_val):
+    """|base|^exp_val with clamping for numerical stability."""
+    return torch.clamp(base.abs(), min=1e-12).pow(exp_val)
+
+
+def _safe_log(x):
+    """log(|x|) with clamping for numerical stability."""
+    return torch.log(torch.clamp(x.abs(), min=1e-12))
+
+
+def _horner(coeffs: torch.Tensor, x: torch.Tensor) -> torch.Tensor:
+    """Evaluate a polynomial via Horner's method (highest power first)."""
+    out = coeffs[0]
+    for k in range(1, coeffs.shape[0]):
+        out = out * x + coeffs[k]
+    return out
+
+
+def compute_meta_grads(g_next, intermediates, g_t, phi, eta, *, degree=2):
+    """Compute the 3*(degree+1) meta-gradients dL/dphi_i for one param tensor.
+
+    The chain: phi -> (pm, pv, ps) -> d_t -> theta_{t+1} -> g_{t+1} -> L
+
+        dL/dphi_i = g_{t+1}^T * dd_t/dphi_i  (summed over all elements)
+
+    Args:
+        g_next: gradient at step t+1, shape matches param.
+        intermediates: dict with keys n_t, m_hat, v_hat, p_m, p_v, p_s, rho.
+        g_t: gradient at step t (stored separately as state["g_prev"]).
+        phi: current group-level phi vector, length 3*(degree+1).
+        eta: main optimizer learning rate.
+        degree: polynomial degree of the response policy.
+
+    Returns:
+        grads: tensor of shape (3*(degree+1),).
+    """
+    n_t = intermediates["n_t"]
+    m_hat = intermediates["m_hat"]
+    v_hat = intermediates["v_hat"]
+    pm = intermediates["p_m"]
+    pv = intermediates["p_v"]
+    ps = intermediates["p_s"]
+    rho = intermediates["rho"]
+
+    denom = _safe_pow(v_hat, pv) + 1e-8
+    n_abs_neg_ps = _safe_pow(n_t, -ps)
+    n_abs_1ps = _safe_pow(n_t, 1 - ps)
+    sign_n = torch.sign(n_t)
+
+    # dd_t / dp_m = -eta * (1 - ps) * |n|^(-ps) * (m_hat - g_t) / denom
+    dd_dpm = -eta * (1 - ps) * n_abs_neg_ps * (m_hat - g_t) / denom
+
+    # dd_t / dp_v = eta * |n|^(1-ps) * sign(n) * v^pv * log|v| / denom^2
+    dd_dpv = eta * n_abs_1ps * sign_n * _safe_pow(v_hat, pv) * _safe_log(v_hat) / (denom * denom)
+
+    # dd_t / dp_s = eta * |n|^(1-ps) * sign(n) * log|n| / denom
+    dd_dps = eta * n_abs_1ps * sign_n * _safe_log(n_t) / denom
+
+    # Scalar dL/dp for each policy variable
+    dL_dpm = torch.sum(g_next * dd_dpm)
+    dL_dpv = torch.sum(g_next * dd_dpv)
+    dL_dps = torch.sum(g_next * dd_dps)
+
+    # --- Chain rule through sigmoid and polynomial ---
+    n_phi = degree + 1
+    coeffs_m = phi[:n_phi]
+    coeffs_v = phi[n_phi : 2 * n_phi]
+    coeffs_s = phi[2 * n_phi :]
+
+    z_m = _horner(coeffs_m, rho)
+    z_v = _horner(coeffs_v, rho)
+    z_s = _horner(coeffs_s, rho)
+
+    s_m = torch.sigmoid(z_m)
+    s_v = torch.sigmoid(z_v)
+    s_s = torch.sigmoid(z_s)
+
+    ds_m = s_m * (1 - s_m)
+    ds_v = s_v * (1 - s_v)
+    ds_s = s_s * (1 - s_s)
+
+    # Build rho powers: [rho^d, rho^{d-1}, ..., rho^1, rho^0]
+    rho_powers = torch.empty(n_phi, device=phi.device)
+    rho_powers[n_phi - 1] = 1.0
+    for k in range(n_phi - 2, -1, -1):
+        rho_powers[k] = rho_powers[k + 1] * rho
+
+    # dL/d(coeffs_m[k]) = dL/dpm * ds_m * rho^(d-k)
+    grads_m = dL_dpm * ds_m * rho_powers
+    # pv = 0.5 * sigmoid(z_v), so dp_v/dz_v = 0.5 * sigmoid'(z_v)
+    grads_v = dL_dpv * 0.5 * ds_v * rho_powers
+    grads_s = dL_dps * ds_s * rho_powers
+
+    return torch.cat([grads_m, grads_v, grads_s])