0
# Array Operations
1

2
High-level NumPy-like GPU array interface providing familiar array operations, mathematical functions, and data manipulation. Enables seamless transition from CPU to GPU computing with automatic memory management and comprehensive array operations.
3

4
## Capabilities
5

6
### Array Creation and Management
7

8
Create and manage GPU arrays with NumPy-compatible interface and automatic memory management.
9

10
```python { .api }
11
class Array:
12
    """
13
    GPU array with NumPy-like interface for device computation.
14
    
15
    Attributes:
16
    - context (Context): OpenCL context
17
    - queue (CommandQueue): Command queue  
18
    - allocator: Memory allocator
19
    - shape (tuple[int, ...]): Array dimensions
20
    - dtype (numpy.dtype): Data type
21
    - size (int): Total number of elements
22
    - nbytes (int): Total bytes
23
    - ndim (int): Number of dimensions
24
    - strides (tuple[int, ...]): Memory strides
25
    """
26
    
27
    def get(self, queue=None, ary=None, async_=False):
28
        """
29
        Transfer array data to host.
30
        
31
        Parameters:
32
        - queue (CommandQueue, optional): Command queue
33
        - ary (numpy.ndarray, optional): Destination array
34
        - async_ (bool): Asynchronous transfer
35
        
36
        Returns:
37
        numpy.ndarray: Host array with data
38
        """
39
    
40
    def set(self, ary, queue=None, async_=False):
41
        """
42
        Transfer data from host to array.
43
        
44
        Parameters:
45
        - ary (numpy.ndarray): Source host array
46
        - queue (CommandQueue, optional): Command queue
47
        - async_ (bool): Asynchronous transfer
48
        """
49
    
50
    def copy(self, queue=None):
51
        """Create copy of array."""
52
    
53
    def __getitem__(self, subscript):
54
        """Array indexing and slicing."""
55
    
56
    def __setitem__(self, subscript, value):
57
        """Array assignment with indexing."""
58
    
59
    # Element-wise operations
60
    def __add__(self, other):
61
        """Element-wise addition."""
62
    
63
    def __sub__(self, other):
64
        """Element-wise subtraction."""
65
    
66
    def __mul__(self, other):
67
        """Element-wise multiplication."""
68
    
69
    def __truediv__(self, other):
70
        """Element-wise division."""
71
    
72
    def __pow__(self, other):
73
        """Element-wise power."""
74

75
def to_device(queue, ary, allocator=None, async_=False):
76
    """
77
    Transfer numpy array to device.
78
    
79
    Parameters:
80
    - queue (CommandQueue): Command queue
81
    - ary (numpy.ndarray): Source array
82
    - allocator (Allocator, optional): Memory allocator
83
    - async_ (bool): Asynchronous transfer
84
    
85
    Returns:
86
    Array: GPU array with copied data
87
    """
88

89
def zeros(queue, shape, dtype=float, order="C", allocator=None):
90
    """
91
    Create zero-filled array on device.
92
    
93
    Parameters:
94
    - queue (CommandQueue): Command queue
95
    - shape (int | tuple[int, ...]): Array shape
96
    - dtype: Data type
97
    - order (str): Memory layout ("C" or "F")
98
    - allocator (Allocator, optional): Memory allocator
99
    
100
    Returns:
101
    Array: Zero-filled GPU array
102
    """
103

104
def zeros_like(ary):
105
    """
106
    Create zero array with same shape and type as existing array.
107
    
108
    Parameters:
109
    - ary (Array): Template array
110
    
111
    Returns:
112
    Array: Zero-filled array
113
    """
114

115
def empty_like(ary):
116
    """
117
    Create uninitialized array with same shape and type.
118
    
119
    Parameters:
120
    - ary (Array): Template array
121
    
122
    Returns:  
123
    Array: Uninitialized array
124
    """
125

126
def arange(queue, *args, **kwargs):
127
    """
128
    Create array with evenly spaced values.
129
    
130
    Parameters:
131
    - queue (CommandQueue): Command queue
132
    - start (number): Start value
133
    - stop (number): Stop value (exclusive)
134
    - step (number): Step size
135
    - dtype: Data type
136
    
137
    Returns:
138
    Array: Array with evenly spaced values
139
    """
140
```
141

142
### Array Operations and Reductions
143

144
Perform mathematical operations and reductions on GPU arrays.
145

