0
# Mathematical Functions
1

2
Comprehensive set of mathematical functions providing GPU acceleration for trigonometric, hyperbolic, exponential, logarithmic, and arithmetic operations. All functions support element-wise operations on arrays and universal function (ufunc) behavior.
3

4
## Capabilities
5

6
### Trigonometric Functions
7

8
GPU-accelerated trigonometric functions for angle computations.
9

10
```python { .api }
11
def sin(x, out=None, **kwargs):
12
    """
13
    Trigonometric sine, element-wise.
14
    
15
    Parameters:
16
    - x: array_like, input array in radians
17
    - out: ndarray, optional output array
18
    
19
    Returns:
20
    cupy.ndarray: Sine of x element-wise
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(x1, x2, out=None, **kwargs):
39
    """Element-wise arc tangent of x1/x2 choosing quadrant correctly."""
40

41
def hypot(x1, x2, out=None, **kwargs):
42
    """Return sqrt(x1**2 + x2**2), element-wise."""
43

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

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

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

53
def rad2deg(x, out=None, **kwargs):
54
    """Convert radians to degrees."""
55

56
def unwrap(p, discont=3.141592653589793, axis=-1):
57
    """Unwrap by changing deltas between values to 2*pi complement."""
58
```
59

60
### Hyperbolic Functions
61

62
Hyperbolic trigonometric functions for mathematical computations.
63

64
```python { .api }
65
def sinh(x, out=None, **kwargs):
66
    """Hyperbolic sine, element-wise."""
67

68
def cosh(x, out=None, **kwargs):
69
    """Hyperbolic cosine, element-wise."""
70

71
def tanh(x, out=None, **kwargs):
72
    """Hyperbolic tangent, element-wise."""
73

74
def arcsinh(x, out=None, **kwargs):
75
    """Inverse hyperbolic sine, element-wise."""
76

77
def arccosh(x, out=None, **kwargs):
78
    """Inverse hyperbolic cosine, element-wise."""
79

80
def arctanh(x, out=None, **kwargs):
81
    """Inverse hyperbolic tangent, element-wise."""
82
```
83

84
### Exponential and Logarithmic Functions
85

86
Functions for exponential and logarithmic computations.
87

88
```python { .api }
89
def exp(x, out=None, **kwargs):
90
    """
91
    Calculate exponential of all elements in input array.
92
    
93
    Parameters:
94
    - x: array_like, input values
95
    - out: ndarray, optional output array
96
    
97
    Returns:
98
    cupy.ndarray: Element-wise exponential of x
99
    """
100

101
def exp2(x, out=None, **kwargs):
102
    """Calculate 2**x for all x in input array."""
103

104
def expm1(x, out=None, **kwargs):
105
    """Calculate exp(x) - 1 for all x in input array."""
106

107
def log(x, out=None, **kwargs):
108
    """Natural logarithm, element-wise."""
109

110
def log10(x, out=None, **kwargs):
111
    """Base-10 logarithm of x."""
112

113
def log2(x, out=None, **kwargs):
114
    """Base-2 logarithm of x."""
115

116
def log1p(x, out=None, **kwargs):
117
    """Return natural logarithm of one plus input array."""
118

119
def logaddexp(x1, x2, out=None, **kwargs):
120
    """Logarithm of sum of exponentials of inputs."""
121

122
def logaddexp2(x1, x2, out=None, **kwargs):
123
    """Logarithm of sum of exponentials of inputs in base 2."""
124
```
125

126
### Arithmetic Functions
127

128
Basic arithmetic operations supporting broadcasting and type promotion.
129

