openscvx 0.5.2.dev1__tar.gz → 0.5.2.dev11__tar.gz

{openscvx-0.5.2.dev1 → openscvx-0.5.2.dev11}/.github/workflows/_docs.yml

@@ -12,6 +12,11 @@ jobs:
   docs:
     name: 📖 Documentation
     runs-on: ubuntu-latest
+    env:
+      # Material stderr banner (MkDocs 2.0 blog); CI uses MkDocs 1.x + --strict.
+      NO_MKDOCS_2_WARNING: "true"
+      # ProperDocs may emit a follow-up WARNING; keep --strict clean.
+      DISABLE_MKDOCS_2_WARNING: "true"
 
     steps:
     - name: Checkout repository
@@ -38,20 +43,23 @@ jobs:
     - name: Cache MkDocs build
       uses: actions/cache@v4
       with:
-        key: mkdocs-material-${{ hashFiles('mkdocs.yml', 'docs/**') }}
+        key: mkdocs-material-${{ hashFiles('mkdocs.yml', 'docs/**', 'material/overrides/**', 'scripts/gen_ref_pages.py', 'scripts/gen_example_pages.py', 'scripts/mkdocs_copy_viser_client_hook.py') }}
         path: .cache
         restore-keys: |
           mkdocs-material-
 
     - name: Install system dependencies
-      run: sudo apt-get update && sudo apt-get install -y pngquant
+      run: >-
+        sudo apt-get update &&
+        sudo apt-get install -y pngquant libcairo2-dev libfreetype6-dev libffi-dev
+        libjpeg-dev libpng-dev zlib1g-dev
 
     # - name: Install MkDocs Material Insiders
     #   run: uv pip install --system git+https://${{ secrets.MKDOCS_INSIDERS_TOKEN }}@github.com/squidfunk/mkdocs-material-insiders.git
 
     - name: Install documentation tools
       run: |
-        uv pip install --system mkdocs-material mkdocstrings-python
+        uv pip install --system "mkdocs-material[imaging]" mkdocstrings-python
         uv pip install --system mkdocs-gen-files mkdocs-literate-nav mkdocs-section-index
         uv pip install --system mike
 

{openscvx-0.5.2.dev1 → openscvx-0.5.2.dev11}/.gitignore

@@ -209,7 +209,15 @@ check_lint.py
 MUJOCO_LOG.TXT
 
 # MkDocs Material Insiders (installed from GitHub in CI, not committed)
