0
# Math Functions
1

2
CUDA math function wrappers providing GPU-accelerated mathematical operations for arrays including trigonometric, exponential, and logarithmic functions. These functions operate element-wise on GPU arrays with automatic type handling.
3

4
## Capabilities
5

6
### Trigonometric Functions
7

8
Element-wise trigonometric functions for GPU arrays.
9

10
```python { .api }
11
def sin(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
12
    """
13
    Element-wise sine function.
14
    
15
    Parameters:
16
    - array: GPUArray, input array
17
    - out: GPUArray, output array (optional)
18
    - stream: Stream, CUDA stream (optional)
19
    
20
    Returns:
21
    GPUArray: sine of input elements
22
    """
23

24
def cos(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
25
    """Element-wise cosine function."""
26

27
def tan(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
28
    """Element-wise tangent function."""
29

30
def asin(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
31
    """Element-wise arcsine function."""
32

33
def acos(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
34
    """Element-wise arccosine function."""
35

36
def atan(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
37
    """Element-wise arctangent function."""
38

39
def atan2(y: GPUArray, x: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
40
    """
41
    Element-wise arctangent of y/x with correct quadrant.
42
    
43
    Parameters:
44
    - y: GPUArray, y coordinates
45
    - x: GPUArray, x coordinates
46
    - out: GPUArray, output array (optional)
47
    - stream: Stream, CUDA stream (optional)
48
    
49
    Returns:
50
    GPUArray: arctangent of y/x in correct quadrant
51
    """
52
```
53

54
### Hyperbolic Functions
55

56
Element-wise hyperbolic functions for GPU arrays.
57

58
```python { .api }
59
def sinh(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
60
    """
61
    Element-wise hyperbolic sine function.
62
    
63
    Parameters:
64
    - array: GPUArray, input array
65
    - out: GPUArray, output array (optional)
66
    - stream: Stream, CUDA stream (optional)
67
    
68
    Returns:
69
    GPUArray: hyperbolic sine of input elements
70
    """
71

72
def cosh(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
73
    """Element-wise hyperbolic cosine function."""
74

75
def tanh(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
76
    """Element-wise hyperbolic tangent function."""
77

78
def asinh(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
79
    """Element-wise inverse hyperbolic sine function."""
80

81
def acosh(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
82
    """Element-wise inverse hyperbolic cosine function."""
83

84
def atanh(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
85
    """Element-wise inverse hyperbolic tangent function."""
86
```
87

88
### Exponential and Logarithmic Functions
89

90
Element-wise exponential and logarithmic functions.
91

92
```python { .api }
93
def exp(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
94
    """
95
    Element-wise exponential function (e^x).
96
    
97
    Parameters:
98
    - array: GPUArray, input array
99
    - out: GPUArray, output array (optional)
100
    - stream: Stream, CUDA stream (optional)
101
    
102
    Returns:
103
    GPUArray: exponential of input elements
104
    """
105

106
def exp2(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
107
    """Element-wise base-2 exponential function (2^x)."""
108

109
def exp10(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
110
    """Element-wise base-10 exponential function (10^x)."""
111

112
def expm1(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
113
    """Element-wise exp(x) - 1 function (accurate for small x)."""
114

115
def log(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
116
    """
117
    Element-wise natural logarithm function.
118
    
119
    Parameters:
120
    - array: GPUArray, input array
121
    - out: GPUArray, output array (optional)
122
    - stream: Stream, CUDA stream (optional)
123
    
124
    Returns:
125
    GPUArray: natural logarithm of input elements
126
    """
127

128
def log2(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
129
    """Element-wise base-2 logarithm function."""
130

131
def log10(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
132
    """Element-wise base-10 logarithm function."""
133

134
def log1p(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
135
    """Element-wise log(1 + x) function (accurate for small x)."""
136
```
137

138
### Power and Root Functions
139

140
Element-wise power and root functions.
141

