0
# Core OpenCL Objects and Management
1

2
Core OpenCL functionality for platform discovery, device selection, context creation, program compilation, and kernel execution. These components provide the foundation for all OpenCL operations and complete control over parallel execution.
3

4
## Capabilities
5

6
### Platform and Device Discovery
7

8
Discover available OpenCL platforms and devices, with support for interactive selection and automatic device filtering.
9

10
```python { .api }
11
def get_platforms():
12
    """
13
    Get list of available OpenCL platforms.
14
    
15
    Returns:
16
    list[Platform]: Available platforms
17
    
18
    Raises:
19
    RuntimeError: If no platforms found or ICD loader issues
20
    """
21

22
def choose_devices(interactive=None, answers=None):
23
    """
24
    Choose OpenCL devices interactively or programmatically.
25
    
26
    Parameters:
27
    - interactive (bool, optional): Enable interactive selection
28
    - answers (list[str], optional): Pre-provided answers for selection
29
    
30
    Returns:
31
    list[Device]: Selected devices
32
    """
33

34
class Platform:
35
    """
36
    Represents an OpenCL platform (driver implementation).
37
    
38
    Attributes:
39
    - name (str): Platform name
40
    - vendor (str): Platform vendor  
41
    - version (str): OpenCL version supported
42
    """
43
    
44
    def get_devices(self, device_type=None):
45
        """Get devices available on this platform."""
46

47
class Device:
48
    """
49
    Represents an OpenCL compute device.
50
    
51
    Attributes:
52
    - name (str): Device name
53
    - type (device_type): Device type (GPU, CPU, etc.)
54
    - vendor (str): Device vendor
55
    - max_compute_units (int): Number of compute units
56
    - max_work_group_size (int): Maximum work group size
57
    - local_mem_size (int): Local memory size in bytes
58
    - global_mem_size (int): Global memory size in bytes
59
    """
60
    
61
    @property
62
    def platform(self):
63
        """Platform this device belongs to."""
64
```
65

66
### Context and Command Queue Management
67

68
Create execution contexts and command queues for managing parallel operations and device communication.
69

70
```python { .api }
71
def create_some_context(interactive=None, answers=None):
72
    """
73
    Create an OpenCL context interactively or programmatically.
74
    
75
    Parameters:
76
    - interactive (bool, optional): Enable interactive device selection
77
    - answers (list[str], optional): Pre-provided device selection answers
78
    
79
    Returns:
80
    Context: Created OpenCL context
81
    """
82

83
class Context:
84
    """
85
    OpenCL execution context managing devices and memory objects.
86
    
87
    Attributes:
88
    - devices (list[Device]): Devices in this context
89
    """
90
    
91
    def __init__(self, devices=None, properties=None, dev_type=None):
92
        """
93
        Create context from devices or device type.
94
        
95
        Parameters:
96
        - devices (list[Device], optional): Specific devices to use
97
        - properties (list, optional): Context properties  
98
        - dev_type (device_type, optional): Device type filter
99
        """
100

101
class CommandQueue:
102
    """
103
    Command queue for scheduling operations on a device.
104
    
105
    Attributes:
106
    - context (Context): Associated context
107
    - device (Device): Target device
108
    """
109
    
110
    def __init__(self, context, device=None, properties=None):
111
        """
112
        Create command queue for device operations.
113
        
114
        Parameters:
115
        - context (Context): OpenCL context
116
        - device (Device, optional): Target device (uses first device if None)
117
        - properties (command_queue_properties, optional): Queue properties
118
        """
119
    
120
    def finish(self):
121
        """Wait for all enqueued commands to complete."""
122
    
123
    def flush(self):
124
        """Submit all enqueued commands to device."""
125
```
126

127
### Program Compilation and Kernel Management
128

129
Compile OpenCL programs from source code with automatic caching and create executable kernels.
130

