# Welcome to PyOpenCL’s documentation!

PyOpenCL gives you easy, Pythonic access to the OpenCL parallel computation API. What makes PyOpenCL special?

- Object cleanup tied to lifetime of objects. This idiom, often called RAII in C++, makes it much easier to write correct, leak- and crash-free code.

- Completeness. PyOpenCL puts the full power of OpenCL’s API at your disposal, if you wish. Every obscure `get_info()` query and all CL calls are accessible.

- Automatic Error Checking. All errors are automatically translated into Python exceptions.

- Speed. PyOpenCL’s base layer is written in C++, so all the niceties above are virtually free.

- Helpful Documentation. You’re looking at it. ;)

- Liberal license. PyOpenCL is open-source under the MIT license and free for commercial, academic, and private use.

Here’s an example, to give you an impression:

    #!/usr/bin/python3

    import numpy as np
    import pyopencl as cl

    a_np = np.random.rand(50000).astype(np.float32)
    b_np = np.random.rand(50000).astype(np.float32)

    ctx = cl.create_some_context()
    queue = cl.CommandQueue(ctx)

    mf = cl.mem_flags
    a_g = cl.Buffer(ctx, mf.READ_ONLY | mf.COPY_HOST_PTR, hostbuf=a_np)
    b_g = cl.Buffer(ctx, mf.READ_ONLY | mf.COPY_HOST_PTR, hostbuf=b_np)

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

    res_g = cl.Buffer(ctx, mf.WRITE_ONLY, a_np.nbytes)
    knl = prg.sum  # Use this Kernel object for repeated calls
    knl(queue, a_np.shape, None, a_g, b_g, res_g)

    res_np = np.empty_like(a_np)
    cl.enqueue_copy(queue, res_np, res_g)

    # Check on CPU with Numpy:
    print(res_np - (a_np + b_np))
    print(np.linalg.norm(res_np - (a_np + b_np)))
    assert np.allclose(res_np, a_np + b_np)

(You can find this example as `examples/demo.py` in the PyOpenCL source distribution.)

# Tutorials

- Gaston Hillar’s two-part article series in Dr. Dobb’s Journal provides a friendly introduction to PyOpenCL.

- Simon McIntosh-Smith and Tom Deakin’s course Hands-on OpenCL contains both lecture slides and exercises (with solutions) (The course covers PyOpenCL as well as OpenCL’s C and C++ APIs.)

- PyOpenCL course at PASI: Parts 1 2 3 4 (YouTube, 2011)

- PyOpenCL course at DTU GPULab and Simula (2011): Lecture 1 Lecture 2 Problem set 1 Problem set 2

- Ian Johnson’s PyOpenCL tutorial.

# Software that works with or enhances PyOpenCL

- Jon Roose’s pyclblas (code) makes BLAS in the form of clBLAS available from within `pyopencl` code.

  Two earlier wrappers continue to be available: one by Eric Hunsberger and one by Lars Ericson.

- Cedric Nugteren provides a wrapper for the CLBlast OpenCL BLAS library: PyCLBlast.

- Gregor Thalhammer’s gpyfft provides a Python wrapper for the OpenCL FFT library clFFT from AMD.

- Bogdan Opanchuk’s reikna offers a variety of GPU-based algorithms (FFT, random number generation, matrix multiplication) designed to work with `pyopencl.array.Array` objects.

- Troels Henriksen, Ken Friis Larsen, and Cosmin Oancea’s Futhark programming language offers a nice way to code nested-parallel programs with reductions and scans on data in `pyopencl.array.Array` instances.

- Robbert Harms and Alard Roebroeck’s MOT offers a variety of GPU-enabled non-linear optimization algorithms and MCMC sampling routines for parallel optimization and sampling of multiple problems.

- Vincent Favre-Nicolin’s pyvkfft makes vkfft accessible from PyOpenCL.

If you know of a piece of software you feel that should be on this list, please let me know, or, even better, send a patch!

# Contents

- OpenCL Runtime: Basics
  - Version Queries
  - Error Reporting
