xopto.mcbase.mcworker module¶

class ClWorker[source]¶

Bases: xopto.mcbase.mcobject.McObject

OpenCL worker with support for allocation of read-write data buffers of arbitrary types and management of read-only lookup tables.

Parameters

types (mctypes.McDataTypes) –
A class that defines all the simulator data types. Use one of the following predefined type classes derived from mctypes.McDataTypes:
- mctypes.McDataTypesSingle
  - 32-bit size type
  - 32-bit default integers,
  - 64-bit detector accumulators,
  - single precision floating-point arithmetics,
  - 32-bit photon packet counter (maximum number of photon packets per OpenCL kernel call limited to 4,294,967,295)
- mctypes.McDataTypesDouble
  - 32-bit size type,
  - 32-bit default integers,
  - 64-bit detector accumulators,
  - double precision floating-point arithmetics,
  - 32-bit photon packet counter (maximum number of photon packets per OpenCL kernel call limited to 4,294,967,295)
- mctypes.McDataTypesSingleCnt64
  - 64-bit size type,
  - 32-bit default integers,
  - 64-bit detector accumulators,
  - single precision floating-point arithmetics,
  - 64-bit photon packet counter (maximum number of photon packets per OpenCL kernel call virtually unlimited)
- mctypes.McDataTypesDoubleCnt64
  - 64-bit size type,
  - 32-bit default integers,
  - 64-bit detector accumulators,
  - double precision floating-point arithmetics,
  - 64-bit photon packet counter (maximum number of photon packets per OpenCL kernel call virtually unlimited)
