xopto.mcbase.mcoptions module

class McBoolOption(name: str, value: bool)

Bases: xopto.mcbase.mcoptions.McOption

Base Class of Monte Carlo kernel options that have a boolean type.

Initializes a boolean kernel option.

Parameters

• name (str) – Property name

• value (bool) – Boolean value of the kernel option.

get_define()

class McDebugMode(value: bool)

Bases: xopto.mcbase.mcoptions.McBoolOption

Switch the kernel debug mode on or off. Use only for kernel development. Default is off.

Initializes the debug mode kernel option.

Parameters

value (bool) – Use True to enable the debug mode or False to disable the debug mode.

default = McBoolOption('MC_ENABLE_DEBUG', False)

off = McBoolOption('MC_ENABLE_DEBUG', False)

on = McBoolOption('MC_ENABLE_DEBUG', True)

class McFloatLutMemory(value: str = 'global')

Bases: xopto.mcbase.mcoptions.McTypeOption

OpenCL memory type used to hold the floating-point lookup table data. Use one of “constant_mem” or “global_mem”. Default is “global_mem”.

Note

Selecting “global_mem” memory will likely lead to a significant performance degradation, in particular on older GPUs. The amount of available “constant_mem” memory on GPUs is typically limited to about 64k.

Initializes the floating-point lookup table memory type kernel option.

Parameters

value (str) – Use “global_mem” to move integer lookup table data to the __global OpenCL memory or use “constant_mem” to move the lookup table data to the __constant OpenCL memory.

constant_mem = McTypeOption('MC_FP_LUT_ARRAY_MEMORY', __constant)

default = McTypeOption('MC_FP_LUT_ARRAY_MEMORY', __constant)

global_mem = McTypeOption('MC_FP_LUT_ARRAY_MEMORY', __global)

class McFloatOption(name: str, value: float)

Bases: xopto.mcbase.mcoptions.McOption

Initializes a floating-point kernel option.

Parameters

• name (str) – Property name

• value (float) – Floating-point value of the kernel option.

class McIntLutMemory(value: str = 'global')

Bases: xopto.mcbase.mcoptions.McTypeOption

OpenCL memory type used to hold the floating-point lookup table data. Use one of __constant or __global. Default is __global.

Note

Selecting “__global” memory will likely lead to a significant performance degradation, in particular on older GPUs. The amount of available “__constant” memory on GPUs is typically limited to about 64k.

Initializes the integer type lookup table memory type kernel option.

Parameters

value (str) – Use “global” to move integer type lookup table data to the __global OpenCL memory or use “constant” to move the lookup table data to the __constant OpenCL memory.

default = McTypeOption('MC_INT_LUT_ARRAY_MEMORY', constant)

class McIntOption(name: str, value: int)

Bases: xopto.mcbase.mcoptions.McOption

Base Class of Monte Carlo kernel options that have an integer type.

Initializes an integer kernel option.

Parameters

• name (str) – Property name

• value (int) – Integer value of the kernel option.

class McMethod(value: int = 0)

Bases: xopto.mcbase.mcoptions.McIntOption

Selects the Monte Carlo simulation method:

• Albedo Weight (0)

• Albedo Rejection (1)

• Microscopic Beer Lambert (2)

A detailed description of the available methods can be found in:

A. Sassaroli and F. Martelli Equivalence of four Monte Carlo methods for photon migration in turbid media J. Opt. Soc. Am. A / Vol. 29, No. 10 / October 2012

Note

Default method is Albedo Weight. The Albedo Rejection is fast but produces noisy results. The Microscopic Beer-Lambert is useful for fluence simulations with voxel size that is smaller than the mean free path.

Initializes the Monte Carlo simulation method option.

Parameters

value (int) –

Allowed values are:

• 0 for Albedo Weight

• 1 for Albedo Rejection or,

• 2 for Microscopic Beer-Lambert.

albedo_rejection = McIntOption('MC_METHOD', 1)

albedo_weight = McIntOption('MC_METHOD', 0)

ar = McIntOption('MC_METHOD', 1)

aw = McIntOption('MC_METHOD', 0)

