0
# Mathematical Functions (Atoms)
1

2
Pre-defined mathematical functions in CVXPY that preserve convexity properties and enable complex mathematical expressions. These atoms are the building blocks for optimization objectives and constraints, organized by mathematical category.
3

4
## Capabilities
5

6
### Linear Algebra Operations
7

8
Basic linear algebra operations for vectors and matrices.
9

10
```python { .api }
11
def matmul(lh_exp, rh_exp):
12
    """
13
    Matrix multiplication.
14
    
15
    Parameters:
16
    - lh_exp: left matrix expression
17
    - rh_exp: right matrix expression
18
    
19
    Returns:
20
    - Expression: matrix product
21
    """
22
    ...
23

24
def multiply(lh_exp, rh_exp):
25
    """
26
    Element-wise multiplication.
27
    
28
    Parameters:
29
    - lh_exp, rh_exp: expressions of compatible shapes
30
    
31
    Returns:
32
    - Expression: element-wise product
33
    """
34
    ...
35

36
def vdot(x, y):
37
    """
38
    Vector dot product (flattens inputs first).
39
    
40
    Parameters:
41
    - x, y: vector expressions
42
    
43
    Returns:
44
    - Expression: scalar dot product
45
    """
46
    ...
47

48
def outer(x, y):
49
    """
50
    Outer product of two vectors.
51
    
52
    Parameters:
53
    - x, y: vector expressions
54
    
55
    Returns:
56
    - Expression: matrix outer product
57
    """
58
    ...
59

60
def trace(expr):
61
    """
62
    Trace of a square matrix.
63
    
64
    Parameters:
65
    - expr: square matrix expression
66
    
67
    Returns:
68
    - Expression: scalar trace
69
    """
70
    ...
71

72
def diag(expr, k=0):
73
    """
74
    Extract diagonal or create diagonal matrix.
75
    
76
    Parameters:
77
    - expr: vector (to create diagonal matrix) or matrix (to extract diagonal)
78
    - k: diagonal offset (0 for main diagonal)
79
    
80
    Returns:
81
    - Expression: diagonal vector or diagonal matrix
82
    """
83
    ...
84
```
85

86
### Array Construction and Manipulation
87

88
Functions for constructing and reshaping arrays and matrices.
89

90
```python { .api }
91
def hstack(arg_list):
92
    """
93
    Horizontal stack of expressions.
94
    
95
    Parameters:
96
    - arg_list: list of expressions with compatible shapes
97
    
98
    Returns:
99
    - Expression: horizontally stacked matrix
100
    """
101
    ...
102

103
def vstack(arg_list):
104
    """
105
    Vertical stack of expressions.
106
    
107
    Parameters:
108
    - arg_list: list of expressions with compatible shapes
109
    
110
    Returns:
111
    - Expression: vertically stacked matrix
112
    """
113
    ...
114

115
def bmat(block_lists):
116
    """
117
    Block matrix construction.
118
    
119
    Parameters:
120
    - block_lists: nested list of matrix expressions
121
    
122
    Returns:
123
    - Expression: block matrix
124
    """
125
    ...
126

127
def reshape(expr, shape):
128
    """
129
    Reshape expression.
130
    
131
    Parameters:
132
    - expr: expression to reshape
133
    - shape: new shape tuple
134
    
135
    Returns:
136
    - Expression: reshaped expression
137
    """
138
    ...
139

140
def vec(X, order='F'):
141
    """
142
    Vectorize matrix (flatten to column vector).
143
    
144
    Parameters:
145
    - X: matrix expression
146
    - order: 'F' (Fortran/column-major) or 'C' (C/row-major)
147
    
148
    Returns:
149
    - Expression: vectorized matrix
150
    """
151
    ...
152

153
def transpose(expr):
154
    """
155
    Transpose of an expression.
156
    
157
    Parameters:
158
    - expr: matrix expression
159
    
160
    Returns:
161
    - Expression: transposed matrix
162
    """
163
    ...
164
```
165

166
### Aggregation Functions
167

168
Functions that aggregate elements across arrays.
169

