0
# Mathematical Functions
1

2
Comprehensive mathematical operations performed on GPU with NumPy-compatible interfaces. These functions provide GPU-accelerated computation for trigonometric, hyperbolic, exponential, logarithmic, arithmetic, and special mathematical functions.
3

4
## Capabilities
5

6
### Trigonometric Functions
7

8
Standard trigonometric functions with GPU acceleration, supporting both scalar and array inputs.
9

10
```python { .api }
11
def sin(x, out=None, **kwargs):
12
    """
13
    Sine function.
14
    
15
    Parameters:
16
    - x: array-like, input array
17
    - out: array, output array, optional
18
    
19
    Returns:
20
    cupy.ndarray: Sine of input on GPU
21
    """
22

23
def cos(x, out=None, **kwargs):
24
    """
25
    Cosine function.
26
    
27
    Parameters:
28
    - x: array-like, input array
29
    - out: array, output array, optional
30
    
31
    Returns:
32
    cupy.ndarray: Cosine of input on GPU
33
    """
34

35
def tan(x, out=None, **kwargs):
36
    """
37
    Tangent function.
38
    
39
    Parameters:
40
    - x: array-like, input array
41
    - out: array, output array, optional
42
    
43
    Returns:
44
    cupy.ndarray: Tangent of input on GPU
45
    """
46

47
def arcsin(x, out=None, **kwargs):
48
    """
49
    Inverse sine function.
50
    
51
    Parameters:
52
    - x: array-like, input array in [-1, 1]
53
    - out: array, output array, optional
54
    
55
    Returns:
56
    cupy.ndarray: Arcsine of input on GPU
57
    """
58

59
def arccos(x, out=None, **kwargs):
60
    """
61
    Inverse cosine function.
62
    
63
    Parameters:
64
    - x: array-like, input array in [-1, 1]
65
    - out: array, output array, optional
66
    
67
    Returns:
68
    cupy.ndarray: Arccosine of input on GPU
69
    """
70

71
def arctan(x, out=None, **kwargs):
72
    """
73
    Inverse tangent function.
74
    
75
    Parameters:
76
    - x: array-like, input array
77
    - out: array, output array, optional
78
    
79
    Returns:
80
    cupy.ndarray: Arctangent of input on GPU
81
    """
82

83
def arctan2(y, x, out=None, **kwargs):
84
    """
85
    Element-wise arc tangent of y/x.
86
    
87
    Parameters:
88
    - y: array-like, y coordinates
89
    - x: array-like, x coordinates
90
    - out: array, output array, optional
91
    
92
    Returns:
93
    cupy.ndarray: Arctangent of y/x on GPU
94
    """
95

96
def hypot(x1, x2, out=None, **kwargs):
97
    """
98
    Element-wise hypotenuse given legs of right triangle.
99
    
100
    Parameters:
101
    - x1: array-like, first leg
102
    - x2: array-like, second leg
103
    - out: array, output array, optional
104
    
105
    Returns:
106
    cupy.ndarray: Hypotenuse sqrt(x1**2 + x2**2) on GPU
107
    """
108

109
def degrees(x, out=None, **kwargs):
110
    """
111
    Convert angles from radians to degrees.
112
    
113
    Parameters:
114
    - x: array-like, input in radians
115
    - out: array, output array, optional
116
    
117
    Returns:
118
    cupy.ndarray: Angles in degrees on GPU
119
    """
120

121
def radians(x, out=None, **kwargs):
122
    """
123
    Convert angles from degrees to radians.
124
    
125
    Parameters:
126
    - x: array-like, input in degrees
127
    - out: array, output array, optional
128
    
129
    Returns:
130
    cupy.ndarray: Angles in radians on GPU
131
    """
132
```
133

134
### Hyperbolic Functions
135

136
Hyperbolic trigonometric functions for advanced mathematical computations.
137

