tessl/pypi-pyopencl

Python wrapper for OpenCL enabling GPU and parallel computing with comprehensive array operations and mathematical functions

1.28x

Overview

Eval results

Files

Memory Management and Data Transfer

Name: tessl/pypi-pyopencl
Rating: 0.86 (1 reviews)
Author: tessl

Comprehensive memory management including buffer creation, image handling, data transfer between host and device, and advanced shared virtual memory (SVM) support for zero-copy operations in OpenCL 2.0+.

Capabilities

Buffer Management

Create and manage device memory buffers for data storage and computation.

class Buffer:
    """
    OpenCL memory buffer for device data storage.
    
    Attributes:
    - size (int): Buffer size in bytes
    - context (Context): Associated OpenCL context
    """
    
    def __init__(self, context, flags, size=0, hostbuf=None):
        """
        Create OpenCL buffer.
        
        Parameters:
        - context (Context): OpenCL context
        - flags (mem_flags): Memory flags (READ_ONLY, WRITE_ONLY, READ_WRITE, etc.)
        - size (int): Buffer size in bytes (required if hostbuf is None)
        - hostbuf (buffer, optional): Host buffer to copy data from
        """
    
    def get_info(self, param):
        """Get buffer information."""

class LocalMemory:
    """
    Specification for kernel local memory allocation.
    """
    
    def __init__(self, size):
        """
        Specify local memory size for kernel.
        
        Parameters:
        - size (int): Local memory size in bytes
        """

Image Handling

Create and manipulate image objects for texture operations and image processing.

def create_image(context, flags, format, shape=None, pitches=None,
                hostbuf=None, is_array=False, buffer=None):
    """
    Create OpenCL image object.
    
    Parameters:
    - context (Context): OpenCL context
    - flags (mem_flags): Memory flags
    - format (ImageFormat): Image format specification
    - shape (tuple[int, ...], optional): Image dimensions (width, height, depth)
    - pitches (tuple[int, ...], optional): Row/slice pitch in bytes
    - hostbuf (buffer, optional): Host image data
    - is_array (bool): Whether to create image array
    - buffer (Buffer, optional): Buffer to create image from
    
    Returns:
    Image: Created image object
    """

def image_from_array(ctx, ary, num_channels=None, mode="r", norm_int=False):
    """
    Create image from numpy array.
    
    Parameters:
    - ctx (Context): OpenCL context
    - ary (numpy.ndarray): Source array (must be C-contiguous)
    - num_channels (int, optional): Number of channels (auto-detected if None)
    - mode (str): Access mode ("r" for read-only, "w" for write-only)
    - norm_int (bool): Use normalized integer format
    
    Returns:
    Image: Image object created from array
    """

class Image:
    """
    OpenCL image object for texture operations.
    
    Attributes:
    - format (ImageFormat): Image format
    - width (int): Image width  
    - height (int): Image height
    - depth (int): Image depth (for 3D images)
    """
    
    def get_info(self, param):
        """Get image information."""

class ImageFormat:
    """
    Specification for image channel order and data type.
    """
    
    def __init__(self, channel_order, channel_type):
        """
        Create image format.
        
        Parameters:
        - channel_order (channel_order): Channel ordering (R, RG, RGBA, etc.)
        - channel_type (channel_type): Data type (FLOAT, SIGNED_INT32, etc.)
        """

def get_supported_image_formats(context, flags, image_type):
    """
    Get supported image formats for context.
    
    Parameters:
    - context (Context): OpenCL context
    - flags (mem_flags): Memory flags
    - image_type (mem_object_type): Image type (IMAGE2D, IMAGE3D, etc.)
    
    Returns:
    list[ImageFormat]: Supported image formats
    """

Data Transfer Operations

Transfer data between host and device memory with support for blocking and non-blocking operations.

