A small, offline CUDA example for reviewing and testing deterministic integer-range search.
The repository demonstrates four reusable engineering ideas:
- split a bounded integer range across one or more GPUs;
- process each device range in deterministic chunks;
- propagate CUDA and worker failures instead of reporting false completion;
- collect a bounded set of matches from a harmless toy predicate.
The included predicate applies SplitMix64 to each integer and matches values whose low bits are zero. It exists only to make the scheduler and error handling testable. Replace it only with workloads you own or are authorized to run.
This project contains no network client, credential handling, wallet logic, key recovery, external target integration, or automatic publishing/submission behavior.
- Linux with an NVIDIA GPU
- CUDA toolkit with
nvcc - Bash 3.2 or newer
The orchestration and CPU-reference tests do not require a GPU.
make buildThe build script detects the local compute capability. If the installed CUDA toolkit is older than the GPU, it tries a forward-compatible compute_80 PTX build and fails explicitly if neither build works.
./build/range-search 0 1000000 12345 20Arguments are:
range-search START COUNT [SEED] [ZERO_BITS] [MATCH_CAPACITY]
Matches are printed as MATCH value=N. A coverage summary goes to standard error. The program exits nonzero on malformed input, CUDA failure, or match-buffer overflow.
SEARCH_BIN=./build/range-search \
./scripts/search-driver.sh 0 10000000 500000 auto 12345 20Arguments are:
search-driver.sh START COUNT [CHUNK] [GPU_COUNT|auto] [SEED] [ZERO_BITS]
The driver emits results only if every assigned chunk completes successfully. Per-device diagnostics are retained until the run finishes and are printed if any worker fails.
Set MATCH_CAPACITY in the environment to change the bounded per-chunk match buffer (default 4096). The value is forwarded to every worker and recorded in each chunk manifest, so changing it invalidates resume metadata.
To retain a verifiable run and resume completed chunks:
SEARCH_BIN=./build/range-search \
SEARCH_RUN_DIR=./runs/example \
./scripts/search-driver.sh 0 10000000 500000 auto 12345 20
SEARCH_BIN=./build/range-search \
SEARCH_RUN_DIR=./runs/example \
SEARCH_RESUME=1 \
./scripts/search-driver.sh 0 10000000 500000 auto 12345 20Each successful chunk records its exact interval, GPU index, binary hash, output hash, match count, seed, predicate setting, and match capacity. scripts/verify-manifest.sh snapshots and validates every certified output, rejects missing, overlapping, reordered, corrupted, out-of-range, or identity-mismatched chunks, and emits merged results only from those verified snapshots.
For portable Bash arithmetic, the driver requires START and the exclusive end START + COUNT to be within 0..2^63-1. The CUDA executable uses unsigned 64-bit values.
make testThe tests use a fake search executable to verify exact range coverage, deterministic result merging, invalid-input rejection, and worker-failure propagation. A deterministic 24-case parameter matrix compares partitioned execution with the CPU reference, and an adversarial suite corrupts manifests, outputs, binary identity, and resume state.
They also compile a CPU reference executable from the same predicate header and compare a direct CPU search with a differently chunked, three-worker run. This catches scheduler gaps and predicate drift without requiring CUDA.
See REVIEW_GUIDE.md for the review questions and EXTERNAL_REVIEW_TEMPLATE.md for a structured response format suitable for another engineer or LLM reviewer.
This is an educational systems template. It performs a local exhaustive search over a caller-supplied integer interval using a toy predicate. Users are responsible for ensuring that any replacement predicate and dataset are lawful and authorized.
MIT