0
# Mathematical Functions
1

2
Comprehensive mathematical operations providing GPU-accelerated versions of standard mathematical functions. All functions maintain NumPy compatibility while leveraging GPU parallelism for significant performance improvements.
3

4
## Capabilities
5

6
### Trigonometric Functions
7

8
Standard trigonometric functions for angle calculations and periodic operations.
9

10
```python { .api }
11
def sin(x):
12
    """
13
    Trigonometric sine, element-wise.
14
    
15
    Parameters:
16
    - x: array-like, input array in radians
17
    
18
    Returns:
19
    cupy.ndarray: Sine of each element
20
    """
21

22
def cos(x):
23
    """Trigonometric cosine, element-wise."""
24

25
def tan(x):
26
    """Trigonometric tangent, element-wise."""
27

28
def arcsin(x):
29
    """
30
    Inverse sine, element-wise.
31
    
32
    Parameters:
33
    - x: array-like, input array with values in [-1, 1]
34
    
35
    Returns:
36
    cupy.ndarray: Arcsine in radians, range [-pi/2, pi/2]
37
    """
38

39
def arccos(x):
40
    """Inverse cosine, element-wise."""
41

42
def arctan(x):
43
    """Inverse tangent, element-wise."""
44

45
def arctan2(y, x):
46
    """
47
    Element-wise arc tangent of y/x choosing quadrant correctly.
48
    
49
    Parameters:
50
    - y: array-like, y-coordinates
51
    - x: array-like, x-coordinates
52
    
53
    Returns:
54
    cupy.ndarray: Angle in radians, range [-pi, pi]
55
    """
56

57
def hypot(x1, x2):
58
    """
59
    Return sqrt(x1**2 + x2**2), element-wise.
60
    
61
    Parameters:
62
    - x1, x2: array-like, leg lengths of right triangle
63
    
64
    Returns:
65
    cupy.ndarray: Hypotenuse length
66
    """
67
```
68

69
### Hyperbolic Functions
70

71
Hyperbolic trigonometric functions for exponential relationships.
72

73
```python { .api }
74
def sinh(x):
75
    """
76
    Hyperbolic sine, element-wise.
77
    
78
    Parameters:
79
    - x: array-like, input array
80
    
81
    Returns:
82
    cupy.ndarray: Hyperbolic sine of each element
83
    """
84

85
def cosh(x):
86
    """Hyperbolic cosine, element-wise."""
87

88
def tanh(x):
89
    """Hyperbolic tangent, element-wise."""
90

91
def arcsinh(x):
92
    """Inverse hyperbolic sine, element-wise."""
93

94
def arccosh(x):
95
    """Inverse hyperbolic cosine, element-wise."""
96

97
def arctanh(x):
98
    """Inverse hyperbolic tangent, element-wise."""
99
```
100

101
### Exponential and Logarithmic Functions
102

103
Exponential and logarithmic operations for growth and scaling calculations.
104

105
```python { .api }
106
def exp(x):
107
    """
108
    Calculate exponential of all elements, e^x.
109
    
110
    Parameters:
111
    - x: array-like, input array
112
    
113
    Returns:
114
    cupy.ndarray: Exponential of each element
115
    """
116

117
def exp2(x):
118
    """Calculate 2^x for all elements."""
119

120
def expm1(x):
121
    """
122
    Calculate exp(x) - 1 for all elements.
123
    More accurate for x close to zero.
124
    """
125

126
def log(x):
127
    """
128
    Natural logarithm, element-wise.
129
    
130
    Parameters:
131
    - x: array-like, input array with positive values
132
    
133
    Returns:
134
    cupy.ndarray: Natural logarithm of each element
135
    """
136

137
def log10(x):
138
    """Base-10 logarithm, element-wise."""
139

140
def log2(x):
141
    """Base-2 logarithm, element-wise."""
142

143
def log1p(x):
144
    """
145
    Return ln(1 + x), element-wise.
146
    More accurate for x close to zero.
147
    """
148

149
def logaddexp(x1, x2):
150
    """
151
    Logarithm of sum of exponentials of inputs.
152
    Computes log(exp(x1) + exp(x2)) in numerically stable way.
153
    """
154

155
def logaddexp2(x1, x2):
156
    """Logarithm of sum of exponentials of inputs in base 2."""
157
```
158

