Tuner.h

Go to the documentation of this file.

 
#pragma once
 
#include <memory>
#include <optional>
#include <ostream>
#include <string>
#include <vector>
 
// Compatibility for multiple platforms
#include <KttPlatform.h>
 
// Data types and enums
#include <ComputeEngine/ComputeApi.h>
#include <ComputeEngine/GlobalSizeType.h>
#include <Kernel/ModifierAction.h>
#include <Kernel/ModifierDimension.h>
#include <Kernel/ModifierType.h>
#include <KernelArgument/ArgumentAccessType.h>
#include <KernelArgument/ArgumentDataType.h>
#include <KernelArgument/ArgumentManagementType.h>
#include <KernelArgument/ArgumentMemoryLocation.h>
#include <KernelArgument/ArgumentMemoryType.h>
#include <KernelRunner/ValidationMethod.h>
#include <KernelRunner/ValidationMode.h>
#include <Output/TimeConfiguration/TimeUnit.h>
#include <Output/OutputFormat.h>
#include <Utility/Logger/LoggingLevel.h>
#include <KttTypes.h>
#include <Api/Configuration/PreciseMeasurementParameters.h>
 
// Data holders
#include <Api/Configuration/DimensionVector.h>
#include <Api/Configuration/KernelConfiguration.h>
#include <Api/Info/DeviceInfo.h>
#include <Api/Info/PlatformInfo.h>
#include <Api/Output/BufferOutputDescriptor.h>
#include <Api/Output/KernelResult.h>
 
// Tuner customization
#include <Api/Searcher/Searcher.h>
#include <Api/StopCondition/StopCondition.h>
#include <Api/ComputeApiInitializer.h>
 
// Half floating-point data type support
#include <Utility/External/half.hpp>
 
namespace ktt
{
 
class TunerCore;
 
class KTT_API Tuner
{
public:
    explicit Tuner(const PlatformIndex platform, const DeviceIndex device, const ComputeApi api);
 
    explicit Tuner(const PlatformIndex platform, const DeviceIndex device, const ComputeApi api, const uint32_t computeQueueCount);
 
    explicit Tuner(const ComputeApi api, const ComputeApiInitializer& initializer);
 
    explicit 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);
 
    [[deprecated("Use SimulateTuning() method instead.")]] 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);
 
    [[deprecated("Use ClearConfigurationData() method instead.")]] 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;
 
    static void SetTimeUnit(const TimeUnit unit);
 
    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();
 
    [[deprecated("Use SynchronizeDevice() or SynchronizeQueues() method instead.")]] 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 void SetLoggingLevel(const LoggingLevel level);
 
    static LoggingLevel GetLoggingLevel();
 
    static void SetLoggingTarget(std::ostream& outputTarget);
 
    static void SetLoggingTarget(const std::string& filePath);
 
private:
    std::unique_ptr<TunerCore> m_Tuner;
 
    KTT_VIRTUAL_API ArgumentId AddArgumentWithReferencedData(const size_t elementSize, const ArgumentDataType dataType,
        const ArgumentMemoryLocation memoryLocation, const ArgumentAccessType accessType, const ArgumentMemoryType memoryType,
        const ArgumentManagementType managementType, void* data, const size_t dataSize, const ArgumentId& customId = "");
    KTT_VIRTUAL_API ArgumentId AddArgumentWithOwnedData(const size_t elementSize, const ArgumentDataType dataType,
        const ArgumentMemoryLocation memoryLocation, const ArgumentAccessType accessType, const ArgumentMemoryType memoryType,
        const ArgumentManagementType managementType, const void* data, const size_t dataSize, const ArgumentId& customId = "",
        const std::string& symbolName = "");
    KTT_VIRTUAL_API ArgumentId AddUserArgument(ComputeBuffer buffer, const size_t elementSize, const ArgumentDataType dataType,
        const ArgumentMemoryLocation memoryLocation, const ArgumentAccessType accessType, const size_t dataSize,
        const ArgumentId& customId = "");
    KTT_VIRTUAL_API void AddParameterInternal(const KernelId id, const std::string& name, const std::vector<ParameterValue>& values,
        const std::string& group, const bool isCompilerParameter);
 
    template <typename T>
    ArgumentDataType DeriveArgumentDataType() const;
};
 
} // namespace ktt
 
#include <Tuner.inl>