default = McIntOption('MC_METHOD', 0)

mbl = McIntOption('MC_METHOD', 2)

microscopic_beer_lambert = McIntOption('MC_METHOD', 2)

class McMinimumPacketWeight(value: float = 0.0001)

Bases: xopto.mcbase.mcoptions.McFloatOption

Minimum packet weight allowed before starting packet termination or lottery. Default value is 1e-4.

Initializes a floating-point kernel option.

Parameters

• name (str) – Property name

• value (float) – Floating-point value of the kernel option.

default = McFloatOption('MC_PACKET_WEIGHT_MIN', 0.0001)

class McOption(name: str, value: str)

Bases: xopto.mcbase.mcobject.McObject

Base Class of Monte Carlo kernel options that are set up through defines.

Initializes a kernel option.

Parameters

• name (str) – Option name

• value (str, bool, int, float) – Option value.

static cl_value(value: str) → str

OpenCL representation of the option value that can be set by a define.

Parameters

value (str or bool or int or float) – Python representation of the option value.

Returns

cl_value – Representation of the option value that can be used in a standard C/OpenCL define.

Return type

str

classmethod make_define(name, value) → str

Create and return a standard C/OpenCL define.

Returns

define – A standard C/OpenCL define representing the option.

Return type

str

property name: str

Option name.

property value: str

Option value.

class McPacketLotteryChance(value: float = 0.1)

Bases: xopto.mcbase.mcoptions.McFloatOption

Terminate photon packet by lottery if the value of a uniform random number from [0, 1] exceeds this value. Default value is 0.1.

Initializes the lottery chance kernel option.

Parameters

value (float) – Lottery survival fraction from 0.0 to 1.0.

default = McFloatOption('MC_PACKET_LOTTERY_CHANCE', 0.1)

class McTypeOption(name: str, value: str)

Bases: xopto.mcbase.mcoptions.McOption

Base Class of Monte Carlo kernel options that have a label type (no quotes in the define).

Initializes a label (no quotes in the define) kernel option.

Parameters

• name (str) – Property name

• value (str) – String value of the kernel option.

class McUseEnhancedRng(value: bool)

Bases: xopto.mcbase.mcoptions.McBoolOption

Run the kernel with the enhanced version of the random number generator. Default is off.

Initializes the enhanced random number generator mode kernel option.

Note

The enhanced version of random number generator is required when performing simulations in large scattering volumes, were the number of scattering events is expected to be on the order of millions. Depending on the OpenCL device, there might be a small performance cost of about 15%, which is the reason for disabling this option by default.

Parameters

value (bool) – Use True to enable the enhanced random number generator mode or False to disable the enhanced random number generator mode.

default = McBoolOption('MC_USE_ENHANCED_RNG', False)

off = McBoolOption('MC_USE_ENHANCED_RNG', False)

on = McBoolOption('MC_USE_ENHANCED_RNG', True)

class McUseEvents(value: bool)

Bases: xopto.mcbase.mcoptions.McBoolOption

Turn on/off tracking of packet events. Default value is off.

Initializes the kernel option for tracking packet events.

Parameters

value (bool) – Use True to enable tracking of packet events or False to disable tracking of packet events.

default = McBoolOption('MC_USE_EVENTS', False)

off = McBoolOption('MC_USE_EVENTS', False)

on = McBoolOption('MC_USE_EVENTS', True)

class McUseFluenceCache(value: bool = False)

Bases: xopto.mcbase.mcoptions.McBoolOption

Turn on or off the use of OpenCL fluence cache. Default is off.

Note

Fluence cache will improve performance for large deposition voxels, where there is a high likelihood that consecutive weight depositions will go into the same accumulator.

Initializes the fluence cache option.

Parameters

value (bool) – Use True to enable fluence cache.

default = McBoolOption('MC_USE_FLUENCE_CACHE', False)

off = McBoolOption('MC_USE_FLUENCE_CACHE', False)

on = McBoolOption('MC_USE_FLUENCE_CACHE', True)

class McUseHalfMath(value: bool = False)

Bases: xopto.mcbase.mcoptions.McBoolOption

