0
# Mathematical Functions
1

2
Comprehensive set of mathematical functions optimized for GPU execution, including trigonometric, exponential, logarithmic, and special functions that operate element-wise on arrays with high performance and numerical accuracy.
3

4
## Capabilities
5

6
### Trigonometric Functions
7

8
Standard trigonometric functions with high accuracy and performance on GPU arrays.
9

10
```python { .api }
11
def sin(x, queue=None):
12
    """
13
    Element-wise sine function.
14
    
15
    Parameters:
16
    - x (Array): Input array
17
    - queue (CommandQueue, optional): Command queue
18
    
19
    Returns:
20
    Array: Sine of each element
21
    """
22

23
def cos(x, queue=None):
24
    """
25
    Element-wise cosine function.
26
    
27
    Parameters:
28
    - x (Array): Input array
29
    - queue (CommandQueue, optional): Command queue
30
    
31
    Returns:
32
    Array: Cosine of each element
33
    """
34

35
def tan(x, queue=None):
36
    """
37
    Element-wise tangent function.
38
    
39
    Parameters:
40
    - x (Array): Input array
41
    - queue (CommandQueue, optional): Command queue
42
    
43
    Returns:
44
    Array: Tangent of each element
45
    """
46

47
def asin(x, queue=None):
48
    """
49
    Element-wise arcsine function.
50
    
51
    Parameters:
52
    - x (Array): Input array (values in [-1, 1])
53
    - queue (CommandQueue, optional): Command queue
54
    
55
    Returns:
56
    Array: Arcsine of each element in radians
57
    """
58

59
def acos(x, queue=None):
60
    """
61
    Element-wise arccosine function.
62
    
63
    Parameters:
64
    - x (Array): Input array (values in [-1, 1])
65
    - queue (CommandQueue, optional): Command queue
66
    
67
    Returns:
68
    Array: Arccosine of each element in radians
69
    """
70

71
def atan(x, queue=None):
72
    """
73
    Element-wise arctangent function.
74
    
75
    Parameters:
76
    - x (Array): Input array
77
    - queue (CommandQueue, optional): Command queue
78
    
79
    Returns:
80
    Array: Arctangent of each element in radians
81
    """
82
```
83

84
### Hyperbolic Functions
85

86
Hyperbolic trigonometric functions and their inverses.
87

88
```python { .api }
89
def sinh(x, queue=None):
90
    """
91
    Element-wise hyperbolic sine function.
92
    
93
    Parameters:
94
    - x (Array): Input array
95
    - queue (CommandQueue, optional): Command queue
96
    
97
    Returns:
98
    Array: Hyperbolic sine of each element
99
    """
100

101
def cosh(x, queue=None):
102
    """
103
    Element-wise hyperbolic cosine function.
104
    
105
    Parameters:
106
    - x (Array): Input array
107
    - queue (CommandQueue, optional): Command queue
108
    
109
    Returns:
110
    Array: Hyperbolic cosine of each element
111
    """
112

113
def tanh(x, queue=None):
114
    """
115
    Element-wise hyperbolic tangent function.
116
    
117
    Parameters:
118
    - x (Array): Input array
119
    - queue (CommandQueue, optional): Command queue
120
    
121
    Returns:
122
    Array: Hyperbolic tangent of each element
123
    """
124

125
def asinh(x, queue=None):
126
    """
127
    Element-wise inverse hyperbolic sine function.
128
    
129
    Parameters:
130
    - x (Array): Input array
131
    - queue (CommandQueue, optional): Command queue
132
    
133
    Returns:
134
    Array: Inverse hyperbolic sine of each element
135
    """
136

137
def acosh(x, queue=None):
138
    """
139
    Element-wise inverse hyperbolic cosine function.
140
    
141
    Parameters:
142
    - x (Array): Input array (values >= 1)
143
    - queue (CommandQueue, optional): Command queue
144
    
145
    Returns:
146
    Array: Inverse hyperbolic cosine of each element
147
    """
148

149
def atanh(x, queue=None):
150
    """
151
    Element-wise inverse hyperbolic tangent function.
152
    
153
    Parameters:
154
    - x (Array): Input array (values in (-1, 1))
155
    - queue (CommandQueue, optional): Command queue
156
    
157
    Returns:
158
    Array: Inverse hyperbolic tangent of each element
159
    """
160
```
161

162
### Pi-based Trigonometric Functions
163

164
Trigonometric functions using π as the base unit for improved accuracy with π multiples.
165

