0
# Mathematical Operations
1

2
Element-wise mathematical functions including trigonometric, logarithmic, arithmetic, and comparison operations. All functions support broadcasting and operate on GPU arrays with the same semantics as NumPy ufuncs.
3

4
## Capabilities
5

6
### Arithmetic Operations
7

8
Basic arithmetic operations supporting broadcasting between arrays and scalars.
9

10
```python { .api }
11
def add(x1, x2, /, out=None):
12
    """
13
    Add elements element-wise.
14
    
15
    Parameters:
16
    - x1, x2: array-like, input arrays
17
    - out: cupy.ndarray, output array
18
    
19
    Returns:
20
    cupy.ndarray: Element-wise sum
21
    """
22

23
def subtract(x1, x2, /, out=None):
24
    """Subtract elements element-wise."""
25

26
def multiply(x1, x2, /, out=None):
27
    """Multiply elements element-wise."""
28

29
def divide(x1, x2, /, out=None):
30
    """Divide elements element-wise."""
31

32
def true_divide(x1, x2, /, out=None):
33
    """True division element-wise."""
34

35
def floor_divide(x1, x2, /, out=None):
36
    """Floor division element-wise."""
37

38
def power(x1, x2, /, out=None):
39
    """
40
    Raise x1 to power x2 element-wise.
41
    
42
    Parameters:
43
    - x1: array-like, base values
44
    - x2: array-like, exponent values  
45
    - out: cupy.ndarray, output array
46
    
47
    Returns:
48
    cupy.ndarray: x1**x2 element-wise
49
    """
50

51
def float_power(x1, x2, /, out=None):
52
    """x1**x2 element-wise with float result."""
53

54
def remainder(x1, x2, /, out=None):
55
    """Remainder of division element-wise."""
56

57
def mod(x1, x2, /, out=None):
58
    """Remainder of division element-wise (alias for remainder)."""
59

60
def divmod(x1, x2, /, out1=None, out2=None):
61
    """
62
    Element-wise divmod operation.
63
    
64
    Parameters:
65
    - x1, x2: array-like, input arrays
66
    - out1, out2: cupy.ndarray, output arrays for quotient and remainder
67
    
68
    Returns:
69
    tuple: (quotient, remainder)
70
    """
71
```
72

73
### Unary Operations
74

75
Operations on single arrays including negation, absolute value, and sign.
76

77
```python { .api }
78
def negative(x, /, out=None):
79
    """
80
    Numerical negative element-wise.
81
    
82
    Parameters:
83
    - x: array-like, input array
84
    - out: cupy.ndarray, output array
85
    
86
    Returns:
87
    cupy.ndarray: -x element-wise
88
    """
89

90
def positive(x, /, out=None):
91
    """Numerical positive element-wise."""
92

93
def absolute(x, /, out=None):
94
    """
95
    Absolute value element-wise.
96
    
97
    Parameters:
98
    - x: array-like, input array
99
    - out: cupy.ndarray, output array
100
    
101
    Returns:
102
    cupy.ndarray: |x| element-wise
103
    """
104

105
def abs(x, /, out=None):
106
    """Absolute value element-wise (alias for absolute)."""
107

108
def fabs(x, /, out=None):
109
    """Absolute value element-wise (for real inputs)."""
110

111
def sign(x, /, out=None):
112
    """
113
    Sign of elements element-wise.
114
    
115
    Parameters:
116
    - x: array-like, input array
117
    - out: cupy.ndarray, output array
118
    
119
    Returns:
120
    cupy.ndarray: Sign of x (-1, 0, or 1)
121
    """
122

123
def reciprocal(x, /, out=None):
124
    """Reciprocal (1/x) element-wise."""
125

126
def square(x, /, out=None):
127
    """Square element-wise."""
128

129
def sqrt(x, /, out=None):
130
    """
131
    Square root element-wise.
132
    
133
    Parameters:
134
    - x: array-like, input array
135
    - out: cupy.ndarray, output array
136
    
137
    Returns:
138
    cupy.ndarray: sqrt(x) element-wise
139
    """
140

141
def cbrt(x, /, out=None):
142
    """Cube root element-wise."""
143
```
144

145
### Trigonometric Functions
146

147
Trigonometric operations in radians.
148

