Metadata-Version: 2.4
Name: ai_ml_workload_library_for_vulkan
Version: 0.12.0.dev20261017
Summary: ML Workload Library for Vulkan
Author: Arm Limited
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSES/Apache-2.0.txt
Dynamic: license-file

# ML Workload Library for Vulkan®

The Workload Library provides an **experimental** C++ API for constructing executable
ML workloads for Vulkan® and running them through a common resource-binding
and execution model.

## Public API

Include the installed public headers that your application requires:

```cpp
#include <mlworkloadlib/workload.hpp>
#include <mlworkloadlib/context.hpp>
#include <mlworkloadlib/session.hpp>
```

The API exposes:

- `mlsdk::workloadlib::Workload`
- `mlsdk::workloadlib::Context`
- `mlsdk::workloadlib::Session`
- `mlsdk::workloadlib::BindingSet`
- `mlsdk::workloadlib::PreparedExecution`

You can create the following workloads:

- VGF-backed workloads with `Workload::fromVGF(...)`
- Standalone compute shader workloads with `Workload::fromComputeShader(...)`
- Standalone Vulkan® data graph workloads with `Workload::fromDataGraph(...)`

Use `Context::wrap(...)` to provide application-owned Vulkan® objects, or
use `Context::create()` to create a runtime-owned Vulkan® context.

## Building the ML Workload Library for Vulkan® from source

The build system must have:

- C/C++ 17 compiler: GCC or Clang on Linux, Clang on Darwin, or MSVC on
  Windows®.
- CMake 3.25 or later.
- Ninja 1.8.2 or later.
- Python 3.10 or later and `uv` 0.9.26. Python tooling dependencies are
  declared in `pyproject.toml` and locked in `uv.lock`.
- Doxygen 1.9.1 or later. (When building documentation)

To create an archive containing the build artifacts, pass the `--package-type`
option with an archive type such as `zip` or `tgz`. Use `--package-dir` to
choose where the archive is written; by default, packages are written to the
build directory.

For more command line options, see the help output:

```bash
python3 scripts/build.py --help
```

## Build-tree usage

Enable the library when configuring the standalone project:

```sh
cmake -S . -B build
```

Link one of the build-tree targets:

```cmake
target_link_libraries(my_target PRIVATE mlworkloadlib)
```

Alternatively, link a namespaced target in the same build:

```cmake
target_link_libraries(my_target PRIVATE MLWorkloadLibraryForVulkan::mlworkloadlib)
```

## Installed package usage

When the ML Workload Library for Vulkan® is installed, the package exports `mlworkloadlib` through the
`MLWorkloadLibraryForVulkan` package. Downstream consumers must use
`MLWorkloadLibraryForVulkan::mlworkloadlib`.

```cmake
find_package(MLWorkloadLibraryForVulkan CONFIG REQUIRED)
target_link_libraries(my_target PRIVATE MLWorkloadLibraryForVulkan::mlworkloadlib)
```

The package target requires the `VGF` and `VulkanHeaders` packages to be
discoverable at configure time.

## Optional VGF support

VGF workload support is enabled by default. Disable it when the library is only
needed for programmatically constructed workloads:

```sh
python3 scripts/build.py --disable-vgf-support
```

For direct CMake configuration, set `ML_WORKLOAD_LIB_ENABLE_VGF_SUPPORT=OFF`.
Such builds do not locate or link VGF Lib. Calls to `Workload::fromVGF(...)`
throw an exception indicating that VGF support is unavailable.

## Optional source module support

The base library supports SPIR-V™ modules. You can choose to enable GLSL and
HLSL source compilation when you build the library:

```sh
python3 scripts/build.py --enable-glsl-support
python3 scripts/build.py --enable-hlsl-support
```

Use `--glslang-path` or `--dxc-path` when the dependency is not in the default
location. For direct CMake configuration, use
`ML_WORKLOAD_LIB_ENABLE_GLSL_SUPPORT` with `GLSLANG_PATH`, or
`ML_WORKLOAD_LIB_ENABLE_HLSL_SUPPORT` with `DXC_PATH`.

Applications can query the source backends available in the linked library with
`mlsdk::workloadlib::supports(...)`.

## Documentation

Install Doxygen and the Python documentation tool dependencies and build the HTML documentation:

```sh
uv sync --locked --no-install-project --no-default-groups --group tooling
uv run --no-sync python scripts/build.py --doc
```

The generated documentation is available at `build/docs/out/index.html`.

## Code coverage

Sync the locked Python tooling dependencies, then run the unit tests on Linux
with GCC coverage instrumentation:

```sh
uv sync --locked --no-install-project --no-default-groups --group test --group tooling
uv run --no-sync python scripts/build.py --coverage --build-dir build-coverage
```

The coverage command writes a detailed HTML report to
`build-coverage/coverage/index.html` and a machine-readable JSON summary to
`build-coverage/coverage/summary.json`. Coverage is collected for the library
sources and public headers; tests and bundled dependencies are excluded from
the report.

## Consumption model

- `mlworkloadlib` is install-tree consumable today via `find_package(MLWorkloadLibraryForVulkan)`.
- `mlworkloadlib` depends on external packages (`VGF`, `VulkanHeaders`), and those
  dependencies are resolved via the standalone package config.

## License

The ML Workload Library for Vulkan® is distributed under the software licenses in
the `LICENSES` directory.

## Trademark notice

Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US
and/or elsewhere.

Khronos® and Vulkan® are registered trademarks, and SPIR-V™ is a trademark of
[The Khronos Group Inc.](https://www.khronos.org/legal/trademarks/).