166
```python { .api }
167
def sinpi(x, queue=None):
168
    """
169
    Element-wise sin(π*x) function.
170
    
171
    Parameters:
172
    - x (Array): Input array
173
    - queue (CommandQueue, optional): Command queue
174
    
175
    Returns:
176
    Array: sin(π*x) for each element
177
    """
178

179
def cospi(x, queue=None):
180
    """
181
    Element-wise cos(π*x) function.
182
    
183
    Parameters:
184
    - x (Array): Input array
185
    - queue (CommandQueue, optional): Command queue
186
    
187
    Returns:
188
    Array: cos(π*x) for each element
189
    """
190

191
def tanpi(x, queue=None):
192
    """
193
    Element-wise tan(π*x) function.
194
    
195
    Parameters:
196
    - x (Array): Input array
197
    - queue (CommandQueue, optional): Command queue
198
    
199
    Returns:
200
    Array: tan(π*x) for each element
201
    """
202

203
def asinpi(x, queue=None):
204
    """
205
    Element-wise asin(x)/π function.
206
    
207
    Parameters:
208
    - x (Array): Input array (values in [-1, 1])
209
    - queue (CommandQueue, optional): Command queue
210
    
211
    Returns:
212
    Array: asin(x)/π for each element
213
    """
214

215
def acospi(x, queue=None):
216
    """
217
    Element-wise acos(x)/π function.
218
    
219
    Parameters:
220
    - x (Array): Input array (values in [-1, 1])
221
    - queue (CommandQueue, optional): Command queue
222
    
223
    Returns:
224
    Array: acos(x)/π for each element
225
    """
226

227
def atanpi(x, queue=None):
228
    """
229
    Element-wise atan(x)/π function.
230
    
231
    Parameters:
232
    - x (Array): Input array
233
    - queue (CommandQueue, optional): Command queue
234
    
235
    Returns:
236
    Array: atan(x)/π for each element
237
    """
238
```
239

240
### Exponential Functions
241

242
Exponential functions with different bases for scientific computation.
243

244
```python { .api }
245
def exp(x, queue=None):
246
    """
247
    Element-wise natural exponential function (e^x).
248
    
249
    Parameters:
250
    - x (Array): Input array
251
    - queue (CommandQueue, optional): Command queue
252
    
253
    Returns:
254
    Array: e^x for each element
255
    """
256

257
def exp2(x, queue=None):
258
    """
259
    Element-wise base-2 exponential function (2^x).
260
    
261
    Parameters:
262
    - x (Array): Input array
263
    - queue (CommandQueue, optional): Command queue
264
    
265
    Returns:
266
    Array: 2^x for each element
267
    """
268

269
def exp10(x, queue=None):
270
    """
271
    Element-wise base-10 exponential function (10^x).
272
    
273
    Parameters:
274
    - x (Array): Input array
275
    - queue (CommandQueue, optional): Command queue
276
    
277
    Returns:
278
    Array: 10^x for each element
279
    """
280

281
def expm1(x, queue=None):
282
    """
283
    Element-wise exp(x) - 1 function with improved accuracy for small x.
284
    
285
    Parameters:
286
    - x (Array): Input array
287
    - queue (CommandQueue, optional): Command queue
288
    
289
    Returns:
290
    Array: exp(x) - 1 for each element
291
    """
292
```
293

294
### Logarithmic Functions
295

296
Logarithmic functions with different bases and specialized variants.
297

298
```python { .api }
299
def log(x, queue=None):
300
    """
301
    Element-wise natural logarithm function.
302
    
303
    Parameters:
304
    - x (Array): Input array (values > 0)
305
    - queue (CommandQueue, optional): Command queue
306
    
307
    Returns:
308
    Array: Natural logarithm of each element
309
    """
310

311
def log2(x, queue=None):
312
    """
313
    Element-wise base-2 logarithm function.
314
    
315
    Parameters:
316
    - x (Array): Input array (values > 0)
317
    - queue (CommandQueue, optional): Command queue
318
    
319
    Returns:
320
    Array: Base-2 logarithm of each element
321
    """
322

323
def log10(x, queue=None):
324
    """
325
    Element-wise base-10 logarithm function.
326
    
327
    Parameters:
328
    - x (Array): Input array (values > 0)
329
    - queue (CommandQueue, optional): Command queue
330
    
331
    Returns:
332
    Array: Base-10 logarithm of each element
333
    """
334

335
def log1p(x, queue=None):
336
    """
337
    Element-wise log(1 + x) function with improved accuracy for small x.
338
    
339
    Parameters:
340
    - x (Array): Input array (values > -1)
341
    - queue (CommandQueue, optional): Command queue
342
    
343
    Returns:
344
    Array: log(1 + x) for each element
345
    """
346

347
def logb(x, queue=None):
348
    """
349
    Element-wise extract exponent function.
350
    
351
    Parameters:
352
    - x (Array): Input array (finite non-zero values)
353
    - queue (CommandQueue, optional): Command queue
354
    
355
    Returns:
356
    Array: Exponent of each element
357
    """
358

359
def ilogb(x, queue=None):
360
    """
361
    Element-wise extract exponent as integer.
362
    
363
    Parameters:
364
    - x (Array): Input array (finite non-zero values)
365
    - queue (CommandQueue, optional): Command queue
366
    
367
    Returns:
368
    Array: Integer exponent of each element
369
    """
370
```
371