170
```python { .api }
171
def sum(expr, axis=None, keepdims=False):
172
    """
173
    Sum along specified axis.
174
    
175
    Parameters:
176
    - expr: expression to sum
177
    - axis: axis to sum along (None for all elements)
178
    - keepdims: whether to keep singleton dimensions
179
    
180
    Returns:
181
    - Expression: sum result
182
    """
183
    ...
184

185
def mean(expr, axis=None, keepdims=False):
186
    """
187
    Mean along specified axis.
188
    
189
    Parameters:
190
    - expr: expression to average
191
    - axis: axis to average along
192
    - keepdims: whether to keep singleton dimensions
193
    
194
    Returns:
195
    - Expression: mean result
196
    """
197
    ...
198

199
def max(expr, axis=None, keepdims=False):
200
    """
201
    Maximum along specified axis.
202
    
203
    Parameters:
204
    - expr: expression
205
    - axis: axis to take maximum along
206
    - keepdims: whether to keep singleton dimensions
207
    
208
    Returns:
209
    - Expression: maximum result
210
    """
211
    ...
212

213
def min(expr, axis=None, keepdims=False):
214
    """
215
    Minimum along specified axis.
216
    
217
    Parameters:
218
    - expr: expression
219
    - axis: axis to take minimum along  
220
    - keepdims: whether to keep singleton dimensions
221
    
222
    Returns:
223
    - Expression: minimum result
224
    """
225
    ...
226

227
def sum_largest(expr, k):
228
    """
229
    Sum of k largest elements.
230
    
231
    Parameters:
232
    - expr: expression
233
    - k: number of largest elements to sum
234
    
235
    Returns:
236
    - Expression: sum of k largest elements
237
    """
238
    ...
239

240
def sum_smallest(expr, k):
241
    """
242
    Sum of k smallest elements.
243
    
244
    Parameters:
245
    - expr: expression  
246
    - k: number of smallest elements to sum
247
    
248
    Returns:
249
    - Expression: sum of k smallest elements
250
    """
251
    ...
252
```
253

254
### Elementwise Functions
255

256
Functions applied element-wise to expressions.
257

258
```python { .api }
259
def abs(expr):
260
    """
261
    Absolute value (element-wise).
262
    
263
    Parameters:
264
    - expr: expression
265
    
266
    Returns:
267
    - Expression: absolute value
268
    """
269
    ...
270

271
def square(expr):
272
    """
273
    Square (element-wise).
274
    
275
    Parameters:
276
    - expr: expression
277
    
278
    Returns:
279
    - Expression: squared expression
280
    """
281
    ...
282

283
def sqrt(expr):
284
    """
285
    Square root (element-wise).
286
    
287
    Parameters:
288
    - expr: expression (must be non-negative)
289
    
290
    Returns:
291
    - Expression: square root
292
    """
293
    ...
294

295
def power(expr, p):
296
    """
297
    Power function (element-wise).
298
    
299
    Parameters:
300
    - expr: expression
301
    - p: power (scalar)
302
    
303
    Returns:
304
    - Expression: expr raised to power p
305
    """
306
    ...
307

308
def exp(expr):
309
    """
310
    Exponential function (element-wise).
311
    
312
    Parameters:
313
    - expr: expression
314
    
315
    Returns:
316
    - Expression: e^expr
317
    """
318
    ...
319

320
def log(expr):
321
    """
322
    Natural logarithm (element-wise).
323
    
324
    Parameters:
325
    - expr: expression (must be positive)
326
    
327
    Returns:
328
    - Expression: natural log
329
    """
330
    ...
331

332
def log1p(expr):
333
    """
334
    log(1 + expr) (element-wise).
335
    
336
    Parameters:
337
    - expr: expression
338
    
339
    Returns:
340
    - Expression: log(1 + expr)
341
    """
342
    ...
343

344
def entr(expr):
345
    """
346
    Entropy function: -expr * log(expr) (element-wise).
347
    
348
    Parameters:
349
    - expr: expression (must be non-negative)
350
    
351
    Returns:
352
    - Expression: entropy
353
    """
354
    ...
355

356
def maximum(lh_exp, rh_exp):
357
    """
358
    Element-wise maximum of two expressions.
359
    
360
    Parameters:
361
    - lh_exp, rh_exp: expressions
362
    
363
    Returns:
364
    - Expression: element-wise maximum
365
    """
366
    ...
367

368
def minimum(lh_exp, rh_exp):
369
    """
370
    Element-wise minimum of two expressions.
371
    
372
    Parameters:
373
    - lh_exp, rh_exp: expressions
374
    
375
    Returns:
376
    - Expression: element-wise minimum
377
    """
378
    ...
379
```
380

381
### Norms and Distances
382

383
Various norm functions for vectors and matrices.
384