def enqueue_copy(queue, dest, src, **kwargs):
    """
    Universal copy function for host/device data transfer.
    
    Supports multiple transfer types:
    - Buffer ↔ Host: Linear data transfer
    - Buffer ↔ Buffer: Device-to-device copy
    - Image ↔ Host: Image data transfer
    - Image ↔ Buffer: Image/buffer conversion
    - Rectangular transfers: Sub-region copying
    
    Parameters:
    - queue (CommandQueue): Command queue
    - dest: Destination (Buffer, Image, or host array)
    - src: Source (Buffer, Image, or host array)
    - src_offset (int, optional): Source offset in bytes
    - dst_offset (int, optional): Destination offset in bytes
    - byte_count (int, optional): Number of bytes to copy
    - origin (tuple, optional): Origin for image/rectangular transfers
    - region (tuple, optional): Region size for image/rectangular transfers
    - is_blocking (bool): Wait for completion (default True)
    - wait_for (list[Event], optional): Events to wait for
    
    Returns:
    Event: Transfer completion event
    """

def enqueue_fill(queue, dest, pattern, size, *, offset=0, wait_for=None):
    """
    Fill memory with repeating pattern.
    
    Parameters:
    - queue (CommandQueue): Command queue
    - dest (Buffer | SVMPointer): Target memory
    - pattern (buffer): Fill pattern
    - size (int): Number of bytes to fill
    - offset (int): Offset in destination
    - wait_for (list[Event], optional): Events to wait for
    
    Returns:
    Event: Fill completion event
    """

def enqueue_fill_buffer(queue, mem, pattern, offset, size, wait_for=None):
    """
    Fill buffer with pattern.
    
    Parameters:
    - queue (CommandQueue): Command queue
    - mem (Buffer): Target buffer
    - pattern (buffer): Fill pattern
    - offset (int): Offset in buffer
    - size (int): Number of bytes to fill
    - wait_for (list[Event], optional): Events to wait for
    
    Returns:
    Event: Fill completion event
    """

def enqueue_fill_image(queue, mem, color, origin, region, wait_for=None):
    """
    Fill image with solid color.
    
    Parameters:
    - queue (CommandQueue): Command queue
    - mem (Image): Target image
    - color (buffer): Fill color matching image format
    - origin (tuple[int, ...]): Origin coordinates (x, y, z)
    - region (tuple[int, ...]): Region size (width, height, depth)
    - wait_for (list[Event], optional): Events to wait for
    
    Returns:
    Event: Fill completion event
    """

def enqueue_migrate_mem_objects(queue, mem_objects, flags=0, wait_for=None):
    """
    Migrate memory objects between devices.
    
    Useful for multi-device scenarios to optimize memory locality.
    
    Parameters:
    - queue (CommandQueue): Command queue
    - mem_objects (list[Buffer | Image]): Memory objects to migrate
    - flags (mem_migration_flags): Migration flags (HOST, CONTENT_UNDEFINED)
    - wait_for (list[Event], optional): Events to wait for
    
    Returns:
    Event: Migration completion event
    """

Memory Mapping

Map device memory to host address space for direct access.

class MemoryMap:
    """
    Context manager for mapped memory regions.
    """
    
    def __enter__(self):
        """Enter mapping context, returns host pointer."""
    
    def __exit__(self, exc_type, exc_val, exc_tb):
        """Exit mapping context, unmaps memory."""
    
    def release(self, queue=None, wait_for=None):
        """
        Explicitly unmap memory.
        
        Parameters:
        - queue (CommandQueue, optional): Command queue
        - wait_for (list[Event], optional): Events to wait for
        
        Returns:
        Event: Unmap completion event
        """

def enqueue_map_buffer(queue, buf, flags, offset, shape, dtype, order="C", 
                      strides=None, wait_for=None, is_blocking=True):
    """
    Map buffer memory to host address space for direct access.
    
    Parameters:
    - queue (CommandQueue): Command queue
    - buf (Buffer): Buffer to map
    - flags (map_flags): Mapping flags (READ, WRITE, READ_WRITE)
    - offset (int): Offset in buffer
    - shape (tuple[int, ...]): Shape of mapped region
    - dtype: NumPy data type for array view
    - order (str): Memory order ("C" or "F")
    - strides (tuple[int, ...], optional): Custom strides
    - wait_for (list[Event], optional): Events to wait for
    - is_blocking (bool): Wait for mapping completion
    
    Returns:
    MemoryMap: Memory mapping context manager
    """