372
### Root Functions
373

374
Square root, cube root, and related functions.
375

376
```python { .api }
377
def sqrt(x, queue=None):
378
    """
379
    Element-wise square root function.
380
    
381
    Parameters:
382
    - x (Array): Input array (values >= 0)
383
    - queue (CommandQueue, optional): Command queue
384
    
385
    Returns:
386
    Array: Square root of each element
387
    """
388

389
def cbrt(x, queue=None):
390
    """
391
    Element-wise cube root function.
392
    
393
    Parameters:
394
    - x (Array): Input array
395
    - queue (CommandQueue, optional): Command queue
396
    
397
    Returns:
398
    Array: Cube root of each element
399
    """
400
```
401

402
### Rounding Functions
403

404
Various rounding and truncation operations.
405

406
```python { .api }
407
def ceil(x, queue=None):
408
    """
409
    Element-wise ceiling function (round up to nearest integer).
410
    
411
    Parameters:
412
    - x (Array): Input array
413
    - queue (CommandQueue, optional): Command queue
414
    
415
    Returns:
416
    Array: Ceiling of each element
417
    """
418

419
def floor(x, queue=None):
420
    """
421
    Element-wise floor function (round down to nearest integer).
422
    
423
    Parameters:
424
    - x (Array): Input array
425
    - queue (CommandQueue, optional): Command queue
426
    
427
    Returns:
428
    Array: Floor of each element
429
    """
430

431
def round(x, queue=None):
432
    """
433
    Element-wise round to nearest integer function.
434
    
435
    Parameters:
436
    - x (Array): Input array
437
    - queue (CommandQueue, optional): Command queue
438
    
439
    Returns:
440
    Array: Nearest integer for each element
441
    """
442

443
def rint(x, queue=None):
444
    """
445
    Element-wise round to nearest integer function.
446
    
447
    Parameters:
448
    - x (Array): Input array
449
    - queue (CommandQueue, optional): Command queue
450
    
451
    Returns:
452
    Array: Nearest integer for each element
453
    """
454

455
def trunc(x, queue=None):
456
    """
457
    Element-wise truncate to integer function (toward zero).
458
    
459
    Parameters:
460
    - x (Array): Input array
461
    - queue (CommandQueue, optional): Command queue
462
    
463
    Returns:
464
    Array: Truncated integer for each element
465
    """
466
```
467

468
### Absolute Value and Sign Functions
469

470
Functions for magnitude and sign operations.
471

472
```python { .api }
473
def fabs(x, queue=None):
474
    """
475
    Element-wise absolute value function.
476
    
477
    Parameters:
478
    - x (Array): Input array
479
    - queue (CommandQueue, optional): Command queue
480
    
481
    Returns:
482
    Array: Absolute value of each element
483
    """
484
```
485

486
### Special Functions
487

488
Error functions, gamma functions, and other special mathematical functions.
489

490
```python { .api }
491
def erf(x, queue=None):
492
    """
493
    Element-wise error function.
494
    
495
    Parameters:
496
    - x (Array): Input array
497
    - queue (CommandQueue, optional): Command queue
498
    
499
    Returns:
500
    Array: Error function of each element
501
    """
502

503
def erfc(x, queue=None):
504
    """
505
    Element-wise complementary error function.
506
    
507
    Parameters:
508
    - x (Array): Input array
509
    - queue (CommandQueue, optional): Command queue
510
    
511
    Returns:
512
    Array: Complementary error function (1 - erf(x))
513
    """
514

515
def tgamma(x, queue=None):
516
    """
517
    Element-wise true gamma function.
518
    
519
    Parameters:
520
    - x (Array): Input array
521
    - queue (CommandQueue, optional): Command queue
522
    
523
    Returns:
524
    Array: Gamma function of each element
525
    """
526

527
def lgamma(x, queue=None):
528
    """
529
    Element-wise natural logarithm of absolute value of gamma function.
530
    
531
    Parameters:
532
    - x (Array): Input array
533
    - queue (CommandQueue, optional): Command queue
534
    
535
    Returns:
536
    Array: log(|gamma(x)|) for each element
537
    """
538
```
539

540
### Utility Functions
541

542
Utility functions for special values and numerical operations.
543

544
```python { .api }
545
def nan(x, queue=None):
546
    """
547
    Generate NaN (Not a Number) values.
548
    
549
    Parameters:
550
    - x (Array): Input array (used for shape and type)
551
    - queue (CommandQueue, optional): Command queue
552
    
553
    Returns:
554
    Array: Array filled with NaN values
555
    """
556
```
557