385
```python { .api }
386
def norm(expr, p=2, axis=None, keepdims=False):
387
    """
388
    General norm function.
389
    
390
    Parameters:
391
    - expr: expression
392
    - p: norm type (1, 2, 'inf', 'fro', 'nuc')
393
    - axis: axis to compute norm along
394
    - keepdims: whether to keep singleton dimensions
395
    
396
    Returns:
397
    - Expression: norm value
398
    """
399
    ...
400

401
def norm1(expr):
402
    """
403
    L1 norm (sum of absolute values).
404
    
405
    Parameters:
406
    - expr: expression
407
    
408
    Returns:
409
    - Expression: L1 norm
410
    """
411
    ...
412

413
def norm2(expr, axis=None):
414
    """
415
    L2 norm (Euclidean norm).
416
    
417
    Parameters:
418
    - expr: expression
419
    - axis: axis to compute norm along
420
    
421
    Returns:
422
    - Expression: L2 norm
423
    """
424
    ...
425

426
def norm_inf(expr):
427
    """
428
    Infinity norm (maximum absolute value).
429
    
430
    Parameters:
431
    - expr: expression
432
    
433
    Returns:
434
    - Expression: infinity norm
435
    """
436
    ...
437

438
def pnorm(expr, p=2, axis=None, keepdims=False, max_denom=1024):
439
    """
440
    P-norm with rational approximation.
441
    
442
    Parameters:
443
    - expr: expression
444
    - p: norm order (>= 1)
445
    - axis: axis to compute norm along
446
    - keepdims: whether to keep singleton dimensions
447
    - max_denom: maximum denominator for rational approximation
448
    
449
    Returns:
450
    - Expression: p-norm
451
    """
452
    ...
453

454
def mixed_norm(expr, p=2, q=1):
455
    """
456
    Mixed norm: ||expr||_{p,q}
457
    
458
    Parameters:
459
    - expr: matrix expression
460
    - p: norm for columns
461
    - q: norm for aggregating column norms
462
    
463
    Returns:
464
    - Expression: mixed norm
465
    """
466
    ...
467
```
468

469
### Matrix Functions
470

471
Functions specific to matrix expressions.
472

473
```python { .api }
474
def lambda_max(expr):
475
    """
476
    Maximum eigenvalue of symmetric matrix.
477
    
478
    Parameters:
479
    - expr: symmetric matrix expression
480
    
481
    Returns:
482
    - Expression: maximum eigenvalue
483
    """
484
    ...
485

486
def lambda_min(expr):
487
    """
488
    Minimum eigenvalue of symmetric matrix.
489
    
490
    Parameters:
491
    - expr: symmetric matrix expression
492
    
493
    Returns:
494
    - Expression: minimum eigenvalue
495
    """
496
    ...
497

498
def sigma_max(expr):
499
    """
500
    Maximum singular value.
501
    
502
    Parameters:
503
    - expr: matrix expression
504
    
505
    Returns:
506
    - Expression: maximum singular value
507
    """
508
    ...
509

510
def log_det(expr):
511
    """
512
    Log determinant of positive definite matrix.
513
    
514
    Parameters:
515
    - expr: positive definite matrix expression
516
    
517
    Returns:
518
    - Expression: log determinant
519
    """
520
    ...
521

522
def matrix_frac(X, P):
523
    """
524
    Matrix fractional function: tr(X^T P^-1 X).
525
    
526
    Parameters:
527
    - X: matrix expression
528
    - P: positive definite matrix
529
    
530
    Returns:
531
    - Expression: matrix fractional value
532
    """
533
    ...
534

535
def quad_form(x, P, assume_PSD=False):
536
    """
537
    Quadratic form: x^T P x.
538
    
539
    Parameters:
540
    - x: vector expression
541
    - P: matrix (should be PSD for convexity)
542
    - assume_PSD: whether to assume P is PSD
543
    
544
    Returns:
545
    - Expression: quadratic form
546
    """
547
    ...
548

549
def quad_over_lin(X, y):
550
    """
551
    Quadratic over linear: sum(X^2) / y.
552
    
553
    Parameters:
554
    - X: expression
555
    - y: positive scalar expression
556
    
557
    Returns:
558
    - Expression: quadratic over linear
559
    """
560
    ...
561
```
562

563
### Special Functions
564

565
Advanced mathematical functions for specific applications.
566

