openscvx 0.4.1.dev12__tar.gz → 0.4.1.dev43__tar.gz

{openscvx-0.4.1.dev12/openscvx.egg-info → openscvx-0.4.1.dev43}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.4.1.dev12
+Version: 0.4.1.dev43
 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
@@ -21,6 +21,7 @@ Requires-Dist: absl-py
 Requires-Dist: flatbuffers
 Requires-Dist: viser
 Requires-Dist: matplotlib
+Requires-Dist: pyyaml
 Provides-Extra: gui
 Requires-Dist: pyqtgraph; extra == "gui"
 Requires-Dist: PyQt5; extra == "gui"
@@ -59,248 +60,173 @@ Dynamic: license-file
 <!-- PROJECT LOGO -->
 <br />
 
-<!-- GETTING STARTED -->
-## Getting Started
+## What is OpenSCvx
 
-### Installation
+OpenSCvx is a general python-based successive convexification implementation which uses a JAX backend.
+It is designed to be easy to use for anyone and fast enough for everyone, all while being open and modular for contributors.
 
-<details>
-<summary>Stable</summary>
+OpenSCvx provides a clean symbolic interface for problem definition which should be intuitive to users of NumPy, JAX, and CVXPY. This allows us to hide a lot of the under-the-hood magic away from the user while also providing a modular architecture, enabling contributors to focus on the algorithms without worrying about interface design.
 