558
## Usage Examples
559

560
### Basic Mathematical Operations
561

562
```python
563
import pyopencl as cl
564
import pyopencl.array as cl_array
565
import pyopencl.clmath as clmath
566
import numpy as np
567

568
# Setup
569
ctx = cl.create_some_context()
570
queue = cl.CommandQueue(ctx)
571

572
# Create array with angles
573
angles = cl_array.arange(queue, 0, 2*np.pi, 0.1, dtype=np.float32)
574

575
# Trigonometric functions
576
sin_values = clmath.sin(angles)
577
cos_values = clmath.cos(angles)
578
tan_values = clmath.tan(angles)
579

580
print(f"Angles shape: {angles.shape}")
581
print(f"Sin values: {sin_values.get()[:5]}")
582
print(f"Cos values: {cos_values.get()[:5]}")
583
```
584

585
### Exponential and Logarithmic Functions
586

587
```python
588
import pyopencl as cl
589
import pyopencl.array as cl_array
590
import pyopencl.clmath as clmath
591
import numpy as np
592

593
# Setup
594
ctx = cl.create_some_context()
595
queue = cl.CommandQueue(ctx)
596

597
# Create array
598
x = cl_array.arange(queue, 0.1, 10, 0.1, dtype=np.float32)
599

600
# Exponential functions
601
exp_x = clmath.exp(x)
602
exp2_x = clmath.exp2(x)
603
exp10_x = clmath.exp10(x)
604

605
# Logarithmic functions
606
log_x = clmath.log(x)
607
log2_x = clmath.log2(x)
608
log10_x = clmath.log10(x)
609

610
print(f"Original: {x.get()[:5]}")
611
print(f"exp(x): {exp_x.get()[:5]}")
612
print(f"log(x): {log_x.get()[:5]}")
613
```
614

615
### Special Functions for Scientific Computing
616

617
```python
618
import pyopencl as cl
619
import pyopencl.array as cl_array
620
import pyopencl.clmath as clmath
621
import numpy as np
622

623
# Setup
624
ctx = cl.create_some_context()
625
queue = cl.CommandQueue(ctx)
626

627
# Create array for statistical/probability calculations
628
x = cl_array.arange(queue, -3, 3, 0.1, dtype=np.float32)
629

630
# Error function (used in statistics)
631
erf_x = clmath.erf(x)
632
erfc_x = clmath.erfc(x)
633

634
# Gamma function (used in probability distributions)
635
positive_x = cl_array.arange(queue, 0.1, 5, 0.1, dtype=np.float32)
636
gamma_x = clmath.tgamma(positive_x)
637
lgamma_x = clmath.lgamma(positive_x)
638

639
print(f"Error function: {erf_x.get()[:5]}")
640
print(f"Gamma function: {gamma_x.get()[:5]}")
641
```
642

643
### Rounding and Precision Control
644

645
```python
646
import pyopencl as cl
647
import pyopencl.array as cl_array
648
import pyopencl.clmath as clmath
649
import numpy as np
650

651
# Setup
652
ctx = cl.create_some_context()
653
queue = cl.CommandQueue(ctx)
654

655
# Create array with decimal values
656
x = cl_array.to_device(queue, np.array([-2.7, -1.3, 0.5, 1.8, 2.9], dtype=np.float32))
657

658
# Different rounding operations
659
ceil_x = clmath.ceil(x)
660
floor_x = clmath.floor(x)
661
round_x = clmath.round(x)
662
trunc_x = clmath.trunc(x)
663

664
print(f"Original: {x.get()}")
665
print(f"Ceiling: {ceil_x.get()}")
666
print(f"Floor: {floor_x.get()}")
667
print(f"Round: {round_x.get()}")
668
print(f"Truncate: {trunc_x.get()}")
669
```
670

671
### Combining Mathematical Functions
672

673
```python
674
import pyopencl as cl
675
import pyopencl.array as cl_array
676
import pyopencl.clmath as clmath
677
import numpy as np
678

679
# Setup
680
ctx = cl.create_some_context()
681
queue = cl.CommandQueue(ctx)
682

683
# Create input array
684
x = cl_array.arange(queue, 0, 4*np.pi, 0.1, dtype=np.float32)
685

686
# Complex mathematical expression: exp(-x/10) * sin(x)
687
damped_sine = clmath.exp(-x/10) * clmath.sin(x)
688

689
# Another example: sqrt(x^2 + 1) 
690
x_vals = cl_array.arange(queue, -10, 10, 0.1, dtype=np.float32)
691
hypot_like = clmath.sqrt(x_vals*x_vals + 1)
692

693
print(f"Damped sine wave: {damped_sine.get()[:10]}")
694
print(f"Hypot-like function: {hypot_like.get()[:10]}")
695
```