149
```python { .api }
150
def sin(x, /, out=None):
151
    """
152
    Trigonometric sine element-wise.
153
    
154
    Parameters:
155
    - x: array-like, input array in radians
156
    - out: cupy.ndarray, output array
157
    
158
    Returns:
159
    cupy.ndarray: sin(x) element-wise
160
    """
161

162
def cos(x, /, out=None):
163
    """Trigonometric cosine element-wise."""
164

165
def tan(x, /, out=None):
166
    """Trigonometric tangent element-wise."""
167

168
def arcsin(x, /, out=None):
169
    """Inverse sine element-wise."""
170

171
def arccos(x, /, out=None):
172
    """Inverse cosine element-wise."""
173

174
def arctan(x, /, out=None):
175
    """Inverse tangent element-wise."""
176

177
def arctan2(x1, x2, /, out=None):
178
    """
179
    Element-wise arc tangent of x1/x2.
180
    
181
    Parameters:
182
    - x1: array-like, y-coordinates
183
    - x2: array-like, x-coordinates
184
    - out: cupy.ndarray, output array
185
    
186
    Returns:
187
    cupy.ndarray: atan2(x1, x2) in range [-pi, pi]
188
    """
189

190
def hypot(x1, x2, /, out=None):
191
    """
192
    Euclidean distance sqrt(x1²+x2²) element-wise.
193
    
194
    Parameters:
195
    - x1, x2: array-like, input arrays
196
    - out: cupy.ndarray, output array
197
    
198
    Returns:
199
    cupy.ndarray: sqrt(x1**2 + x2**2)
200
    """
201
```
202

203
### Hyperbolic Functions
204

205
Hyperbolic trigonometric functions.
206

207
```python { .api }
208
def sinh(x, /, out=None):
209
    """
210
    Hyperbolic sine element-wise.
211
    
212
    Parameters:
213
    - x: array-like, input array
214
    - out: cupy.ndarray, output array
215
    
216
    Returns:
217
    cupy.ndarray: sinh(x) element-wise
218
    """
219

220
def cosh(x, /, out=None):
221
    """Hyperbolic cosine element-wise."""
222

223
def tanh(x, /, out=None):
224
    """Hyperbolic tangent element-wise."""
225

226
def arcsinh(x, /, out=None):
227
    """Inverse hyperbolic sine element-wise."""
228

229
def arccosh(x, /, out=None):
230
    """Inverse hyperbolic cosine element-wise."""
231

232
def arctanh(x, /, out=None):
233
    """Inverse hyperbolic tangent element-wise."""
234
```
235

236
### Exponential and Logarithmic Functions
237

238
Exponential, logarithmic, and power functions.
239

240
```python { .api }
241
def exp(x, /, out=None):
242
    """
243
    Exponential function element-wise.
244
    
245
    Parameters:
246
    - x: array-like, input array
247
    - out: cupy.ndarray, output array
248
    
249
    Returns:
250
    cupy.ndarray: e**x element-wise
251
    """
252

253
def exp2(x, /, out=None):
254
    """2**x element-wise."""
255

256
def expm1(x, /, out=None):
257
    """exp(x) - 1 element-wise (more accurate for small x)."""
258

259
def log(x, /, out=None):
260
    """
261
    Natural logarithm element-wise.
262
    
263
    Parameters:
264
    - x: array-like, input array
265
    - out: cupy.ndarray, output array
266
    
267
    Returns:
268
    cupy.ndarray: ln(x) element-wise
269
    """
270

271
def log2(x, /, out=None):
272
    """Base-2 logarithm element-wise."""
273

274
def log10(x, /, out=None):
275
    """Base-10 logarithm element-wise."""
276

277
def log1p(x, /, out=None):
278
    """log(1 + x) element-wise (more accurate for small x)."""
279

280
def logaddexp(x1, x2, /, out=None):
281
    """
282
    log(exp(x1) + exp(x2)) element-wise.
283
    
284
    Parameters:
285
    - x1, x2: array-like, input arrays
286
    - out: cupy.ndarray, output array
287
    
288
    Returns:
289
    cupy.ndarray: Numerically stable log(exp(x1) + exp(x2))
290
    """
291

292
def logaddexp2(x1, x2, /, out=None):
293
    """log2(2**x1 + 2**x2) element-wise."""
294
```
295

296
### Rounding Functions
297

298
Functions for rounding and truncating values.
299

300
```python { .api }
301
def around(a, decimals=0, out=None):
302
    """
303
    Round to given number of decimals.
304
    
305
    Parameters:
306
    - a: array-like, input array
307
    - decimals: int, number of decimals to round to
308
    - out: cupy.ndarray, output array
309
    
310
    Returns:
311
    cupy.ndarray: Rounded values
312
    """
313

314
def round(a, decimals=0, out=None):
315
    """Round to given number of decimals (alias for around)."""
316

317
def rint(x, /, out=None):
318
    """Round to nearest integer."""
319

320
def floor(x, /, out=None):
321
    """Floor of input element-wise."""
322

323
def ceil(x, /, out=None):
324
    """Ceiling of input element-wise."""
325

326
def trunc(x, /, out=None):
327
    """Truncate to integers element-wise."""
328

329
def fix(x, out=None):
330
    """Round to nearest integer towards zero."""
331
```
332

