0
# Mathematical Functions
1

2
Element-wise mathematical operations on GPU arrays, providing the same interface as NumPy while leveraging GPU acceleration. All functions support broadcasting and can operate on arrays of different shapes.
3

4
## Capabilities
5

6
### Trigonometric Functions
7

8
```python { .api }
9
def sin(x, out=None, **kwargs):
10
    """Trigonometric sine, element-wise."""
11

12
def cos(x, out=None, **kwargs):
13
    """Trigonometric cosine, element-wise."""
14

15
def tan(x, out=None, **kwargs):
16
    """Trigonometric tangent, element-wise."""
17

18
def arcsin(x, out=None, **kwargs):
19
    """Inverse sine, element-wise."""
20

21
def arccos(x, out=None, **kwargs):
22
    """Inverse cosine, element-wise."""
23

24
def arctan(x, out=None, **kwargs):
25
    """Inverse tangent, element-wise."""
26

27
def arctan2(x1, x2, out=None, **kwargs):
28
    """Element-wise arc tangent of x1/x2."""
29

30
def hypot(x1, x2, out=None, **kwargs):
31
    """Hypotenuse given catheti."""
32

33
def degrees(x, out=None, **kwargs):
34
    """Convert radians to degrees."""
35

36
def radians(x, out=None, **kwargs):
37
    """Convert degrees to radians."""
38

39
def deg2rad(x, out=None, **kwargs):
40
    """Convert degrees to radians."""
41

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

45
def unwrap(p, discont=3.141592653589793, axis=-1):
46
    """Unwrap phase angles."""
47
```
48

49
### Hyperbolic Functions
50

51
```python { .api }
52
def sinh(x, out=None, **kwargs):
53
    """Hyperbolic sine, element-wise."""
54

55
def cosh(x, out=None, **kwargs):
56
    """Hyperbolic cosine, element-wise."""
57

58
def tanh(x, out=None, **kwargs):
59
    """Hyperbolic tangent, element-wise."""
60

61
def arcsinh(x, out=None, **kwargs):
62
    """Inverse hyperbolic sine, element-wise."""
63

64
def arccosh(x, out=None, **kwargs):
65
    """Inverse hyperbolic cosine, element-wise."""
66

67
def arctanh(x, out=None, **kwargs):
68
    """Inverse hyperbolic tangent, element-wise."""
69
```
70

71
### Exponential and Logarithmic Functions
72

73
```python { .api }
74
def exp(x, out=None, **kwargs):
75
    """Calculate exponential of all elements."""
76

77
def expm1(x, out=None, **kwargs):
78
    """Calculate exp(x) - 1 for all elements."""
79

80
def exp2(x, out=None, **kwargs):
81
    """Calculate 2**x for all elements."""
82

83
def log(x, out=None, **kwargs):
84
    """Natural logarithm, element-wise."""
85

86
def log10(x, out=None, **kwargs):
87
    """Base-10 logarithm, element-wise."""
88

89
def log2(x, out=None, **kwargs):
90
    """Base-2 logarithm, element-wise."""
91

92
def log1p(x, out=None, **kwargs):
93
    """Return log(1 + x), element-wise."""
94

95
def logaddexp(x1, x2, out=None, **kwargs):
96
    """Logarithm of the sum of exponentiations."""
97

98
def logaddexp2(x1, x2, out=None, **kwargs):
99
    """Logarithm of the sum of exponentiations in base 2."""
100
```
101

102
### Arithmetic Functions
103

104
```python { .api }
105
def add(x1, x2, out=None, **kwargs):
106
    """Add arguments element-wise."""
107

108
def subtract(x1, x2, out=None, **kwargs):
109
    """Subtract arguments, element-wise."""
110

111
def multiply(x1, x2, out=None, **kwargs):
112
    """Multiply arguments element-wise."""
113

114
def divide(x1, x2, out=None, **kwargs):
115
    """Divide arguments element-wise."""
116

117
def true_divide(x1, x2, out=None, **kwargs):
118
    """Returns a true division of the inputs, element-wise."""
119

120
def floor_divide(x1, x2, out=None, **kwargs):
121
    """Return the largest integer smaller or equal to the division."""
122

123
def negative(x, out=None, **kwargs):
124
    """Numerical negative, element-wise."""
125

126
def positive(x, out=None, **kwargs):
127
    """Numerical positive, element-wise."""
128

129
def power(x1, x2, out=None, **kwargs):
130
    """First array elements raised to powers from second array."""
131

132
def float_power(x1, x2, out=None, **kwargs):
133
    """First array elements raised to powers from second array, element-wise."""
134

135
def remainder(x1, x2, out=None, **kwargs):
136
    """Return element-wise remainder of division."""
137

138
def mod(x1, x2, out=None, **kwargs):
139
    """Return element-wise remainder of division."""
140

141
def fmod(x1, x2, out=None, **kwargs):
142
    """Return the element-wise remainder of division."""
143

144
def divmod(x1, x2, out1=None, out2=None, **kwargs):
145
    """Return element-wise quotient and remainder simultaneously."""
146

147
def modf(x, out1=None, out2=None, **kwargs):
148
    """Return fractional and integral parts of array, element-wise."""
149

150
def reciprocal(x, out=None, **kwargs):
151
    """Return the reciprocal of the argument, element-wise."""
152
```
153