138
```python { .api }
139
def sinh(x, out=None, **kwargs):
140
    """
141
    Hyperbolic sine function.
142
    
143
    Parameters:
144
    - x: array-like, input array
145
    - out: array, output array, optional
146
    
147
    Returns:
148
    cupy.ndarray: Hyperbolic sine of input on GPU
149
    """
150

151
def cosh(x, out=None, **kwargs):
152
    """
153
    Hyperbolic cosine function.
154
    
155
    Parameters:
156
    - x: array-like, input array
157
    - out: array, output array, optional
158
    
159
    Returns:
160
    cupy.ndarray: Hyperbolic cosine of input on GPU
161
    """
162

163
def tanh(x, out=None, **kwargs):
164
    """
165
    Hyperbolic tangent function.
166
    
167
    Parameters:
168
    - x: array-like, input array
169
    - out: array, output array, optional
170
    
171
    Returns:
172
    cupy.ndarray: Hyperbolic tangent of input on GPU
173
    """
174

175
def arcsinh(x, out=None, **kwargs):
176
    """
177
    Inverse hyperbolic sine function.
178
    
179
    Parameters:
180
    - x: array-like, input array
181
    - out: array, output array, optional
182
    
183
    Returns:
184
    cupy.ndarray: Inverse hyperbolic sine of input on GPU
185
    """
186

187
def arccosh(x, out=None, **kwargs):
188
    """
189
    Inverse hyperbolic cosine function.
190
    
191
    Parameters:
192
    - x: array-like, input array >= 1
193
    - out: array, output array, optional
194
    
195
    Returns:
196
    cupy.ndarray: Inverse hyperbolic cosine of input on GPU
197
    """
198

199
def arctanh(x, out=None, **kwargs):
200
    """
201
    Inverse hyperbolic tangent function.
202
    
203
    Parameters:
204
    - x: array-like, input array in (-1, 1)
205
    - out: array, output array, optional
206
    
207
    Returns:
208
    cupy.ndarray: Inverse hyperbolic tangent of input on GPU
209
    """
210
```
211

212
### Exponential and Logarithmic Functions
213

214
Exponential and logarithmic functions with various bases and special cases.
215

216
```python { .api }
217
def exp(x, out=None, **kwargs):
218
    """
219
    Exponential function e^x.
220
    
221
    Parameters:
222
    - x: array-like, input array
223
    - out: array, output array, optional
224
    
225
    Returns:
226
    cupy.ndarray: Exponential of input on GPU
227
    """
228

229
def exp2(x, out=None, **kwargs):
230
    """
231
    Base-2 exponential function 2^x.
232
    
233
    Parameters:
234
    - x: array-like, input array
235
    - out: array, output array, optional
236
    
237
    Returns:
238
    cupy.ndarray: Base-2 exponential of input on GPU
239
    """
240

241
def expm1(x, out=None, **kwargs):
242
    """
243
    Exponential minus one: exp(x) - 1.
244
    
245
    Parameters:
246
    - x: array-like, input array
247
    - out: array, output array, optional
248
    
249
    Returns:
250
    cupy.ndarray: exp(x) - 1 on GPU
251
    """
252

253
def log(x, out=None, **kwargs):
254
    """
255
    Natural logarithm.
256
    
257
    Parameters:
258
    - x: array-like, input array > 0
259
    - out: array, output array, optional
260
    
261
    Returns:
262
    cupy.ndarray: Natural logarithm of input on GPU
263
    """
264

265
def log2(x, out=None, **kwargs):
266
    """
267
    Base-2 logarithm.
268
    
269
    Parameters:
270
    - x: array-like, input array > 0
271
    - out: array, output array, optional
272
    
273
    Returns:
274
    cupy.ndarray: Base-2 logarithm of input on GPU
275
    """
276

277
def log10(x, out=None, **kwargs):
278
    """
279
    Base-10 logarithm.
280
    
281
    Parameters:
282
    - x: array-like, input array > 0
283
    - out: array, output array, optional
284
    
285
    Returns:
286
    cupy.ndarray: Base-10 logarithm of input on GPU
287
    """
288

289
def log1p(x, out=None, **kwargs):
290
    """
291
    Logarithm of one plus input: log(1 + x).
292
    
293
    Parameters:
294
    - x: array-like, input array > -1
295
    - out: array, output array, optional
296
    
297
    Returns:
298
    cupy.ndarray: log(1 + x) on GPU
299
    """
300

301
def logaddexp(x1, x2, out=None, **kwargs):
302
    """
303
    Logarithm of sum of exponentials: log(exp(x1) + exp(x2)).
304
    
305
    Parameters:
306
    - x1: array-like, first input array
307
    - x2: array-like, second input array
308
    - out: array, output array, optional
309
    
310
    Returns:
311
    cupy.ndarray: log(exp(x1) + exp(x2)) on GPU
312
    """
313

314
def logaddexp2(x1, x2, out=None, **kwargs):
315
    """
316
    Base-2 logarithm of sum of powers: log2(2^x1 + 2^x2).
317
    
318
    Parameters:
319
    - x1: array-like, first input array
320
    - x2: array-like, second input array
321
    - out: array, output array, optional
322
    
323
    Returns:
324
    cupy.ndarray: log2(2^x1 + 2^x2) on GPU
325
    """
326
```
327

