OpenCL Runtime: Memory¶

class pyopencl.MemoryObjectHolder¶

.. attribute:: info

Lower case versions of the mem_info constants may be used as attributes on instances of this class to directly query info attributes.

get_info(param)¶: See mem_info for values of param.

int_ptr¶

Instances of this class are hashable, and two instances of this class may be compared using “==” and “!=”. (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

class pyopencl.MemoryObject¶

Inherits from :class:`MemoryObjectHolder`.

hostbuf¶

release()¶

get_host_array(shape, dtype, order='C')¶: Return the memory object’s associated host memory area as a numpy.ndarray of the given shape, dtype and order.

int_ptr¶: Return an integer corresponding to the pointer value of the underlying cl_mem. Use from_int_ptr() to turn back into a Python object.

Added in version 2013.2.

from_int_ptr(int_ptr_value: int, retain: bool = True) → object¶: (static method) Return a new Python object referencing the C-level cl_mem object at the location pointed to by int_ptr_value. The relevant clRetain* function will be called if retain is True.If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to pyopencl.

Added in version 2013.2.

Changed in version 2016.1: retain added.

Memory Migration¶

pyopencl.enqueue_migrate_mem_objects(queue, mem_objects, flags=0, wait_for=None)¶

Parameters:: flags – from mem_migration_flags

Added in version 2011.2.

Only available with CL 1.2.

Buffer¶

class pyopencl.Buffer(context, flags, size=0, hostbuf=None)¶

Create a Buffer. See mem_flags for values of flags. If hostbuf is specified, size defaults to the size of the specified buffer if it is passed as zero.

Buffer inherits from MemoryObject.

Note

Python also defines a type of buffer object, and PyOpenCL interacts with those, too, as the host-side target of enqueue_copy(). Make sure to always be clear on whether a Buffer or a Python buffer object is needed.

Note that actual memory allocation in OpenCL may be deferred. Buffers are attached to a Context and are only moved to a device once the buffer is used on that device. That is also the point when out-of-memory errors will occur. If you’d like to be sure that there’s enough memory for your allocation, either use enqueue_migrate_mem_objects() (if available) or simply perform a small transfer to the buffer. See also pyopencl.tools.ImmediateAllocator.

get_sub_region(origin, size, flags=0)¶: Only available in OpenCL 1.1 and newer.

__getitem__(slc)¶: slc is a slice object indicating from which byte index range a sub-buffer is to be created. The flags argument of get_sub_region() is set to the same flags with which self was created.

pyopencl.enqueue_fill_buffer(queue, mem, pattern, offset, size, wait_for=None)[source]¶

Parameters:

mem – the on device Buffer
pattern – a buffer object (likely a numpy.ndarray, eg. np.uint32(0)). The memory associated with pattern can be reused or freed once the function completes.
size – The size in bytes of the region to be filled. Must be a multiple of the size of the pattern.
offset – The location in bytes of the region being filled in mem. Must be a multiple of the size of the pattern.

Fills a buffer with the provided pattern

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution.

Only available with CL 1.2.

Added in version 2011.2.

Shared Virtual Memory (SVM)¶

Shared virtual memory allows the host and the compute device to share address space, so that pointers on the host and on the device may have the same meaning. In addition, it allows the same memory to be accessed by both the host and the device. Coarse-grain SVM requires that buffers be mapped before being accessed on the host, fine-grain SVM does away with that requirement.

Warning

Compared to Buffers, SVM brings with it a new concern: the synchronization of memory deallocation. Unlike other objects in OpenCL, SVM is represented by a plain (C-language) pointer and thus has no ability for reference counting.

As a result, it is perfectly legal to allocate a Buffer, enqueue an operation on it, and release the buffer, without worrying about whether the operation has completed. The OpenCL implementation will keep the buffer alive until the operation has completed. This is not the case with SVM: Unless otherwise specified, memory deallocation is performed immediately when requested, and so SVM will be deallocated whenever the Python garbage collector sees fit, even if the operation has not completed, immediately leading to undefined behavior (i.e., typically, memory corruption and, before too long, a crash).

Version 2022.2 of PyOpenCL offers substantially improved tools for dealing with this. In particular, all means for allocating SVM allow specifying a CommandQueue, so that deallocation is enqueued and performed after previously-enqueued operations have completed.

SVM requires OpenCL 2.0.

Opaque and “Wrapped-`numpy`” Styles of Referencing SVM¶

When trying to pass SVM pointers to functionality in pyopencl, two styles are supported:

First, the opaque style. This style most closely resembles Buffer-based allocation available in OpenCL 1.x. SVM pointers are held in opaque “handle” objects such as SVMAllocation.
Second, the wrapped-numpy style. In this case, a numpy.ndarray (or another object implementing the Python buffer protocol) serves as the reference to an area of SVM. This style permits using memory areas with pyopencl’s SVM interfaces even if they were allocated outside of pyopencl.

Since passing a numpy.ndarray (or another type of object obeying the buffer interface) already has existing semantics in most settings in pyopencl (such as when passing arguments to a kernel or calling enqueue_copy()), there exists a wrapper object, SVM, that may be “wrapped around” these objects to mark them as SVM.

The commonality between the two styles is that both ultimately implement the SVMPointer interface, which pyopencl uses to obtain the actual SVM pointer.

Note that it is easily possible to obtain a numpy.ndarray view of SVM areas held in the opaque style, see SVMPointer.buf, permitting transitions from opaque to wrapped-numpy style. The opposite transition (from wrapped-numpy to opaque) is not necessarily straightforward, as it would require “fishing” the opaque SVM handle out of a chain of numpy.ndarray.base attributes (or similar, depending on the actual object serving as the main SVM reference).

See Helper functions for numpy-based SVM allocation for helper functions that ease setting up the wrapped-numpy structure.

Wrapped-numpy SVM tends to be a good fit for fine-grain SVM because of the ease of direct host-side access, but the creation of the nested structure that makes this possible is associated with a certain amount of cost.

By comparison, opaque SVM access tends to be a good fit for coarse-grain SVM, because direct host access is not possible without mapping the array anyway, and it has lower setup cost. It is of course entirely possible to use opaque SVM access with fine-grain SVM.

Changed in version 2022.2: This version adds the opaque style of SVM access.

Using SVM with Arrays¶

While all types of SVM can be used as the memory backing pyopencl.array.Array objects, ensuring that new arrays returned by array operations (e.g. arithmetic) also use SVM is easiest to accomplish by passing an SVMAllocator (or SVMPool) as the allocator parameter in functions returning new arrays.

SVM Pointers, Allocations, and Maps¶

class pyopencl.SVMPointer¶

A base class for things that can be passed to functions that allow an SVM pointer, e.g. kernel enqueues and memory copies.

Objects of this type cannot currently be directly created or implemented in Python. To obtain objects implementing this type, consider its subtypes SVMAllocation and SVM.

property svm_ptr¶: Gives the SVM pointer as an int.

property size¶

An int denoting the size in bytes, or None, if the size of the SVM pointed to is not known.

Most objects of this type (e.g. instances of SVMAllocation and SVM know their size, so that, for example enqueue_copy will automatically copy an entire SVMAllocation when a size is not explicitly specified.

map(queue: _cl.CommandQueue, *, flags: int, is_blocking: bool = True, wait_for: WaitList = None, size: int | None = None) → SVMMap[NDArray[Any]][source]¶

Parameters:

is_blocking – If False, subsequent code must wait on SVMMap.event in the returned object before accessing the mapped memory.
flags – a combination of pyopencl.map_flags.
size – The size of the map in bytes. If not provided, defaults to size.

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution.

map_ro(queue: _cl.CommandQueue, *, is_blocking: bool = True, wait_for: WaitList = None, size: int | None = None) → SVMMap[NDArray[Any]][source]¶: Like map(), but with flags set for a read-only map.

map_rw(queue: _cl.CommandQueue, *, is_blocking: bool = True, wait_for: WaitList = None, size: int | None = None) → SVMMap[NDArray[Any]][source]¶: Like map(), but with flags set for a read-only map.

as_buffer(ctx: Context, *, flags: int | None = None, size: int | None = None) → Buffer[source]¶

Parameters:

ctx – a Context
flags – a combination of pyopencl.map_flags, defaults to read-write.
size – The size of the map in bytes. If not provided, defaults to size.

Returns:

a Buffer corresponding to self.

The memory referred to by this object must not be freed before the returned Buffer is released.

property buf¶

An opaque object implementing the Python buffer protocol. It exposes the pointed-to memory as a one-dimensional buffer of bytes, with the size matching size.

No guarantee is provided that two references to this attribute result in the same object.

class pyopencl.SVMAllocation(*args, **kwargs)¶

Is a SVMPointer.

Added in version 2016.2.

__init__(self, context: pyopencl._cl.Context, size: int, alignment: int, flags: int, queue: pyopencl._cl.CommandQueue | None = None) → None¶

Parameters:

flags – See svm_mem_flags.
queue –
If not specified, the allocation will be freed eagerly, irrespective of whether pending/enqueued operations are still using this memory.

If specified, deallocation of the memory will be enqueued with the given queue, and will only be performed after previously-enqueue operations in the queue have completed.

It is an error to specify an out-of-order queue.

Warning

Not specifying a queue will typically lead to undesired behavior, including crashes and memory corruption. See the warning in Shared Virtual Memory (SVM).

enqueue_release(self, queue: pyopencl._cl.CommandQueue | None = None, wait_for: object | None = None) → pyopencl._cl.Event¶

Returns:: a pyopencl.Event

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution.

Enqueue the release of this allocation into queue. If queue is not specified, enqueue the deallocation into the queue provided at allocation time or via bind_to_queue.

bind_to_queue(self, queue: pyopencl._cl.CommandQueue) → None¶: Change the queue used for implicit enqueue of deallocation to queue. Sufficient synchronization is ensured by enqueuing a marker into the old queue and waiting on this marker in the new queue.

unbind_from_queue(self) → None¶: Configure the allocation to no longer implicitly enqueue memory allocation. If such a queue was previously provided, finish() is automatically called on it.

class pyopencl.SVM(*args, **kwargs)¶

Tags an object exhibiting the Python buffer interface (such as a numpy.ndarray) as referring to shared virtual memory.

Is a SVMPointer, hence objects of this type may be passed to kernel calls and enqueue_copy(), and all methods declared there are also available there. Note that map() differs slightly from SVMPointer.map().

Depending on the features of the OpenCL implementation, the following types of objects may be passed to/wrapped in this type:

fine-grain shared memory as returned by (e.g.) fsvm_empty(), if the implementation supports fine-grained shared virtual memory. This memory may directly be passed to a kernel:
```
ary = cl.fsvm_empty(ctx, 1000, np.float32)
assert isinstance(ary, np.ndarray)

prg.twice(queue, ary.shape, None, cl.SVM(ary))
queue.finish() # synchronize
print(ary) # access from host
```
Observe how mapping (as needed in coarse-grain SVM) is no longer necessary.
any numpy.ndarray (or other Python object with a buffer interface) if the implementation supports fine-grained system shared virtual memory.

This is how plain numpy arrays may directly be passed to a kernel:
```
ary = np.zeros(1000, np.float32)
prg.twice(queue, ary.shape, None, cl.SVM(ary))
queue.finish() # synchronize
print(ary) # access from host
```
coarse-grain shared memory as returned by (e.g.) csvm_empty() for any implementation of OpenCL 2.0.

Note

Applications making use of coarse-grain SVM may be better served by opaque-style SVM. See Opaque and “Wrapped-numpy” Styles of Referencing SVM.

This is how coarse-grain SVM may be used from both host and device:
```
svm_ary = cl.SVM(
    cl.csvm_empty(ctx, 1000, np.float32, alignment=64))
assert isinstance(svm_ary.mem, np.ndarray)

with svm_ary.map_rw(queue) as ary:
    ary.fill(17)  # use from host

prg.twice(queue, svm_ary.mem.shape, None, svm_ary)
```

Coarse-grain shared-memory must be mapped into host address space using map() before being accessed through the numpy interface.

Note

This object merely serves as a ‘tag’ that changes the behavior of functions to which it is passed. It has no special management relationship to the memory it tags. For example, it is permissible to grab a numpy.ndarray out of SVM.mem of one SVM instance and use the array to construct another. Neither of the tags need to be kept alive.

Added in version 2016.2.

mem¶: The wrapped object.

__init__(self, arg: object, /) → None¶

map(queue: _cl.CommandQueue, flags: int, is_blocking: bool = True, wait_for: WaitList = None) → SVMMap[SVMInnerT][source]¶

Parameters:

is_blocking – If False, subsequent code must wait on SVMMap.event in the returned object before accessing the mapped memory.
flags – a combination of pyopencl.map_flags.

Returns:

an SVMMap instance

This differs from the inherited SVMPointer.map in that no size can be specified, and that mem is the exact array produced when the SVMMap is used as a context manager.

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution.

map_ro(queue: _cl.CommandQueue, is_blocking: bool = True, wait_for: WaitList = None) → SVMMap[SVMInnerT][source]¶: Like map(), but with flags set for a read-only map.

map_rw(queue: _cl.CommandQueue, is_blocking: bool = True, wait_for: WaitList = None) → SVMMap[SVMInnerT][source]¶: Like map(), but with flags set for a read-only map.

class pyopencl.SVMMap(svm: SVM[SVMInnerT] | None, array: SVMInnerT, queue: CommandQueue, event: Event)[source]¶

Returned by SVMPointer.map() and SVM.map(). This class may also be used as a context manager in a with statement. release() will be called upon exit from the with region. The value returned to the as part of the context manager is the mapped Python object (e.g. a numpy array).

Added in version 2016.2.

property event¶: The Event returned when mapping the memory.

release(queue: CommandQueue | None = None, wait_for: Sequence[Event] | None = None) → Event[source]¶

Parameters:: queue – a pyopencl.CommandQueue. Defaults to the one with which the map was created, if not specified.
Returns:: a pyopencl.Event

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution.

Helper functions for `numpy`-based SVM allocation¶

pyopencl.svm_empty(ctx: Context, flags: svm_mem_flags, shape: int | tuple[int, ...], dtype: DTypeT, order: Literal['F', 'C'] = 'C', alignment: int | None = None, queue: CommandQueue | None = None) → ndarray[tuple[int, ...], DTypeT][source]¶

Allocate an empty numpy.ndarray of the given shape, dtype and order. (See numpy.empty() for the meaning of these arguments.) The array will be allocated in shared virtual memory belonging to ctx.

Parameters:

ctx – a Context
flags – a combination of flags from svm_mem_flags.
alignment – the number of bytes to which the beginning of the memory is aligned. Defaults to the numpy.dtype.itemsize of dtype.

Returns:

a numpy.ndarray whose numpy.ndarray.base attribute is a SVMAllocation.

To pass the resulting array to an OpenCL kernel or enqueue_copy(), you will likely want to wrap the returned array in an SVM tag.

Added in version 2016.2.

Changed in version 2022.2: queue argument added.

pyopencl.svm_empty_like(ctx: Context, flags: svm_mem_flags, ary: ndarray[tuple[int, ...], DTypeT], alignment: int | None = None) → ndarray[tuple[int, ...], DTypeT][source]¶

Allocate an empty numpy.ndarray like the existing numpy.ndarray ary. The array will be allocated in shared virtual memory belonging to ctx.

Parameters:: alignment – the number of bytes to which the beginning of the memory is aligned. Defaults to the numpy.dtype.itemsize of dtype.
Returns:: a numpy.ndarray whose numpy.ndarray.base attribute is a SVMAllocation.

To pass the resulting array to an OpenCL kernel or enqueue_copy(), you will likely want to wrap the returned array in an SVM tag.

Added in version 2016.2.

pyopencl.csvm_empty(ctx: Context, shape: int | tuple[int, ...], dtype: DTypeT, order: Literal['F', 'C'] = 'C', alignment: int | None = None, queue: CommandQueue | None = None) → ndarray[tuple[int, ...], DTypeT][source]¶: Like svm_empty(), but with flags set for a coarse-grain read-write buffer.

Added in version 2016.2.

pyopencl.csvm_empty_like(ctx: Context, ary: ndarray[tuple[int, ...], DTypeT], alignment: int | None = None) → ndarray[tuple[int, ...], DTypeT][source]¶: Like svm_empty_like(), but with flags set for a coarse-grain read-write buffer.

Added in version 2016.2.

pyopencl.fsvm_empty(ctx: Context, shape: int | tuple[int, ...], dtype: DTypeT, order: Literal['F', 'C'] = 'C', alignment: int | None = None, queue: CommandQueue | None = None) → ndarray[tuple[int, ...], DTypeT][source]¶: Like svm_empty(), but with flags set for a fine-grain read-write buffer.

Added in version 2016.2.

pyopencl.fsvm_empty_like(ctx: Context, ary: ndarray[tuple[int, ...], DTypeT], alignment: int | None = None) → ndarray[tuple[int, ...], DTypeT][source]¶: Like svm_empty_like(), but with flags set for a fine-grain read-write buffer.

Added in version 2016.2.

Operations on SVM¶

(See also Transfers.)

pyopencl.enqueue_svm_memfill(queue: CommandQueue, dest: SVMPointer, pattern: Buffer | ndarray[tuple[Any, ...], dtype[Any]], byte_count: int | None = None, wait_for: Sequence[Event] | None = None) → Event[source]¶

Fill shared virtual memory with a pattern.

Parameters:

dest – a Python buffer object, or any implementation of SVMPointer.
pattern – a Python buffer object (e.g. a numpy.ndarray with the fill pattern to be used.
byte_count – The size of the memory to be fill. Defaults to the entirety of dest.

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution.

Added in version 2016.2.

pyopencl.enqueue_svm_migrate_mem(queue: CommandQueue, svms: Sequence[SVMPointer], flags: svm_mem_flags, wait_for: Sequence[Event] | None = None)[source]¶

Parameters:

svms – a collection of Python buffer objects (e.g. numpy arrays), or any implementation of SVMPointer.
flags – a combination of mem_migration_flags

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution.

Added in version 2016.2.

This function requires OpenCL 2.1.

Image¶

class pyopencl.ImageFormat(channel_order, channel_type)¶

channel_order¶: See channel_order for possible values.

channel_data_type¶: See channel_type for possible values.

channel_count¶: Added in version 0.91.5.

dtype_size¶: Added in version 0.91.5.

itemsize¶: Added in version 0.91.5.

__repr__()[source]¶: Returns a str representation of the image format.

Added in version 0.91.

Changed in version 0.91: Constructor arguments added.

Changed in version 2013.2: ImageFormat was made comparable and hashable

pyopencl.get_supported_image_formats(context, flags, image_type)¶: See mem_flags for possible values of flags and mem_object_type for possible values of image_type.

class pyopencl.Image¶

Use :func:`create_image` to create images.

Added in version 0.91.

info¶: Lower case versions of the mem_info and image_info constants may be used as attributes on instances of this class to directly query info attributes.

shape¶: Return the value of the shape constructor argument as a tuple.

get_image_info(param)¶: See image_info for values of param.

release()¶

pyopencl.create_image(context, flags, format, shape=None, pitches=None, hostbuf=None, is_array=False, buffer=None) → Image[source]¶

See mem_flags for values of flags. shape is a 2- or 3-tuple. format is an instance of ImageFormat. pitches is a 1-tuple for 2D images and a 2-tuple for 3D images, indicating the distance in bytes from one scan line to the next, and from one 2D image slice to the next.

If hostbuf is given and shape is None, then hostbuf.shape is used as the shape parameter.

Image inherits from MemoryObject.

Note

If you want to load images from numpy.ndarray instances or read images back into them, be aware that OpenCL images expect the x dimension to vary fastest, whereas in the default (C) order of numpy arrays, the last index varies fastest. If your array is arranged in the wrong order in memory, there are two possible fixes for this:

Convert the array to Fortran (column-major) order using numpy.asarray().
Pass ary.T.copy() to the image creation function.

Added in version 2024.3.

pyopencl.image_from_array(ctx, ary, num_channels=None, mode='r', norm_int=False)[source]¶

Build a 2D or 3D Image from the numpy.ndarray ary. If num_channels is greater than one, the last dimension of ary must be identical to num_channels. ary must be in C order. If num_channels is not given, it defaults to 1 for scalar types and the number of entries for Vector Types.

The ImageFormat is chosen as the first num_channels components of “RGBA”.

Parameters:: mode – “r” or “w” for read/write

Note

When reading from the image object, the indices passed to read_imagef are in the reverse order from what they would be when accessing ary from Python.

If norm_int is True, then the integer values are normalized to a floating point scale of 0..1 when read.

Added in version 2011.2.

pyopencl.enqueue_fill_image(queue, mem, color, origin, region, wait_for=None)¶

Parameters:: color – a buffer object (likely a numpy.ndarray)

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution.

Only available with CL 1.2.

Added in version 2011.2.

Transfers¶

pyopencl.enqueue_copy(queue: CommandQueue, dest: Buffer, src: Buffer | ndarray[tuple[Any, ...], dtype[Any]], *, dst_offset: int = 0, is_blocking: bool = True, wait_for: Sequence[Event] | None = None) → Event[source]¶

pyopencl.enqueue_copy(queue: CommandQueue, dest: Buffer | ndarray[tuple[Any, ...], dtype[Any]], src: Buffer, *, src_offset: int = 0, is_blocking: bool = True, wait_for: Sequence[Event] | None = None) → Event

pyopencl.enqueue_copy(queue: CommandQueue, dest: Buffer, src: Buffer, *, src_offset: int = 0, dst_offset: int = 0, byte_count: int | None = None, wait_for: Sequence[Event] | None = None) → Event

pyopencl.enqueue_copy(queue: CommandQueue, dest: Buffer, src: Buffer | ndarray[tuple[Any, ...], dtype[Any]], *, origin: tuple[int, ...], host_origin: tuple[int, ...], region: tuple[int, ...], buffer_pitches: tuple[int, ...] | None = None, host_pitches: tuple[int, ...] | None = None, is_blocking: bool = True, wait_for: Sequence[Event] | None = None) → Event

pyopencl.enqueue_copy(queue: CommandQueue, dest: Buffer | ndarray[tuple[Any, ...], dtype[Any]], src: Buffer, *, origin: tuple[int, ...], host_origin: tuple[int, ...], region: tuple[int, ...], buffer_pitches: tuple[int, ...] | None = None, host_pitches: tuple[int, ...] | None = None, is_blocking: bool = True, wait_for: Sequence[Event] | None = None) → Event

pyopencl.enqueue_copy(queue: CommandQueue, dest: Buffer, src: Buffer, *, src_origin: tuple[int, ...], dst_origin: tuple[int, ...], region: tuple[int, ...], src_pitches: tuple[int, ...] | None = None, dst_pitches: tuple[int, ...] | None = None, wait_for: Sequence[Event] | None = None) → Event

pyopencl.enqueue_copy(queue: CommandQueue, dest: Buffer | ndarray[tuple[Any, ...], dtype[Any]], src: Image, *, origin: tuple[int, ...], region: tuple[int, ...], pitches: tuple[int, ...] | None = None, is_blocking: bool = True, wait_for: Sequence[Event] | None = None) → Event

pyopencl.enqueue_copy(queue: CommandQueue, dest: Image, src: Buffer | ndarray[tuple[Any, ...], dtype[Any]], *, origin: tuple[int, ...], region: tuple[int, ...], pitches: tuple[int, ...] | None = None, is_blocking: bool = True, wait_for: Sequence[Event] | None = None) → Event

pyopencl.enqueue_copy(queue: CommandQueue, dest: Image, src: Buffer, *, origin: tuple[int, ...], region: tuple[int, ...], pitches: tuple[int, ...] | None = None, wait_for: Sequence[Event] | None = None) → Event

pyopencl.enqueue_copy(queue: CommandQueue, dest: Buffer, src: Image, *, origin: tuple[int, ...], region: tuple[int, ...], pitches: tuple[int, ...] | None = None, wait_for: Sequence[Event] | None = None) → Event

pyopencl.enqueue_copy(queue: CommandQueue, dest: Image, src: Image, *, src_origin: tuple[int, ...], dest_origin: tuple[int, ...], region: tuple[int, ...], wait_for: Sequence[Event] | None = None) → Event

pyopencl.enqueue_copy(queue: CommandQueue, dest: SVMPointer | Buffer | ndarray[tuple[Any, ...], dtype[Any]], src: SVMPointer | Buffer | ndarray[tuple[Any, ...], dtype[Any]], *, byte_count: int | None = None, src_offset: int = 0, dst_offset: int = 0, is_blocking: bool = True, wait_for: Sequence[Event] | None = None) → Event

Copy from Image, Buffer or the host to Image, Buffer or the host. (Note: host-to-host copies are unsupported.)

The following keyword arguments are available:

Parameters:

wait_for – (optional, default empty)
is_blocking – Wait for completion. Defaults to True. (Available on any copy involving host memory)

Returns:

A NannyEvent if the transfer involved a host-side buffer, otherwise an Event.

Note

Be aware that the deletion of the NannyEvent that is returned by the function if the transfer involved a host-side buffer will block until the transfer is complete, so be sure to keep a reference to this Event until the transfer has completed.

Note

Two types of ‘buffer’ occur in the arguments to this function, Buffer and ‘host-side buffers’. The latter are defined by Python and commonly called buffer objects. numpy arrays are a very common example. Make sure to always be clear on whether a Buffer or a Python buffer object is needed.

Transfer Buffer ↔ host

Parameters:

src_offset –
offset in bytes (optional)

May only be nonzero if applied on the device side.
dst_offset –
offset in bytes (optional)

May only be nonzero if applied on the device side.

Note

The size of the transfer is controlled by the size of the of the host-side buffer. If the host-side buffer is a numpy.ndarray, you can control the transfer size by transferring into a smaller ‘view’ of the target array, like this:

cl.enqueue_copy(queue, large_dest_numpy_array[:15], src_buffer)

Transfer Buffer ↔ Buffer

Parameters:

byte_count – (optional) If not specified, defaults to the size of the source in versions 2012.x and earlier, and to the minimum of the size of the source and target from 2013.1 on.
src_offset – (optional)
dst_offset – (optional)

Rectangular Buffer ↔ host transfers (CL 1.1 and newer)

Parameters:

buffer_origin – tuple of int of length three or shorter. (mandatory)
host_origin – tuple of int of length three or shorter. (mandatory)
region – tuple of int of length three or shorter. (mandatory)
buffer_pitches – tuple of int of length two or shorter. (optional, “tightly-packed” if unspecified)
host_pitches – tuple of int of length two or shorter. (optional, “tightly-packed” if unspecified)

Rectangular Buffer ↔ Buffer transfers (CL 1.1 and newer)

Parameters:

src_origin – tuple of int of length three or shorter. (mandatory)
dst_origin – tuple of int of length three or shorter. (mandatory)
region – tuple of int of length three or shorter. (mandatory)
src_pitches – tuple of int of length two or shorter. (optional, “tightly-packed” if unspecified)
dst_pitches – tuple of int of length two or shorter. (optional, “tightly-packed” if unspecified)

Transfer Image ↔ host

Parameters:

origin – tuple of int of length three or shorter. (mandatory)
region – tuple of int of length three or shorter. (mandatory)
pitches – tuple of int of length two or shorter. (optional)

Transfer Buffer ↔ Image

Parameters:

offset – offset in buffer (mandatory)
origin – tuple of int of length three or shorter. (mandatory)
region – tuple of int of length three or shorter. (mandatory)

Transfer Image ↔ Image

Parameters:

src_origin – tuple of int of length three or shorter. (mandatory)
dest_origin – tuple of int of length three or shorter. (mandatory)
region – tuple of int of length three or shorter. (mandatory)

Transfer SVMPointer/host ↔ SVMPointer/host

Parameters:: byte_count – (optional) If not specified, defaults to the size of the source in versions 2012.x and earlier, and to the minimum of the size of the source and target from 2013.1 on.

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution.

Added in version 2011.1.

pyopencl.enqueue_fill(queue, dest, src, **kwargs)[source]¶: Added in version 2022.2.

pyopencl.enqueue_copy_buffer_p2p_amd(platform, queue, src, dest, size=None, wait_for=None)¶

AMD extension to perform a peer-to-peer copy between two buffers on two different devices. The two devices must be in different contexts. The queue must be where the source buffer is located.

Parameters:

platform – a Platform instance
queue – a CommandQueue instance
src – a Buffer instance
dest – a Buffer instance
size – the number of bytes to copy. If None, the minimum of the sizes of the two buffers is used.

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution.

Only available on AMD platforms.

Added in version 2023.1.2.

Mapping Memory into Host Address Space¶

class pyopencl.MemoryMap¶

This class may also be used as a context manager in a with statement. The memory corresponding to this object will be unmapped when this object is deleted or release() is called.

release(self, queue: pyopencl._cl.CommandQueue | None = None, wait_for: object | None = None) → pyopencl._cl.Event¶

pyopencl.enqueue_map_buffer(queue, buf, flags, offset, shape, dtype, order='C', strides=None, wait_for=None, is_blocking=True)¶

wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting execution. shape, dtype, and order have the same meaning as in numpy.empty(). See map_flags for possible values of flags. strides, if given, overrides order.

Returns:: a tuple (array, event). array is a numpy.ndarray representing the host side of the map. Its .base member contains a MemoryMap.

Changed in version 2011.1: is_blocking now defaults to True.

Changed in version 2013.1: order now defaults to “C”.

Changed in version 2013.2: Added strides argument.

Sample usage:

mapped_buf = cl.enqueue_map_buffer(queue, buf, ...)
with mapped_buf.base:
    # work with mapped_buf
    ...

# memory will be unmapped here

pyopencl.enqueue_map_image(queue, buf, flags, origin, region, shape, dtype, order='C', strides=None, wait_for=None, is_blocking=True)¶

Returns:: a tuple (array, event, row_pitch, slice_pitch). array is a numpy.ndarray representing the host side of the map. Its .base member contains a MemoryMap.

Changed in version 2011.1: is_blocking now defaults to True.

Changed in version 2013.1: order now defaults to “C”.

Changed in version 2013.2: Added strides argument.

Samplers¶

class pyopencl.Sampler¶

__init__(context, normalized_coords, addressing_mode, filter_mode)¶

normalized_coords is a bool indicating whether to use coordinates between 0 and 1 (True) or the texture’s natural pixel size (False). See addressing_mode and filter_mode for possible argument values.

Also supports an alternate signature (context, properties).

Parameters:: properties – a sequence of keys and values from sampler_properties as accepted by clCreateSamplerWithProperties() (see the OpenCL spec for details). The trailing 0 is added automatically and does not need to be included.

This signature Requires OpenCL 2 or newer.

Changed in version 2018.2: The properties-based signature was added.

info¶: Lower case versions of the sampler_info constants may be used as attributes on instances of this class to directly query info attributes.

get_info(param)¶: See sampler_info for values of param.

from_int_ptr(int_ptr_value: int, retain: bool = True) → pyopencl._cl.Sampler¶: (static method) Return a new Python object referencing the C-level cl_sampler object at the location pointed to by int_ptr_value. The relevant clRetain* function will be called if retain is True.If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to pyopencl.

Added in version 2013.2.

Changed in version 2016.1: retain added.

int_ptr¶: Return an integer corresponding to the pointer value of the underlying cl_sampler. Use from_int_ptr() to turn back into a Python object.

Added in version 2013.2.

Pipes¶

class pyopencl.Pipe(context, flags, packet_size, max_packets, properties=())¶

See mem_flags for values of flags.

Parameters:: properties – a sequence of keys and values from pipe_properties as accepted by clCreatePipe(). The trailing 0 is added automatically and does not need to be included. (This argument must currently be empty.)

This function requires OpenCL 2 or newer.

Added in version 2020.3.

Changed in version 2021.1.7: properties now defaults to an empty tuple.

get_pipe_info(param)¶: See pipe_info for values of param.

Type aliases¶

class pyopencl._cl.Buffer¶: See pyopencl.Buffer.

class pyopencl._cl.Image¶: See pyopencl.Image.

OpenCL Runtime: Memory¶

Memory Migration¶

Buffer¶

Shared Virtual Memory (SVM)¶

Opaque and “Wrapped-numpy” Styles of Referencing SVM¶

Using SVM with Arrays¶

SVM Pointers, Allocations, and Maps¶

Helper functions for numpy-based SVM allocation¶

Operations on SVM¶

Image¶

Transfers¶

Mapping Memory into Host Address Space¶

Samplers¶

Pipes¶

Type aliases¶

Opaque and “Wrapped-`numpy`” Styles of Referencing SVM¶

Helper functions for `numpy`-based SVM allocation¶