Skip to content

SyclReproSum 1.2.0

Choose a tag to compare

@lilohuang lilohuang released this 13 Jul 15:07
· 14 commits to main since this release

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::sum and adn::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::sum now rejects null pointers for nonempty inputs with
    std::invalid_argument.
  • adn::sum now rejects element counts whose byte size would overflow
    size_t with std::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::sum and adn::cumsum operation requires shared
    USM support for environment probes. Scalar sums also store their partial
    binned accumulators in shared USM.
  • adn::cumsum additionally requires device USM for tile totals, tile
    prefixes, and other internal scan storage.
  • adn::sum requires 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_USMDependencies holds an unfinished cross-queue producer and verifies
    that adn::sum cannot access the shared-USM input or return early.
  • Cumsum_USMDependencies performs the same ordering check for both cumulative
    input and output, then validates every generated prefix.
  • Sum_ByteSizeOverflowRejected verifies the new deterministic
    std::length_error path.
  • USMCapabilitiesValidated covers 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::sum and four-argument adn::cumsum calls 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::sum input now throws std::invalid_argument instead
    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_error and a descriptive requirement.
  • No compiled library or link step is required. Replace or update
    repro_sum.hpp and 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-validation

make 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::sum and adn::cumsum overloads.
  • 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.