- OpenCL Runtime: Constants
  - `addressing_mode`
  - `channel_order`
  - `channel_type`
  - `command_execution_status`
  - `command_queue_info`
  - `command_queue_properties`
  - `command_type`
  - `context_info`
  - `context_properties`
  - `device_affinity_domain`
  - `device_atomic_capabilities`
  - `device_device_enqueue_capabilities`
  - `device_exec_capabilities`
  - `device_fp_config`
  - `device_info`
  - `device_local_mem_type`
  - `device_mem_cache_type`
  - `device_partition_property`
  - `device_svm_capabilities`
  - `device_topology_type_amd`
  - `device_type`
  - `event_info`
  - `filter_mode`
  - `gl_context_info`
  - `gl_object_type`
  - `gl_texture_info`
  - `image_info`
  - `kernel_arg_access_qualifier`
  - `kernel_arg_address_qualifier`
  - `kernel_arg_info`
  - `kernel_arg_type_qualifier`
  - `kernel_info`
  - `kernel_sub_group_info`
  - `kernel_work_group_info`
  - `khronos_vendor_id`
  - `map_flags`
  - `mem_flags`
  - `mem_info`
  - `mem_migration_flags`
  - `mem_object_type`
  - `pipe_info`
  - `pipe_properties`
  - `platform_info`
  - `profiling_info`
  - `program_binary_type`
  - `program_build_info`
  - `program_info`
  - `program_kind`
  - `queue_properties`
  - `sampler_info`
  - `sampler_properties`
  - `status_code`
  - `svm_mem_flags`
  - `version_bits`
  - `NameVersion`
  - `DeviceTopologyAmd`
- OpenCL Runtime: Platforms, Devices and Contexts
  - Platform
  - Device
  - Context
- OpenCL Runtime: Command Queues and Events
  - Command Queue
  - Event
  - Event Subclasses
  - Synchronization Functions
- OpenCL Runtime: Memory
  - `MemoryObject`
  - Memory Migration
  - Buffer
  - Shared Virtual Memory (SVM)
  - Image
  - Transfers
  - Mapping Memory into Host Address Space
  - Samplers
  - Pipes
  - Type aliases
- OpenCL Runtime: Programs and Kernels
  - Program
  - Kernel
- OpenCL Runtime: OpenGL Interoperability
  - `have_gl()`
  - `get_gl_sharing_context_properties()`
  - `get_apple_cgl_share_group()`
  - `GLBuffer`
  - `GLRenderBuffer`
  - `GLTexture`
  - `enqueue_acquire_gl_objects()`
  - `enqueue_release_gl_objects()`
  - `get_gl_context_info_khr()`
- Built-in Utilities
  - Memory Pools
  - CL-Object-dependent Caching
  - Testing
  - Argument Types
  - Device Characterization
  - Type aliases
- Multi-dimensional arrays
  - Data Types
  - The `Array` Class
  - Elementwise Functions on `Array` Instances
  - Generating Arrays of Random Numbers
- OpenCL Type Mapping
  - Scalar Types
  - Vector Types
- Parallel Algorithms
  - Element-wise expression evaluation (“map”)
  - Sums and counts (“reduce”)
  - Prefix Sums (“scan”)
  - Predicated copies (“partition”, “unique”, …)
  - Sorting (radix sort)
  - Building many variable-size lists
  - Bitonic Sort
- How-tos
  - How to use struct types with PyOpenCL
- Installation
  - Installing from Conda Forge
  - Installing from PyPI wheels
  - Installing via Christoph Gohlke’s binary wheels (Windows)
  - Installing from source
- Tips
  - Syntax highlighting
  - IPython integration
- Guidelines
  - API Stability
  - Relation with OpenCL’s C Bindings
  - Interoperability with other OpenCL software
- User-visible Changes
  - Unreleased
  - Version 2022.2
  - Version 2020.2
  - Version 2018.2
  - Version 2018.1
  - Version 2017.2
  - Version 2017.1
  - Version 2016.2
  - Version 2016.1
  - Version 2015.2.4
  - Version 2015.2.3
  - Version 2015.2.2
  - Version 2015.2.1
  - Version 2015.2
  - Version 2015.1
  - Version 2014.1
  - Version 2013.2
  - Version 2013.1
  - Version 2012.1
  - Version 2011.2
  - Version 2011.1.2
  - Version 2011.1.1
  - Version 2011.1
  - Version 0.92
  - Version 0.91.5
  - Version 0.91.4
  - Version 0.91.3
  - Version 0.91.2
  - Version 0.91.1
  - Version 0.91
  - Version 0.90.4
  - Version 0.90.3
  - Version 0.90.2
  - Version 0.90.1
  - Version 0.90
- License
- Frequently Asked Questions
- Citing PyOpenCL
- Acknowledgments
  - Contributors
  - Funding
- Documentation Cross-References
  - Numpy
  - OpenCL Specification
  - Internal Types
- 🚀 Github
- 💾 Download Releases

Note that this guide does not explain OpenCL programming and technology. Please refer to the official Khronos OpenCL documentation for that.

PyOpenCL also has its own web site, where you can find updates, new versions, documentation, and support.

# Indices and tables

- Index

- Module Index

- Search Page