130
```python { .api }
131
def add(x1, x2, out=None, **kwargs):
132
    """
133
    Add arguments element-wise.
134
    
135
    Parameters:
136
    - x1, x2: array_like, input arrays to add
137
    - out: ndarray, optional output array
138
    
139
    Returns:  
140
    cupy.ndarray: Sum of x1 and x2, element-wise
141
    """
142

143
def subtract(x1, x2, out=None, **kwargs):
144
    """Subtract arguments element-wise."""
145

146
def multiply(x1, x2, out=None, **kwargs):
147
    """Multiply arguments element-wise."""
148

149
def divide(x1, x2, out=None, **kwargs):
150
    """Divide arguments element-wise."""
151

152
def true_divide(x1, x2, out=None, **kwargs):
153
    """True division of arguments element-wise."""
154

155
def floor_divide(x1, x2, out=None, **kwargs):
156
    """Floor division of arguments element-wise."""
157

158
def power(x1, x2, out=None, **kwargs):
159
    """First array elements raised to powers from second array."""
160

161
def float_power(x1, x2, out=None, **kwargs):
162
    """First array elements raised to powers, promoting to float."""
163

164
def remainder(x1, x2, out=None, **kwargs):
165
    """Return element-wise remainder of division."""
166

167
def mod(x1, x2, out=None, **kwargs):
168
    """Return element-wise remainder of division (same as remainder)."""
169

170
def fmod(x1, x2, out=None, **kwargs):
171
    """Return element-wise remainder of division."""
172

173
def divmod(x1, x2, out1=None, out2=None, **kwargs):
174
    """Return element-wise quotient and remainder."""
175

176
def negative(x, out=None, **kwargs):
177
    """Numerical negative, element-wise."""
178

179
def positive(x, out=None, **kwargs):  
180
    """Numerical positive, element-wise."""
181

182
def reciprocal(x, out=None, **kwargs):
183
    """Return reciprocal of argument, element-wise."""
184
```
185

186
### Complex Number Functions
187

188
Functions for complex number manipulation and analysis.
189

190
```python { .api }
191
def angle(z, deg=False):
192
    """Return angle of complex argument."""
193

194
def real(val):
195
    """Return real part of complex argument."""
196

197
def imag(val):
198
    """Return imaginary part of complex argument."""
199

200
def conjugate(x, out=None, **kwargs):
201
    """Return complex conjugate, element-wise."""
202

203
def conj(x, out=None, **kwargs):
204
    """Return complex conjugate, element-wise (same as conjugate)."""
205
```
206

207
### Rounding Functions
208

209
Functions for rounding and truncating numerical values.
210

211
```python { .api }
212
def around(a, decimals=0, out=None):
213
    """
214
    Round array to given number of decimals.
215
    
216
    Parameters:
217
    - a: array_like, input data
218
    - decimals: int, number of decimal places to round to
219
    - out: ndarray, optional output array
220
    
221
    Returns:
222
    cupy.ndarray: Rounded array
223
    """
224

225
def round_(a, decimals=0, out=None):
226
    """Round array to given number of decimals (same as around)."""
227

228
def rint(x, out=None, **kwargs):
229
    """Round elements to nearest integer."""
230

231
def fix(x, out=None):
232
    """Round to nearest integer towards zero."""
233

234
def floor(x, out=None, **kwargs):
235
    """Return floor of input, element-wise."""
236

237
def ceil(x, out=None, **kwargs):
238
    """Return ceiling of input, element-wise."""
239

240
def trunc(x, out=None, **kwargs):
241
    """Return truncated value of input, element-wise."""
242
```
243

244
### Miscellaneous Mathematical Functions
245

246
Various mathematical utility functions.
247

248
```python { .api }
249
def sqrt(x, out=None, **kwargs):
250
    """
251
    Return non-negative square-root of array, element-wise.
252
    
253
    Parameters:
254
    - x: array_like, input array
255
    - out: ndarray, optional output array
256
    
257
    Returns:
258
    cupy.ndarray: Square-root of x, element-wise
259
    """
260

261
def square(x, out=None, **kwargs):
262
    """Return element-wise square of input."""
263

264
def absolute(x, out=None, **kwargs):
265
    """Calculate absolute value element-wise."""
266

267
def abs(x, out=None, **kwargs):
268
    """Calculate absolute value element-wise (same as absolute)."""
269

270
def cbrt(x, out=None, **kwargs):
271
    """Return cube-root of array, element-wise."""
272

273
def fabs(x, out=None, **kwargs):
274
    """Compute absolute values element-wise."""
275

276
def sign(x, out=None, **kwargs):
277
    """Returns element-wise indication of sign of number."""
278

279
def heaviside(x1, x2, out=None, **kwargs):
280
    """Compute Heaviside step function."""
281

282
def maximum(x1, x2, out=None, **kwargs):
283
    """Element-wise maximum of array elements."""
284

285
def minimum(x1, x2, out=None, **kwargs):
286
    """Element-wise minimum of array elements."""
287

288
def fmax(x1, x2, out=None, **kwargs):
289
    """Element-wise maximum of array elements (ignores NaNs)."""
290

291
def fmin(x1, x2, out=None, **kwargs):
292
    """Element-wise minimum of array elements (ignores NaNs)."""
293

294
def clip(a, a_min, a_max, out=None, **kwargs):
295
    """Clip values in array to specified range."""
296

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

300
def real_if_close(a, tol=100):
301
    """If complex input returns real part if imaginary part is close to zero."""
302

303
def interp(x, xp, fp, left=None, right=None, period=None):
304
    """One-dimensional linear interpolation."""
305

306
def convolve(a, v, mode='full'):
307
    """Return discrete linear convolution of one-dimensional arrays."""
308
```
309