567
```python { .api }
568
def geo_mean(expr):
569
    """
570
    Geometric mean.
571
    
572
    Parameters:
573
    - expr: expression with positive elements
574
    
575
    Returns:
576
    - Expression: geometric mean
577
    """
578
    ...
579

580
def harmonic_mean(expr):
581
    """
582
    Harmonic mean.
583
    
584
    Parameters:
585
    - expr: expression with positive elements
586
    
587
    Returns:
588
    - Expression: harmonic mean
589
    """
590
    ...
591

592
def log_sum_exp(expr, axis=None, keepdims=False):
593
    """
594
    Log-sum-exponential: log(sum(exp(expr))).
595
    
596
    Parameters:
597
    - expr: expression
598
    - axis: axis to sum along
599
    - keepdims: whether to keep singleton dimensions
600
    
601
    Returns:
602
    - Expression: log-sum-exp
603
    """
604
    ...
605

606
def kl_div(x, y):
607
    """
608
    Kullback-Leibler divergence.
609
    
610
    Parameters:
611
    - x, y: expressions (probability distributions)
612
    
613
    Returns:  
614
    - Expression: KL divergence
615
    """
616
    ...
617

618
def rel_entr(x, y):
619
    """
620
    Relative entropy: x * log(x/y).
621
    
622
    Parameters:
623
    - x, y: expressions
624
    
625
    Returns:
626
    - Expression: relative entropy
627
    """
628
    ...
629

630
def huber(expr, M=1):
631
    """
632
    Huber function (robust loss).
633
    
634
    Parameters:
635
    - expr: expression
636
    - M: threshold parameter
637
    
638
    Returns:
639
    - Expression: Huber loss
640
    """
641
    ...
642

643
def sum_squares(expr):
644
    """
645
    Sum of squares.
646
    
647
    Parameters:
648
    - expr: expression
649
    
650
    Returns:
651
    - Expression: sum of squared elements
652
    """
653
    ...
654
```
655

656
### Complex Number Operations
657

658
Functions for working with complex-valued expressions.
659

660
```python { .api }
661
def conj(expr):
662
    """
663
    Complex conjugate (element-wise).
664
    
665
    Parameters:
666
    - expr: expression
667
    
668
    Returns:
669
    - Expression: complex conjugate
670
    """
671
    ...
672

673
def imag(expr):
674
    """
675
    Imaginary part (element-wise).
676
    
677
    Parameters:
678
    - expr: expression
679
    
680
    Returns:
681
    - Expression: imaginary part
682
    """
683
    ...
684

685
def real(expr):
686
    """
687
    Real part (element-wise).
688
    
689
    Parameters:
690
    - expr: expression
691
    
692
    Returns:
693
    - Expression: real part
694
    """
695
    ...
696
```
697

698
### Statistical Functions
699

700
Statistical and probability functions.
701

702
```python { .api }
703
def std(expr, axis=None, keepdims=False):
704
    """
705
    Standard deviation along specified axis.
706
    
707
    Parameters:
708
    - expr: expression
709
    - axis: axis to compute std along
710
    - keepdims: whether to keep singleton dimensions
711
    
712
    Returns:
713
    - Expression: standard deviation
714
    """
715
    ...
716

717
def var(expr, axis=None, keepdims=False):
718
    """
719
    Variance along specified axis.
720
    
721
    Parameters:
722
    - expr: expression
723
    - axis: axis to compute variance along
724
    - keepdims: whether to keep singleton dimensions
725
    
726
    Returns:
727
    - Expression: variance
728
    """
729
    ...
730

731
def cvar(expr, alpha):
732
    """
733
    Conditional value at risk (CVaR).
734
    
735
    Parameters:
736
    - expr: expression representing losses
737
    - alpha: confidence level (0 < alpha < 1)
738
    
739
    Returns:
740
    - Expression: CVaR value
741
    """
742
    ...
743

744
def ptp(expr, axis=None, keepdims=False):
745
    """
746
    Peak-to-peak (range) along specified axis.
747
    
748
    Parameters:
749
    - expr: expression
750
    - axis: axis to compute range along
751
    - keepdims: whether to keep singleton dimensions
752
    
753
    Returns:
754
    - Expression: peak-to-peak range
755
    """
756
    ...
757
```
758

759
### Cumulative Functions
760

761
Cumulative operations on arrays.
762

763
```python { .api }
764
def cumsum(expr, axis=None):
765
    """
766
    Cumulative sum along specified axis.
767
    
768
    Parameters:
769
    - expr: expression
770
    - axis: axis to compute cumulative sum along
771
    
772
    Returns:
773
    - Expression: cumulative sum
774
    """
775
    ...
776

777
def cummax(expr, axis=None):
778
    """
779
    Cumulative maximum along specified axis.
780
    
781
    Parameters:
782
    - expr: expression
783
    - axis: axis to compute cumulative max along
784
    
785
    Returns:
786
    - Expression: cumulative maximum
787
    """
788
    ...
789

790
def cumprod(expr, axis=None):
791
    """
792
    Cumulative product along specified axis.
793
    
794
    Parameters:
795
    - expr: expression
796
    - axis: axis to compute cumulative product along
797
    
798
    Returns:
799
    - Expression: cumulative product
800
    """
801
    ...
802
```
803

804
### Advanced Elementwise Functions
805

806
Additional elementwise mathematical functions.
807