-material/
-# But allow custom overrides to be committed
+# Ignore contents of material/ but not material/overrides/ (Git cannot un-ignore
+# paths inside an ignored directory when the rule is material/).
+material/*
 !material/overrides/
+!material/overrides/**
 src/
+
+# SPICE kernels for spacecrafts examples
+examples/spacecraft/ker/
+
+# Solver_data folder
+solver_data/

{openscvx-0.5.2.dev1 → openscvx-0.5.2.dev11}/CONTRIBUTING.md

@@ -20,7 +20,6 @@ pip install -e ".[test]"
 ```
 
 For additional features, you can install optional dependencies:
-- `pip install -e ".[gui]"` - GUI visualization tools
 - `pip install -e ".[cvxpygen]"` - Code generation support
 - `pip install -e ".[stl]"` - STL (Signal Temporal Logic) constraints
 
@@ -204,11 +203,17 @@ def solve(self, max_iterations: int = 100) -> OptimizationResult:
 To preview documentation locally, first install the dependencies:
 
 ```bash
-pip install mkdocs-material mkdocstrings-python mkdocs-gen-files mkdocs-literate-nav mkdocs-section-index
+pip install "mkdocs-material[imaging]" mkdocstrings-python mkdocs-gen-files mkdocs-literate-nav mkdocs-section-index
 ```
 
+The `social` plugin (enabled in `mkdocs.yml`) uses **CairoSVG**, which loads the native **Cairo** library. A `pip`-only `cairosvg` on macOS often cannot find `libcairo` and will spam warnings during `mkdocs build` / `mkdocs serve`. Install Cairo into the same environment (for example `conda install -c conda-forge cairo cairosvg`) or install Cairo via Homebrew so the dynamic linker can resolve it. Uninstalling `cairosvg` does not silence the build: the plugin will warn on every page that imaging dependencies are missing.
+
 Then serve the documentation locally:
 
 ```bash
 mkdocs serve
 ```
+
+To silence MkDocs 2.0 / ProperDocs notices when building with **`--strict`**, set **`NO_MKDOCS_2_WARNING=true`** (Material’s stderr banner) and, if you use ProperDocs, **`DISABLE_MKDOCS_2_WARNING=true`** for the pip-style WARNING; the documentation workflow sets both for CI.
+
+The version dropdown uses Material’s **mike** integration and expects a `versions.json` at the site root. Plain `mkdocs serve` does not run `mike deploy`, so the repo includes a minimal **`docs/versions.json`** (copied into the build) to avoid a 404 in local previews. On **GitHub Pages**, CI replaces the published root with **`mike deploy`**, which writes the real multi-version manifest. To preview multiple versions locally the same way as production, use **`mike serve`** after you have a `gh-pages` branch with deployed versions.

{openscvx-0.5.2.dev1/openscvx.egg-info → openscvx-0.5.2.dev11}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.5.2.dev1
+Version: 0.5.2.dev11
 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
-Project-URL: Homepage, https://openscvx.github.io/openscvx/
+Project-URL: Homepage, https://openscvx.github.io/OpenSCvx/
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: Apache Software License
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cvxpy>=1.8.1
@@ -23,15 +23,13 @@ Requires-Dist: viser
 Requires-Dist: matplotlib
 Requires-Dist: pyyaml
 Requires-Dist: pydantic>=2.0
-Provides-Extra: gui
-Requires-Dist: pyqtgraph; extra == "gui"
-Requires-Dist: PyQt5; extra == "gui"
-Requires-Dist: scipy; extra == "gui"
-Requires-Dist: PyOpenGL; extra == "gui"
-Requires-Dist: PyOpenGL_accelerate; extra == "gui"
 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: moreau
+Requires-Dist: moreau>=0.3.3; extra == "moreau"
 Provides-Extra: stl
 Requires-Dist: stljax; extra == "stl"
 Provides-Extra: lie
@@ -156,11 +154,11 @@ uv pip install openscvx
 ```
 
 > [!TIP]
-> **Optional Dependencies**
+> **Optional dependencies**
 >
-> For GUI support or CVXPYGen code generation:
+> For CVXPYGen code generation:
 > ```bash
-> pip install openscvx[gui,cvxpygen]
+> pip install openscvx[cvxpygen]
 > ```
 
 > [!TIP]
@@ -204,19 +202,19 @@ uv pip install -e .
 > git clone --recurse-submodules https://github.com/OpenSCvx/OpenSCvx.git
 > ```
 >
-> After a clone without submodules, initialise Menagerie whenever you need it:
+> After a clone without submodules, initialize Menagerie whenever you need it:
 >
 > ```bash
 > git submodule update --init third_party/mujoco_menagerie
 > ```
 
-## Getting Started
+## Documentation
 
-Check out the OpenSCvx documentation to help you get started
+Check out the OpenSCvx documentation:
 
-- [Getting Started Docs](https://openscvx.github.io/OpenSCvx/latest/getting-started/)
 - [Users Guide](https://openscvx.github.io/OpenSCvx/latest/UsersGuide/00_introduction/)
-- [API Reference](https://openscvx.github.io/OpenSCvx/latest/Reference/problem/)
+- [API Reference](https://openscvx.github.io/OpenSCvx/latest/Reference/)
+- [Examples overview](https://openscvx.github.io/OpenSCvx/latest/examples/)
 
 ### Running the Examples
 

{openscvx-0.5.2.dev1 → openscvx-0.5.2.dev11}/README.md

@@ -107,11 +107,11 @@ uv pip install openscvx
 ```
 
 > [!TIP]
-> **Optional Dependencies**
+> **Optional dependencies**
 >
-> For GUI support or CVXPYGen code generation:
+> For CVXPYGen code generation:
 > ```bash
-> pip install openscvx[gui,cvxpygen]
+> pip install openscvx[cvxpygen]
 > ```
 
 > [!TIP]
@@ -155,19 +155,19 @@ uv pip install -e .
 > git clone --recurse-submodules https://github.com/OpenSCvx/OpenSCvx.git
 > ```
 >
-> After a clone without submodules, initialise Menagerie whenever you need it:
+> After a clone without submodules, initialize Menagerie whenever you need it:
 >
 > ```bash
 > git submodule update --init third_party/mujoco_menagerie
 > ```
 
-## Getting Started
+## Documentation
 
-Check out the OpenSCvx documentation to help you get started
+Check out the OpenSCvx documentation:
 
-- [Getting Started Docs](https://openscvx.github.io/OpenSCvx/latest/getting-started/)
 - [Users Guide](https://openscvx.github.io/OpenSCvx/latest/UsersGuide/00_introduction/)
-- [API Reference](https://openscvx.github.io/OpenSCvx/latest/Reference/problem/)
+- [API Reference](https://openscvx.github.io/OpenSCvx/latest/Reference/)
+- [Examples overview](https://openscvx.github.io/OpenSCvx/latest/examples/)
 
 ### Running the Examples
 

{openscvx-0.5.2.dev1 → openscvx-0.5.2.dev11}/docs/UnderTheHood/lowering_architecture.md

@@ -160,9 +160,45 @@ 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. Three 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. |
+| Moreau | `MoreauPTRSolver` | `solver={"backend": "moreau"}` | JAX-native conic solver (`moreau.jax.Solver`). Sparse CSR assembly; SOC epigraphs for the L1 / pos PTR penalties (fewer variables and rows than QPAX). Warm-starts between SCP iterations. Same supported subset as QPAX. Paves the way for user `.convex()` SOC support in a follow-up. |
+
+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"})
+
+# JAX-native Moreau conic (requires the `moreau` extra: pip install openscvx[moreau]).
+problem = ox.Problem(..., solver={"backend": "moreau"})
+```
+
+Both JAX backends consume 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