131
```python { .api }
132
class Program:
133
    """
134
    Compiled OpenCL program with automatic caching support.
135
    """
136
    
137
    def __init__(self, context, source):
138
        """
139
        Create program from OpenCL source code.
140
        
141
        Parameters:
142
        - context (Context): OpenCL context
143
        - source (str): OpenCL source code
144
        """
145
    
146
    def build(self, options=None, devices=None, cache_dir=None):
147
        """
148
        Build program for devices.
149
        
150
        Parameters:
151
        - options (str | list[str], optional): Build options
152
        - devices (list[Device], optional): Target devices
153
        - cache_dir (str, optional): Cache directory for binaries
154
        
155
        Returns:
156
        Program: Self for method chaining
157
        """
158
    
159
    def compile(self, options=None, devices=None, headers=None):
160
        """Compile program without linking."""
161
    
162
    def get_info(self, param):
163
        """Get program information."""
164
    
165
    def get_build_info(self, device, param):
166
        """Get build information for device."""
167
    
168
    def all_kernels(self):
169
        """Get all kernels in program."""
170
    
171
    def __getattr__(self, name):
172
        """Access kernel by name (e.g., prg.my_kernel)."""
173

174
def create_program_with_built_in_kernels(context, devices, kernel_names):
175
    """
176
    Create program with built-in kernels.
177
    
178
    Parameters:
179
    - context (Context): OpenCL context
180
    - devices (list[Device]): Target devices
181
    - kernel_names (str | list[str]): Built-in kernel names
182
    
183
    Returns:
184
    Program: Program with built-in kernels
185
    """
186

187
def link_program(context, programs, options=None, devices=None):
188
    """
189
    Link compiled programs into executable program.
190
    
191
    Parameters:
192
    - context (Context): OpenCL context
193
    - programs (list[Program]): Compiled programs to link
194
    - options (str | list[str], optional): Link options
195
    - devices (list[Device], optional): Target devices
196
    
197
    Returns:
198
    Program: Linked executable program
199
    """
200

201
class Kernel:
202
    """
203
    Executable OpenCL kernel function.
204
    
205
    Attributes:
206
    - function_name (str): Kernel function name
207
    - num_args (int): Number of kernel arguments
208
    - context (Context): Associated context
209
    """
210
    
211
    def __init__(self, program, name):
212
        """
213
        Create kernel from program.
214
        
215
        Parameters:
216
        - program (Program): Compiled program
217
        - name (str): Kernel function name
218
        """
219
    
220
    def get_info(self, param):
221
        """Get kernel information."""
222
    
223
    def get_work_group_info(self, param, device):
224
        """Get work group information for device."""
225
    
226
    def set_arg(self, index, arg):
227
        """Set kernel argument by index."""
228
    
229
    def set_args(self, *args):
230
        """Set all kernel arguments."""
231
    
232
    def __call__(self, queue, global_size, local_size, *args, **kwargs):
233
        """Execute kernel with arguments."""
234
```
235

236
### Kernel Execution
237

238
Execute kernels on devices with support for ND-range execution and event synchronization.
239

240
```python { .api }
241
def enqueue_nd_range_kernel(queue, kernel, global_size, local_size=None, 
242
                           global_offset=None, wait_for=None, g_times_l=False):
243
    """
244
    Execute kernel over ND-range of work items.
245
    
246
    Parameters:
247
    - queue (CommandQueue): Command queue
248
    - kernel (Kernel): Kernel to execute
249
    - global_size (tuple[int, ...]): Global work size
250
    - local_size (tuple[int, ...], optional): Local work group size
251
    - global_offset (tuple[int, ...], optional): Global work offset
252
    - wait_for (list[Event], optional): Events to wait for
253
    - g_times_l (bool): Whether global_size is multiple of local_size
254
    
255
    Returns:
256
    Event: Kernel execution event
257
    """
258
```
259

260
### Event Management and Synchronization
261

262
Manage asynchronous operations with events for synchronization and profiling.
263