Turn on or off the use of OpenCL half-precision math. Default is off.

Note

Half-precision math gives performance benefit at a significantly reduced precision. Use this option with care.

Initializes the half-precision math kernel option.

Parameters

value (bool) – Use True to enable the half-precision math or False to disable half-precision math.

Note

The half-precision math and native math McUseNativeMath options are mutually excluding. Ony one of the two options can be enabled at any given time. If both options are enabled, the native math option takes precedence.

default = McBoolOption('MC_USE_HALF_MATH', False)

off = McBoolOption('MC_USE_HALF_MATH', False)

on = McBoolOption('MC_USE_HALF_MATH', True)

class McUseLottery(value: bool)

Bases: xopto.mcbase.mcoptions.McBoolOption

Switch on or off photon packet termination by lottery. Default is on.

Initializes the lottery kernel option.

Parameters

value (bool) – Use True to enable the lottery or False to disable the lottery.

default = McBoolOption('MC_USE_LOTTERY', True)

off = McBoolOption('MC_USE_LOTTERY', False)

on = McBoolOption('MC_USE_LOTTERY', True)

class McUseNativeMath(value: bool = False)

Bases: xopto.mcbase.mcoptions.McBoolOption

Turn on or off the use of OpenCL native math. Default is off.

Note

Native math usually gives some performance benefit, but might not be fully compliant with precisions defined by the IEEE standards.

Initializes the native math kernel option.

Parameters

value (bool) – Use True to enable native math or False to disable native math.

default = McBoolOption('MC_USE_NATIVE_MATH', False)

off = McBoolOption('MC_USE_NATIVE_MATH', False)

on = McBoolOption('MC_USE_NATIVE_MATH', True)

class McUsePackedStructures(value: bool)

Bases: xopto.mcbase.mcoptions.McBoolOption

Turn on/off the use of tightly packed structures. Default value is off.

Note

Note that packed structures can lead to significant performance degradation of the Monte Carlo kernel. This option is the last resort if the fields of the OpenCL and host structures cannot be properly aligned. When declaring OPenCL or host structures always start with the largest data type and move towards smaller data types. Use data types that are of size no less than 4 bytes.

Initializes the packed structures kernel option.

Parameters

value (bool) – Use True to enable packed structures or False to disable packed structures.

default = McBoolOption('MC_USE_PACKED_STRUCTURES', False)

off = McBoolOption('MC_USE_PACKED_STRUCTURES', False)

on = McBoolOption('MC_USE_PACKED_STRUCTURES', True)

class McUseSoft64Atomics(value: bool)

Bases: xopto.mcbase.mcoptions.McBoolOption

Force software implementation of 64-bit atomic operations.

Initializes the software-based 64-bit integer atomics usage option.

Parameters

value (bool) – Use True to force software-implemented 64-bit integer atomics.

default = McBoolOption('MC_USE_SOFT_64_ATOMICS', False)

off = McBoolOption('MC_USE_SOFT_64_ATOMICS', False)

on = McBoolOption('MC_USE_SOFT_64_ATOMICS', True)

cl_value(value: str) → str

OpenCL representation of the option value that can be set by a define. :param value: Python representation of the option value. :type value: str or bool or int or float

Returns

cl_value – Representation of the option value that can be used in a standard C/OpenCL define.

Return type

str

make_defines(options: List[Tuple[str, str]], indent: Optional[str] = None) → str

Create defines for the given list of options. These defines should be included at the beginning of the OpenCL source file.

Parameters

• options (List[RawOption]) – List of options defined as [(option_name, option_value), …].

• indent (str) – Indent to use when creating define directives.

Returns

defs – Options as defines, one per line.

Return type

str

resolve_cl_options(*args: Tuple[Tuple[str, str]]) → List[Tuple[str, str]]

Resolve collections of OpenCL options passed as input arguments. Check for duplicate options with different values and raise ValueError if the same option is defined with different values.

Parameters

args (Tuple[RawOption]) – Each positional argument must be a list of options defined as [(name, value), …].

Returns

options – List of resolved options defined as [(name, value), …].

Return type

List[RawOption]