159
### Arithmetic Operations
160

161
Basic arithmetic operations supporting broadcasting and element-wise computation.
162

163
```python { .api }
164
def add(x1, x2):
165
    """
166
    Add arguments element-wise.
167
    
168
    Parameters:
169
    - x1, x2: array-like, input arrays
170
    
171
    Returns:
172
    cupy.ndarray: Element-wise sum
173
    """
174

175
def subtract(x1, x2):
176
    """Subtract arguments element-wise."""
177

178
def multiply(x1, x2):
179
    """Multiply arguments element-wise."""
180

181
def divide(x1, x2):
182
    """Divide arguments element-wise."""
183

184
def true_divide(x1, x2):
185
    """True division, returns floating point result."""
186

187
def floor_divide(x1, x2):
188
    """Floor division, largest integer smaller than or equal to division."""
189

190
def power(x1, x2):
191
    """
192
    First array elements raised to powers from second array, element-wise.
193
    
194
    Parameters:
195
    - x1: array-like, base values
196
    - x2: array-like, exponent values
197
    
198
    Returns:
199
    cupy.ndarray: x1**x2 element-wise
200
    """
201

202
def float_power(x1, x2):
203
    """Power function that promotes integers to float."""
204

205
def remainder(x1, x2):
206
    """
207
    Return element-wise remainder of division.
208
    Same as x1 % x2.
209
    """
210

211
def mod(x1, x2):
212
    """Return element-wise remainder of division (alias for remainder)."""
213

214
def fmod(x1, x2):
215
    """Return element-wise remainder of division with same sign as dividend."""
216

217
def divmod(x1, x2):
218
    """
219
    Return element-wise quotient and remainder simultaneously.
220
    
221
    Returns:
222
    tuple: (floor_divide(x1, x2), remainder(x1, x2))
223
    """
224
```
225

226
### Rounding Functions
227

228
Functions for rounding and truncating floating-point values.
229

230
```python { .api }
231
def around(a, decimals=0):
232
    """
233
    Round array to given number of decimals.
234
    
235
    Parameters:
236
    - a: array-like, input array
237
    - decimals: int, number of decimal places to round to
238
    
239
    Returns:
240
    cupy.ndarray: Rounded array
241
    """
242

243
def round(a, decimals=0):
244
    """Round array to given number of decimals (alias for around)."""
245

246
def rint(x):
247
    """
248
    Round elements to nearest integer.
249
    
250
    Returns:
251
    cupy.ndarray: Rounded to nearest integer, dtype unchanged
252
    """
253

254
def ceil(x):
255
    """
256
    Return ceiling of input, element-wise.
257
    
258
    Returns:
259
    cupy.ndarray: Smallest integer >= x
260
    """
261

262
def floor(x):
263
    """
264
    Return floor of input, element-wise.
265
    
266
    Returns:
267
    cupy.ndarray: Largest integer <= x
268
    """
269

270
def trunc(x):
271
    """Return truncated value, element-wise."""
272

273
def fix(x):
274
    """Round to nearest integer towards zero."""
275
```
276

277
### Sign and Absolute Value Functions
278

279
Functions for handling signs and absolute values.
280

281
```python { .api }
282
def absolute(x):
283
    """
284
    Calculate absolute value element-wise.
285
    
286
    Parameters:
287
    - x: array-like, input array
288
    
289
    Returns:
290
    cupy.ndarray: Absolute values
291
    """
292

293
def abs(x):
294
    """Calculate absolute value element-wise (alias for absolute)."""
295

296
def fabs(x):
297
    """Absolute value, floating-point version."""
298

299
def sign(x):
300
    """
301
    Return element-wise indication of sign.
302
    
303
    Returns:
304
    cupy.ndarray: -1 for negative, 0 for zero, +1 for positive
305
    """
306

307
def copysign(x1, x2):
308
    """
309
    Change sign of x1 to match sign of x2, element-wise.
310
    
311
    Parameters:
312
    - x1: array-like, values to change sign of
313
    - x2: array-like, values whose signs are used
314
    
315
    Returns:
316
    cupy.ndarray: x1 with signs of x2
317
    """
318

319
def signbit(x):
320
    """
321
    Return element-wise True where signbit is set (less than zero).
322
    
323
    Returns:
324
    cupy.ndarray: Boolean array indicating sign bit
325
    """
326
```
327

