0
# Mathematical Functions
1

2
Complete set of mathematical operations including trigonometric, hyperbolic, exponential, logarithmic, arithmetic, and special functions, all optimized for GPU execution. CuPy provides GPU-accelerated implementations of all NumPy mathematical functions with identical APIs.
3

4
## Capabilities
5

6
### Trigonometric Functions
7

8
Standard trigonometric functions with GPU acceleration.
9

10
```python { .api }
11
def sin(x, out=None, **kwargs):
12
    """Trigonometric sine, element-wise.
13
    
14
    Args:
15
        x: Input array in radians
16
        out: Output array
17
        **kwargs: Additional ufunc arguments
18
        
19
    Returns:
20
        cupy.ndarray: Sine values
21
    """
22

23
def cos(x, out=None, **kwargs):
24
    """Trigonometric cosine, element-wise."""
25

26
def tan(x, out=None, **kwargs):
27
    """Trigonometric tangent, element-wise."""
28

29
def arcsin(x, out=None, **kwargs):
30
    """Inverse sine, element-wise."""
31

32
def arccos(x, out=None, **kwargs):
33
    """Inverse cosine, element-wise."""
34

35
def arctan(x, out=None, **kwargs):
36
    """Inverse tangent, element-wise."""
37

38
def arctan2(y, x, out=None, **kwargs):
39
    """Element-wise arc tangent of y/x choosing quadrant correctly."""
40

41
def degrees(x, out=None, **kwargs):
42
    """Convert radians to degrees."""
43

44
def radians(x, out=None, **kwargs):
45
    """Convert degrees to radians."""
46

47
def deg2rad(x, out=None, **kwargs):
48
    """Convert degrees to radians (alias for radians)."""
49

50
def rad2deg(x, out=None, **kwargs):
51
    """Convert radians to degrees (alias for degrees)."""
52

53
def hypot(x1, x2, out=None, **kwargs):
54
    """Given the legs of a right triangle, return its hypotenuse.
55
    
56
    Equivalent to sqrt(x1**2 + x2**2), element-wise, with proper handling
57
    of complex numbers and infinities.
58
    """
59

60
def unwrap(p, discont=3.141592653589793, axis=-1):
61
    """Unwrap by changing deltas between values to 2*pi complement.
62
    
63
    Args:
64
        p: Input array
65
        discont: Maximum discontinuity between values
66
        axis: Axis along which unwrap will operate
67
        
68
    Returns:
69
        cupy.ndarray: Output array with unwrapped values
70
    """
71
```
72

73
### Hyperbolic Functions
74

75
Hyperbolic trigonometric functions for exponential relationships.
76

77
```python { .api }
78
def sinh(x, out=None, **kwargs):
79
    """Hyperbolic sine, element-wise."""
80

81
def cosh(x, out=None, **kwargs):
82
    """Hyperbolic cosine, element-wise."""
83

84
def tanh(x, out=None, **kwargs):
85
    """Hyperbolic tangent, element-wise."""
86

87
def arcsinh(x, out=None, **kwargs):
88
    """Inverse hyperbolic sine, element-wise."""
89

90
def arccosh(x, out=None, **kwargs):
91
    """Inverse hyperbolic cosine, element-wise."""
92

93
def arctanh(x, out=None, **kwargs):
94
    """Inverse hyperbolic tangent, element-wise."""
95
```
96

97
### Exponential and Logarithmic Functions
98

99
Exponential and logarithmic operations with various bases.
100

101
```python { .api }
102
def exp(x, out=None, **kwargs):
103
    """Calculate the exponential of all elements in the input array.
104
    
105
    Args:
106
        x: Input array
107
        out: Output array
108
        **kwargs: Additional ufunc arguments
109
        
110
    Returns:
111
        cupy.ndarray: Exponential values
112
    """
113

114
def exp2(x, out=None, **kwargs):
115
    """Calculate 2**x for all elements in array."""
116

117
def expm1(x, out=None, **kwargs):
118
    """Calculate exp(x) - 1 for all elements."""
119

120
def log(x, out=None, **kwargs):
121
    """Natural logarithm, element-wise."""
122

123
def log2(x, out=None, **kwargs):
124
    """Base-2 logarithm, element-wise."""
125

126
def log10(x, out=None, **kwargs):
127
    """Base-10 logarithm, element-wise."""
128

129
def log1p(x, out=None, **kwargs):
130
    """Return the natural logarithm of one plus the input array."""
131

132
def logaddexp(x1, x2, out=None, **kwargs):
133
    """Logarithm of the sum of exponentials of inputs."""
134

135
def logaddexp2(x1, x2, out=None, **kwargs):
136
    """Logarithm of the sum of exponentials of inputs in base 2."""
137
```
138

