ktt::Tuner Class Reference

#include <Tuner.h>

Public Member Functions
	Tuner (const PlatformIndex platform, const DeviceIndex device, const ComputeApi api)
	Tuner (const PlatformIndex platform, const DeviceIndex device, const ComputeApi api, const uint32_t computeQueueCount)
	Tuner (const ComputeApi api, const ComputeApiInitializer &initializer)
	Tuner (const ComputeApi api, const ComputeApiInitializer &initializer, std::vector< QueueId > &assignedQueueIds)
	~Tuner ()
KernelDefinitionId	AddKernelDefinition (const std::string &name, const std::string &source, const DimensionVector &globalSize, const DimensionVector &localSize, const std::vector< std::string > &typeNames={})
KernelDefinitionId	AddKernelDefinition (const std::string &name, const std::string &source, const std::vector< std::string > &typeNames={})
KernelDefinitionId	AddKernelDefinitionFromFile (const std::string &name, const std::string &filePath, const DimensionVector &globalSize, const DimensionVector &localSize, const std::vector< std::string > &typeNames={})
KernelDefinitionId	AddKernelDefinitionFromFile (const std::string &name, const std::string &filePath, const std::vector< std::string > &typeNames={})
KernelDefinitionId	GetKernelDefinitionId (const std::string &name, const std::vector< std::string > &typeNames={}) const
void	RemoveKernelDefinition (const KernelDefinitionId id)
void	SetArguments (const KernelDefinitionId id, const std::vector< ArgumentId > &argumentIds)
KernelId	CreateSimpleKernel (const std::string &name, const KernelDefinitionId definitionId)
KernelId	CreateCompositeKernel (const std::string &name, const std::vector< KernelDefinitionId > &definitionIds, KernelLauncher launcher=nullptr)
void	RemoveKernel (const KernelId id)
void	SetLauncher (const KernelId id, KernelLauncher launcher)
template<typename T >
void	AddParameter (const KernelId id, const std::string &name, const std::vector< T > &values, const std::string &group="")
void	AddCompilerParameter (const KernelId id, const std::string &name, const std::vector< std::string > &values={}, const std::string &group="")
void	AddSeparateCompilerParameter (const KernelId id, const std::string &name, const std::vector< std::string > &values={})
void	AddScriptParameter (const KernelId id, const std::string &name, const ParameterValueType valueType, const std::string &valueScript, const std::string &group="")
void	AddScriptCompilerParameter (const KernelId id, const std::string &name, const ParameterValueType valueType, const std::string &valueScript, const std::string &group="")
void	AddScriptSeparateCompilerParameter (const KernelId id, const std::string &name, const ParameterValueType valueType, const std::string &valueScript)
void	AddThreadModifier (const KernelId id, const std::vector< KernelDefinitionId > &definitionIds, const ModifierType type, const ModifierDimension dimension, const std::vector< std::string > &parameters, ModifierFunction function)
void	AddThreadModifier (const KernelId id, const std::vector< KernelDefinitionId > &definitionIds, const ModifierType type, const ModifierDimension dimension, const std::string &parameter, const ModifierAction action)
void	AddScriptThreadModifier (const KernelId id, const std::vector< KernelDefinitionId > &definitionIds, const ModifierType type, const ModifierDimension dimension, const std::string &script)
void	AddConstraint (const KernelId id, const std::vector< std::string > &parameters, ConstraintFunction function)
void	AddGenericConstraint (const KernelId id, const std::vector< std::string > &parameters, GenericConstraintFunction function)
void	AddScriptConstraint (const KernelId id, const std::vector< std::string > &parameters, const std::string &script)
void	SetProfiledDefinitions (const KernelId id, const std::vector< KernelDefinitionId > &definitionIds)
template<typename T >
ArgumentId	AddArgumentVector (const std::vector< T > &data, const ArgumentAccessType accessType, const ArgumentId &customId="")
template<typename T >
ArgumentId	AddArgumentVector (std::vector< T > &data, const ArgumentAccessType accessType, const ArgumentMemoryLocation memoryLocation, const ArgumentManagementType managementType, const bool referenceUserData, const ArgumentId &customId="")
template<typename T >
ArgumentId	AddArgumentVector (ComputeBuffer buffer, const size_t bufferSize, const ArgumentAccessType accessType, const ArgumentMemoryLocation memoryLocation, const ArgumentId &customId="")
ArgumentId	AddArgumentVector (ComputeBuffer buffer, const size_t bufferSize, const size_t elementSize, const ArgumentAccessType accessType, const ArgumentMemoryLocation memoryLocation, const ArgumentId &customId="")
ArgumentId	AddArgumentVectorFromFile (const std::string &filePath, const ArgumentDataType dataType, const size_t elementSize, const ArgumentAccessType accessType, const ArgumentMemoryLocation memoryLocation=ArgumentMemoryLocation::Device, const ArgumentManagementType managementType=ArgumentManagementType::Framework, const ArgumentId &customId="")
ArgumentId	AddArgumentVectorFromGenerator (const std::string &generatorFunction, const ArgumentDataType dataType, const size_t bufferSize, const size_t elementSize, const ArgumentAccessType accessType, const ArgumentMemoryLocation memoryLocation=ArgumentMemoryLocation::Device, const ArgumentManagementType managementType=ArgumentManagementType::Framework, const ArgumentId &customId="")
void	SaveArgumentVector (const ArgumentId &id, const std::string &filePath)
template<typename T >
ArgumentId	AddArgumentScalar (const T &data, const ArgumentId &customId="")
ArgumentId	AddArgumentScalar (const void *data, const size_t dataSize, const ArgumentId &customId="")
template<typename T >
ArgumentId	AddArgumentLocal (const size_t localMemorySize, const ArgumentId &customId="")
template<typename T >
ArgumentId	AddArgumentSymbol (const T &data, const ArgumentId &customId="", const std::string &symbolName="")
void	RemoveArgument (const ArgumentId &id)
void	SetReadOnlyArgumentCache (const bool flag)
KernelResult	Run (const KernelId id, const KernelConfiguration &configuration, const std::vector< BufferOutputDescriptor > &output)
KernelResult	Run (const KernelId id, const KernelConfiguration &configuration, const KernelDimensions &dimensions, const std::vector< BufferOutputDescriptor > &output)
void	SetProfiling (const bool flag)
bool	GetProfiling ()
void	SetValidationMethod (const ValidationMethod method, const double toleranceThreshold)
void	SetValidationMode (const ValidationMode mode)
void	SetValidationRange (const ArgumentId &id, const size_t range)
void	SetValueComparator (const ArgumentId &id, ValueComparator comparator)
void	SetReferenceComputation (const ArgumentId &id, ReferenceComputation computation)
void	SetReferenceKernel (const ArgumentId &id, const KernelId referenceId, const KernelConfiguration &configuration, const KernelDimensions &dimensions={})
void	SetReferenceArgument (const ArgumentId &id, const ArgumentId &referenceId)
std::vector< KernelResult >	Tune (const KernelId id, std::unique_ptr< StopCondition > stopCondition=nullptr, const std::optional< PreciseMeasurementParameters > &preciseParams=std::nullopt)
std::vector< KernelResult >	Tune (const KernelId id, const KernelDimensions &dimensions, std::unique_ptr< StopCondition > stopCondition=nullptr, const std::optional< PreciseMeasurementParameters > &preciseParams=std::nullopt)
std::vector< KernelResult >	TuneOptions (const KernelId id, const KernelConfiguration &baseConfiguration, std::unique_ptr< StopCondition > stopCondition=nullptr, const std::optional< PreciseMeasurementParameters > &preciseParams=std::nullopt)
std::vector< KernelResult >	TuneOptions (const KernelId id, const KernelConfiguration &baseConfiguration, const KernelDimensions &dimensions, std::unique_ptr< StopCondition > stopCondition=nullptr, const std::optional< PreciseMeasurementParameters > &preciseParams=std::nullopt)
KernelResult	TuneIteration (const KernelId id, const std::vector< BufferOutputDescriptor > &output, const bool recomputeReference=false, const std::optional< PreciseMeasurementParameters > &preciseParams=std::nullopt)
KernelResult	TuneIteration (const KernelId id, const KernelDimensions &dimensions, const std::vector< BufferOutputDescriptor > &output, const bool recomputeReference=false, const std::optional< PreciseMeasurementParameters > &preciseParams=std::nullopt)
std::vector< KernelResult >	SimulateKernelTuning (const KernelId id, const std::vector< KernelResult > &results, const uint64_t iterations=0)
std::vector< KernelResult >	SimulateTuning (const KernelId id, const std::vector< KernelResult > &results, std::unique_ptr< StopCondition > stopCondition=nullptr)
void	SetSearcher (const KernelId id, std::unique_ptr< Searcher > searcher)
void	SetProfileBasedSearcher (const KernelId id, const std::string &modelPath, const bool useBuiltinModule=true, const uint batchSize=5, const uint neighborSize=100, const uint randomSize=10)
void	InitializeConfigurationData (const KernelId id)
void	ClearConfigurationData (const KernelId id)
void	ClearData (const KernelId id)
uint64_t	GetConfigurationsCount (const KernelId id) const
KernelConfiguration	GetBestConfiguration (const KernelId id) const
KernelConfiguration	CreateConfiguration (const KernelId id, const ParameterInput &parameters) const
std::string	GetKernelSource (const KernelId id, const KernelConfiguration &configuration) const
std::string	GetKernelDefinitionSource (const KernelDefinitionId id, const KernelConfiguration &configuration) const
KernelResult	GetBestResult (const std::vector< KernelResult > &results) const
void	SaveResults (const std::vector< KernelResult > &results, const std::string &filePath, const OutputFormat format, const UserData &data={}) const
std::vector< KernelResult >	LoadResults (const std::string &filePath, const OutputFormat format) const
std::vector< KernelResult >	LoadResults (const std::string &filePath, const OutputFormat format, UserData &data) const
QueueId	AddComputeQueue (ComputeQueue queue)
void	RemoveComputeQueue (const QueueId id)
void	WaitForComputeAction (const ComputeActionId id)
void	WaitForTransferAction (const TransferActionId id)
void	SynchronizeQueue (const QueueId id)
void	SynchronizeQueues ()
void	SynchronizeDevice ()
void	Synchronize ()
void	SetProfilingCounters (const std::vector< std::string > &counters)
void	SetCompilerOptions (const std::string &options, const bool overrideDefault=false)
void	SetCompiler (const std::string &compiler)
void	SetGlobalSizeType (const GlobalSizeType type)
void	SetAutomaticGlobalSizeCorrection (const bool flag)
void	SetKernelCacheCapacity (const uint64_t capacity)
std::vector< PlatformInfo >	GetPlatformInfo () const
std::vector< DeviceInfo >	GetDeviceInfo (const PlatformIndex platform) const
DeviceInfo	GetCurrentDeviceInfo () const

