0
# Mathematical Functions
1

2
Comprehensive mathematical operations including trigonometric, hyperbolic, exponential, logarithmic, arithmetic, and complex number functions. All functions are GPU-accelerated and maintain compatibility with NumPy's mathematical function interface.
3

4
## Capabilities
5

6
### Trigonometric Functions
7

8
Standard trigonometric functions operating element-wise on GPU arrays.
9

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

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

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

28
def arcsin(x, out=None):
29
    """Inverse sine, element-wise.
30
    
31
    Returns:
32
    cupy.ndarray: angles in radians, in range [-π/2, π/2]
33
    """
34

35
def arccos(x, out=None):
36
    """Inverse cosine, element-wise."""
37

38
def arctan(x, out=None):
39
    """Inverse tangent, element-wise."""
40

41
def arctan2(x1, x2, out=None):
42
    """Element-wise arc tangent of x1/x2, choosing quadrant correctly.
43
    
44
    Parameters:
45
    - x1: array-like, y-coordinates
46
    - x2: array-like, x-coordinates
47
    - out: ndarray, output array
48
    
49
    Returns:
50
    cupy.ndarray: angles in radians, in range [-π, π]
51
    """
52

53
def hypot(x1, x2, out=None):
54
    """Element-wise hypotenuse calculation: sqrt(x1**2 + x2**2)."""
55

56
def degrees(x, out=None):
57
    """Convert angles from radians to degrees."""
58

59
def radians(x, out=None):
60
    """Convert angles from degrees to radians."""
61

62
def deg2rad(x, out=None):
63
    """Convert angles from degrees to radians."""
64

65
def rad2deg(x, out=None):
66
    """Convert angles from radians to degrees."""
67
```
68

69
### Hyperbolic Functions
70

71
Hyperbolic trigonometric functions and their inverses.
72

73
```python { .api }
74
def sinh(x, out=None):
75
    """Hyperbolic sine, element-wise."""
76

77
def cosh(x, out=None):
78
    """Hyperbolic cosine, element-wise."""
79

80
def tanh(x, out=None):
81
    """Hyperbolic tangent, element-wise."""
82

83
def arcsinh(x, out=None):
84
    """Inverse hyperbolic sine, element-wise."""
85

86
def arccosh(x, out=None):
87
    """Inverse hyperbolic cosine, element-wise."""
88

89
def arctanh(x, out=None):
90
    """Inverse hyperbolic tangent, element-wise."""
91
```
92

93
### Exponential and Logarithmic Functions
94

95
Exponential, logarithmic, and power functions.
96

97
```python { .api }
98
def exp(x, out=None):
99
    """Calculate exponential of all elements in input array.
100
    
101
    Parameters:
102
    - x: array-like, input values
103
    - out: ndarray, output array
104
    
105
    Returns:
106
    cupy.ndarray: e**x for each element
107
    """
108

109
def exp2(x, out=None):
110
    """Calculate 2**x for all elements in input array."""
111

112
def expm1(x, out=None):
113
    """Calculate exp(x) - 1 for all elements, accurate for small x."""
114

115
def log(x, out=None):
116
    """Natural logarithm, element-wise."""
117

118
def log10(x, out=None):
119
    """Base-10 logarithm, element-wise."""
120

121
def log2(x, out=None):
122
    """Base-2 logarithm, element-wise."""
123

124
def log1p(x, out=None):
125
    """Calculate log(1 + x) for all elements, accurate for small x."""
126

127
def logaddexp(x1, x2, out=None):
128
    """Logarithm of sum of exponentials: log(exp(x1) + exp(x2))."""
129

130
def logaddexp2(x1, x2, out=None):
131
    """Logarithm of sum of exponentials base 2."""
132

133
def power(x1, x2, out=None):
134
    """First array elements raised to powers from second array, element-wise.
135
    
136
    Parameters:
137
    - x1: array-like, bases
138
    - x2: array-like, exponents  
139
    - out: ndarray, output array
140
    
141
    Returns:
142
    cupy.ndarray: x1**x2, element-wise
143
    """
144

145
def sqrt(x, out=None):
146
    """Non-negative square root, element-wise."""
147

148
def cbrt(x, out=None):
149
    """Cube root, element-wise."""
150

151
def square(x, out=None):
152
    """Element-wise square: x**2."""
153
```
154

155
### Arithmetic Functions
156

157
Basic arithmetic operations between arrays and scalars.
158

159
```python { .api }
160
def add(x1, x2, out=None):
161
    """Add arguments element-wise.
162
    
163
    Parameters:
164
    - x1: array-like, first input array
165
    - x2: array-like, second input array
166
    - out: ndarray, output array
167
    
168
    Returns:
169
    cupy.ndarray: sum of x1 and x2, element-wise
170
    """
171

172
def subtract(x1, x2, out=None):
173
    """Subtract arguments element-wise."""