333
### Comparison Operations
334

335
Element-wise comparison functions returning boolean arrays.
336

337
```python { .api }
338
def equal(x1, x2, /, out=None):
339
    """
340
    Element-wise equality comparison.
341
    
342
    Parameters:
343
    - x1, x2: array-like, input arrays
344
    - out: cupy.ndarray, output boolean array
345
    
346
    Returns:
347
    cupy.ndarray: Boolean array of x1 == x2
348
    """
349

350
def not_equal(x1, x2, /, out=None):
351
    """Element-wise inequality comparison."""
352

353
def less(x1, x2, /, out=None):
354
    """Element-wise less-than comparison."""
355

356
def less_equal(x1, x2, /, out=None):
357
    """Element-wise less-than-or-equal comparison."""
358

359
def greater(x1, x2, /, out=None):
360
    """Element-wise greater-than comparison."""
361

362
def greater_equal(x1, x2, /, out=None):
363
    """Element-wise greater-than-or-equal comparison."""
364
```
365

366
### Complex Number Functions
367

368
Operations for complex numbers.
369

370
```python { .api }
371
def real(val):
372
    """
373
    Real part of complex values.
374
    
375
    Parameters:
376
    - val: array-like, input array
377
    
378
    Returns:
379
    cupy.ndarray: Real components
380
    """
381

382
def imag(val):
383
    """Imaginary part of complex values."""
384

385
def conjugate(x, /, out=None):
386
    """
387
    Complex conjugate element-wise.
388
    
389
    Parameters:
390
    - x: array-like, input array
391
    - out: cupy.ndarray, output array
392
    
393
    Returns:
394
    cupy.ndarray: Complex conjugate of x
395
    """
396

397
def conj(x, /, out=None):
398
    """Complex conjugate element-wise (alias for conjugate)."""
399

400
def angle(z, deg=False):
401
    """
402
    Argument of complex values.
403
    
404
    Parameters:
405
    - z: array-like, complex input array
406
    - deg: bool, return angle in degrees if True
407
    
408
    Returns:
409
    cupy.ndarray: Angles in radians (or degrees)
410
    """
411
```
412

413
### Minimum/Maximum Operations
414

415
Element-wise minimum and maximum operations.
416

417
```python { .api }
418
def maximum(x1, x2, /, out=None):
419
    """
420
    Element-wise maximum.
421
    
422
    Parameters:
423
    - x1, x2: array-like, input arrays
424
    - out: cupy.ndarray, output array
425
    
426
    Returns:
427
    cupy.ndarray: Element-wise maximum values
428
    """
429

430
def minimum(x1, x2, /, out=None):
431
    """Element-wise minimum."""
432

433
def fmax(x1, x2, /, out=None):
434
    """Element-wise maximum, ignoring NaNs."""
435

436
def fmin(x1, x2, /, out=None):
437
    """Element-wise minimum, ignoring NaNs."""
438

439
def clip(a, a_min, a_max, out=None):
440
    """
441
    Clip values to range [a_min, a_max].
442
    
443
    Parameters:
444
    - a: array-like, input array
445
    - a_min: scalar or array, minimum value
446
    - a_max: scalar or array, maximum value  
447
    - out: cupy.ndarray, output array
448
    
449
    Returns:
450
    cupy.ndarray: Clipped values
451
    """
452
```
453

454
### Reduction Operations
455

456
Operations that reduce arrays along axes.
457