328
### Arithmetic Functions
329

330
Basic arithmetic operations with broadcasting support and GPU acceleration.
331

332
```python { .api }
333
def add(x1, x2, out=None, **kwargs):
334
    """
335
    Addition of arrays element-wise.
336
    
337
    Parameters:
338
    - x1: array-like, first input array
339
    - x2: array-like, second input array
340
    - out: array, output array, optional
341
    
342
    Returns:
343
    cupy.ndarray: Element-wise sum on GPU
344
    """
345

346
def subtract(x1, x2, out=None, **kwargs):
347
    """
348
    Subtraction of arrays element-wise.
349
    
350
    Parameters:
351
    - x1: array-like, first input array
352
    - x2: array-like, second input array
353
    - out: array, output array, optional
354
    
355
    Returns:
356
    cupy.ndarray: Element-wise difference on GPU
357
    """
358

359
def multiply(x1, x2, out=None, **kwargs):
360
    """
361
    Multiplication of arrays element-wise.
362
    
363
    Parameters:
364
    - x1: array-like, first input array
365
    - x2: array-like, second input array
366
    - out: array, output array, optional
367
    
368
    Returns:
369
    cupy.ndarray: Element-wise product on GPU
370
    """
371

372
def divide(x1, x2, out=None, **kwargs):
373
    """
374
    Division of arrays element-wise.
375
    
376
    Parameters:
377
    - x1: array-like, dividend array
378
    - x2: array-like, divisor array
379
    - out: array, output array, optional
380
    
381
    Returns:
382
    cupy.ndarray: Element-wise quotient on GPU
383
    """
384

385
def true_divide(x1, x2, out=None, **kwargs):
386
    """
387
    True division of arrays element-wise.
388
    
389
    Parameters:
390
    - x1: array-like, dividend array
391
    - x2: array-like, divisor array  
392
    - out: array, output array, optional
393
    
394
    Returns:
395
    cupy.ndarray: Element-wise true division on GPU
396
    """
397

398
def floor_divide(x1, x2, out=None, **kwargs):
399
    """
400
    Floor division of arrays element-wise.
401
    
402
    Parameters:
403
    - x1: array-like, dividend array
404
    - x2: array-like, divisor array
405
    - out: array, output array, optional
406
    
407
    Returns:
408
    cupy.ndarray: Element-wise floor division on GPU
409
    """
410

411
def power(x1, x2, out=None, **kwargs):
412
    """
413
    Element-wise power function.
414
    
415
    Parameters:
416
    - x1: array-like, base array
417
    - x2: array-like, exponent array
418
    - out: array, output array, optional
419
    
420
    Returns:
421
    cupy.ndarray: Element-wise x1^x2 on GPU
422
    """
423

424
def remainder(x1, x2, out=None, **kwargs):
425
    """
426
    Remainder of division element-wise.
427
    
428
    Parameters:
429
    - x1: array-like, dividend array
430
    - x2: array-like, divisor array
431
    - out: array, output array, optional
432
    
433
    Returns:
434
    cupy.ndarray: Element-wise remainder on GPU
435
    """
436

437
def negative(x, out=None, **kwargs):
438
    """
439
    Numerical negative element-wise.
440
    
441
    Parameters:
442
    - x: array-like, input array
443
    - out: array, output array, optional
444
    
445
    Returns:
446
    cupy.ndarray: Negative of input on GPU
447
    """
448

449
def absolute(x, out=None, **kwargs):
450
    """
451
    Absolute value element-wise.
452
    
453
    Parameters:
454
    - x: array-like, input array
455
    - out: array, output array, optional
456
    
457
    Returns:
458
    cupy.ndarray: Absolute value of input on GPU
459
    """
460
```
461

