superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/math/hopfield.py

@@ -1,282 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3
-
-"""Modern Continuous Hopfield Network (Ramsauer et al., 2020).
-
-Implementation of the continuous Hopfield energy and update rules
-from "Hopfield Networks is All You Need" (arXiv 2008.02217).
-
-This is the mathematical foundation for the 6th retrieval channel.
-The Hopfield update is equivalent to single-head self-attention:
-  xi_new = X' @ softmax(beta * X @ xi)
-
-Key properties:
-  - Energy function: E(xi) = -logsumexp(beta * X @ xi) + beta/2 * ||xi||^2
-  - Update rule: xi_new = X' @ softmax(beta * X @ xi)
-  - Beta: 1/sqrt(d) (inverse temperature)
-  - Storage capacity: O(exp(d/2)) -- exponential in dimension
-  - Convergence: 1 step for well-separated patterns
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: AGPL-3.0-or-later
-"""
-
-from __future__ import annotations
-
-import logging
-import math
-from dataclasses import dataclass
-from typing import Any
-
-import numpy as np
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Configuration (local definition; Delivery Lead moves to core/config.py)
-# ---------------------------------------------------------------------------
-
-@dataclass(frozen=True)
-class HopfieldConfig:
-    """Modern Continuous Hopfield Network configuration.
-
-    Based on Ramsauer et al. (2020): "Hopfield Networks is All You Need"
-    Energy: E(xi) = -log(sum_i exp(B * xi' * x_i)) + B/2 * ||xi||^2
-    Update: xi_new = X' @ softmax(B * X @ xi)
-    Beta:   B = 1/sqrt(d) where d = dimension
-
-    Storage capacity: O(e^{d/2}) -- exponential in dimension.
-    For d=768: theoretical capacity >> millions of patterns.
-    """
-
-    enabled: bool = True
-    dimension: int = 768
-    max_iterations: int = 1
-    convergence_epsilon: float = 1e-6
-    prefilter_threshold: int = 10_000
-    # MUST match HopfieldConfig.prefilter_candidates in core/config.py, where the
-    # reasoning for the value is written. This stage decides final membership, so
-    # this number is a hard limit on which memories can be returned at all.
-    prefilter_candidates: int = 500
-    skip_threshold: int = 100_000
-    cache_ttl_seconds: float = 60.0
-
-
-# ---------------------------------------------------------------------------
-# Hopfield State (immutable result)
-# ---------------------------------------------------------------------------
-
-@dataclass(frozen=True)
-class HopfieldState:
-    """Result of a single Hopfield retrieval step."""
-
-    retrieved_pattern: np.ndarray    # d-dimensional completed pattern
-    attention_weights: np.ndarray    # n-dimensional softmax weights
-    energy_before: float             # E(xi) before update
-    energy_after: float              # E(xi_new) after update
-    converged: bool                  # energy_after <= energy_before
-    iterations: int                  # Number of update steps taken
-
-
-# ---------------------------------------------------------------------------
-# Modern Continuous Hopfield Network
-# ---------------------------------------------------------------------------
-
-class ModernHopfieldNetwork:
-    """Modern Continuous Hopfield Network (Ramsauer et al., 2020).
-
-    Provides energy computation, single-step update, full retrieval
-    with convergence detection, and attention scoring.
-
-    Usage::
-
-        net = ModernHopfieldNetwork(HopfieldConfig(dimension=768))
-        state = net.retrieve(query_vec, memory_matrix)
-        scores = net.attention_scores(query_vec, memory_matrix)
-    """
-
-    def __init__(self, config: HopfieldConfig) -> None:
-        """Initialize with config. Computes beta = 1/sqrt(d).
-
-        HR-01: Beta MUST be 1/sqrt(d), no other values.
-        """
-        self._config = config
-        self._beta: float = 1.0 / math.sqrt(config.dimension)  # HR-01
-
-    # -- Public API ---------------------------------------------------------
-
-    def energy(self, xi: np.ndarray, memory_matrix: np.ndarray) -> float:
-        """Compute Modern Hopfield energy function.
-
-        E(xi) = -logsumexp(beta * X @ xi) + beta/2 * ||xi||^2
-
-        HR-04: Uses numerically stable logsumexp (shift by max).
-
-        Args:
-            xi: Query vector, shape (d,).
-            memory_matrix: Stored patterns, shape (n, d). L2-normalized rows.
-
-        Returns:
-            Energy value (float). Lower = better match to stored patterns.
-            Returns 0.0 for empty memory matrix.
-        """
-        # Guard: empty matrix
-        if memory_matrix.shape[0] == 0:
-            return 0.0
-
-        xi_64 = xi.astype(np.float64)  # HR-11: float64 for energy
-        mem_64 = memory_matrix.astype(np.float64)
-
-        # Compute logits: beta * X @ xi, shape (n,)
-        logits = self._beta * (mem_64 @ xi_64)
-
-        # HR-04: Numerically stable logsumexp
-        max_logit = float(np.max(logits))
-        lse = max_logit + float(np.log(np.sum(np.exp(logits - max_logit))))
-
-        # Energy: -lse + beta/2 * ||xi||^2
-        energy = -lse + (self._beta / 2.0) * float(np.dot(xi_64, xi_64))
-
-        # Guard against NaN (degenerate all-zero matrix)
-        if math.isnan(energy):
-            return 0.0
-
-        return energy
-
-    def update(self, xi: np.ndarray, memory_matrix: np.ndarray) -> np.ndarray:
-        """Single Hopfield update step.
-
-        xi_new = X' @ softmax(beta * X @ xi)
-
-        HR-02: Uses numerically stable softmax (shift by max).
-
-        Args:
-            xi: Query vector, shape (d,).
-            memory_matrix: Stored patterns, shape (n, d). L2-normalized rows.
-
-        Returns:
-            Updated vector xi_new, shape (d,). Returns zeros if matrix is empty.
-        """
-        d = self._config.dimension
-
-        # Guard: empty matrix
-        if memory_matrix.shape[0] == 0:
-            return np.zeros(d, dtype=np.float32)
-
-        # Compute logits: beta * X @ xi, shape (n,)
-        logits = self._beta * (memory_matrix @ xi)
-
-        # HR-02: Numerically stable softmax
-        attention = self._softmax(logits)
-
-        # Pattern completion: X' @ attention, shape (d,)
-        xi_new = memory_matrix.T @ attention
-
-        return xi_new.astype(np.float32)
-
-    def retrieve(
-        self,
-        query: np.ndarray,
-        memory_matrix: np.ndarray,
-        max_iterations: int = 0,
-    ) -> HopfieldState:
-        """Full retrieval with convergence detection and energy tracking.
-
-        Iteratively applies the Hopfield update rule until energy converges
-        or max_iterations is reached.
-
-        Args:
-            query: Query vector, shape (d,).
-            memory_matrix: Stored patterns, shape (n, d).
-            max_iterations: Override for config.max_iterations. 0 = use config.
-
-        Returns:
-            HopfieldState with retrieved pattern, attention, energy, convergence info.
-        """
-        d = self._config.dimension
-
-        # Guard: empty matrix
-        if memory_matrix.shape[0] == 0:
-            return HopfieldState(
-                retrieved_pattern=np.zeros(d, dtype=np.float32),
-                attention_weights=np.array([], dtype=np.float32),
-                energy_before=0.0,
-                energy_after=0.0,
-                converged=False,
-                iterations=0,
-            )
-
-        iters = max_iterations if max_iterations > 0 else self._config.max_iterations
-
-        # HR-11: float64 for energy computation precision
-        xi = query.copy().astype(np.float64)
-        mem_f32 = memory_matrix.astype(np.float32)  # HR-11: float32 for memory
-
-        energy_initial = self.energy(xi.astype(np.float32), mem_f32)
-        e_before = energy_initial
-        xi_new = xi.copy()
-
-        iteration = 0
-        for iteration in range(iters):
-            xi_new = self.update(xi.astype(np.float32), mem_f32).astype(np.float64)
-            e_after = self.energy(xi_new.astype(np.float32), mem_f32)
-
-            # Convergence check
-            if abs(e_after - e_before) < self._config.convergence_epsilon:
-                break
-
-            xi = xi_new
-            e_before = e_after
-
-        # Final energy
-        e_final = self.energy(xi_new.astype(np.float32), mem_f32)
-
-        # Final attention weights
-        attention = self._softmax(
-            self._beta * (mem_f32 @ xi_new.astype(np.float32)),
-        )
-
-        return HopfieldState(
-            retrieved_pattern=xi_new.astype(np.float32),
-            attention_weights=attention.astype(np.float32),
-            energy_before=energy_initial,
-            energy_after=e_final,
-            converged=(e_final <= energy_initial + 1e-9),
-            iterations=iteration + 1,
-        )
-
-    def attention_scores(
-        self,
-        query: np.ndarray,
-        memory_matrix: np.ndarray,
-    ) -> np.ndarray:
-        """Compute Hopfield attention weights WITHOUT full update.
-
-        Used for scoring/ranking without pattern completion.
-
-        Args:
-            query: Query vector, shape (d,).
-            memory_matrix: Stored patterns, shape (n, d).
-
-        Returns:
-            Attention weights, shape (n,), summing to 1.0.
-        """
-        if memory_matrix.shape[0] == 0:
-            return np.array([], dtype=np.float32)
-
-        logits = self._beta * (memory_matrix @ query)
-        return self._softmax(logits)
-
-    # -- Private helpers ----------------------------------------------------
-
-    def _softmax(self, logits: np.ndarray) -> np.ndarray:
-        """Numerically stable softmax.
-
-        HR-02: Shift by max to prevent overflow.
-        softmax(x) = exp(x - max(x)) / sum(exp(x - max(x)))
-        """
-        shifted = logits - np.max(logits)  # HR-02
-        exp_vals = np.exp(shifted)
-        return exp_vals / np.sum(exp_vals)