142
```python { .api }
143
def pow(base: GPUArray, exponent: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
144
    """
145
    Element-wise power function (base^exponent).
146
    
147
    Parameters:
148
    - base: GPUArray, base values
149
    - exponent: GPUArray, exponent values
150
    - out: GPUArray, output array (optional)
151
    - stream: Stream, CUDA stream (optional)
152
    
153
    Returns:
154
    GPUArray: base raised to exponent power
155
    """
156

157
def sqrt(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
158
    """
159
    Element-wise square root function.
160
    
161
    Parameters:
162
    - array: GPUArray, input array
163
    - out: GPUArray, output array (optional)
164
    - stream: Stream, CUDA stream (optional)
165
    
166
    Returns:
167
    GPUArray: square root of input elements
168
    """
169

170
def rsqrt(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
171
    """Element-wise reciprocal square root function (1/sqrt(x))."""
172

173
def cbrt(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
174
    """Element-wise cube root function."""
175

176
def rcbrt(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
177
    """Element-wise reciprocal cube root function (1/cbrt(x))."""
178
```
179

180
### Rounding and Absolute Value Functions
181

182
Element-wise rounding and absolute value functions.
183

184
```python { .api }
185
def fabs(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
186
    """
187
    Element-wise absolute value function.
188
    
189
    Parameters:
190
    - array: GPUArray, input array
191
    - out: GPUArray, output array (optional)
192
    - stream: Stream, CUDA stream (optional)
193
    
194
    Returns:
195
    GPUArray: absolute value of input elements
196
    """
197

198
def ceil(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
199
    """Element-wise ceiling function (round up to nearest integer)."""
200

201
def floor(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
202
    """Element-wise floor function (round down to nearest integer)."""
203

204
def trunc(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
205
    """Element-wise truncation function (round toward zero)."""
206

207
def round(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
208
    """Element-wise round function (round to nearest integer)."""
209

210
def rint(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
211
    """Element-wise round to nearest integer function."""
212
```
213

214
### Special Functions
215

216
Element-wise special mathematical functions.
217

218
```python { .api }
219
def erf(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
220
    """
221
    Element-wise error function.
222
    
223
    Parameters:
224
    - array: GPUArray, input array
225
    - out: GPUArray, output array (optional)
226
    - stream: Stream, CUDA stream (optional)
227
    
228
    Returns:
229
    GPUArray: error function of input elements
230
    """
231

232
def erfc(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
233
    """Element-wise complementary error function."""
234

235
def gamma(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
236
    """Element-wise gamma function."""
237

238
def lgamma(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
239
    """Element-wise log gamma function."""
240

241
def j0(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
242
    """Element-wise Bessel function of the first kind of order 0."""
243

244
def j1(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
245
    """Element-wise Bessel function of the first kind of order 1."""
246

247
def y0(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
248
    """Element-wise Bessel function of the second kind of order 0."""
249

250
def y1(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
251
    """Element-wise Bessel function of the second kind of order 1."""
252
```
253

254
### Floating-Point Manipulation
255

256
Functions for manipulating floating-point representations.
257

258
```python { .api }
259
def fmod(x: GPUArray, y: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
260
    """
261
    Element-wise floating-point remainder of x/y.
262
    
263
    Parameters:
264
    - x: GPUArray, dividend
265
    - y: GPUArray, divisor
266
    - out: GPUArray, output array (optional)
267
    - stream: Stream, CUDA stream (optional)
268
    
269
    Returns:
270
    GPUArray: floating-point remainder
271
    """
272

273
def modf(array: GPUArray, int_part: GPUArray = None, stream: Stream = None) -> tuple[GPUArray, GPUArray]:
274
    """
275
    Element-wise split into fractional and integer parts.
276
    
277
    Parameters:
278
    - array: GPUArray, input array
279
    - int_part: GPUArray, output for integer parts (optional)
280
    - stream: Stream, CUDA stream (optional)
281
    
282
    Returns:
283
    tuple: (fractional_part, integer_part) as GPUArrays
284
    """
285

286
def frexp(array: GPUArray, exp_array: GPUArray = None, stream: Stream = None) -> tuple[GPUArray, GPUArray]:
287
    """
288
    Element-wise extract mantissa and exponent.
289
    
290
    Parameters:
291
    - array: GPUArray, input array
292
    - exp_array: GPUArray, output for exponents (optional)
293
    - stream: Stream, CUDA stream (optional)
294
    
295
    Returns:
296
    tuple: (mantissa, exponent) as GPUArrays
297
    """
298

299
def ldexp(mantissa: GPUArray, exponent: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
300
    """
301
    Element-wise load exponent (mantissa * 2^exponent).
302
    
303
    Parameters:
304
    - mantissa: GPUArray, mantissa values
305
    - exponent: GPUArray, exponent values
306
    - out: GPUArray, output array (optional)
307
    - stream: Stream, CUDA stream (optional)
308
    
309
    Returns:
310
    GPUArray: mantissa * 2^exponent
311
    """
312
```
313