139
### Power and Root Functions
140

141
Power operations and root calculations.
142

143
```python { .api }
144
def power(x1, x2, out=None, **kwargs):
145
    """First array elements raised to powers from second array.
146
    
147
    Args:
148
        x1: Base values
149
        x2: Exponent values
150
        out: Output array
151
        **kwargs: Additional ufunc arguments
152
        
153
    Returns:
154
        cupy.ndarray: Power values
155
    """
156

157
def sqrt(x, out=None, **kwargs):
158
    """Return the non-negative square-root of an array."""
159

160
def square(x, out=None, **kwargs):
161
    """Return the element-wise square of the input."""
162

163
def cbrt(x, out=None, **kwargs):
164
    """Return the cube-root of an array."""
165

166
def reciprocal(x, out=None, **kwargs):
167
    """Return the reciprocal of the argument."""
168
```
169

170
### Arithmetic Operations
171

172
Basic and advanced arithmetic operations.
173

174
```python { .api }
175
def add(x1, x2, out=None, **kwargs):
176
    """Add arguments element-wise.
177
    
178
    Args:
179
        x1, x2: Input arrays or scalars
180
        out: Output array
181
        **kwargs: Additional ufunc arguments
182
        
183
    Returns:
184
        cupy.ndarray: Sum of inputs
185
    """
186

187
def subtract(x1, x2, out=None, **kwargs):
188
    """Subtract arguments element-wise."""
189

190
def multiply(x1, x2, out=None, **kwargs):
191
    """Multiply arguments element-wise."""
192

193
def divide(x1, x2, out=None, **kwargs):
194
    """Divide arguments element-wise."""
195

196
def true_divide(x1, x2, out=None, **kwargs):
197
    """Returns true division element-wise."""
198

199
def floor_divide(x1, x2, out=None, **kwargs):
200
    """Return largest integers smaller or equal to division."""
201

202
def mod(x1, x2, out=None, **kwargs):
203
    """Return element-wise remainder of division."""
204

205
def remainder(x1, x2, out=None, **kwargs):
206
    """Return element-wise remainder of division."""
207

208
def divmod(x1, x2, out1=None, out2=None):
209
    """Return element-wise quotient and remainder simultaneously."""
210

211
def negative(x, out=None, **kwargs):
212
    """Numerical negative, element-wise."""
213

214
def positive(x, out=None, **kwargs):
215
    """Numerical positive, element-wise."""
216

217
def absolute(x, out=None, **kwargs):
218
    """Calculate absolute value element-wise."""
219

220
def fabs(x, out=None, **kwargs):
221
    """Compute absolute values element-wise."""
222

223
def sign(x, out=None, **kwargs):
224
    """Returns element-wise indication of sign of number."""
225
```
226

227
### Rounding and Discretization
228

229
Functions for rounding and discretizing values.
230

231
```python { .api }
232
def around(a, decimals=0, out=None):
233
    """Round to given number of decimals.
234
    
235
    Args:
236
        a: Input array
237
        decimals: Number of decimals to round to
238
        out: Output array
239
        
240
    Returns:
241
        cupy.ndarray: Rounded values
242
    """
243

244
def round(a, decimals=0, out=None):
245
    """Round to given number of decimals."""
246

247
def rint(x, out=None, **kwargs):
248
    """Round elements to nearest integers."""
249

250
def floor(x, out=None, **kwargs):
251
    """Return floor of input, element-wise."""
252

253
def ceil(x, out=None, **kwargs):
254
    """Return ceiling of input, element-wise."""
255

256
def trunc(x, out=None, **kwargs):
257
    """Return truncated value of input, element-wise."""
258

259
def fix(x, out=None):
260
    """Round to nearest integer towards zero."""
261
```
262

263
### Complex Number Functions
264

265
Operations specific to complex numbers.
266

267
```python { .api }
268
def real(val):
269
    """Return real part of complex argument."""
270

271
def imag(val):
272
    """Return imaginary part of complex argument."""
273

274
def conj(x, out=None, **kwargs):
275
    """Return complex conjugate, element-wise."""
276

277
def conjugate(x, out=None, **kwargs):
278
    """Return complex conjugate, element-wise."""
279

280
def angle(z, deg=False):
281
    """Return angle of complex argument."""
282

283
def real_if_close(a, tol=100):
284
    """If complex parts are close to zero, return real parts."""
285
```
286

