Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 30 additions & 2 deletions packages/experimental/kumo-pytorch/src/kumo/pytorch/anchors.py
Original file line number Diff line number Diff line change
Expand Up @@ -384,6 +384,31 @@ def __call__(self, position: int) -> int:
if value < self._n:
return value

def many(self, positions):
"""Evaluate positions in scalar order; the caller bounds the input size."""
import numpy as np

# Avoid array overhead for tiny batches and retain scalar support for
# very large integer domains without truncating their high bits.
if len(positions) < 64 or self._half > 31:
return [self(int(position)) for position in positions]
values = np.asarray(positions)
if values.size == 0:
return np.empty(0, dtype=np.uint64)
if np.any(values < 0) or np.any(values >= self._n):
raise IndexError(f"permutation positions outside [0, {self._n})")
values = values.astype(np.uint64, copy=True)
active = np.arange(len(values))
with np.errstate(over="ignore"):
while len(active):
left = values[active] >> self._half
right = values[active] & self._mask
for key in self._keys:
left, right = right, left ^ (_mix(key ^ right) & self._mask)
values[active] = (left << self._half) | right
active = active[values[active] >= self._n]
return values


def shard_positions(
n: int,
Expand Down Expand Up @@ -417,8 +442,11 @@ def shard_positions(
yield from range(rank, n, world_size)
return
order = _Permutation(n, _mix(seed) ^ _mix(epoch))
for position in range(rank, n, world_size):
yield order(position)
# Bound temporary storage independently of epoch size. Chunking does not
# change the pointwise mapping or the rank's strided positions.
step = 4096 * world_size
for start in range(rank, n, step):
yield from map(int, order.many(range(start, min(start + step, n), world_size)))


def padded_positions(
Expand Down
103 changes: 103 additions & 0 deletions packages/experimental/kumo-pytorch/tests/test_anchor_permutation.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
# All rights reserved.
# SPDX-License-Identifier: Apache-2.0

"""The default anchor shuffle keeps its scalar sequence with bounded work."""

from itertools import islice

import pytest

from kumo.pytorch.anchors import _mix, _Permutation, shard_positions


@pytest.mark.parametrize("size", [*range(66), 127, 128, 129, 4095, 4096, 4097, 10003])
@pytest.mark.parametrize("seed", [0, -1, 2**64 + 17])
def test_vector_permutation_is_the_existing_scalar_permutation(size, seed):
order = _Permutation(size, seed)
expected = [order(i) for i in range(size)]
for width in (17, 4096):
actual = [
int(value)
for start in range(0, size, width)
for value in order.many(range(start, min(size, start + width)))
]
assert actual == expected
assert sorted(expected) == list(range(size))


@pytest.mark.parametrize("half", range(17, 32))
@pytest.mark.parametrize("window", ["start", "middle", "end"])
def test_large_vector_domains_match_scalar_without_fallback(half, window, monkeypatch):
# Just above a power of two exercises cycle walking at every large width.
size = 2 ** (2 * half - 2) + 1
start = {"start": 0, "middle": size // 2, "end": size - 4096}[window]
positions = range(start, start + 4096)
order = _Permutation(size, 77)
expected = [order(position) for position in positions]

def refuse_scalar(self, position):
pytest.fail("large-domain parity must exercise the vector kernel")

monkeypatch.setattr(_Permutation, "__call__", refuse_scalar)
assert list(order.many(positions)) == expected


@pytest.mark.parametrize("size", [2**32 - 1, 2**32 + 1, 2**63, 2**64 - 1, 2**64, 2**65 + 1])
def test_large_domains_are_pointwise_and_do_not_allocate_an_epoch(size):
positions = [0, 1, size // 2, size - 2, size - 1]
order = _Permutation(size, 77)
assert list(order.many(positions)) == [order(i) for i in positions]
assert list(islice(shard_positions(size, seed=7, epoch=3, shuffle=True), 5)) == [
_Permutation(size, _mix(7) ^ _mix(3))(i) for i in range(5)
]


@pytest.mark.parametrize("epoch,rank,world", [(0, 0, 1), (3, 2, 7), (9, 11, 20)])
def test_vector_shuffle_keeps_each_rank_sequence(epoch, rank, world):
size = 8209
order = _Permutation(size, _mix(31) ^ _mix(epoch))
assert list(
shard_positions(size, seed=31, epoch=epoch, shuffle=True, rank=rank, world_size=world)
) == [order(i) for i in range(rank, size, world)]


def test_first_outputs_only_evaluate_bounded_chunks(monkeypatch):
evaluated = []
original = _Permutation.many

def bounded(self, positions):
assert len(positions) <= 4096
evaluated.append(len(positions))
return original(self, positions)

monkeypatch.setattr(_Permutation, "many", bounded)
iterator = shard_positions(2**40, shuffle=True, rank=2, world_size=7)
assert evaluated == []
assert len(list(islice(iterator, 4100))) == 4100
assert evaluated == [4096, 4096]


@pytest.mark.parametrize("from_table", [False, True])
@pytest.mark.parametrize("rank,world", [(0, 1), (2, 3), (10, 11)])
def test_task_delivery_keeps_scalar_order(from_table, rank, world):
from kumo.pytorch.api import InMemoryEngine, prepare
from tests.test_anchor_tables import DATASET, _contract, _requests_for, _scores, _table

requests = _requests_for("train")
seed, epoch = 31, 3
scalar = _Permutation(len(requests), _mix(seed) ^ _mix(epoch))
expected = [float(requests[scalar(i)].entity_id) for i in range(rank, len(requests), world)]
with prepare(_contract(), DATASET, InMemoryEngine()) as plan:
with plan.materialize(_table(), fit_split="train") as task:
selection = {"split": "train"} if from_table else {"requests": requests}
delivered = task.batches(
**selection,
batch_size=3,
seed=seed,
epoch=epoch,
shuffle=True,
rank=rank,
world_size=world,
)
assert _scores(delivered) == expected
Loading