458
```python { .api }
459
def sum(a, axis=None, dtype=None, out=None, keepdims=False, initial=None, where=None):
460
    """
461
    Sum of array elements over given axes.
462
    
463
    Parameters:
464
    - a: array-like, input array
465
    - axis: None or int or tuple of ints, axes to sum over
466
    - dtype: data type, type of output
467
    - out: cupy.ndarray, output array
468
    - keepdims: bool, keep reduced dimensions as size 1
469
    - initial: scalar, starting value for sum
470
    - where: array of bool, elements to include
471
    
472
    Returns:
473
    cupy.ndarray: Sum along specified axes
474
    """
475

476
def prod(a, axis=None, dtype=None, out=None, keepdims=False, initial=None, where=None):
477
    """Product of array elements over given axes."""
478

479
def mean(a, axis=None, dtype=None, out=None, keepdims=False):
480
    """Mean of array elements over given axes."""
481

482
def cumsum(a, axis=None, dtype=None, out=None):
483
    """
484
    Cumulative sum along axis.
485
    
486
    Parameters:
487
    - a: array-like, input array
488
    - axis: int, axis along which to compute cumsum
489
    - dtype: data type, type of output
490
    - out: cupy.ndarray, output array
491
    
492
    Returns:
493
    cupy.ndarray: Cumulative sum
494
    """
495

496
def cumprod(a, axis=None, dtype=None, out=None):
497
    """Cumulative product along axis."""
498

499
def diff(a, n=1, axis=-1, prepend=None, append=None):
500
    """
501
    Discrete difference along given axis.
502
    
503
    Parameters:
504
    - a: array-like, input array
505
    - n: int, number of times to difference
506
    - axis: int, axis along which to difference
507
    - prepend: array-like, values to prepend
508
    - append: array-like, values to append
509
    
510
    Returns:
511
    cupy.ndarray: Differences
512
    """
513
```
514

515
### Special Mathematical Functions
516

517
Specialized mathematical functions.
518

519
```python { .api }
520
def sinc(x):
521
    """
522
    Sinc function: sin(πx)/(πx).
523
    
524
    Parameters:
525
    - x: array-like, input array
526
    
527
    Returns:
528
    cupy.ndarray: sinc(x) element-wise
529
    """
530

531
def heaviside(x1, x2, /, out=None):
532
    """
533
    Heaviside step function.
534
    
535
    Parameters:
536
    - x1: array-like, input values
537
    - x2: array-like, value at x1 == 0
538
    - out: cupy.ndarray, output array
539
    
540
    Returns:
541
    cupy.ndarray: Heaviside function values
542
    """
543

544
def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None):
545
    """
546
    Replace NaN/Inf with finite numbers.
547
    
548
    Parameters:
549
    - x: array-like, input array
550
    - copy: bool, whether to create copy
551
    - nan: scalar, value to replace NaN with
552
    - posinf: scalar, value to replace +inf with
553
    - neginf: scalar, value to replace -inf with
554
    
555
    Returns:
556
    cupy.ndarray: Array with finite values
557
    """
558

559
def real_if_close(a, tol=100):
560
    """Return real part if imaginary part is close to zero."""
561

562
def interp(x, xp, fp, left=None, right=None, period=None):
563
    """
564
    One-dimensional linear interpolation.
565
    
566
    Parameters:
567
    - x: array-like, x-coordinates to interpolate at
568
    - xp: array-like, x-coordinates of data points
569
    - fp: array-like, y-coordinates of data points
570
    - left: scalar, value for x < xp[0]
571
    - right: scalar, value for x > xp[-1]
572
    - period: scalar, period for periodic interpolation
573
    
574
    Returns:
575
    cupy.ndarray: Interpolated values
576
    """
577
```
578

579
## Usage Examples
580

581
### Basic Arithmetic with Broadcasting
582

583
```python
584
import cupy as cp
585

586
# Element-wise operations
587
a = cp.array([1, 2, 3, 4])
588
b = cp.array([10, 20, 30, 40])
589

590
sum_result = cp.add(a, b)  # [11, 22, 33, 44]
591
prod_result = a * b        # Broadcasting works same as NumPy
592

593
# Scalar operations
594
scaled = a * 2.5
595
power_result = cp.power(a, 2)  # [1, 4, 9, 16]
596
```
597

598
### Complex Mathematical Operations
599

600
```python
601
# Trigonometric operations on ranges
602
x = cp.linspace(0, 2*cp.pi, 1000)
603
y = cp.sin(x)
604
phase = cp.arctan2(cp.sin(x), cp.cos(x))
605

606
# Logarithmic operations
607
data = cp.random.lognormal(0, 1, (1000,))
608
log_data = cp.log(data)
609
stable_sum = cp.logaddexp.reduce(log_data)
610
```
611

612
### Reductions and Aggregations
613

614
```python
615
# Statistical reductions
616
matrix = cp.random.random((1000, 1000))
617
row_sums = cp.sum(matrix, axis=1)
618
col_means = cp.mean(matrix, axis=0) 
619
total_sum = cp.sum(matrix)  # Sum all elements
620

621
# Cumulative operations
622
cumulative = cp.cumsum(matrix, axis=0)
623
running_product = cp.cumprod(matrix, axis=1)
624
```