openscvx 0.5.3.dev25__tar.gz → 0.5.3.dev26__tar.gz

{openscvx-0.5.3.dev25/openscvx.egg-info → openscvx-0.5.3.dev26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.5.3.dev25
+Version: 0.5.3.dev26
 Summary: A general Python-based successive convexification implementation which uses a JAX backend.
 Author-email: Chris Hayner and Griffin Norris <haynec@uw.edu>
 License: Apache Software License

openscvx-0.5.3.dev26/docs/UnderTheHood/custom_algorithms_autotuners.md

@@ -0,0 +1,223 @@
+# Custom Algorithms and Autotuners
+
+OpenSCvx solves through a pluggable SCP loop: an **algorithm** owns the
+iteration (how a subproblem is built, when the loop is converged) and an
+**autotuner** owns the penalty-weight update applied each step. Both are
+ordinary Python classes behind small abstract bases — `Algorithm` and
+`AutotuningBase`, importable from `openscvx.algorithms` — so swapping either
+out is a subclass, not a fork.
+
+Most users never touch these: the default
+`PenalizedTrustRegion` + `AugmentedLagrangian` pair covers the common case.
+Reach for this page when you want a different penalty schedule, a different
+convergence rule, or a whole new SCP variant — and you want it to keep
+working under `solve()`, `solve_jax()`, and `solve_batched()` alike.
+
+Both bases live under `openscvx.algorithms`:
+
+```python
+from openscvx.algorithms import Algorithm, AutotuningBase, HyperParams
+```
+
+## A custom autotuner
+
+An autotuner is a **pure functional update on the iterate**. Its one required
+method, `update_weights`, takes the current `AlgorithmState`, the just-solved
+subproblem `candidate`, the constraints, settings, and parameters, and returns
+the *next* `AlgorithmState`:
+
+```python
+import jax.numpy as jnp
+from openscvx.algorithms import AdaptiveStateCode, AutotuningBase, HyperParams
+
+
+class MyHyper(HyperParams):
+    ramp: float = 2.0
+
+
+class MyAutotuner(AutotuningBase):
+    COMPUTES_ACCEPTANCE_METRICS = False  # this tuner never rejects an iterate
+
+    def __init__(self, ramp: float = 2.0):
+        self.hyper = MyHyper(ramp=ramp)  # assign self.hyper FIRST
+
+    def update_weights(self, state, candidate, nodal_constraints, settings, params):
+        return state.replace(
+            # accept the candidate: its trajectory becomes the next iterate
+            x=candidate.x,
+            u=candidate.u,
+            x_prop=candidate.x_prop,
+            x_prop_plus=candidate.x_prop_plus,
+            # ramp the proximal weight every iteration
+            lam_prox=state.lam_prox * state.hyper.ramp,
+            # jnp.int32, not bare asarray: the code must keep the state field's
+            # strong int32 dtype or the lax.while_loop carry check fails.
+            adaptive_state_code=jnp.int32(AdaptiveStateCode.ACCEPT_HIGHER),
+        )
+```
+
+Three rules carry the whole contract.
+
+### The returned state *is* the next iterate
+
+The SCP loop discards everything except what `update_weights` returns.
+Accepting the subproblem's candidate therefore means **carrying its
+trajectory onto the returned state** — `x` / `u` / `x_prop` / `x_prop_plus`
+from `candidate` — while rejecting means keeping the previous fields and
+adjusting only the weights.
+
+!!! warning "The silent no-op"
+    An update that never copies the candidate produces a solver that runs to
+    `k_max` without the iterate ever moving — no error, just a flat history.
+    If a custom tuner seems to "not converge," check that the accept branch
+    copies all four trajectory fields.
+
+Express any accept/reject branching with `jax.lax.cond` or `jnp.where`, not a
+Python `if` on iterate values: `update_weights` is traced (it runs inside the
+`lax.while_loop` of `solve_jax` / `solve_batched`, vmapped per batch element),
+so it must not mutate `state` or `candidate`, raise on data-dependent
+conditions, or return strings.
+
+### Declare tunable knobs as `HyperParams`, not `self` attributes
+
+A numeric knob a user might sweep (a ramp factor, a relaxation iteration) must
+**not** be read off `self` inside `update_weights` — a plain Python attribute
+is baked into the trace and invisible to every override channel. Declare it on
+a `HyperParams` subclass, assign an instance to `self.hyper`, and read it from
+`state.hyper`.
+
+The declaration *is* the registration. With nothing else, the field becomes:
+
+* a **per-solve override** — `problem.solve_jax(algorithm={"ramp": 1.5})`;
+* a **batchable sweep target** —
+  `problem.solve_batched(algorithm={"ramp": jnp.linspace(1.1, 2.0, 8)})`;
+* a **runtime input** of the exported `solve_batched` artifact, so changing it
+  needs no recompile.
+
+!!! danger "Assign `self.hyper` first"
+    Declared knobs are also readable and writable as bare attributes
+    (`autotuner.ramp = 3.0`) for ergonomics — a proxy on `AutotuningBase`
+    routes the access into `hyper`. That proxy only works once `self.hyper`
+    exists, so assign it as the **first** line of `__init__`. A knob assigned
+    before `hyper` exists lands as a plain instance attribute the proxy cannot
+    see, and your override channels silently break.
+
+### Acceptance metrics are opt-in
+
+`COMPUTES_ACCEPTANCE_METRICS` (default `True`) tells the loop whether
+`update_weights` produces a predicted/actual reduction and an acceptance
+ratio. The loop records and prints those diagnostics only when it is `True`.
+A tuner that never rejects an iterate — like the built-in
+`ConstantProximalWeight` and `RampProximalWeight` — sets it `False`.
+
+To add columns to the iteration table, set the class attribute `COLUMNS` to a
+list of `openscvx.utils.printing.Column` specs; the algorithm concatenates
+them into its own table via `get_columns`.
+
+## A custom algorithm
+
+An `Algorithm` owns the SCP iteration end to end: it *builds* the JAX-pure
+iteration body, *stores* it, and *drives* it one step at a time. All iteration
+state lives on `AlgorithmState` (JAX-traceable) and `AlgorithmHistory`
+(Python-side) threaded explicitly through `step()` — avoid storing mutable
+iteration state on `self`.
+
+The surface is six methods. `converged` has a working default; the other five
+are abstract.
+
+### `__init__` — end with `super().__init__`
+
+The base records the weights, autotuner, and convergence parameters. Every
+parameter is required, so the ABC is not yet another place defaults are
+declared — your subclass owns the user-facing defaults and forwards them:
+
+```python
+from openscvx.algorithms import Algorithm
+from openscvx.algorithms.weights import Weights
+from openscvx.algorithms import AugmentedLagrangian
+
+
+class MyAlgorithm(Algorithm):
+    def __init__(self, autotuner=None, k_max=200, **weight_kwargs):
+        super().__init__(
+            weights=Weights.build(**weight_kwargs),
+            autotuner=autotuner if autotuner is not None else AugmentedLagrangian(),
+            k_max=k_max,
+            t_max=None,
+            ep_tr=1e-4,
+            ep_vb=1e-4,
+            ep_vc=1e-8,
+        )
+```
+
+### `build_iteration` — fuse the step
+
+`Problem` assembles the discretization solvers, lowered constraints, and
+convex-solver callback, then asks the algorithm to fuse them into one JAX-pure
+`(state, params) -> (next_state, diagnostics)` body. The algorithm owns this
+because the fusion is algorithm-specific (which autotuner runs, which penalty
+terms are assembled). PTR's implementation is a thin wrapper around
+`make_scp_iteration` (`openscvx/algorithms/scvx/iteration.py`) that threads its
+`autotuner` into the fused body. The returned body must advance `state.k` by
+one per call — every solve path terminates on `k` reaching `k_max`.
+
+### `initialize` and `step` — store, then drive
+
+`Problem.initialize()` builds and JIT-warms the body, then hands it back via
+`initialize(iteration_fn, emitter)` for the algorithm to store. `step()` is the
+Python-loop driver: it calls the stored body, records the per-iteration
+diagnostics into `history`, emits progress, and returns
+`(next_state, converged)`.
+
+### `converged` — the one-method convergence hook
+
+`converged(state)` is the only piece of convergence policy that is
+algorithm-specific; it has a concrete default, so override it only to change
+the rule:
+
+```python
+def converged(self, state):
+    return state.J_vc < state.ep_vc   # custom: virtual control alone
+```
+
+The default — every metric below its threshold — is algorithm-agnostic, since
+`AlgorithmState` carries `J_tr` / `J_vb` / `J_vc` and the `ep_*` tolerances
+generically.
+
+!!! note "Honored on every solve path"
+    The override is honored on **all three** solve paths. `step()` routes
+    through it on the Python `solve()` path, and the `lax.while_loop` harness
+    (`openscvx/algorithms/loop.py`) takes it as the loop predicate for
+    `solve_jax` / `solve_batched`, where it is vmapped per batch element. It
+    must therefore be JAX-traceable. An override implies a subclass, hence a
+    distinct class name that the export cache key already folds in — so a
+    changed predicate invalidates stale batched artifacts on its own.
+
+By contrast, `t_max` (the wall-clock time limit) is honored **only** on the
+Python `solve()` path; the JAX loop terminates on `k_max` and `converged`
+alone, since there is no wall-clock probe inside a trace.
+
+### `get_columns` and `citation`
+
+`get_columns(verbosity)` returns the iteration-table columns to print —
+implementations typically concatenate the algorithm's own columns with the
+autotuner's `COLUMNS` and filter by each column's `min_verbosity`.
+`citation()` returns a list of BibTeX strings for the algorithm.
+
+## Using a custom class
+
+Pass either to the `Problem` constructor — the algorithm directly, an
+autotuner through the algorithm:
+
+```python
+import openscvx as ox
+
+problem = ox.Problem(
+    ...,
+    algorithm=MyAlgorithm(autotuner=MyAutotuner(ramp=1.5)),
+)
+```
+
+The default `PenalizedTrustRegion` lives at
+`openscvx/algorithms/scvx/penalized_trust_region.py` and is the reference
+implementation to read alongside this guide.

{openscvx-0.5.3.dev25 → openscvx-0.5.3.dev26}/mkdocs.yml

@@ -198,4 +198,5 @@ nav:
     - Under the Hood:
       - 'UnderTheHood/vectorization_and_vmapping.md'
       - 'UnderTheHood/lowering_architecture.md'
-      - 'UnderTheHood/batching_jit_grad.md'
+      - 'UnderTheHood/batching_jit_grad.md'
+      - 'UnderTheHood/custom_algorithms_autotuners.md'

{openscvx-0.5.3.dev25 → openscvx-0.5.3.dev26}/openscvx/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.3.dev25'
-__version_tuple__ = version_tuple = (0, 5, 3, 'dev25')
+__version__ = version = '0.5.3.dev26'
+__version_tuple__ = version_tuple = (0, 5, 3, 'dev26')
 
-__commit_id__ = commit_id = 'ge4b992a50'
+__commit_id__ = commit_id = 'g053a32537'

{openscvx-0.5.3.dev25 → openscvx-0.5.3.dev26}/openscvx/algorithms/__init__.py

@@ -5,9 +5,11 @@ for solving non-convex trajectory optimization problems through iterative convex
 approximation.
 
 All algorithms inherit from :class:`Algorithm`, enabling pluggable algorithm
-implementations and custom SCvx variants. Immutable components (solver,
-discretization_solver, jax_constraints, etc.) are stored during ``initialize()``;
-mutable configuration (params, settings) is passed per-step.
+implementations and custom SCvx variants. An algorithm builds its fused,
+JAX-pure iteration body (``build_iteration``), stores it along with the
+diagnostics emitter (``initialize``), drives it one step at a time on the
+Python path (``step``), and owns its convergence policy (``converged``) —
+honored identically by ``solve()``, ``solve_jax()``, and ``solve_batched()``.
 
 The iterate carry is split into two objects:
 
@@ -48,19 +50,18 @@ from .autotuner import (
     RampProximalWeight,
     RampProximalWeightSpec,
 )
-from .base import (
+from .autotuner.base import AutotuningBase
+from .base import Algorithm
+from .history import AlgorithmHistory, DiscretizationResult
+from .hyperparams import HyperParams
+from .optimization_results import OptimizationResults
+from .scvx import PenalizedTrustRegion
+from .state import (
     AdaptiveStateCode,
-    Algorithm,
-    AlgorithmHistory,
     AlgorithmState,
-    AutotuningBase,
     CandidateIterate,
-    DiscretizationResult,
-    HyperParams,
     adaptive_state_code_to_str,
 )
-from .optimization_results import OptimizationResults
-from .scvx import PenalizedTrustRegion
 from .weights import Weights
 
 # ---------------------------------------------------------------------------

{openscvx-0.5.3.dev25 → openscvx-0.5.3.dev26}/openscvx/algorithms/autotuner/acceptance_ratio.py

@@ -29,20 +29,21 @@ from openscvx.utils.printing import (
     color_adaptive_state,
 )
 
-from ..base import AdaptiveStateCode, AutotuningBase, HyperParams
+from ..penalty import calculate_nonlinear_penalty
+from ..state import AdaptiveStateCode
+from .base import AutotuningBase, LamCostRelaxHyper
 
 if TYPE_CHECKING:
     from openscvx.lowered import LoweredJaxConstraints
 
-    from ..base import AlgorithmState, CandidateIterate
+    from ..state import AlgorithmState, CandidateIterate
 
 
-class AcceptanceRatioHyper(HyperParams):
+class AcceptanceRatioHyper(LamCostRelaxHyper):
     """Knobs shared by every acceptance-ratio autotuner.
 
-    ``lam_cost_drop`` is the iteration after which ``lam_cost`` relaxation
-    applies (``state.k > lam_cost_drop``): ``-1`` relaxes from the first
-    iteration, and the default ``lam_cost_relax=1.0`` makes that a no-op.
+    Extends the shared :class:`LamCostRelaxHyper` ``lam_cost`` relaxation knobs
+    with the acceptance-ratio decision thresholds and the ``lam_prox`` clips.
     """
 
     gamma_1: float = 2.0
@@ -52,8 +53,6 @@ class AcceptanceRatioHyper(HyperParams):
     eta_2: float = 0.8
     lam_prox_min: float = 1e-3
     lam_prox_max: float = 1e4
-    lam_cost_drop: int = -1
-    lam_cost_relax: float = 1.0
 
 
 class AcceptanceRatioAutotuner(AutotuningBase):
@@ -121,7 +120,7 @@ class AcceptanceRatioAutotuner(AutotuningBase):
         Pure functional update — see class docstring.
         """
         candidate_x_prop = candidate.x_prop_plus[1:]
-        nonlin_cost, nonlin_pen, nodal_pen = self.calculate_nonlinear_penalty(
+        nonlin_cost, nonlin_pen, nodal_pen = calculate_nonlinear_penalty(
             candidate_x_prop,
             candidate.x,
             candidate.u,
@@ -135,17 +134,7 @@ class AcceptanceRatioAutotuner(AutotuningBase):
         )
         J_nonlin = nonlin_cost + nonlin_pen + nodal_pen
 
-        # Cost relaxation: when state.k > hyper.lam_cost_drop, scale
-        # state.lam_cost; otherwise reset to the algorithm's initial weight
-        # (carried on the pytree as state.lam_cost_init, broadcast at
-        # from_settings()). Both constants ride the pytree so per-solve
-        # overrides and vmap sweeps reach the traced body. Scalar
-        # lam_cost_relax preserves the user-specified per-state weight ratios.
-        lam_cost_next = jnp.where(
-            state.k > state.hyper.lam_cost_drop,
-            state.lam_cost * state.hyper.lam_cost_relax,
-            state.lam_cost_init,
-        )
+        lam_cost_next = self._relaxed_lam_cost(state)
 
         def first_iter(state):
             # Iter 1: accept unconditionally, leave weights at their init values,
@@ -164,7 +153,7 @@ class AcceptanceRatioAutotuner(AutotuningBase):
             # Recompute the previous iterate's J_nonlin from the pytree fields
             # (state.x/state.u were the *previous* accepted iterate).
             prev_x_prop = state.x_prop_plus[1:]
-            prev_cost, prev_pen, prev_nodal_pen = self.calculate_nonlinear_penalty(
+            prev_cost, prev_pen, prev_nodal_pen = calculate_nonlinear_penalty(
                 prev_x_prop,
                 state.x,
                 state.u,

{openscvx-0.5.3.dev25 → openscvx-0.5.3.dev26}/openscvx/algorithms/autotuner/augmented_lagrangian.py

@@ -18,7 +18,7 @@ from .acceptance_ratio import AcceptanceRatioAutotuner, AcceptanceRatioHyper
 if TYPE_CHECKING:
     from openscvx.lowered import LoweredJaxConstraints
 
-    from ..base import AlgorithmState, CandidateIterate
+    from ..state import AlgorithmState, CandidateIterate
 
 
 class AugmentedLagrangianHyper(AcceptanceRatioHyper):

openscvx-0.5.3.dev26/openscvx/algorithms/autotuner/base.py

@@ -0,0 +1,259 @@
+"""Abstract base for autotuning strategies.
+
+:class:`AutotuningBase` is the contract every penalty-weight update rule
+implements: :py:meth:`~AutotuningBase.update_weights` is a pure functional
+update on an :class:`~openscvx.algorithms.state.AlgorithmState` pytree, so the
+SCP body composes with ``jax.jit`` / ``jax.vmap`` / ``jax.grad``. The base also
+houses :class:`LamCostRelaxHyper`, the ``lam_cost`` relaxation knobs every
+built-in autotuner shares, and :meth:`AutotuningBase._relaxed_lam_cost`, the
+single implementation of that rule.
+
+This module mirrors the package's ``base.py``-is-the-ABC idiom inside the
+``autotuner`` subpackage; the concrete autotuners live alongside it.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import fields as dc_fields
+from dataclasses import replace as dc_replace
+from typing import TYPE_CHECKING, List
+
+import jax.numpy as jnp
+
+from openscvx.utils.printing import Column
+
+from ..hyperparams import HyperParams
+
+if TYPE_CHECKING:
+    import hashlib
+
+    from openscvx.config import Config
+    from openscvx.lowered.jax_constraints import LoweredJaxConstraints
+
+    from ..state import AlgorithmState, CandidateIterate
+
+
+class LamCostRelaxHyper(HyperParams):
+    """``lam_cost`` relaxation knobs shared by every built-in autotuner.
+
+    Every autotuner relaxes ``lam_cost`` by the same rule (see
+    :meth:`AutotuningBase._relaxed_lam_cost`), so the two knobs that steer it
+    live here once instead of being re-declared per class. ``lam_cost_drop`` is
+    the iteration after which relaxation applies (``state.k > lam_cost_drop``):
+    ``-1`` relaxes from the first iteration, and the default
+    ``lam_cost_relax=1.0`` makes that a no-op.
+    """
+
+    lam_cost_drop: int = -1
+    lam_cost_relax: float = 1.0
+
+
+class AutotuningBase(ABC):
+    """Base class for autotuning strategies in SCP algorithms.
+
+    Subclasses implement :py:meth:`update_weights` as a **pure functional
+    update** on an :class:`AlgorithmState` pytree. Concretely, an autotuner
+    must:
+
+    * Not mutate ``state`` or ``candidate``.
+    * Not return strings, raise on data-dependent conditions, or append to
+      Python lists at trace time.
+    * Express all branching on iterate values via ``jax.lax.cond`` /
+      ``jnp.where``.
+
+    The autotuner's per-iteration outcome is encoded as an
+    :class:`AdaptiveStateCode` int32 on the returned state; the SCP loop
+    converts that back to a human-readable label only on the Python-loop
+    printing path.
+
+    **The returned state IS the next iterate.** The SCP loop discards
+    everything except what ``update_weights`` returns, so accepting the
+    subproblem's candidate means carrying its trajectory onto the returned
+    state — ``x`` / ``u`` / ``x_prop`` / ``x_prop_plus`` from ``candidate`` —
+    while rejecting means keeping the previous fields and adjusting only the
+    weights. An update that never copies the candidate produces a solver that
+    runs to ``k_max`` without the iterate ever moving, silently.
+
+    **Declaring tunable hyperparameters.** A numeric knob a user might sweep
+    (a penalty ramp, a relaxation iteration) must not be read off ``self``
+    inside ``update_weights`` — a Python attribute is baked into the trace
+    and invisible to every override channel. Instead, declare it on a
+    :class:`HyperParams` subclass, assign an instance to ``self.hyper``, and
+    read it from ``state.hyper``::
+
+        class MyHyper(HyperParams):
+            ramp: float = 2.0
+
+        class MyAutotuner(AutotuningBase):
+            def __init__(self, ramp: float = 2.0):
+                self.hyper = MyHyper(ramp=ramp)
+
+            def update_weights(self, state, candidate, nodal_constraints, settings, params):
+                return state.replace(
+                    # accept the candidate: it becomes the next iterate
+                    x=candidate.x,
+                    u=candidate.u,
+                    x_prop=candidate.x_prop,
+                    x_prop_plus=candidate.x_prop_plus,
+                    lam_prox=state.lam_prox * state.hyper.ramp,
+                    adaptive_state_code=...,
+                )
+
+    The declaration is the registration: the field becomes a per-solve
+    override (``solve_jax(algorithm={"ramp": ...})``), a batchable sweep
+    target (``solve_batched(algorithm={"ramp": jnp.linspace(...)})``), and a
+    runtime input of the exported batched artifact — with zero core edits.
+    Every numeric knob of the built-in autotuners is declared this way, so the
+    only configuration left outside ``hyper`` is structural choices that select
+    code paths (class attributes like ``COMPUTES_ACCEPTANCE_METRICS``); they
+    are part of the traced program, not data. For ergonomics, declared knobs
+    are still readable and writable as bare attributes
+    (``autotuner.ramp = 3.0``): the proxy below routes the access into
+    ``hyper`` so a constructor — or a test — may keep assigning knobs by name.
+    Assign ``self.hyper`` *first* in ``__init__``; a knob assigned before
+    ``hyper`` exists lands as a plain instance attribute the proxy cannot see.
+
+    Class Attributes:
+        COLUMNS: List of Column specs for autotuner-specific metrics to display.
+            Subclasses override this to add their own columns.
+        COMPUTES_ACCEPTANCE_METRICS: Whether ``update_weights`` computes a
+            predicted/actual reduction and the resulting acceptance ratio. The
+            SCP loop records and prints those diagnostics only when this is
+            ``True`` (the default); tuners that never reject an iterate — e.g.
+            :class:`~openscvx.algorithms.autotuner.constant_proximal_weight.ConstantProximalWeight`
+            and :class:`~openscvx.algorithms.autotuner.ramp_proximal_weight.RampProximalWeight`
+            — set it ``False``.
+        hyper: The autotuner's declared hyperparameters — a
+            :class:`HyperParams` instance carrying plain-Python defaults
+            (the empty base when it declares none). Snapshotted onto
+            ``AlgorithmState.hyper`` with array leaves (see
+            :meth:`AlgorithmState.from_settings`; ``int`` fields get ``k``'s
+            integer dtype, ``float`` fields the float dtype), which is what
+            ``update_weights`` reads at trace time.
+    """
+
+    COLUMNS: List[Column] = []
+    COMPUTES_ACCEPTANCE_METRICS: bool = True
+    hyper: HyperParams = HyperParams()
+
+    def __getattr__(self, name: str):
+        """Read a declared hyperparameter as a bare attribute.
+
+        Promoted knobs live on the frozen ``hyper`` container, but the
+        documented API and constructors still touch them by name
+        (``autotuner.lam_prox_max``). ``__getattr__`` fires only on failed
+        normal lookups, so real attributes (``COLUMNS``, ``hyper`` itself) are
+        unaffected; a name matching a ``hyper`` field resolves there.
+        """
+        hyper = self.__dict__.get("hyper")
+        if hyper is not None and name in {f.name for f in dc_fields(hyper)}:
+            return getattr(hyper, name)
+        raise AttributeError(f"{type(self).__name__!r} has no attribute {name!r}")
+
+    def __setattr__(self, name: str, value) -> None:
+        """Route a write to a declared hyperparameter into the frozen ``hyper``.
+
+        Without this, assigning a promoted knob as a bare attribute
+        (``autotuner.lam_prox_max = 1e6``) would silently shadow the ``hyper``
+        field and never reach the solve. A name matching a ``hyper`` field is
+        applied via :func:`dataclasses.replace`; every other attribute
+        (including ``hyper`` itself) is set normally, so constructors may keep
+        assigning knobs by name — they route into ``hyper``, provided
+        ``self.hyper`` was assigned first (see the class docstring).
+        """
+        hyper = self.__dict__.get("hyper")
+        if hyper is not None and name != "hyper" and name in {f.name for f in dc_fields(hyper)}:
+            # Clear any instance attribute shadowing the knob (left by an
+            # assignment made before ``hyper`` existed) so reads resolve
+            # through ``__getattr__`` to the value just written.
+            self.__dict__.pop(name, None)
+            super().__setattr__("hyper", dc_replace(hyper, **{name: value}))
+        else:
+            super().__setattr__(name, value)
+
+    def _hash_into(self, hasher: "hashlib._Hash") -> None:
+        """Contribute the autotuner's update rule to the ``solve_batched`` cache key.
+
+        The exported batched loop bakes in ``update_weights`` and every numeric
+        parameter that steers it (penalty ramps, acceptance thresholds, weight
+        clips). The default hashes the concrete class plus all instance
+        attributes — sufficient because autotuner parameters are plain
+        scalars. The ``hyper`` *values* are excluded: declared hyperparameters
+        ride ``AlgorithmState.hyper`` as runtime inputs, so one artifact serves
+        every setting of them (the same reasoning that keeps the ``ep_*``
+        thresholds out of the algorithm's hash). The ``hyper`` *schema* is
+        folded in, though: the ``hyper`` leaves map positionally onto the
+        exported artifact's avals, so a field reorder or addition silently
+        permutes runtime values against the wrong leaves. Hashing the field
+        names in declaration order turns such a change into a clean cache miss
+        and rebuild — this matters because :class:`LamCostRelaxHyper` moves
+        ``lam_cost_drop`` / ``lam_cost_relax`` to the *front* of the field
+        order. Folded in by :meth:`Algorithm._hash_into`; mirrors the symbolic
+        ``_hash_into`` protocol.
+        """
+        from openscvx.utils.caching import hash_value_into
+
+        hasher.update(type(self).__name__.encode())
+        for name in sorted(vars(self)):
+            if name == "hyper":
+                continue
+            hasher.update(name.encode())
+            hash_value_into(hasher, getattr(self, name))
+        # Schema, not values: the hyper field order/names fix the exported
+        # artifact's leaf layout, so a reorder must invalidate cached artifacts
+        # rather than silently permute runtime values onto the wrong avals.
+        for fld in dc_fields(self.hyper):
+            hasher.update(fld.name.encode())
+
+    @staticmethod
+    def _relaxed_lam_cost(state: "AlgorithmState") -> jnp.ndarray:
+        """``lam_cost`` for the next iterate per the shared relaxation rule.
+
+        When ``state.k > state.hyper.lam_cost_drop``, scale ``state.lam_cost``
+        by ``state.hyper.lam_cost_relax``; otherwise reset to the algorithm's
+        initial weight (carried on the pytree as ``state.lam_cost_init``,
+        broadcast at :meth:`AlgorithmState.from_settings`). Both constants ride
+        the pytree so per-solve overrides and ``vmap`` sweeps reach the traced
+        body; the scalar ``lam_cost_relax`` preserves the user-specified
+        per-state weight ratios. Shared verbatim by every built-in autotuner
+        via the :class:`LamCostRelaxHyper` knobs.
+        """
+        return jnp.where(
+            state.k > state.hyper.lam_cost_drop,
+            state.lam_cost * state.hyper.lam_cost_relax,
+            state.lam_cost_init,
+        )
+
+    @abstractmethod
+    def update_weights(
+        self,
+        state: "AlgorithmState",
+        candidate: "CandidateIterate",
+        nodal_constraints: "LoweredJaxConstraints",
+        settings: "Config",
+        params: dict,
+    ) -> "AlgorithmState":
+        """Return the next-iterate :class:`AlgorithmState`.
+
+        Must be JAX-traceable. See the class docstring for the contract.
+
+        Args:
+            state: Current-iterate pytree. Initial weights live on
+                ``state.lam_cost_init``; autotuners read from there rather than
+                from the algorithm's ``Weights`` object so the JIT'd closure
+                stays cache-stable across weight mutations.
+            candidate: Subproblem result (read-only here). On acceptance its
+                trajectory fields must be carried onto the returned state —
+                see the class docstring.
+            nodal_constraints: Lowered JAX constraints.
+            settings: Configuration object.
+            params: Problem parameter dictionary.
+
+        Returns:
+            The next-iterate :class:`AlgorithmState` — the SCP loop uses
+            nothing else, so an accepting update carries
+            ``candidate.x / u / x_prop / x_prop_plus`` onto it, while a
+            rejecting update keeps the previous fields and adjusts only the
+            weights. Its :py:attr:`AlgorithmState.adaptive_state_code` encodes
+            the autotuner's decision; the SCP loop records that into history
+            and maps it to a printable label.
+        """