pilot-optimizer 0.1.0__py3-none-any.whl

pilot/__init__.py

@@ -0,0 +1,4 @@
+from .optimizer import PILOT
+
+__all__ = ["PILOT"]
+__version__ = "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/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])

pilot/optimizer.py

@@ -0,0 +1,287 @@
+"""
+PILOT -- Policy-Informed Learned Optimization for Training.
+
+Adam with a learnable brain that reads the loss landscape and reshapes
+the update rule every step. The brain is trained by gradient descent using
+information the optimizer already computes.
+"""
+
+import torch
+from torch.optim import Optimizer
+
+from .diagnostics import DiagnosticsTracker
+from .meta_grads import compute_meta_grads
+
+
+# Degree-1 biases for the three policy sigmoids (slope=0, so flat at init).
+_PHI_BIAS = (1.4, 3.0, -2.0)
+
+META_GRAD_CLIP = 1.0  # safety cap on ||meta_grad_acc|| before phi update
+
+
+def _build_phi_init(degree: int) -> torch.Tensor:
+    """Build the initial phi vector for a given polynomial degree.
+
+    Layout: three consecutive blocks of (degree+1) coefficients, one per
+    policy variable (pm, pv, ps). Within each block the coefficients are
+    ordered highest-power-first: [coeff_d, ..., coeff_1, coeff_0].
+
+    Higher-order coefficients start at zero; the degree-1 (slope) coefficient
+    is zero; the degree-0 (bias) coefficient gets the Adam-like default.
+    This makes the initial behavior identical regardless of degree.
+    """
+    n = degree + 1
+    phi = torch.zeros(3 * n)
+    for i, bias in enumerate(_PHI_BIAS):
+        phi[i * n + n - 1] = bias  # constant term (last in block)
+    return phi
+
+
+def _horner(coeffs: torch.Tensor, x: torch.Tensor) -> torch.Tensor:
+    """Evaluate a polynomial using Horner's method.
+
+    coeffs: 1-D tensor [c_d, c_{d-1}, ..., c_1, c_0] (highest power first).
+    x: scalar tensor.
+    Returns: scalar tensor = c_d*x^d + ... + c_1*x + c_0.
+    """
+    out = coeffs[0]
+    for k in range(1, coeffs.shape[0]):
+        out = out * x + coeffs[k]
+    return out
+
+
+class PILOT(Optimizer):
+    r"""PILOT optimizer.
+
+    Args:
+        params: iterable of parameters to optimize.
+        lr: learning rate (default: 1e-3).
+        betas: coefficients for running averages of gradient and its square (default: (0.9, 0.999)).
+        eps: term for numerical stability (default: 1e-8).
+        weight_decay: weight decay coefficient (default: 0.01).
+        gamma: smoothing factor for the landscape signal (default: 0.95).
+        eta_phi: meta learning rate for the response policy (default: 0.01).
+        degree: polynomial degree for the response policy (default: 2).
+        diagnostics: if True, record internal state every step (default: False).
+        policy_overrides: optional dict to fix policy variables, e.g. {'pm': 1.0}.
+            Overridden variables bypass phi and their meta-gradient blocks are zeroed.
+    """
+
+    def __init__(
+        self,
+        params,
+        lr=1e-3,
+        betas=(0.9, 0.999),
+        eps=1e-8,
+        weight_decay=0.01,
+        gamma=0.95,
+        eta_phi=0.01,
+        degree=2,
+        diagnostics=False,
+        policy_overrides=None,
+    ):
+        if not 0.0 <= lr:
+            raise ValueError(f"Invalid learning rate: {lr}")
+        if not 0.0 <= betas[0] < 1.0:
+            raise ValueError(f"Invalid beta1: {betas[0]}")
+        if not 0.0 <= betas[1] < 1.0:
+            raise ValueError(f"Invalid beta2: {betas[1]}")
+        if not 0.0 <= eps:
+            raise ValueError(f"Invalid eps: {eps}")
+        if not 0.0 <= gamma < 1.0:
+            raise ValueError(f"Invalid gamma: {gamma}")
+        if not (isinstance(degree, int) and degree >= 1):
+            raise ValueError(f"Invalid degree: {degree} (must be int >= 1)")
+
+        defaults = dict(
+            lr=lr,
+            betas=betas,
+            eps=eps,
+            weight_decay=weight_decay,
+            gamma=gamma,
+            eta_phi=eta_phi,
+            degree=degree,
+        )
+        super().__init__(params, defaults)
+
+        self.diagnostics = (
+            DiagnosticsTracker(degree=degree) if diagnostics else None
+        )
+        self.policy_overrides = policy_overrides or {}
+
+        phi_init = _build_phi_init(degree)
+
+        # Initialize phi and rho per group. rho is a 0-dim tensor on the
+        # first param's device to avoid GPU->CPU syncs in the hot path.
+        for group in self.param_groups:
+            device = next(iter(group["params"])).device
+            group["rho"] = torch.zeros((), device=device)
+            group["phi"] = phi_init.clone().to(device=device)
+            group["step"] = 0
+
+    @torch.no_grad()
+    def step(self, closure=None):
+        """Performs a single optimization step."""
+        loss = None
+        if closure is not None:
+            with torch.enable_grad():
+                loss = closure()
+
+        for group in self.param_groups:
+            lr = group["lr"]
+            beta1, beta2 = group["betas"]
+            eps = group["eps"]
+            weight_decay = group["weight_decay"]
+            gamma = group["gamma"]
+            eta_phi = group["eta_phi"]
+
+            phi = group["phi"]
+            rho = group["rho"]
+            group["step"] += 1
+            step = group["step"]
+
+            bias_corr1 = 1 - beta1 ** step
+            bias_corr2 = 1 - beta2 ** step
+
+            # ---- Pass 1: single landscape signal from the full gradient ----
+            # Accumulate dot(g, g_prev), ||g||^2, ||g_prev||^2 across all params.
+            # Also handles lazy state init so pass 2 can rely on it.
+            dot = torch.zeros((), device=phi.device)
+            sq_g = torch.zeros((), device=phi.device)
+            sq_prev = torch.zeros((), device=phi.device)
+
+            for p in group["params"]:
+                if p.grad is None:
+                    continue
+                state = self.state[p]
+                if len(state) == 0:
+                    state["m"] = torch.zeros_like(p)
+                    state["v"] = torch.zeros_like(p)
+                    state["g_prev"] = torch.zeros_like(p)
+                    state["intermediates"] = None
+                g = p.grad
+                g_prev = state["g_prev"]
+                dot = dot + (g * g_prev).sum().to(phi.device)
+                sq_g = sq_g + g.pow(2).sum().to(phi.device)
+                sq_prev = sq_prev + g_prev.pow(2).sum().to(phi.device)
+
+            denom_cos = (sq_g * sq_prev).sqrt()
+            r = torch.where(
+                denom_cos > 1e-12,
+                dot / denom_cos.clamp(min=1e-12),
+                torch.zeros((), device=phi.device),
+            )
+            rho = gamma * rho + (1 - gamma) * r
+
+            # ---- Single response policy for the whole group ----
+            degree = group["degree"]
+            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)
+
+            pm = torch.sigmoid(z_m)
+            pv = 0.5 * torch.sigmoid(z_v)
+            ps = torch.sigmoid(z_s)
+
+            if self.policy_overrides:
+                if 'pm' in self.policy_overrides:
+                    pm = torch.tensor(self.policy_overrides['pm'], device=phi.device)
+                if 'pv' in self.policy_overrides:
+                    pv = torch.tensor(self.policy_overrides['pv'], device=phi.device)
+                if 'ps' in self.policy_overrides:
+                    ps = torch.tensor(self.policy_overrides['ps'], device=phi.device)
+
+            # ---- Pass 2: meta-gradient + Adam update for each param ----
+            meta_grad_acc = torch.zeros(3 * n_phi, device=phi.device)
+
+            for p in group["params"]:
+                if p.grad is None:
+                    continue
+
+                g = p.grad
+                state = self.state[p]
+                m = state["m"]
+                v = state["v"]
+                g_prev = state["g_prev"]  # still holds g_{t-1} until we copy below
+
+                # Meta-gradient from step t (intermediates) against g_{t+1} (current g).
+                intermediates = state.get("intermediates")
+                if intermediates is not None:
+                    mg = compute_meta_grads(
+                        g, intermediates, g_prev, phi, lr, degree=degree
+                    )
+                    meta_grad_acc += mg.to(phi.device)
+
+                # Adam bookkeeping
+                m.mul_(beta1).add_(g, alpha=1 - beta1)
+                v.mul_(beta2).addcmul_(g, g, value=1 - beta2)
+                m_hat = m / bias_corr1
+                v_hat = v / bias_corr2
+
+                # Move policy scalars to param device if needed (no-op on single device).
+                pm_p = pm.to(g.device) if pm.device != g.device else pm
+                pv_p = pv.to(g.device) if pv.device != g.device else pv
+                ps_p = ps.to(g.device) if ps.device != g.device else ps
+
+                # Adaptive step
+                n = pm_p * m_hat + (1 - pm_p) * g
+                n_abs = torch.clamp(n.abs(), min=1e-12)
+                denom = v_hat.pow(pv_p) + eps
+                d = -lr * n_abs.pow(1 - ps_p) * torch.sign(n) / denom
+
+                # Decoupled weight decay (AdamW-style)
+                if weight_decay != 0:
+                    d = d - lr * weight_decay * p.data
+
+                p.data.add_(d)
+
+                # Store intermediates for next step's meta-gradient.
+                rho_p = rho.to(g.device) if rho.device != g.device else rho
+                state["intermediates"] = {
+                    "n_t": n.detach(),
+                    "m_hat": m_hat.detach(),
+                    "v_hat": v_hat.detach(),
+                    "p_m": pm_p.detach(),
+                    "p_v": pv_p.detach(),
+                    "p_s": ps_p.detach(),
+                    "rho": rho_p.detach().clone(),
+                }
+
+                # Update g_prev to g_t for the next step.
+                g_prev.copy_(g)
+
+            # ---- Update phi with accumulated meta-gradients ----
+            if self.policy_overrides:
+                if 'pm' in self.policy_overrides:
+                    meta_grad_acc[:n_phi] = 0
+                if 'pv' in self.policy_overrides:
+                    meta_grad_acc[n_phi:2 * n_phi] = 0
+                if 'ps' in self.policy_overrides:
+                    meta_grad_acc[2 * n_phi:] = 0
+
+            # Clip by L2 norm to guard against log|n| blow-up in meta-gradients.
+            mg_norm = meta_grad_acc.norm()
+            scale = torch.clamp(META_GRAD_CLIP / (mg_norm + 1e-12), max=1.0)
+            phi.add_(meta_grad_acc * scale, alpha=-eta_phi)
+
+            # Persist updated rho (still a tensor, no sync).
+            group["rho"] = rho
+
+            # ---- Diagnostics ----
+            if self.diagnostics is not None:
+                self.diagnostics.record(
+                    step,
+                    float(r),
+                    float(rho),
+                    float(pm),
+                    float(pv),
+                    float(ps),
+                    phi,
+                )
+
+        return loss