-To grab the latest stable release simply run
+OpenSCvx makes heavy use of [JAX](https://github.com/jax-ml/jax) to efficiently perform calculations in the successive convex programming loop through automatic differentiation, ahead-of-time (AOT) compilation, vectorization, and GPU acceleration. Behind this is a [CVXPY](https://github.com/cvxpy/cvxpy/)-based backend to solve the convex subproblems.
 
-```sh
-pip install openscvx
-```
+This is an open project and is under active development. Try it out, give us feedback, and help contribute.
 
-to install OpenSCVx in your python environment.
+```python
+import openscvx as ox
 
-Or using uv:
+g = 9.81
 
-```sh
-uv pip install openscvx
-```
+# Define states
+position = ox.State("position", shape=(2,))
+position.min = [0.0, 0.0]
+position.max = [10.0, 10.0]
+position.initial = [0.0, 10.0]
+position.final = [10.0, 5.0]
 
-For optional dependencies:
+velocity = ox.State("velocity", shape=(1,))
+velocity.min = [0.0]
+velocity.max = [10.0]
+velocity.initial = [0.0]
+velocity.final = [ox.Free(10.0)]
 
-```sh
-pip install openscvx[gui,cvxpygen]
-# or with uv
-uv pip install openscvx[gui,cvxpygen]
-```
-</details>
-
-<details>
-<summary>Nightly</summary>
+# Define control (angle from vertical)
+theta = ox.Control("theta", shape=(1,))
+theta.min = [0.0]
+theta.max = [1.755]
+theta.guess = [[0.09], [1.755]]
 
-To install the latest development version (nightly):
+# Define dynamics
+dynamics = {
+    "position": ox.Concat(
+        velocity * ox.Sin(theta),
+        -velocity * ox.Cos(theta),
+    ),
+    "velocity": g * ox.Cos(theta),
+}
 
-```sh
-pip install --pre openscvx
+constraints = []
+for state in [position, velocity]:
+    constraints.append(ox.ctcs(state <= state.max))
+    constraints.append(ox.ctcs(state.min <= state))
+
+# Build and solve
+problem = ox.Problem(
+    dynamics=dynamics,
+    constraints=constraints,
+    states=[position, velocity],
+    controls=[theta],
+    time=ox.Time(initial=0.0, final=ox.Minimize(2.0), min=0.0, max=2.0),
+    N=2,
+)
+
+
+problem.initialize()
+results = problem.solve()
+results = problem.post_process()
 ```
 
-With optional dependencies:
+## Installation
 
-```sh
-pip install --pre openscvx[gui,cvxpygen]
-```
+OpenSCvx is available on [PyPI](https://pypi.org/project/openscvx/) and can be trivially installed with pip.
 
-Or using uv:
+It is recommended to install OpenSCvx inside a virtual environment (venv, conda, uv, *etc.*). If you don't already have one set up:
 
-```sh
-uv pip install --pre openscvx
-# With optional dependencies
-uv pip install --pre openscvx[gui,cvxpygen]
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
 ```
 
-**Note:** The `--pre` flag tells pip/uv to install pre-release versions (e.g., `1.2.4.dev3`) from PyPI.
-
-Alternatively, for local development with the latest source:
-
-```sh
-# Clone the repo
-git clone https://github.com/OpenSCvx/OpenSCvx.git
-cd OpenSCvx
+### Using pip
 
-# Install in editable/development mode
-pip install -e .
-# or with uv
-uv pip install -e .
+```bash
+pip install openscvx
 ```
 
-</details>
+### Using uv
 
-### Dependencies
+If you have [uv installed](https://docs.astral.sh/uv/getting-started/installation/) you can prefix the commands with `uv` for faster installation:
 
-The main packages are:
-
-- `cvxpy` - is used to formulate and solve the convex subproblems
-- `jax` - is used for determining the Jacobians using automatic differentiation, vectorization, and ahead-of-time (AOT) compilation of the dynamics and their Jacobians 
-- `numpy` - is used for numerical operations
-- `diffrax` - is used for the numerical integration of the dynamics
-- `termcolor` - is used for pretty command line output
-- `plotly` - is used for all visualizations
-
-These will be installed automatically, but can be installed via conda or pip if you are building from source.
+```bash
+uv pip install openscvx
+```
 
-#### GUI Dependencies (Optional)
+> [!TIP]
+> **Optional Dependencies**
+>
+> For GUI support or CVXPYGen code generation:
+> ```bash
+> pip install openscvx[gui,cvxpygen]
+> ```
 
-For interactive 3D plotting and real-time visualization, additional packages are required:
+> [!TIP]
+> **Nightly Builds**
+>
+> To install the latest development version (nightly), use the `--pre` flag:
+> ```bash
+> pip install --pre openscvx
+> ```
 
-- `pyqtgraph` - is used for interactive 3D plotting and real-time visualization
-- `PyQt5` - provides the Qt5 GUI framework for pyqtgraph
-- `scipy` - is used for spatial transformations in plotting functions
-- `PyOpenGL` - provides OpenGL bindings for Python, required for 3D plotting
-- `PyOpenGL_accelerate` - (optional) speeds up PyOpenGL
+## Installing From Source
 
+### Using pip
 
-For local development:
+```bash
+git clone https://github.com/OpenSCvx/OpenSCvx.git
+cd OpenSCvx
 
-```sh
-pip install -e ".[gui]"
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
 ```
 
-#### CVXPYGen Dependencies (Optional)
-
-For code generation and faster solver performance, CVXPYGen can be installed:
-
-- `cvxpygen` - enables code generation for faster solver performance
-- `qocogen` - custom solver backend for CVXPYGen (included with cvxpygen extras)
+### Using uv
 
-To install with CVXPYGen support:
-
-```sh
-pip install openscvx[cvxpygen]
-```
-
-Or for both GUI and CVXPYGen:
+```bash
+git clone https://github.com/OpenSCvx/OpenSCvx.git
+cd OpenSCvx
 
-```sh
-pip install openscvx[gui,cvxpygen]
+uv venv
+source .venv/bin/activate
+uv pip install -e .
 ```
 
-CVXPYGen features include:
-- Automatic C++ code generation for optimization problems
-- Faster solver performance through compiled code
-- Support for custom solver backends like QOCOGen
+## Getting Started
 
-### Local Development
+Check out the OpenSCvx documentation to help you get started
 
-This git repository can be installed using https
+- [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/)
 
-```sh
-git clone https://github.com/OpenSCvx/OpenSCvx.git
-```
+### Running the Examples
 
-or ssh
+We also have a selection of problems in the `examples/` folder as well as on the [Examples page](https://openscvx.github.io/OpenSCvx/latest/Examples/abstract/brachistochrone/) of the documentation. The example trajectory optimization problems are grouped by application and represent some of the problem types that can be solved by OpenSCvx.
 
-```sh
-git clone git@github.com:OpenSCvx/OpenSCvx.git
-```
+> [!Note]
+> To run the examples, you'll need to clone this repository and install OpenSCvx in editable mode (`pip install -e .`). See the [Installing From Source](#installing-from-source) section above for detailed installation instructions.
 
-Dependencies can then be installed using Conda or Pip
-
-<details>
-<summary>Via Conda</summary>
-
-1. Clone the repo using https or ssh
-2. Create a conda environment with Python:
-   ```sh
-   conda create -n openscvx python>=3.9
-   ```
-3. Activate the environment:
-   ```sh
-   conda activate openscvx
-   ```
-4. Install the package with dependencies:
-   ```sh
-   pip install -e .
-   ```
-
-   Or install with optional dependencies:
-   ```sh
-   pip install -e ".[gui,cvxpygen]"
-   ```
-</details>
-
-<details>
-<summary>Via uv</summary>
-
-1. Prerequisites
-   - Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
-2. Clone the repo using https or ssh
-3. Create virtual environment and install the package:
-   ```sh
-   uv venv
-   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-   uv pip install -e .
-   ```
-
-   Or install with optional dependencies:
-   ```sh
-   uv pip install -e ".[gui,cvxpygen]"
-   ```
-</details>
-
-<details>
-<summary>Via pip</summary>
-
-1. Prerequisites
-   Python >= 3.9
-2. Clone the repo using https or ssh
-3. Create virtual environment (called `venv` here) and source it
-   ```sh
-   python3 -m venv venv
-   source venv/bin/activate
-   ```
-4. Install the package with dependencies:
-   ```sh
-   pip install -e .
-   ```
-
-   Or install with optional dependencies:
-   ```sh
-   pip install -e ".[gui,cvxpygen]"
-   ```
-</details>
-
-### Running Trajectory Optimization
-
-See `examples/` folder for several example trajectory optimization problems grouped by application.
 To run a problem simply run any of the examples directly, for example:
 
 ```sh
 python3 examples/abstract/brachistochrone.py
 ```
 
-> **Note:** To run the examples, you'll need to clone this repository and install OpenSCvx in editable mode (`pip install -e .`). See the [Local Development](#local-development) section above for detailed installation instructions.
-
 and adjust the plotting as needed.
 
 Check out the problem definitions inside `examples/` to see how to define your own problems.
 
 ## Code Structure
-<img src="figures/oscvx_structure_full_dark.svg" width="1200"/>
-
-## ToDos
 
-- [X] Standardized Vehicle and Constraint classes
-- [X] Implement QOCOGen with CVPYGEN
-- [X] Non-Dilated Time Propagation
-- [X] Save and reload the compiled JAX code
-- [x] Unified Mathematical Interface
-- [ ] Auto-SCvx Weight Tuning
-- [ ] Compiled at the subproblem level with JAX
-- [ ] Single Shot propagation
+<img src="figures/oscvx_structure_full_dark.svg" width="1200"/>
 
 ## What is implemented
 
 This repo has the following features:
 
 1. Free Final Time
-2. Fully adaptive time dilation (```s``` is appended to the control vector)
+2. Fully adaptive time dilation (`s` is appended to the control vector)
 3. Continuous-Time Constraint Satisfaction
-4. FOH and ZOH exact discretization (```t``` is a state so you can bring your own scheme)
+4. FOH and ZOH exact discretization (`t` is a state so you can bring your own scheme)
 6. Vectorized and Ahead-of-Time (AOT) Compiled Multishooting Discretization
 7. JAX Autodiff for Jacobians
 

openscvx-0.4.1.dev43/README.md

@@ -0,0 +1,233 @@
+<a id="readme-top"></a>
+
+<img src="figures/openscvx_logo.svg" width="1200"/>
+<p align="center">
+    <a href="https://github.com/OpenSCvx/OpenSCvx/actions/workflows/lint.yml"><img src="https://github.com/OpenSCvx/OpenSCvx/actions/workflows/lint.yml/badge.svg"/></a>
+    <a href="https://github.com/OpenSCvx/OpenSCvx/actions/workflows/tests-unit.yml"><img src="https://github.com/OpenSCvx/OpenSCvx/actions/workflows/tests-unit.yml/badge.svg"/></a>
+    <a href="https://github.com/OpenSCvx/OpenSCvx/actions/workflows/tests-integration.yml"><img src="https://github.com/OpenSCvx/OpenSCvx/actions/workflows/tests-integration.yml/badge.svg"/></a>
+    <a href="https://github.com/OpenSCvx/OpenSCvx/actions/workflows/nightly.yml"><img src="https://github.com/OpenSCvx/OpenSCvx/actions/workflows/nightly.yml/badge.svg"/></a>
+    <a href="https://github.com/OpenSCvx/OpenSCvx/actions/workflows/release.yml"><img src="https://github.com/OpenSCvx/OpenSCvx/actions/workflows/release.yml/badge.svg?event=release"/></a>
+</p>
+<p align="center">
+    <a href="https://arxiv.org/abs/2410.22596"><img src="http://img.shields.io/badge/arXiv-2410.22596-B31B1B.svg"/></a>
+    <a href="https://www.apache.org/licenses/LICENSE-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"/></a>
+</p>
+
+<!-- PROJECT LOGO -->
+<br />
+
+## What is OpenSCvx
+
+OpenSCvx is a general python-based successive convexification implementation which uses a JAX backend.
+It is designed to be easy to use for anyone and fast enough for everyone, all while being open and modular for contributors.
+
+OpenSCvx provides a clean symbolic interface for problem definition which should be intuitive to users of NumPy, JAX, and CVXPY. This allows us to hide a lot of the under-the-hood magic away from the user while also providing a modular architecture, enabling contributors to focus on the algorithms without worrying about interface design.
+
+OpenSCvx makes heavy use of [JAX](https://github.com/jax-ml/jax) to efficiently perform calculations in the successive convex programming loop through automatic differentiation, ahead-of-time (AOT) compilation, vectorization, and GPU acceleration. Behind this is a [CVXPY](https://github.com/cvxpy/cvxpy/)-based backend to solve the convex subproblems.
+
+This is an open project and is under active development. Try it out, give us feedback, and help contribute.
+
+```python
+import openscvx as ox
+
+g = 9.81
+
+# Define states
+position = ox.State("position", shape=(2,))
+position.min = [0.0, 0.0]
+position.max = [10.0, 10.0]
+position.initial = [0.0, 10.0]
+position.final = [10.0, 5.0]
+
+velocity = ox.State("velocity", shape=(1,))
+velocity.min = [0.0]
+velocity.max = [10.0]
+velocity.initial = [0.0]
+velocity.final = [ox.Free(10.0)]
+
+# Define control (angle from vertical)
+theta = ox.Control("theta", shape=(1,))
+theta.min = [0.0]
+theta.max = [1.755]
+theta.guess = [[0.09], [1.755]]
+
+# Define dynamics
+dynamics = {
+    "position": ox.Concat(
+        velocity * ox.Sin(theta),
+        -velocity * ox.Cos(theta),
+    ),
+    "velocity": g * ox.Cos(theta),
+}
+
+constraints = []
+for state in [position, velocity]:
+    constraints.append(ox.ctcs(state <= state.max))
+    constraints.append(ox.ctcs(state.min <= state))
+
+# Build and solve
+problem = ox.Problem(
+    dynamics=dynamics,
+    constraints=constraints,
+    states=[position, velocity],
+    controls=[theta],
+    time=ox.Time(initial=0.0, final=ox.Minimize(2.0), min=0.0, max=2.0),
+    N=2,
+)
+
+
+problem.initialize()
+results = problem.solve()
+results = problem.post_process()
+```
+
+## Installation
+
+OpenSCvx is available on [PyPI](https://pypi.org/project/openscvx/) and can be trivially installed with pip.
+
+It is recommended to install OpenSCvx inside a virtual environment (venv, conda, uv, *etc.*). If you don't already have one set up:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### Using pip
+
+```bash
+pip install openscvx
+```
+
+### Using uv
+
+If you have [uv installed](https://docs.astral.sh/uv/getting-started/installation/) you can prefix the commands with `uv` for faster installation:
+
+```bash
+uv pip install openscvx
+```
+
+> [!TIP]
+> **Optional Dependencies**
+>
+> For GUI support or CVXPYGen code generation:
+> ```bash
+> pip install openscvx[gui,cvxpygen]
+> ```
+
+> [!TIP]
+> **Nightly Builds**
+>
+> To install the latest development version (nightly), use the `--pre` flag:
+> ```bash
+> pip install --pre openscvx
+> ```
+
+## Installing From Source
+
+### Using pip
+
+```bash
+git clone https://github.com/OpenSCvx/OpenSCvx.git
+cd OpenSCvx
+
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### Using uv
+
+```bash
+git clone https://github.com/OpenSCvx/OpenSCvx.git
+cd OpenSCvx
+
+uv venv
+source .venv/bin/activate
+uv pip install -e .
+```
+
+## Getting Started
+
+Check out the OpenSCvx documentation to help you get started
+
+- [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/)
+
+### Running the Examples
+
+We also have a selection of problems in the `examples/` folder as well as on the [Examples page](https://openscvx.github.io/OpenSCvx/latest/Examples/abstract/brachistochrone/) of the documentation. The example trajectory optimization problems are grouped by application and represent some of the problem types that can be solved by OpenSCvx.
+
+> [!Note]
+> To run the examples, you'll need to clone this repository and install OpenSCvx in editable mode (`pip install -e .`). See the [Installing From Source](#installing-from-source) section above for detailed installation instructions.
+
+To run a problem simply run any of the examples directly, for example:
+
+```sh
+python3 examples/abstract/brachistochrone.py
+```
+
+and adjust the plotting as needed.
+
+Check out the problem definitions inside `examples/` to see how to define your own problems.
+
+## Code Structure
+
+<img src="figures/oscvx_structure_full_dark.svg" width="1200"/>
+
+## What is implemented
+
+This repo has the following features:
+
+1. Free Final Time
+2. Fully adaptive time dilation (`s` is appended to the control vector)
+3. Continuous-Time Constraint Satisfaction
+4. FOH and ZOH exact discretization (`t` is a state so you can bring your own scheme)
+6. Vectorized and Ahead-of-Time (AOT) Compiled Multishooting Discretization
+7. JAX Autodiff for Jacobians
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Acknowledgements
+
+This work was supported by a NASA Space Technology Graduate Research Opportunity and the Office of Naval Research under grant N00014-17-1-2433. The authors would like to acknowledge Natalia Pavlasek, Fabio Spada, Samuel Buckner, Abhi Kamath, Govind Chari, and Purnanand Elango as well as the other Autonomous Controls Laboratory members, for their many helpful discussions and support throughout this work.
+
+## Citation
+
+Please cite the following works if you use the repository,
+
+```tex
+@ARTICLE{hayner2025los,
+        author={Hayner, Christopher R. and Carson III, John M. and Açıkmeşe, Behçet and Leung, Karen},
+        journal={IEEE Robotics and Automation Letters}, 
+        title={Continuous-Time Line-of-Sight Constrained Trajectory Planning for 6-Degree of Freedom Systems}, 
+        year={2025},
+        volume={},
+        number={},
+        pages={1-8},
+        keywords={Robot sensing systems;Vectors;Vehicle dynamics;Line-of-sight propagation;Trajectory planning;Trajectory optimization;Quadrotors;Nonlinear dynamical systems;Heuristic algorithms;Convergence;Constrained Motion Planning;Optimization and Optimal Control;Aerial Systems: Perception and Autonomy},
+        doi={10.1109/LRA.2025.3545299}}
+```
+
+```tex
+@misc{elango2024ctscvx,
+      title={Successive Convexification for Trajectory Optimization with Continuous-Time Constraint Satisfaction}, 
+      author={Purnanand Elango and Dayou Luo and Abhinav G. Kamath and Samet Uzun and Taewan Kim and Behçet Açıkmeşe},
+      year={2024},
+      eprint={2404.16826},
+      archivePrefix={arXiv},
+      primaryClass={math.OC},
+      url={https://arxiv.org/abs/2404.16826}, 
+}
+```
+
+```tex
+@misc{chari2025qoco,
+  title = {QOCO: A Quadratic Objective Conic Optimizer with Custom Solver Generation},
+  author = {Chari, Govind M and A{\c{c}}{\i}kme{\c{s}}e, Beh{\c{c}}et},
+  year = {2025},
+  eprint = {2503.12658},
+  archiveprefix = {arXiv},
+  primaryclass = {math.OC},
+}
+```