Getting started

This project is Docker-first. Build, test, benchmark, and run demos inside the development container so host CUDA toolkits, compilers, and Python packages do not affect results.

Prerequisites

• Docker Engine or Docker Desktop with Compose v2.
• NVIDIA driver compatible with CUDA 13.x when using GPU tests or the GPU demo.
• nvidia-container-toolkit on Linux hosts that need GPU passthrough.
• No host compiler, CUDA toolkit, or CMake installation is required.

Verify Docker Compose from the repository root:

docker compose run --rm dev bash -lc 'cmake --version && ctest --version'

Repository layout

Path	Purpose
src/core/	CPU feature maps, solvers, and model compositions
src/cuda/	CUDA primitive kernels and RAII wrappers
src/io/	Dataset loading, preprocessing, and drift streams
src/app/	Demo HTTP backend
tests/	GoogleTest unit and integration tests
bench/	Google Benchmark microbenchmarks
docs/	Narrative docs and API entry point
docker/	Development and demo images

First commands

# Configure and run the full CPU test suite
docker compose run --rm dev ctest --output-on-failure

# Run the docs link and Mermaid sanity gate
docker compose run --rm dev ./scripts/docs_check.sh

# Run benchmarks and write JSON to data/benchmarks/latest/
docker compose run --rm dev ./scripts/run_benchmarks.sh

GPU runtime note

The CUDA image builds without a GPU. Runtime GPU tests and the GPU demo require a compatible NVIDIA driver and container toolkit. If no GPU is visible, CUDA tests skip cleanly instead of failing.