808
```python { .api }
809
def ceil(expr):
810
    """
811
    Ceiling function (element-wise).
812
    
813
    Parameters:
814
    - expr: expression
815
    
816
    Returns:
817
    - Expression: ceiling values
818
    """
819
    ...
820

821
def floor(expr):
822
    """
823
    Floor function (element-wise).
824
    
825
    Parameters:
826
    - expr: expression  
827
    
828
    Returns:
829
    - Expression: floor values
830
    """
831
    ...
832

833
def inv_pos(expr):
834
    """
835
    Reciprocal of positive part: 1/pos(expr).
836
    
837
    Parameters:
838
    - expr: expression
839
    
840
    Returns:
841
    - Expression: reciprocal of positive part
842
    """
843
    ...
844

845
def logistic(expr):
846
    """
847
    Logistic function: 1/(1 + exp(-expr)).
848
    
849
    Parameters:
850
    - expr: expression
851
    
852
    Returns:
853
    - Expression: logistic function values
854
    """
855
    ...
856

857
def loggamma(expr):
858
    """
859
    Log gamma function (element-wise).
860
    
861
    Parameters:
862
    - expr: expression (must be positive)
863
    
864
    Returns:
865
    - Expression: log gamma values
866
    """
867
    ...
868

869
def log_normcdf(expr):
870
    """
871
    Log of normal cumulative distribution function.
872
    
873
    Parameters:
874
    - expr: expression
875
    
876
    Returns:
877
    - Expression: log normal CDF values
878
    """
879
    ...
880

881
def neg(expr):
882
    """
883
    Negative part: max(-expr, 0).
884
    
885
    Parameters:
886
    - expr: expression
887
    
888
    Returns:
889
    - Expression: negative part
890
    """
891
    ...
892

893
def pos(expr):
894
    """
895
    Positive part: max(expr, 0).
896
    
897
    Parameters:
898
    - expr: expression
899
    
900
    Returns:
901
    - Expression: positive part
902
    """
903
    ...
904

905
def scalene(expr, alpha, beta):
906
    """
907
    Scalene function.
908
    
909
    Parameters:
910
    - expr: expression
911
    - alpha, beta: scalar parameters
912
    
913
    Returns:
914
    - Expression: scalene function values
915
    """
916
    ...
917

918
def sign(expr):
919
    """
920
    Sign function (element-wise).
921
    
922
    Parameters:
923
    - expr: expression
924
    
925
    Returns:
926
    - Expression: sign values (-1, 0, or 1)
927
    """
928
    ...
929

930
def xexp(expr):
931
    """
932
    Extended exponential: expr * exp(expr).
933
    
934
    Parameters:
935
    - expr: expression
936
    
937
    Returns:
938
    - Expression: extended exponential
939
    """
940
    ...
941

942
def one_minus_pos(expr):
943
    """
944
    One minus positive part: 1 - pos(expr).
945
    
946
    Parameters:
947
    - expr: expression
948
    
949
    Returns:
950
    - Expression: one minus positive part
951
    """
952
    ...
953

954
def diff_pos(x, y):
955
    """
956
    Positive difference: pos(x - y).
957
    
958
    Parameters:
959
    - x, y: expressions
960
    
961
    Returns:
962
    - Expression: positive difference
963
    """
964
    ...
965
```
966

967
### Advanced Matrix Functions
968

969
Additional matrix operations and eigenvalue functions.
970

971
```python { .api }
972
def condition_number(expr):
973
    """
974
    Condition number of a matrix.
975
    
976
    Parameters:
977
    - expr: matrix expression
978
    
979
    Returns:
980
    - Expression: condition number
981
    """
982
    ...
983

984
def resolvent(expr, s):
985
    """
986
    Matrix resolvent: (sI - expr)^(-1).
987
    
988
    Parameters:
989
    - expr: matrix expression
990
    - s: scalar parameter
991
    
992
    Returns:
993
    - Expression: resolvent matrix
994
    """
995
    ...
996

997
def eye_minus_inv(expr):
998
    """
999
    (I - expr)^(-1) for matrices with eigenvalues < 1.
1000
    
1001
    Parameters:
1002
    - expr: matrix expression
1003
    
1004
    Returns:
1005
    - Expression: inverse of (I - expr)
1006
    """
1007
    ...
1008

1009
def lambda_sum_largest(expr, k):
1010
    """
1011
    Sum of k largest eigenvalues.
1012
    
1013
    Parameters:
1014
    - expr: symmetric matrix expression
1015
    - k: number of largest eigenvalues to sum
1016
    
1017
    Returns:
1018
    - Expression: sum of k largest eigenvalues
1019
    """
1020
    ...
1021

1022
def lambda_sum_smallest(expr, k):
1023
    """
1024
    Sum of k smallest eigenvalues.
1025
    
1026
    Parameters:
1027
    - expr: symmetric matrix expression
1028
    - k: number of smallest eigenvalues to sum
1029
    
1030
    Returns:
1031
    - Expression: sum of k smallest eigenvalues
1032
    """
1033
    ...
1034

1035
def gen_lambda_max(A, B):
1036
    """
1037
    Generalized maximum eigenvalue of (A, B).
1038
    
1039
    Parameters:
1040
    - A, B: matrix expressions
1041
    
1042
    Returns:
1043
    - Expression: generalized maximum eigenvalue
1044
    """
1045
    ...
1046

1047
def pf_eigenvalue(expr):
1048
    """
1049
    Perron-Frobenius eigenvalue of non-negative matrix.
1050
    
1051
    Parameters:
1052
    - expr: non-negative matrix expression
1053
    
1054
    Returns:
1055
    - Expression: Perron-Frobenius eigenvalue
1056
    """
1057
    ...
1058

1059
def tr_inv(expr):
1060
    """
1061
    Trace of matrix inverse: tr(expr^(-1)).
1062
    
1063
    Parameters:
1064
    - expr: positive definite matrix expression
1065
    
1066
    Returns:
1067
    - Expression: trace of inverse
1068
    """
1069
    ...
1070
```
1071

