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:

.. code-block:: bash

    pip install vulkan-columnar

Then:

.. code-block:: python

    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
--------------------

.. code-block:: bash

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

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

Running Tests
-------------

.. code-block:: bash

    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:

.. code-block:: bash

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

Expected output:

.. code-block::

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

C API Usage
-----------

.. code-block:: c

    #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 :doc:`api-reference` for the complete C ABI function listing.