Repository navigation
SyclReproSum 1.2.0
SyclReproSum 1.2.0 adds explicit SYCL event dependencies to the reproducible
sum and cumulative-sum APIs, clarifies the synchronous execution contract, and
strengthens input and USM capability validation. The release remains
header-only, source-compatible with existing calls, C++17, and based on the
Ahrens-Demmel-Nguyen (ADN) binned floating-point format, with binned primitives
adapted from the ReproBLAS reference implementation.
Highlights
- New dependency-aware overloads for both
adn::sumandadn::cumsum. - Producer events can be passed directly to the library without a separate
host-side wait. - Dependencies are attached to the first library operation that accesses user
memory, including plain-host-pointer copy paths. - Existing overloads remain available and synchronous, with their caller-side
USM synchronization responsibility now documented explicitly. adn::sumnow rejects null pointers for nonempty inputs with
std::invalid_argument.adn::sumnow rejects element counts whose byte size would overflow
size_twithstd::length_error.- Shared and device USM requirements are now checked explicitly and documented
instead of being left to allocation failure behavior. - Missing USM capabilities produce descriptive
std::runtime_error
exceptions. - Cross-queue producer tests verify dependency ordering for scalar and
cumulative sums. - The test suite now contains 173 correctness cases and four 100-million-
element benchmarks per selected device, plus ten cross-device cases and one
version test. - Version macros now report 1.2.0.
Dependency-aware APIs
The new overloads accept a list of prerequisite SYCL events:
template <int K = 3, int WG_SIZE = 256, typename T>
T sum(sycl::queue &q, const T *arr, size_t N,
const std::vector<sycl::event> &dependencies);
template <int K = 3, int WG_SIZE = 256, typename T>
void cumsum(sycl::queue &q, const T *input, T *output, size_t N,
const std::vector<sycl::event> &dependencies);For example, an input transfer can feed directly into a reproducible sum:
double *device_input = sycl::malloc_device<double>(count, q);
sycl::event input_ready =
q.memcpy(device_input, host_input, count * sizeof(double));
double result = adn::sum(q, device_input, count, {input_ready});The caller does not need to wait for input_ready separately. The library
orders its first input access after that event and waits for its own submitted
work before returning.
The same model applies to cumulative sums:
sycl::event input_ready = producer_queue.submit([&](sycl::handler &h) {
h.parallel_for(sycl::range<1>(count), [=](sycl::id<1> i) {
input[i] = static_cast<double>(i[0] + 1);
});
});
adn::cumsum(q, input, output, count, {input_ready});The producer and consumer queues may be distinct when the supplied event is a
valid dependency for the target context.
Ordering and synchronous behavior
Both the original and dependency-aware overloads are synchronous. A return
from adn::sum or adn::cumsum means all work submitted by that library call
has completed. These APIs intentionally do not return a SYCL event.
The dependency list controls when the library may begin accessing the user
ranges:
| Operation and pointer path | First ordered library access |
|---|---|
sum with USM input |
First reduction kernel |
sum with plain host input |
Host-to-device copy |
cumsum with USM input and output |
Tile-total kernel |
cumsum with any plain host range |
Required copy or the first dependent kernel, with later accesses ordered transitively |
For overloads without a dependency list, callers must complete earlier
operations that write or conflict with USM input or output ranges before the
call. Callers must also prevent conflicting concurrent access while the
synchronous operation is running.
This makes the ownership boundary explicit: the dependency overloads express
known producer ordering to the library, while the original overloads preserve
their existing simple synchronous interface.
Stronger input validation
adn::sum now matches the defensive behavior already provided by
adn::cumsum for invalid nonempty input.
Null pointers
For N > 0, a null sum input is rejected deterministically:
adn::sum(q, static_cast<const double *>(nullptr), 1);
// Throws std::invalid_argument.For N == 0, the pointer is not inspected and the scalar sum still returns
positive zero. Empty cumulative sums likewise return without touching either
range.
Byte-size overflow
adn::sum now verifies that N * sizeof(T) can be represented by size_t.
An overflowing count throws std::length_error before pointer classification,
allocation, copying, or kernel submission. The existing conservative
adn::max_reproducible_count<T> check remains in place and is evaluated first.
These checks provide stable API-level errors instead of backend-dependent
copy, allocation, or kernel failures.
Explicit USM requirements
Version 1.2.0 makes the implementation's USM requirements part of the
documented and validated device contract:
- Every valid, nonempty
adn::sumandadn::cumsumoperation requires shared
USM support for environment probes. Scalar sums also store their partial
binned accumulators in shared USM. adn::cumsumadditionally requires device USM for tile totals, tile
prefixes, and other internal scan storage.adn::sumrequires device USM only when a plain host input must be copied to
a temporary device allocation.- A direct sum from device, shared, or host USM does not add a device-USM
requirement beyond the capabilities needed by that pointer itself.
adn::validate_environment<T>(q) now validates shared USM in addition to the
existing floating-point requirements. Internal shared and device allocation
helpers also check their corresponding SYCL aspects before attempting an
allocation. Missing support produces a descriptive std::runtime_error
instead of an incidental std::bad_alloc or backend allocation exception.
The established floating-point requirements remain unchanged: supported
devices must provide fp64, round-to-nearest behavior, gradual underflow,
Inf/NaN handling, and signed-zero preservation as verified by the advertised
capabilities and runtime device probes.
Reproducibility and numerical behavior
This release does not change the ADN accumulator arithmetic, bin layout,
deposit, renormalization, merge, or conversion paths. Valid inputs retain the
same bit-reproducibility guarantees and numerical behavior as version 1.1.0.
Within adn::max_reproducible_count<T>, scalar sums remain independent of
input permutation, work-group size, work-item scheduling, and validated
device. Cumulative prefixes remain bit-identical across runs, supported
work-group sizes, and validated devices for a fixed input sequence, with the
last prefix retaining full input-order independence.
Canonical NaN handling, infinity propagation, signed zero, subnormal support,
capacity limits, fold-count behavior, and work-group-size configuration are
unchanged.
Testing and validation
Four parameterized correctness cases were added per selected device:
Sum_USMDependenciesholds an unfinished cross-queue producer and verifies
thatadn::sumcannot access the shared-USM input or return early.Cumsum_USMDependenciesperforms the same ordering check for both cumulative
input and output, then validates every generated prefix.Sum_ByteSizeOverflowRejectedverifies the new deterministic
std::length_errorpath.USMCapabilitiesValidatedcovers shared and device USM aspect checks.
The empty-input sum test now also covers a null pointer for both zero and
nonzero counts, and environment validation tests account for shared USM.
The complete suite now contains:
- 173 correctness cases and four throughput benchmarks per selected device.
- Ten cross-device reproducibility cases.
- One version and capacity test.
- 542 total tests on the validation system with two GPUs and one CPU.
The release was built as one CUDA plus SPIR-V fat binary and validated on:
- NVIDIA RTX PRO 4500 Blackwell via CUDA.
- Intel Graphics [0x7d67] via Level Zero.
- Intel Core Ultra 7 265 CPU via OpenCL.
Release validation results:
- All 530 non-benchmark tests passed.
- The same 530 tests passed under hostile host floating-point modes.
- Both unsafe-device variants passed all three expected rejection tests.
- The compile-time unsafe evaluation-mode rejection check passed.
- All 542 tests passed when the twelve 100-million-element scalar and
cumulative throughput benchmarks were included. - clang-format 18, ASCII-content, and whitespace checks passed.
The dependency and validation changes are outside the binned arithmetic, and
the existing shuffled-input, work-group matrix, repeated-run, special-value,
and cross-device bit-identity tests continue to pass.
Compatibility and upgrade notes
- Version 1.2.0 is an additive, source-compatible release for valid existing
calls. - Existing three-argument
adn::sumand four-argumentadn::cumsumcalls do
not require source changes. - Existing overloads remain synchronous and now document that callers are
responsible for completing conflicting prior USM operations. - Applications with producer events can adopt the new overloads incrementally.
- A nonempty null
adn::suminput now throwsstd::invalid_argumentinstead
of reaching backend-dependent behavior. - A sum count with an unrepresentable byte size now throws
std::length_error. - Devices without the required USM aspects now fail early with
std::runtime_errorand a descriptive requirement. - No compiled library or link step is required. Replace or update
repro_sum.hppand continue compiling as C++17 with SYCL.
Build requirements
- A C++17 compiler with SYCL support.
- Intel DPC++/LLVM with the required offload target support.
- An fp64-capable SYCL CPU or GPU device that passes runtime environment
validation. - Shared USM for every valid nonempty operation.
- Device USM for cumulative sums and sums of plain host arrays.
- oneDPL headers for the cumulative-sum throughput baseline.
- The Google Test submodule for the test suite.
Typical commands remain:
make all
make run
make test
make test-validationmake test includes the 100-million-element throughput benchmarks. For a
faster correctness-only run:
./repro_test "--gtest_filter=-*Bench*"Changes since 1.1.0
- Add dependency-aware
adn::sumandadn::cumsumoverloads. - Attach prerequisites to the first user-memory access on direct-USM and
plain-host-pointer paths. - Document synchronous completion and caller responsibility for the original
overloads. - Reject nonempty null inputs in
adn::sum. - Reject sum byte-size overflow before pointer handling or allocation.
- Validate shared and device USM aspects where each operation requires them.
- Document path-specific USM prerequisites and failure behavior.
- Add cross-queue dependency, input-validation, and USM-capability tests.
- Expand the per-device correctness suite from 169 to 173 cases.
- Update the encoded library version from 1.1.0 to 1.2.0.
Full comparison:
v1.1.0...v1.2.0
Attribution and license
SyclReproSum is licensed under the BSD 3-Clause License. Portions of the
binned accumulator primitives are adapted from ReproBLAS, Copyright 2016,
University of California. See THIRD_PARTY_NOTICES for the complete
attribution and license terms.