0
# Constraints
1

2
Constraint types that define the feasible region of optimization problems in CVXPY. These constraints ensure that solutions satisfy specified mathematical relationships and belong to appropriate geometric sets.
3

4
## Capabilities
5

6
### Base Constraint Class
7

8
```python { .api }
9
class Constraint:
10
    """
11
    Base class for all constraints.
12
    """
13
    
14
    @property
15
    def value(self):
16
        """Value of the constraint expression (for checking feasibility)."""
17
        ...
18
        
19
    @property
20
    def violation(self):
21
        """Amount by which the constraint is violated."""
22
        ...
23
        
24
    @property
25
    def dual_value(self):
26
        """Dual variable value associated with this constraint."""
27
        ...
28
        
29
    def is_dcp(self, dpp=False):
30
        """Check if constraint follows disciplined convex programming rules."""
31
        ...
32
        
33
    def is_dgp(self, dpp=False):
34
        """Check if constraint follows disciplined geometric programming rules."""
35
        ...
36
```
37

38
### Equality Constraints (Zero)
39

40
Equality constraints of the form `expr == 0`.
41

42
```python { .api }
43
class Zero(Constraint):
44
    """
45
    Equality constraint: expr == 0
46
    
47
    Parameters:
48
    - expr: Expression that should equal zero
49
    """
50
    def __init__(self, expr): ...
51
```
52

53
Usage examples:
54

55
```python
56
import cvxpy as cp
57

58
x = cp.Variable(3)
59
A = cp.Parameter((2, 3))
60
b = cp.Parameter(2)
61

62
# Linear equality constraints: Ax = b
63
equality_constraint = (A @ x == b)
64

65
# Sum constraint: sum of x equals 1
66
sum_constraint = (cp.sum(x) == 1)
67

68
# Individual element constraints
69
element_constraint = (x[0] == 2 * x[1])
70

71
# Multiple equality constraints
72
constraints = [A @ x == b, cp.sum(x) == 1, x[0] + x[1] == x[2]]
73
```
74

75
### Non-Negativity Constraints (NonNeg)
76

77
Non-negativity constraints of the form `expr >= 0`.
78

79
```python { .api }
80
class NonNeg(Constraint):
81
    """
82
    Non-negativity constraint: expr >= 0
83
    
84
    Parameters:
85
    - expr: Expression that should be non-negative
86
    """
87
    def __init__(self, expr): ...
88
```
89

90
Usage examples:
91

92
```python
93
import cvxpy as cp
94

95
x = cp.Variable(5)
96

97
# Simple non-negativity
98
nonneg_constraint = (x >= 0)
99

100
# Element-wise non-negativity  
101
A = cp.Variable((3, 4))
102
matrix_nonneg = (A >= 0)
103

104
# Expression non-negativity
105
expr = 2*x[0] - x[1] + 3
106
expr_nonneg = (expr >= 0)
107
```
108

109
### Non-Positivity Constraints (NonPos)
110

111
Non-positivity constraints of the form `expr <= 0`.
112

113
```python { .api }
114
class NonPos(Constraint):
115
    """
116
    Non-positivity constraint: expr <= 0
117
    
118
    Parameters:
119
    - expr: Expression that should be non-positive
120
    """
121
    def __init__(self, expr): ...
122
```
123

124
Usage examples:
125

126
```python
127
import cvxpy as cp
128

129
x = cp.Variable(3)
130

131
# Upper bound constraints
132
upper_bound = (x <= 1)
133

134
# Resource constraints (consumption <= capacity)
135
consumption = cp.sum(x)
136
capacity = 10
137
resource_constraint = (consumption <= capacity)
138
```
139

140
### Positive Semidefinite Constraints (PSD)
141

142
Positive semidefinite constraints for symmetric matrices.
143

144
```python { .api }
145
class PSD(Constraint):
146
    """
147
    Positive semidefinite constraint: expr >= 0 (matrix sense)
148
    
149
    Parameters:
150
    - expr: Symmetric matrix expression that should be PSD
151
    """
152
    def __init__(self, expr): ...
153
```
154

155
Usage examples:
156