1072
### Quantum Information Functions
1073

1074
Functions for quantum information theory.
1075

1076
```python { .api }
1077
def von_neumann_entr(expr):
1078
    """
1079
    von Neumann entropy: -tr(expr * log(expr)).
1080
    
1081
    Parameters:
1082
    - expr: positive semidefinite matrix (density matrix)
1083
    
1084
    Returns:
1085
    - Expression: von Neumann entropy
1086
    """
1087
    ...
1088

1089
def quantum_rel_entr(A, B):
1090
    """
1091
    Quantum relative entropy: tr(A * (log(A) - log(B))).
1092
    
1093
    Parameters:
1094
    - A, B: positive semidefinite matrices
1095
    
1096
    Returns:
1097
    - Expression: quantum relative entropy
1098
    """
1099
    ...
1100

1101
def quantum_cond_entr(A, B):
1102
    """
1103
    Quantum conditional entropy.
1104
    
1105
    Parameters:
1106
    - A, B: positive semidefinite matrices
1107
    
1108
    Returns:
1109
    - Expression: quantum conditional entropy
1110
    """
1111
    ...
1112
```
1113

1114
### Array Manipulation and Broadcasting
1115

1116
Functions for reshaping and manipulating arrays.
1117

1118
```python { .api }
1119
def broadcast_to(expr, shape):
1120
    """
1121
    Broadcast expression to specified shape.
1122
    
1123
    Parameters:
1124
    - expr: expression
1125
    - shape: target shape tuple
1126
    
1127
    Returns:
1128
    - Expression: broadcasted expression
1129
    """
1130
    ...
1131

1132
def deep_flatten(expr):
1133
    """
1134
    Flatten expression to 1D vector.
1135
    
1136
    Parameters:
1137
    - expr: expression
1138
    
1139
    Returns:
1140
    - Expression: flattened vector
1141
    """
1142
    ...
1143

1144
def permute_dims(expr, axes):
1145
    """
1146
    Permute dimensions of expression.
1147
    
1148
    Parameters:
1149
    - expr: expression
1150
    - axes: permutation of dimension indices
1151
    
1152
    Returns:
1153
    - Expression: permuted expression
1154
    """
1155
    ...
1156

1157
def swapaxes(expr, axis1, axis2):
1158
    """
1159
    Swap two axes of expression.
1160
    
1161
    Parameters:
1162
    - expr: expression
1163
    - axis1, axis2: axes to swap
1164
    
1165
    Returns:
1166
    - Expression: expression with swapped axes
1167
    """
1168
    ...
1169

1170
def moveaxis(expr, source, destination):
1171
    """
1172
    Move axis from source to destination position.
1173
    
1174
    Parameters:
1175
    - expr: expression
1176
    - source: source axis position
1177
    - destination: destination axis position
1178
    
1179
    Returns:
1180
    - Expression: expression with moved axis
1181
    """
1182
    ...
1183

1184
def concatenate(expressions, axis=0):
1185
    """
1186
    Concatenate expressions along specified axis.
1187
    
1188
    Parameters:
1189
    - expressions: list of expressions to concatenate
1190
    - axis: axis along which to concatenate
1191
    
1192
    Returns:
1193
    - Expression: concatenated expression
1194
    """
1195
    ...
1196

1197
def diff(expr, k=1, axis=-1):
1198
    """
1199
    Discrete difference along specified axis.
1200
    
1201
    Parameters:
1202
    - expr: expression
1203
    - k: order of difference (number of times differences are taken)
1204
    - axis: axis along which differences are taken
1205
    
1206
    Returns:
1207
    - Expression: discrete differences
1208
    """
1209
    ...
1210
```
1211