Static Public Member Functions
static void	SetTimeUnit (const TimeUnit unit)
static void	SetLoggingLevel (const LoggingLevel level)
static LoggingLevel	GetLoggingLevel ()
static void	SetLoggingTarget (std::ostream &outputTarget)
static void	SetLoggingTarget (const std::string &filePath)

Detailed Description

Class which serves as the main part of public API of KTT framework.

Constructor & Destructor Documentation

Tuner() [1/4]

ktt::Tuner::Tuner ( const PlatformIndex  platform, const DeviceIndex  device, const ComputeApi  api  )

explicit

Creates tuner for the specified platform, device and compute API. All compute commands are submitted to a single queue. Indices for available platforms and devices can be retrieved by using GetPlatformInfo() and GetDeviceInfo() methods. If the specified compute API is CUDA or Vulkan, platform index is ignored.

Parameters

platform	Index for platform used by the tuner.
device	Index for device used by the tuner.
api	Compute API used by the tuner.

Tuner() [2/4]

ktt::Tuner::Tuner ( const PlatformIndex  platform, const DeviceIndex  device, const ComputeApi  api, const uint32_t  computeQueueCount  )

explicit

Creates tuner for the specified platform, device and compute API. Multiple compute queues can be created, based on the specified count. Compute commands to different queues can be submitted by utilizing KernelLauncher and ComputeInterface. Indices for available platforms and devices can be retrieved by using GetPlatformInfo() and GetDeviceInfo() methods. If the specified compute API is CUDA or Vulkan, platform index is ignored.

Parameters

platform	Index for platform used by the tuner.
device	Index for device used by the tuner.
api	Compute API used by the tuner.
computeQueueCount	Number of compute queues created inside the tuner. Has to be greater than zero.

Tuner() [3/4]

ktt::Tuner::Tuner ( const ComputeApi  api, const ComputeApiInitializer &  initializer  )

explicit

Creates tuner for the specified compute API using custom initializer. The initializer contains user-provided compute device context and queues.

Parameters

api	Compute API used by the tuner.
initializer	Custom compute API initializer. See ComputeApiInitializer for more information.

Tuner() [4/4]

ktt::Tuner::Tuner ( const ComputeApi  api, const ComputeApiInitializer &  initializer, std::vector< QueueId > &  assignedQueueIds  )

explicit

Creates tuner for the specified compute API using custom initializer. The initializer contains user-provided compute device context and queues. The ids assigned to queues will be added to the provided vector.

Parameters

api	Compute API used by the tuner.
initializer	Custom compute API initializer. See ComputeApiInitializer for more information.
assignedQueueIds	Ids assigned to compute queues inside initializer by the tuner. The order of assigned ids matches the order of queues inside initializer.

~Tuner()

ktt::Tuner::~Tuner

(

)

Tuner destructor.

Member Function Documentation

AddArgumentLocal()

template<typename T >

template< typename T > ArgumentId ktt::Tuner::AddArgumentLocal	(	const size_t	localMemorySize,
		const ArgumentId &	customId = ""
	)

Adds new local memory (shared memory in CUDA) argument to the tuner. All local memory arguments are read-only and cannot be initialized from host memory. In case of CUDA API usage, local memory arguments cannot be directly set as kernel function arguments. Setting a local memory argument to kernel in CUDA means that corresponding amount of memory will be allocated for kernel to use. In that case, all local memory argument ids should be specified at the end of the vector when calling SetArguments() method.

Parameters

localMemorySize	Size of kernel argument in bytes.
customId	Custom argument id that can be specified instead of a default.

Returns

Id assigned to kernel argument by tuner. The id can be used in other API methods.

AddArgumentScalar() [1/2]

template<typename T >

template< typename T > ArgumentId ktt::Tuner::AddArgumentScalar	(	const T &	data,
		const ArgumentId &	customId = ""
	)

Adds new scalar argument to the tuner. All scalar arguments are read-only.

Parameters

data	Kernel argument data. The data type must be trivially copyable. Bool, reference or pointer types are not supported.
customId	Custom argument id that can be specified instead of a default.

Returns

Id assigned to kernel argument by tuner. The id can be used in other API methods.

AddArgumentScalar() [2/2]

ArgumentId ktt::Tuner::AddArgumentScalar	(	const void *	data,
		const size_t	dataSize,
		const ArgumentId &	customId = ""
	)

Adds new scalar argument to the tuner. All scalar arguments are read-only. This method can be utilized when templated version of scalar argument addition cannot be used.

Parameters

data	Pointer to memory with kernel argument data.
dataSize	Size of data in bytes (e.g., 4 for 32-bit float).
customId	Custom argument id that can be specified instead of a default.

Returns

Id assigned to kernel argument by tuner. The id can be used in other API methods.

AddArgumentSymbol()

template<typename T >

template< typename T > ArgumentId ktt::Tuner::AddArgumentSymbol	(	const T &	data,
		const ArgumentId &	customId = "",
		const std::string &	symbolName = ""
	)

Adds new symbol argument to the tuner.

Parameters

data	Kernel argument data. The data type must be trivially copyable. Bool, reference or pointer types are not supported.
customId	Custom argument id that can be specified instead of a default.
symbolName	Name of the corresponding symbol in kernel source code. Only utilized when tuner is using CUDA API. The symbol name must be unique.

Returns

Id assigned to kernel argument by tuner. The id can be used in other API methods.

AddArgumentVector() [1/4]

template<typename T >

template< typename T > ArgumentId ktt::Tuner::AddArgumentVector	(	ComputeBuffer	buffer,
		const size_t	bufferSize,
		const ArgumentAccessType	accessType,
		const ArgumentMemoryLocation	memoryLocation,
		const ArgumentId &	customId = ""
	)

Adds new vector argument to the tuner. The argument buffer is created and managed by user and depending on the compute API, can be either CUdeviceptr or cl_mem handle. The tuner will not destroy the argument.

Parameters

buffer	User-provided memory buffer.
bufferSize	Size of the provided user buffer in bytes.
accessType	Access type specifies whether argument is used for input or output. See ArgumentAccessType for more information.
memoryLocation	Memory location specifies whether argument data will be accessed from device or host memory during its usage by compute API. See ArgumentMemoryLocation for more information.
customId	Custom argument id that can be specified instead of a default.

Returns

Id assigned to kernel argument by tuner. The id can be used in other API methods.

AddArgumentVector() [2/4]