157
```python
158
import cvxpy as cp
159
import numpy as np
160

161
# PSD matrix variable
162
n = 4
163
X = cp.Variable((n, n), symmetric=True)
164
psd_constraint = (X >> 0)  # X is PSD
165

166
# Linear matrix inequality (LMI)
167
A = [np.random.randn(n, n) for _ in range(3)]
168
x = cp.Variable(3)
169
lmi = (sum(x[i] * A[i] for i in range(3)) >> 0)
170

171
# Covariance matrix constraint
172
Sigma = cp.Variable((n, n), symmetric=True)
173
mu = cp.Variable(n)
174
# Ensure covariance matrix is PSD
175
constraints = [Sigma >> 0, cp.trace(Sigma) <= 1]
176

177
# Semidefinite program example
178
C = np.random.randn(n, n)
179
objective = cp.Minimize(cp.trace(C @ X))
180
problem = cp.Problem(objective, [X >> 0, cp.trace(X) == 1])
181
```
182

183
### Second-Order Cone Constraints (SOC)
184

185
Second-order cone (Lorentz cone) constraints of the form `||x||_2 <= t`.
186

187
```python { .api }
188
class SOC(Constraint):
189
    """
190
    Second-order cone constraint: ||X||_2 <= t
191
    
192
    Parameters:
193
    - t: scalar expression (upper bound)
194
    - X: vector expression (should be in the cone)
195
    """
196
    def __init__(self, t, X): ...
197
```
198

199
Usage examples:
200

201
```python
202
import cvxpy as cp
203

204
# Basic SOC constraint: ||x||_2 <= t
205
x = cp.Variable(3)
206
t = cp.Variable()
207
soc_constraint = cp.SOC(t, x)
208

209
# Equivalent using norm
210
norm_constraint = (cp.norm(x, 2) <= t)
211

212
# Quadratic constraint: x^T P x <= t^2 (if P is PSD)
213
P = cp.Parameter((3, 3), PSD=True)
214
quadratic_soc = cp.SOC(t, cp.psd_wrap(P.value) @ x)
215

216
# Portfolio risk constraint
217
n = 5
218
w = cp.Variable(n)  # portfolio weights
219
Sigma = cp.Parameter((n, n), PSD=True)  # covariance matrix
220
risk_limit = 0.1
221

222
# ||Sigma^{1/2} w||_2 <= risk_limit
223
L = cp.Parameter((n, n))  # Cholesky factor of Sigma
224
risk_constraint = cp.SOC(risk_limit, L.T @ w)
225
```
226

227
### Exponential Cone Constraints
228

229
Exponential cone constraints for problems involving exponential and logarithmic functions.
230

231
```python { .api }
232
class ExpCone(Constraint):
233
    """
234
    Exponential cone constraint: (x, y, z) in exp cone
235
    Equivalently: y * exp(x/y) <= z, y > 0
236
    
237
    Parameters:
238
    - x, y, z: scalar expressions
239
    """
240
    def __init__(self, x, y, z): ...
241

242
class OpRelEntrConeQuad(Constraint):
243
    """
244
    Operator relative entropy cone constraint.
245
    """
246
    def __init__(self, X, Y, Z): ...
247

248
class RelEntrConeQuad(Constraint):
249
    """
250
    Relative entropy cone constraint.
251
    """
252
    def __init__(self, x, y, z): ...
253
```
254

255
Usage examples:
256

257
```python
258
import cvxpy as cp
259

260
# Exponential cone constraint
261
x = cp.Variable()
262
y = cp.Variable()
263
z = cp.Variable()
264
exp_constraint = cp.ExpCone(x, y, z)
265

266
# Logarithmic constraint using exponential cone
267
# log(x) >= y is equivalent to exp(y) <= x
268
log_constraint = cp.ExpCone(y, 1, x)
269

270
# Entropy maximization
271
n = 5
272
p = cp.Variable(n)  # probability distribution
273
entropy_constraint = [cp.ExpCone(-cp.entr(p[i]), 1, 1) for i in range(n)]
274
constraints = [p >= 0, cp.sum(p) == 1] + entropy_constraint
275
```
276

