Intel oneAPI OpenCL Runtime

Common errors

• ModuleNotFoundError: No module named 'intel_opencl_rt'

  cause The `intel-opencl-rt` package is a runtime provider, not a Python module designed for direct import. You should not attempt to `import intel_opencl_rt`.
  fix Remove the `import intel_opencl_rt` statement. Instead, use a Python OpenCL binding library (e.g., `pyopencl`) which will dynamically link to the runtime provided by this package.

• pyopencl.LogicError: clGetPlatformIDs failed (errcode=-1)

  cause This error typically indicates that no OpenCL platforms or devices could be found by `pyopencl`. This can happen if the `intel-opencl-rt` runtime is not correctly installed, drivers are missing, or no compatible Intel hardware is present.
  fix Verify that `intel-opencl-rt` is installed (`pip show intel-opencl-rt`). Ensure your system has an Intel CPU with integrated graphics or an Intel GPU. Install or update necessary system-level drivers from Intel. You may also check the output of `clinfo` (if available on your system) to see detected OpenCL platforms.

Warnings

• gotcha This package is not a Python library for direct import. It installs a system runtime (shared libraries) that other OpenCL Python bindings (like `pyopencl`) discover and use. You will not `import intel_opencl_rt` in your Python code.
  Fix: Instead of trying to import, install the package and then use a Python OpenCL binding library like `pyopencl` or `pylibopencl`. These libraries will automatically detect the installed OpenCL runtime.
• gotcha The `intel-opencl-rt` package provides the *runtime*, but requires compatible Intel hardware (e.g., an Intel integrated GPU or discrete GPU) and potentially system-level drivers to function correctly and provide hardware acceleration.
  Fix: Ensure your system has a supported Intel CPU with integrated graphics or an Intel discrete GPU. Verify that necessary system-level drivers are installed and up-to-date, typically via Intel's driver support assistant or by installing the full oneAPI Base Toolkit.
• gotcha If you have already installed the Intel oneAPI Base Toolkit, installing `intel-opencl-rt` via pip might be redundant or could potentially lead to version conflicts if the pip package's runtime files conflict with the system-wide oneAPI installation.
  Fix: Prefer installing the oneAPI Base Toolkit for a comprehensive and managed installation. Only use `pip install intel-opencl-rt` if you specifically need just the OpenCL runtime in a Python environment and do not have a full oneAPI installation, or if you encounter issues with system-wide installations.

Install

• pip install intel-opencl-rt Install the runtime

Imports

• Intel OpenCL Runtime
  wrong:

  from intel_opencl_rt import OpenCLDevice

  correct:

  This package is a runtime, not a Python module to be imported directly.

  The `intel-opencl-rt` package provides shared libraries (.so/.dll) that are discovered by other OpenCL binding libraries (like `pyopencl`) at runtime. It does not expose Python symbols for direct import.

Quickstart

This quickstart demonstrates how to use `pyopencl` to perform a simple vector addition, leveraging the OpenCL runtime provided by `intel-opencl-rt`. You will first need to install `pyopencl` (e.g., `pip install pyopencl`). The `intel-opencl-rt` package installs the backend necessary for `pyopencl` to find and utilize Intel OpenCL devices.

import pyopencl as cl
import numpy

# This code assumes intel-opencl-rt has installed the necessary drivers/runtime.
# pyopencl will automatically find and use the available OpenCL platform.

try:
    platform = cl.get_platforms()[0] # Get the first OpenCL platform
    devices = platform.get_devices() # Get devices for the platform
    
    # Filter for Intel devices if desired, or use the first available.
    intel_devices = [d for d in devices if 'Intel' in d.vendor]
    device_to_use = intel_devices[0] if intel_devices else devices[0]

    ctx = cl.Context([device_to_use])
    queue = cl.CommandQueue(ctx)

    a = numpy.random.rand(50000).astype(numpy.float32)
    b = numpy.random.rand(50000).astype(numpy.float32)

    mf = cl.mem_flags
    a_buf = cl.Buffer(ctx, mf.READ_ONLY | mf.COPY_HOST_PTR, hostbuf=a)
    b_buf = cl.Buffer(ctx, mf.READ_ONLY | mf.COPY_HOST_PTR, hostbuf=b)
    dest_buf = cl.Buffer(ctx, mf.WRITE_ONLY, a.nbytes)

    prg = cl.Program(ctx, "__kernel void sum(__global const float *a, __global const float *b, __global float *c) { int gid = get_global_id(0); c[gid] = a[gid] + b[gid]; }").build()

    prg.sum(queue, a.shape, None, a_buf, b_buf, dest_buf)
    c = numpy.empty_like(a)
    cl.enqueue_copy(queue, c, dest_buf).wait()

    print(f"OpenCL platform: {platform.name}")
    print(f"OpenCL device: {device_to_use.name}")
    print(f"Result calculated via OpenCL: {c[:5]}...")
    print(f"Expected result: {(a+b)[:5]}...")
    assert numpy.allclose(c, a + b)
    print("OpenCL computation successful!")

except cl.LogicError as e:
    print(f"Failed to initialize OpenCL: {e}")
    print("Please ensure OpenCL drivers are installed and a compatible device is present.")
except IndexError:
    print("No OpenCL platforms or devices found. Ensure Intel OpenCL runtime is correctly installed and compatible hardware is available.")