154
### Rounding Functions
155

156
```python { .api }
157
def around(a, decimals=0, out=None):
158
    """Round to given number of decimals."""
159

160
def round_(a, decimals=0, out=None):
161
    """Round to given number of decimals."""
162

163
def rint(x, out=None, **kwargs):
164
    """Round elements to nearest integers."""
165

166
def fix(x, out=None):
167
    """Round to nearest integer towards zero."""
168

169
def floor(x, out=None, **kwargs):
170
    """Return floor of input, element-wise."""
171

172
def ceil(x, out=None, **kwargs):
173
    """Return ceiling of input, element-wise."""
174

175
def trunc(x, out=None, **kwargs):
176
    """Return truncated value of input, element-wise."""
177
```
178

179
### Sums, Products, Differences
180

181
```python { .api }
182
def sum(a, axis=None, dtype=None, out=None, keepdims=False, initial=None, where=True):
183
    """
184
    Sum of array elements over given axis.
185

186
    Parameters:
187
    - a: input array
188
    - axis: axis or axes along which to sum
189
    - dtype: data type of the output
190
    - out: output array
191
    - keepdims: keep dimensions of original array
192
    - initial: starting value for sum
193
    - where: elements to include in sum
194

195
    Returns:
196
    cupy.ndarray: sum along specified axis
197
    """
198

199
def prod(a, axis=None, dtype=None, out=None, keepdims=False, initial=None, where=True):
200
    """Return product of array elements over given axis."""
201

202
def nansum(a, axis=None, dtype=None, out=None, keepdims=False):
203
    """Return sum of array elements, ignoring NaNs."""
204

205
def nanprod(a, axis=None, dtype=None, out=None, keepdims=False):
206
    """Return product of array elements, ignoring NaNs."""
207

208
def cumsum(a, axis=None, dtype=None, out=None):
209
    """Return cumulative sum of elements along axis."""
210

211
def cumprod(a, axis=None, dtype=None, out=None):
212
    """Return cumulative product of elements along axis."""
213

214
def nancumsum(a, axis=None, dtype=None, out=None):
215
    """Return cumulative sum of elements, ignoring NaNs."""
216

217
def nancumprod(a, axis=None, dtype=None, out=None):
218
    """Return cumulative product of elements, ignoring NaNs."""
219

220
def diff(a, n=1, axis=-1, prepend=None, append=None):
221
    """Calculate n-th discrete difference along axis."""
222

223
def ediff1d(ary, to_end=None, to_begin=None):
224
    """Differences between consecutive elements."""
225

226
def gradient(f, *varargs, axis=None, edge_order=1):
227
    """Return gradient of N-dimensional array."""
228

229
def trapz(y, x=None, dx=1.0, axis=-1):
230
    """Integrate using trapezoidal rule."""
231
```
232

233
### Complex Number Functions
234

235
```python { .api }
236
def angle(z, deg=False):
237
    """Return angle of complex argument."""
238

239
def real(val):
240
    """Return real part of complex argument."""
241

242
def imag(val):
243
    """Return imaginary part of complex argument."""
244

245
def conj(x, out=None, **kwargs):
246
    """Return complex conjugate, element-wise."""
247

248
def conjugate(x, out=None, **kwargs):
249
    """Return complex conjugate, element-wise."""
250
```
251

252
### Floating Point Functions
253

254
```python { .api }
255
def signbit(x, out=None, **kwargs):
256
    """Returns element-wise True where signbit is set."""
257

258
def copysign(x1, x2, out=None, **kwargs):
259
    """Change sign of x1 to that of x2, element-wise."""
260

261
def frexp(x, out1=None, out2=None, **kwargs):
262
    """Decompose elements to mantissa and two's exponent."""
263

264
def ldexp(x1, x2, out=None, **kwargs):
265
    """Return x1 * 2**x2, element-wise."""
266

267
def nextafter(x1, x2, out=None, **kwargs):
268
    """Return next floating-point value after x1 towards x2."""
269
```
270

271
### Rational Functions
272

273
```python { .api }
274
def gcd(x1, x2, out=None, **kwargs):
275
    """Return greatest common divisor of |x1| and |x2|."""
276

277
def lcm(x1, x2, out=None, **kwargs):
278
    """Return least common multiple of |x1| and |x2|."""
279
```
280

281
### Miscellaneous Functions
282