ArgumentId ktt::Tuner::AddArgumentVector	(	ComputeBuffer	buffer,
		const size_t	bufferSize,
		const size_t	elementSize,
		const ArgumentAccessType	accessType,
		const ArgumentMemoryLocation	memoryLocation,
		const ArgumentId &	customId = ""
	)

Adds new vector argument to the tuner. The argument buffer is created and managed by user and depending on the compute API, can be either CUdeviceptr or cl_mem handle. The tuner will not destroy the argument. This method can be utilized when templated version of argument addition cannot be used. When using validation for arguments added through this method, value comparator must always be provided.

Parameters

buffer	User-provided memory buffer.
bufferSize	Size of the provided user buffer in bytes.
elementSize	Size of a single element inside buffer in bytes (e.g., 4 for 32-bit float).
accessType	Access type specifies whether argument is used for input or output. See ArgumentAccessType for more information.
memoryLocation	Memory location specifies whether argument data will be accessed from device or host memory during its usage by compute API. See ArgumentMemoryLocation for more information.
customId	Custom argument id that can be specified instead of a default.

Returns

Id assigned to kernel argument by tuner. The id can be used in other API methods.

AddArgumentVector() [3/4]

template<typename T >

template< typename T > ArgumentId ktt::Tuner::AddArgumentVector	(	const std::vector< T > &	data,
		const ArgumentAccessType	accessType,
		const ArgumentId &	customId = ""
	)

Adds new vector argument to the tuner. Makes copy of argument data, so the source data vector remains unaffected by tuner operations. Argument data will be accessed from device memory during its usage by compute API. The compute API buffer will be automatically created and managed by the KTT framework.

Parameters

data	Kernel argument data. The data type must be trivially copyable. Bool, reference or pointer types are not supported.
accessType	Access type specifies whether argument is used for input or output. See ArgumentAccessType for more information.
customId	Custom argument id that can be specified instead of a default.

Returns

Id assigned to kernel argument by tuner. The id can be used in other API methods.

AddArgumentVector() [4/4]

template<typename T >

template< typename T > ArgumentId ktt::Tuner::AddArgumentVector	(	std::vector< T > &	data,
		const ArgumentAccessType	accessType,
		const ArgumentMemoryLocation	memoryLocation,
		const ArgumentManagementType	managementType,
		const bool	referenceUserData,
		const ArgumentId &	customId = ""
	)

Adds new vector argument to the tuner. Allows wide range of argument customization options.

Parameters

data	Kernel argument data. The data type must be trivially copyable. Bool, reference or pointer types are not supported.
accessType	Access type specifies whether argument is used for input or output. See ArgumentAccessType for more information.
memoryLocation	Memory location specifies whether argument data will be accessed from device or host memory during its usage by compute API. See ArgumentMemoryLocation for more information.
managementType	Management type specifies who is responsible for creating, managing data and destroying compute API buffer corresponding to the argument. See ArgumentManagementType for more information.
referenceUserData	If set to true, tuner will store reference to source data and will access it directly during buffer operations. This results in lower memory overhead, but relies on a user to keep data in the source vector valid. If set to false, copy of the data will be made by the tuner.
customId	Custom argument id that can be specified instead of a default.

Returns

Id assigned to kernel argument by tuner. The id can be used in other API methods.

AddArgumentVectorFromFile()

ArgumentId ktt::Tuner::AddArgumentVectorFromFile	(	const std::string &	filePath,
		const ArgumentDataType	dataType,
		const size_t	elementSize,
		const ArgumentAccessType	accessType,
		const ArgumentMemoryLocation	memoryLocation = ArgumentMemoryLocation::Device,
		const ArgumentManagementType	managementType = ArgumentManagementType::Framework,
		const ArgumentId &	customId = ""
	)

Adds new vector argument to the tuner. Loads the argument data from the specified binary file.

Parameters

filePath	Path to the file from which argument data will be loaded.
dataType	Type of the argument data.
elementSize	Size of a single element inside the argument in bytes (e.g., 4 for 32-bit float).
accessType	Access type specifies whether argument is used for input or output. See ArgumentAccessType for more information.
memoryLocation	Memory location specifies whether argument data will be accessed from device or host memory during its usage by compute API. See ArgumentMemoryLocation for more information.
managementType	Management type specifies who is responsible for creating, managing data and destroying compute API buffer corresponding to the argument. See ArgumentManagementType for more information.
customId	Custom argument id that can be specified instead of a default.

Returns

Id assigned to kernel argument by tuner. The id can be used in other API methods.

AddArgumentVectorFromGenerator()

ArgumentId ktt::Tuner::AddArgumentVectorFromGenerator	(	const std::string &	generatorFunction,
		const ArgumentDataType	dataType,
		const size_t	bufferSize,
		const size_t	elementSize,
		const ArgumentAccessType	accessType,
		const ArgumentMemoryLocation	memoryLocation = ArgumentMemoryLocation::Device,
		const ArgumentManagementType	managementType = ArgumentManagementType::Framework,
		const ArgumentId &	customId = ""
	)

Adds new vector argument to the tuner. Generates the argument data from the specified Python script.

Parameters

generatorFunction	Python function which generates the elements inside the argument. It is called once per each element index, with the index value being stored in a Python local variable named 'i'.
dataType	Type of the argument data.
bufferSize	Size of the generated buffer in bytes.
elementSize	Size of a single element inside the argument in bytes (e.g., 4 for 32-bit float).
accessType	Access type specifies whether argument is used for input or output. See ArgumentAccessType for more information.
memoryLocation	Memory location specifies whether argument data will be accessed from device or host memory during its usage by compute API. See ArgumentMemoryLocation for more information.
managementType	Management type specifies who is responsible for creating, managing data and destroying compute API buffer corresponding to the argument. See ArgumentManagementType for more information.
customId	Custom argument id that can be specified instead of a default.

Returns

Id assigned to kernel argument by tuner. The id can be used in other API methods.

AddCompilerParameter()

void ktt::Tuner::AddCompilerParameter	(	const KernelId	id,
		const std::string &	name,
		const std::vector< std::string > &	values = {},
		const std::string &	group = ""
	)

Works exactly as AddParameter(), but for compiler parameters. Adds new compiler parameter for the specified kernel, providing parameter name and optionally list of allowed values. Parameters will be added to the compiler as compiler options. During the tuning process, tuner will generate configurations for combinations of kernel parameters and their values.

Parameters

id	Id of kernel for which the parameter will be added.
name	Name of a parameter. Parameter names for a single kernel must be unique.
values	Optional allowed values for the parameter. Value type is a string. If left empty, parameter with be either present without any value or completely excluded.
group	Optional group inside which the parameter will be added. Tuning configurations are generated separately for each group. This is useful when kernels contain groups of parameters that can be tuned independently. In this way, the total number of generated configurations can be significantly reduced.

AddComputeQueue()

QueueId ktt::Tuner::AddComputeQueue

(

ComputeQueue

queue

)

Adds the specified compute queue to the tuner. New queues can only be added if tuner was initialized with compute API initializer.

Parameters

queue

Queue which will be added. The queue should be tied to the context specified inside compute API initializer.

Returns

Id assigned to queue by the tuner.

AddConstraint()

void ktt::Tuner::AddConstraint	(	const KernelId	id,
		const std::vector< std::string > &	parameters,
		ConstraintFunction	function
	)

Adds constraint for the specified kernel. Constraints are used to prevent generating of configurations with conflicting combinations of parameter values.

Parameters

id	Id of kernel for which the constraint will be added.
parameters	Names of kernel parameters which will be affected by the constraint function. The order of parameter names corresponds to the order of parameter values inside the constraint function vector argument. Note that constraints can only be added between parameters which belong into the same group. The corresponding parameters must be added to the tuner with AddParameter() before calling this method. Only parameters with the unsigned integer type can be used with constraints.
function	Function which returns true if the provided combination of parameter values is valid. Returns false otherwise.

AddGenericConstraint()

void ktt::Tuner::AddGenericConstraint	(	const KernelId	id,
		const std::vector< std::string > &	parameters,
		GenericConstraintFunction	function
	)

Adds constraint for the specified kernel. Constraints are used to prevent generating of configurations with conflicting combinations of parameter values.

Parameters

id	Id of kernel for which the constraint will be added.
parameters	Names of kernel parameters which will be affected by the constraint function. The order of parameter names corresponds to the order of parameter values inside the constraint function vector argument. Note that constraints can only be added between parameters which belong into the same group. The corresponding parameters must be added to the tuner with AddParameter() before calling this method.
function	Function which returns true if the provided combination of parameter values is valid. Returns false otherwise.

AddKernelDefinition() [1/2]

KernelDefinitionId ktt::Tuner::AddKernelDefinition	(	const std::string &	name,
		const std::string &	source,
		const DimensionVector &	globalSize,
		const DimensionVector &	localSize,
		const std::vector< std::string > &	typeNames = {}
	)

