0
# qpsolvers
1

2
A comprehensive Python library providing a unified interface for solving convex quadratic programming problems. qpsolvers supports over 20 different backend solvers including OSQP, CVXOPT, Gurobi, MOSEK, and others, abstracting away solver-specific APIs and matrix format requirements.
3

4
## Package Information
5

6
- **Package Name**: qpsolvers  
7
- **Language**: Python
8
- **Installation**: `pip install qpsolvers` or `pip install qpsolvers[open_source_solvers]`
9
- **License**: LGPL-3.0-or-later
10
- **Version**: 4.8.1
11

12
## Core Imports
13

14
```python
15
import qpsolvers
16
```
17

18
Common imports for solving:
19

20
```python
21
from qpsolvers import solve_qp, solve_problem, available_solvers
22
```
23

24
Import specific solver functions:
25

26
```python
27
from qpsolvers import osqp_solve_qp, cvxopt_solve_qp, proxqp_solve_qp
28
```
29

30
Import data structures:
31

32
```python
33
from qpsolvers import Problem, Solution, ActiveSet
34
```
35

36
## Basic Usage
37

38
```python
39
import numpy as np
40
from qpsolvers import solve_qp
41

42
# Define a quadratic program: minimize 1/2 x^T P x + q^T x
43
# subject to G x <= h, A x = b, lb <= x <= ub
44
M = np.array([[1.0, 2.0, 0.0], [-8.0, 3.0, 2.0], [0.0, 1.0, 1.0]])
45
P = M.T @ M  # positive definite cost matrix
46
q = np.array([3.0, 2.0, 3.0]) @ M
47

48
# Inequality constraints: G x <= h
49
G = np.array([[1.0, 2.0, 1.0], [2.0, 0.0, 1.0], [-1.0, 2.0, -1.0]])
50
h = np.array([3.0, 2.0, -2.0])
51

52
# Equality constraints: A x = b
53
A = np.array([1.0, 1.0, 1.0])
54
b = np.array([1.0])
55

56
# Solve the QP
57
x = solve_qp(P, q, G, h, A, b, solver="proxqp")
58
print(f"Solution: {x}")
59
```
60

61
## Architecture
62

63
qpsolvers provides a unified interface that abstracts different QP solver APIs:
64

65
- **Frontend API**: Unified functions (`solve_qp`, `solve_problem`) that accept standard QP formulations
66
- **Backend Adapters**: Solver-specific modules that translate between the unified API and individual solver interfaces  
67
- **Data Structures**: `Problem` class for QP representation, `Solution` class for results with optimality checks
68
- **Matrix Support**: Handles both dense (NumPy) and sparse (SciPy CSC) matrix formats automatically
69
- **Solver Discovery**: Runtime detection of available solvers with graceful fallbacks
70

71
This architecture enables seamless switching between solvers and automatic format conversion while maintaining compatibility with the scientific Python ecosystem.
72

73
## Capabilities
74

75
### Core Solving Functions
76

77
Main functions for solving quadratic programs with the unified API. These provide the primary interface for QP solving with automatic solver selection and matrix format handling.
78

79
```python { .api }
80
def solve_qp(
81
    P: Union[np.ndarray, spa.csc_matrix],
82
    q: np.ndarray,
83
    G: Optional[Union[np.ndarray, spa.csc_matrix]] = None,
84
    h: Optional[np.ndarray] = None,
85
    A: Optional[Union[np.ndarray, spa.csc_matrix]] = None,
86
    b: Optional[np.ndarray] = None,
87
    lb: Optional[np.ndarray] = None,
88
    ub: Optional[np.ndarray] = None,
89
    solver: Optional[str] = None,
90
    initvals: Optional[np.ndarray] = None,
91
    verbose: bool = False,
92
    **kwargs
93
) -> Optional[np.ndarray]: ...
94

95
def solve_problem(
96
    problem: Problem,
97
    solver: str,
98
    initvals: Optional[np.ndarray] = None,
99
    verbose: bool = False,
100
    **kwargs
101
) -> Solution: ...
102

103
def solve_ls(
104
    R: Union[np.ndarray, spa.csc_matrix],
105
    s: np.ndarray,
106
    G: Optional[Union[np.ndarray, spa.csc_matrix]] = None,
107
    h: Optional[np.ndarray] = None,
108
    A: Optional[Union[np.ndarray, spa.csc_matrix]] = None,
109
    b: Optional[np.ndarray] = None,
110
    lb: Optional[np.ndarray] = None,
111
    ub: Optional[np.ndarray] = None,
112
    W: Optional[Union[np.ndarray, spa.csc_matrix]] = None,
113
    solver: Optional[str] = None,
114
    initvals: Optional[np.ndarray] = None,
115
    verbose: bool = False,
116
    sparse_conversion: Optional[bool] = None,
117
    **kwargs
118
) -> Optional[np.ndarray]: ...
119

120
def solve_unconstrained(problem: Problem) -> Solution: ...
121
```
122

