From 958bf3f3c97a57a88cc648e47e93d05fc2a2ff96 Mon Sep 17 00:00:00 2001 From: Alejandro Saucedo Date: Tue, 3 Nov 2020 08:00:38 +0000 Subject: [PATCH] Added python overview to documentation --- docs/index.rst | 3 +- docs/overview/python-package.rst | 101 +++++++++++++++++++++-------- docs/overview/python-reference.rst | 44 +++++++++++++ 3 files changed, 120 insertions(+), 28 deletions(-) create mode 100644 docs/overview/python-reference.rst diff --git a/docs/index.rst b/docs/index.rst index 57f1a12..340b345 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,13 +12,14 @@ Index :titlesonly: Simple & Advanced Examples + Python Package Overview Asynchronous & Parallel Operations Memory Management Principles Build System Deep Dive Converting GLSL/HLSL Shaders to C++ Headers Mobile App Integration (Android) Game Engine Integration (Godot Engine) - Python Class Documentation & Reference + Python Class Documentation & Reference C++ Class Documentation & Reference Code Index diff --git a/docs/overview/python-package.rst b/docs/overview/python-package.rst index 0a8eb7a..74e0cba 100644 --- a/docs/overview/python-package.rst +++ b/docs/overview/python-package.rst @@ -1,44 +1,91 @@ - -Python Class Documentation & Reference +Python Package Overview ======== -This section provides a breakdown of the Python classes and what each of their functions provide. +This section provides an overview of the Python Package from a functionality perspective. If you wish to see all the classes and their respective functions you can find that in the `Python Class Reference Section `_. + Below is a diagram that provides insights on the relationship between Vulkan Kompute objects and Vulkan resources, which primarily encompass ownership of either CPU and/or GPU memory. .. image:: ../images/kompute-architecture.jpg :width: 70% -Manager -------- +Python Components +^^^^^^^^ -The Kompute Manager provides a high level interface to simplify interaction with underlying :class:`kp.Sequence` of Operations. +The Python package exposes three main classes: -.. autoclass:: kp.Manager - :members: +* :class:`kp.Manager` - Manages all high level Vulkan and Kompute resources created +* :class:`kp.Sequence` - Contains a set of recorded operations that can be reused +* :class:`kp.Tensor` - Core data component to manage GPU and host data used in operations + +One thing that you will notice is that the class :class:`kp::OpBase` and all its relevant operator subclasses are not exposed in Python. + +This is primarily because the way to interact with the operations are through the respective :class:`kp.Manager` and :class:`kp.Sequence` functions. + +More specifically, it can be through the following functions: + +* mgr.eval_ - Runs operation under an existing named sequence +* mgr.eval__def - Runs operation under a new anonymous sequence +* mgr.eval_async_ - Runs operation asynchronously under an existing named sequence +* mgr.eval_async__def - Runs operation asynchronously under a new anonymous sequence +* seq.record_ - Records operation in sequence (requires sequence to be in recording mode) + +You can see these operations being used in the `Simple Python example `_ and in the `Extended Python Example `_. + +Kompute Operation Capabilities +^^^^^ + +Handling multiple capabilites of processing can be done by compute shaders being loaded into separate sequences. The example below shows how this can be done: + +.. code-block:: python + :linenos: + from kp import Manager + + # We'll assume we have the shader data available + from my_spv_shader_data import mult_shader, sum_shader + + mgr = Manager() + + t1 = mgr.build_tensor([2,2,2]) + t2 = mgr.build_tensor([1,2,3]) + t3 = mgr.build_tensor([1,2,3]) + + # Create multiple separate sequences + sq_mult = mgr.create_sequence("SQ_MULT") + sq_sum = mgr.create_sequence("SQ_SUM") + sq_sync = mgr.create_sequence("SQ_SYNC") + + # Initialize sq_mult + sq_mult.begin() + sq_mult.record_algo_data([t1, t2, t3], add_shader) + sq_mult.end() + + sq_sum.begin() + sq_sum.record_algo_data([t3, t2, t1], sum_shader) + sq_sum.end() + + sq_sync.begin() + sq_sync.record_tensor_sync_local([t1, t3]) + sq_sync.end() + + # Run multiple iterations + for i in range(10): + sq_mult.eval() + sq_sum.eval() + + sq_sync.eval() + + print(t1.data(), t2.data(), t3.data()) -Sequence -------- +Package Installation +^^^^^^^^^ -The Kompute Sequence consists of batches of Kompute Operations, which are executed on a respective GPU queue. The execution of sequences can be synchronous or asynchronous, and it can be coordinated through its respective Vulkan Fence. +The package can be installed through the top level `setup.py` by running: -.. autoclass:: kp.Sequence - :members: +``` +pip install . +``` -Tensor -------- - -The Kompute Tensor is the atomic unit in Kompute, and it is used primarily for handling Host and GPU Device data. - -.. autoclass:: kp.Tensor - :members: - - -TensorType -------- - -.. automodule:: kp - :members: diff --git a/docs/overview/python-reference.rst b/docs/overview/python-reference.rst new file mode 100644 index 0000000..0a8eb7a --- /dev/null +++ b/docs/overview/python-reference.rst @@ -0,0 +1,44 @@ + + +Python Class Documentation & Reference +======== + +This section provides a breakdown of the Python classes and what each of their functions provide. +Below is a diagram that provides insights on the relationship between Vulkan Kompute objects and Vulkan resources, which primarily encompass ownership of either CPU and/or GPU memory. + +.. image:: ../images/kompute-architecture.jpg + :width: 70% + +Manager +------- + +The Kompute Manager provides a high level interface to simplify interaction with underlying :class:`kp.Sequence` of Operations. + +.. autoclass:: kp.Manager + :members: + + +Sequence +------- + +The Kompute Sequence consists of batches of Kompute Operations, which are executed on a respective GPU queue. The execution of sequences can be synchronous or asynchronous, and it can be coordinated through its respective Vulkan Fence. + +.. autoclass:: kp.Sequence + :members: + + +Tensor +------- + +The Kompute Tensor is the atomic unit in Kompute, and it is used primarily for handling Host and GPU Device data. + +.. autoclass:: kp.Tensor + :members: + + +TensorType +------- + +.. automodule:: kp + :members: +