314
### Comparison Functions
315

316
Element-wise comparison and selection functions.
317

318
```python { .api }
319
def fmax(x: GPUArray, y: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
320
    """
321
    Element-wise maximum (handles NaN correctly).
322
    
323
    Parameters:
324
    - x: GPUArray, first array
325
    - y: GPUArray, second array
326
    - out: GPUArray, output array (optional)
327
    - stream: Stream, CUDA stream (optional)
328
    
329
    Returns:
330
    GPUArray: element-wise maximum
331
    """
332

333
def fmin(x: GPUArray, y: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
334
    """Element-wise minimum (handles NaN correctly)."""
335

336
def copysign(magnitude: GPUArray, sign: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
337
    """
338
    Element-wise copy sign from one array to magnitude of another.
339
    
340
    Parameters:
341
    - magnitude: GPUArray, magnitude values
342
    - sign: GPUArray, sign values
343
    - out: GPUArray, output array (optional)
344
    - stream: Stream, CUDA stream (optional)
345
    
346
    Returns:
347
    GPUArray: magnitude with sign from sign array
348
    """
349

350
def signbit(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
351
    """
352
    Element-wise test for sign bit.
353
    
354
    Parameters:
355
    - array: GPUArray, input array
356
    - out: GPUArray, output array (optional)
357
    - stream: Stream, CUDA stream (optional)
358
    
359
    Returns:
360
    GPUArray: non-zero where sign bit is set
361
    """
362
```
363

364
### Complex Number Functions
365

366
Functions for complex number operations on GPU arrays.
367

368
```python { .api }
369
def real(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
370
    """
371
    Extract real part of complex array.
372
    
373
    Parameters:
374
    - array: GPUArray, complex input array
375
    - out: GPUArray, output array (optional)
376
    - stream: Stream, CUDA stream (optional)
377
    
378
    Returns:
379
    GPUArray: real part of input elements
380
    """
381

382
def imag(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
383
    """Extract imaginary part of complex array."""
384

385
def conj(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
386
    """Complex conjugate of array elements."""
387

388
def abs(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
389
    """
390
    Absolute value (magnitude) of array elements.
391
    
392
    Parameters:
393
    - array: GPUArray, input array (real or complex)
394
    - out: GPUArray, output array (optional)  
395
    - stream: Stream, CUDA stream (optional)
396
    
397
    Returns:
398
    GPUArray: absolute value of input elements
399
    """
400

401
def arg(array: GPUArray, out: GPUArray = None, stream: Stream = None) -> GPUArray:
402
    """Phase angle of complex array elements."""
403
```
404

405
## Usage Examples
406

407
### Basic Math Operations
408

409
```python
410
import pycuda.gpuarray as gpuarray
411
import pycuda.cumath as cumath
412
import numpy as np
413

414
# Create test array
415
x = gpuarray.to_gpu(np.linspace(0, np.pi, 100).astype(np.float32))
416

417
# Trigonometric functions
418
sin_x = cumath.sin(x)
419
cos_x = cumath.cos(x)
420
tan_x = cumath.tan(x)
421

422
# Exponential and logarithmic
423
exp_x = cumath.exp(x)
424
log_x = cumath.log(x + 1)  # Add 1 to avoid log(0)
425

426
# Power functions
427
sqrt_x = cumath.sqrt(x)
428
pow_x = cumath.pow(x, 2.0)
429
```
430

431
### Complex Number Operations
432

433
```python
434
# Complex array operations
435
complex_array = gpuarray.to_gpu(np.array([1+2j, 3+4j, 5+6j], dtype=np.complex64))
436

437
# Extract components
438
real_part = cumath.real(complex_array)
439
imag_part = cumath.imag(complex_array)
440

441
# Complex operations
442
magnitude = cumath.abs(complex_array)
443
phase = cumath.arg(complex_array)
444
conjugate = cumath.conj(complex_array)
445
```
446

447
### In-Place Operations
448

449
```python
450
# In-place operations (when out parameter equals input)
451
x = gpuarray.to_gpu(np.array([1.0, 2.0, 3.0, 4.0], dtype=np.float32))
452

453
# Square root in-place
454
cumath.sqrt(x, out=x)  # x is now [1.0, 1.414, 1.732, 2.0]
455

456
# Exponential in-place  
457
cumath.exp(x, out=x)   # x is now exp of previous values
458
```