def enqueue_map_image(queue, img, flags, origin, region, shape, dtype,
                     order="C", strides=None, wait_for=None, is_blocking=True):
    """
    Map image memory to host address space for direct access.
    
    Parameters:
    - queue (CommandQueue): Command queue
    - img (Image): Image to map
    - flags (map_flags): Mapping flags (READ, WRITE, READ_WRITE)
    - origin (tuple[int, ...]): Origin coordinates (x, y, z)
    - region (tuple[int, ...]): Region size (width, height, depth)
    - shape (tuple[int, ...]): Shape of mapped array
    - dtype: NumPy data type for array view
    - order (str): Memory order ("C" or "F")
    - strides (tuple[int, ...], optional): Custom strides
    - wait_for (list[Event], optional): Events to wait for
    - is_blocking (bool): Wait for mapping completion
    
    Returns:
    MemoryMap: Memory mapping context manager
    """

Shared Virtual Memory (OpenCL 2.0+)

Zero-copy memory sharing between host and device using shared virtual memory.

class SVM:
    """
    Shared Virtual Memory pointer wrapper.
    """
    
    def __init__(self, data):
        """
        Wrap host data as SVM pointer.
        
        Parameters:
        - data: Host data with buffer interface
        """

class SVMPointer:
    """
    Base class for SVM pointer implementations.
    """

class SVMAllocation:
    """
    SVM memory allocation with device access.
    """
    
    def __init__(self, ctx, size, alignment, flags, queue=None):
        """
        Allocate SVM memory.
        
        Parameters:
        - ctx (Context): OpenCL context
        - size (int): Allocation size in bytes
        - alignment (int): Memory alignment
        - flags (svm_mem_flags): SVM memory flags
        - queue (CommandQueue, optional): Associated queue
        """

class SVMMap:
    """
    Context manager for SVM memory mapping.
    
    Attributes:
    - array: Mapped array object
    - event (Event): Mapping event
    """
    
    def __enter__(self):
        """Enter mapping context."""
    
    def __exit__(self, exc_type, exc_val, exc_tb):
        """Exit mapping context."""
    
    def release(self, queue=None, wait_for=None):
        """
        Release SVM mapping.
        
        Parameters:
        - queue (CommandQueue, optional): Command queue
        - wait_for (list[Event], optional): Events to wait for
        
        Returns:
        Event: Release completion event
        """

def svm_empty(ctx, flags, shape, dtype, order="C", alignment=None, queue=None):
    """
    Allocate empty SVM array.
    
    Parameters:
    - ctx (Context): OpenCL context
    - flags (svm_mem_flags): SVM memory flags
    - shape (int | tuple[int, ...]): Array shape
    - dtype: NumPy data type
    - order (str): Memory layout ("C" or "F")
    - alignment (int, optional): Memory alignment
    - queue (CommandQueue, optional): Associated queue
    
    Returns:
    numpy.ndarray: SVM-backed array
    """

def svm_empty_like(ctx, flags, ary, alignment=None):
    """
    Allocate SVM array like existing array.
    
    Parameters:
    - ctx (Context): OpenCL context
    - flags (svm_mem_flags): SVM memory flags
    - ary (numpy.ndarray): Template array
    - alignment (int, optional): Memory alignment
    
    Returns:
    numpy.ndarray: SVM-backed array
    """

def csvm_empty(ctx, shape, dtype, order="C", alignment=None, queue=None):
    """
    Allocate coarse-grain SVM array (convenience function).
    
    Parameters:
    - ctx (Context): OpenCL context
    - shape (int | tuple[int, ...]): Array shape
    - dtype: NumPy data type
    - order (str): Memory layout
    - alignment (int, optional): Memory alignment
    - queue (CommandQueue, optional): Associated queue
    
    Returns:
    numpy.ndarray: Coarse-grain SVM array
    """

def fsvm_empty(ctx, shape, dtype, order="C", alignment=None, queue=None):
    """
    Allocate fine-grain SVM array (convenience function).
    
    Parameters:
    - ctx (Context): OpenCL context
    - shape (int | tuple[int, ...]): Array shape
    - dtype: NumPy data type
    - order (str): Memory layout
    - alignment (int, optional): Memory alignment
    - queue (CommandQueue, optional): Associated queue
    
    Returns:
    numpy.ndarray: Fine-grain SVM array
    """