package/src/superlocalmemory/math/langevin.py

@@ -1,411 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Riemannian Langevin dynamics with persistence for memory lifecycle.
-
-Evolves memory positions via a discretised Langevin SDE driven by an
-access-aware potential function.  Frequently accessed memories are
-confined near the origin (ACTIVE, high retrieval weight) by a strong
-potential, while neglected memories diffuse toward the boundary
-(ARCHIVED, weight approaches 0) as their confinement weakens.
-
-Core SDE (Girolami & Calderhead 2011):
-
-    xi_{t+1} = xi_t - g^{-1}(xi_t) * grad U(xi_t) * dt
-             + sqrt(2 * T * dt) * g^{-1/2}(xi_t) * eta
-
-Potential function:
-
-    U(xi) = alpha * ||xi||^2
-           - beta  * log(access_count + 1)
-           + gamma * age_days
-           - delta * importance
-
-    - Accessed memories:  beta term lowers potential  -> drift to origin
-    - Old / unused:       gamma term raises potential -> drift to boundary
-    - Important memories: delta term lowers potential -> retain near origin
-
-V1 bugs fixed in v3.5:
-    1. Positions were computed per-recall then DISCARDED.  Now ``step()``
-       and ``batch_step()`` return new positions for the caller to persist.
-    2. Weight range was [0.7, 1.0] --- too narrow to change rankings.
-       Now [0.0, 1.0] so archived memories can be effectively suppressed.
-
-References:
-    Girolami M & Calderhead B (2011). Riemann manifold Langevin and
-        Hamiltonian Monte Carlo methods. JRSS-B, 73(2), 123--214.
-    Roberts G O & Tweedie R L (1996). Exponential convergence of Langevin
-        distributions. Bernoulli, 2(4), 341--363.
-    Xifara T, Sherlock C, Livingstone S, Byrne S & Girolami M (2014).
-        Langevin diffusions and the MALA algorithm. Statistics &
-        Probability Letters, 91, 59--67.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: AGPL-3.0-or-later
-"""
-
-from __future__ import annotations
-
-import math
-from typing import Any
-
-import numpy as np
-
-from superlocalmemory.storage.models import MemoryLifecycle
-
-# ---------------------------------------------------------------------------
-# Lifecycle zone boundaries (radius thresholds on the unit ball)
-# ---------------------------------------------------------------------------
-
-_RADIUS_ACTIVE: float = 0.3    # [0, 0.3)    -> ACTIVE
-_RADIUS_WARM: float = 0.55     # [0.3, 0.55) -> WARM
-_RADIUS_COLD: float = 0.8      # [0.55, 0.8) -> COLD
-                                # [0.8, 1.0)  -> ARCHIVED
-
-# Potential coefficients (defaults)
-# Alpha must be > 0.5*T*(d-2)/lam_inv ≈ 1.8 at T=0.3 for confinement
-# to counter the Riemannian curvature correction near the origin.
-_ALPHA: float = 3.0   # Base confinement (strong enough to counter correction)
-_BETA: float = 0.8    # Access STRENGTHENS confinement (keeps active facts near origin)
-_GAMMA: float = 0.005 # Age WEAKENS confinement (old facts drift to boundary)
-_DELTA: float = 0.5   # Importance STRENGTHENS confinement
-
-# Safety
-_MAX_NORM: float = 0.99   # Clamp radius < 1 (open ball)
-_EPS: float = 1e-8
-
-
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-class LangevinDynamics:
-    """Riemannian Langevin dynamics with persistence for memory lifecycle.
-
-    Positions live on the open unit ball B^d.  The potential function
-    encodes access frequency, age, and importance as competing forces.
-    The lifecycle state (ACTIVE / WARM / COLD / ARCHIVED) is determined
-    purely by radial position.
-
-    Attributes:
-        dt:           Time-step size for Euler-Maruyama integration.
-        temperature:  Boltzmann temperature controlling diffusion spread.
-        weight_range: (min_weight, max_weight) for lifecycle weighting.
-        dim:          Dimensionality of the position space.
-    """
-
-    __slots__ = (
-        "dt", "temperature", "weight_range", "dim",
-        "_alpha", "_beta", "_gamma", "_delta",
-    )
-
-    def __init__(
-        self,
-        dt: float = 0.01,
-        temperature: float = 1.0,
-        weight_range: tuple[float, float] = (0.0, 1.0),
-        dim: int = 8,
-    ) -> None:
-        if dt <= 0:
-            raise ValueError(f"dt must be positive, got {dt}")
-        if temperature <= 0:
-            raise ValueError(f"temperature must be positive, got {temperature}")
-        if weight_range[0] > weight_range[1]:
-            raise ValueError(
-                f"weight_range min > max: {weight_range[0]} > {weight_range[1]}"
-            )
-
-        self.dt = dt
-        self.temperature = temperature
-        self.weight_range = weight_range
-        self.dim = dim
-
-        # Potential coefficients
-        self._alpha = _ALPHA
-        self._beta = _BETA
-        self._gamma = _GAMMA
-        self._delta = _DELTA
-
-    # ------------------------------------------------------------------
-    # Single-fact step
-    # ------------------------------------------------------------------
-
-    def step(
-        self,
-        position: list[float],
-        access_count: int,
-        age_days: float,
-        importance: float,
-        seed: int | None = None,
-    ) -> tuple[list[float], float]:
-        """One Euler-Maruyama step of the Langevin SDE.
-
-        Computes the gradient of the potential at the current position,
-        applies drift + stochastic diffusion, and returns the new position
-        plus the resulting lifecycle weight.
-
-        The caller is responsible for PERSISTING the returned position
-        back to the database.  This is the key V1 fix: positions must
-        evolve across recalls, not be recomputed from scratch each time.
-
-        Args:
-            position:     Current position on the unit ball, length ``dim``.
-            access_count: Total number of times this fact has been accessed.
-            age_days:     Days since the fact was first stored.
-            importance:   Fact importance score in [0, 1].
-            seed:         Optional RNG seed for reproducible diffusion.
-
-        Returns:
-            (new_position, lifecycle_weight) where new_position is a list
-            of floats inside the unit ball and lifecycle_weight is in
-            [weight_range[0], weight_range[1]].
-        """
-        xi = np.asarray(position, dtype=np.float64)
-        if xi.shape[0] != self.dim:
-            # Graceful resize: pad or truncate
-            xi = _resize_position(xi, self.dim)
-
-        # --- Gradient of potential ---
-        grad = self._potential_gradient(xi, access_count, age_days, importance)
-
-        # --- Conformal factor on Poincare ball: lambda = 2 / (1 - ||x||^2) ---
-        norm_sq = float(np.dot(xi, xi))
-        norm_sq = min(norm_sq, _MAX_NORM ** 2)
-        lam = 2.0 / (1.0 - norm_sq + _EPS)
-        lam_inv = 1.0 / lam
-
-        # --- Drift: -lambda^{-2} * grad_U * dt (Eq. 5 term 1) ---
-        drift = -(lam_inv ** 2) * grad * self.dt
-
-        # --- V3.3.12: Ebbinghaus forgetting drift (Eq. 6 in Paper 3) ---
-        # λ(m) = 1/S(m) pushes toward boundary (forgetting) based on memory strength.
-        # S(m) is computed from access_count + importance. Higher S → less drift.
-        strength = max(0.5, 0.3 * math.log(1.0 + access_count) + 0.4 * importance)
-        forget_rate = 1.0 / strength  # λ(m)
-        # F(ξ) = ξ/||ξ|| points outward (toward boundary = archived zone)
-        xi_norm = float(np.linalg.norm(xi))
-        if xi_norm > _EPS:
-            forget_direction = xi / xi_norm
-        else:
-            forget_direction = np.zeros(self.dim)
-        forgetting_drift = forget_rate * forget_direction * self.dt * 0.1  # Scaled down to prevent instability
-
-        # --- Curvature correction: 0.5 * T * (d-2) * lambda^{-1} * xi * dt (Eq. 5 term 3) ---
-        correction = 0.5 * self.temperature * (self.dim - 2) * lam_inv * xi * self.dt
-
-        # --- Diffusion: sqrt(2T * dt) * lambda^{-1} * noise (Eq. 5 term 2) ---
-        rng = np.random.default_rng(seed)
-        noise = rng.standard_normal(self.dim)
-        diffusion = math.sqrt(2.0 * self.temperature * self.dt) * lam_inv * noise
-
-        # --- Full Euler-Maruyama update with forgetting (Eq. 6, Girolami & Calderhead 2011) ---
-        new_xi = xi + drift + forgetting_drift + correction + diffusion
-
-        # --- Project back into the open ball ---
-        new_xi = _project_to_ball(new_xi)
-
-        weight = self.compute_lifecycle_weight(new_xi.tolist())
-        return new_xi.tolist(), weight
-
-    # ------------------------------------------------------------------
-    # Lifecycle weight from position
-    # ------------------------------------------------------------------
-
-    def compute_lifecycle_weight(self, position: list[float]) -> float:
-        """Compute retrieval weight from radial position.
-
-        Weight decreases linearly from max to min as radius moves from
-        origin to boundary.  This ensures archived memories (near boundary)
-        are strongly suppressed in retrieval rankings.
-
-        Args:
-            position: Current position, length ``dim``.
-
-        Returns:
-            Weight in [weight_range[0], weight_range[1]].
-        """
-        xi = np.asarray(position, dtype=np.float64)
-        radius = float(np.linalg.norm(xi))
-        radius = min(radius, _MAX_NORM)
-
-        # Linear interpolation: radius 0 -> max weight, radius 1 -> min weight
-        lo, hi = self.weight_range
-        weight = hi - (hi - lo) * (radius / _MAX_NORM)
-        return max(lo, min(hi, weight))
-
-    # ------------------------------------------------------------------
-    # Lifecycle state classification
-    # ------------------------------------------------------------------
-
-    def get_lifecycle_state(self, weight: float) -> MemoryLifecycle:
-        """Classify lifecycle state from weight.
-
-        Uses the weight (derived from radius) rather than raw radius,
-        so the caller doesn't need to know zone boundaries.
-
-        Args:
-            weight: Lifecycle weight in [0, 1].
-
-        Returns:
-            MemoryLifecycle enum value.
-        """
-        # Map weight back to approximate radius for zone classification
-        lo, hi = self.weight_range
-        span = hi - lo
-        if span < _EPS:
-            return MemoryLifecycle.ACTIVE
-
-        # radius_approx: weight=hi -> radius=0, weight=lo -> radius=MAX_NORM
-        radius_approx = (hi - weight) / span * _MAX_NORM
-
-        if radius_approx < _RADIUS_ACTIVE:
-            return MemoryLifecycle.ACTIVE
-        if radius_approx < _RADIUS_WARM:
-            return MemoryLifecycle.WARM
-        if radius_approx < _RADIUS_COLD:
-            return MemoryLifecycle.COLD
-        return MemoryLifecycle.ARCHIVED
-
-    # ------------------------------------------------------------------
-    # Batch step (background maintenance)
-    # ------------------------------------------------------------------
-
-    def batch_step(
-        self,
-        facts: list[dict[str, Any]],
-        seed: int | None = None,
-    ) -> list[dict[str, Any]]:
-        """Batch Langevin step for background maintenance.
-
-        Evolves all fact positions in a single pass.  Designed to be
-        called periodically (e.g. every N hours) to let the memory store
-        self-organise over time.
-
-        Each input dict must contain:
-            - ``fact_id``:      str
-            - ``position``:     list[float]
-            - ``access_count``: int
-            - ``age_days``:     float
-            - ``importance``:   float
-
-        Args:
-            facts: List of fact dicts with position and metadata.
-            seed:  Optional base seed (incremented per fact for variety).
-
-        Returns:
-            List of dicts with ``fact_id``, ``position`` (updated),
-            ``weight``, and ``lifecycle`` fields.
-        """
-        results: list[dict[str, Any]] = []
-        base_seed = seed
-
-        for i, fact in enumerate(facts):
-            fact_seed = (base_seed + i) if base_seed is not None else None
-
-            new_pos, weight = self.step(
-                position=fact["position"],
-                access_count=fact["access_count"],
-                age_days=fact["age_days"],
-                importance=fact["importance"],
-                seed=fact_seed,
-            )
-
-            results.append({
-                "fact_id": fact["fact_id"],
-                "position": new_pos,
-                "weight": weight,
-                "lifecycle": self.get_lifecycle_state(weight).value,
-            })
-
-        return results
-
-    # ------------------------------------------------------------------
-    # Potential gradient (private)
-    # ------------------------------------------------------------------
-
-    def _potential_gradient(
-        self,
-        xi: np.ndarray,
-        access_count: int,
-        age_days: float,
-        importance: float,
-    ) -> np.ndarray:
-        """Metadata-modulated confinement gradient .
-
-        Potential:
-            U(xi) = effective_alpha * ||xi||^2
-
-        Where effective_alpha is modulated by metadata:
-            effective_alpha = alpha
-                + beta * log(access+1)/10   (frequent access → stronger confinement → ACTIVE)
-                - gamma * min(age, 365)/365  (aging → weaker confinement → drifts to ARCHIVED)
-                + delta * importance          (important → stronger confinement → stays ACTIVE)
-
-        Gradient:
-            grad U = 2 * effective_alpha * xi
-
-        This ensures metadata drives correct lifecycle dynamics:
-        - Frequently accessed facts stay near origin (ACTIVE, high weight)
-        - Old unused facts drift toward boundary (ARCHIVED, low weight)
-        - Important facts resist archival (persistent)
-
-        Args:
-            xi:           Position array.
-            access_count: Total access count.
-            age_days:     Days since creation.
-            importance:   Importance score [0, 1].
-
-        Returns:
-            Gradient vector, same shape as xi.
-        """
-        import math as _math
-        effective_alpha = (
-            self._alpha
-            + self._beta * _math.log(access_count + 1) / 10.0
-            - self._gamma * min(age_days, 365.0) / 365.0
-            + self._delta * importance
-        )
-        effective_alpha = max(0.1, effective_alpha)
-        return 2.0 * effective_alpha * xi
-
-
-# ---------------------------------------------------------------------------
-# Helpers (module-private)
-# ---------------------------------------------------------------------------
-
-def _project_to_ball(xi: np.ndarray) -> np.ndarray:
-    """Project point back into the open unit ball.
-
-    If ||xi|| >= MAX_NORM, rescale to sit at MAX_NORM.
-
-    Args:
-        xi: Position array.
-
-    Returns:
-        Projected position with ||result|| < 1.
-    """
-    norm = float(np.linalg.norm(xi))
-    if norm >= _MAX_NORM:
-        return xi * (_MAX_NORM / (norm + _EPS))
-    return xi
-
-
-def _resize_position(xi: np.ndarray, target_dim: int) -> np.ndarray:
-    """Resize a position vector to target dimensionality.
-
-    Pads with zeros or truncates as needed.
-
-    Args:
-        xi:         Source position.
-        target_dim: Desired dimensionality.
-
-    Returns:
-        Resized position array.
-    """
-    current = xi.shape[0]
-    if current == target_dim:
-        return xi
-    if current < target_dim:
-        return np.pad(xi, (0, target_dim - current), constant_values=0.0)
-    return xi[:target_dim]