Adds new kernel definition to the tuner. Requires specification of a kernel name, its source code and its global and local thread sizes.

Parameters

name	Name of a kernel function inside kernel source code. The name must be unique.
source	Kernel source code written in the corresponding compute API language.
globalSize	Dimensions for base kernel global size (e.g., grid size in CUDA, NDRange size in OpenCL).
localSize	Dimensions for base kernel local size (e.g., block size in CUDA, work-group size in OpenCL).
typeNames	Names of types which will be used to instantiate kernel template. Only supported in CUDA kernels.

Returns

Id assigned to kernel definition by the tuner. The id can be used in other API methods.

AddKernelDefinition() [2/2]

KernelDefinitionId ktt::Tuner::AddKernelDefinition	(	const std::string &	name,
		const std::string &	source,
		const std::vector< std::string > &	typeNames = {}
	)

Adds new kernel definition to the tuner. Requires specification of a kernel name and its source code.

Parameters

name	Name of a kernel function inside kernel source code. The name must be unique.
source	Kernel source code written in the corresponding compute API language.
typeNames	Names of types which will be used to instantiate kernel template. Only supported in CUDA kernels.

Returns

Id assigned to kernel definition by the tuner. The id can be used in other API methods.

AddKernelDefinitionFromFile() [1/2]

KernelDefinitionId ktt::Tuner::AddKernelDefinitionFromFile	(	const std::string &	name,
		const std::string &	filePath,
		const DimensionVector &	globalSize,
		const DimensionVector &	localSize,
		const std::vector< std::string > &	typeNames = {}
	)

Adds new kernel definition to the tuner. Requires specification of a kernel name, file path to its source code and its global and local thread sizes.

Parameters

name	Name of a kernel function inside kernel source code. The name must be unique.
filePath	Path to file with kernel source code written in the corresponding compute API language.
globalSize	Dimensions for base kernel global size (e.g., grid size in CUDA, NDRange size in OpenCL).
localSize	Dimensions for base kernel local size (e.g., block size in CUDA, work-group size in OpenCL).
typeNames	Names of types which will be used to instantiate kernel template. Only supported in CUDA kernels.

Returns

Id assigned to kernel definition by the tuner. The id can be used in other API methods.

AddKernelDefinitionFromFile() [2/2]

KernelDefinitionId ktt::Tuner::AddKernelDefinitionFromFile	(	const std::string &	name,
		const std::string &	filePath,
		const std::vector< std::string > &	typeNames = {}
	)

Adds new kernel definition to the tuner. Requires specification of a kernel name and file path to its source code.

Parameters

name	Name of a kernel function inside kernel source code. The name must be unique.
filePath	Path to file with kernel source code written in the corresponding compute API language.
typeNames	Names of types which will be used to instantiate kernel template. Only supported in CUDA kernels.

Returns

Id assigned to kernel definition by the tuner. The id can be used in other API methods.

AddParameter()

template<typename T >

template< typename T > void ktt::Tuner::AddParameter	(	const KernelId	id,
		const std::string &	name,
		const std::vector< T > &	values,
		const std::string &	group = ""
	)

Adds new parameter for the specified kernel, providing parameter name and list of allowed values. Parameters will be added to the kernel source code as preprocessor definitions. During the tuning process, tuner will generate configurations for combinations of kernel parameters and their values.

Parameters

id	Id of kernel for which the parameter will be added.
name	Name of a parameter. Parameter names for a single kernel must be unique.
values	Allowed values for the parameter. Supported value types are 64-bit integer (signed / unsigned), double, bool and string.
group	Optional group inside which the parameter will be added. Tuning configurations are generated separately for each group. This is useful when kernels contain groups of parameters that can be tuned independently. In this way, the total number of generated configurations can be significantly reduced.

AddScriptCompilerParameter()

void ktt::Tuner::AddScriptCompilerParameter	(	const KernelId	id,
		const std::string &	name,
		const ParameterValueType	valueType,
		const std::string &	valueScript,
		const std::string &	group = ""
	)

Works exactly as AddScriptParameter(), but for compiler parameters. Adds new compiler parameter for the specified kernel, providing parameter name, value type and a script which generates list of allowed values. Compiler parameters will be added as a compiler option. During the tuning process, tuner will generate configurations for combinations of kernel parameters and their values.

Parameters

id	Id of kernel for which the parameter will be added.
name	Name of a parameter. Parameter names for a single kernel must be unique.
valueType	Type of parameter values.
valueScript	Python script which will be executed to generate a list of parameter values. The values of the tuning parameters can be utilized by the script. The default thread size can be accessed from script through variable named "defaultSize".
group	Optional group inside which the parameter will be added. Tuning configurations are generated separately for each group. This is useful when kernels contain groups of parameters that can be tuned independently. In this way, the total number of generated configurations can be significantly reduced.

AddScriptConstraint()

void ktt::Tuner::AddScriptConstraint	(	const KernelId	id,
		const std::vector< std::string > &	parameters,
		const std::string &	script
	)

Adds constraint for the specified kernel. Constraints are used to prevent generating of configurations with conflicting combinations of parameter values. This version of constraint addition requires inclusion of Python backend.

Parameters

id	Id of kernel for which the constraint will be added.
parameters	Names of kernel parameters which will be affected by the constraint. Note that constraints can only be added between parameters which belong into the same group. The corresponding parameters must be added to the tuner with AddParameter() before calling this method.
script	Python script which will be executed to evaluate the constraint. The values of the specified parameters can be utilized by the script.

AddScriptParameter()

void ktt::Tuner::AddScriptParameter	(	const KernelId	id,
		const std::string &	name,
		const ParameterValueType	valueType,
		const std::string &	valueScript,
		const std::string &	group = ""
	)

Adds new parameter for the specified kernel, providing parameter name, value type and a script which generates list of allowed values. Parameters will be added to the kernel source code as preprocessor definitions. During the tuning process, tuner will generate configurations for combinations of kernel parameters and their values.

Parameters

id	Id of kernel for which the parameter will be added.
name	Name of a parameter. Parameter names for a single kernel must be unique.
valueType	Type of parameter values.
valueScript	Python script which will be executed to generate a list of parameter values. The values of the tuning parameters can be utilized by the script. The default thread size can be accessed from script through variable named "defaultSize".
group	Optional group inside which the parameter will be added. Tuning configurations are generated separately for each group. This is useful when kernels contain groups of parameters that can be tuned independently. In this way, the total number of generated configurations can be significantly reduced.

AddScriptSeparateCompilerParameter()

void ktt::Tuner::AddScriptSeparateCompilerParameter	(	const KernelId	id,
		const std::string &	name,
		const ParameterValueType	valueType,
		const std::string &	valueScript
	)

Works similarily to AddScriptCompilerParameter(), but for compiler parameters that are tuned separately. For standard tuning, only its first value will be used. Other values can be tuned with TuneOptions.

Parameters

id	Id of kernel for which the parameter will be added.
name	Name of a parameter. Parameter names for a single kernel must be unique.
valueType	Type of parameter values.
valueScript	Python script which will be executed to generate a list of parameter values. The values of the tuning parameters can be utilized by the script. The default thread size can be accessed from script through variable named "defaultSize".

AddScriptThreadModifier()

void void ktt::Tuner::AddScriptThreadModifier	(	const KernelId	id,
		const std::vector< KernelDefinitionId > &	definitionIds,
		const ModifierType	type,
		const ModifierDimension	dimension,
		const std::string &	script
	)

Adds thread modifier function for the specified kernel. Thread modifiers are useful in cases when kernel parameters affect number of required kernel threads. If multiple thread modifiers are specified for the same type and dimension, they are applied in order of their addition. This version of thread modifier requires inclusion of Python backend.

Parameters

id	Id of kernel for which the modifier will be set.
definitionIds	Kernel definitions whose thread sizes will be affected by the thread modifier.
type	Type of the thread modifier. See ModifierType for more information.
dimension	Dimension which will be affected by the modifier. See ModifierDimension for more information.
script	Python script which will be executed to evaluate the constraint. The values of the tuning parameters can be utilized by the script. The default thread size can be accessed from script through variable named "defaultSize".

AddSeparateCompilerParameter()

void ktt::Tuner::AddSeparateCompilerParameter	(	const KernelId	id,
		const std::string &	name,
		const std::vector< std::string > &	values = {}
	)

Works like AddCompilerParameter(), but compiler options added through this function, will be tuned separately (after standard tuning). These compiler optinos can be tuned with TuneOptions() function.

Parameters