328
### Comparison Functions
329

330
Element-wise comparison and extremum functions.
331

332
```python { .api }
333
def maximum(x1, x2):
334
    """
335
    Element-wise maximum of array elements.
336
    
337
    Parameters:
338
    - x1, x2: array-like, input arrays
339
    
340
    Returns:
341
    cupy.ndarray: Maximum values element-wise
342
    """
343

344
def minimum(x1, x2):
345
    """Element-wise minimum of array elements."""
346

347
def fmax(x1, x2):
348
    """Element-wise maximum, ignoring NaNs."""
349

350
def fmin(x1, x2):
351
    """Element-wise minimum, ignoring NaNs."""
352

353
def clip(a, a_min, a_max, out=None):
354
    """
355
    Clip values in array to specified range.
356
    
357
    Parameters:
358
    - a: array-like, input array
359
    - a_min: scalar or array, minimum value(s)
360
    - a_max: scalar or array, maximum value(s)
361
    - out: cupy.ndarray, output array
362
    
363
    Returns:
364
    cupy.ndarray: Clipped array
365
    """
366
```
367

368
### Root and Power Functions
369

370
Functions for calculating roots and powers.
371

372
```python { .api }
373
def sqrt(x):
374
    """
375
    Return non-negative square root, element-wise.
376
    
377
    Parameters:
378
    - x: array-like, input array with non-negative values
379
    
380
    Returns:
381
    cupy.ndarray: Square root of each element
382
    """
383

384
def cbrt(x):
385
    """Return cube root, element-wise."""
386

387
def square(x):
388
    """Return element-wise square of input."""
389

390
def reciprocal(x):
391
    """
392
    Return reciprocal of argument, element-wise.
393
    
394
    Returns:
395
    cupy.ndarray: 1/x element-wise
396
    """
397
```
398

399
### Special Mathematical Functions
400

401
Specialized mathematical functions for scientific computing.
402

403
```python { .api }
404
def heaviside(x1, x2):
405
    """
406
    Compute Heaviside step function.
407
    
408
    Parameters:
409
    - x1: array-like, input values
410
    - x2: array-like, value for x1 == 0
411
    
412
    Returns:
413
    cupy.ndarray: 0 where x1 < 0, x2 where x1 == 0, 1 where x1 > 0
414
    """
415

416
def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None):
417
    """
418
    Replace NaN with zero and infinity with large finite numbers.
419
    
420
    Parameters:
421
    - x: array-like, input array
422
    - copy: bool, whether to create copy
423
    - nan: scalar, value to replace NaN with
424
    - posinf: scalar, value to replace positive infinity with
425
    - neginf: scalar, value to replace negative infinity with
426
    
427
    Returns:
428
    cupy.ndarray: Array with finite values
429
    """
430

431
def real_if_close(a, tol=100):
432
    """
433
    Convert complex array to real if imaginary parts are close to zero.
434
    
435
    Parameters:
436
    - a: array-like, input array
437
    - tol: float, tolerance for considering imaginary part as zero
438
    
439
    Returns:
440
    cupy.ndarray: Real array if possible, otherwise unchanged
441
    """
442

443
def interp(x, xp, fp, left=None, right=None, period=None):
444
    """
445
    One-dimensional linear interpolation.
446
    
447
    Parameters:
448
    - x: array-like, x-coordinates at which to evaluate interpolated values
449
    - xp: array-like, x-coordinates of data points (must be increasing)
450
    - fp: array-like, y-coordinates of data points
451
    - left: scalar, value for x < xp[0]
452
    - right: scalar, value for x > xp[-1]
453
    - period: scalar, period for periodic interpolation
454
    
455
    Returns:
456
    cupy.ndarray: Interpolated values
457
    """
458
```
459

460
### Complex Number Functions
461

462
Functions for working with complex numbers.
463

