openscvx 0.5.2.dev13__tar.gz → 0.5.2.dev14__tar.gz

{openscvx-0.5.2.dev13/openscvx.egg-info → openscvx-0.5.2.dev14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.5.2.dev13
+Version: 0.5.2.dev14
 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.2.dev13 → openscvx-0.5.2.dev14}/openscvx/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.2.dev13'
-__version_tuple__ = version_tuple = (0, 5, 2, 'dev13')
+__version__ = version = '0.5.2.dev14'
+__version_tuple__ = version_tuple = (0, 5, 2, 'dev14')
 
-__commit_id__ = commit_id = 'ga445685bf'
+__commit_id__ = commit_id = 'g78ea9d746'

{openscvx-0.5.2.dev13 → openscvx-0.5.2.dev14}/openscvx/solvers/base.py

@@ -281,9 +281,24 @@ class PTRSolverSpec(BaseModel):
     or ``"moreau"``
     (:class:`openscvx.solvers.moreau_ptr_solver.MoreauPTRSolver`).
 
-    ``cvx_solver``, ``cvxpygen``, and ``cvxpygen_override`` are CVXPy-only;
-    setting them under ``backend="qpax"`` or ``backend="moreau"`` is a
-    configuration error.
+    Backend-specific fields mirror the constructor parameters of each class.
+    Fields that don't belong to the active backend are a configuration error
+    and raise ``ValidationError``.
+
+    CVXPy-only:
+        ``cvx_solver``, ``cvxpygen``, ``cvxpygen_override``.
+
+    QPAX-only:
+        ``solver_tol``.
+
+    Moreau-only:
+        ``verbose``, ``device``, ``tol_gap_abs``, ``tol_feas``.
+
+    Shared between QPAX and Moreau:
+        ``max_iter``.
+
+    All backends:
+        ``solver_args`` (escape hatch for settings not covered by named fields).
 
     !!! warning
         Enabling ``cvxpygen`` currently disables sparse parameter declarations.
@@ -294,11 +309,27 @@ class PTRSolverSpec(BaseModel):
 
     type: Literal["PTRSolver"] = "PTRSolver"
     backend: Literal["cvxpy", "qpax", "moreau"] = "cvxpy"
+
+    # CVXPy-only
     cvx_solver: Optional[str] = None
-    solver_args: Optional[Dict[str, Any]] = None
     cvxpygen: bool = False
     cvxpygen_override: bool = False
 
+    # QPAX-specific
+    solver_tol: Optional[float] = None
+
+    # Shared between QPAX and Moreau
+    max_iter: Optional[int] = None
+
+    # Moreau-specific
+    verbose: Optional[bool] = None
+    device: Optional[str] = None
+    tol_gap_abs: Optional[float] = None
+    tol_feas: Optional[float] = None
+
+    # Escape hatch for all backends
+    solver_args: Optional[Dict[str, Any]] = None
+
     model_config = ConfigDict(extra="forbid")
 
     @model_validator(mode="after")
@@ -318,6 +349,45 @@ class PTRSolverSpec(BaseModel):
                     f"{offenders} only valid for backend='cvxpy'; "
                     "remove these fields or set backend='cvxpy'."
                 )
+        if self.backend == "cvxpy":
+            offenders = [
+                name
+                for name, value in (
+                    ("solver_tol", self.solver_tol),
+                    ("max_iter", self.max_iter),
+                    ("verbose", self.verbose),
+                    ("device", self.device),
+                    ("tol_gap_abs", self.tol_gap_abs),
+                    ("tol_feas", self.tol_feas),
+                )
+                if value is not None
+            ]
+            if offenders:
+                raise ValueError(
+                    f"{offenders} not valid for backend='cvxpy'; pass these "
+                    "via solver_args or switch to the qpax / moreau backend."
+                )
+        if self.backend == "qpax":
+            offenders = [
+                name
+                for name, value in (
+                    ("verbose", self.verbose),
+                    ("device", self.device),
+                    ("tol_gap_abs", self.tol_gap_abs),
+                    ("tol_feas", self.tol_feas),
+                )
+                if value is not None
+            ]
+            if offenders:
+                raise ValueError(
+                    f"{offenders} only valid for backend='moreau'; "
+                    "remove these fields or set backend='moreau'."
+                )
+        if self.backend == "moreau" and self.solver_tol is not None:
+            raise ValueError(
+                "solver_tol is only valid for backend='qpax'; "
+                "remove this field or set backend='qpax'."
+            )
         return self
 
     def build(self) -> ConvexSolver:
@@ -335,10 +405,31 @@ class PTRSolverSpec(BaseModel):
         if self.backend == "moreau":
             from .moreau_ptr_solver import MoreauPTRSolver
 
-            return MoreauPTRSolver(solver_args=self.solver_args)
+            kwargs: Dict[str, Any] = {}
+            if self.max_iter is not None:
+                kwargs["max_iter"] = self.max_iter
+            if self.verbose is not None:
+                kwargs["verbose"] = self.verbose
+            if self.device is not None:
+                kwargs["device"] = self.device
+            if self.tol_gap_abs is not None:
+                kwargs["tol_gap_abs"] = self.tol_gap_abs
+            if self.tol_feas is not None:
+                kwargs["tol_feas"] = self.tol_feas
+            if self.solver_args is not None:
+                kwargs["solver_args"] = self.solver_args
+            return MoreauPTRSolver(**kwargs)
+
         from .qpax_ptr_solver import QPAXPTRSolver
 
-        return QPAXPTRSolver(solver_args=self.solver_args)
+        kwargs = {}
+        if self.solver_tol is not None:
+            kwargs["solver_tol"] = self.solver_tol
+        if self.max_iter is not None:
+            kwargs["max_iter"] = self.max_iter
+        if self.solver_args is not None:
+            kwargs["solver_args"] = self.solver_args
+        return QPAXPTRSolver(**kwargs)
 
 
 def __getattr__(name: str):

{openscvx-0.5.2.dev13 → openscvx-0.5.2.dev14}/openscvx/solvers/moreau_ptr_solver.py

@@ -241,24 +241,75 @@ class MoreauPTRSolver(PTRSolver):
         through a full SCvx solve.
 
     Args:
-        solver_args: Keyword arguments forwarded to :class:`moreau.Settings`.
-            Useful keys include ``max_iter`` (default 200), ``verbose``
-            (default False), ``device`` (``'auto'``, ``'cpu'``, or
-            ``'cuda'``), and a nested ``ipm_settings`` dict for IPM tolerances
-            (e.g. ``{"tol_gap_abs": 1e-8, "tol_feas": 1e-8}``).
+        max_iter: Maximum number of IPM iterations forwarded to
+            :class:`moreau.Settings`. Defaults to ``200``.
+        verbose: Whether Moreau prints per-iteration diagnostics.
+            Forwarded to :class:`moreau.Settings`. Defaults to ``False``.
+        device: Compute device for Moreau's JAX kernels. One of
+            ``"auto"``, ``"cpu"``, or ``"cuda"``. Forwarded to
+            :class:`moreau.Settings`. Defaults to ``"auto"``.
+        tol_gap_abs: Absolute duality-gap tolerance forwarded to
+            :class:`moreau.IPMSettings`. ``None`` uses Moreau's default.
+        tol_feas: Primal/dual feasibility tolerance forwarded to
+            :class:`moreau.IPMSettings`. ``None`` uses Moreau's default.
+        solver_args: Additional keyword arguments forwarded verbatim to
+            :class:`moreau.Settings`. Use for settings not covered by the
+            named params above. ``solver_args["ipm_settings"]`` may be a
+            dict or a :class:`moreau.IPMSettings` object; if it is a dict,
+            ``tol_gap_abs`` / ``tol_feas`` are merged into it. Raises
+            ``ValueError`` at construction time if any top-level key or
+            IPM tolerance overlaps with a named param.
 
     Attributes:
         layout: :class:`_ConicLayout` describing flat decision-vector slot
             ranges. Populated by :meth:`create_variables`.
     """
 
-    def __init__(self, solver_args: Optional[Dict] = None):
+    def __init__(
+        self,
+        *,
+        max_iter: int = 200,
+        verbose: bool = False,
+        device: str = "auto",
+        tol_gap_abs: Optional[float] = None,
+        tol_feas: Optional[float] = None,
+        solver_args: Optional[Dict] = None,
+    ):
         if not _MOREAU_AVAILABLE:
             raise ImportError(
                 "MoreauPTRSolver requires the `moreau` package. "
                 "Install it with: pip install openscvx[moreau]"
             )
-        self.solver_args = dict(solver_args) if solver_args else {}
+
+        _named = {"max_iter": max_iter, "verbose": verbose, "device": device}
+        _extra = dict(solver_args) if solver_args else {}
+        _overlap = _named.keys() & _extra.keys()
+        if _overlap:
+            raise ValueError(
+                f"Moreau settings {sorted(_overlap)} appear as both named arguments "
+                "and inside solver_args; use one or the other."
+            )
+        merged = {**_named, **_extra}
+
+        _ipm = {
+            k: v for k, v in [("tol_gap_abs", tol_gap_abs), ("tol_feas", tol_feas)] if v is not None
+        }
+        if _ipm:
+            existing_ipm = merged.get("ipm_settings", {})
+            if not isinstance(existing_ipm, dict):
+                raise ValueError(
+                    "Cannot combine tol_gap_abs / tol_feas named arguments with an "
+                    "ipm_settings object in solver_args; use one form or the other."
+                )
+            ipm_overlap = _ipm.keys() & existing_ipm.keys()
+            if ipm_overlap:
+                raise ValueError(
+                    f"Moreau IPM settings {sorted(ipm_overlap)} appear as both named "
+                    "arguments and inside solver_args['ipm_settings']; use one or the other."
+                )
+            merged["ipm_settings"] = {**_ipm, **existing_ipm}
+
+        self.solver_args = merged
 
         self.layout: Optional[_ConicLayout] = None
         self._S_x: Optional[np.ndarray] = None

{openscvx-0.5.2.dev13 → openscvx-0.5.2.dev14}/openscvx/solvers/qpax_ptr_solver.py

@@ -177,25 +177,44 @@ class QPAXPTRSolver(PTRSolver):
         what lets ``jax.grad`` / ``jax.vmap`` reach through a full SCvx solve.
 
     Args:
-        solver_args: Keyword arguments forwarded to ``qpax.solve_qp``. Useful
-            keys include ``solver_tol`` (default ``1e-5``), ``max_iter``
-            (default ``30``), ``linear_solver``, and ``backend`` (``"i"`` for
-            implicit retraction-manifold PDIP — qpax's default — or ``"e"``
-            for the explicit predictor-corrector path).
+        solver_tol: Convergence tolerance forwarded to ``qpax.solve_qp``
+            as ``solver_tol``. Defaults to ``1e-5``.
+        max_iter: Maximum number of PDIP iterations forwarded to
+            ``qpax.solve_qp`` as ``max_iter``. Defaults to ``30``.
+        solver_args: Additional keyword arguments forwarded verbatim to
+            ``qpax.solve_qp``. Use for settings not covered by the named
+            params above — e.g. ``backend="e"`` for the explicit
+            predictor-corrector path, or ``linear_solver``. Raises
+            ``ValueError`` at construction time if any key overlaps with a
+            named param.
 
     Attributes:
         layout: ``_QPLayout`` describing the flat decision-vector slot ranges.
             Populated by :meth:`create_variables`.
     """
 
-    def __init__(self, solver_args: Optional[dict] = None):
+    def __init__(
+        self,
+        *,
+        solver_tol: float = 1e-5,
+        max_iter: int = 30,
+        solver_args: Optional[dict] = None,
+    ):
         if not _QPAX_AVAILABLE:
             raise ImportError(
                 "QPAXPTRSolver requires the `qpax` package. "
                 "Install it with: pip install openscvx[qpax]"
             )
 