id	Id of kernel for which the parameter will be added.
name	Name of a parameter. Parameter names for a single kernel must be unique.
values	Optional allowed values for the parameter. Value type is a string. If left empty, parameter with be either present without any value or completely excluded.

AddThreadModifier() [1/2]

void ktt::Tuner::AddThreadModifier	(	const KernelId	id,
		const std::vector< KernelDefinitionId > &	definitionIds,
		const ModifierType	type,
		const ModifierDimension	dimension,
		const std::string &	parameter,
		const ModifierAction	action
	)

Adds thread modifier function for the specified kernel. This is a simplified version of the thread modifier method which supports only a single kernel parameter and limited number of actions, but is easier to use. If multiple thread modifiers are specified for the same type and dimension, they are applied in order of their addition.

Parameters

id	Id of kernel for which the modifier will be set.
definitionIds	Kernel definitions whose thread sizes will be affected by the thread modifier.
type	Type of the thread modifier. See ModifierType for more information.
dimension	Dimension which will be affected by the thread modifier. See ModifierDimension for more information.
parameter	Name of a kernel parameter whose value will be utilized by the thread modifier. The corresponding parameter must be added to the tuner with AddParameter() before calling this method. Only parameters with the unsigned integer type can be used with thread modifiers.
action	Action of the thread modifier. See ModifierAction for more information.

AddThreadModifier() [2/2]

void ktt::Tuner::AddThreadModifier	(	const KernelId	id,
		const std::vector< KernelDefinitionId > &	definitionIds,
		const ModifierType	type,
		const ModifierDimension	dimension,
		const std::vector< std::string > &	parameters,
		ModifierFunction	function
	)

Adds thread modifier function for the specified kernel. The function receives thread size in the specified dimension and values of the specified kernel parameters as input and returns modified thread size based on these values. Thread modifiers are useful in cases when kernel parameters affect number of required kernel threads. If multiple thread modifiers are specified for the same type and dimension, they are applied in order of their addition.

Parameters

id	Id of kernel for which the modifier will be set.
definitionIds	Kernel definitions whose thread sizes will be affected by the thread modifier.
type	Type of the thread modifier. See ModifierType for more information.
dimension	Dimension which will be affected by the modifier. See ModifierDimension for more information.
parameters	Names of kernel parameters whose values will be passed into the modifier function. The order of parameter names will correspond to the order of parameter values inside the modifier function vector argument. The corresponding parameters must be added to the tuner with AddParameter() before calling this method. Only parameters with the unsigned integer type can be used with thread modifiers.
function	Function which receives thread size in the specified kernel dimension and values of kernel parameters as input and returns modified thread size based on these values.

ClearConfigurationData()

void ktt::Tuner::ClearConfigurationData

(

const KernelId

id

)

Resets searcher and clears generated configurations for the specified kernel.

Parameters

id	Id of kernel whose configuration data will be cleared.

ClearData()

void ktt::Tuner::ClearData

(

const KernelId

id

)

Resets tuning process and clears generated configurations for the specified kernel.

Deprecated:

Use ClearConfigurationData() method instead.

Parameters

id	Id of kernel whose data will be cleared.

CreateCompositeKernel()

KernelId ktt::Tuner::CreateCompositeKernel	(	const std::string &	name,
		const std::vector< KernelDefinitionId > &	definitionIds,
		KernelLauncher	launcher = nullptr
	)

Creates composite kernel from the specified definitions. Note that kernel launcher is required in order to launch kernels with multiple definitions.

Parameters

name	Kernel name used during logging and output operations. The name must be unique.
definitionIds	Ids of kernel definitions which will be utilized by the kernel.
launcher	Launcher for the kernel. It can be defined either during kernel creation or later with SetLauncher() method.

Returns

Id assigned to kernel by the tuner. The id can be used in other API methods.

CreateConfiguration()

KernelConfiguration ktt::Tuner::CreateConfiguration	(	const KernelId	id,
		const ParameterInput &	parameters
	)		const

Creates and returns configuration for the specified kernel based on provided parameters and their values.

Parameters

id	Id of kernel for which the configuration will be created.
parameters	Vector of parameter names and their values from which the configuration is generated. If certain parameters are omitted, their first specified values are added to the configuration.

Returns

Configuration created based on the specified input. See KernelConfiguration for more information.

CreateSimpleKernel()

KernelId ktt::Tuner::CreateSimpleKernel	(	const std::string &	name,
		const KernelDefinitionId	definitionId
	)

Creates simple kernel from the specified definition.

Parameters

name	Kernel name used during logging and output operations. The name must be unique.
definitionId	Id of kernel definition which will be utilized by the kernel.

Returns

Id assigned to kernel by the tuner. The id can be used in other API methods.

GetBestConfiguration()

KernelConfiguration ktt::Tuner::GetBestConfiguration

(

const KernelId

id

)

const

Returns the best configuration found for specified kernel. Valid configuration will be returned only if kernel tuning was already performed for the corresponding kernel (e.g., TuneIteration was called at least once).

Parameters

id	Id of kernel for which the best configuration will be returned.

Returns

Best configuration for the specified kernel. See KernelConfiguration for more information.

GetBestResult()

KernelResult ktt::Tuner::GetBestResult

(

const std::vector< KernelResult > &

results

)

const

Get best kernel result.

Parameters

results

Results which will be searched.

GetConfigurationsCount()

uint64_t ktt::Tuner::GetConfigurationsCount

(

const KernelId

id

)

const

Returns the total number of configurations for specified kernel. Valid number will be returned only if configuration data was already initialized for the corresponding kernel (e.g., InitializeConfigurationData, TuneIteration, Tune was called beforehand).

Parameters

id	Id of kernel for which the total number of configurations will be returned.

Returns

Total number of configurations for specified kernel

GetCurrentDeviceInfo()

DeviceInfo ktt::Tuner::GetCurrentDeviceInfo

(

)

const

Retrieves detailed information about device used by the tuner. See DeviceInfo for more information.

Returns

Information about device used by the tuner.

GetDeviceInfo()

std::vector< DeviceInfo > ktt::Tuner::GetDeviceInfo

(

const PlatformIndex

platform

)

const

Retrieves detailed information about all available devices on the specified platform. See DeviceInfo for more information.

Parameters

platform

Index of platform for which the device information will be retrieved.

Returns

Information about all available devices on the specified platform.

GetKernelDefinitionId()

KernelDefinitionId ktt::Tuner::GetKernelDefinitionId	(	const std::string &	name,
		const std::vector< std::string > &	typeNames = {}
	)		const

Retrieves kernel definition id from the tuner based on provided name and template arguments.

Parameters

name	Name of a kernel definition.
typeNames	Names of types which were used to instantiate kernel template. Only supported in CUDA kernels.

Returns

Id of the corresponding kernel definition. If no such definition exists, InvalidKernelDefinitionId will be returned.

GetKernelDefinitionSource()

std::string ktt::Tuner::GetKernelDefinitionSource	(	const KernelDefinitionId	id,
		const KernelConfiguration &	configuration
	)		const

Returns kernel source with preprocessor definitions for the specified kernel definition based on provided configuration.

Parameters

id	Id of kernel definition for which the source is returned.
configuration	Kernel configuration for which the source will be generated. See KernelConfiguration for more information.

Returns

Kernel definition source with preprocessor definitions for the specified kernel based on provided configuration.

GetKernelSource()

std::string ktt::Tuner::GetKernelSource	(	const KernelId	id,
		const KernelConfiguration &	configuration
	)		const

Returns kernel source with preprocessor definitions for the specified kernel based on provided configuration. Valid source is returned only for kernels with single definition.

Parameters

id	Id of kernel for which the source is returned.
configuration	Kernel configuration for which the source will be generated. See KernelConfiguration for more information.

Returns

Kernel source with preprocessor definitions for the specified kernel based on provided configuration.

GetLoggingLevel()

static LoggingLevel ktt::Tuner::GetLoggingLevel ( )

static

Retrieves logging level currently used by tuner.

Returns

Logging level currently used by tuner. See LoggingLevel for more information.

GetPlatformInfo()

std::vector< PlatformInfo > ktt::Tuner::GetPlatformInfo

(

)

const

Retrieves detailed information about all available platforms. See PlatformInfo for more information.

Returns

Information about all available platforms.

GetProfiling()

bool ktt::Tuner::GetProfiling

(

)

Returns whether profiling is switched on.

Returns

true if KTT is set to collect profiling metrics, false otherwise.

InitializeConfigurationData()

void ktt::Tuner::InitializeConfigurationData

(

const KernelId

id

)

Generates configuration space and initializes searcher for the specified kernel.

Parameters

id	Id of kernel whose configuration data will be initialized.

LoadResults() [1/2]

std::vector< KernelResult > ktt::Tuner::LoadResults	(	const std::string &	filePath,
		const OutputFormat	format
	)		const