cl_devices (str or cl.Device or List[cl.Device] or cl.Context or cl.CommnadQueue) – A python list of OpenCL devices that are used for conducting the simulation. See the clGpuDevices and clCpuDevices functions of the xopto.clinfo module for details on obtaining a list of OpenCl capable devices. If None is provided, the first available device is used (GPU devices have priority over CPU devices). Use function xopto.clinfo.device() to get a desired device by simple keywords, e.g. a call clinfo.device([‘amd’, ‘nvidia’, ‘hd’, ‘cpu’], that will search for an AMD GPU, Nvidia GPU, Intel Hd GPU, any CPU and return the first device found. The value of this input argument can also be an instance of OpenCL Context or an instance of OpenCL CommandQueue. Note that in case an instance of CommandQueue is passed, the value of parameter cl_profiling is ignored since it is not possible to enable or disable profiling on an existing OpenCL CommandQueue.
cl_build_options (List[str]) – A list of OpenCL build option as specified by the OpenCl manuals at https://www.khronos.org/. An example of commonly used build options: cloptions=[‘-cl-opt-disable’, ‘-Werror’, ‘-cl-fast-relaxed-math’, ‘-cl-mad-enable’].
cl_profiling (bool) – Enables OpenCL command queue profiling. Note that in case an instance of CommandQueue is passed as the cl_devices parameter, the value of parameter cl_profiling is ignored since it is not possible to enable or disable profiling on an existing OpenCL CommandQueue.
kwargs (dict) – Keyword arguments passed to the Mixin classes.

Note

Use the create_allocator() method to create buffer allocators and the create_lut_manager() method to create managers of lookup tables.

append_r_lut_data(dtype: numpy.dtype, data: numpy.ndarray, force: bool = False) → xopto.mcbase.mcutil.lut.LutEntry [source]¶

Add a read-only lookup table data array to the list of managed lookup table arrays.

Parameters

dtype (np.dtype) – Data type of the lookup table manager.
data (np.ndarray) – Lookup table data to be added to the managed list. The numpy array must be of a type that can be converted to the data type of the lookup table manager.
force (bool) – Add the array to the managed list even if an existing entry for the given data array is found.

Returns

lutentry – Lookup table entry. Use the :py:attr:LutEntry.offset to get the offset of the first element in the common data array.

Return type

LutEntry

cl_allocate_rw_buffer(dtype: numpy.dtype, owner: any, shape: tuple, download=True)[source]¶

Allocate a read-write OpenCL buffer of the given data type using the related OpenCL buffer allocator.

Parameters

dtype (np.dtype) – Numpy data type of the buffer allocator.
owner (any) – Object that will own the allocated buffer.
shape (Tuple[int]) – Shape of the buffer array to allocate.
download (bool) – Set to True if the data buffer should be downloaded after executing the kernel. The downloaded data will be passed to the update_data() of the owner.

Returns

allocation – Buffer allocation object with information on the allocation.

Return type

BufferAllocation

cl_allocation_download(allocation: xopto.mcbase.mcutil.buffer.BufferAllocation, out: Optional[numpy.ndarray] = None) → numpy.ndarray[source]¶

Download the content of the allocated buffer from the OpenCL device.

Parameters

allocation (BufferAllocation) – Buffer allocation as returned by the allocate_buffer() methods.
out (np.ndarray) – Optional target numpy data array that will be filled with the content of the OpenCL buffer. The type and size of the numpy array must match the allocation.

Returns

out – Numpy data array that is filled with the OpenCL buffer content.

Return type

np.ndarray

cl_allocation_upload(allocation: xopto.mcbase.mcutil.buffer.BufferAllocation, data: numpy.ndarray)[source]¶

Upload an allocated OpenCL buffer from host to the OpenCL device.

Parameters

allocation (BufferAllocation) – Buffer allocation as returned by the cl_allocate_rw_int_buffer() or cl_allocate_rw_accumulator_buffer() or cl_allocate_rw_accumulator_buffer() methods.
data (np.ndarray) – Data array to be uploaded. The type and size of the numpy array must match the allocation.

property cl_buffers: dict¶: OpenCL data buffers.

cl_build(cl_src: str, verbose: bool = False) → pyopencl.Program[source]¶

Build OpenCL source code. A context and command queue are created on the first run.

Parameters

cl_src (str) – OpenCL source code as a string.
verbose (bool) – Turns on verbose reporting.

Returns

program – OpenCL executable.

Return type

cl.Program

property cl_build_options: Tuple[str]¶: Returns a tuple of OpenCL build options that were passed to the constructor.

property cl_context: pyopencl._cl.Context¶: OpenCL context.

property cl_device: List[pyopencl._cl.Device]¶: OpenCL device that is used to run this simulator instance.

property cl_exec: pyopencl.Program¶: The latest OpenCL program built with this worker.

property cl_profiling: bool¶: Returns True if OpenCL command queue allows profiling.

property cl_queue: pyopencl._cl.CommandQueue¶: OpenCL command queue.

cl_r_buffer(name: str, data: numpy.ndarray, size: Optional[int] = None) → pyopencl._cl.Buffer[source]¶

Create a read-only OpenCL buffer and optionally initialize the buffer with data. If a buffer of equal or larger size is found for the given name, a new buffer is not created.

Parameters

name (str) – A unique name for the buffer.
data (any object with a buffer interface) – Initializer for the OpenCl buffer.
size (int) – Size of the buffer in bytes.
buffer (cl.Buffer) – The OpenCL buffer.

Note

One of the size or data input arguments must be defined. If both are defined, data will be used to derive the size and initialize the OpenCL buffer.

cl_r_lut_buffer(dtype: numpy.dtype, update=True)[source]¶

Returns an OpenCL buffer (create if not exist) representing the read-only data arrays managed by the related read-only lookup table manager. The value of update argument controls if the content of the OpenCL buffer is updated with the content of the managed arrays. If an OpenCL buffer does not exist, a new one is created and updated regardless of the value of the update argument.

Parameters

dtype (np.dtype) – Data type of the lookup table manager.
update (bool) – If True, update the flat numpy array with the current content of the managed lookup tables. If an OpenCL buffer does not exist, a new is created and updated regardless of the value of the update argument.

Returns

cl_float_lut – OpenCL buffer of the floating-point lookup table array.

Return type

cl.Buffer

cl_rw_allocator(dtype: numpy.dtype) → xopto.mcbase.mcutil.buffer.BufferAllocator [source]¶

Returns OpenCL read-write buffer allocator for the give data type.

Parameters: dtype (np.dtype) – Numpy data type used with the allocator.
Returns: allocator – Buffer allocator for the given data type.
Return type: BufferAllocator

cl_rw_allocator_buffer(dtype: numpy.dtype, fill=None) → pyopencl._cl.Buffer[source]¶

Fetch the OpenCL read-write buffer of the allocator for the given data type. A new OpenCL buffer is created on the first call. A new OpenCL buffer is also allocated if the size of the existing buffer is too small for the allocations. The fill argument can be used to initialize the buffer with the given value.

Parameters

dtype (np.dtype) – Buffer allocator data type.
fill (np.dtype.type) – If not None, initialize the buffer with the given value / fill.

Returns

buffer – OpenCL read-write buffer of the allocator.

Return type

cl.Buffer

property cl_rw_allocators: xopto.mcbase.mcutil.buffer.RestrictedBufferAllocators¶: Allocators of OpenCL buffers.

cl_rw_buffer(name: str, data: Optional[numpy.ndarray] = None, size: Optional[int] = None) → pyopencl._cl.Buffer[source]¶

Create a read-write OpenCL buffer and optionally initialize the buffer with data.

Parameters

name (str) – A unique name for the buffer.
data (any object with a buffer interface) – Initializer for the OpenCl buffer.
size (int) – Size of the buffer in bytes.

Returns

buffer – The OpenCL buffer.

Return type

cl.Buffer

Note

One of the size or data input arguments must be defined. If both are defined, data will be used to derive the size and initialize the OpenCL buffer.

cl_w_buffer(name: str, size: Optional[int] = None) → pyopencl._cl.Buffer[source]¶

Create a write only OpenCL buffer and optionally initialize the buffer with data. If a buffer of equal or larger size is found for the given name, a new buffer is not created.

Parameters

name (str) – A unique name for the buffer.
size (int) – Size of the buffer in bytes.

Returns

buffer – The opencl buffer.

Return type

cl.Buffer

cl_w_buffer_fill(cl_buffer: pyopencl._cl.Buffer, dtype: numpy.dtype, fill: int, offset: int = 0, size: Optional[int] = None, cl_kernel=None)[source]¶

Fast fill of writable OpenCL buffers with a given scalar value.

The OpenCL buffer must be writable, since the initialization is performed in an OpenCL kernel!

Parameters

cl_buffer (cl.Buffer) – The OpenCL buffer to fill.
dtype (np.dtype) – Numpy dtype of a buffer element/item.
fill (int or float) – Scalar value used as a buffer fill. Must be convertible to the given data type (dtype).
size (int) – The last item of the buffer relative to the offset that will be filled. If None, the entire buffer from the offset will be filled. Note that the size is given in buffer items not bytes!
offset (int) – First item of the buffer that will be filled. Note that the size is given in buffer items not bytes!
cl_kernel (cl.Kernel) –
OpenCL kernel that will be used to fill the buffer. If None, a matching kernel will be searched in the current executable cl_exec. The fill kernels must follow the following footprint:
```
fill_<dtype>(__global T *buffer, T fill_value,
             mc_size_t size, mc_size_t offset)
```
where dtype should be one of (double, float, int64, uint64, int32 or uint32).

Note

Note that the size and offset are given in buffer items not bytes!

dtype_to_typename(dtype: numpy.dtype) → str[source]¶

Return a standard short type name for the given numpy data type.

Parameters: dtype (np.dtype) – Numpy data type.
Returns: typename – A short standard type name for the given numpy data type.
Return type: str

event_timing(event: pyopencl._cl.Event) → Tuple[float, float][source]¶

If OpenCL profiling is enabled, the timing related to an OpenCL event can be retrieved through the profile property of the event:

ev.profile.queued - nanosecond counter captured on event queued
ev.profile.submit - nanosecond counter captured on event submitted
ev.profile.start - nanosecond counter captured on start of execution
ev.profile.complete - nanosecond counter captured on end of execution

This method returns the time (s) that was required to start executing of the command and the time (s) required to execute the command.

Parameters

event (cl.Event) – OpenCL event instance.

Returns

dt_delay (float) – Time (s) that was required to start the execution of the command (profile.start - profile.submit).
dt_exec (float) – Time (s) that was required to execute the command (profile.complete - profile.start).

property np_allocators: xopto.mcbase.mcutil.buffer.NumpyAllocators¶: Allocators of temporary numpy buffers.

property np_buffers: dict¶: Numpy data buffers.

r_lut_manager(dtype: numpy.dtype) → xopto.mcbase.mcutil.lut.LutManager [source]¶

Return a read-only lookup table manager that matches the given data type.

Parameters: dtype (np.dtype) – Data type managed by the lookup table manager.

property types: xopto.mcbase.mctypes.McDataTypesBase¶: Data types used by the OpenCL kernel.

class ClWorkerRngMixin(*args, **kwargs)[source]¶

Bases: object

ClWorker class mixin that can be used to create an OpenCl Random number generator.

Random number generator mixin for an OpenCL worker. Use the rng to access the random number generator and cl_max_threads to determine the maximum number of threads that can be run concurrently with this random number generator. The mutable seeeds can be accessed through the rng_seeds_x property and the immutable seeds through the rng_seeds_a.

Parameters: rnginit (np.uint64) – OpenCL random number generator initializer as a 64-bit unsigned integer. Use this initializer if there is a need to put the random, number generator into a known initial state.

property cl_max_threads: int¶: The maximum number of OpenCl threads that can be run concurrently with this random number generator.

property rng: xopto.cl.clrng.Random¶: Random number generator for OpenCL.

property rng_seeds_a¶: Immutable random number generator seeds A.

property rng_seeds_x¶: Mutable random number generator seeds X.

class ClWorkerStandardBufferLutMixin[source]¶

Bases: object

ClWorker class mixin that creates interfaces for a standard set of OpenCL read-write buffer allocators and read-ony lookup table managers.

append_r_float_lut(data: numpy.ndarray, force: bool = False) → xopto.mcbase.mcutil.lut.LutEntry [source]¶

Append data to the floating-point type read-only lookuptable. The OpenCL data type of the read-only lookup table is mc_float_t.

Parameters

data (np.ndarray) – Lookup table data to manage.
force (bool) – If True, append the data array even if it is already managed.

Returns

lut_entry (LutEntry) – Lookup table entry. Use the offset property to locate the first element of the entry in the lookup table buffer.
new (bool) – True if a lookup table entry with the same data was not found among the existing managed lookup table entries. If the value of the force argument is True, this value is always returned as True.

append_r_int_lut(data: numpy.ndarray, force: bool = False) → xopto.mcbase.mcutil.lut.LutEntry [source]¶

Append data to the integer type read-only lookuptable with The OpenCL data type of the read-only lookup table is mc_int_t.

Parameters

data (np.ndarray) – Lookup table data to manage.
force (bool) – If True, append the data array even if it is already managed.

Returns

lut_entry (LutEntry) – Lookup table entry. Use the offset property to locate the first element of the entry in the lookup table buffer.
new (bool) – True if a lookup table entry with the same data was not found among the existing managed lookup table entries. If the value of the force argument is True, this value is always returned as True.

cl_allocate_rw_accumulator_buffer(owner: any, shape: Tuple[int], download: bool = True) → xopto.mcbase.mcutil.buffer.BufferAllocation [source]¶

Allocate a new read-write accumulator buffer with OpenCL type mc_accu_t.

Parameters

owner (any) – Allocation owner / caller.
shape (Tuple[int]) – Allocation buffer shape.
download (bool) – Set to True if download is required after executing the kernel. The downloaded data will be passed to the update_data() method of the owner.

Returns

allocation – The buffer allocation.

Return type

BufferAllocation

cl_allocate_rw_float_buffer(owner: any, shape: tuple, download: bool = True) → xopto.mcbase.mcutil.buffer.BufferAllocator [source]¶

Allocate a new read-write floating-point buffer with OpenCL type mc_fp_t.

Parameters

owner (any) – Allocation owner / caller.
shape (Tuple[int]) – Allocation buffer shape.
download (bool) – Set to True if download is required after executing the kernel. The downloaded data will be passed to the update_data() method of the owner.

Returns

allocation – The buffer allocation.

Return type

BufferAllocation

cl_allocate_rw_int_buffer(owner: any, shape: tuple, download: bool = True) → xopto.mcbase.mcutil.buffer.BufferAllocator [source]¶

Allocate a new read-write integer buffer with OpenCL type mc_int_t.

Parameters

owner (any) – Allocation owner / caller.
shape (Tuple[int]) – Allocation buffer shape.
download (bool) – Set to True if download is required after executing the kernel. The downloaded data will be passed to the update_data() method of the owner.

Returns

allocation – The buffer allocation.

Return type

BufferAllocation

cl_r_float_lut(update: bool = True) → pyopencl._cl.Buffer[source]¶

Returns an OpenCL buffer (create if not exist) representing the read-only data arrays managed by the floating-point lookup table manager. The value of update argument controls if the content of the OpenCL buffer is updated with the content of the managed arrays. If an OpenCL buffer does not exist, a new is created and updated regardless of the value of the update argument.

Parameters: update (bool) – If True, update the flat numpy array of lookup tables with the current content of the managed lookup tables. If an OpenCL buffer does not exist, a new one is created and updated regardless of the value of the update argument.
Returns: cl_float_lut – OpenCL buffer of the floating-point lookup table array.
Return type: cl.Buffer

cl_r_int_lut(update: bool = True) → pyopencl._cl.Buffer[source]¶

Returns an OpenCL buffer (create if not exist) representing the read-only integer arrays managed by the integer lookup table manager. The value of update argument controls if the content of the OpenCL buffer is updated with the content of the managed arrays. If an OpenCL buffer does not exist, a new one is created and updated regardless of the value of the update argument.

Parameters: update (bool) – If True, update the flat numpy array of lookup tables with the current content of the managed lookup tables. If an OpenCL buffer does not exist, a new one is created and updated regardless of the value of the update argument.
Returns: cl_float_lut – OpenCL buffer of the floating-point lookup table array.
Return type: cl.Buffer

property cl_rw_accumulator_allocator: xopto.mcbase.mcutil.buffer.BufferAllocator¶: Allocator of read-write accumulator type OpenCL buffers.

cl_rw_accumulator_buffer(fill=None) → pyopencl._cl.Buffer[source]¶

Fetch the OpenCL buffer of the accumulator allocator. A new OpenCL buffer is created on the first call.

Parameters: fill (int) – Scalar value used to fill the buffer. Must be convertible to the given data type (dtype).
Returns: buffer – OpenCL buffer.
Return type: cl.Buffer

property cl_rw_float_allocator: xopto.mcbase.mcutil.buffer.BufferAllocator¶: Allocator of read-write floating-point type OpenCL buffers.

cl_rw_float_buffer(fill: Optional[float] = None) → pyopencl._cl.Buffer[source]¶

Fetch the OpenCL buffer of the floating-point allocator. A new OpenCL buffer is created on the first call.

Parameters: fill (float) – Scalar value used to fill the buffer. Must be convertible to the given data type (dtype).
Returns: buffer – OpenCL buffer.
Return type: cl.Buffer

property cl_rw_int_allocator: xopto.mcbase.mcutil.buffer.BufferAllocator¶: Allocator of read-write integer type OpenCL buffers.

cl_rw_int_buffer(fill: Optional[int] = None) → pyopencl._cl.Buffer[source]¶

Fetch the OpenCL buffer of the integer allocator. A new OpenCL buffer is created on the first call.

Parameters: fill (int) – Scalar value used to fill the buffer. Must be convertible to the given data type (dtype).
Returns: buffer – OpenCL buffer.
Return type: cl.Buffer

clear_r_float_lut()[source]¶: Clear the content of the floating point read-only lookup table manager.

clear_r_int_lut()[source]¶: Clear the content of the integer read-only lookup table manager.

property float_r_lut_manager: xopto.mcbase.mcutil.lut.LutManager¶: Floating-point read-only data lookup table manager.

property int_r_lut_manager: xopto.mcbase.mcutil.lut.LutManager¶: Integer read-only data lookup table manager.

property np_r_float_lut: numpy.ndarray¶: Numpy data buffer of the read-only floating-point type lookup table.

property np_r_int_lut: numpy.ndarray¶: Numpy data buffer of the read-only integer type lookup table.