146
```python { .api }
147
def sum(a, dtype=None, queue=None, slice=None):
148
    """
149
    Sum array elements.
150
    
151
    Parameters:
152
    - a (Array): Input array
153
    - dtype: Result data type
154
    - queue (CommandQueue, optional): Command queue
155
    - slice: Array slice to sum
156
    
157
    Returns:
158
    scalar | Array: Sum result
159
    """
160

161
def dot(a_gpu, b_gpu, dtype=None, queue=None):
162
    """
163
    Dot product of two arrays.
164
    
165
    Parameters:
166
    - a_gpu (Array): First array
167
    - b_gpu (Array): Second array  
168
    - dtype: Result data type
169
    - queue (CommandQueue, optional): Command queue
170
    
171
    Returns:
172
    Array: Dot product result
173
    """
174

175
def vdot(a_gpu, b_gpu, dtype=None, queue=None):
176
    """
177
    Vector dot product with complex conjugation.
178
    
179
    Parameters:
180
    - a_gpu (Array): First array (conjugated)
181
    - b_gpu (Array): Second array
182
    - dtype: Result data type
183
    - queue (CommandQueue, optional): Command queue
184
    
185
    Returns:
186
    scalar: Dot product result
187
    """
188

189
def subset_dot(subset, a, b, dtype_out=None, queue=None):
190
    """
191
    Dot product on array subset.
192
    
193
    Parameters:
194
    - subset (Array): Index subset  
195
    - a (Array): First array
196
    - b (Array): Second array
197
    - dtype_out: Output data type
198
    - queue (CommandQueue, optional): Command queue
199
    
200
    Returns:
201
    Array: Subset dot product
202
    """
203
```
204

205
### Array Manipulation
206

207
Reshape, transpose, and manipulate array structure.
208

209
```python { .api }
210
def transpose(a_gpu, axes=None):
211
    """
212
    Transpose array dimensions.
213
    
214
    Parameters:
215
    - a_gpu (Array): Input array
216
    - axes (tuple[int, ...], optional): Axis permutation
217
    
218
    Returns:
219
    Array: Transposed array
220
    """
221

222
def reshape(a_gpu, shape):
223
    """
224
    Reshape array to new dimensions.
225
    
226
    Parameters:
227
    - a_gpu (Array): Input array
228
    - shape (tuple[int, ...]): New shape
229
    
230
    Returns:
231
    Array: Reshaped array
232
    """
233

234
def as_strided(a_gpu, shape=None, strides=None):
235
    """
236
    Create strided view of array.
237
    
238
    Parameters:
239
    - a_gpu (Array): Input array
240
    - shape (tuple[int, ...], optional): New shape
241
    - strides (tuple[int, ...], optional): New strides
242
    
243
    Returns:
244
    Array: Strided array view
245
    """
246

247
def concatenate(arrays, axis=0, queue=None, allocator=None):
248
    """
249
    Concatenate arrays along axis.
250
    
251
    Parameters:
252
    - arrays (list[Array]): Arrays to concatenate
253
    - axis (int): Concatenation axis
254
    - queue (CommandQueue, optional): Command queue
255
    - allocator (Allocator, optional): Memory allocator
256
    
257
    Returns:
258
    Array: Concatenated array
259
    """
260

261
def stack(arrays, axis=0, queue=None, allocator=None):
262
    """
263
    Stack arrays along new axis.
264
    
265
    Parameters:
266
    - arrays (list[Array]): Arrays to stack
267
    - axis (int): New axis position
268
    - queue (CommandQueue, optional): Command queue
269
    - allocator (Allocator, optional): Memory allocator
270
    
271
    Returns:
272
    Array: Stacked array
273
    """
274

275
def hstack(arrays, queue=None, allocator=None):
276
    """
277
    Stack arrays horizontally (column-wise).
278
    
279
    Parameters:
280
    - arrays (list[Array]): Arrays to stack
281
    - queue (CommandQueue, optional): Command queue
282
    - allocator (Allocator, optional): Memory allocator
283
    
284
    Returns:
285
    Array: Horizontally stacked array
286
    """
287
```
288

289
### Indexing and Element Access
290

291
Advanced indexing, element selection, and data rearrangement.
292