310
### Special Functions
311

312
Special mathematical functions for advanced computations.
313

314
```python { .api }
315
def i0(x):
316
    """Modified Bessel function of first kind, order 0."""
317

318
def sinc(x):
319
    """Return sinc function (sin(pi*x)/(pi*x))."""
320
```
321

322
### Floating Point Functions
323

324
Functions for floating point number manipulation and analysis.
325

326
```python { .api }
327
def copysign(x1, x2, out=None, **kwargs):
328
    """Change sign of x1 to that of x2, element-wise."""
329

330
def frexp(x, out1=None, out2=None, **kwargs):
331
    """Decompose elements of x into mantissa and exponent."""
332

333
def ldexp(x1, x2, out=None, **kwargs):
334
    """Compute x1 * 2**x2, element-wise."""
335

336
def nextafter(x1, x2, out=None, **kwargs):
337
    """Return next floating-point value after x1 towards x2."""
338

339
def signbit(x, out=None, **kwargs):
340
    """Returns element-wise True where signbit is set."""
341
```
342

343
### Integer Functions
344

345
Functions specific to integer operations.
346

347
```python { .api }
348
def gcd(x1, x2, out=None, **kwargs):
349
    """Return greatest common divisor of |x1| and |x2|."""
350

351
def lcm(x1, x2, out=None, **kwargs):
352
    """Return least common multiple of |x1| and |x2|."""
353
```
354

355
## Usage Examples
356

357
### Basic Mathematical Operations
358

359
```python
360
import cupy as cp
361

362
# Create sample data
363
x = cp.linspace(0, 2*cp.pi, 100)
364
y = cp.random.random((1000, 1000))
365

366
# Trigonometric functions
367
sin_x = cp.sin(x)
368
cos_x = cp.cos(x)
369
tan_x = cp.tan(x)
370

371
# Combine operations
372
result = cp.sin(x) * cp.cos(x) + cp.tan(x/2)
373

374
# Exponential and logarithmic
375
exp_y = cp.exp(y)
376
log_y = cp.log(y + 1)  # Add 1 to avoid log(0)
377

378
# Power operations
379
squared = cp.square(y)
380
sqrt_y = cp.sqrt(y)
381
power_result = cp.power(y, 2.5)
382
```
383

384
### Advanced Mathematical Computations
385

386
```python
387
# Complex number operations
388
complex_arr = cp.array([1+2j, 3-4j, 5+0j])
389
magnitudes = cp.absolute(complex_arr)
390
angles = cp.angle(complex_arr)
391
conjugates = cp.conjugate(complex_arr)
392

393
# Rounding and clipping
394
data = cp.random.normal(0, 1, (100, 100))
395
rounded = cp.around(data, decimals=2)
396
clipped = cp.clip(data, -2, 2)
397

398
# Element-wise comparisons and selections
399
a = cp.random.random((100, 100))
400
b = cp.random.random((100, 100))
401
max_values = cp.maximum(a, b)
402
min_values = cp.minimum(a, b)
403
```
404

405
### Broadcasting and Universal Functions
406

407
```python
408
# Broadcasting with different shapes
409
scalar = 5
410
vector = cp.array([1, 2, 3, 4])
411
matrix = cp.random.random((4, 3))
412

413
# Operations automatically broadcast
414
result1 = matrix + scalar  # Add scalar to all elements
415
result2 = matrix + vector.reshape(-1, 1)  # Add vector to each column
416

417
# Universal function behavior
418
ufunc_result = cp.add.reduce(matrix, axis=0)  # Sum along first axis
419
accumulated = cp.add.accumulate(vector)  # Cumulative sum
420
```