openscvx 2.dev5__tar.gz → 2.dev7__tar.gz

{openscvx-2.dev5/openscvx.egg-info → openscvx-2.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 2.dev5
+Version: 2.dev7
 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
@@ -26,6 +26,8 @@ Requires-Dist: pydantic>=2.0
 Provides-Extra: cvxpygen
 Requires-Dist: cvxpygen; extra == "cvxpygen"
 Requires-Dist: qocogen; extra == "cvxpygen"
+Provides-Extra: qpax
+Requires-Dist: qpax>=0.1.1; extra == "qpax"
 Provides-Extra: stl
 Requires-Dist: stljax; extra == "stl"
 Provides-Extra: lie

{openscvx-2.dev5 → openscvx-2.dev7}/docs/UnderTheHood/lowering_architecture.md

@@ -160,9 +160,40 @@ JAX lowering has no dependency on:
 
 This means JAX-lowered dynamics and constraints could be used with alternative solvers.
 
+## Convex Subproblem Backends
+
+The convex subproblem at each SCP iteration is solved by a concrete subclass
+of the abstract `PTRSolver` base. Two backends ship today:
+
+| Backend | Class | Selector | Notes |
+|---------|-------|----------|-------|
+| CVXPy (default) | `CVXPyPTRSolver` | `solver={"backend": "cvxpy"}` (default) | DCP graph via CVXPy, dispatched to QOCO / CLARABEL / etc. Supports user `.convex()` constraints, cross-node constraints, CTCS, and impulsive controls. Optional cvxpygen code generation. |
+| QPAX | `QPAXPTRSolver` | `solver={"backend": "qpax"}` | JAX-native QP via `qpax.solve_qp`. Flat `(Q, q, A, b, G, h)` assembly. Supports box / dynamics / CTCS / boundary-Fix; **rejects** user `.convex()`, cross-node, and impulsive at `initialize()` with a clear "use `CVXPyPTRSolver`" message. Enables a path toward an end-to-end JAX-differentiable SCP loop in follow-up work. |
+
+Picking a backend at construction time:
+
+```python
+import openscvx as ox
+
+# Default — same as today's CVXPyPTRSolver.
+problem = ox.Problem(...)
+
+# Explicit CVXPy with a different inner solver.
+problem = ox.Problem(..., solver={"backend": "cvxpy", "cvx_solver": "CLARABEL"})
+
+# JAX-native QPAX (requires the `qpax` extra: pip install openscvx[qpax]).
+problem = ox.Problem(..., solver={"backend": "qpax"})
+```
+
+QPAX consumes the global JAX dtype — pass `float_dtype="float64"` to `Problem`
+if you need tight inner-solver tolerances; the default `float32` is enough for
+many problems but caps the QP's conditioning.
+
 ## Further Reading
 
 - `openscvx/symbolic/lower.py` — Main lowering implementation
 - `openscvx/lowered/` — Dataclass definitions
 - `openscvx/symbolic/lowerers/jax.py` — JAX visitor implementation
 - `openscvx/symbolic/lowerers/cvxpy.py` — CVXPy visitor implementation
+- `openscvx/solvers/ptr_solver.py` — Abstract `PTRSolver` contract
+- `openscvx/solvers/cvxpy_ptr_solver.py` / `qpax_ptr_solver.py` — Concrete backends

{openscvx-2.dev5 → openscvx-2.dev7}/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,
@@ -28,7 +29,10 @@ 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
+from openscvx.solvers import CVXPyPTRSolver, PTRSolver
+
+# QPAXPTRSolver is exposed lazily via __getattr__ below to keep `import qpax`
+# off the hot import path for users who don't install the optional extra.
 from openscvx.symbolic.expr import (
     CTCS,
     Abs,
@@ -90,6 +94,16 @@ from openscvx.utils.cache import clear_cache, get_cache_dir, get_cache_size
 
 load_results = OptimizationResults.load
 
+
+def __getattr__(name: str):
+    """Lazy export for backends that depend on optional packages."""
+    if name == "QPAXPTRSolver":
+        from openscvx.solvers.qpax_ptr_solver import QPAXPTRSolver
+
+        return QPAXPTRSolver
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 __all__ = [
     # Main Trajectory Optimization Entrypoint
     "Problem",
@@ -187,9 +201,12 @@ __all__ = [
     "VectorizeDiscretizeLinearize",
     # Convex Solver
     "PTRSolver",
+    "CVXPyPTRSolver",
+    "QPAXPTRSolver",
     # Algorithm & Autotuning
     "PenalizedTrustRegion",
     "AugmentedLagrangian",
+    "AdaptiveProximalWeight",
     "ConstantProximalWeight",
     "RampProximalWeight",
 ]

{openscvx-2.dev5 → openscvx-2.dev7}/openscvx/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.dev5'
-__version_tuple__ = version_tuple = (2, 'dev5')
+__version__ = version = '2.dev7'
+__version_tuple__ = version_tuple = (2, 'dev7')
 
-__commit_id__ = commit_id = 'g4161a5a13'
+__commit_id__ = commit_id = 'g3a34d4fce'

{openscvx-2.dev5 → openscvx-2.dev7}/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.dev7/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.dev7/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))

{openscvx-2.dev5/openscvx/algorithms → openscvx-2.dev7/openscvx/algorithms/autotuner}/augmented_lagrangian.py

@@ -14,13 +14,13 @@ from openscvx.utils.printing import (
     color_adaptive_state,
 )
 
-from .base import AutotuningBase
+from ..base import AutotuningBase
 
 if TYPE_CHECKING:
     from openscvx.lowered import LoweredJaxConstraints
 
-    from .base import AlgorithmState, CandidateIterate
-    from .weights import Weights
+    from ..base import AlgorithmState, CandidateIterate
+    from ..weights import Weights
 
 
 class AugmentedLagrangian(AutotuningBase):
@@ -86,8 +86,12 @@ class AugmentedLagrangian(AutotuningBase):
             eta_2: Threshold above which solution is accepted with lower weight.
                 Defaults to 0.8.
             ep: Threshold for virtual control weight update (nu > ep vs nu <= ep).
-                Defaults to 0.5.
-            eta_lambda: Step size for virtual control weight update. Defaults to 1e0.
+                Must lie in (0, 1). Defaults to 0.99; when tuning, try 1e-1 if needed.
+                Typically tuned together with ``eta_lambda`` (often the first
+                parameters adjusted).
+            eta_lambda: Step size for virtual control weight update. Defaults to 1e1.
+                Typically tuned together with ``ep`` (often the first parameters
+                adjusted).
             lam_vc_max: Maximum virtual control penalty weight. Defaults to 1e5.
             lam_prox_min: Minimum trust region (proximal) weight. Defaults to 1e-3.
             lam_prox_max: Maximum trust region (proximal) weight. Defaults to 2e5.

{openscvx-2.dev5/openscvx/algorithms → openscvx-2.dev7/openscvx/algorithms/autotuner}/constant_proximal_weight.py

@@ -6,13 +6,13 @@ from pydantic import BaseModel, ConfigDict
 
 from openscvx.config import Config
 
-from .base import AutotuningBase
+from ..base import AutotuningBase
 
 if TYPE_CHECKING:
     from openscvx.lowered import LoweredJaxConstraints
 
-    from .base import AlgorithmState, CandidateIterate
-    from .weights import Weights
+    from ..base import AlgorithmState, CandidateIterate
+    from ..weights import Weights
 
 
 class ConstantProximalWeight(AutotuningBase):

{openscvx-2.dev5/openscvx/algorithms → openscvx-2.dev7/openscvx/algorithms/autotuner}/ramp_proximal_weight.py

@@ -7,13 +7,13 @@ from pydantic import BaseModel, ConfigDict
 
 from openscvx.config import Config
 
-from .base import AutotuningBase
+from ..base import AutotuningBase
 
 if TYPE_CHECKING:
     from openscvx.lowered import LoweredJaxConstraints
 
-    from .base import AlgorithmState, CandidateIterate
-    from .weights import Weights
+    from ..base import AlgorithmState, CandidateIterate
+    from ..weights import Weights
 
 
 class RampProximalWeight(AutotuningBase):

openscvx-2.dev7/openscvx/algorithms/scvx/__init__.py

@@ -0,0 +1,5 @@
+"""Successive convexification algorithm implementations."""
+
+from .penalized_trust_region import PenalizedTrustRegion
+
+__all__ = ["PenalizedTrustRegion"]

{openscvx-2.dev5/openscvx/algorithms → openscvx-2.dev7/openscvx/algorithms/scvx}/penalized_trust_region.py

@@ -22,11 +22,11 @@ from openscvx.utils.printing import (
     color_prob_stat,
 )
 
-from .augmented_lagrangian import AugmentedLagrangian
-from .base import Algorithm, AlgorithmState, CandidateIterate
-from .constant_proximal_weight import ConstantProximalWeight
-from .ramp_proximal_weight import RampProximalWeight
-from .weights import Weights
+from ..autotuner.augmented_lagrangian import AugmentedLagrangian
+from ..autotuner.constant_proximal_weight import ConstantProximalWeight
+from ..autotuner.ramp_proximal_weight import RampProximalWeight
+from ..base import Algorithm, AlgorithmState, CandidateIterate
+from ..weights import Weights
 
 if TYPE_CHECKING:
     from openscvx.lowered import LoweredJaxConstraints
@@ -34,7 +34,7 @@ if TYPE_CHECKING:
     from openscvx.symbolic.expr.control import Control
     from openscvx.symbolic.expr.state import State
 
-    from .base import AutotuningBase
+    from ..base import AutotuningBase
 
 warnings.filterwarnings("ignore")
 

{openscvx-2.dev5 → openscvx-2.dev7}/openscvx/loader.py

@@ -40,7 +40,7 @@ from pydantic import BaseModel, ConfigDict
 from openscvx.algorithms import PenalizedTrustRegionConfig
 from openscvx.config import SettingsSpec
 from openscvx.discretization import DiscretizerSpec
-from openscvx.solvers import SolverSpec
+from openscvx.solvers import PTRSolverSpec
 from openscvx.symbolic.expr.control import ControlSpec
 from openscvx.symbolic.expr.expr import Expr
 from openscvx.symbolic.expr.parameter import ParameterSpec
@@ -66,7 +66,7 @@ class ProblemSpec(BaseModel):
     constraints: List[str] = []
     algorithm: Optional[PenalizedTrustRegionConfig] = None
     discretizer: Optional[DiscretizerSpec] = None
-    solver: Optional[SolverSpec] = None
+    solver: Optional[PTRSolverSpec] = None
     settings: Optional[SettingsSpec] = None
     states_prop: Optional[List[StateSpec]] = None
     dynamics_prop: Optional[Dict[str, Any]] = None

{openscvx-2.dev5 → openscvx-2.dev7}/openscvx/lowered/cvxpy_constraints.py

@@ -17,7 +17,10 @@ class LoweredCvxpyConstraints:
 
     Attributes:
         constraints: List of CVXPy constraint objects (cp.Constraint).
-            Includes both nodal and cross-node convex constraints.
+            Includes both nodal and cross-node convex constraints. Empty
+            for backends that don't accept ``.convex()`` constraints — the
+            refusal happens earlier, in
+            :meth:`openscvx.solvers.base.ConvexSolver.lower_convex_constraints`.
     """
 
     constraints: list["cp.Constraint"] = field(default_factory=list)

{openscvx-2.dev5 → openscvx-2.dev7}/openscvx/problem.py

@@ -201,9 +201,11 @@ class Problem:
                     discretizer=ox.LinearizeDiscretize(dis_type="ZOH", ode_solver="Dopri8")
             solver: Convex subproblem solver configuration. Accepts:
 
-                - ``None`` — uses ``PTRSolver()`` with defaults (QOCO backend).
+                - ``None`` — uses ``CVXPyPTRSolver()`` with defaults (QOCO backend).
                 - A ``ConvexSolver`` instance — used directly.
-                - A ``dict`` — passed as kwargs to ``PTRSolver()``.
+                - A ``dict`` — validated as ``PTRSolverSpec``; the ``backend``
+                  field (``"cvxpy"`` or ``"qpax"``) selects the concrete
+                  backend.
 
                 Examples::
 
@@ -216,8 +218,12 @@ class Problem:
                     # Enable cvxpygen code generation
                     solver={"cvxpygen": True}
 
+                    # JAX-native QPAX backend (no cvx_solver / cvxpygen fields)
+                    solver={"backend": "qpax"}
+
                     # Instance
-                    solver=ox.PTRSolver(cvx_solver="CLARABEL")
+                    solver=ox.CVXPyPTRSolver(cvx_solver="CLARABEL")
+                    solver=ox.QPAXPTRSolver()
             byof (ByofSpec, optional): Expert mode only. Raw JAX functions to
                 bypass symbolic layer. See :class:`openscvx.expert.ByofSpec` for
                 detailed documentation.
@@ -393,9 +399,9 @@ class Problem:
     def solver(self) -> ConvexSolver:
         """Access the convex subproblem solver instance.
 
-        Attributes such as ``cvx_solver``, ``solver_args``, ``cvxpygen``, and
-        ``cvxpygen_override`` can be modified freely before ``initialize``
-        is called::
+        Backend-specific attributes (e.g. ``cvx_solver``, ``solver_args``,
+        ``cvxpygen``, ``cvxpygen_override`` on :class:`CVXPyPTRSolver`) can
+        be modified freely before ``initialize`` is called::
 
             problem.solver.solver_args = {"abstol": 1e-6, "reltol": 1e-9}
             problem.solver.cvxpygen = True
@@ -407,7 +413,7 @@ class Problem:
             will have no effect on subsequent solves.
 
         Returns:
-            The solver instance (e.g., PTRSolver).
+            The solver instance — a concrete :class:`PTRSolver` subclass.
         """
         return self._solver
 
@@ -510,12 +516,12 @@ class Problem:
                 self._lowered.x_prop_unified.final[state._slice] = state.final
                 self._lowered.x_prop_unified.final_type[state._slice] = state.final_type
 
-        # Update CVXPy solver parameters (only if solver is initialized)
-        if self._solver._problem is not None:
-            self._solver.update_boundary_conditions(
-                x_init=self._lowered.x_unified.initial,
-                x_term=self._lowered.x_unified.final,
-            )
+        # Push to the solver — both backends short-circuit on a pre-initialize
+        # call, so this is safe to invoke from any lifecycle point.
+        self._solver.update_boundary_conditions(
+            x_init=self._lowered.x_unified.initial,
+            x_term=self._lowered.x_unified.final,
+        )
 
     def _sync_guesses(self):
         """Sync trajectory guesses from State/Control objects to lowered representation.

openscvx-2.dev7/openscvx/solvers/__init__.py

@@ -0,0 +1,93 @@
+"""Convex subproblem solvers for trajectory optimization.
+
+This module provides implementations of convex subproblem solvers used within
+SCvx algorithms. At each iteration of a successive convexification algorithm,
+the non-convex problem is approximated by a convex subproblem, which is then
+solved using one of these solver backends.
+
+All solvers inherit from :class:`ConvexSolver`, enabling pluggable solver
+implementations and custom backends:
+
+```python
+class ConvexSolver(ABC):
+    @abstractmethod
+    def create_variables(self, N, x_unified, u_unified, jax_constraints) -> None:
+        '''Create backend-specific optimization variables (called once).'''
+        ...
+
+    @abstractmethod
+    def initialize(self, lowered, settings) -> None:
+        '''Build the convex subproblem structure (called once).'''
+        ...
+
+    @abstractmethod
+    def solve(self, state, params, settings) -> Any:
+        '''Update parameters and solve (called each iteration).'''
+        ...
+```
+
+The Penalized Trust-Region (PTR) subproblem ships with two concrete backends:
+
+- :class:`CVXPyPTRSolver` — DCP graph via CVXPy, dispatched to any of its
+  supported conic solvers (QOCO, CLARABEL, ...). Optional code generation
+  via cvxpygen for improved per-iteration performance.
+- :class:`QPAXPTRSolver` — flat ``(Q, q, A, b, G, h)`` assembled as JAX
+  arrays and solved with ``qpax.solve_qp``. Aimed at end-to-end JAX
+  differentiability of the SCP loop (follow-up work).
+
+Both share the abstract :class:`PTRSolver` contract.
+
+Note:
+    Solvers own their optimization variables (e.g., ``CVXPySolver.ocp_vars``).
+    The lowering process calls ``solver.create_variables()`` before constraint
+    lowering, then ``solver.initialize()`` after. See :mod:`openscvx.solvers.base`
+    for the interface details.
+"""
+
+import warnings
+from typing import Any
+
+from .base import ConvexSolver, PTRSolverSpec
+from .cvxpy_ptr_solver import CVXPyPTRSolver
+from .ptr_solver import PTRSolver, PTRSolveResult
+
+
+def resolve_solver_config(val: Any) -> PTRSolverSpec:
+    """Validate a dict / Spec into a :class:`PTRSolverSpec` instance."""
+    if isinstance(val, PTRSolverSpec):
+        return val
+    return PTRSolverSpec.model_validate(val)
+
+
+def __getattr__(name: str):
+    """Deprecated alias: ``SolverSpec`` → :class:`PTRSolverSpec`."""
+    if name == "SolverSpec":
+        warnings.warn(
+            "openscvx.solvers.SolverSpec is deprecated; use PTRSolverSpec.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return PTRSolverSpec
+    if name == "QPAXPTRSolver":
+        # Lazy import so users without the qpax extra don't pay a hard
+        # ImportError just for `from openscvx.solvers import QPAXPTRSolver`
+        # — the import error gets deferred to instantiation time, where the
+        # error message points at the install command.
+        from .qpax_ptr_solver import QPAXPTRSolver
+
+        return QPAXPTRSolver
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Base classes
+    "ConvexSolver",
+    "PTRSolver",
+    "PTRSolveResult",
+    # PTR backends
+    "CVXPyPTRSolver",
+    "QPAXPTRSolver",
+    # Config
+    "PTRSolverSpec",
+    "resolve_solver_config",
+]