293
```python { .api }
294
def take(a_gpu, indices, queue=None, out=None):
295
    """
296
    Take elements by indices.
297
    
298
    Parameters:
299
    - a_gpu (Array): Source array
300
    - indices (Array): Index array
301
    - queue (CommandQueue, optional): Command queue
302
    - out (Array, optional): Output array
303
    
304
    Returns:
305
    Array: Selected elements
306
    """
307

308
def multi_take(arrays, indices, queue=None, out=None):
309
    """
310
    Take elements from multiple arrays using same indices.
311
    
312
    Parameters:
313
    - arrays (list[Array]): Source arrays
314
    - indices (Array): Index array
315
    - queue (CommandQueue, optional): Command queue
316
    - out (list[Array], optional): Output arrays
317
    
318
    Returns:
319
    list[Array]: Selected elements from each array
320
    """
321

322
def multi_put(arrays, dest_indices, dest_shape, dest_dtype, queue=None, out=None):
323
    """
324
    Put elements into multiple destination arrays.
325
    
326
    Parameters:
327
    - arrays (list[Array]): Source arrays
328
    - dest_indices (Array): Destination indices
329
    - dest_shape (tuple): Destination shape
330
    - dest_dtype: Destination data type
331
    - queue (CommandQueue, optional): Command queue
332
    - out (list[Array], optional): Output arrays
333
    
334
    Returns:
335
    list[Array]: Destination arrays with put elements
336
    """
337

338
def multi_take_put(arrays, dest_indices, src_indices, dest_shape, 
339
                   src_offsets, dest_dtype, queue=None, out=None):
340
    """
341
    Combined take and put operation.
342
    
343
    Parameters:
344
    - arrays (list[Array]): Source arrays
345
    - dest_indices (Array): Destination indices
346
    - src_indices (Array): Source indices  
347
    - dest_shape (tuple): Destination shape
348
    - src_offsets (Array): Source offsets
349
    - dest_dtype: Destination data type
350
    - queue (CommandQueue, optional): Command queue
351
    - out (list[Array], optional): Output arrays
352
    
353
    Returns:
354
    list[Array]: Result arrays
355
    """
356
```
357

358
### Array Analysis and Computation
359

360
Compute differences, cumulative operations, and array statistics.
361

362
```python { .api }
363
def diff(a_gpu, queue=None, allocator=None):
364
    """
365
    Calculate differences between consecutive elements.
366
    
367
    Parameters:
368
    - a_gpu (Array): Input array
369
    - queue (CommandQueue, optional): Command queue
370
    - allocator (Allocator, optional): Memory allocator
371
    
372
    Returns:
373
    Array: Array of differences
374
    """
375

376
def cumsum(a_gpu, queue=None, allocator=None):
377
    """
378
    Cumulative sum along array.
379
    
380
    Parameters:
381
    - a_gpu (Array): Input array
382
    - queue (CommandQueue, optional): Command queue
383
    - allocator (Allocator, optional): Memory allocator
384
    
385
    Returns:
386
    Array: Cumulative sum array
387
    """
388
```
389

390
### Logical Operations
391

392
Element-wise logical operations and boolean array manipulation.
393

394
```python { .api }
395
def all(a_gpu, queue=None):
396
    """
397
    Test if all elements are true.
398
    
399
    Parameters:
400
    - a_gpu (Array): Input array
401
    - queue (CommandQueue, optional): Command queue
402
    
403
    Returns:
404
    bool: True if all elements are true
405
    """
406

407
def any(a_gpu, queue=None):
408
    """
409
    Test if any elements are true.
410
    
411
    Parameters:
412
    - a_gpu (Array): Input array
413
    - queue (CommandQueue, optional): Command queue
414
    
415
    Returns:
416
    bool: True if any elements are true
417
    """
418

419
def logical_and(a_gpu, b_gpu, queue=None):
420
    """
421
    Element-wise logical AND.
422
    
423
    Parameters:
424
    - a_gpu (Array): First array
425
    - b_gpu (Array): Second array
426
    - queue (CommandQueue, optional): Command queue
427
    
428
    Returns:
429
    Array: Logical AND result
430
    """
431

432
def logical_or(a_gpu, b_gpu, queue=None):
433
    """
434
    Element-wise logical OR.
435
    
436
    Parameters:
437
    - a_gpu (Array): First array
438
    - b_gpu (Array): Second array
439
    - queue (CommandQueue, optional): Command queue
440
    
441
    Returns:
442
    Array: Logical OR result
443
    """
444

445
def logical_not(a_gpu, queue=None):
446
    """
447
    Element-wise logical NOT.
448
    
449
    Parameters:
450
    - a_gpu (Array): Input array
451
    - queue (CommandQueue, optional): Command queue
452
    
453
    Returns:
454
    Array: Logical NOT result
455
    """
456
```
457

458
### Comparison and Selection
459

460
Element-wise comparisons and conditional selection.
461

