diff --git a/python/src/main.cpp b/python/src/main.cpp index 3cc3e214e..34a0e6bbc 100644 --- a/python/src/main.cpp +++ b/python/src/main.cpp @@ -7,109 +7,150 @@ namespace py = pybind11; PYBIND11_MODULE(komputepy, m) { - py::enum_(m, "TensorTypes") - .value("device", kp::Tensor::TensorTypes::eDevice) - .value("staging", kp::Tensor::TensorTypes::eStaging) - .value("storage", kp::Tensor::TensorTypes::eStorage) + py::enum_(m, "TensorTypes", "Enum with GPU memory types for Tensor.") + .value("device", kp::Tensor::TensorTypes::eDevice, "Tensor holding data in GPU memory.") + .value("staging", kp::Tensor::TensorTypes::eStaging, "Tensor used for transfer of data to device.") + .value("storage", kp::Tensor::TensorTypes::eStorage, "Tensor with host visible gpu memory.") .export_values(); - py::class_>(m, "Tensor") + py::class_>(m, "Tensor", "Structured data used in GPU operations.") .def(py::init( [](const std::vector& data) { return std::unique_ptr(new kp::Tensor(data)); - })) + }), "Initialiser with only list of data components.") .def(py::init( [](const std::vector& data, kp::Tensor::TensorTypes tensorTypes) { return std::unique_ptr(new kp::Tensor(data, tensorTypes)); - })) - .def("data", &kp::Tensor::data) - .def("size", &kp::Tensor::size) - .def("tensor_type", &kp::Tensor::tensorType) - .def("is_init", &kp::Tensor::isInit) - .def("set_data", &kp::Tensor::setData) - .def("map_data_from_host", &kp::Tensor::mapDataFromHostMemory) - .def("map_data_into_host", &kp::Tensor::mapDataIntoHostMemory); + }), "Initialiser with list of data components and tensor GPU memory type.") + .def("data", &kp::Tensor::data, "Retrieves the data as a list containing the local Tensor memory data.") + .def("size", &kp::Tensor::size, "Retrieves the size of the Tensor data as per the local Tensor memory.") + .def("tensor_type", &kp::Tensor::tensorType, "Retreves the memory type of the tensor.") + .def("is_init", &kp::Tensor::isInit, "Checks whether the tensor GPU memory has been initialised.") + .def("set_data", &kp::Tensor::setData, "Overrides the data in the local Tensor memory.") + .def("map_data_from_host", &kp::Tensor::mapDataFromHostMemory, "Maps data into GPU memory from tensor local data.") + .def("map_data_into_host", &kp::Tensor::mapDataIntoHostMemory, "Maps data from GPU memory into tensor local data."); py::class_>(m, "Sequence") - .def("init", &kp::Sequence::init) + .def("init", &kp::Sequence::init, "Initialises Vulkan resources within sequence using provided device.") // record - .def("begin", &kp::Sequence::begin) - .def("end", &kp::Sequence::end) + .def("begin", &kp::Sequence::begin, "Clears previous commands and starts recording commands in sequence which can be run in batch.") + .def("end", &kp::Sequence::end, "Stops listening and recording for new commands.") // eval - .def("eval", &kp::Sequence::eval) - .def("eval_async", &kp::Sequence::evalAsync) - .def("eval_await", &kp::Sequence::evalAwait) + .def("eval", &kp::Sequence::eval, "Executes the currently recorded commands synchronously by waiting on Vulkan Fence.") + .def("eval_async", &kp::Sequence::evalAsync, "Executes the currently recorded commands asynchronously.") + .def("eval_await", &kp::Sequence::evalAwait, "Waits until the execution finishes using Vulkan Fence.") // status - .def("is_running", &kp::Sequence::isRunning) - .def("is_rec", &kp::Sequence::isRecording) - .def("is_init", &kp::Sequence::isInit) + .def("is_running", &kp::Sequence::isRunning, "Checks whether the Sequence operations are currently still executing.") + .def("is_rec", &kp::Sequence::isRecording, "Checks whether the Sequence is currently in recording mode.") + .def("is_init", &kp::Sequence::isInit, "Checks if the Sequence has been initialized") // record - .def("record_tensor_create", &kp::Sequence::record) - .def("record_tensor_copy", &kp::Sequence::record) - .def("record_tensor_sync_device", &kp::Sequence::record) - .def("record_tensor_sync_local", &kp::Sequence::record) - .def("record_algo_mult", &kp::Sequence::record) - .def("record_algo_file", &kp::Sequence::record) - .def("record_algo_data", &kp::Sequence::record>) - .def("record_algo_lro", &kp::Sequence::record); + .def("record_tensor_create", &kp::Sequence::record, + "Records operation to create and initialise tensor GPU memory and buffer") + .def("record_tensor_copy", &kp::Sequence::record, + "Records operation to copy one tensor to one or many tensors") + .def("record_tensor_sync_device", &kp::Sequence::record, + "Records operation to sync tensor from local memory to GPU memory") + .def("record_tensor_sync_local", &kp::Sequence::record, + "Records operation to sync tensor(s) from GPU memory to local memory using staging tensors") + .def("record_algo_mult", &kp::Sequence::record, + "Records operation to run multiplication compute shader to two input tensors and an output tensor") + .def("record_algo_file", &kp::Sequence::record, + "Records an operation using a custom shader provided from a shader path") + .def("record_algo_data", &kp::Sequence::record>, + "Records an operation using a custom shader provided as raw string or spirv bytes") + .def("record_algo_lro", &kp::Sequence::record, + "Records operation to run left right out operation with custom shader"); py::class_(m, "Manager") - .def(py::init()) + .def(py::init(), "Default initializer uses device 0 and first compute compatible GPU queueFamily") .def(py::init( [](uint32_t physicalDeviceIndex) { return std::unique_ptr(new kp::Manager(physicalDeviceIndex)); - })) + }), "Manager initialiser can provide specified device index but will use first compute compatible GPU queueFamily") .def(py::init( [](uint32_t physicalDeviceIndex, const std::vector& familyQueueIndices) { return std::unique_ptr(new kp::Manager(physicalDeviceIndex, familyQueueIndices)); - })) - .def("get_create_sequence", &kp::Manager::getOrCreateManagedSequence) + }), "Manager initialiser can provide specified device and array of GPU queueFamilies to load.") + .def("get_create_sequence", &kp::Manager::getOrCreateManagedSequence, "Get a Sequence or create a new one with given name") .def("create_sequence", &kp::Manager::createManagedSequence, - py::arg("name"), py::arg("queueIndex") = 0) + py::arg("name"), py::arg("queueIndex") = 0, "Create a sequence with specific name and specified index of available queues") .def("build_tensor", &kp::Manager::buildTensor, - py::arg("data"), py::arg("tensorType") = kp::Tensor::TensorTypes::eDevice) + py::arg("data"), py::arg("tensorType") = kp::Tensor::TensorTypes::eDevice, + "Build and initialise tensor") // Await functions .def("eval_await", &kp::Manager::evalOpAwait, - py::arg("sequenceName"), py::arg("waitFor") = UINT64_MAX) + py::arg("sequenceName"), py::arg("waitFor") = UINT64_MAX, + "Awaits for asynchronous operation on a named Sequence") .def("eval_await_def", &kp::Manager::evalOpAwaitDefault, - py::arg("waitFor") = UINT64_MAX) + py::arg("waitFor") = UINT64_MAX, "Awaits for asynchronous operation on the last anonymous Sequence created") // eval default - .def("eval_tensor_create_def", &kp::Manager::evalOpDefault) - .def("eval_tensor_copy_def", &kp::Manager::evalOpDefault) - .def("eval_tensor_sync_device_def", &kp::Manager::evalOpDefault) - .def("eval_tensor_sync_local_def", &kp::Manager::evalOpDefault) - .def("eval_algo_mult_def", &kp::Manager::evalOpDefault) - .def("eval_algo_file_def", &kp::Manager::evalOpDefault) - .def("eval_algo_data_def", &kp::Manager::evalOpDefault>) - .def("eval_algo_lro_def", &kp::Manager::evalOpDefault) + .def("eval_tensor_create_def", &kp::Manager::evalOpDefault, + "Evaluates operation to create and initialise tensor GPU memory and buffer with new anonymous Sequence") + .def("eval_tensor_copy_def", &kp::Manager::evalOpDefault, + "Evaluates operation to copy one tensor to one or many tensors with new anonymous Sequence") + .def("eval_tensor_sync_device_def", &kp::Manager::evalOpDefault, + "Evaluates operation to sync tensor from local memory to GPU memory with new anonymous Sequence") + .def("eval_tensor_sync_local_def", &kp::Manager::evalOpDefault, + "Evaluates operation to sync tensor(s) from GPU memory to local memory using staging tensors with new anonymous Sequence") + .def("eval_algo_mult_def", &kp::Manager::evalOpDefault, + "Evaluates operation to run multiplication compute shader to two input tensors and an output tensor with new anonymous Sequence") + .def("eval_algo_file_def", &kp::Manager::evalOpDefault, + "Evaluates an operation using a custom shader provided from a shader path with new anonymous Sequence") + .def("eval_algo_data_def", &kp::Manager::evalOpDefault>, + "Evaluates an operation using a custom shader provided as raw string or spirv bytes with new anonymous Sequence") + .def("eval_algo_lro_def", &kp::Manager::evalOpDefault, + "Evaluates operation to run left right out operation with custom shader with new anonymous Sequence") // eval - .def("eval_tensor_create", &kp::Manager::evalOp) - .def("eval_tensor_copy", &kp::Manager::evalOp) - .def("eval_tensor_sync_device", &kp::Manager::evalOp) - .def("eval_tensor_sync_local", &kp::Manager::evalOp) - .def("eval_algo_mult", &kp::Manager::evalOp) - .def("eval_algo_file", &kp::Manager::evalOp) - .def("eval_algo_data", &kp::Manager::evalOp>) - .def("eval_algo_lro", &kp::Manager::evalOp) + .def("eval_tensor_create", &kp::Manager::evalOp, + "Evaluates operation to create and initialise tensor GPU memory and buffer with explicitly named Sequence") + .def("eval_tensor_copy", &kp::Manager::evalOp, + "Evaluates operation to copy one tensor to one or many tensors with explicitly named Sequence") + .def("eval_tensor_sync_device", &kp::Manager::evalOp, + "Evaluates operation to sync tensor from local memory to GPU memory with explicitly named Sequence") + .def("eval_tensor_sync_local", &kp::Manager::evalOp, + "Evaluates operation to sync tensor(s) from GPU memory to local memory using staging tensors with explicitly named Sequence") + .def("eval_algo_mult", &kp::Manager::evalOp, + "Evaluates operation to run multiplication compute shader to two input tensors and an output tensor with explicitly named Sequence") + .def("eval_algo_file", &kp::Manager::evalOp, + "Evaluates an operation using a custom shader provided from a shader path with explicitly named Sequence") + .def("eval_algo_data", &kp::Manager::evalOp>, + "Evaluates an operation using a custom shader provided as raw string or spirv bytes with explicitly named Sequence") + .def("eval_algo_lro", &kp::Manager::evalOp, + "Evaluates operation to run left right out operation with custom shader with explicitly named Sequence") // eval async default - .def("eval_async_tensor_create_def", &kp::Manager::evalOpAsyncDefault) - .def("eval_async_tensor_copy_def", &kp::Manager::evalOpAsyncDefault) - .def("eval_async_tensor_sync_device_def", &kp::Manager::evalOpAsyncDefault) - .def("eval_async_tensor_sync_local_def", &kp::Manager::evalOpAsyncDefault) - .def("eval_async_algo_mult_def", &kp::Manager::evalOpAsyncDefault) - .def("eval_async_algo_file_def", &kp::Manager::evalOpAsyncDefault) - .def("eval_async_algo_data_def", &kp::Manager::evalOpAsyncDefault>) - .def("eval_async_algo_lro_def", &kp::Manager::evalOpAsyncDefault) + .def("eval_async_tensor_create_def", &kp::Manager::evalOpAsyncDefault, + "Evaluates asynchronously operation to create and initialise tensor GPU memory and buffer with anonymous Sequence") + .def("eval_async_tensor_copy_def", &kp::Manager::evalOpAsyncDefault, + "Evaluates asynchronously operation to copy one tensor to one or many tensors with anonymous Sequence") + .def("eval_async_tensor_sync_device_def", &kp::Manager::evalOpAsyncDefault, + "Evaluates asynchronously operation to sync tensor from local memory to GPU memory with anonymous Sequence") + .def("eval_async_tensor_sync_local_def", &kp::Manager::evalOpAsyncDefault, + "Evaluates asynchronously operation to sync tensor(s) from GPU memory to local memory using staging tensors with anonymous Sequence") + .def("eval_async_algo_mult_def", &kp::Manager::evalOpAsyncDefault, + "Evaluates asynchronously operation to run multiplication compute shader to two input tensors and an output tensor with anonymous Sequence") + .def("eval_async_algo_file_def", &kp::Manager::evalOpAsyncDefault, + "Evaluates asynchronously an operation using a custom shader provided from a shader path with anonymous Sequence") + .def("eval_async_algo_data_def", &kp::Manager::evalOpAsyncDefault>, + "Evaluates asynchronously an operation using a custom shader provided as raw string or spirv bytes with anonymous Sequence") + .def("eval_async_algo_lro_def", &kp::Manager::evalOpAsyncDefault, + "Evaluates asynchronously operation to run left right out operation with custom shader with anonymous Sequence") // eval async - .def("eval_tensor_create", &kp::Manager::evalOpAsync) - .def("eval_tensor_copy", &kp::Manager::evalOpAsync) - .def("eval_tensor_sync_device", &kp::Manager::evalOpAsync) - .def("eval_tensor_sync_local", &kp::Manager::evalOpAsync) - .def("eval_algo_mult", &kp::Manager::evalOpAsync) - .def("eval_algo_file", &kp::Manager::evalOpAsync) - .def("eval_algo_data", &kp::Manager::evalOpAsync>) - .def("eval_algo_lro", &kp::Manager::evalOpAsync); - + .def("eval_async_tensor_create", &kp::Manager::evalOpAsync, + "Evaluates asynchronously operation to create and initialise tensor GPU memory and buffer with explicitly named Sequence") + .def("eval_async_tensor_copy", &kp::Manager::evalOpAsync, + "Evaluates asynchronously operation to copy one tensor to one or many tensors with explicitly named Sequence") + .def("eval_async_tensor_sync_device", &kp::Manager::evalOpAsync, + "Evaluates asynchronously operation to sync tensor from local memory to GPU memory with explicitly named Sequence") + .def("eval_async_tensor_sync_local", &kp::Manager::evalOpAsync, + "Evaluates asynchronously operation to sync tensor(s) from GPU memory to local memory using staging tensors with explicitly named Sequence") + .def("eval_async_algo_mult", &kp::Manager::evalOpAsync, + "Evaluates asynchronously operation to run multiplication compute shader to two input tensors and an output tensor with explicitly named Sequence") + .def("eval_async_algo_file", &kp::Manager::evalOpAsync, + "Evaluates asynchronously an operation using a custom shader provided from a shader path with explicitly named Sequence") + .def("eval_async_algo_data", &kp::Manager::evalOpAsync>, + "Evaluates asynchronously an operation using a custom shader provided as raw string or spirv bytes with explicitly named Sequence") + .def("eval_async_algo_lro", &kp::Manager::evalOpAsync, + "Evaluates asynchronously operation to run left right out operation with custom shader with explicitly named Sequence"); #ifdef VERSION_INFO m.attr("__version__") = VERSION_INFO;