From e4b289e230e385ea2790348288c6414554ac0e91 Mon Sep 17 00:00:00 2001 From: Shahar Sandhaus Date: Mon, 8 Sep 2025 23:38:41 -0700 Subject: [PATCH 1/5] Adding numpy to install script for docs --- .github/workflows/deploy_docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml index dccde4a0..77badf55 100644 --- a/.github/workflows/deploy_docs.yml +++ b/.github/workflows/deploy_docs.yml @@ -44,6 +44,8 @@ jobs: "sphinx>=7,<9" \ sphinx-rtd-theme + pip install numpy + # If your docs import your package (autodoc), also install it: # python -m pip install -e . From 6eebbcaaca0ca7f19a353b79c1b311353644a0cd Mon Sep 17 00:00:00 2001 From: Shahar Sandhaus Date: Tue, 9 Sep 2025 13:37:33 -0700 Subject: [PATCH 2/5] More documentation work --- docs/getting_started.rst | 2 +- docs/tutorials/buffer_tutorial.rst | 52 +++++++++++------------------- docs/tutorials/context_system.rst | 32 +++++++++++++----- 3 files changed, 43 insertions(+), 43 deletions(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 011a4a99..180cbd80 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -1,4 +1,4 @@ -Getting Started/Installation +Getting Started =============================== Welcome to vkdispatch! This guide will help you install the library and run your first GPU-accelerated code. diff --git a/docs/tutorials/buffer_tutorial.rst b/docs/tutorials/buffer_tutorial.rst index 6dec2a24..30441715 100644 --- a/docs/tutorials/buffer_tutorial.rst +++ b/docs/tutorials/buffer_tutorial.rst @@ -1,36 +1,13 @@ Buffer Creation and Usage ================= -The Buffer system is the heart of vkdispatch. All GPU memory operations -go through Buffer objects. - -.. note:: - Always use BufferBuilder to create buffers - direct Buffer construction - is not supported. - -Buffer Class ------------- - -.. autoclass:: vkdispatch.Buffer - :members: __init__, _destroy, write, read - :show-inheritance: - - **Location:** vkdispatch.base.Buffer - - **Example Usage:** - - .. code-block:: python - - buffer = vd.Buffer((1000000,), vd.float32) - buffer.write(my_data) - result = buffer.read() +In vkdispatch, nearly all data is stored inside "buffers" (each wrapping an individual `VkBuffer `_ object and all other objects needed to manage it). These are the equivalent of :class:`torch.Tensor` or :func:`wp.array` in :class:`warp-lang`. +However, unlike :class:`torch.Tensor` or :func:`wp.array`, vkdispatch buffers are by default multi-device. This means that when a vkdispatch buffer is allocated on a multi-device or multi-queue context, multiple :class:`VkBuffer`'s are allocated (one for each queue on each device). This architecture has the benefit of greatly simplfying multi-GPU programs, since all buffers can be assumed to exist on all devices and all queues. Your First GPU Buffer --------------------- - - .. code-block:: python import vkdispatch as vd @@ -56,15 +33,22 @@ Your First GPU Buffer :class: tip 1. We import `vkdispatch` and `numpy` (a common dependency for numerical data). - 2. A `BufferBuilder` is used to define the characteristics of our GPU buffer (size, usage). - 3. `buffer.upload()` transfers data from your CPU's memory to the GPU. - 4. `buffer.download()` retrieves data back from the GPU to the CPU. - 5. Error checking is crucial in GPU programming, so `check_for_errors()` ensures operations completed successfully. + 2. We use the :func:`vkdispatch.asbuffer` function to upload the numpy array to a vkdispatch buffer. + 3. :func:`vkdispatch.Buffer.read` retrieves data back from the GPU to the CPU. The number provided as an argument to the function is the queue index to read from. For a simple context with one device and one queue, there is only 1 queue, so we read from index 0. If the index is ommited the function returns a python list of the contents of all buffers on all queues and devices. + +Buffer Class API Reference +------------ +.. autoclass:: vkdispatch.Buffer + :members: __init__, _destroy, write, read + :show-inheritance: -Buffer Builder --------------- + **Location:** vkdispatch.base.Buffer -.. autoclass:: vkdispatch.BufferBuilder - :members: - :show-inheritance: \ No newline at end of file + **Example Usage:** + + .. code-block:: python + + buffer = vd.Buffer((1000000,), vd.float32) + buffer.write(my_data) + result = buffer.read() diff --git a/docs/tutorials/context_system.rst b/docs/tutorials/context_system.rst index 59f57be3..e4144cf5 100644 --- a/docs/tutorials/context_system.rst +++ b/docs/tutorials/context_system.rst @@ -1,12 +1,12 @@ Initialization and Context Creation ============== -.. This page is now its own HTML file - In vkdispatch, all operations are handled by a global context object which keeps track of things behind the scenes. By default, any function call into the vkdispatch API (aside from the vd.shader decorator) invokes the creation of a context with default -settings. However, you can also control the context creation process for on of many reasons: +settings. This means that **this page can be skipped if you have no need to customize context parameters.** + +However, you can control the context creation process for one of many reasons: * To utlize more than one device or queue, for full control over GPU resources * To enable debugging features such as printing to stdout from shaders @@ -45,16 +45,32 @@ Initialization API .. autofunction:: vkdispatch.initialize +.. .. autoclass:: vkdispatch.LogLevel +.. :members: VERBOSE, INFO, WARNING, ERROR +.. :show-inheritance: + Context Management ------------------ +After the initialization stage, vkdispatch must create a context to be used. By default, this context will be created when the vkdispatch API is first used (like the initialization). The default context is configured to only use one GPU with one queue, to enable multi-device contexts, the user must manually call the :func:`vkdispatch.make_context` function before calling any other vkdispatch API: + +.. code-block:: python + + import vkdispatch as vd + + # Call the initilization first if you want to modify the instance settings + # vd.initialize(...) + + # To use all available devices, we create the context with the `multi_device` flag + vd.make_context(multi_device=True) + + # To allocate multiple queues per device for maximum utilization we use the `multi_queue` flag + vd.make_context(multi_queue=True) + + # To utilize all devices with multiple queues, we use both flags + vd.make_context(multi_device=True, multi_queue=True) Context API ------------------ .. autofunction:: vkdispatch.make_context -.. autofunction:: vkdispatch.get_context - -.. autoclass:: vkdispatch.LogLevel - :members: VERBOSE, INFO, WARNING, ERROR - :show-inheritance: \ No newline at end of file From f9c2a33dd327b10178d326f9fd575992ca907e99 Mon Sep 17 00:00:00 2001 From: Shahar Sandhaus Date: Tue, 9 Sep 2025 14:54:39 -0700 Subject: [PATCH 3/5] Added dtype doc page --- docs/tutorials/buffer_tutorial.rst | 9 ++++ docs/tutorials/data_types.rst | 66 ++++++++++++++++++++++++++++++ docs/tutorials/index.rst | 1 + 3 files changed, 76 insertions(+) create mode 100644 docs/tutorials/data_types.rst diff --git a/docs/tutorials/buffer_tutorial.rst b/docs/tutorials/buffer_tutorial.rst index 30441715..b21ca45d 100644 --- a/docs/tutorials/buffer_tutorial.rst +++ b/docs/tutorials/buffer_tutorial.rst @@ -5,6 +5,12 @@ In vkdispatch, nearly all data is stored inside "buffers" (each wrapping an indi However, unlike :class:`torch.Tensor` or :func:`wp.array`, vkdispatch buffers are by default multi-device. This means that when a vkdispatch buffer is allocated on a multi-device or multi-queue context, multiple :class:`VkBuffer`'s are allocated (one for each queue on each device). This architecture has the benefit of greatly simplfying multi-GPU programs, since all buffers can be assumed to exist on all devices and all queues. +Allocating Buffers +--------------------- + +To allocate a buffer, you can use the constructor of the :class:`vkdispatch.Buffer` class. + + Your First GPU Buffer --------------------- @@ -52,3 +58,6 @@ Buffer Class API Reference buffer = vd.Buffer((1000000,), vd.float32) buffer.write(my_data) result = buffer.read() + +.. autofunction:: vkdispatch.asbuffer + diff --git a/docs/tutorials/data_types.rst b/docs/tutorials/data_types.rst new file mode 100644 index 00000000..e0482e57 --- /dev/null +++ b/docs/tutorials/data_types.rst @@ -0,0 +1,66 @@ +Data Types Overview +===================== + +In vkdispatch, there are a number of different datatypes that can be used to store data in buffers and images and to process data in shaders. These data types come in 3 formats (for now, all 32 bit): + + * signed int (e.g. :class:`int32 ` and :class:`ivec2 `) + * unsigned int (e.g. :class:`uint32 ` and :class:`uvec3 `) + * floating point (e.g. :class:`float32 ` and :class:`vec4 `) + +In the near future 64 bit and 16 bit types will be added. + +They also come in the following shapes: + + * Scalars + * Complex Number (internally represented as `vec2` in GLSL shaders) + * Vectors (of size 2, 3, and 4) + * Matricies (only :class:`vkdispatch.float32` at 2x2 and 4x4) + +Data Type API Reference +--------------------- + +.. autofunction:: vkdispatch.is_dtype + +.. autofunction:: vkdispatch.is_scalar + +.. autofunction:: is_complex + +.. autofunction:: vkdispatch.is_vector + +.. autofunction:: vkdispatch.is_matrix + +.. autofunction:: vkdispatch.from_numpy_dtype + +.. autofunction:: vkdispatch.to_numpy_dtype + +.. autoclass:: vkdispatch.dtype + +.. autoclass:: vkdispatch.int32 + +.. autoclass:: vkdispatch.uint32 + +.. autoclass:: vkdispatch.float32 + +.. autoclass:: vkdispatch.complex64 + +.. autoclass:: vkdispatch.vec2 + +.. autoclass:: vkdispatch.vec3 + +.. autoclass:: vkdispatch.vec4 + +.. autoclass:: vkdispatch.ivec2 + +.. autoclass:: vkdispatch.ivec3 + +.. autoclass:: vkdispatch.ivec4 + +.. autoclass:: vkdispatch.uvec2 + +.. autoclass:: vkdispatch.uvec3 + +.. autoclass:: vkdispatch.uvec4 + +.. autoclass:: vkdispatch.mat2 + +.. autoclass:: vkdispatch.mat4 \ No newline at end of file diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 393b7523..9feda027 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -8,5 +8,6 @@ A collection of tutorials covering how to use and modify the vkdispatch library. context_system buffer_tutorial + data_types building_from_source \ No newline at end of file From 0d17e24083a8c8a58bc2d071d997e3df21227039 Mon Sep 17 00:00:00 2001 From: Shahar Sandhaus Date: Tue, 9 Sep 2025 15:21:19 -0700 Subject: [PATCH 4/5] Added logging page --- README.md | 4 ++-- docs/getting_started.rst | 4 ++-- docs/tutorials/buffer_tutorial.rst | 31 +++++++++++++++--------------- docs/tutorials/context_system.rst | 13 +++++-------- docs/tutorials/index.rst | 3 ++- docs/tutorials/logging.rst | 9 +++++++++ 6 files changed, 35 insertions(+), 29 deletions(-) create mode 100644 docs/tutorials/logging.rst diff --git a/README.md b/README.md index 495348e5..fb7d7d76 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# Getting Started / Installation +# Getting Started Welcome to **vkdispatch**! This guide will help you install the library and run your first GPU-accelerated code. > **Note:** vkdispatch requires a Vulkan-compatible GPU and drivers installed on your system. Please ensure your system meets these requirements before proceeding. -## PyPI +## Installation The default installation method for `vkdispatch` is through PyPI (pip): diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 180cbd80..ecdf9b2f 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -7,8 +7,8 @@ Welcome to vkdispatch! This guide will help you install the library and run your vkdispatch requires a Vulkan-compatible GPU and drivers installed on your system. Please ensure your system meets these requirements before proceeding. -PyPI ----- +Installation +--------------------------- The default installation method for `vkdispatch` is through PyPI (pip): diff --git a/docs/tutorials/buffer_tutorial.rst b/docs/tutorials/buffer_tutorial.rst index b21ca45d..9e5f59d9 100644 --- a/docs/tutorials/buffer_tutorial.rst +++ b/docs/tutorials/buffer_tutorial.rst @@ -3,15 +3,12 @@ Buffer Creation and Usage In vkdispatch, nearly all data is stored inside "buffers" (each wrapping an individual `VkBuffer `_ object and all other objects needed to manage it). These are the equivalent of :class:`torch.Tensor` or :func:`wp.array` in :class:`warp-lang`. -However, unlike :class:`torch.Tensor` or :func:`wp.array`, vkdispatch buffers are by default multi-device. This means that when a vkdispatch buffer is allocated on a multi-device or multi-queue context, multiple :class:`VkBuffer`'s are allocated (one for each queue on each device). This architecture has the benefit of greatly simplfying multi-GPU programs, since all buffers can be assumed to exist on all devices and all queues. +However, unlike :class:`torch.Tensor` or :func:`wp.array`, vkdispatch buffers are by default multi-device. This means that when a vkdispatch buffer is allocated on a multi-device or multi-queue context, multiple :class:`VkBuffer`\s are allocated (one for each queue on each device). This architecture has the benefit of greatly simplfying multi-GPU programs, since all buffers can be assumed to exist on all devices and all queues. -Allocating Buffers ---------------------- - -To allocate a buffer, you can use the constructor of the :class:`vkdispatch.Buffer` class. +To allocate a buffer, you can either directly use the :func:`constructor ` of the `Buffer` class or the :func:`vd.asbuffer ` function to directly upload a numpy array to the gpu as a buffer. -Your First GPU Buffer +Simple GPU Buffer Example --------------------- .. code-block:: python @@ -39,25 +36,27 @@ Your First GPU Buffer :class: tip 1. We import `vkdispatch` and `numpy` (a common dependency for numerical data). - 2. We use the :func:`vkdispatch.asbuffer` function to upload the numpy array to a vkdispatch buffer. - 3. :func:`vkdispatch.Buffer.read` retrieves data back from the GPU to the CPU. The number provided as an argument to the function is the queue index to read from. For a simple context with one device and one queue, there is only 1 queue, so we read from index 0. If the index is ommited the function returns a python list of the contents of all buffers on all queues and devices. + 2. We use the :func:`vd.asbuffer ` function to upload the numpy array to a vkdispatch buffer. + 3. :func:`read(0) ` retrieves data back from the GPU to the CPU. The number provided as an argument to the function is the queue index to read from. For a simple context with one device and one queue, there is only 1 queue, so we read from index 0. If the index is ommited the function returns a python list of the contents of all buffers on all queues and devices. -Buffer Class API Reference +Buffer API Reference ------------ .. autoclass:: vkdispatch.Buffer :members: __init__, _destroy, write, read - :show-inheritance: + + + .. :show-inheritance: - **Location:** vkdispatch.base.Buffer + .. **Location:** vkdispatch.base.Buffer - **Example Usage:** + .. **Example Usage:** - .. code-block:: python + .. .. code-block:: python - buffer = vd.Buffer((1000000,), vd.float32) - buffer.write(my_data) - result = buffer.read() + .. buffer = vd.Buffer((1000000,), vd.float32) + .. buffer.write(my_data) + .. result = buffer.read() .. autofunction:: vkdispatch.asbuffer diff --git a/docs/tutorials/context_system.rst b/docs/tutorials/context_system.rst index e4144cf5..b86ce87b 100644 --- a/docs/tutorials/context_system.rst +++ b/docs/tutorials/context_system.rst @@ -1,10 +1,7 @@ Initialization and Context Creation ============== -In vkdispatch, all operations are handled by a global context object which keeps -track of things behind the scenes. By default, any function call into the vkdispatch -API (aside from the vd.shader decorator) invokes the creation of a context with default -settings. This means that **this page can be skipped if you have no need to customize context parameters.** +In vkdispatch, all operations are handled by a global context object which keeps track of things behind the scenes. By default, any function call into the vkdispatch API (aside from the :func:`vd.shader ` decorator) invokes the creation of a context with default settings. This means that **this page can be skipped if you have no need to customize context parameters.** However, you can control the context creation process for one of many reasons: @@ -18,7 +15,7 @@ Initialization The first part of any vkdispatch program is initialization. This step is distinct from context creation since it controls the creation of the `VkInstance `_ object, which is required to be able to list the number and type of devices in the system. Since this information may be useful for context creation, the step of initialization and context creation is seperate. -To create a context you must call :class:`vkdispatch.initialize` before any other call +To create a context you must call :func:`vd.initialize() ` before any other call to a vkdispatch API, a few examples are provided below: .. code-block:: python @@ -40,7 +37,7 @@ to a vkdispatch API, a few examples are provided below: .. note:: The debug_mode flag enables the `VK_EXT_debug_utils `_ vulkan extension and singals the creation of a `VkDebugUtilsMessengerEXT `_ object. This allows for printing from shaders, but also significantly reduces performance by introducing runtime debugging tools. Therefore, it is recommended this option remain off unless needed for in shader debugging. -Initialization API +Initialization API Reference ------------------ .. autofunction:: vkdispatch.initialize @@ -52,7 +49,7 @@ Initialization API Context Management ------------------ -After the initialization stage, vkdispatch must create a context to be used. By default, this context will be created when the vkdispatch API is first used (like the initialization). The default context is configured to only use one GPU with one queue, to enable multi-device contexts, the user must manually call the :func:`vkdispatch.make_context` function before calling any other vkdispatch API: +After the initialization stage, vkdispatch must create a context to be used. By default, this context will be created when the vkdispatch API is first used (like the initialization). The default context is configured to only use one GPU with one queue, to enable multi-device contexts, the user must manually call :func:`vd.make_context() ` before calling any other vkdispatch API: .. code-block:: python @@ -70,7 +67,7 @@ After the initialization stage, vkdispatch must create a context to be used. By # To utilize all devices with multiple queues, we use both flags vd.make_context(multi_device=True, multi_queue=True) -Context API +Context API Reference ------------------ .. autofunction:: vkdispatch.make_context diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 9feda027..4522f2ec 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -1,4 +1,4 @@ -Vkdispatch tutorials +Tutorials ==================== A collection of tutorials covering how to use and modify the vkdispatch library. @@ -9,5 +9,6 @@ A collection of tutorials covering how to use and modify the vkdispatch library. context_system buffer_tutorial data_types + logging building_from_source \ No newline at end of file diff --git a/docs/tutorials/logging.rst b/docs/tutorials/logging.rst new file mode 100644 index 00000000..4309a456 --- /dev/null +++ b/docs/tutorials/logging.rst @@ -0,0 +1,9 @@ +Logging Overview +==================== + +Vkdispatch includes a logging system for debugging the internal library. + +Logging API Reference +------------------ + +.. autoclass:: vkdispatch.LogLevel \ No newline at end of file From 678bbc8ae759e5b6469f8e1e0b138c53143465ab Mon Sep 17 00:00:00 2001 From: Shahar Date: Wed, 10 Sep 2025 00:33:29 -0400 Subject: [PATCH 5/5] Update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index fb7d7d76..93b102e0 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ Welcome to **vkdispatch**! This guide will help you install the library and run your first GPU-accelerated code. +**[WARNING: This site is still under heavy development, and has many missing sections]** + > **Note:** vkdispatch requires a Vulkan-compatible GPU and drivers installed on your system. Please ensure your system meets these requirements before proceeding. ## Installation