283
```python { .api }
284
def abs(x, out=None, **kwargs):
285
    """Absolute value element-wise."""
286

287
def absolute(x, out=None, **kwargs):
288
    """Absolute value element-wise."""
289

290
def fabs(x, out=None, **kwargs):
291
    """Absolute values (floating point only)."""
292

293
def sign(x, out=None, **kwargs):
294
    """Sign function."""
295

296
def heaviside(x1, x2, out=None, **kwargs):
297
    """Compute Heaviside step function."""
298

299
def maximum(x1, x2, out=None, **kwargs):
300
    """Element-wise maximum of array elements."""
301

302
def minimum(x1, x2, out=None, **kwargs):
303
    """Element-wise minimum of array elements."""
304

305
def fmax(x1, x2, out=None, **kwargs):
306
    """Element-wise maximum, ignoring NaNs."""
307

308
def fmin(x1, x2, out=None, **kwargs):
309
    """Element-wise minimum, ignoring NaNs."""
310

311
def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None):
312
    """Replace NaN with zero and infinity with large finite numbers."""
313

314
def real_if_close(a, tol=100):
315
    """If complex input returns a real array if complex parts are close to zero."""
316

317
def interp(x, xp, fp, left=None, right=None, period=None):
318
    """One-dimensional linear interpolation."""
319

320
def clip(a, a_min, a_max, out=None, **kwargs):
321
    """Clip (limit) values in array."""
322

323
def sqrt(x, out=None, **kwargs):
324
    """Return non-negative square-root, element-wise."""
325

326
def cbrt(x, out=None, **kwargs):
327
    """Return cube-root, element-wise."""
328

329
def square(x, out=None, **kwargs):
330
    """Return element-wise square of input."""
331

332
def convolve(a, v, mode='full'):
333
    """Return discrete linear convolution of one-dimensional arrays."""
334
```
335

336
### Special Functions
337

338
```python { .api }
339
def i0(x):
340
    """Modified Bessel function of first kind, order 0."""
341

342
def sinc(x):
343
    """Return sinc function."""
344
```
345

346
### Window Functions
347

348
```python { .api }
349
def bartlett(M):
350
    """Return Bartlett window."""
351

352
def blackman(M):
353
    """Return Blackman window."""
354

355
def hamming(M):
356
    """Return Hamming window."""
357

358
def hanning(M):
359
    """Return Hann window."""
360

361
def kaiser(M, beta):
362
    """Return Kaiser window."""
363
```
364

365
## Usage Examples
366

367
### Basic Mathematical Operations
368

369
```python
370
import cupy as cp
371

372
# Create sample data
373
x = cp.linspace(0, 2*cp.pi, 100)
374
y = cp.random.random(100)
375

376
# Trigonometric functions
377
sine_values = cp.sin(x)
378
cosine_values = cp.cos(x)
379
tangent_values = cp.tan(x)
380

381
# Inverse functions
382
arcsine = cp.arcsin(y)  # y should be in [-1, 1]
383
phase_angle = cp.arctan2(sine_values, cosine_values)
384
```
385

386
### Exponentials and Logarithms
387

388
```python
389
import cupy as cp
390

391
# Exponential functions
392
x = cp.linspace(-2, 2, 100)
393
exp_x = cp.exp(x)
394
exp2_x = cp.exp2(x)  # 2^x
395
expm1_x = cp.expm1(x)  # exp(x) - 1
396

397
# Logarithmic functions
398
positive_x = cp.abs(x) + 1e-8  # Ensure positive for log
399
log_x = cp.log(positive_x)
400
log10_x = cp.log10(positive_x)
401
log2_x = cp.log2(positive_x)
402
```
403

404
### Array Arithmetic
405

406
```python
407
import cupy as cp
408

409
# Create arrays
410
a = cp.array([1, 2, 3, 4, 5])
411
b = cp.array([2, 3, 4, 5, 6])
412

413
# Basic arithmetic
414
sum_ab = cp.add(a, b)
415
diff_ab = cp.subtract(a, b)
416
prod_ab = cp.multiply(a, b)
417
quot_ab = cp.divide(a, b)
418

419
# Broadcasting works too
420
scalar = 2
421
scaled = cp.multiply(a, scalar)
422
powered = cp.power(a, scalar)
423
```
424

425
### Statistical Reductions
426

427
```python
428
import cupy as cp
429

430
# Create 2D array
431
data = cp.random.random((100, 50))
432

433
# Sum operations
434
total_sum = cp.sum(data)
435
row_sums = cp.sum(data, axis=1)  # Sum along columns
436
col_sums = cp.sum(data, axis=0)  # Sum along rows
437

438
# Product operations
439
total_prod = cp.prod(data)
440
cumulative_sum = cp.cumsum(data, axis=0)
441
```
442

443
### Complex Number Operations
444

445
```python
446
import cupy as cp
447

448
# Create complex arrays
449
real_part = cp.random.random(100)
450
imag_part = cp.random.random(100)
451
complex_array = real_part + 1j * imag_part
452

453
# Complex operations
454
magnitude = cp.abs(complex_array)
455
phase = cp.angle(complex_array)
456
conjugate = cp.conj(complex_array)
457

458
# Extract parts
459
real_extracted = cp.real(complex_array)
460
imag_extracted = cp.imag(complex_array)
461
```