Add RandomUniform-28 with deterministic generator attribute (Philox4x32-10)

[strimo378]

Adds an optional generator attribute, a 64-bit seed_int64 attribute, and an optional offset input to RandomUniform (new opset-28 schema), making the operator optionally deterministic — and therefore testable — while fully supporting streaming inference. RandomUniform was previously the only generator op with no backend node tests at all, because its output could not be verified.

Supersedes #2, which specified MT19937; this PR uses the counter-based Philox-4x32-10 instead (#2 stays open as backup).

• generator="unspecified" (default value): the PRNG remains implementation-defined; fully backward compatible. This mode gives no determinism guarantee: results may differ across implementations and even across runs of the same implementation, even when a seed is specified. An implementation may produce reproducible results here, but is not required to. The legacy float seed attribute applies only to this mode.
• generator="philox4x32_10": fully specified Philox-4x32 generator with 10 rounds (Salmon et al., "Parallel random numbers: as easy as 1, 2, 3", SC'11; standard constants M0=0xD2511F53, M1=0xCD9E8D57, W0=0x9E3779B9, W1=0xBB67AE85):
  • Key: the required seed_int64 attribute (INT); its two's complement bits are the unsigned 64-bit Philox key — key0 = seed_int64 & 0xFFFFFFFF, key1 = (seed_int64 >> 32) & 0xFFFFFFFF. The legacy float seed is not used in this mode and must not be set (both enforced by shape inference, as is rejection of unknown generator names). Rationale: ONNX attributes have exactly one fixed type and seed is float32, whose 24-bit significand cannot address a 64-bit key space; a dedicated INT attribute follows the established Constant value_int/value_float pattern. (ONNX has no unsigned attribute type, so int64-bits-as-uint64 is the standard encoding, also used for the offset input.)
  • Counter mapping: block b uses the 128-bit counter (lo32(b), hi32(b), lo32(offset), hi32(offset)) and yields four 32-bit words w0..w3. For bfloat16/float16/float, element i uses word i mod 4 of block ⌊i/4⌋ and forms r = ⌊w / 2^(32-p)⌋ / 2^p with p significand bits (8/11/24) — exactly representable in the target type. For double, element i uses words 2*(i mod 2) and 2*(i mod 2)+1 of block ⌊i/2⌋ combined via the res53 scheme (r = (⌊a/2^5⌋·2^26 + ⌊b/2^6⌋) / 2^53).
  • The element value is low + r * (high - low), with low/high converted to dtype and all arithmetic performed in dtype under IEEE 754 round-to-nearest-even — bit-identical across conforming implementations. No double-precision arithmetic is needed unless dtype is double.
  • Order-independent by construction: each output element depends only on (seed_int64, offset, its position i), so elements can be computed independently, in any order, or in parallel — stated normatively in the operator doc.

Streaming: the offset input

A hidden "continue where the last run stopped" mode cannot exist in ONNX — a model run is a pure function of its inputs, and hidden state would be undefined under concurrent runs, session cloning, or replay. Instead, streaming is a wiring decision around one explicit input:

• Optional input offset (int64 scalar, 0 if absent): keys Philox counter words c2/c3. Since the block index lives in c0/c1 and the offset in c2/c3, streams of different offsets never overlap, regardless of the output size.
• Reset per run (testing, reproducibility): feed a constant offset or omit the input — every run draws identical values.
• Streaming (fresh values per run): feed a different offset in every run. Because every offset value is an independent stream, any non-repeating scheme works — a host-side step counter, an offset stored as an initializer in the model file and advanced at checkpoint time, or a Loop-carried value incremented in the graph. Each run remains individually deterministic and replayable, unlike hidden-state RNGs.

The operator deliberately has no next_offset output: offset + 1 is trivially computable (host counter, Add node, loop-carried update), so such an output would carry no information — unlike present_state/KV-cache outputs, which cannot be derived without recomputation. It would also over-specify a chaining protocol where none is needed.

The 28→27 downgrade adapter rejects nodes that use the offset input or the seed_int64 attribute (not expressible in older opsets).

The attribute value set is deliberately extensible: the same pattern is intended to be rolled out to the other non-deterministic operators later (RandomNormal, RandomUniformLike, RandomNormalLike, Bernoulli, Multinomial), and future opset versions can add further generator algorithms. The Philox implementation already lives in the shared _CommonRandom base of the reference runtime in preparation for that.

Test cases and their intent

Every backend node test case documents its intent in a docstring that is published verbatim in docs/TestCoverage.md; the reference-evaluator tests carry the same information as comments. Summary:

Test	Intent
test_randomuniform_philox	Base case: default range/dtype, 12 elements = three full counter blocks.
test_randomuniform_philox_multi_block	Counter-block stress: 35 elements span nine blocks with a partially consumed last block (35 = 8·4 + 3), exposing wrong block increments, word ordering, or padding handling.
test_randomuniform_philox_nd_shape	Non-trivial 4-D shape with singleton dimension and negative low: row-major ordering must be rank-independent; sign handling in low + r*(high-low).
test_randomuniform_philox_offset	Streaming: offset fed as an input .pb file (offset=5), expected output from the stream disjoint to offset 0.
test_randomuniform_philox_low_high	Non-default range: the affine transform must be evaluated in the target dtype, not in double.
test_randomuniform_philox_double	Double path: two words per element (res53), word pairing 0/1 vs. 2/3 within a block.
test_randomuniform_philox_float16 / _bfloat16	Reduced-precision paths (p=11 / p=8): top-bits extraction, exact representability. (bfloat16 excluded on NumPy < 2.0, matching existing bfloat16 exclusions.)
evaluator: element independence	Row-major values of a smaller tensor must be a prefix of any larger tensor with the same seed, across block boundaries; a different seed changes the stream. Directly verifies the counter-based order-independence claim.
evaluator: offset streaming	Runs with different offsets draw disjoint streams; each run is individually replayable; a model without the offset input equals offset 0.
evaluator: statelessness	Running the same model twice yields bit-identical output — catches backends with hidden RNG state.
evaluator: Random123 KAT	The three philox4x32 10 known-answer vectors from the Random123 distribution (tests/kat_vectors), hardcoded inline.

Multi-run .pb data: the backend test runner executes every test_data_set_N directory of a test case, so per-run input variation is expressible — the offset test uses exactly this mechanism (input_0.pb carries the offset). Dynamic output shapes remain out of scope by construction: shape is a required attribute; data-dependent shapes are the domain of RandomUniformLike, which will gain the same generator/offset mechanics in the planned follow-up.

Changes

• defs.cc: RandomUniform-28 with generator and seed_int64 attributes and optional offset input (type constraint T2 = int64); shape inference validates the generator value, requires seed_int64 for deterministic generators, and rejects the float seed alongside them; old.cc: v22 schema preserved; operator_sets.h: registered under opset 28; new doc string with the complete, self-contained Philox-4x32-10 specification (round function, key schedule, counter mapping, offset/streaming semantics)
• convert.h / adapters: 27→28 CompatibleAdapter; 28→27 custom adapter that drops generator="unspecified" and rejects deterministic generators, the seed_int64 attribute, and the offset input
• Reference implementation: vectorized _Philox4x32 class in _op_common_random.py (seed_int64 + offset keyed), verified against the known-answer vectors from the Random123 distribution and against the word stream of the canonical Random123 implementation; uses ml_dtypes.finfo so non-native float types (bfloat16) resolve their precision correctly
• Node tests: first-ever backend node tests for RandomUniform (8 cases, see table above) with exact expected outputs generated by an independent inline Philox implementation in the test case, verified bit-exactly by the reference backend runner
• Unit tests: schema (incl. seed_int64 typing), shape inference (incl. error cases: missing seed_int64, float seed with philox, unknown generator), version converter 27↔28 (incl. offset and seed_int64 rejection), reference evaluator (see table above)
• Regenerated docs/Operators.md, docs/Changelog.md, docs/TestCoverage.md, and backend test data

Motivation and Context

The random-number operators are non-deterministic per spec: even with seed set, results differ across implementations, so conformance tests cannot verify their output. As a consequence, the random operators are effectively invisible to conformance tracking such as the ONNX Backend Scoreboard: there are no node tests whose results a backend could be checked against. With an opt-in, fully specified generator (Philox-4x32-10 for now, extensible later), the output becomes reproducible and bit-exactly verifiable, so random operators can be covered by the standard backend test suite and their support becomes measurable on the scoreboard — while the default behavior, including its freedom to be non-deterministic, stays unchanged. Philox is counter-based, so the specification is order-independent and parallelizable — a natural fit for GPU and multi-threaded backends — and the explicit offset input supports streaming inference with fresh, reproducible values per run.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PVuibCDPDmYP2zoMawf9sp