264
```python { .api }
265
class Event:
266
    """
267
    Represents an OpenCL event for asynchronous operations.
268
    
269
    Attributes:
270
    - command_execution_status (int): Execution status
271
    - command_type (int): Command type that created event
272
    """
273
    
274
    def wait(self):
275
        """Wait for event completion."""
276
    
277
    def get_info(self, param):
278
        """Get event information."""
279
    
280
    def get_profiling_info(self, param):
281
        """Get profiling information."""
282

283
class NannyEvent(Event):
284
    """Event with automatic host memory management."""
285

286
class UserEvent(Event):
287
    """User-created event for custom synchronization."""
288
    
289
    def __init__(self, context):
290
        """Create user event."""
291
    
292
    def set_status(self, status):
293
        """Set event status."""
294

295
def wait_for_events(events):
296
    """
297
    Wait for multiple events to complete.
298
    
299
    Parameters:
300
    - events (list[Event]): Events to wait for
301
    """
302
```
303

304
### Command Queue Operations
305

306
Insert synchronization primitives into command queues.
307

308
```python { .api }
309
def enqueue_marker(queue, wait_for=None):
310
    """
311
    Insert marker into command queue.
312
    
313
    Parameters:
314
    - queue (CommandQueue): Command queue
315
    - wait_for (list[Event], optional): Events to wait for
316
    
317
    Returns:
318
    Event: Marker event
319
    """
320

321
def enqueue_barrier(queue, wait_for=None):
322
    """
323
    Insert barrier into command queue.
324
    
325
    Parameters:
326
    - queue (CommandQueue): Command queue  
327
    - wait_for (list[Event], optional): Events to wait for
328
    
329
    Returns:
330
    Event: Barrier event
331
    """
332
```
333

334
### Debugging Support
335

336
Enable debugging and optimization for OpenCL development.
337

338
```python { .api }
339
def enable_debugging(platform_or_context):
340
    """
341
    Enable debugging for OpenCL platform or context.
342
    
343
    Parameters:
344
    - platform_or_context (Platform | Context): Target for debugging
345
    """
346
```
347

348
## Usage Examples
349

350
### Basic Context and Queue Setup
351

352
```python
353
import pyopencl as cl
354

355
# Interactive context creation
356
ctx = cl.create_some_context()
357
queue = cl.CommandQueue(ctx)
358

359
# Alternative: specific device selection
360
platforms = cl.get_platforms()
361
devices = platforms[0].get_devices()
362
ctx = cl.Context([devices[0]])
363
queue = cl.CommandQueue(ctx)
364
```
365

366
### Program Compilation and Kernel Execution
367

368
```python
369
import pyopencl as cl
370
import numpy as np
371

372
# Create context and queue
373
ctx = cl.create_some_context()
374
queue = cl.CommandQueue(ctx)
375

376
# OpenCL kernel source
377
kernel_source = """
378
__kernel void vector_add(__global const float* a,
379
                        __global const float* b,
380
                        __global float* result) {
381
    int gid = get_global_id(0);
382
    result[gid] = a[gid] + b[gid];
383
}
384
"""
385

386
# Compile program
387
program = cl.Program(ctx, kernel_source).build()
388

389
# Create kernel
390
kernel = program.vector_add
391

392
# Create buffers and execute
393
a = np.random.randn(1000).astype(np.float32)
394
b = np.random.randn(1000).astype(np.float32)
395
result = np.empty_like(a)
396

397
a_buf = cl.Buffer(ctx, cl.mem_flags.READ_ONLY | cl.mem_flags.COPY_HOST_PTR, hostbuf=a)
398
b_buf = cl.Buffer(ctx, cl.mem_flags.READ_ONLY | cl.mem_flags.COPY_HOST_PTR, hostbuf=b)
399
result_buf = cl.Buffer(ctx, cl.mem_flags.WRITE_ONLY, result.nbytes)
400

401
# Execute kernel
402
event = kernel(queue, a.shape, None, a_buf, b_buf, result_buf)
403
cl.enqueue_copy(queue, result, result_buf, wait_for=[event])
404

405
print(f"Result: {result[:5]}")
406
```