Loads kernel results from the specified file. The file must be previously created by the tuner method SaveResults() with corresponding output format.

Parameters

filePath	File from which the results will be loaded. The file extension is added automatically based on the specified format.
format	Format in which the results are stored. See OutputFormat for more information.

Returns

Results loaded from the file.

LoadResults() [2/2]

std::vector< KernelResult > ktt::Tuner::LoadResults	(	const std::string &	filePath,
		const OutputFormat	format,
		UserData &	data
	)		const

Loads kernel results from the specified file. The file must be previously created by the tuner method SaveResults() with corresponding output format.

Parameters

filePath	File from which the results will be loaded. The file extension is added automatically based on the specified format.
format	Format in which the results are stored. See OutputFormat for more information.
data	User data which will be loaded from the file together with results.

Returns

Results loaded from the file.

RemoveArgument()

void ktt::Tuner::RemoveArgument

(

const ArgumentId &

id

)

Removes argument with the specified id from the tuner. Note that argument can only be removed if it is not associated with any kernel definition.

Parameters

id	Id of the argument which will be removed.

RemoveComputeQueue()

void ktt::Tuner::RemoveComputeQueue

(

const QueueId

id

)

Removes the specified compute queue from the tuner. Only queues added by user can be removed.

Parameters

id	Id of compute queue which will be removed.

RemoveKernel()

void ktt::Tuner::RemoveKernel

(

const KernelId

id

)

Removes kernel with the specified id from the tuner. If the kernel is used as a reference kernel, the corresponding kernel argument output validation will be disabled.

Parameters

id	Id of the kernel which will be removed.

RemoveKernelDefinition()

void ktt::Tuner::RemoveKernelDefinition

(

const KernelDefinitionId

id

)

Removes kernel definition with the specified id from the tuner. Note that definition can only be removed if it is not associated with any kernel.

Parameters

id	Id of the kernel definition which will be removed.

Run() [1/2]

KernelResult ktt::Tuner::Run	(	const KernelId	id,
		const KernelConfiguration &	configuration,
		const KernelDimensions &	dimensions,
		const std::vector< BufferOutputDescriptor > &	output
	)

Runs kernel using the specified dimensions and configuration.

Parameters

id	Id of kernel which will be run.
configuration	Configuration under which the kernel will be launched. See KernelConfiguration for more information.
dimensions	Global and local sizes with which the kernel will be launched. If no dimensions are specified for some definition, the sizes specified during its addition will be used.
output	User-provided memory locations for kernel arguments which should be retrieved. See BufferOutputDescriptor for more information.

Returns

Result containing information about kernel computation. See KernelResult for more information.

Run() [2/2]

KernelResult ktt::Tuner::Run	(	const KernelId	id,
		const KernelConfiguration &	configuration,
		const std::vector< BufferOutputDescriptor > &	output
	)

Runs kernel using the specified configuration.

Parameters

id	Id of kernel which will be run.
configuration	Configuration under which the kernel will be launched. See KernelConfiguration for more information.
output	User-provided memory locations for kernel arguments which should be retrieved. See BufferOutputDescriptor for more information.

Returns

Result containing information about kernel computation. See KernelResult for more information.

SaveArgumentVector()

void ktt::Tuner::SaveArgumentVector	(	const ArgumentId &	id,
		const std::string &	filePath
	)

Saves the data of the specified vector argument into raw binary file.

Parameters

id	Id of vector argument that will be saved.
filePath	Path to the file where argument data will be saved.

SaveResults()

void ktt::Tuner::SaveResults	(	const std::vector< KernelResult > &	results,
		const std::string &	filePath,
		const OutputFormat	format,
		const UserData &	data = {}
	)		const

Saves specified kernel results to the specified file.

Parameters

results	Results which will be saved.
filePath	File where the results will be saved. The file extension is added automatically based on the specified format.
format	Format in which the results are saved. See OutputFormat for more information.
data	User data which will be saved into the file together with results.

SetArguments()

void ktt::Tuner::SetArguments	(	const KernelDefinitionId	id,
		const std::vector< ArgumentId > &	argumentIds
	)

Sets arguments for the specified kernel definition.

Parameters

id	Id of a kernel definition for which the arguments will be set.
argumentIds	Ids of arguments to be used by the specified definition. The order of ids must match the order of kernel arguments inside kernel function. The provided ids must be unique.

SetAutomaticGlobalSizeCorrection()

void ktt::Tuner::SetAutomaticGlobalSizeCorrection

(

const bool

flag

)

Toggles automatic correction for kernel global size, which ensures that global size in each dimension is always a multiple of local size in corresponding dimension. Performs a roundup to the nearest higher multiple. Automatic global size correction is disabled by default. Note that automatic global size correction works only if global size type is set to OpenCL.

Parameters

flag	If true, automatic global size correction will be enabled. It will be disabled otherwise.

SetCompiler()

void ktt::Tuner::SetCompiler

(

const std::string &

compiler

)

Sets the compiler executable to use for kernel compilation. This is only supported for the C++ backend. For CUDA, OpenCL, and Vulkan backends, this method will throw an exception since they use built-in compilers. Default compiler for C++ backend is "g++".

Parameters

compiler

Path or name of the compiler executable (e.g., "g++", "clang++", "/usr/bin/clang++").

SetCompilerOptions()

void ktt::Tuner::SetCompilerOptions	(	const std::string &	options,
		const bool	overrideDefault = false
	)

Sets compute API compiler options to specified options. There are no default options for OpenCL backend. By default for CUDA backend, the compiler option "--gpu-architecture=compute_xx" is added, where xx is the compute capability retrieved from the device. For the list of OpenCL compiler options, see: https://www.khronos.org/registry/OpenCL/sdk/1.2/docs/man/xhtml/clBuildProgram.html For the list of CUDA compiler options, see: http://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#nvcc-command-options

Parameters

options	Compute API compiler options. If multiple options are used, they need to be separated by a single space character.
overrideDefault	If false, the default options will be applied in addition to the specified options. If true, no default options will be applied.

SetGlobalSizeType()

void ktt::Tuner::SetGlobalSizeType

(

const GlobalSizeType

type

)

Sets global size specification type to specified compute API style. In OpenCL, NDrange size is specified as number of work-items in a work-group multiplied by number of work-groups. In CUDA, grid size is specified as number of blocks. This method makes it possible to use OpenCL style in CUDA and vice versa. Default global size type is the one corresponding to the compute API used by the tuner.

Parameters

type	Global size type which will be set for tuner. See GlobalSizeType for more information.

SetKernelCacheCapacity()

void ktt::Tuner::SetKernelCacheCapacity

(

const uint64_t

capacity

)

Sets capacity of compiled kernel cache used by the tuner. The cache contains recently compiled kernels which are prepared to be launched immediately, eliminating compilation overhead. Using the cache can significantly improve tuner performance during online tuning or iterative kernel running with custom KernelLauncher. Default cache size is 10.

Parameters

capacity

Controls kernel cache capacity. If zero, kernel cache is completely disabled.

SetLauncher()

void ktt::Tuner::SetLauncher	(	const KernelId	id,
		KernelLauncher	launcher
	)

Specifies kernel launcher for a kernel. Kernel launcher enables customization of kernel execution. This is useful in multiple cases. E.g., running part of the computation in C++ code, utilizing iterative kernel launches or kernels with multiple definitions.

Parameters

id	Id of kernel for which launcher will be set.
launcher	Launcher for the specified kernel. See ComputeInterface for further information.

SetLoggingLevel()

static void ktt::Tuner::SetLoggingLevel ( const LoggingLevel  level )

static

Sets logging level for tuner. Default logging level is info.

Parameters

level

Logging level which will be used by tuner. See LoggingLevel for more information.

SetLoggingTarget() [1/2]

static void ktt::Tuner::SetLoggingTarget ( const std::string &  filePath )

static

Sets the target for info messages logging to specified file. Default logging target is std::clog.

Parameters

filePath

Path to file where tuner info messages will printed.

SetLoggingTarget() [2/2]

static void ktt::Tuner::SetLoggingTarget ( std::ostream &  outputTarget )

static

Sets the target for info messages logging to specified output stream. Default logging target is std::clog.

Parameters

outputTarget

Location where tuner info messages will be printed.

SetProfileBasedSearcher()

void ktt::Tuner::SetProfileBasedSearcher	(	const KernelId	id,
		const std::string &	modelPath,
		const bool	useBuiltinModule = true,
		const uint	batchSize = 5,
		const uint	neighborSize = 100,
		const uint	randomSize = 10
	)

Sets profile-based searcher to be used during kernel tuning. This is special method for profile-based searcher, for other searchers, use SetSearcher.