1212
### Matrix Wrapping Functions
1213

1214
Functions that wrap matrices with special properties.
1215

1216
```python { .api }
1217
def hermitian_wrap(expr):
1218
    """
1219
    Wrap expression to ensure Hermitian property.
1220
    
1221
    Parameters:
1222
    - expr: matrix expression
1223
    
1224
    Returns:
1225
    - Expression: Hermitian matrix
1226
    """
1227
    ...
1228

1229
def psd_wrap(expr):
1230
    """
1231
    Wrap expression to ensure positive semidefinite property.
1232
    
1233
    Parameters:
1234
    - expr: matrix expression
1235
    
1236
    Returns:
1237
    - Expression: PSD matrix
1238
    """
1239
    ...
1240

1241
def skew_symmetric_wrap(expr):
1242
    """
1243
    Wrap expression to ensure skew-symmetric property.
1244
    
1245
    Parameters:
1246
    - expr: matrix expression
1247
    
1248
    Returns:
1249
    - Expression: skew-symmetric matrix
1250
    """
1251
    ...
1252

1253
def symmetric_wrap(expr):
1254
    """
1255
    Wrap expression to ensure symmetric property.
1256
    
1257
    Parameters:
1258
    - expr: matrix expression
1259
    
1260
    Returns:
1261
    - Expression: symmetric matrix
1262
    """
1263
    ...
1264
```
1265

1266
### Triangular Matrix Operations
1267

1268
Operations related to triangular matrices.
1269

1270
```python { .api }
1271
def upper_tri(expr, k=0):
1272
    """
1273
    Extract upper triangular part of matrix.
1274
    
1275
    Parameters:
1276
    - expr: matrix expression
1277
    - k: diagonal offset (0 for main diagonal)
1278
    
1279
    Returns:
1280
    - Expression: upper triangular matrix
1281
    """
1282
    ...
1283

1284
def vec_to_upper_tri(expr, strict=False):
1285
    """
1286
    Convert vector to upper triangular matrix.
1287
    
1288
    Parameters:
1289
    - expr: vector expression
1290
    - strict: whether to exclude diagonal elements
1291
    
1292
    Returns:
1293
    - Expression: upper triangular matrix
1294
    """
1295
    ...
1296
```
1297

1298
### Special Advanced Functions
1299

1300
Specialized mathematical functions for specific applications.
1301

1302
```python { .api }
1303
def conv(x, y):
1304
    """
1305
    Convolution of two vectors.
1306
    
1307
    Parameters:
1308
    - x, y: vector expressions
1309
    
1310
    Returns:
1311
    - Expression: convolution result
1312
    """
1313
    ...
1314

1315
def convolve(x, y):
1316
    """
1317
    Convolution of two expressions.
1318
    
1319
    Parameters:
1320
    - x, y: expressions
1321
    
1322
    Returns:
1323
    - Expression: convolution result
1324
    """
1325
    ...
1326

1327
def kron(X, Y):
1328
    """
1329
    Kronecker product of two matrices.
1330
    
1331
    Parameters:
1332
    - X, Y: matrix expressions
1333
    
1334
    Returns:
1335
    - Expression: Kronecker product
1336
    """
1337
    ...
1338

1339
def partial_trace(expr, dims, axis):
1340
    """
1341
    Partial trace operation (quantum mechanics).
1342
    
1343
    Parameters:
1344
    - expr: matrix expression
1345
    - dims: dimensions of subsystems
1346
    - axis: axis to trace over
1347
    
1348
    Returns:
1349
    - Expression: partial trace result
1350
    """
1351
    ...
1352

1353
def partial_transpose(expr, dims, axis):
1354
    """
1355
    Partial transpose operation (quantum mechanics).
1356
    
1357
    Parameters:
1358
    - expr: matrix expression
1359
    - dims: dimensions of subsystems
1360
    - axis: axis to transpose
1361
    
1362
    Returns:
1363
    - Expression: partial transpose result
1364
    """
1365
    ...
1366

1367
def dotsort(expr, W):
1368
    """
1369
    Dot sort function.
1370
    
1371
    Parameters:
1372
    - expr: expression
1373
    - W: weight matrix
1374
    
1375
    Returns:
1376
    - Expression: dot sort result
1377
    """
1378
    ...
1379

1380
def dist_ratio(expr, X, Y):
1381
    """
1382
    Distance ratio function.
1383
    
1384
    Parameters:
1385
    - expr, X, Y: expressions
1386
    
1387
    Returns:
1388
    - Expression: distance ratio
1389
    """
1390
    ...
1391

1392
def length(expr):
1393
    """
1394
    Length (magnitude) of vector expression.
1395
    
1396
    Parameters:
1397
    - expr: vector expression
1398
    
1399
    Returns:
1400
    - Expression: vector length
1401
    """
1402
    ...
1403

1404
def inv_prod(expr):
1405
    """
1406
    Inverse product function.
1407
    
1408
    Parameters:
1409
    - expr: expression
1410
    
1411
    Returns:
1412
    - Expression: inverse product
1413
    """
1414
    ...
1415

1416
def perspective(f, x):
1417
    """
1418
    Perspective function: x * f(expr/x).
1419
    
1420
    Parameters:
1421
    - f: convex function
1422
    - x: positive scaling expression
1423
    
1424
    Returns:
1425
    - Expression: perspective function result
1426
    """
1427
    ...
1428

1429
def promote(expr, shape):
1430
    """
1431
    Promote expression to specified shape.
1432
    
1433
    Parameters:
1434
    - expr: expression
1435
    - shape: target shape
1436
    
1437
    Returns:
1438
    - Expression: promoted expression
1439
    """
1440
    ...
1441

1442
def scalar_product(x, y):
1443
    """
1444
    Scalar product of two expressions.
1445
    
1446
    Parameters:
1447
    - x, y: expressions
1448
    
1449
    Returns:
1450
    - Expression: scalar product
1451
    """
1452
    ...
1453

1454
def tv(expr, *args):
1455
    """
1456
    Total variation function.
1457
    
1458
    Parameters:
1459
    - expr: expression
1460
    - args: additional arguments for TV computation
1461
    
1462
    Returns:
1463
    - Expression: total variation
1464
    """
1465
    ...
1466
```
1467

