openscvx 2.dev4__tar.gz → 2.dev6__tar.gz

{openscvx-2.dev4/openscvx.egg-info → openscvx-2.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 2.dev4
+Version: 2.dev6
 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-2.dev4 → openscvx-2.dev6}/examples/mjx/cartpole_mjx.py

@@ -34,7 +34,6 @@ except ImportError:
     sys.exit(1)
 
 import openscvx as ox
-from openscvx.integrations import mjx_byof
 
 CARTPOLE_XML = """
 <mujoco model="cartpole">
@@ -69,36 +68,32 @@ n_u = int(mjx_model.nu)
 n = 60
 total_time = 3.0
 
-qpos = ox.State("qpos", shape=(n_q,))
+# ── MJX dynamics as a first-class adapter ─────────────────────────────────────
+# `MjxDynamics` builds default qpos / qvel / ctrl State and Control objects
+# matching the model's nq / nv / nu and routes the MJX forward dynamics into
+# the BYOF channel internally — no separate `byof=` plumbing required.
+dyn = ox.MjxDynamics(mjx_model)
+qpos, qvel = dyn.states
+(ctrl,) = dyn.controls
+
 qpos.min = np.array([-3.0, -2.0 * np.pi])
 qpos.max = np.array([3.0, 2.0 * np.pi])
 qpos.initial = np.array([0.0, np.pi])
 qpos.final = np.array([0.0, 0.0])
 
-qvel = ox.State("qvel", shape=(n_v,))
 qvel.min = np.array([-10.0, -15.0])
 qvel.max = np.array([10.0, 15.0])
 qvel.initial = np.array([0.0, 0.0])
 qvel.final = np.array([0.0, 0.0])
 
-ctrl = ox.Control("ctrl", shape=(n_u,))
 ctrl.min = np.array([-1.0])
 ctrl.max = np.array([1.0])
 ctrl.guess = np.zeros((n, n_u))
 
-states = [qpos, qvel]
-controls = [ctrl]
-
-dynamics = {
-    "qpos": qvel,
-}
-
-byof: ox.ByofSpec = {"dynamics": mjx_byof(mjx_model, qpos=qpos, qvel=qvel, ctrl=ctrl)}
-
 constraints = []
-for state in states:
+for state in dyn.states:
     constraints.extend([ox.ctcs(state <= state.max), ox.ctcs(state.min <= state)])
-for control in controls:
+for control in dyn.controls:
     constraints.extend([ox.ctcs(control <= control.max), ox.ctcs(control.min <= control)])
 
 theta_guess = np.linspace(np.pi, 0.0, n)
@@ -115,13 +110,12 @@ time = ox.Time(
 )
 
 problem = ox.Problem(
-    dynamics=dynamics,
-    states=states,
-    controls=controls,
+    dynamics=dyn,
+    states=dyn.states,
+    controls=dyn.controls,
     time=time,
     constraints=constraints,
     N=n,
-    byof=byof,
     algorithm={
         "lam_prox": 1e-1,
         "lam_cost": 1e-2,

{openscvx-2.dev4 → openscvx-2.dev6}/examples/mjx/double_cartpole_mjx.py

@@ -34,8 +34,6 @@ except ImportError:
     sys.exit(1)
 
 import openscvx as ox
-from openscvx import ByofSpec
-from openscvx.integrations import mjx_byof
 
 L1, L2 = 0.5, 0.4  # link lengths (m)
 
@@ -81,32 +79,26 @@ n_u = int(mjx_model.nu)  # 1: cart force
 n = 400
 total_time = 2.5
 
-# ── State / control definitions ───────────────────────────────────────────────
-qpos = ox.State("qpos", shape=(n_q,))
+# ── MJX dynamics adapter ──────────────────────────────────────────────────────
+dyn = ox.MjxDynamics(mjx_model)
+qpos, qvel = dyn.states
+(ctrl,) = dyn.controls
+ctrl.parameterization = "ZOH"
+
 qpos.min = np.array([-8.0, -2 * np.pi, -2 * np.pi])
 qpos.max = np.array([8.0, 2 * np.pi, 2 * np.pi])
 qpos.initial = np.array([0.0, np.pi, 0.0])  # cart at origin, link1 hanging down
 qpos.final = [ox.Free(0.0), 0.0, 0.0]  # cart free, both links upright
 
-qvel = ox.State("qvel", shape=(n_v,))
 qvel.min = np.array([-12.0, -12.0, -12.0])
 qvel.max = np.array([12.0, 12.0, 12.0])
 qvel.initial = np.zeros(n_v)
 qvel.final = [0.0, 0.0, 0.0]
 
-ctrl = ox.Control("ctrl", shape=(n_u,), parameterization="ZOH")
 ctrl.min = np.array([-2.0])
 ctrl.max = np.array([2.0])
 ctrl.guess = np.zeros((n, n_u))
 
-states = [qpos, qvel]
-controls = [ctrl]
-
-# ── Dynamics: position kinematics symbolically, velocity via MJX ──────────────
-dynamics: dict = {"qpos": qvel}  # nq == nv, valid for all-revolute/prismatic joints
-
-byof: ByofSpec = {"dynamics": mjx_byof(mjx_model, qpos=qpos, qvel=qvel, ctrl=ctrl)}
-
 # ── Constraints (CTCS on state / control bounds) ───────────────────────────────
 constraints = []
 
@@ -123,13 +115,12 @@ time = ox.Time(
 )
 
 problem = ox.Problem(
-    dynamics=dynamics,
-    states=states,
-    controls=controls,
+    dynamics=dyn,
+    states=dyn.states,
+    controls=dyn.controls,
     time=time,
     constraints=constraints,
     N=n,
-    byof=byof,
     algorithm={
         "lam_prox": 1e-1,
         "lam_cost": 0e0,

{openscvx-2.dev4 → openscvx-2.dev6}/examples/mjx/skydio_x2_mjx.py

@@ -51,8 +51,7 @@ from examples.plotting_viser import (
     create_animated_plotting_server,
     create_scp_animated_plotting_server,
 )
-from openscvx import ByofSpec, Problem
-from openscvx.integrations import mjx_byof
+from openscvx import Problem
 from openscvx.utils import gen_vertices, rot
 
 HOVER_CTRL = 3.2495625  # N per motor for level hover (from menagerie keyframe)
@@ -78,33 +77,28 @@ n_u = int(mjx_model.nu)  # 4 — rotor thrusts
 n = 22
 total_time = 24.0
 
-# ── State / control definitions ───────────────────────────────────────────────
-qpos = ox.State("qpos", shape=(n_q,))
+# ── MJX dynamics adapter ──────────────────────────────────────────────────────
+# The free joint has nq=7 but nv=6 (quaternion adds one extra position DOF).
+# MjxDynamics detects nq > nv and automatically routes quaternion kinematics
+# for "qpos" alongside the MJX "qvel" dynamics through the BYOF channel.
+dyn = ox.MjxDynamics(mjx_model)
+qpos, qvel = dyn.states
+(ctrl,) = dyn.controls
+
 qpos.min = np.array([-200.0, -100.0, 15.0, -1.0, -1.0, -1.0, -1.0])
 qpos.max = np.array([200.0, 100.0, 200.0, 1.0, 1.0, 1.0, 1.0])
 qpos.initial = np.concatenate([START_POS, HOVER_QUAT])
 qpos.final = [10.0, 0.0, 20.0, ("free", 1.0), ("free", 0.0), ("free", 0.0), ("free", 0.0)]
 
-qvel = ox.State("qvel", shape=(n_v,))
 qvel.min = np.array([-100.0, -100.0, -100.0, -10.0, -10.0, -10.0])
 qvel.max = np.array([100.0, 100.0, 100.0, 10.0, 10.0, 10.0])
 qvel.initial = np.zeros(n_v)
 qvel.final = [("free", 0.0)] * n_v
 
-ctrl = ox.Control("ctrl", shape=(n_u,))
 ctrl.min = np.zeros(n_u)
 ctrl.max = 13.0 * np.ones(n_u)
 ctrl.guess = HOVER_CTRL * np.ones((n, n_u))
 
-states = [qpos, qvel]
-controls = [ctrl]
-
-# ── Dynamics via BYOF ─────────────────────────────────────────────────────────
-# The free joint has nq=7 but nv=6 (quaternion adds one extra position DOF).
-# nq=7, nv=6 (free joint): mjx_byof detects nq > nv and automatically
-# includes quaternion kinematics for "qpos" alongside the MJX "qvel" dynamics.
-byof: ByofSpec = {"dynamics": mjx_byof(mjx_model, qpos=qpos, qvel=qvel, ctrl=ctrl)}
-
 # ── Gate parameters (matching examples/drone/drone_racing.py) ───────────────
 n_gates = 10
 initial_gate_centers = [
@@ -135,9 +129,9 @@ gate_centers = np.array(modified_centers)
 
 # ── Constraints ───────────────────────────────────────────────────────────────
 constraints = []
-for state in states:
+for state in dyn.states:
     constraints.extend([ox.ctcs(state <= state.max), ox.ctcs(state.min <= state)])
-for control in controls:
+for control in dyn.controls:
     constraints.extend([ox.ctcs(control <= control.max), ox.ctcs(control.min <= control)])
 
 # Enforce sequential gate traversal using nodal constraints on qpos position.
@@ -172,13 +166,12 @@ time = ox.Time(
 )
 
 problem = Problem(
-    dynamics={},  # all dynamics go through BYOF
-    states=states,
-    controls=controls,
+    dynamics=dyn,
+    states=dyn.states,
+    controls=dyn.controls,
     time=time,
     constraints=constraints,
     N=n,
-    byof=byof,
     algorithm={
         "lam_prox": 1e-1,
         "lam_cost": 1e-2,

{openscvx-2.dev4 → openscvx-2.dev6}/examples/mjx/triple_cartpole_3d_mjx.py

@@ -57,8 +57,7 @@ except ImportError:
     sys.exit(1)
 
 import openscvx as ox
-from openscvx import ByofSpec, Problem
-from openscvx.integrations import mjx_byof
+from openscvx import Problem
 
 L1, L2, L3 = 0.5, 0.4, 0.3  # link lengths (m)
 
@@ -122,8 +121,11 @@ IDX_A1, IDX_B1 = 2, 3
 IDX_A2, IDX_B2 = 4, 5
 IDX_A3, IDX_B3 = 6, 7
 
-# ── State / control definitions ───────────────────────────────────────────────
-qpos = ox.State("qpos", shape=(n_q,))
+# ── MJX dynamics adapter ──────────────────────────────────────────────────────
+dyn = ox.MjxDynamics(mjx_model)
+qpos, qvel = dyn.states
+(ctrl,) = dyn.controls
+
 qpos.min = np.array(
     [-8.0, -8.0, -2 * np.pi, -2 * np.pi, -2 * np.pi, -2 * np.pi, -2 * np.pi, -2 * np.pi]
 )
@@ -142,25 +144,15 @@ qpos.final = [
     0.0,  # link 3 upright
 ]
 
-qvel = ox.State("qvel", shape=(n_v,))
 qvel.min = np.full(n_v, -12.0)
 qvel.max = np.full(n_v, 12.0)
 qvel.initial = np.zeros(n_v)
 qvel.final = [0.0] * n_v
 
-ctrl = ox.Control("ctrl", shape=(n_u,))
 ctrl.min = np.array([-2.0, -2.0])
 ctrl.max = np.array([2.0, 2.0])
 ctrl.guess = np.zeros((n, n_u))
 
-states = [qpos, qvel]
-controls = [ctrl]
-
-# ── Dynamics: position kinematics symbolically, velocity via MJX ──────────────
-dynamics: dict = {"qpos": qvel}  # nq == nv
-
-byof: ByofSpec = {"dynamics": mjx_byof(mjx_model, qpos=qpos, qvel=qvel, ctrl=ctrl)}
-
 # ── Constraints (CTCS on state / control bounds) ─────────────────────────────
 constraints = []
 
@@ -179,13 +171,12 @@ time = ox.Time(
 )
 
 problem = Problem(
-    dynamics=dynamics,
-    states=states,
-    controls=controls,
+    dynamics=dyn,
+    states=dyn.states,
+    controls=dyn.controls,
     time=time,
     constraints=constraints,
     N=n,
-    byof=byof,
     algorithm={
         "lam_prox": 1e-1,
         "lam_cost": 0e0,

{openscvx-2.dev4 → openscvx-2.dev6}/examples/mjx/triple_cartpole_mjx.py

@@ -35,8 +35,7 @@ except ImportError:
     sys.exit(1)
 
 import openscvx as ox
-from openscvx import ByofSpec, Problem
-from openscvx.integrations import mjx_byof
+from openscvx import Problem
 
 L1, L2, L3 = 0.5, 0.4, 0.3  # link lengths (m)
 
@@ -88,35 +87,28 @@ n_u = int(mjx_model.nu)  # 1: cart force
 n = 60  # more nodes → finer resolution near the unstable upright equilibrium
 total_time = 2.5
 
-# ── State / control definitions ───────────────────────────────────────────────
-qpos = ox.State("qpos", shape=(n_q,))
+# ── MJX dynamics adapter ──────────────────────────────────────────────────────
+dyn = ox.MjxDynamics(mjx_model)
+qpos, qvel = dyn.states
+(ctrl,) = dyn.controls
+
 qpos.min = np.array([-100.0, -2 * np.pi, -2 * np.pi, -2 * np.pi])
 qpos.max = np.array([100.0, 2 * np.pi, 2 * np.pi, 2 * np.pi])
 qpos.initial = np.array([0.0, np.pi, 0.0, 0.0])  # all links hanging down
 qpos.final = [ox.Free(0.0), 0.0, 0.0, 0.0]  # all links upright
 
-qvel = ox.State("qvel", shape=(n_v,))
 qvel.min = np.array([-12.0, -12.0, -12.0, -12.0])
 qvel.max = np.array([12.0, 12.0, 12.0, 12.0])
 qvel.initial = np.zeros(n_v)
 qvel.final = [0.0, 0.0, 0.0, 0.0]
 
-ctrl = ox.Control("ctrl", shape=(n_u,))
 ctrl.min = np.array([-3.0])
 ctrl.max = np.array([3.0])
 ctrl.guess = np.zeros((n, n_u))
 
-states = [qpos, qvel]
-controls = [ctrl]
-
-# ── Dynamics: position kinematics symbolically, velocity via MJX ──────────────
-dynamics: dict = {"qpos": qvel}  # nq==nv so this is always valid
-
-byof: ByofSpec = {"dynamics": mjx_byof(mjx_model, qpos=qpos, qvel=qvel, ctrl=ctrl)}
-
 # ── Constraints (CTCS on state / control bounds) ───────────────────────────────
 constraints = []
-for state in states:
+for state in dyn.states:
     constraints.extend([ox.ctcs(state <= state.max), ox.ctcs(state.min <= state)])
 
 # ── Initial guess: linearly swing θ₁ from π → 0, others stay 0 ───────────────
@@ -132,13 +124,12 @@ time = ox.Time(
 )
 
 problem = Problem(
-    dynamics=dynamics,
-    states=states,
-    controls=controls,
+    dynamics=dyn,
+    states=dyn.states,
+    controls=dyn.controls,
     time=time,
     constraints=constraints,
     N=n,
-    byof=byof,
     algorithm={
         "lam_prox": 1e0,
         "lam_cost": 0e0,

{openscvx-2.dev4 → openscvx-2.dev6}/openscvx/__init__.py

@@ -12,6 +12,7 @@ import openscvx.symbolic.expr.spatial as spatial
 import openscvx.symbolic.expr.stl as stl
 import openscvx.symbolic.expr.stljax as stljax
 from openscvx.algorithms import (
+    AdaptiveProximalWeight,
     AugmentedLagrangian,
     ConstantProximalWeight,
     PenalizedTrustRegion,
@@ -25,6 +26,7 @@ from openscvx.discretization import (
     VectorizeDiscretizeLinearize,
 )
 from openscvx.expert import ByofSpec
+from openscvx.integrations import DynamicsAdapter, MjxDynamics
 from openscvx.loader import load_dict, load_json, load_yaml
 from openscvx.problem import Problem
 from openscvx.solvers import PTRSolver
@@ -176,6 +178,9 @@ __all__ = [
     "lie",
     # Expert mode types
     "ByofSpec",
+    # External-backend dynamics adapters
+    "DynamicsAdapter",
+    "MjxDynamics",
     # Discretization
     "DiscretizeLinearizeVectorize",
     "LinearizeDiscretize",
@@ -186,6 +191,7 @@ __all__ = [
     # Algorithm & Autotuning
     "PenalizedTrustRegion",
     "AugmentedLagrangian",
+    "AdaptiveProximalWeight",
     "ConstantProximalWeight",
     "RampProximalWeight",
 ]

{openscvx-2.dev4 → openscvx-2.dev6}/openscvx/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.dev4'
-__version_tuple__ = version_tuple = (2, 'dev4')
+__version__ = version = '2.dev6'
+__version_tuple__ = version_tuple = (2, 'dev6')
 
-__commit_id__ = commit_id = 'g85f47e152'
+__commit_id__ = commit_id = 'gcabefce07'

{openscvx-2.dev4 → openscvx-2.dev6}/openscvx/algorithms/__init__.py

@@ -82,12 +82,19 @@ from typing import Annotated, Any, Dict, List, Optional, Union
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
-from .augmented_lagrangian import AugmentedLagrangian, AugmentedLagrangianSpec
+from .autotuner import (
+    AdaptiveProximalWeight,
+    AdaptiveProximalWeightSpec,
+    AugmentedLagrangian,
+    AugmentedLagrangianSpec,
+    ConstantProximalWeight,
+    ConstantProximalWeightSpec,
+    RampProximalWeight,
+    RampProximalWeightSpec,
+)
 from .base import Algorithm, AlgorithmState, AutotuningBase, DiscretizationResult
-from .constant_proximal_weight import ConstantProximalWeight, ConstantProximalWeightSpec
 from .optimization_results import OptimizationResults
-from .penalized_trust_region import PenalizedTrustRegion
-from .ramp_proximal_weight import RampProximalWeight, RampProximalWeightSpec
+from .scvx import PenalizedTrustRegion
 from .weights import Weights
 
 # ---------------------------------------------------------------------------
@@ -97,6 +104,7 @@ from .weights import Weights
 AutotunerConfig = Annotated[
     Union[
         AugmentedLagrangianSpec,
+        AdaptiveProximalWeightSpec,
         RampProximalWeightSpec,
         ConstantProximalWeightSpec,
     ],
@@ -173,6 +181,7 @@ __all__ = [
     "PenalizedTrustRegion",
     "AutotuningBase",
     "AugmentedLagrangian",
+    "AdaptiveProximalWeight",
     "ConstantProximalWeight",
     "RampProximalWeight",
     # Config models

openscvx-2.dev6/openscvx/algorithms/autotuner/__init__.py

@@ -0,0 +1,17 @@
+"""SCP weight autotuning strategies."""
+
+from .adaptive_proximal_weight import AdaptiveProximalWeight, AdaptiveProximalWeightSpec
+from .augmented_lagrangian import AugmentedLagrangian, AugmentedLagrangianSpec
+from .constant_proximal_weight import ConstantProximalWeight, ConstantProximalWeightSpec
+from .ramp_proximal_weight import RampProximalWeight, RampProximalWeightSpec
+
+__all__ = [
+    "AdaptiveProximalWeight",
+    "AdaptiveProximalWeightSpec",
+    "AugmentedLagrangian",
+    "AugmentedLagrangianSpec",
+    "ConstantProximalWeight",
+    "ConstantProximalWeightSpec",
+    "RampProximalWeight",
+    "RampProximalWeightSpec",
+]

openscvx-2.dev6/openscvx/algorithms/autotuner/adaptive_proximal_weight.py

@@ -0,0 +1,190 @@
+"""Autotuning functions for SCP (Successive Convex Programming) parameters."""
+
+from copy import deepcopy
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+from pydantic import BaseModel, ConfigDict
+
+from openscvx.config import Config
+
+from ..base import AutotuningBase
+from .augmented_lagrangian import AugmentedLagrangian
+
+if TYPE_CHECKING:
+    from openscvx.lowered import LoweredJaxConstraints
+
+    from ..base import AlgorithmState, CandidateIterate
+    from ..weights import Weights
+
+
+class AdaptiveProximalWeight(AutotuningBase):
+    """PTR-style proximal adaptation with fixed virtual penalty weights.
+
+    Same acceptance-ratio logic as :class:`AugmentedLagrangian` for ``lam_prox``,
+    but ``lam_vc`` and ``lam_vb_*`` are held constant at their current state values.
+    """
+
+    COLUMNS = AugmentedLagrangian.COLUMNS
+
+    def __init__(
+        self,
+        gamma_1: float = 2.0,
+        gamma_2: float = 0.5,
+        eta_0: float = 1e-2,
+        eta_1: float = 1e-1,
+        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,
+    ):
+        self.gamma_1 = gamma_1
+        self.gamma_2 = gamma_2
+        self.eta_0 = eta_0
+        self.eta_1 = eta_1
+        self.eta_2 = eta_2
+        self.lam_prox_min = lam_prox_min
+        self.lam_prox_max = lam_prox_max
+        self.lam_cost_drop = lam_cost_drop
+        self.lam_cost_relax = lam_cost_relax
+
+    @staticmethod
+    def _copy_virtual_weights(
+        candidate: "CandidateIterate",
+        state: "AlgorithmState",
+    ) -> None:
+        candidate.lam_vc = state.lam_vc
+        candidate.lam_vb_nodal = state.lam_vb_nodal
+        candidate.lam_vb_cross = state.lam_vb_cross
+
+    def update_weights(
+        self,
+        state: "AlgorithmState",
+        candidate: "CandidateIterate",
+        nodal_constraints: "LoweredJaxConstraints",
+        settings: Config,
+        params: dict,
+        weights: "Weights",
+    ) -> str:
+        """Update SCP proximal weight based on acceptance ratio; keep VC/VB fixed."""
+        candidate_x_prop = (
+            candidate.x_prop_plus[1:] if candidate.x_prop_plus is not None else candidate.x_prop
+        )
+        (
+            nonlinear_cost,
+            nonlinear_penalty,
+            nodal_penalty,
+        ) = self.calculate_nonlinear_penalty(
+            candidate_x_prop,
+            candidate.x,
+            candidate.u,
+            state.lam_vc,
+            state.lam_vb_nodal,
+            state.lam_vb_cross,
+            state.lam_cost,
+            nodal_constraints,
+            params,
+            settings,
+        )
+
+        candidate.J_nonlin = nonlinear_cost + nonlinear_penalty + nodal_penalty
+
+        if state.k > self.lam_cost_drop:
+            candidate.lam_cost = state.lam_cost * self.lam_cost_relax
+        else:
+            candidate.lam_cost = weights.lam_cost
+
+        lam_prox_k = deepcopy(state.lam_prox)
+
+        if state.k > 1:
+            state_x_prop_plus = state.x_prop_plus()
+            state_x_prop = (
+                state_x_prop_plus[1:] if state_x_prop_plus is not None else state.x_prop()
+            )
+            (
+                prev_nonlinear_cost,
+                prev_nonlinear_penalty,
+                prev_nodal_penalty,
+            ) = self.calculate_nonlinear_penalty(
+                state_x_prop,
+                state.x,
+                state.u,
+                state.lam_vc,
+                state.lam_vb_nodal,
+                state.lam_vb_cross,
+                state.lam_cost,
+                nodal_constraints,
+                params,
+                settings,
+            )
+
+            J_nonlin_prev = prev_nonlinear_cost + prev_nonlinear_penalty + prev_nodal_penalty
+
+            actual_reduction = J_nonlin_prev - candidate.J_nonlin
+            predicted_reduction = J_nonlin_prev - candidate.J_lin
+
+            if predicted_reduction == 0:
+                raise ValueError("Predicted reduction is 0.")
+
+            rho = actual_reduction / predicted_reduction
+
+            state.pred_reduction_history.append(predicted_reduction)
+            state.actual_reduction_history.append(actual_reduction)
+            state.acceptance_ratio_history.append(rho)
+
+            if rho < self.eta_0:
+                lam_prox_k1 = np.minimum(self.lam_prox_max, self.gamma_1 * lam_prox_k)
+                candidate.lam_prox = lam_prox_k1
+                state.reject_solution(candidate)
+                adaptive_state = "Reject Higher"
+            elif rho >= self.eta_0 and rho < self.eta_1:
+                lam_prox_k1 = np.minimum(self.lam_prox_max, self.gamma_1 * lam_prox_k)
+                candidate.lam_prox = lam_prox_k1
+                self._copy_virtual_weights(candidate, state)
+                state.accept_solution(candidate)
+                adaptive_state = "Accept Higher"
+            elif rho >= self.eta_1 and rho < self.eta_2:
+                candidate.lam_prox = lam_prox_k
+                self._copy_virtual_weights(candidate, state)
+                state.accept_solution(candidate)
+                adaptive_state = "Accept Constant"
+            else:
+                lam_prox_k1 = np.maximum(self.lam_prox_min, self.gamma_2 * lam_prox_k)
+                candidate.lam_prox = lam_prox_k1
+                self._copy_virtual_weights(candidate, state)
+                state.accept_solution(candidate)
+                adaptive_state = "Accept Lower"
+
+        else:
+            candidate.lam_prox = lam_prox_k
+            self._copy_virtual_weights(candidate, state)
+            state.accept_solution(candidate)
+            adaptive_state = "Initial"
+
+        return adaptive_state
+
+
+# =============================================================================
+# Pydantic spec for dict / YAML validation
+# =============================================================================
+
+
+class AdaptiveProximalWeightSpec(BaseModel):
+    """Validates AdaptiveProximalWeight configuration from dict/YAML input."""
+
+    type: Literal["AdaptiveProximalWeight"] = "AdaptiveProximalWeight"
+    gamma_1: float = 2.0
+    gamma_2: float = 0.5
+    eta_0: float = 1e-2
+    eta_1: float = 1e-1
+    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
+
+    model_config = ConfigDict(extra="forbid")
+
+    def build(self) -> AdaptiveProximalWeight:
+        return AdaptiveProximalWeight(**self.model_dump(exclude={"type"}, exclude_unset=True))