174

175
def multiply(x1, x2, out=None):
176
    """Multiply arguments element-wise."""
177

178
def divide(x1, x2, out=None):
179
    """Divide arguments element-wise."""
180

181
def true_divide(x1, x2, out=None):
182
    """True division element-wise, always returns float."""
183

184
def floor_divide(x1, x2, out=None):
185
    """Floor division element-wise."""
186

187
def negative(x, out=None):
188
    """Numerical negative, element-wise."""
189

190
def positive(x, out=None):
191
    """Numerical positive, element-wise."""
192

193
def reciprocal(x, out=None):
194
    """Return reciprocal element-wise: 1/x."""
195

196
def remainder(x1, x2, out=None):
197
    """Element-wise remainder of division."""
198

199
def mod(x1, x2, out=None):
200
    """Element-wise remainder of division (alias for remainder)."""
201

202
def divmod(x1, x2, out1=None, out2=None):
203
    """Element-wise quotient and remainder simultaneously."""
204

205
def fmod(x1, x2, out=None):
206
    """Element-wise remainder of division (C-style)."""
207

208
def modf(x, out1=None, out2=None):
209
    """Return fractional and integral parts of elements."""
210

211
def absolute(x, out=None):
212
    """Absolute value element-wise."""
213

214
def abs(x, out=None):
215
    """Absolute value element-wise (alias)."""
216

217
def sign(x, out=None):
218
    """Element-wise indication of the sign of a number."""
219
```
220

221
### Rounding Functions
222

223
Functions for rounding array elements to different precisions.
224

225
```python { .api }
226
def around(a, decimals=0, out=None):
227
    """Round to given number of decimals.
228
    
229
    Parameters:
230
    - a: array-like, input array
231
    - decimals: int, number of decimals to round to
232
    - out: ndarray, output array
233
    
234
    Returns:
235
    cupy.ndarray: rounded array
236
    """
237

238
def round_(a, decimals=0, out=None):
239
    """Round to given number of decimals."""
240

241
def rint(x, out=None):
242
    """Round elements to nearest integer."""
243

244
def fix(x, out=None):
245
    """Round to nearest integer toward zero."""
246

247
def floor(x, out=None):
248
    """Floor of input, element-wise."""
249

250
def ceil(x, out=None):
251
    """Ceiling of input, element-wise."""
252

253
def trunc(x, out=None):
254
    """Truncated value of input, element-wise."""
255
```
256

257
### Complex Number Functions
258

259
Functions for working with complex numbers.
260

261
```python { .api }
262
def real(val):
263
    """Return real part of complex argument element-wise.
264
    
265
    Parameters:
266
    - val: array-like, input array
267
    
268
    Returns:
269
    cupy.ndarray: real component of input
270
    """
271

272
def imag(val):
273
    """Return imaginary part of complex argument element-wise."""
274

275
def conjugate(x, out=None):
276
    """Return complex conjugate element-wise."""
277

278
def conj(x, out=None):
279
    """Return complex conjugate element-wise (alias)."""
280

281
def angle(z, deg=False):
282
    """Return angle of complex argument.
283
    
284
    Parameters:
285
    - z: array-like, complex input
286
    - deg: bool, return angle in degrees if True
287
    
288
    Returns:
289
    cupy.ndarray: angles in radians (or degrees)
290
    """
291
```
292

293
### Comparison and Extrema Functions
294

295
Functions for comparing values and finding extrema.
296

297
```python { .api }
298
def maximum(x1, x2, out=None):
299
    """Element-wise maximum of array elements.
300
    
301
    Parameters:
302
    - x1: array-like, first input array
303
    - x2: array-like, second input array
304
    - out: ndarray, output array
305
    
306
    Returns:
307
    cupy.ndarray: maximum values element-wise
308
    """
309

310
def minimum(x1, x2, out=None):
311
    """Element-wise minimum of array elements."""
312

313
def fmax(x1, x2, out=None):
314
    """Element-wise maximum, ignoring NaNs."""
315

316
def fmin(x1, x2, out=None):
317
    """Element-wise minimum, ignoring NaNs."""
318

319
def clip(a, a_min, a_max, out=None):
320
    """Clip (limit) values in array.
321
    
322
    Parameters:
323
    - a: array-like, input array
324
    - a_min: scalar or array, minimum value
325
    - a_max: scalar or array, maximum value
326
    - out: ndarray, output array
327
    
328
    Returns:
329
    cupy.ndarray: clipped array
330
    """
331
```
332

333
### Floating Point Functions
334

335
Functions for working with floating-point representations.
336

337
```python { .api }
338
def copysign(x1, x2, out=None):
339
    """Change sign of x1 to match sign of x2, element-wise."""
340

341
def frexp(x, out1=None, out2=None):
342
    """Decompose numbers into mantissa and exponent."""