1468
### Usage Examples
1469

1470
```python
1471
import cvxpy as cp
1472
import numpy as np
1473

1474
# Linear algebra example
1475
A = cp.Parameter((4, 5))
1476
x = cp.Variable(5)
1477
b = cp.Parameter(4)
1478

1479
# Matrix-vector operations
1480
Ax = A @ x  # or cp.matmul(A, x)
1481
residual = Ax - b
1482
objective = cp.Minimize(cp.sum_squares(residual))
1483

1484
# Norm constraints
1485
constraints = [
1486
    cp.norm(x, 1) <= 1,  # L1 constraint (sparse)
1487
    cp.norm(x, 2) <= 2,  # L2 constraint (bounded)
1488
    cp.norm(x, 'inf') <= 0.5  # Infinity norm constraint
1489
]
1490

1491
# Portfolio optimization with different objectives
1492
n = 10
1493
w = cp.Variable(n)  # portfolio weights
1494
mu = cp.Parameter(n)  # expected returns
1495
Sigma = cp.Parameter((n, n), PSD=True)  # covariance matrix
1496

1497
# Different risk measures
1498
variance_risk = cp.quad_form(w, Sigma)
1499
mad_risk = cp.norm(w, 1)  # mean absolute deviation proxy
1500
max_weight_risk = cp.norm(w, 'inf')  # concentration risk
1501

1502
# Utility functions
1503
log_utility = cp.sum(cp.log(w))  # log utility (must have w > 0)
1504
entropy_regularization = cp.sum(cp.entr(w))  # entropy regularization
1505

1506
# Matrix completion problem
1507
m, n = 20, 15
1508
X = cp.Variable((m, n))
1509
mask = np.random.binomial(1, 0.3, (m, n))  # observed entries
1510
Y_obs = cp.Parameter((m, n))  # observed values
1511

1512
# Nuclear norm minimization (low-rank recovery)
1513
objective = cp.Minimize(cp.norm(X, 'nuc'))
1514
observed_constraints = [X[i, j] == Y_obs[i, j] for i, j in zip(*np.where(mask))]
1515

1516
matrix_completion = cp.Problem(objective, observed_constraints)
1517

1518
# Robust optimization with Huber loss
1519
data_fit = cp.sum(cp.huber(A @ x - b, M=1.0))
1520
robust_objective = cp.Minimize(data_fit + 0.1 * cp.norm(x, 1))
1521

1522
# Geometric programming (requires DGP mode)
1523
x = cp.Variable(pos=True)
1524
y = cp.Variable(pos=True)
1525
gp_objective = cp.Minimize(x * y)
1526
gp_constraints = [x + y == 1, cp.geo_mean([x, y]) >= 0.1]
1527
gp_problem = cp.Problem(gp_objective, gp_constraints)
1528
gp_problem.solve(gp=True)
1529
```