462
### Rounding Functions
463

464
Functions for rounding numbers to integers or specified decimal places.
465

466
```python { .api }
467
def around(a, decimals=0, out=None):
468
    """
469
    Round to given number of decimals.
470
    
471
    Parameters:
472
    - a: array-like, input array
473
    - decimals: int, number of decimal places
474
    - out: array, output array, optional
475
    
476
    Returns:
477
    cupy.ndarray: Rounded array on GPU
478
    """
479

480
def round_(a, decimals=0, out=None):
481
    """
482
    Round to given number of decimals.
483
    
484
    Parameters:
485
    - a: array-like, input array
486
    - decimals: int, number of decimal places
487
    - out: array, output array, optional
488
    
489
    Returns:
490
    cupy.ndarray: Rounded array on GPU
491
    """
492

493
def rint(x, out=None, **kwargs):
494
    """
495
    Round to nearest integer.
496
    
497
    Parameters:
498
    - x: array-like, input array
499
    - out: array, output array, optional
500
    
501
    Returns:
502
    cupy.ndarray: Rounded to nearest integer on GPU
503
    """
504

505
def floor(x, out=None, **kwargs):
506
    """
507
    Floor function (round down).
508
    
509
    Parameters:
510
    - x: array-like, input array
511
    - out: array, output array, optional
512
    
513
    Returns:
514
    cupy.ndarray: Floor of input on GPU
515
    """
516

517
def ceil(x, out=None, **kwargs):
518
    """
519
    Ceiling function (round up).
520
    
521
    Parameters:
522
    - x: array-like, input array
523
    - out: array, output array, optional
524
    
525
    Returns:
526
    cupy.ndarray: Ceiling of input on GPU
527
    """
528

529
def trunc(x, out=None, **kwargs):
530
    """
531
    Truncate towards zero.
532
    
533
    Parameters:
534
    - x: array-like, input array
535
    - out: array, output array, optional
536
    
537
    Returns:
538
    cupy.ndarray: Truncated values on GPU
539
    """
540
```
541

542
### Miscellaneous Mathematical Functions
543

544
Additional mathematical functions including roots, extrema, and special operations.
545

546
```python { .api }
547
def sqrt(x, out=None, **kwargs):
548
    """
549
    Square root function.
550
    
551
    Parameters:
552
    - x: array-like, input array >= 0
553
    - out: array, output array, optional
554
    
555
    Returns:
556
    cupy.ndarray: Square root of input on GPU
557
    """
558

559
def cbrt(x, out=None, **kwargs):
560
    """
561
    Cube root function.
562
    
563
    Parameters:
564
    - x: array-like, input array
565
    - out: array, output array, optional
566
    
567
    Returns:
568
    cupy.ndarray: Cube root of input on GPU
569
    """
570

571
def square(x, out=None, **kwargs):
572
    """
573
    Square function.
574
    
575
    Parameters:
576
    - x: array-like, input array
577
    - out: array, output array, optional
578
    
579
    Returns:
580
    cupy.ndarray: Square of input on GPU
581
    """
582

583
def sign(x, out=None, **kwargs):
584
    """
585
    Sign function.
586
    
587
    Parameters:
588
    - x: array-like, input array
589
    - out: array, output array, optional
590
    
591
    Returns:
592
    cupy.ndarray: Sign of input (-1, 0, 1) on GPU
593
    """
594

595
def maximum(x1, x2, out=None, **kwargs):
596
    """
597
    Element-wise maximum.
598
    
599
    Parameters:
600
    - x1: array-like, first input array
601
    - x2: array-like, second input array
602
    - out: array, output array, optional
603
    
604
    Returns:
605
    cupy.ndarray: Element-wise maximum on GPU
606
    """
607

608
def minimum(x1, x2, out=None, **kwargs):
609
    """
610
    Element-wise minimum.
611
    
612
    Parameters:
613
    - x1: array-like, first input array
614
    - x2: array-like, second input array
615
    - out: array, output array, optional
616
    
617
    Returns:
618
    cupy.ndarray: Element-wise minimum on GPU
619
    """
620

621
def clip(a, a_min, a_max, out=None, **kwargs):
622
    """
623
    Clip values to range.
624
    
625
    Parameters:
626
    - a: array-like, input array
627
    - a_min: scalar or array, minimum value
628
    - a_max: scalar or array, maximum value
629
    - out: array, output array, optional
630
    
631
    Returns:
632
    cupy.ndarray: Clipped array on GPU
633
    """
634
```
635