464
```python { .api }
465
def real(val):
466
    """
467
    Return real part of complex argument.
468
    
469
    Parameters:
470
    - val: array-like, input array
471
    
472
    Returns:
473
    cupy.ndarray: Real component
474
    """
475

476
def imag(val):
477
    """Return imaginary part of complex argument."""
478

479
def conjugate(x):
480
    """
481
    Return complex conjugate, element-wise.
482
    
483
    Returns:
484
    cupy.ndarray: Complex conjugate of each element
485
    """
486

487
def conj(x):
488
    """Return complex conjugate (alias for conjugate)."""
489

490
def angle(z, deg=False):
491
    """
492
    Return angle of complex argument.
493
    
494
    Parameters:
495
    - z: array-like, complex input
496
    - deg: bool, return angle in degrees if True, radians if False
497
    
498
    Returns:
499
    cupy.ndarray: Angle of each complex number
500
    """
501
```
502

503
### Floating Point Functions
504

505
Functions for manipulating floating-point representations.
506

507
```python { .api }
508
def frexp(x):
509
    """
510
    Decompose elements to mantissa and two's exponent.
511
    
512
    Parameters:
513
    - x: array-like, input array
514
    
515
    Returns:
516
    tuple: (mantissa, exponent) where x = mantissa * 2**exponent
517
    """
518

519
def ldexp(x1, x2):
520
    """
521
    Return x1 * 2**x2, element-wise.
522
    
523
    Parameters:
524
    - x1: array-like, mantissa
525
    - x2: array-like, exponent
526
    
527
    Returns:
528
    cupy.ndarray: x1 * 2**x2
529
    """
530

531
def nextafter(x1, x2):
532
    """
533
    Return next floating-point value after x1 towards x2.
534
    
535
    Returns:
536
    cupy.ndarray: Next representable value
537
    """
538

539
def modf(x):
540
    """
541
    Return fractional and integer parts of array.
542
    
543
    Returns:
544
    tuple: (fractional_part, integer_part)
545
    """
546
```
547

548
## Usage Examples
549

550
### Basic Mathematical Operations
551

552
```python
553
import cupy as cp
554
import numpy as np
555

556
# Create sample data
557
x = cp.linspace(0, 2*cp.pi, 1000)
558
y = cp.random.rand(1000)
559

560
# Trigonometric functions
561
sine_wave = cp.sin(x)
562
cosine_wave = cp.cos(x)
563
tangent_values = cp.tan(x)
564

565
# Exponential and logarithmic
566
exp_values = cp.exp(y)
567
log_values = cp.log(y + 1)  # Add 1 to avoid log(0)
568

569
# Arithmetic operations
570
a = cp.array([1, 2, 3, 4, 5])
571
b = cp.array([2, 4, 6, 8, 10])
572

573
sum_result = cp.add(a, b)
574
product = cp.multiply(a, b)
575
power_result = cp.power(a, 2)
576

577
# Complex operations
578
complex_array = cp.array([1+2j, 3+4j, 5+6j])
579
real_parts = cp.real(complex_array)
580
imag_parts = cp.imag(complex_array)
581
conjugates = cp.conjugate(complex_array)
582

583
# Binary operations on integer arrays
584
int_array1 = cp.array([5, 3, 8, 12], dtype=cp.int32)  # Binary: 0101, 0011, 1000, 1100
585
int_array2 = cp.array([3, 5, 4, 15], dtype=cp.int32)  # Binary: 0011, 0101, 0100, 1111
586

587
# Bitwise operations
588
and_result = cp.bitwise_and(int_array1, int_array2)    # 1, 1, 0, 12
589
or_result = cp.bitwise_or(int_array1, int_array2)      # 7, 7, 12, 15
590
xor_result = cp.bitwise_xor(int_array1, int_array2)    # 6, 6, 12, 3
591
not_result = cp.bitwise_not(int_array1)                # Bitwise inversion
592

593
# Bit shifting
594
left_shifted = cp.left_shift(int_array1, 2)   # Multiply by 4: 20, 12, 32, 48
595
right_shifted = cp.right_shift(int_array1, 1) # Divide by 2: 2, 1, 4, 6
596

597
# Binary packing/unpacking
598
binary_array = cp.array([0, 1, 1, 0, 1, 0, 1, 1], dtype=cp.uint8)
599
packed = cp.packbits(binary_array)            # Pack into uint8
600
unpacked = cp.unpackbits(packed)              # Unpack back to binary
601
```