343

344
def ldexp(x1, x2, out=None):
345
    """Compute x1 * 2**x2, element-wise."""
346

347
def nextafter(x1, x2, out=None):
348
    """Return next floating-point value after x1 towards x2."""
349

350
def signbit(x, out=None):
351
    """Return element-wise True where signbit is set."""
352
```
353

354
### Special Mathematical Functions
355

356
Special functions and numerical utilities.
357

358
```python { .api }
359
def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None):
360
    """Replace NaN with zero and infinity with large finite numbers.
361
    
362
    Parameters:
363
    - x: array-like, input array
364
    - copy: bool, whether to create copy
365
    - nan: int, float, value to replace NaN with
366
    - posinf: int, float, value to replace positive infinity with  
367
    - neginf: int, float, value to replace negative infinity with
368
    
369
    Returns:
370
    cupy.ndarray: array with replaced values
371
    """
372

373
def interp(x, xp, fp, left=None, right=None, period=None):
374
    """One-dimensional linear interpolation."""
375

376
def sinc(x):
377
    """Return sinc function: sin(π*x)/(π*x)."""
378

379
def i0(x):
380
    """Modified Bessel function of first kind, order 0."""
381
```
382

383
### Aggregation Functions
384

385
Reduction operations that compute summary statistics.
386

387
```python { .api }
388
def sum(a, axis=None, dtype=None, out=None, keepdims=False):
389
    """Sum of array elements over given axis.
390
    
391
    Parameters:
392
    - a: array-like, input array
393
    - axis: int or tuple, axis to sum over
394
    - dtype: data type of output
395
    - out: ndarray, output array
396
    - keepdims: bool, keep reduced dimensions
397
    
398
    Returns:
399
    cupy.ndarray: sum along specified axis
400
    """
401

402
def prod(a, axis=None, dtype=None, out=None, keepdims=False):
403
    """Product of array elements over given axis."""
404

405
def cumsum(a, axis=None, dtype=None, out=None):
406
    """Cumulative sum along axis."""
407

408
def cumprod(a, axis=None, dtype=None, out=None):
409
    """Cumulative product along axis."""
410

411
def diff(a, n=1, axis=-1, prepend=None, append=None):
412
    """Calculate discrete difference along axis."""
413

414
def gradient(f, *varargs, axis=None, edge_order=1):
415
    """Return gradient of N-dimensional array."""
416
```
417

418
## Usage Examples
419

420
### Basic Mathematical Operations
421

422
```python
423
import cupy as cp
424
import numpy as np
425

426
# Create sample data
427
x = cp.linspace(0, 2 * cp.pi, 1000)
428
y = cp.random.random((100, 100))
429

430
# Trigonometric functions
431
sin_vals = cp.sin(x)
432
cos_vals = cp.cos(x)
433
tan_vals = cp.tan(x)
434

435
# Exponential and logarithmic
436
exp_vals = cp.exp(y)
437
log_vals = cp.log(cp.abs(y) + 1)  # Add 1 to avoid log(0)
438
power_vals = cp.power(y, 2.5)
439
```
440

441
### Element-wise Operations
442

443
```python
444
import cupy as cp
445

446
# Create arrays
447
a = cp.array([1, 4, 9, 16, 25])
448
b = cp.array([1, 2, 3, 4, 5])
449

450
# Arithmetic operations
451
addition = cp.add(a, b)           # [2, 6, 12, 20, 30]
452
multiplication = cp.multiply(a, b) # [1, 8, 27, 64, 125]
453
square_root = cp.sqrt(a)          # [1, 2, 3, 4, 5]
454
reciprocal = cp.reciprocal(b.astype(float))  # [1.0, 0.5, 0.33, 0.25, 0.2]
455
```
456

457
### Complex Numbers
458

459
```python
460
import cupy as cp
461

462
# Create complex arrays
463
z = cp.array([1+2j, 3+4j, 5+6j])
464

465
# Complex operations
466
real_part = cp.real(z)        # [1, 3, 5]
467
imag_part = cp.imag(z)        # [2, 4, 6]  
468
conjugate = cp.conjugate(z)   # [1-2j, 3-4j, 5-6j]
469
magnitude = cp.abs(z)         # [2.236, 5.0, 7.81]
470
phase = cp.angle(z)           # [1.107, 0.927, 0.876] radians
471
```
472

473
### Aggregation and Statistics
474

475
```python
476
import cupy as cp
477

478
# Create 2D array
479
data = cp.random.random((1000, 500))
480

481
# Compute statistics
482
total_sum = cp.sum(data)
483
mean_val = cp.mean(data)
484
row_sums = cp.sum(data, axis=1)    # Sum each row
485
col_means = cp.mean(data, axis=0)   # Mean of each column
486

487
# Cumulative operations
488
cumulative_sum = cp.cumsum(data, axis=0)
489
```