openscvx 0.3.2.dev127__tar.gz → 0.3.2.dev143__tar.gz

{openscvx-0.3.2.dev127 → openscvx-0.3.2.dev143}/CONTRIBUTING.md

@@ -178,3 +178,36 @@ While we do not strictly follow [test driven development (TDD)](https://en.wikip
 For example, the [symbolic-expression layer](openscvx/symbolic/__init__.py) is well covered by [tests](tests/symbolic/) which were written simultaneously with the symbolic layer.
 
 The extensive test suite helps ensure that new features and refactors don't break existing functionality.
+
+#### Documentation
+
+We use [MkDocs](https://www.mkdocs.org/) with [Material](https://squidfunk.github.io/mkdocs-material/) theme for documentation, hosted at [haynec.github.io/OpenSCvx](https://haynec.github.io/OpenSCvx/).
+
+API reference is auto-generated from docstrings using [mkdocstrings](https://mkdocstrings.github.io/). Please use [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) for all public functions and classes:
+
+```python
+def solve(self, max_iterations: int = 100) -> OptimizationResult:
+    """Solve the trajectory optimization problem.
+
+    Args:
+        max_iterations: Maximum number of SCP iterations.
+
+    Returns:
+        The optimization result containing the trajectory and convergence info.
+
+    Raises:
+        ConvergenceError: If the solver fails to converge.
+    """
+```
+
+To preview documentation locally, first install the dependencies:
+
+```bash
+pip install mkdocs-material mkdocstrings-python mkdocs-gen-files mkdocs-literate-nav mkdocs-section-index
+```
+
+Then serve the documentation locally:
+
+```bash
+mkdocs serve
+```

{openscvx-0.3.2.dev127/openscvx.egg-info → openscvx-0.3.2.dev143}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.3.2.dev127
+Version: 0.3.2.dev143
 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.3.2.dev127 → openscvx-0.3.2.dev143}/openscvx/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.3.2.dev127'
-__version_tuple__ = version_tuple = (0, 3, 2, 'dev127')
+__version__ = version = '0.3.2.dev143'
+__version_tuple__ = version_tuple = (0, 3, 2, 'dev143')
 
-__commit_id__ = commit_id = 'g580ea58cc'
+__commit_id__ = commit_id = 'gfab08d1d7'

openscvx-0.3.2.dev143/openscvx/algorithms/__init__.py

@@ -0,0 +1,92 @@
+"""Successive convexification algorithms for trajectory optimization.
+
+This module provides implementations of SCvx (Successive Convexification) algorithms
+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:
+
+```python
+class Algorithm(ABC):
+    @abstractmethod
+    def initialize(self, ocp, discretization_solver, jax_constraints,
+                   solve_ocp, emitter, params, settings) -> None:
+        '''Store compiled infrastructure and warm-start solvers.'''
+        ...
+
+    @abstractmethod
+    def step(self, state, params, settings) -> bool:
+        '''Execute one iteration using stored infrastructure.'''
+        ...
+```
+
+Immutable components (ocp, discretization_solver, jax_constraints, etc.) are stored
+during ``initialize()``. Mutable configuration (params, settings) is passed per-step
+to support runtime parameter updates and tolerance tuning.
+
+:class:`AlgorithmState` holds mutable state during SCP iterations. Algorithms
+that require additional state can subclass it:
+
+```python
+@dataclass
+class MyAlgorithmState(AlgorithmState):
+    my_custom_field: float = 0.0
+```
+
+Note:
+    ``AlgorithmState`` currently combines iteration metrics (costs, weights),
+    trajectory history, and discretization data. A future refactor may separate
+    these concerns into distinct classes for clearer data flow:
+
+    ```python
+    @dataclass
+    class AlgorithmState:
+        # Mutable iteration state
+        k: int
+        J_tr: float
+        J_vb: float
+        J_vc: float
+        w_tr: float
+        lam_cost: float
+        lam_vc: ...
+        lam_vb: float
+
+    @dataclass
+    class TrajectoryHistory:
+        # Accumulated trajectory solutions
+        X: List[np.ndarray]
+        U: List[np.ndarray]
+
+        @property
+        def x(self): return self.X[-1]
+
+        @property
+        def u(self): return self.U[-1]
+
+    @dataclass
+    class DebugHistory:
+        # Optional diagnostic data (discretization matrices, etc.)
+        V_history: List[np.ndarray]
+        VC_history: List[np.ndarray]
+        TR_history: List[np.ndarray]
+    ```
+
+Current Implementations:
+
+- :class:`PenalizedTrustRegion`: Penalized Trust Region (PTR) algorithm
+"""
+
+from .base import Algorithm, AlgorithmState
+from .optimization_results import OptimizationResults
+from .penalized_trust_region import PenalizedTrustRegion
+
+__all__ = [
+    # Base class
+    "Algorithm",
+    "AlgorithmState",
+    # Core results
+    "OptimizationResults",
+    # PTR algorithm
+    "PenalizedTrustRegion",
+]

{openscvx-0.3.2.dev127 → openscvx-0.3.2.dev143}/openscvx/algorithms/autotuning.py

@@ -5,10 +5,10 @@ from typing import TYPE_CHECKING
 from openscvx.config import Config
 
 if TYPE_CHECKING:
-    from .solver_state import SolverState
+    from .base import AlgorithmState
 
 
-def update_scp_weights(state: "SolverState", settings: Config, scp_k: int):
+def update_scp_weights(state: "AlgorithmState", settings: Config, scp_k: int):
     """Update SCP weights and cost parameters based on iteration number.
 
     Args:

openscvx-0.3.2.dev127/openscvx/algorithms/solver_state.py → openscvx-0.3.2.dev143/openscvx/algorithms/base.py

@@ -1,22 +1,25 @@
-"""Solver state management for SCP iterations.
+"""Base class for successive convexification algorithms.
 
-This module contains the SolverState dataclass that holds all mutable state
-during successive convex programming iterations. By separating solver state
-from problem definition, we enable clean reset() functionality and prevent
-accidental mutation of initial conditions.
+This module defines the abstract interface that all SCP algorithm implementations
+must follow, along with the AlgorithmState dataclass that holds mutable state
+during SCP iterations.
 """
 
+from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, List, Union
 
 import numpy as np
 
 if TYPE_CHECKING:
+    import cvxpy as cp
+
     from openscvx.config import Config
+    from openscvx.lowered.jax_constraints import LoweredJaxConstraints
 
 
 @dataclass
-class SolverState:
+class AlgorithmState:
     """Mutable state for SCP iterations.
 
     This dataclass holds all state that changes during the solve process.
@@ -200,8 +203,8 @@ class SolverState:
         return V_final[:, i3:i4].reshape(self.N - 1, self.n_x, self.n_u)
 
     @classmethod
-    def from_settings(cls, settings: "Config") -> "SolverState":
-        """Create initial solver state from configuration.
+    def from_settings(cls, settings: "Config") -> "AlgorithmState":
+        """Create initial algorithm state from configuration.
 
         Copies only the trajectory arrays from settings, leaving all metadata
         (bounds, boundary conditions, etc.) in the original settings object.
@@ -210,7 +213,7 @@ class SolverState:
             settings: Configuration object containing initial guesses and SCP parameters
 
         Returns:
-            Fresh SolverState initialized from settings with copied arrays
+            Fresh AlgorithmState initialized from settings with copied arrays
         """
         return cls(
             k=1,
@@ -230,3 +233,119 @@ class SolverState:
             VC_history=[],
             TR_history=[],
         )
+
+
+class Algorithm(ABC):
+    """Abstract base class for successive convexification algorithms.
+
+    This class defines the interface for SCP algorithms used in trajectory
+    optimization. Implementations should remain minimal and functional,
+    delegating state management to the AlgorithmState dataclass.
+
+    The two core methods mirror the SCP workflow:
+
+    - initialize: Store compiled infrastructure and warm-start solvers
+    - step: Execute one convex subproblem iteration
+
+    Immutable components (ocp, discretization_solver, jax_constraints, etc.) are
+    stored during initialize(). Mutable configuration (params, settings) is passed
+    per-step to support runtime parameter updates and tolerance tuning.
+
+    !!! tip "Statefullness"
+        Avoid storing mutable iteration state (costs, weights, trajectories) on
+        ``self``. All iteration state should live in :class:`AlgorithmState` or
+        a subclass thereof, passed explicitly to ``step()``. This keeps algorithm
+        classes stateless w.r.t. iteration, making data flow explicit and staying
+        close to functional programming principles where possible.
+
+    Example:
+        Implementing a custom algorithm::
+
+            class MyAlgorithm(Algorithm):
+                def initialize(self, ocp, discretization_solver,
+                               jax_constraints, solve_ocp, emitter,
+                               params, settings):
+                    # Store compiled infrastructure
+                    self._ocp = ocp
+                    self._discretization_solver = discretization_solver
+                    self._jax_constraints = jax_constraints
+                    self._solve_ocp = solve_ocp
+                    self._emitter = emitter
+                    # Warm-start with initial params/settings...
+
+                def step(self, state, params, settings):
+                    # Run one iteration using self._* and per-step params/settings
+                    return converged
+    """
+
+    @abstractmethod
+    def initialize(
+        self,
+        ocp: "cp.Problem",
+        discretization_solver: callable,
+        jax_constraints: "LoweredJaxConstraints",
+        solve_ocp: callable,
+        emitter: callable,
+        params: dict,
+        settings: "Config",
+    ) -> None:
+        """Initialize the algorithm and store compiled infrastructure.
+
+        This method stores immutable components and performs any setup required
+        before the SCP loop begins (e.g., warm-starting solvers). The params and
+        settings are passed for warm-start but may change between steps.
+
+        Args:
+            ocp: The CVXPy optimal control problem
+            discretization_solver: Compiled discretization solver function
+            jax_constraints: JIT-compiled JAX constraint functions
+            solve_ocp: Callable that solves the OCP (captures solver config)
+            emitter: Callback for emitting iteration progress data
+            params: Problem parameters dictionary (for warm-start only)
+            settings: Configuration object (for warm-start only)
+        """
+        ...
+
+    @abstractmethod
+    def step(
+        self,
+        state: AlgorithmState,
+        params: dict,
+        settings: "Config",
+    ) -> bool:
+        """Execute one iteration of the SCP algorithm.
+
+        This method solves a single convex subproblem, updates the algorithm
+        state in place, and returns whether convergence criteria are met.
+
+        Uses stored infrastructure (ocp, discretization_solver, etc.) with
+        per-step params and settings to support runtime modifications.
+
+        Args:
+            state: Mutable algorithm state (modified in place)
+            params: Problem parameters dictionary (may change between steps)
+            settings: Configuration object (may change between steps)
+
+        Returns:
+            True if convergence criteria are satisfied, False otherwise.
+        """
+        ...
+
+    @abstractmethod
+    def citation(self) -> List[str]:
+        """Return BibTeX citations for this algorithm.
+
+        Implementations should return a list of BibTeX entry strings for the
+        papers that should be cited when using this algorithm.
+
+        Returns:
+            List of BibTeX citation strings.
+
+        Example:
+            Getting citations for an algorithm::
+
+                algorithm = PenalizedTrustRegion()
+                for bibtex in algorithm.citation():
+                    print(bibtex)
+        """
+        ...