Getting Started

Prerequisites

Vulkan 1.3 driver (any vendor: AMD, NVIDIA, Intel, Apple Silicon)
CPU with Vulkan 1.3 SDK (for building from source)
CMake 3.20+
GCC 13+ or Clang 17+ (C++20)

Python Quick Start

Install from PyPI (coming soon) or from source:

pip install vulkan-columnar

Then:

from vulkan_columnar import VcContext, U32, F64

with VcContext() as ctx:
    col = ctx.create_column(U32, [5, 3, 1, 4, 2])
    print(col.read())          # [5 3 1 4 2]
    print(col.sort().read())   # [1 2 3 4 5]
    print(col.filter(col > 2).read())  # [5 3 4]

Building from Source

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

This builds libvulkan_columnar.dll/.so/.dylib.

Running Tests

cmake -B build -DCMAKE_BUILD_TYPE=Debug \
    -DVC_BUILD_TESTS=ON -DVC_ENABLE_ASAN=ON -DVC_ENABLE_UBSAN=ON
cmake --build build
cd build && ctest --output-on-failure

Debug builds enable Vulkan validation layers automatically. Tests must pass with zero validation errors.

Hello Compute

Verify your Vulkan toolchain with the standalone sandbox spike:

cmake -B build -DVC_SANDBOX=ON
cmake --build build --target hello_compute
./build/sandbox/hello_compute

Expected output:

GPU: AMD Radeon RX 9070 (Vulkan 1.4.329)
PASS: All 1024 elements correctly incremented.

C API Usage

#include "vulkan_columnar/vc_context.h"
#include <stdio.h>

int main() {
    VcContext* ctx = vc_create_context();

    uint32_t data[] = {5, 3, 1, 4, 2};
    VcColumn* col = vc_create_column(ctx, VC_DTYPE_U32, 5, data);

    VcColumn* sorted = vc_sort(ctx, col);
    uint32_t buf[5];
    vc_read_column(ctx, sorted, buf, sizeof(buf));

    printf("Sorted: %u %u %u %u %u\\n", buf[0], buf[1], buf[2], buf[3], buf[4]);

    vc_destroy_column(ctx, sorted);
    vc_destroy_column(ctx, col);
    vc_destroy_context(ctx);
    return 0;
}

Supported Operations

The library covers the full Polars expression surface for numeric and string types (100+ ops). Key groups:

Filter / Cast: Boolean mask filtering, type conversion
Sort: LSD radix sort (all numeric dtypes, nullable)
Reduce: Sum, min, max, count, mean (U32/I32/F32/F64), with null handling
Group-by: Sort-based group-by with sum/count/mean/std/var/min/max
Join: Shared-memory hash join (inner/left/right)
Element-wise: Arithmetic (add/sub/mul), comparison (eq/neq/lt/gt)
String: Length, upper/lower, concat, strip, replace, find, substring, regex
Window / Rolling: Shift, fill, cumulative sum, rolling sum/mean
Unique / Drop Nulls / Concat / Slice / When-Then / Gather
Temporal: Date parts, durations, arithmetic
List / Struct (v0.2): Nested column types with list/struct ops

See the API Reference for the complete C ABI function listing.