277
### Power Cone Constraints
278

279
Power cone constraints for problems involving power functions.
280

281
```python { .api }
282
class PowCone3D(Constraint):
283
    """
284
    3D power cone constraint: (x, y, z) in pow cone
285
    Equivalently: |x|^alpha * |y|^(1-alpha) >= |z|, x >= 0, y >= 0
286
    
287
    Parameters:
288
    - x, y, z: scalar expressions
289
    - alpha: power parameter in (0, 1)
290
    """
291
    def __init__(self, x, y, z, alpha): ...
292

293
class PowConeND(Constraint):
294
    """
295
    N-dimensional power cone constraint.
296
    
297
    Parameters:
298
    - x: vector expression
299
    - y: scalar expression  
300
    - alpha: vector of power parameters
301
    """
302
    def __init__(self, x, y, alpha): ...
303
```
304

305
Usage examples:
306

307
```python
308
import cvxpy as cp
309

310
# 3D power cone
311
x = cp.Variable()
312
y = cp.Variable()
313
z = cp.Variable()
314
alpha = 0.3
315
pow_constraint = cp.PowCone3D(x, y, z, alpha)
316

317
# Geometric mean constraint using power cone
318
# (x * y)^(1/2) >= z is equivalent to power cone constraint
319
geo_mean_constraint = cp.PowCone3D(x, y, z, 0.5)
320

321
# P-norm minimization using power cones
322
n = 10
323
x = cp.Variable(n)
324
p = 1.5  # between 1 and 2
325
# Minimize ||x||_p using power cone formulation
326
```
327

328
### Finite Set Constraints
329

330
Constraints that restrict variables to finite discrete sets.
331

332
```python { .api }
333
class FiniteSet(Constraint):
334
    """
335
    Finite set membership constraint.
336
    
337
    Parameters:
338
    - expr: expression that should be in the set
339
    - values: list or array of allowed values
340
    """
341
    def __init__(self, expr, values): ...
342
```
343

344
Usage examples:
345

346
```python
347
import cvxpy as cp
348

349
# Binary variable constraint
350
x = cp.Variable()
351
binary_constraint = cp.FiniteSet(x, [0, 1])
352

353
# Multi-valued discrete constraint
354
y = cp.Variable()
355
discrete_constraint = cp.FiniteSet(y, [-1, 0, 1, 2])
356

357
# Vector finite set constraint
358
z = cp.Variable(2)
359
vector_set_constraint = cp.FiniteSet(z, [[0, 0], [1, 0], [0, 1], [1, 1]])
360
```
361

362
### Constraint Composition
363

364
```python
365
import cvxpy as cp
366
import numpy as np
367

368
# Complex optimization problem with multiple constraint types
369
n = 4
370
x = cp.Variable(n)
371
X = cp.Variable((n, n), symmetric=True)
372
t = cp.Variable()
373

374
constraints = [
375
    # Equality constraints
376
    cp.sum(x) == 1,
377
    X[0, 0] == 1,
378
    
379
    # Inequality constraints  
380
    x >= 0,
381
    t >= 0,
382
    
383
    # Second-order cone
384
    cp.norm(x, 2) <= t,
385
    
386
    # PSD constraint
387
    X >> 0,
388
    
389
    # Linear matrix inequality
390
    cp.bmat([[X, x.reshape((-1, 1))],
391
             [x.reshape((1, -1)), t]]) >> 0
392
]
393

394
# Portfolio optimization with multiple constraint types
395
w = cp.Variable(n)  # weights
396
mu = cp.Parameter(n)  # expected returns
397
Sigma = cp.Parameter((n, n), PSD=True)  # covariance
398

399
portfolio_constraints = [
400
    w >= 0,  # long-only
401
    cp.sum(w) == 1,  # fully invested
402
    cp.quad_form(w, Sigma) <= 0.01,  # risk constraint
403
    mu.T @ w >= 0.05  # return constraint
404
]
405

406
objective = cp.Maximize(mu.T @ w - 0.5 * cp.quad_form(w, Sigma))
407
portfolio_problem = cp.Problem(objective, portfolio_constraints)
408
```