pilot_optimizer-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+pilot/__init__.py,sha256=lkgpmUggaQ0t25jh5OWADfnhl5KpbX8CWXL-QWdUW_E,72
+pilot/diagnostics.py,sha256=A1_gRprfSpXEPGOkeVDHxsMLxl2qtHyun0HO2tgaDk8,1834
+pilot/meta_grads.py,sha256=lhIZjaggoDkeyukRNrhIT6WsY031M1zfGXplVry6kHk,3479
+pilot/optimizer.py,sha256=hcLeXtM3HRVQK3B1gMXJdp-MudSefTDICF_E72d3-b4,10820
+pilot_optimizer-0.1.0.dist-info/licenses/LICENSE,sha256=d50RzYxuMWIMIhnSEGoYkVNnbUCeae2WrpPoDQgFIYE,1071
+pilot_optimizer-0.1.0.dist-info/METADATA,sha256=J8XOcu6WF1_BeUs9PjyRekbnk8ixyKkmaNiRYJdJBAo,6535
+pilot_optimizer-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pilot_optimizer-0.1.0.dist-info/top_level.txt,sha256=BijnVJdXnIPxxx3s60M848seL4Z12gNUPod6KPJxK9c,6
+pilot_optimizer-0.1.0.dist-info/RECORD,,

pilot_optimizer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pilot_optimizer-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+pilot