def enqueue_svm_memfill(queue, dest, pattern, byte_count=None, wait_for=None):
    """
    Fill SVM memory with pattern.
    
    Parameters:
    - queue (CommandQueue): Command queue
    - dest (SVMPointer): Target SVM memory
    - pattern (buffer): Fill pattern
    - byte_count (int, optional): Bytes to fill (default: entire dest)
    - wait_for (list[Event], optional): Events to wait for
    
    Returns:
    Event: Fill completion event
    """

def enqueue_svm_migrate_mem(queue, svms, flags, wait_for=None):
    """
    Migrate SVM memory between devices (OpenCL 2.1).
    
    Parameters:
    - queue (CommandQueue): Command queue
    - svms (list[SVMPointer]): SVM objects to migrate
    - flags (mem_migration_flags): Migration flags
    - wait_for (list[Event], optional): Events to wait for
    
    Returns:
    Event: Migration completion event
    """

Sampler Objects

Configure texture sampling for image operations.

class Sampler:
    """
    Texture sampler for image operations.
    """
    
    def __init__(self, context, normalized_coords, addressing_mode, filter_mode):
        """
        Create texture sampler.
        
        Parameters:
        - context (Context): OpenCL context
        - normalized_coords (bool): Use normalized coordinates
        - addressing_mode (addressing_mode): Address handling (CLAMP, REPEAT, etc.)
        - filter_mode (filter_mode): Filtering (NEAREST, LINEAR)
        """

Usage Examples

Basic Buffer Operations

import pyopencl as cl
import numpy as np

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

# Create host data
data = np.random.randn(1000).astype(np.float32)

# Create buffer and copy data
buf = cl.Buffer(ctx, cl.mem_flags.READ_WRITE | cl.mem_flags.COPY_HOST_PTR, hostbuf=data)

# Modify data on device (kernel execution would go here)
# ...

# Copy back to host
result = np.empty_like(data)
cl.enqueue_copy(queue, result, buf)

Image Processing Example

import pyopencl as cl
import numpy as np

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

# Create image from numpy array
image_data = np.random.randint(0, 256, (512, 512, 4), dtype=np.uint8)
image = cl.image_from_array(ctx, image_data, mode="r")

# Process image (kernel execution would go here)
# ...

# Read back processed image
result = np.empty_like(image_data)
cl.enqueue_copy(queue, result, image, origin=(0, 0), region=image_data.shape[:2])

SVM Memory Usage

import pyopencl as cl
import numpy as np

# Setup (requires OpenCL 2.0+)
ctx = cl.create_some_context()
queue = cl.CommandQueue(ctx)

# Check SVM support
if not cl.characterize.has_coarse_grain_buffer_svm(ctx.devices[0]):
    print("SVM not supported")
    exit()

# Allocate SVM memory
svm_data = cl.csvm_empty(ctx, (1000,), np.float32)

# Fill with data
svm_data[:] = np.random.randn(1000).astype(np.float32)

# Use in kernel (both host and device can access)
# kernel execution would use SVM(svm_data) as argument
# ...

print(f"SVM data: {svm_data[:5]}")

Memory Mapping

import pyopencl as cl
import numpy as np

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

# Create buffer
size = 1000 * np.dtype(np.float32).itemsize
buf = cl.Buffer(ctx, cl.mem_flags.READ_WRITE, size)

# Map buffer for host access
with cl.enqueue_map_buffer(queue, buf, cl.map_flags.READ | cl.map_flags.WRITE, 
                          0, size, np.float32) as mapped:
    # Direct access to device memory
    mapped[:] = np.random.randn(1000).astype(np.float32)
    print(f"Mapped data: {mapped[:5]}")

# Buffer automatically unmapped when leaving 'with' block

Install with Tessl CLI

npx tessl i tessl/pypi-pyopencl

tessl/pypi-pyopencl

memory-management.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Memory Management and Data Transfer

Capabilities

Buffer Management

Image Handling

Data Transfer Operations

Memory Mapping

Shared Virtual Memory (OpenCL 2.0+)

Sampler Objects

Usage Examples

Basic Buffer Operations

Image Processing Example

SVM Memory Usage

Memory Mapping

memory-management.mddocs/