123
[Core Solving Functions](./core-solving.md)
124

125
### Individual Solver Interfaces
126

127
Direct access to specific QP solver implementations. Each solver function provides solver-specific parameters and optimizations while maintaining the unified API structure.
128

129
```python { .api }
130
def osqp_solve_qp(...) -> Optional[np.ndarray]: ...
131
def cvxopt_solve_qp(...) -> Optional[np.ndarray]: ...
132
def proxqp_solve_qp(...) -> Optional[np.ndarray]: ...
133
def gurobi_solve_qp(...) -> Optional[np.ndarray]: ...
134
def mosek_solve_qp(...) -> Optional[np.ndarray]: ...
135
# ... and 16 more solver functions
136

137
available_solvers: List[str]
138
dense_solvers: List[str]
139
sparse_solvers: List[str]
140
```
141

142
[Individual Solver Interfaces](./solvers.md)
143

144
### Data Structures
145

146
Core classes for representing quadratic programs, solutions, and active constraint sets. These provide structured data handling with validation and optimality checking.
147

148
```python { .api }
149
class Problem:
150
    P: Union[np.ndarray, spa.csc_matrix]
151
    q: np.ndarray
152
    G: Optional[Union[np.ndarray, spa.csc_matrix]]
153
    h: Optional[np.ndarray]
154
    A: Optional[Union[np.ndarray, spa.csc_matrix]]
155
    b: Optional[np.ndarray]
156
    lb: Optional[np.ndarray]
157
    ub: Optional[np.ndarray]
158
    
159
    def check_constraints(self) -> None: ...
160
    def condition_number(self) -> float: ...
161

162
class Solution:
163
    problem: Problem
164
    found: Optional[bool]
165
    obj: Optional[float]
166
    x: Optional[np.ndarray]
167
    y: Optional[np.ndarray]
168
    z: Optional[np.ndarray]
169
    z_box: Optional[np.ndarray]
170
    extras: dict
171
    
172
    def is_optimal(self, eps_abs: float) -> bool: ...
173

174
class ActiveSet:
175
    G_indices: Sequence[int]
176
    lb_indices: Sequence[int]
177
    ub_indices: Sequence[int]
178
```
179

180
[Data Structures](./data-structures.md)
181

182
### Utilities and Conversions
183

184
Helper functions for matrix conversions, problem transformations, error handling, and debugging support.
185

186
```python { .api }
187
# Conversion utilities
188
def combine_linear_box_inequalities(...): ...
189
def linear_from_box_inequalities(...): ...
190
def ensure_sparse_matrices(...): ...
191
def socp_from_qp(...): ...
192
def split_dual_linear_box(...): ...
193

194
# Utility functions
195
def print_matrix_vector(...) -> None: ...
196

197
# Exception classes
198
class QPError(Exception): ...
199
class NoSolverSelected(QPError): ...
200
class ParamError(QPError): ...
201
class ProblemError(QPError): ...
202
class SolverNotFound(QPError): ...
203
class SolverError(QPError): ...
204
```
205

206
[Utilities and Conversions](./utilities.md)
207

208
## Package Metadata
209

210
```python { .api }
211
__version__: str  # "4.8.1"
212
```