462
```python { .api }
463
def maximum(a_gpu, b_gpu, queue=None):
464
    """
465
    Element-wise maximum of arrays.
466
    
467
    Parameters:
468
    - a_gpu (Array): First array
469
    - b_gpu (Array): Second array
470
    - queue (CommandQueue, optional): Command queue
471
    
472
    Returns:
473
    Array: Element-wise maximum
474
    """
475

476
def minimum(a_gpu, b_gpu, queue=None):
477
    """
478
    Element-wise minimum of arrays.
479
    
480
    Parameters:
481
    - a_gpu (Array): First array
482
    - b_gpu (Array): Second array
483
    - queue (CommandQueue, optional): Command queue
484
    
485
    Returns:
486
    Array: Element-wise minimum
487
    """
488

489
def if_positive(criterion, then_, else_, queue=None, out=None):
490
    """
491
    Conditional selection based on sign.
492
    
493
    Parameters:
494
    - criterion (Array): Condition array
495
    - then_ (Array): Values for positive elements
496
    - else_ (Array): Values for non-positive elements
497
    - queue (CommandQueue, optional): Command queue
498
    - out (Array, optional): Output array
499
    
500
    Returns:
501
    Array: Conditionally selected values
502
    """
503
```
504

505
## Usage Examples
506

507
### Basic Array Operations
508

509
```python
510
import pyopencl as cl
511
import pyopencl.array as cl_array
512
import numpy as np
513

514
# Setup
515
ctx = cl.create_some_context()
516
queue = cl.CommandQueue(ctx)
517

518
# Create arrays
519
a = cl_array.to_device(queue, np.random.randn(1000).astype(np.float32))
520
b = cl_array.to_device(queue, np.random.randn(1000).astype(np.float32))
521

522
# Element-wise operations
523
c = a + b
524
d = a * 2.0
525
e = cl_array.sum(a)
526

527
print(f"Sum: {e}")
528
print(f"First 5 elements of c: {c.get()[:5]}")
529
```
530

531
### Array Manipulation and Indexing
532

533
```python
534
import pyopencl as cl
535
import pyopencl.array as cl_array
536
import numpy as np
537

538
# Setup
539
ctx = cl.create_some_context()
540
queue = cl.CommandQueue(ctx)
541

542
# Create 2D array
543
data = np.random.randn(100, 50).astype(np.float32)
544
gpu_array = cl_array.to_device(queue, data)
545

546
# Transpose
547
transposed = cl_array.transpose(gpu_array)
548
print(f"Original shape: {gpu_array.shape}")
549
print(f"Transposed shape: {transposed.shape}")
550

551
# Indexing and slicing
552
subset = gpu_array[10:20, :]
553
print(f"Subset shape: {subset.shape}")
554

555
# Take elements by indices
556
indices = cl_array.arange(queue, 0, 100, 2, dtype=np.int32)  # Even indices
557
selected = cl_array.take(gpu_array.reshape(-1), indices)
558
print(f"Selected shape: {selected.shape}")
559
```
560

561
### Linear Algebra Operations
562

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

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

572
# Matrix multiplication using dot product
573
A = cl_array.to_device(queue, np.random.randn(100, 50).astype(np.float32))
574
B = cl_array.to_device(queue, np.random.randn(50, 80).astype(np.float32))
575

576
# Dot product (matrix multiplication)
577
C = cl_array.dot(A, B)
578
print(f"Matrix multiplication result shape: {C.shape}")
579

580
# Vector operations
581
x = cl_array.to_device(queue, np.random.randn(1000).astype(np.float32))
582
y = cl_array.to_device(queue, np.random.randn(1000).astype(np.float32))
583

584
# Dot product
585
dot_result = cl_array.vdot(x, y)
586
print(f"Vector dot product: {dot_result}")
587
```
588

589
### Array Reductions and Statistics
590

591
```python
592
import pyopencl as cl
593
import pyopencl.array as cl_array
594
import numpy as np
595

596
# Setup
597
ctx = cl.create_some_context()
598
queue = cl.CommandQueue(ctx)
599

600
# Create array
601
data = cl_array.to_device(queue, np.random.randn(10000).astype(np.float32))
602

603
# Reductions
604
total_sum = cl_array.sum(data)
605
all_positive = cl_array.all(data > 0)
606
any_negative = cl_array.any(data < 0)
607

608
print(f"Sum: {total_sum}")
609
print(f"All positive: {all_positive}")
610
print(f"Any negative: {any_negative}")
611

612
# Cumulative operations
613
cumulative = cl_array.cumsum(data)
614
print(f"Cumulative sum shape: {cumulative.shape}")
615
```