287
### Reduction Operations
288

289
Aggregate operations across array dimensions.
290

291
```python { .api }
292
def sum(a, axis=None, dtype=None, out=None, keepdims=False, initial=None, where=None):
293
    """Sum of array elements over given axis.
294
    
295
    Args:
296
        a: Input array
297
        axis: Axis to sum over
298
        dtype: Output data type
299
        out: Output array
300
        keepdims: Keep reduced dimensions
301
        initial: Initial value
302
        where: Boolean mask
303
        
304
    Returns:
305
        cupy.ndarray or scalar: Sum result
306
    """
307

308
def prod(a, axis=None, dtype=None, out=None, keepdims=False, initial=None, where=None):
309
    """Product of array elements over given axis."""
310

311
def mean(a, axis=None, dtype=None, out=None, keepdims=False, where=None):
312
    """Compute arithmetic mean along specified axis."""
313

314
def cumsum(a, axis=None, dtype=None, out=None):
315
    """Return cumulative sum of elements along given axis."""
316

317
def cumprod(a, axis=None, dtype=None, out=None):
318
    """Return cumulative product of elements along given axis."""
319

320
def diff(a, n=1, axis=-1, prepend=None, append=None):
321
    """Calculate n-th discrete difference along given axis."""
322

323
def gradient(f, *varargs, axis=None, edge_order=1):
324
    """Return gradient of an N-dimensional array."""
325
```
326

327
### Statistical Functions
328

329
Mathematical statistics and data analysis functions.
330

331
```python { .api }
332
def std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=False, where=None):
333
    """Compute standard deviation along specified axis."""
334

335
def var(a, axis=None, dtype=None, out=None, ddof=0, keepdims=False, where=None):
336
    """Compute variance along specified axis."""
337

338
def min(a, axis=None, out=None, keepdims=False, initial=None, where=None):
339
    """Return minimum along axis."""
340

341
def max(a, axis=None, out=None, keepdims=False, initial=None, where=None):
342
    """Return maximum along axis."""
343

344
def ptp(a, axis=None, out=None, keepdims=False):
345
    """Range of values (maximum - minimum) along axis."""
346
```
347

348
### Special Mathematical Functions
349

350
Specialized mathematical functions.
351

352
```python { .api }
353
def clip(a, a_min, a_max, out=None, **kwargs):
354
    """Clip values in array to given range.
355
    
356
    Args:
357
        a: Input array
358
        a_min: Minimum value
359
        a_max: Maximum value
360
        out: Output array
361
        
362
    Returns:
363
        cupy.ndarray: Clipped array
364
    """
365

366
def fmod(x1, x2, out=None, **kwargs):
367
    """Return remainder of division (C library fmod)."""
368

369
def modf(x, out1=None, out2=None):
370
    """Return fractional and integral parts of numbers."""
371

372
def frexp(x, out1=None, out2=None):
373
    """Decompose numbers into mantissa and exponent."""
374

375
def ldexp(x1, x2, out=None, **kwargs):
376
    """Compute x1 * 2**x2, element-wise."""
377

378
def copysign(x1, x2, out=None, **kwargs):
379
    """Change sign of x1 to that of x2, element-wise."""
380

381
def nextafter(x1, x2, out=None, **kwargs):
382
    """Return next floating-point value after x1 towards x2."""
383

384
def spacing(x, out=None, **kwargs):
385
    """Return distance between x and nearest adjacent number."""
386
```
387

388
### Window Functions
389

390
Window functions for signal processing and spectral analysis.
391

392
```python { .api }
393
def bartlett(M):
394
    """Return the Bartlett window.
395
    
396
    Args:
397
        M: Number of points in the output window
398
        
399
    Returns:
400
        cupy.ndarray: The window, with the maximum value normalized to 1
401
    """
402

403
def blackman(M):
404
    """Return the Blackman window.
405
    
406
    Args:
407
        M: Number of points in the output window
408
        
409
    Returns:
410
        cupy.ndarray: The window, with the maximum value normalized to 1
411
    """
412

413
def hamming(M):
414
    """Return the Hamming window.
415
    
416
    Args:
417
        M: Number of points in the output window
418
        
419
    Returns:
420
        cupy.ndarray: The window, with the maximum value normalized to 1
421
    """
422

423
def hanning(M):
424
    """Return the Hanning window.
425
    
426
    Args:
427
        M: Number of points in the output window
428
        
429
    Returns:
430
        cupy.ndarray: The window, with the maximum value normalized to 1
431
    """
432

433
def kaiser(M, beta):
434
    """Return the Kaiser window.
435
    
436
    Args:
437
        M: Number of points in the output window
438
        beta: Shape parameter for window
439
        
440
    Returns:
441
        cupy.ndarray: The window, with the maximum value normalized to 1
442
    """
443
```
444