Parameters

id	Id of kernel for which searcher will be set.
modelPath	Path to a ML model file containing trained model for the tuned kernel.
useBuiltinModule	Toggles usage of built-in profile-based searcher module. If set to false, the built-in module will not be used, making it possible to use externally modified version of module which is useful for debugging.
batchSize	number of configuration from which the fastest one is profiled. Default value also needs to be changed in TuningLoader/Commands/SearcherCommand.cpp
neighborSize	number of neighboring configurations that are used for batch selection. Default value also needs to be changed in TuningLoader/Commands/SearcherCommand.cpp
randomSize	number of random configurations that are used for batch selection. Default value also needs to be changed in TuningLoader/Commands/SearcherCommand.cpp

SetProfiledDefinitions()

void ktt::Tuner::SetProfiledDefinitions	(	const KernelId	id,
		const std::vector< KernelDefinitionId > &	definitionIds
	)

Enables profiling of specified kernel definitions. This is useful if only some definitions inside the kernel need to be profiled. By default, profiling is enabled only for the first definition specified during kernel creation. Note that this method has effect only if kernel profiling functionality is enabled. See SetKernelProfiling() method for more information.

Parameters

id	Id of kernel for which the profiled definitions will be set.
definitionIds	Ids of definitions inside the kernel for which the profiling will be enabled.

SetProfiling()

void ktt::Tuner::SetProfiling

(

const bool

flag

)

Toggles profiling of kernels inside the tuner. Profiled kernel runs generate profiling counters which can be used by searchers and stop conditions for more accurate performance measurement. Profiling counters can also be retrieved through API and saved into a file with kernel results. Note that enabling profiling will result in longer tuning times because profiled kernels have to be launched multiple times with the same configuration in order to collect all profiling counters. Asynchronous kernel launches are not supported when kernel profiling is enabled. Kernel profiling is disabled by default.

Parameters

flag	If true, kernel profiling is enabled. It is disabled otherwise.

SetProfilingCounters()

void ktt::Tuner::SetProfilingCounters

(

const std::vector< std::string > &

counters

)

Specifies profiling counters that will be collected during kernel profiling. Note that not all profiling counters are available on all devices. For the list of old CUDA CUPTI profiling counters, see: https://docs.nvidia.com/cupti/Cupti/r_main.html#metrics-reference For the list of new CUDA CUPTI profiling counters, see: https://docs.nvidia.com/cupti/Cupti/r_main.html#r_host_raw_metrics_api For the list of AMD GPA profiling counters, see: https://gpuperfapi.readthedocs.io/en/latest/counters.html

Parameters

counters

Names of counters that will be collected during kernel profiling.

SetReadOnlyArgumentCache()

void ktt::Tuner::SetReadOnlyArgumentCache

(

const bool

flag

)

Toggles caching of read-only kernel arguments which have management type set to framework. This can significantly speed up tuning, since arguments are uploaded into compute API buffers only once. Caching is enabled by default. Users who wish to modify read-only arguments inside kernel launcher may want to disable this behaviour.

Parameters

flag	If true, read-only argument caching is enabled. It is disabled otherwise.

SetReferenceArgument()

void ktt::Tuner::SetReferenceArgument	(	const ArgumentId &	id,
		const ArgumentId &	referenceId
	)

Sets reference argument for the specified argument. Reference argument data will be compared to tuned kernel output in order to ensure correctness of computation.

Parameters

id	Id of argument for which the reference argument will be set. Only not read-only vector arguments can be validated.
referenceId	Id of the reference argument. Only vector arguments can be set as a reference.

SetReferenceComputation()

void ktt::Tuner::SetReferenceComputation	(	const ArgumentId &	id,
		ReferenceComputation	computation
	)

Sets reference computation for the specified argument. Reference computation output will be compared to tuned kernel output in order to ensure correctness of computation.

Parameters

id	Id of argument for which reference computation will be set. Only not read-only vector arguments can be validated.
computation	Function which receives memory buffer on input where it stores its computed reference result. The size of buffer matches the size of kernel argument in bytes. If a custom validation range was set, the size of buffer matches the specified range.

SetReferenceKernel()

void ktt::Tuner::SetReferenceKernel	(	const ArgumentId &	id,
		const KernelId	referenceId,
		const KernelConfiguration &	configuration,
		const KernelDimensions &	dimensions = {}
	)

Sets reference kernel for the specified argument. Reference kernel output will be compared to tuned kernel output in order to ensure correctness of computation. Reference kernel uses only specified configuration.

Parameters

id	Id of argument for which reference kernel will be set. Only not read-only vector arguments can be validated.
referenceId	Id of reference kernel.
configuration	Configuration under which the reference kernel will be launched to produce reference output. This is useful if the kernel has a configuration which is known to produce correct results.
dimensions	Global and local sizes with which the reference kernel will be launched. If no dimensions are specified for some definition, the sizes specified during its addition will be used.

SetSearcher()

void ktt::Tuner::SetSearcher	(	const KernelId	id,
		std::unique_ptr< Searcher >	searcher
	)

Sets searcher which will be used during kernel tuning. If no searcher is specified, DeterministicSearcher will be used.

Parameters

id	Id of kernel for which searcher will be set.
searcher	Searcher which decides which kernel configuration will be launched next. See Searcher for more information.

SetTimeUnit()

static void ktt::Tuner::SetTimeUnit ( const TimeUnit  unit )

static

Sets time unit used for printing of results. Default time unit is milliseconds.

Parameters

unit	Time unit which will be used for printing of results. See TimeUnit for more information.

SetValidationMethod()

void ktt::Tuner::SetValidationMethod	(	const ValidationMethod	method,
		const double	toleranceThreshold
	)

Sets validation method and tolerance threshold for floating-point argument validation. Default validation method is side by side comparison. Default tolerance threshold is 1e-4.

Parameters

method	Validation method which will be used for floating-point argument validation. See ValidationMethod for more information.
toleranceThreshold	Output validation threshold. If difference between tuned kernel output and reference output is within the threshold, the tuned kernel output will be considered correct.

SetValidationMode()

void ktt::Tuner::SetValidationMode

(

const ValidationMode

mode

)

Sets mode under which kernel output validation is enabled. By default, output validation is enabled only during kernel tuning.

Parameters

mode	Bitfield of modes under which kernel output validation is enabled. See ValidationMode for more information.

SetValidationRange()

void ktt::Tuner::SetValidationRange	(	const ArgumentId &	id,
		const size_t	range
	)

Sets validation range for the specified argument. The entire argument is validated by default.

Parameters

id	Id of argument for which the validation range will be set. Only not read-only vector arguments can be validated.
range	Number of argument elements which will be validated, starting from the first element.

SetValueComparator()

void ktt::Tuner::SetValueComparator	(	const ArgumentId &	id,
		ValueComparator	comparator
	)

Sets value comparator for the specified kernel argument. Arguments with custom data type cannot be compared using built-in comparison operators and require user to provide a comparator. Comparator can also be optionally added for arguments with built-in data types.

Parameters

id	Id of argument for which the comparator will be set. Only not read-only vector arguments can be validated.
comparator	Function which receives two elements with data type matching the type of specified kernel argument and returns true if the elements are equal. Returns false otherwise.

SimulateKernelTuning()

std::vector< KernelResult > ktt::Tuner::SimulateKernelTuning	(	const KernelId	id,
		const std::vector< KernelResult > &	results,
		const uint64_t	iterations = 0
	)

Performs simulated tuning process for the specified kernel. The kernel is not tuned, execution times are read from the provided results. Creates configuration space based on combinations of provided kernel parameters and constraints. The configurations will be launched in order that depends on specified Searcher. This method can be used to test behaviour and performance of newly implemented searchers. The provided results should correspond to the results output by the same kernel during regular tuning.

Deprecated:

Use SimulateTuning() method instead.

Parameters

id	Id of the kernel for simulated tuning.
results	Results from which the kernel execution times will be retrieved.
iterations	Number of iterations performed. If equal to 0, search of the entire tuning space is performed.

Returns

Vector of results for configurations chosen by the searcher during simulated tuning.

SimulateTuning()

std::vector< KernelResult > ktt::Tuner::SimulateTuning	(	const KernelId	id,
		const std::vector< KernelResult > &	results,
		std::unique_ptr< StopCondition >	stopCondition = nullptr
	)

Performs simulated tuning process for the specified kernel. The kernel is not tuned, execution times are read from the provided results. Creates configuration space based on combinations of provided kernel parameters and constraints. The configurations will be launched in order that depends on specified Searcher. This method can be used to test behaviour and performance of newly implemented searchers. The provided results should correspond to the results that were created by the same kernel during regular tuning.

Parameters