636
### Sum and Product Functions
637

638
Aggregation functions for computing sums, products, and cumulative operations.
639

640
```python { .api }
641
def sum(a, axis=None, dtype=None, out=None, keepdims=False, initial=None, where=True):
642
    """
643
    Sum of array elements over given axes.
644
    
645
    Parameters:
646
    - a: array-like, input array
647
    - axis: int or tuple, axes to sum over, optional
648
    - dtype: data type, result data type, optional
649
    - out: array, output array, optional
650
    - keepdims: bool, keep dimensions
651
    - initial: scalar, initial value, optional
652
    - where: array, condition, optional
653
    
654
    Returns:
655
    cupy.ndarray: Sum along specified axes on GPU
656
    """
657

658
def prod(a, axis=None, dtype=None, out=None, keepdims=False, initial=None, where=True):
659
    """
660
    Product of array elements over given axes.
661
    
662
    Parameters:
663
    - a: array-like, input array
664
    - axis: int or tuple, axes to multiply over, optional
665
    - dtype: data type, result data type, optional
666
    - out: array, output array, optional
667
    - keepdims: bool, keep dimensions
668
    - initial: scalar, initial value, optional
669
    - where: array, condition, optional
670
    
671
    Returns:
672
    cupy.ndarray: Product along specified axes on GPU
673
    """
674

675
def cumsum(a, axis=None, dtype=None, out=None):
676
    """
677
    Cumulative sum along axis.
678
    
679
    Parameters:
680
    - a: array-like, input array
681
    - axis: int, axis for cumulative sum, optional
682
    - dtype: data type, result data type, optional
683
    - out: array, output array, optional
684
    
685
    Returns:
686
    cupy.ndarray: Cumulative sum on GPU
687
    """
688

689
def cumprod(a, axis=None, dtype=None, out=None):
690
    """
691
    Cumulative product along axis.
692
    
693
    Parameters:
694
    - a: array-like, input array
695
    - axis: int, axis for cumulative product, optional
696
    - dtype: data type, result data type, optional
697
    - out: array, output array, optional
698
    
699
    Returns:
700
    cupy.ndarray: Cumulative product on GPU
701
    """
702
```
703

704
## Usage Examples
705

706
### Basic Mathematical Operations
707

708
```python
709
import cupy as cp
710
import numpy as np
711

712
# Create test arrays
713
x = cp.linspace(0, 2*cp.pi, 1000)
714
y = cp.array([[1, 2, 3], [4, 5, 6]], dtype=cp.float32)
715

716
# Trigonometric functions
717
sin_x = cp.sin(x)
718
cos_x = cp.cos(x)
719
tan_half = cp.tan(x/2)
720

721
# Exponential and logarithmic
722
exp_y = cp.exp(y)
723
log_y = cp.log(y)
724
sqrt_y = cp.sqrt(y)
725

726
# Element-wise arithmetic
727
z = cp.add(y, 10)  # Broadcasting
728
product = cp.multiply(y, y)  # Element-wise square
729
```
730

731
### Advanced Mathematical Operations
732

733
```python
734
# Complex mathematical expressions
735
amplitude = cp.sqrt(cp.add(cp.square(sin_x), cp.square(cos_x)))
736
phase = cp.arctan2(sin_x, cos_x)
737

738
# Aggregation operations
739
total = cp.sum(y)
740
row_sums = cp.sum(y, axis=1)
741
cumulative = cp.cumsum(y.flatten())
742

743
# Rounding and clipping
744
rounded = cp.around(y * 1.7, decimals=1)
745
clipped = cp.clip(y, 2, 5)
746
```