445
## Usage Examples
446

447
### Basic Mathematical Operations
448

449
```python
450
import cupy as cp
451

452
# Create sample data
453
x = cp.linspace(0, 2*cp.pi, 100)
454
y = cp.random.random((10, 10))
455

456
# Trigonometric functions
457
sin_vals = cp.sin(x)
458
cos_vals = cp.cos(x)
459
combined = cp.sin(x) * cp.cos(x)
460

461
# Exponential and logarithmic
462
exp_vals = cp.exp(y)
463
log_vals = cp.log(y + 1)  # Add 1 to avoid log(0)
464

465
# Power operations
466
squared = cp.square(y)
467
sqrt_vals = cp.sqrt(cp.abs(y))
468
power_vals = cp.power(y, 2.5)
469
```
470

471
### Element-wise Arithmetic
472

473
```python
474
# Arrays for operations
475
a = cp.array([1, 2, 3, 4, 5])
476
b = cp.array([2, 3, 4, 5, 6])
477

478
# Basic arithmetic
479
sum_ab = cp.add(a, b)      # [3, 5, 7, 9, 11]
480
diff_ab = cp.subtract(a, b) # [-1, -1, -1, -1, -1]
481
prod_ab = cp.multiply(a, b) # [2, 6, 12, 20, 30]
482
div_ab = cp.divide(b, a)    # [2.0, 1.5, 1.33..., 1.25, 1.2]
483

484
# Advanced operations
485
remainder = cp.mod(b, a)    # [0, 1, 1, 1, 1]
486
absolute = cp.abs(diff_ab)  # [1, 1, 1, 1, 1]
487
```
488

489
### Reduction Operations
490

491
```python
492
# 2D array for reductions
493
matrix = cp.random.random((5, 4))
494

495
# Different reduction operations
496
total_sum = cp.sum(matrix)                    # Sum all elements
497
row_sums = cp.sum(matrix, axis=1)            # Sum each row
498
col_sums = cp.sum(matrix, axis=0)            # Sum each column
499
mean_val = cp.mean(matrix)                   # Overall mean
500
row_means = cp.mean(matrix, axis=1)          # Mean of each row
501

502
# Cumulative operations
503
cumulative_sum = cp.cumsum(matrix, axis=0)   # Cumulative sum along columns
504
cumulative_prod = cp.cumprod(matrix, axis=1) # Cumulative product along rows
505
```
506

507
### Complex Number Operations
508

509
```python
510
# Complex number operations
511
z1 = cp.array([1+2j, 3+4j, 5+6j])
512
z2 = cp.array([2+1j, 4+3j, 6+5j])
513

514
# Complex arithmetic
515
z_sum = cp.add(z1, z2)
516
z_prod = cp.multiply(z1, z2)
517

518
# Complex-specific functions
519
real_parts = cp.real(z1)        # [1, 3, 5]
520
imag_parts = cp.imag(z1)        # [2, 4, 6]
521
conjugates = cp.conj(z1)        # [1-2j, 3-4j, 5-6j]
522
magnitudes = cp.abs(z1)         # Magnitude of complex numbers
523
phases = cp.angle(z1)           # Phase angles
524
```
525

526
### Specialized Functions
527

528
```python
529
# Clipping values
530
data = cp.array([-5, -1, 0, 1, 5, 10])
531
clipped = cp.clip(data, 0, 5)  # [0, 0, 0, 1, 5, 5]
532

533
# Rounding operations
534
floats = cp.array([1.2, 2.7, -0.8, 3.14159])
535
rounded = cp.round(floats, 2)    # [1.2, 2.7, -0.8, 3.14]
536
floors = cp.floor(floats)        # [1.0, 2.0, -1.0, 3.0]
537
ceilings = cp.ceil(floats)       # [2.0, 3.0, 0.0, 4.0]
538

539
# Sign operations
540
signs = cp.sign(floats)          # [1.0, 1.0, -1.0, 1.0]
541
absolute_vals = cp.abs(floats)   # [1.2, 2.7, 0.8, 3.14159]
542
```