id	Id of the kernel for simulated tuning.
results	Results from which the kernel execution times will be retrieved.
stopCondition	Condition which decides whether to continue the tuning process. If no condition is provided, simulated tuning will end when all configurations are explored. See StopCondition for more information.

Returns

Vector of results for configurations chosen by the searcher during simulated tuning.

Synchronize()

void ktt::Tuner::Synchronize

(

)

Blocks until all commands submitted to KTT device are completed.

Deprecated:

Use SynchronizeDevice() or SynchronizeQueues() method instead.

SynchronizeDevice()

void ktt::Tuner::SynchronizeDevice

(

)

Blocks until all commands submitted to KTT device are completed.

SynchronizeQueue()

void ktt::Tuner::SynchronizeQueue

(

const QueueId

id

)

Blocks until all commands submitted to the specified KTT device queue are completed.

Parameters

id	Id of queue which will be synchronized.

SynchronizeQueues()

void ktt::Tuner::SynchronizeQueues

(

)

Blocks until all commands submitted to all KTT device queues are completed.

Tune() [1/2]

std::vector< KernelResult > ktt::Tuner::Tune	(	const KernelId	id,
		const KernelDimensions &	dimensions,
		std::unique_ptr< StopCondition >	stopCondition = nullptr,
		const std::optional< PreciseMeasurementParameters > &	preciseParams = std::nullopt
	)

Performs the tuning process for specified kernel. Creates configuration space based on combinations of provided kernel parameters and constraints. The configurations will be launched in order that depends on the specified Searcher. Tuning will end either when all configurations are explored or when the specified stop condition is fulfilled.

Parameters

id	Id of the tuned kernel.
dimensions	Global and local sizes with which the kernel will be launched. If no dimensions are specified for some definition, the sizes specified during its addition will be used.
stopCondition	Condition which decides whether to continue the tuning process. If no condition is provided, tuning will end when all configurations are explored. See StopCondition for more information.
preciseParams	Optional parameters for precise measurement. If not provided, kernel is executed once per configuration. If provided, each configuration is executed multiple times for more stable timing data. When KTT is built with power measurement support (–power-usage, CUDA with NVML only), also collects power readings until they stabilize.

Returns

Vector of results containing information about kernel computation in specific configuration. See KernelResult for more information.

Tune() [2/2]

std::vector< KernelResult > ktt::Tuner::Tune	(	const KernelId	id,
		std::unique_ptr< StopCondition >	stopCondition = nullptr,
		const std::optional< PreciseMeasurementParameters > &	preciseParams = std::nullopt
	)

Performs the tuning process for specified kernel. Creates configuration space based on combinations of provided kernel parameters and constraints. The configurations will be launched in order that depends on the specified Searcher. Tuning will end either when all configurations are explored or when the specified stop condition is fulfilled.

Parameters

id	Id of the tuned kernel.
stopCondition	Condition which decides whether to continue the tuning process. If no condition is provided, tuning will end when all configurations are explored. See StopCondition for more information.
preciseParams	Optional parameters for precise measurement. If not provided, kernel is executed once per configuration. If provided, each configuration is executed multiple times for more stable timing data. When KTT is built with power measurement support (–power-usage, CUDA with NVML only), also collects power readings until they stabilize.

Returns

Vector of results containing information about kernel computation in specific configuration. See KernelResult for more information.

TuneIteration() [1/2]

KernelResult ktt::Tuner::TuneIteration	(	const KernelId	id,
		const KernelDimensions &	dimensions,
		const std::vector< BufferOutputDescriptor > &	output,
		const bool	recomputeReference = false,
		const std::optional< PreciseMeasurementParameters > &	preciseParams = std::nullopt
	)

Performs one step of the tuning process for specified kernel. When this method is called for the kernel for the first time, it creates configuration space based on combinations of provided kernel parameters and constraints. Each time this method is called, it launches a single kernel configuration. If all configurations were already launched, it runs kernel using the best configuration. Output data can be retrieved by providing output descriptors. Allows control over recomputation of reference output.

Parameters

id	Id of the tuned kernel.
dimensions	Global and local sizes with which the kernel will be launched. If no dimensions are specified for some definition, the sizes specified during its addition will be used.
output	User-provided memory locations for kernel arguments which should be retrieved. See BufferOutputDescriptor for more information.
recomputeReference	Flag which controls whether recomputation of reference output should be performed or not. Useful if kernel data between individual method invocations change.
preciseParams	Optional parameters for precise measurement. If not provided, kernel is executed once per configuration. If provided, each configuration is executed multiple times for more stable timing data. When KTT is built with power measurement support (–power-usage, CUDA with NVML only), also collects power readings until they stabilize.

Returns

Result containing information about kernel computation in specific configuration. See KernelResult for more information.

TuneIteration() [2/2]

KernelResult ktt::Tuner::TuneIteration	(	const KernelId	id,
		const std::vector< BufferOutputDescriptor > &	output,
		const bool	recomputeReference = false,
		const std::optional< PreciseMeasurementParameters > &	preciseParams = std::nullopt
	)

Performs one step of the tuning process for specified kernel. When this method is called for the kernel for the first time, it creates configuration space based on combinations of provided kernel parameters and constraints. Each time this method is called, it launches a single kernel configuration. If all configurations were already launched, it runs kernel using the best configuration. Output data can be retrieved by providing output descriptors. Allows control over recomputation of reference output.

Parameters

id	Id of the tuned kernel.
output	User-provided memory locations for kernel arguments which should be retrieved. See BufferOutputDescriptor for more information.
recomputeReference	Flag which controls whether recomputation of reference output should be performed or not. Useful if kernel data between individual method invocations change.
preciseParams	Optional parameters for precise measurement. If not provided, kernel is executed once per configuration. If provided, each configuration is executed multiple times for more stable timing data. When KTT is built with power measurement support (–power-usage, CUDA with NVML only), also collects power readings until they stabilize.

Returns

Result containing information about kernel computation in specific configuration. See KernelResult for more information.

TuneOptions() [1/2]

std::vector< KernelResult > ktt::Tuner::TuneOptions	(	const KernelId	id,
		const KernelConfiguration &	baseConfiguration,
		const KernelDimensions &	dimensions,
		std::unique_ptr< StopCondition >	stopCondition = nullptr,
		const std::optional< PreciseMeasurementParameters > &	preciseParams = std::nullopt
	)

Works simiraliry to Tune(), but is used for tuning compiler options separately. These options can be added through function AddSeparateCompilerParameter().

Parameters

id	Id of the tuned kernel.
baseConfiguration	Configuration on top of which compiler options will be tuned.
dimensions	Global and local sizes with which the kernel will be launched. If no dimensions are specified for some definition, the sizes specified during its addition will be used.
stopCondition	Condition which decides whether to continue the tuning process. If no condition is provided, tuning will end when all configurations are explored. See StopCondition for more information.
preciseParams	Optional parameters for precise measurement. If not provided, kernel is executed once per configuration. If provided, each configuration is executed multiple times for more stable timing data. When KTT is built with power measurement support (–power-usage, CUDA with NVML only), also collects power readings until they stabilize.

Returns

Vector of results containing information about kernel computation in specific configuration. See KernelResult for more information.

TuneOptions() [2/2]

std::vector< KernelResult > ktt::Tuner::TuneOptions	(	const KernelId	id,
		const KernelConfiguration &	baseConfiguration,
		std::unique_ptr< StopCondition >	stopCondition = nullptr,
		const std::optional< PreciseMeasurementParameters > &	preciseParams = std::nullopt
	)

Works simiraliry to Tune(), but is used for tuning compiler options separately. These options can be added through function AddSeparateCompilerParameter().

Parameters

id	Id of the tuned kernel.
baseConfiguration	Configuration on top of which compiler options will be tuned.
stopCondition	Condition which decides whether to continue the tuning process. If no condition is provided, tuning will end when all configurations are explored. See StopCondition for more information.
preciseParams	Optional parameters for precise measurement. If not provided, kernel is executed once per configuration. If provided, each configuration is executed multiple times for more stable timing data. When KTT is built with power measurement support (–power-usage, CUDA with NVML only), also collects power readings until they stabilize.

Returns

Vector of results containing information about kernel computation in specific configuration. See KernelResult for more information.

WaitForComputeAction()

void ktt::Tuner::WaitForComputeAction

(

const ComputeActionId

id

)

Blocks until the specified compute action is finished.

Parameters

id	Id of compute action to wait for.

WaitForTransferAction()

void ktt::Tuner::WaitForTransferAction

(

const TransferActionId

id

)

Blocks until the specified buffer transfer action is finished.

Parameters

id	Id of transfer action to wait for.

---

The documentation for this class was generated from the following file:

• Source/Tuner.h