-        self.solver_args = dict(solver_args) if solver_args else {}
+        _named = {"solver_tol": solver_tol, "max_iter": max_iter}
+        _extra = dict(solver_args) if solver_args else {}
+        _overlap = _named.keys() & _extra.keys()
+        if _overlap:
+            raise ValueError(
+                f"QPAX settings {sorted(_overlap)} appear as both named arguments "
+                "and inside solver_args; use one or the other."
+            )
+        self.solver_args = {**_named, **_extra}
 
         # Populated by create_variables / initialize.
         self.layout: Optional[_QPLayout] = None

{openscvx-0.5.2.dev13 → openscvx-0.5.2.dev14/openscvx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.5.2.dev13
+Version: 0.5.2.dev14
 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.2.dev13 → openscvx-0.5.2.dev14}/tests/solvers/test_moreau_ptr_solver.py

@@ -122,6 +122,81 @@ def test_moreau_spec_build_returns_moreau_solver():
     assert isinstance(solver, MoreauPTRSolver)
 
 
+def test_moreau_named_params_populate_solver_args():
+    """Named constructor params should be merged into solver_args so
+    _build_moreau_settings picks them up unchanged."""
+    solver = MoreauPTRSolver(max_iter=500, verbose=True, device="cpu")
+    assert solver.solver_args["max_iter"] == 500
+    assert solver.solver_args["verbose"] is True
+    assert solver.solver_args["device"] == "cpu"
+
+
+def test_moreau_ipm_tolerances_nest_into_ipm_settings():
+    """tol_gap_abs and tol_feas should be folded into solver_args['ipm_settings']
+    so _build_moreau_settings receives them in the expected nested location."""
+    solver = MoreauPTRSolver(tol_gap_abs=1e-10, tol_feas=1e-10)
+    assert solver.solver_args["ipm_settings"] == {"tol_gap_abs": 1e-10, "tol_feas": 1e-10}
+
+
+def test_moreau_ipm_tolerances_merge_with_solver_args_ipm_settings():
+    """Named IPM tolerance params should merge with a dict inside solver_args
+    rather than silently overwriting it."""
+    solver = MoreauPTRSolver(
+        tol_gap_abs=1e-10,
+        solver_args={"ipm_settings": {"tol_feas": 1e-9}},
+    )
+    assert solver.solver_args["ipm_settings"]["tol_gap_abs"] == 1e-10
+    assert solver.solver_args["ipm_settings"]["tol_feas"] == 1e-9
+
+
+def test_moreau_named_param_overlap_with_solver_args_raises():
+    """Passing the same top-level key as a named arg and inside solver_args
+    should raise immediately."""
+    with pytest.raises(ValueError, match="max_iter"):
+        MoreauPTRSolver(max_iter=200, solver_args={"max_iter": 100})
+
+    with pytest.raises(ValueError, match="device"):
+        MoreauPTRSolver(device="cpu", solver_args={"device": "cuda"})
+
+
+def test_moreau_ipm_overlap_with_solver_args_ipm_settings_raises():
+    """A named IPM tolerance and the same key inside solver_args['ipm_settings']
+    is a user error and should raise."""
+    with pytest.raises(ValueError, match="tol_gap_abs"):
+        MoreauPTRSolver(
+            tol_gap_abs=1e-10,
+            solver_args={"ipm_settings": {"tol_gap_abs": 1e-8}},
+        )
+
+
+def test_moreau_spec_named_fields_build_correctly():
+    """PTRSolverSpec with Moreau named fields should build a MoreauPTRSolver
+    with the right solver_args."""
+    from openscvx.solvers import resolve_solver_config
+
+    spec = resolve_solver_config(
+        {
+            "backend": "moreau",
+            "max_iter": 300,
+            "device": "cpu",
+            "tol_gap_abs": 1e-10,
+        }
+    )
+    solver = spec.build()
+    assert isinstance(solver, MoreauPTRSolver)
+    assert solver.solver_args["max_iter"] == 300
+    assert solver.solver_args["device"] == "cpu"
+    assert solver.solver_args["ipm_settings"]["tol_gap_abs"] == 1e-10
+
+
+def test_moreau_spec_rejects_qpax_only_fields():
+    """solver_tol (QPAX-only) must not be accepted under backend='moreau'."""
+    from openscvx.solvers import resolve_solver_config
+
+    with pytest.raises(ValueError, match="solver_tol"):
+        resolve_solver_config({"backend": "moreau", "solver_tol": 1e-8})
+
+
 # ============================================================================
 # Unsupported-feature rejection tests
 # ============================================================================

{openscvx-0.5.2.dev13 → openscvx-0.5.2.dev14}/tests/solvers/test_qpax_ptr_solver.py

@@ -109,6 +109,77 @@ def test_qpax_spec_rejects_cvxpy_only_fields():
         resolve_solver_config({"backend": "qpax", "cvx_solver": "CLARABEL"})
 
 
+def test_qpax_named_params_populate_solver_args():
+    """Named constructor params should be merged into solver_args so the
+    existing qpax.solve_qp(**self.solver_args) dispatch picks them up."""
+    solver = QPAXPTRSolver(solver_tol=1e-8, max_iter=50)
+    assert solver.solver_args["solver_tol"] == 1e-8
+    assert solver.solver_args["max_iter"] == 50
+
+
+def test_qpax_named_param_overlap_with_solver_args_raises():
+    """Passing the same key as a named arg and inside solver_args is a user
+    error — the constructor should raise immediately rather than silently
+    discarding one value."""
+    with pytest.raises(ValueError, match="solver_tol"):
+        QPAXPTRSolver(solver_tol=1e-8, solver_args={"solver_tol": 1e-7})
+
+    with pytest.raises(ValueError, match="max_iter"):
+        QPAXPTRSolver(max_iter=50, solver_args={"max_iter": 100})
+
+
+def test_qpax_solver_args_escape_hatch():
+    """Keys not covered by named params (e.g. backend='e') should pass
+    through the solver_args escape hatch unchanged."""
+    solver = QPAXPTRSolver(solver_tol=1e-6, solver_args={"backend": "e"})
+    assert solver.solver_args["backend"] == "e"
+    assert solver.solver_args["solver_tol"] == 1e-6
+
+
+def test_qpax_spec_named_fields_build_correctly():
+    """PTRSolverSpec with QPAX named fields should build a QPAXPTRSolver
+    with the right solver_args."""
+    from openscvx.solvers import QPAXPTRSolver, resolve_solver_config
+
+    spec = resolve_solver_config({"backend": "qpax", "solver_tol": 1e-8, "max_iter": 75})
+    solver = spec.build()
+    assert isinstance(solver, QPAXPTRSolver)
+    assert solver.solver_args["solver_tol"] == 1e-8
+    assert solver.solver_args["max_iter"] == 75
+
+
+def test_qpax_spec_rejects_moreau_only_fields():
+    """Moreau-specific fields (verbose, device, tol_gap_abs, tol_feas) must
+    not be accepted under backend='qpax'."""
+    from openscvx.solvers import resolve_solver_config
+
+    with pytest.raises(ValueError, match="only valid for backend='moreau'"):
+        resolve_solver_config({"backend": "qpax", "verbose": True})
+
+    with pytest.raises(ValueError, match="only valid for backend='moreau'"):
+        resolve_solver_config({"backend": "qpax", "tol_gap_abs": 1e-10})
+
+
+def test_qpax_spec_rejects_solver_tol_under_moreau():
+    """solver_tol must not be accepted under backend='moreau'."""
+    from openscvx.solvers import resolve_solver_config
+
+    with pytest.raises(ValueError, match="solver_tol"):
+        resolve_solver_config({"backend": "moreau", "solver_tol": 1e-8})
+
+
+def test_cvxpy_spec_rejects_jax_backend_fields():
+    """QPAX/Moreau named fields (solver_tol, max_iter, verbose, device, …)
+    must not be accepted under backend='cvxpy'."""
+    from openscvx.solvers import resolve_solver_config
+
+    with pytest.raises(ValueError, match="not valid for backend='cvxpy'"):
+        resolve_solver_config({"backend": "cvxpy", "solver_tol": 1e-8})
+
+    with pytest.raises(ValueError, match="not valid for backend='cvxpy'"):
+        resolve_solver_config({"backend": "cvxpy", "max_iter": 100})
+
+
 # ============================================================================
 # Unsupported-feature rejection tests
 # ============================================================================