From ed41319efc9f1bdcdcc7b92e07bbcab5ebcd38b4 Mon Sep 17 00:00:00 2001 From: "Michael J. Williams" Date: Fri, 13 Nov 2026 10:45:16 +0100 Subject: [PATCH 1/3] ENH: add integer, permutation, exponential and Poisson sampling --- CHANGELOG.md | 3 + README.md | 50 +++++- src/orng/_utils.py | 42 ++++- src/orng/backends/cupy.py | 127 ++++++++++++- src/orng/backends/jax.py | 131 +++++++++++++- src/orng/backends/numpy.py | 118 +++++++++++- src/orng/backends/torch.py | 127 ++++++++++++- src/orng/functional.py | 32 ++++ src/orng/orng.py | 133 ++++++++++++++ tests/test_backends.py | 355 +++++++++++++++++++++++++++++++++++++ 10 files changed, 1111 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bb5eec8..bb4bd20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,9 @@ are included in the corresponding stable release. ### Added +- `integers`, `permutation`, `exponential`, and `poisson` in the object and + functional APIs for all four backends, including shape, dtype, RNG-state, + checkpoint replay, and JAX compilation support. - Pixi development environments for NumPy, JAX, CPU PyTorch, and CUDA CuPy, with test, lint, formatting, and type-check tasks used locally and in CI. ([#17](https://github.com/sequince-dev/orng/pull/17)) diff --git a/README.md b/README.md index db9a8e5..f58de6b 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,10 @@ generators. It mirrors a subset of the `numpy.random.Generator` API: - `normal` - `choice` - `gamma` +- `integers` +- `permutation` +- `exponential` +- `poisson` letting you pick the underlying backend at runtime. The following backends are currently supported: @@ -44,6 +48,10 @@ from orng import RandomGenerator rng = RandomGenerator(backend="numpy", seed=42) samples = rng.normal(loc=0.0, scale=1.0, size=5) uniform = rng.uniform(low=-1.0, high=1.0, size=(2, 2)) +indices = rng.integers(0, 10, size=5) +shuffled = rng.permutation(10) +waiting_times = rng.exponential(scale=2.0, size=5) +counts = rng.poisson(lam=3.0, size=5) ``` The backend module is imported lazily. If the requested library is missing, @@ -107,6 +115,45 @@ Supported functional methods: - `normal` - `choice` - `gamma` +- `integers` +- `permutation` +- `exponential` +- `poisson` + +`integers(low, high=None, size=None, dtype=None)` uses scalar integer bounds +and a half-open interval: `low` is inclusive and `high` is exclusive. With +only one bound, it samples from zero up to that bound. Both bounds must fit +in the requested signed `int32` or `int64` dtype. Array-valued bounds and the +NumPy `endpoint` option are not supported. + +`permutation(x, axis=0)` returns a shuffled copy of an array, or a permuted +`arange(x)` for a non-negative integer. It applies the same permutation to all +slices along the selected axis and preserves the input array's dtype. + +For `exponential(scale=1.0, size=None, dtype=None)` and +`poisson(lam=1.0, size=None, dtype=None)`, `size` specifies the full output +shape, and parameter arrays must broadcast to that shape. When `size=None`, +the parameter shape determines the output. Scale and rate parameters must +be finite and non-negative; zero produces zero samples. Poisson rates must +remain below the output integer limit with a ten-standard-deviation margin. +Exponential uses the scale (mean), rather than its reciprocal rate, and supports +`float32` and `float64` output. Poisson supports `int32` and `int64` output. + +The new integer-valued methods default to `int64` on NumPy, CuPy, and PyTorch; +JAX follows its X64 configuration. Exponential defaults to `float64` on NumPy +and CuPy and `float32` on PyTorch and JAX. Explicit 64-bit dtypes on JAX require +X64 mode. Under JAX `jit`, integer bounds, output shapes, and permutation axes +must be static; array-valued scale and rate parameters can be dynamic and must +satisfy their constraints before the compiled call. + +The functional versions take `state` first and return `(sample, next_state)`: + +```python +indices, state = backend.integers(state, low=0, high=10, size=(5,)) +shuffled, state = backend.permutation(state, 10) +waiting_times, state = backend.exponential(state, scale=2.0, size=(5,)) +counts, state = backend.poisson(state, lam=3.0, size=(5,)) +``` ### JAX Compilation Example @@ -146,8 +193,7 @@ inputs: If `generator=None`, ORNG creates a new backend-native state from `seed`. If `seed=None`, the backend chooses a fresh random seed using its usual behavior. -The `state` value passed into `random`, `uniform`, `normal`, `choice`, and -`gamma` also matches the backend: +The `state` value passed into every sampling method also matches the backend: | Backend | `pure=True` state | `pure=False` state | |---------|-------------------|--------------------| diff --git a/src/orng/_utils.py b/src/orng/_utils.py index 6093af1..5e46233 100644 --- a/src/orng/_utils.py +++ b/src/orng/_utils.py @@ -1,7 +1,9 @@ from __future__ import annotations import math -from typing import Sequence, Tuple +import operator +from numbers import Real +from typing import Any, Sequence, Tuple SizeLike = int | Sequence[int] | None @@ -26,4 +28,42 @@ def total_size(shape: Tuple[int, ...]) -> int: return math.prod(shape) +def integer_bounds( + low: int, high: int | None, minimum: int, maximum: int +) -> tuple[int, int]: + """Validate scalar integer bounds before a backend can clip or wrap them.""" + lower = operator.index(low) + upper = operator.index(high) if high is not None else lower + if high is None: + lower = 0 + if lower >= upper: + raise ValueError("low must be less than high.") + if lower < minimum or upper > maximum: + raise ValueError("Integer bounds must fit in the requested dtype.") + return lower, upper + + +def normalize_axis(axis: int, ndim: int) -> int: + """Validate an axis without accepting out-of-range values modulo ndim.""" + axis = operator.index(axis) + if not -ndim <= axis < ndim: + raise ValueError("axis is out of bounds for the input array.") + return axis % ndim + + +def validate_nonnegative_scalar(value: Any, name: str) -> None: + """Reject invalid Python scalar parameters without converting JAX tracers.""" + if isinstance(value, Real) and (value < 0 or not math.isfinite(value)): + raise ValueError(f"{name} must be finite and non-negative.") + + +def poisson_rate_limit(lam: Any, maximum: int) -> float: + """Reserve ten standard deviations below the output integer limit.""" + validate_nonnegative_scalar(lam, "lam") + limit = maximum - 10 * math.sqrt(maximum) + if isinstance(lam, Real) and float(lam) > limit: + raise ValueError("lam is too large for the requested dtype.") + return limit + + __all__ = ["SizeLike", "normalize_shape", "total_size"] diff --git a/src/orng/backends/cupy.py b/src/orng/backends/cupy.py index 5834021..f61d473 100644 --- a/src/orng/backends/cupy.py +++ b/src/orng/backends/cupy.py @@ -2,9 +2,17 @@ import copy from collections.abc import Mapping +from numbers import Integral from typing import Any -from .._utils import SizeLike +from .._utils import ( + SizeLike, + integer_bounds, + normalize_axis, + normalize_shape, + poisson_rate_limit, + validate_nonnegative_scalar, +) class CuPyBackend: @@ -12,6 +20,32 @@ def __init__(self, *, seed: int | None, generator: Any | None) -> None: self._impl = CuPyFunctionalBackend(pure=False) self._state = self._impl.init_state(seed=seed, generator=generator) + def integers( + self, *, low: int, high: int | None, size: SizeLike, dtype: Any | None + ) -> Any: + result, self._state = self._impl.integers( + self._state, low=low, high=high, size=size, dtype=dtype + ) + return result + + def permutation(self, x: int | Any, *, axis: int) -> Any: + result, self._state = self._impl.permutation(self._state, x, axis=axis) + return result + + def exponential( + self, *, scale: Any, size: SizeLike, dtype: Any | None + ) -> Any: + result, self._state = self._impl.exponential( + self._state, scale=scale, size=size, dtype=dtype + ) + return result + + def poisson(self, *, lam: Any, size: SizeLike, dtype: Any | None) -> Any: + result, self._state = self._impl.poisson( + self._state, lam=lam, size=size, dtype=dtype + ) + return result + def random(self, *, size: SizeLike, dtype: Any | None) -> Any: result, self._state = self._impl.random( self._state, @@ -169,6 +203,97 @@ def _result_and_next_state(self, gen: Any, result: Any) -> tuple[Any, Any]: return result, copy.deepcopy(gen.bit_generator.state) return result, gen + def integers( + self, + state: Any, + *, + low: int, + high: int | None = None, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + xp = self._cupy + sample_dtype = xp.dtype(dtype if dtype is not None else xp.int64) + if sample_dtype not in (xp.dtype(xp.int32), xp.dtype(xp.int64)): + raise TypeError("dtype must be int32 or int64.") + limits = xp.iinfo(sample_dtype) + low, high = integer_bounds(low, high, int(limits.min), int(limits.max)) + gen = self._generator_from_state(state) + result = gen.integers( + low, high, size=normalize_shape(size), dtype=sample_dtype + ) + return self._result_and_next_state(gen, result) + + def exponential( + self, + state: Any, + *, + scale: Any = 1.0, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + xp = self._cupy + sample_dtype = xp.dtype(dtype if dtype is not None else xp.float64) + if sample_dtype not in (xp.dtype(xp.float32), xp.dtype(xp.float64)): + raise TypeError("dtype must be float32 or float64.") + validate_nonnegative_scalar(scale, "scale") + parameter = xp.asarray(scale) + if bool(xp.any((parameter < 0) | ~xp.isfinite(parameter))): + raise ValueError("scale must be finite and non-negative.") + shape = None if size is None else normalize_shape(size) + gen = self._generator_from_state(state) + result = gen.exponential(scale=parameter, size=shape) + result = xp.asarray(result, dtype=sample_dtype) + return self._result_and_next_state(gen, result) + + def poisson( + self, + state: Any, + *, + lam: Any = 1.0, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + xp = self._cupy + sample_dtype = xp.dtype(dtype if dtype is not None else xp.int64) + if sample_dtype not in (xp.dtype(xp.int32), xp.dtype(xp.int64)): + raise TypeError("dtype must be int32 or int64.") + limit = poisson_rate_limit(lam, int(xp.iinfo(sample_dtype).max)) + parameter = xp.asarray(lam) + if bool(xp.any((parameter < 0) | ~xp.isfinite(parameter))): + raise ValueError("lam must be finite and non-negative.") + if bool(xp.any(parameter > limit)): + raise ValueError("lam is too large for the requested dtype.") + shape = None if size is None else normalize_shape(size) + gen = self._generator_from_state(state) + result = gen.poisson(lam=parameter, size=shape) + result = xp.asarray(result, dtype=sample_dtype) + return self._result_and_next_state(gen, result) + + def permutation( + self, state: Any, x: int | Any, *, axis: int = 0 + ) -> tuple[Any, Any]: + cp = self._cupy + if isinstance(x, Integral): + if x < 0: + raise ValueError("x must be non-negative.") + domain = cp.arange(x) + else: + domain = cp.asarray(x) + axis = normalize_axis(axis, domain.ndim) + gen = self._generator_from_state(state) + n = domain.shape[axis] + # Generator has no permutation method. Reject tied random keys so + # sorting does not favour any input ordering when keys collide. + while True: + keys = gen.random(n, dtype=cp.float64) + indices = cp.argsort(keys) + ordered = keys[indices] + if not bool(cp.any(ordered[1:] == ordered[:-1])): + break + result = cp.take(domain, indices, axis=axis) + return self._result_and_next_state(gen, result) + def random( self, state: Any, diff --git a/src/orng/backends/jax.py b/src/orng/backends/jax.py index 3015106..8819304 100644 --- a/src/orng/backends/jax.py +++ b/src/orng/backends/jax.py @@ -2,9 +2,17 @@ import secrets from collections.abc import Mapping +from numbers import Integral from typing import Any -from .._utils import SizeLike, normalize_shape +from .._utils import ( + SizeLike, + integer_bounds, + normalize_axis, + normalize_shape, + poisson_rate_limit, + validate_nonnegative_scalar, +) class JAXBackend: @@ -12,6 +20,32 @@ def __init__(self, *, seed: int | None, key: Any | None) -> None: self._impl = JAXFunctionalBackend() self._state = self._impl.init_state(seed=seed, generator=key) + def integers( + self, *, low: int, high: int | None, size: SizeLike, dtype: Any | None + ) -> Any: + result, self._state = self._impl.integers( + self._state, low=low, high=high, size=size, dtype=dtype + ) + return result + + def permutation(self, x: int | Any, *, axis: int) -> Any: + result, self._state = self._impl.permutation(self._state, x, axis=axis) + return result + + def exponential( + self, *, scale: Any, size: SizeLike, dtype: Any | None + ) -> Any: + result, self._state = self._impl.exponential( + self._state, scale=scale, size=size, dtype=dtype + ) + return result + + def poisson(self, *, lam: Any, size: SizeLike, dtype: Any | None) -> Any: + result, self._state = self._impl.poisson( + self._state, lam=lam, size=size, dtype=dtype + ) + return result + def random(self, *, size: SizeLike, dtype: Any | None) -> Any: result, self._state = self._impl.random( self._state, @@ -141,6 +175,101 @@ def init_state(self, *, seed: int | None, generator: Any | None) -> Any: seed = secrets.randbits(32) return self._jax.random.key(seed) + def integers( + self, + state: Any, + *, + low: int, + high: int | None = None, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + jnp = self._jnp + sample_dtype = jnp.dtype(dtype if dtype is not None else int) + if sample_dtype not in (jnp.dtype(jnp.int32), jnp.dtype(jnp.int64)): + raise TypeError("dtype must be int32 or int64.") + canonical_dtype = self._jax.dtypes.canonicalize_dtype(sample_dtype) + if dtype is not None and canonical_dtype != sample_dtype: + raise ValueError("Enable JAX X64 mode to request a 64-bit dtype.") + sample_dtype = canonical_dtype + limits = jnp.iinfo(sample_dtype) + low, high = integer_bounds(low, high, int(limits.min), int(limits.max)) + key, next_state = self._jax.random.split(state) + result = self._jax.random.randint( + key, normalize_shape(size), low, high, dtype=sample_dtype + ) + return result, next_state + + def permutation( + self, state: Any, x: int | Any, *, axis: int = 0 + ) -> tuple[Any, Any]: + if isinstance(x, Integral): + if x < 0: + raise ValueError("x must be non-negative.") + domain = self._jnp.arange(x) + else: + domain = self._jnp.asarray(x) + axis = normalize_axis(axis, domain.ndim) + key, next_state = self._jax.random.split(state) + result = self._jax.random.permutation(key, domain, axis=axis) + return result, next_state + + def exponential( + self, + state: Any, + *, + scale: Any = 1.0, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + jnp = self._jnp + sample_dtype = jnp.dtype(dtype if dtype is not None else jnp.float32) + if sample_dtype not in ( + jnp.dtype(jnp.float32), + jnp.dtype(jnp.float64), + ): + raise TypeError("dtype must be float32 or float64.") + validate_nonnegative_scalar(scale, "scale") + canonical_dtype = self._jax.dtypes.canonicalize_dtype(sample_dtype) + if dtype is not None and canonical_dtype != sample_dtype: + raise ValueError("Enable JAX X64 mode to request a 64-bit dtype.") + sample_dtype = canonical_dtype + scales = jnp.asarray(scale, dtype=sample_dtype) + shape = scales.shape if size is None else normalize_shape(size) + scales = jnp.broadcast_to(scales, shape) + key, next_state = self._jax.random.split(state) + result = ( + self._jax.random.exponential(key, shape=shape, dtype=sample_dtype) + * scales + ) + return result, next_state + + def poisson( + self, + state: Any, + *, + lam: Any = 1.0, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + jnp = self._jnp + sample_dtype = jnp.dtype(dtype if dtype is not None else int) + if sample_dtype not in (jnp.dtype(jnp.int32), jnp.dtype(jnp.int64)): + raise TypeError("dtype must be int32 or int64.") + canonical_dtype = self._jax.dtypes.canonicalize_dtype(sample_dtype) + if dtype is not None and canonical_dtype != sample_dtype: + raise ValueError("Enable JAX X64 mode to request a 64-bit dtype.") + sample_dtype = canonical_dtype + poisson_rate_limit(lam, int(jnp.iinfo(sample_dtype).max)) + rates = jnp.asarray(lam) + shape = rates.shape if size is None else normalize_shape(size) + rates = jnp.broadcast_to(rates, shape) + key, next_state = self._jax.random.split(state) + result = self._jax.random.poisson( + key, rates, shape=shape, dtype=sample_dtype + ) + return result, next_state + def random( self, state: Any, diff --git a/src/orng/backends/numpy.py b/src/orng/backends/numpy.py index 0cf46cf..db70603 100644 --- a/src/orng/backends/numpy.py +++ b/src/orng/backends/numpy.py @@ -2,9 +2,17 @@ import copy from collections.abc import Mapping +from numbers import Integral from typing import Any -from .._utils import SizeLike +from .._utils import ( + SizeLike, + integer_bounds, + normalize_axis, + normalize_shape, + poisson_rate_limit, + validate_nonnegative_scalar, +) class NumPyBackend: @@ -12,6 +20,32 @@ def __init__(self, *, seed: int | None, generator: Any | None) -> None: self._impl = NumPyFunctionalBackend(pure=False) self._state = self._impl.init_state(seed=seed, generator=generator) + def integers( + self, *, low: int, high: int | None, size: SizeLike, dtype: Any | None + ) -> Any: + result, self._state = self._impl.integers( + self._state, low=low, high=high, size=size, dtype=dtype + ) + return result + + def permutation(self, x: int | Any, *, axis: int) -> Any: + result, self._state = self._impl.permutation(self._state, x, axis=axis) + return result + + def exponential( + self, *, scale: Any, size: SizeLike, dtype: Any | None + ) -> Any: + result, self._state = self._impl.exponential( + self._state, scale=scale, size=size, dtype=dtype + ) + return result + + def poisson(self, *, lam: Any, size: SizeLike, dtype: Any | None) -> Any: + result, self._state = self._impl.poisson( + self._state, lam=lam, size=size, dtype=dtype + ) + return result + def random(self, *, size: SizeLike, dtype: Any | None) -> Any: result, self._state = self._impl.random( self._state, @@ -169,6 +203,88 @@ def _result_and_next_state(self, gen: Any, result: Any) -> tuple[Any, Any]: return result, copy.deepcopy(gen.bit_generator.state) return result, gen + def integers( + self, + state: Any, + *, + low: int, + high: int | None = None, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + xp = self._np + sample_dtype = xp.dtype(dtype if dtype is not None else xp.int64) + if sample_dtype not in (xp.dtype(xp.int32), xp.dtype(xp.int64)): + raise TypeError("dtype must be int32 or int64.") + limits = xp.iinfo(sample_dtype) + low, high = integer_bounds(low, high, int(limits.min), int(limits.max)) + gen = self._generator_from_state(state) + result = gen.integers( + low, high, size=normalize_shape(size), dtype=sample_dtype + ) + return self._result_and_next_state(gen, result) + + def exponential( + self, + state: Any, + *, + scale: Any = 1.0, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + xp = self._np + sample_dtype = xp.dtype(dtype if dtype is not None else xp.float64) + if sample_dtype not in (xp.dtype(xp.float32), xp.dtype(xp.float64)): + raise TypeError("dtype must be float32 or float64.") + validate_nonnegative_scalar(scale, "scale") + parameter = xp.asarray(scale) + if bool(xp.any((parameter < 0) | ~xp.isfinite(parameter))): + raise ValueError("scale must be finite and non-negative.") + shape = None if size is None else normalize_shape(size) + gen = self._generator_from_state(state) + result = gen.exponential(scale=parameter, size=shape) + result = xp.asarray(result, dtype=sample_dtype) + return self._result_and_next_state(gen, result) + + def poisson( + self, + state: Any, + *, + lam: Any = 1.0, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + xp = self._np + sample_dtype = xp.dtype(dtype if dtype is not None else xp.int64) + if sample_dtype not in (xp.dtype(xp.int32), xp.dtype(xp.int64)): + raise TypeError("dtype must be int32 or int64.") + limit = poisson_rate_limit(lam, int(xp.iinfo(sample_dtype).max)) + parameter = xp.asarray(lam) + if bool(xp.any((parameter < 0) | ~xp.isfinite(parameter))): + raise ValueError("lam must be finite and non-negative.") + if bool(xp.any(parameter > limit)): + raise ValueError("lam is too large for the requested dtype.") + shape = None if size is None else normalize_shape(size) + gen = self._generator_from_state(state) + result = gen.poisson(lam=parameter, size=shape) + result = xp.asarray(result, dtype=sample_dtype) + return self._result_and_next_state(gen, result) + + def permutation( + self, state: Any, x: int | Any, *, axis: int = 0 + ) -> tuple[Any, Any]: + np = self._np + if isinstance(x, Integral): + if x < 0: + raise ValueError("x must be non-negative.") + domain = np.arange(x) + else: + domain = np.asarray(x) + axis = normalize_axis(axis, domain.ndim) + gen = self._generator_from_state(state) + result = gen.permutation(domain, axis=axis) + return self._result_and_next_state(gen, result) + def random( self, state: Any, diff --git a/src/orng/backends/torch.py b/src/orng/backends/torch.py index 9f0d76c..ee0c020 100644 --- a/src/orng/backends/torch.py +++ b/src/orng/backends/torch.py @@ -2,9 +2,18 @@ from collections.abc import Mapping from dataclasses import dataclass +from numbers import Integral from typing import Any -from .._utils import SizeLike, normalize_shape, total_size +from .._utils import ( + SizeLike, + integer_bounds, + normalize_axis, + normalize_shape, + poisson_rate_limit, + total_size, + validate_nonnegative_scalar, +) class TorchBackend: @@ -18,6 +27,32 @@ def __init__( self._impl = TorchFunctionalBackend(device=device, pure=False) self._state = self._impl.init_state(seed=seed, generator=generator) + def integers( + self, *, low: int, high: int | None, size: SizeLike, dtype: Any | None + ) -> Any: + result, self._state = self._impl.integers( + self._state, low=low, high=high, size=size, dtype=dtype + ) + return result + + def permutation(self, x: int | Any, *, axis: int) -> Any: + result, self._state = self._impl.permutation(self._state, x, axis=axis) + return result + + def exponential( + self, *, scale: Any, size: SizeLike, dtype: Any | None + ) -> Any: + result, self._state = self._impl.exponential( + self._state, scale=scale, size=size, dtype=dtype + ) + return result + + def poisson(self, *, lam: Any, size: SizeLike, dtype: Any | None) -> Any: + result, self._state = self._impl.poisson( + self._state, lam=lam, size=size, dtype=dtype + ) + return result + def random(self, *, size: SizeLike, dtype: Any | None) -> Any: result, self._state = self._impl.random( self._state, @@ -199,6 +234,96 @@ def _result_and_next_state( ), ) + def integers( + self, + state: Any, + *, + low: int, + high: int | None = None, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + torch = self._torch + sample_dtype = dtype if dtype is not None else torch.int64 + if sample_dtype not in (torch.int32, torch.int64): + raise TypeError("dtype must be int32 or int64.") + limits = torch.iinfo(sample_dtype) + low, high = integer_bounds(low, high, limits.min, limits.max) + shape = normalize_shape(size) + gen, device = self._generator_from_state(state) + result = torch.randint( + low, high, shape, generator=gen, device=device, dtype=sample_dtype + ) + return self._result_and_next_state(gen, state, result) + + def permutation( + self, state: Any, x: int | Any, *, axis: int = 0 + ) -> tuple[Any, Any]: + torch = self._torch + gen, device = self._generator_from_state(state) + if isinstance(x, Integral): + if x < 0: + raise ValueError("x must be non-negative.") + domain = torch.arange(x, device=device) + else: + domain = torch.as_tensor(x, device=device) + axis = normalize_axis(axis, domain.ndim) + indices = torch.randperm( + domain.shape[axis], generator=gen, device=device + ) + result = domain.index_select(axis, indices) + return self._result_and_next_state(gen, state, result) + + def exponential( + self, + state: Any, + *, + scale: Any = 1.0, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + torch = self._torch + sample_dtype = dtype if dtype is not None else torch.float32 + if sample_dtype not in (torch.float32, torch.float64): + raise TypeError("dtype must be float32 or float64.") + validate_nonnegative_scalar(scale, "scale") + gen, device = self._generator_from_state(state) + scales = torch.as_tensor(scale, device=device, dtype=sample_dtype) + if bool(torch.any((scales < 0) | ~torch.isfinite(scales))): + raise ValueError("scale must be finite and non-negative.") + shape = scales.shape if size is None else normalize_shape(size) + scales = torch.broadcast_to(scales, shape) + result = torch.empty(shape, device=device, dtype=sample_dtype) + result.exponential_(generator=gen) + result = result * scales + return self._result_and_next_state(gen, state, result) + + def poisson( + self, + state: Any, + *, + lam: Any = 1.0, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, Any]: + torch = self._torch + sample_dtype = dtype if dtype is not None else torch.int64 + if sample_dtype not in (torch.int32, torch.int64): + raise TypeError("dtype must be int32 or int64.") + limit = poisson_rate_limit(lam, torch.iinfo(sample_dtype).max) + gen, device = self._generator_from_state(state) + # Poisson draws are floating point in PyTorch. Float64 avoids rounding + # integer counts above 2**24 before conversion to the output dtype. + rates = torch.as_tensor(lam, device=device, dtype=torch.float64) + if bool(torch.any((rates < 0) | ~torch.isfinite(rates))): + raise ValueError("lam must be finite and non-negative.") + if bool(torch.any(rates > limit)): + raise ValueError("lam is too large for the requested dtype.") + shape = rates.shape if size is None else normalize_shape(size) + rates = torch.broadcast_to(rates, shape) + result = torch.poisson(rates, generator=gen).to(dtype=sample_dtype) + return self._result_and_next_state(gen, state, result) + def random( self, state: Any, diff --git a/src/orng/functional.py b/src/orng/functional.py index 6e66cc7..f48cc40 100644 --- a/src/orng/functional.py +++ b/src/orng/functional.py @@ -85,6 +85,38 @@ def init_state( generator: FunctionalGenerator, ) -> FunctionalState: ... + def integers( + self, + state: FunctionalState, + *, + low: int, + high: int | None = None, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, FunctionalState]: ... + + def permutation( + self, state: FunctionalState, x: int | Any, *, axis: int = 0 + ) -> tuple[Any, FunctionalState]: ... + + def exponential( + self, + state: FunctionalState, + *, + scale: Any = 1.0, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, FunctionalState]: ... + + def poisson( + self, + state: FunctionalState, + *, + lam: Any = 1.0, + size: SizeLike = None, + dtype: Any | None = None, + ) -> tuple[Any, FunctionalState]: ... + def random( self, state: FunctionalState, diff --git a/src/orng/orng.py b/src/orng/orng.py index 8a180e0..d937fee 100644 --- a/src/orng/orng.py +++ b/src/orng/orng.py @@ -27,6 +27,25 @@ def state_dict(self) -> dict[str, Any]: ... def load_state_dict(self, state: Mapping[str, Any]) -> None: ... + def integers( + self, + *, + low: int, + high: int | None, + size: SizeLike, + dtype: Any | None, + ) -> Any: ... + + def permutation(self, x: int | Any, *, axis: int) -> Any: ... + + def exponential( + self, *, scale: Any, size: SizeLike, dtype: Any | None + ) -> Any: ... + + def poisson( + self, *, lam: Any, size: SizeLike, dtype: Any | None + ) -> Any: ... + def random(self, *, size: SizeLike, dtype: Any | None) -> Any: ... def uniform( @@ -122,6 +141,120 @@ def __post_init__(self) -> None: device=self.device, ) + def integers( + self, + low: int, + high: int | None = None, + size: SizeLike = None, + *, + dtype: Any | None = None, + ) -> Any: + """Draw integers from the half-open interval ``[low, high)``. + + Parameters + ---------- + low : int + Inclusive lower bound, or exclusive upper bound when high is None. + high : int or None, optional + Exclusive upper bound. Both bounds must fit in the output dtype. + size : int, sequence of int, or None, optional + Output shape. None returns a scalar sample. + dtype : dtype or None, optional + Backend-native int32 or int64. Defaults to int64 except on JAX, + where the default integer dtype follows the JAX X64 configuration. + + Returns + ------- + samples : array or scalar + Integer samples with the requested shape and dtype. + """ + return self._impl.integers(low=low, high=high, size=size, dtype=dtype) + + def permutation(self, x: int | Any, axis: int = 0) -> Any: + """Return a shuffled copy of a range or array. + + Parameters + ---------- + x : int or array_like + Non-negative range length, or an array with at least one dimension. + axis : int, optional + Axis to permute. All slices use the same permutation. For integer + input, only 0 and -1 are valid. + + Returns + ------- + shuffled : array + A copy with the input shape and dtype, or a permuted arange(x). + The input array is never modified. + """ + return self._impl.permutation(x, axis=axis) + + def exponential( + self, + scale: Any = 1.0, + size: SizeLike = None, + *, + dtype: Any | None = None, + ) -> Any: + """Draw samples from an exponential distribution. + + Parameters + ---------- + scale : float or array_like, optional + Finite, non-negative scale (the mean), not the rate. + size : int, sequence of int, or None, optional + Full output shape, to which scale must broadcast. When None, use + the parameter shape; scalar parameters return a scalar sample. + dtype : dtype or None, optional + Backend-native float32 or float64. Defaults to float64 for NumPy + and CuPy, and float32 for PyTorch and JAX. + + Returns + ------- + samples : array or scalar + Non-negative floating-point samples with the requested shape. + + Notes + ----- + JAX array parameters must satisfy the constraints before entering jit; + dynamic array values are not checked inside compiled sampling calls. + """ + return self._impl.exponential(scale=scale, size=size, dtype=dtype) + + def poisson( + self, + lam: Any = 1.0, + size: SizeLike = None, + *, + dtype: Any | None = None, + ) -> Any: + """Draw samples from a Poisson distribution. + + Parameters + ---------- + lam : float or array_like, optional + Finite, non-negative expected event count. Rates near the output + integer limit are rejected, reserving ten standard deviations. + JAX array inputs must also satisfy this bound before entering jit. + size : int, sequence of int, or None, optional + Full output shape, to which lam must broadcast. When None, use + the parameter shape; scalar parameters return a scalar sample. + dtype : dtype or None, optional + Backend-native int32 or int64. Defaults to int64 except on JAX, + where the default integer dtype follows the JAX X64 configuration. + + Returns + ------- + samples : array or scalar + Non-negative integer event counts with the requested shape. + + Notes + ----- + JAX array parameters must satisfy the constraints before entering jit; + dynamic array values are not checked inside compiled sampling calls. + """ + return self._impl.poisson(lam=lam, size=size, dtype=dtype) + def random( self, size: SizeLike = None, diff --git a/tests/test_backends.py b/tests/test_backends.py index d1dcd3d..2633490 100644 --- a/tests/test_backends.py +++ b/tests/test_backends.py @@ -1,5 +1,8 @@ from __future__ import annotations +from importlib import import_module +from typing import Any + import pytest from orng import RandomGenerator @@ -335,3 +338,355 @@ def test_choice_with_probabilities_and_no_replacement(backend_case): ) backend_case["assert_array"](without_replacement, shape=(3,), dtype=None) assert len(set(backend_case["to_list"](without_replacement))) == 3 + + +@pytest.fixture +def sampling_namespace(backend_name: str) -> Any: + return import_module( + "jax.numpy" if backend_name == "jax" else backend_name + ) + + +@pytest.fixture( + params=[ + ("integers", (), {"low": -3, "high": 8, "size": (4, 5)}), + ("permutation", (40,), {}), + ("exponential", (), {"scale": 2.0, "size": (4, 5)}), + ("poisson", (), {"lam": 3.0, "size": (4, 5)}), + ], + ids=["integers", "permutation", "exponential", "poisson"], +) +def new_sampling_method(request: Any) -> tuple[str, tuple, dict]: + return request.param + + +def _host_array(value: Any, name: str) -> Any: + np = import_module("numpy") + if name == "torch": + return value.cpu().numpy() + if name == "cupy": + return import_module("cupy").asnumpy(value) + return np.asarray(value) + + +def test_new_methods_checkpoint_and_state_advancement( + backend_name: str, new_sampling_method: tuple[str, tuple, dict] +) -> None: + np = import_module("numpy") + method, args, kwargs = new_sampling_method + rng = RandomGenerator(backend_name, seed=723) + snapshot = rng.state_dict() + first = getattr(rng, method)(*args, **kwargs) + second = getattr(rng, method)(*args, **kwargs) + assert not np.array_equal( + _host_array(first, backend_name), _host_array(second, backend_name) + ) + restored = RandomGenerator.from_state_dict(snapshot) + for expected in (first, second): + actual = getattr(restored, method)(*args, **kwargs) + np.testing.assert_array_equal( + _host_array(actual, backend_name), + _host_array(expected, backend_name), + ) + np.testing.assert_array_equal( + _host_array(rng.random(size=10), backend_name), + _host_array(restored.random(size=10), backend_name), + ) + + +@pytest.mark.parametrize("pure", [True, False]) +def test_new_functional_methods_thread_the_managed_state( + backend_name: str, + new_sampling_method: tuple[str, tuple, dict], + pure: bool, +) -> None: + from orng.functional import create_functional_backend + + if backend_name == "jax" and not pure: + pytest.skip("JAX has no mutable functional mode.") + np = import_module("numpy") + method, args, kwargs = new_sampling_method + backend = create_functional_backend(backend_name, pure=pure) + state = backend.init_state(seed=723, generator=None) + call = getattr(backend, method) + first, next_state = call(state, *args, **kwargs) + if pure: + replay, _ = call(state, *args, **kwargs) + np.testing.assert_array_equal( + _host_array(first, backend_name), _host_array(replay, backend_name) + ) + else: + assert next_state is state + second, next_state = call(next_state, *args, **kwargs) + assert not np.array_equal( + _host_array(first, backend_name), _host_array(second, backend_name) + ) + # The mutable object API and the functional API must use the same stream. + rng = RandomGenerator(backend_name, seed=723) + for expected in (first, second): + actual = getattr(rng, method)(*args, **kwargs) + np.testing.assert_array_equal( + _host_array(actual, backend_name), + _host_array(expected, backend_name), + ) + following, _ = backend.random(next_state, size=10) + np.testing.assert_array_equal( + _host_array(following, backend_name), + _host_array(rng.random(size=10), backend_name), + ) + + +@pytest.mark.parametrize("size", [None, (), 0, (2, 0), (3, 4)]) +def test_integers_shape_bounds_and_dtype( + rng: RandomGenerator, sampling_namespace: Any, size: Any +) -> None: + xp = sampling_namespace + result = rng.integers(-2, 3, size=size, dtype=xp.int32) + shape = ( + () if size is None else ((size,) if isinstance(size, int) else size) + ) + assert result.shape == shape + assert result.dtype == xp.int32 + assert bool(xp.all((result >= -2) & (result < 3))) + assert int(rng.integers(1)) == 0 + + +@pytest.mark.parametrize("low,high", [(0, None), (3, 3), (4, 2)]) +def test_integers_rejects_empty_intervals( + rng: RandomGenerator, low: int, high: int | None +) -> None: + with pytest.raises(ValueError, match="low must be less"): + rng.integers(low, high) + + +def test_integers_rejects_noninteger_and_overflowing_bounds( + rng: RandomGenerator, sampling_namespace: Any +) -> None: + with pytest.raises(TypeError): + invalid_low: Any = 1.5 + rng.integers(invalid_low, 4) + with pytest.raises(ValueError, match="bounds must fit"): + rng.integers(0, 2**32, dtype=sampling_namespace.int32) + + +@pytest.mark.parametrize( + "method,param", [("exponential", "scale"), ("poisson", "lam")] +) +def test_new_distributions_broadcast_to_output_shape( + rng: RandomGenerator, sampling_namespace: Any, method: str, param: str +) -> None: + xp = sampling_namespace + dtype = xp.float32 if method == "exponential" else xp.int32 + call = getattr(rng, method) + values = ( + xp.asarray([0.0, 2.0]) + if rng.backend != "torch" + else xp.tensor([0.0, 2.0]) + ) + result = call(**{param: values}, size=(5, 2), dtype=dtype) + assert result.shape == (5, 2) + assert result.dtype == dtype + assert bool(xp.all(result >= 0)) + assert bool(xp.all(result[:, 0] == 0)) + assert call(**{param: values}).shape == (2,) + assert call(**{param: 2.0}).shape == () + assert call(**{param: 2.0}, size=()).shape == () + assert call(**{param: values}, size=(0, 2)).shape == (0, 2) + with pytest.raises((ValueError, RuntimeError)): + call(**{param: values}, size=(3,)) + with pytest.raises((ValueError, RuntimeError)): + call(**{param: values}, size=()) + + +@pytest.mark.parametrize( + "method,param", [("exponential", "scale"), ("poisson", "lam")] +) +@pytest.mark.parametrize("value", [-1.0, float("nan"), float("inf")]) +def test_new_distributions_reject_invalid_scalar_parameters( + rng: RandomGenerator, method: str, param: str, value: float +) -> None: + with pytest.raises(ValueError, match="finite and non-negative"): + getattr(rng, method)(**{param: value}) + + +@pytest.mark.parametrize("method", ["integers", "poisson", "exponential"]) +def test_new_distributions_reject_invalid_dtypes( + rng: RandomGenerator, sampling_namespace: Any, method: str +) -> None: + kwargs = {"low": 3} if method == "integers" else {} + with pytest.raises(TypeError, match="dtype must be"): + getattr(rng, method)(**kwargs, dtype=bool) + + +def test_permutation_preserves_slices_and_input( + rng: RandomGenerator, sampling_namespace: Any +) -> None: + xp = sampling_namespace + np = import_module("numpy") + original = xp.arange(24).reshape(2, 3, 4) + shuffled = rng.permutation(original, axis=-2) + assert shuffled.shape == original.shape + assert shuffled.dtype == original.dtype + np.testing.assert_array_equal( + _host_array(original, rng.backend), np.arange(24).reshape(2, 3, 4) + ) + # Each column determines the same row permutation, across both batches. + host = _host_array(shuffled, rng.backend) + order = host[0, :, 0] // 4 + np.testing.assert_array_equal( + host, np.arange(24).reshape(2, 3, 4)[:, order, :] + ) + assert sorted(_host_array(rng.permutation(30), rng.backend)) == list( + range(30) + ) + assert rng.permutation(0).shape == (0,) + assert rng.permutation(original, axis=0).shape == original.shape + with pytest.raises(ValueError, match="non-negative"): + rng.permutation(-1) + with pytest.raises(ValueError, match="axis"): + rng.permutation(original, axis=3) + with pytest.raises(ValueError, match="axis"): + rng.permutation( + xp.asarray(1) if rng.backend != "torch" else xp.tensor(1) + ) + + +def test_new_distribution_moments(rng: RandomGenerator) -> None: + np = import_module("numpy") + n = 30000 + integers = _host_array(rng.integers(-2, 4, size=n), rng.backend) + assert abs(integers.mean() - 0.5) < 0.08 + counts = np.bincount(integers + 2, minlength=6) + assert np.all(np.abs(counts - n / 6) < 400) + exponential = _host_array(rng.exponential(scale=2.0, size=n), rng.backend) + # About six standard errors for the mean and a conservative variance bound. + assert abs(exponential.mean() - 2.0) < 0.08 + assert abs(exponential.var() - 4.0) < 0.4 + poisson = _host_array(rng.poisson(lam=4.0, size=n), rng.backend) + assert abs(poisson.mean() - 4.0) < 0.08 + assert abs(poisson.var() - 4.0) < 0.3 + + +def test_jax_new_methods_compile_with_dynamic_parameters() -> None: + jax = pytest.importorskip("jax") + jnp = pytest.importorskip("jax.numpy") + from orng.functional import create_functional_backend + + backend = create_functional_backend("jax") + state = backend.init_state(seed=987, generator=None) + + def step(key: Any, scale: Any, lam: Any, values: Any) -> tuple: + integers, key = backend.integers(key, low=-2, high=7, size=(3, 2)) + exponential, key = backend.exponential(key, scale=scale, size=(3, 2)) + poisson, key = backend.poisson(key, lam=lam, size=(3, 2)) + shuffled, key = backend.permutation(key, values, axis=1) + return integers, exponential, poisson, shuffled, key + + parameters = ( + jnp.array([0.0, 2.0]), + jnp.array([0.0, 4.0]), + jnp.arange(6).reshape(2, 3), + ) + expected = step(state, *parameters) + actual = jax.jit(step)(state, *parameters) + for eager, compiled in zip(expected[:-1], actual[:-1]): + assert bool(jnp.allclose(eager, compiled, rtol=1e-6, atol=1e-6)) + assert bool( + jnp.array_equal( + jax.random.key_data(expected[-1]), jax.random.key_data(actual[-1]) + ) + ) + assert bool(jnp.all(actual[1][:, 0] == 0)) + assert bool(jnp.all(actual[2][:, 0] == 0)) + + +@pytest.mark.parametrize("enabled", [False, True]) +def test_jax_new_methods_respect_x64_configuration(enabled: bool) -> None: + jax = pytest.importorskip("jax") + jnp = pytest.importorskip("jax.numpy") + previous = jax.config.x64_enabled + jax.config.update("jax_enable_x64", enabled) + try: + rng = RandomGenerator("jax", seed=5) + if not enabled: + for method, kwargs in [ + ("integers", {"low": 5}), + ("poisson", {}), + ("exponential", {}), + ]: + dtype = jnp.float64 if method == "exponential" else jnp.int64 + with pytest.raises(ValueError, match="X64"): + getattr(rng, method)(**kwargs, dtype=dtype) + else: + assert rng.integers(5, size=3, dtype=jnp.int64).dtype == jnp.int64 + assert rng.poisson(size=3, dtype=jnp.int64).dtype == jnp.int64 + assert ( + rng.exponential(size=3, dtype=jnp.float64).dtype == jnp.float64 + ) + assert rng.integers(5).dtype == jnp.int64 + assert rng.poisson().dtype == jnp.int64 + finally: + jax.config.update("jax_enable_x64", previous) + + +@pytest.mark.parametrize("dtype_name", ["int64", "float64"]) +def test_new_methods_support_64_bit_dtypes( + rng: RandomGenerator, sampling_namespace: Any, dtype_name: str +) -> None: + if rng.backend == "jax": + pytest.skip("JAX X64 modes are covered separately.") + xp = sampling_namespace + if dtype_name == "int64": + assert rng.integers(5, size=3, dtype=xp.int64).dtype == xp.int64 + assert rng.poisson(size=3, dtype=xp.int64).dtype == xp.int64 + else: + assert rng.exponential(size=3, dtype=xp.float64).dtype == xp.float64 + + +def test_cupy_permutation_retries_tied_keys(monkeypatch: Any) -> None: + import sys + + from numpy.random import Generator + + np = import_module("numpy") + from orng.backends.cupy import CuPyFunctionalBackend + + class TiedGenerator(Generator): + calls = 0 + + def random(self, size: Any = None, dtype: Any = None) -> Any: + self.calls += 1 + return np.array( + [0.1, 0.1, 0.2] if self.calls == 1 else [0.7, 0.2, 0.4] + ) + + monkeypatch.setitem(sys.modules, "cupy", np) + generator = TiedGenerator(np.random.PCG64(1)) + backend = CuPyFunctionalBackend(pure=False) + state = backend.init_state(seed=None, generator=generator) + result, next_state = backend.permutation(state, 3) + np.testing.assert_array_equal(result, [1, 2, 0]) + assert generator.calls == 2 + assert next_state is state + + +def test_torch_new_methods_keep_samples_on_cuda( + new_sampling_method: tuple[str, tuple, dict], +) -> None: + torch = pytest.importorskip("torch") + if not torch.cuda.is_available(): + pytest.skip("PyTorch CUDA is unavailable.") + method, args, kwargs = new_sampling_method + rng = RandomGenerator("torch", seed=723, device="cuda") + result = getattr(rng, method)(*args, **kwargs) + assert result.device.type == "cuda" + + +def test_poisson_rejects_rates_that_would_overflow( + rng: RandomGenerator, sampling_namespace: Any +) -> None: + with pytest.raises(ValueError, match="too large"): + rng.poisson(lam=2**32, dtype=sampling_namespace.int32) + if rng.backend != "jax": + with pytest.raises(ValueError, match="too large"): + rng.poisson(lam=[1.0, 2**32], dtype=sampling_namespace.int32) From 942c7c690f9246949db96817b4299a1d2262cb2b Mon Sep 17 00:00:00 2001 From: "Michael J. Williams" Date: Fri, 13 Nov 2026 10:52:00 +0100 Subject: [PATCH 2/3] TST: name sampling tests after their behavior --- tests/test_backends.py | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/tests/test_backends.py b/tests/test_backends.py index 2633490..5596ff1 100644 --- a/tests/test_backends.py +++ b/tests/test_backends.py @@ -356,7 +356,7 @@ def sampling_namespace(backend_name: str) -> Any: ], ids=["integers", "permutation", "exponential", "poisson"], ) -def new_sampling_method(request: Any) -> tuple[str, tuple, dict]: +def sampling_method(request: Any) -> tuple[str, tuple, dict]: return request.param @@ -369,11 +369,11 @@ def _host_array(value: Any, name: str) -> Any: return np.asarray(value) -def test_new_methods_checkpoint_and_state_advancement( - backend_name: str, new_sampling_method: tuple[str, tuple, dict] +def test_sampling_methods_checkpoint_and_state_advancement( + backend_name: str, sampling_method: tuple[str, tuple, dict] ) -> None: np = import_module("numpy") - method, args, kwargs = new_sampling_method + method, args, kwargs = sampling_method rng = RandomGenerator(backend_name, seed=723) snapshot = rng.state_dict() first = getattr(rng, method)(*args, **kwargs) @@ -395,9 +395,9 @@ def test_new_methods_checkpoint_and_state_advancement( @pytest.mark.parametrize("pure", [True, False]) -def test_new_functional_methods_thread_the_managed_state( +def test_functional_sampling_methods_thread_the_managed_state( backend_name: str, - new_sampling_method: tuple[str, tuple, dict], + sampling_method: tuple[str, tuple, dict], pure: bool, ) -> None: from orng.functional import create_functional_backend @@ -405,7 +405,7 @@ def test_new_functional_methods_thread_the_managed_state( if backend_name == "jax" and not pure: pytest.skip("JAX has no mutable functional mode.") np = import_module("numpy") - method, args, kwargs = new_sampling_method + method, args, kwargs = sampling_method backend = create_functional_backend(backend_name, pure=pure) state = backend.init_state(seed=723, generator=None) call = getattr(backend, method) @@ -472,7 +472,7 @@ def test_integers_rejects_noninteger_and_overflowing_bounds( @pytest.mark.parametrize( "method,param", [("exponential", "scale"), ("poisson", "lam")] ) -def test_new_distributions_broadcast_to_output_shape( +def test_distributions_broadcast_to_output_shape( rng: RandomGenerator, sampling_namespace: Any, method: str, param: str ) -> None: xp = sampling_namespace @@ -502,7 +502,7 @@ def test_new_distributions_broadcast_to_output_shape( "method,param", [("exponential", "scale"), ("poisson", "lam")] ) @pytest.mark.parametrize("value", [-1.0, float("nan"), float("inf")]) -def test_new_distributions_reject_invalid_scalar_parameters( +def test_distributions_reject_invalid_scalar_parameters( rng: RandomGenerator, method: str, param: str, value: float ) -> None: with pytest.raises(ValueError, match="finite and non-negative"): @@ -510,7 +510,7 @@ def test_new_distributions_reject_invalid_scalar_parameters( @pytest.mark.parametrize("method", ["integers", "poisson", "exponential"]) -def test_new_distributions_reject_invalid_dtypes( +def test_distributions_reject_invalid_dtypes( rng: RandomGenerator, sampling_namespace: Any, method: str ) -> None: kwargs = {"low": 3} if method == "integers" else {} @@ -551,7 +551,7 @@ def test_permutation_preserves_slices_and_input( ) -def test_new_distribution_moments(rng: RandomGenerator) -> None: +def test_sampling_distribution_moments(rng: RandomGenerator) -> None: np = import_module("numpy") n = 30000 integers = _host_array(rng.integers(-2, 4, size=n), rng.backend) @@ -567,7 +567,7 @@ def test_new_distribution_moments(rng: RandomGenerator) -> None: assert abs(poisson.var() - 4.0) < 0.3 -def test_jax_new_methods_compile_with_dynamic_parameters() -> None: +def test_jax_sampling_methods_compile_with_dynamic_parameters() -> None: jax = pytest.importorskip("jax") jnp = pytest.importorskip("jax.numpy") from orng.functional import create_functional_backend @@ -601,7 +601,7 @@ def step(key: Any, scale: Any, lam: Any, values: Any) -> tuple: @pytest.mark.parametrize("enabled", [False, True]) -def test_jax_new_methods_respect_x64_configuration(enabled: bool) -> None: +def test_jax_sampling_methods_respect_x64_configuration(enabled: bool) -> None: jax = pytest.importorskip("jax") jnp = pytest.importorskip("jax.numpy") previous = jax.config.x64_enabled @@ -630,7 +630,7 @@ def test_jax_new_methods_respect_x64_configuration(enabled: bool) -> None: @pytest.mark.parametrize("dtype_name", ["int64", "float64"]) -def test_new_methods_support_64_bit_dtypes( +def test_sampling_methods_support_64_bit_dtypes( rng: RandomGenerator, sampling_namespace: Any, dtype_name: str ) -> None: if rng.backend == "jax": @@ -670,13 +670,13 @@ def random(self, size: Any = None, dtype: Any = None) -> Any: assert next_state is state -def test_torch_new_methods_keep_samples_on_cuda( - new_sampling_method: tuple[str, tuple, dict], +def test_torch_sampling_methods_keep_samples_on_cuda( + sampling_method: tuple[str, tuple, dict], ) -> None: torch = pytest.importorskip("torch") if not torch.cuda.is_available(): pytest.skip("PyTorch CUDA is unavailable.") - method, args, kwargs = new_sampling_method + method, args, kwargs = sampling_method rng = RandomGenerator("torch", seed=723, device="cuda") result = getattr(rng, method)(*args, **kwargs) assert result.device.type == "cuda" From 1fd01bccbbb8d062844c9385ad080f1e4e822fe4 Mon Sep 17 00:00:00 2001 From: "Michael J. Williams" Date: Fri, 13 Nov 2026 10:55:03 +0100 Subject: [PATCH 3/3] DOC: keep sampling method details in API docstrings --- README.md | 38 -------------------------------------- 1 file changed, 38 deletions(-) diff --git a/README.md b/README.md index f58de6b..81d3e0a 100644 --- a/README.md +++ b/README.md @@ -49,9 +49,6 @@ rng = RandomGenerator(backend="numpy", seed=42) samples = rng.normal(loc=0.0, scale=1.0, size=5) uniform = rng.uniform(low=-1.0, high=1.0, size=(2, 2)) indices = rng.integers(0, 10, size=5) -shuffled = rng.permutation(10) -waiting_times = rng.exponential(scale=2.0, size=5) -counts = rng.poisson(lam=3.0, size=5) ``` The backend module is imported lazily. If the requested library is missing, @@ -120,41 +117,6 @@ Supported functional methods: - `exponential` - `poisson` -`integers(low, high=None, size=None, dtype=None)` uses scalar integer bounds -and a half-open interval: `low` is inclusive and `high` is exclusive. With -only one bound, it samples from zero up to that bound. Both bounds must fit -in the requested signed `int32` or `int64` dtype. Array-valued bounds and the -NumPy `endpoint` option are not supported. - -`permutation(x, axis=0)` returns a shuffled copy of an array, or a permuted -`arange(x)` for a non-negative integer. It applies the same permutation to all -slices along the selected axis and preserves the input array's dtype. - -For `exponential(scale=1.0, size=None, dtype=None)` and -`poisson(lam=1.0, size=None, dtype=None)`, `size` specifies the full output -shape, and parameter arrays must broadcast to that shape. When `size=None`, -the parameter shape determines the output. Scale and rate parameters must -be finite and non-negative; zero produces zero samples. Poisson rates must -remain below the output integer limit with a ten-standard-deviation margin. -Exponential uses the scale (mean), rather than its reciprocal rate, and supports -`float32` and `float64` output. Poisson supports `int32` and `int64` output. - -The new integer-valued methods default to `int64` on NumPy, CuPy, and PyTorch; -JAX follows its X64 configuration. Exponential defaults to `float64` on NumPy -and CuPy and `float32` on PyTorch and JAX. Explicit 64-bit dtypes on JAX require -X64 mode. Under JAX `jit`, integer bounds, output shapes, and permutation axes -must be static; array-valued scale and rate parameters can be dynamic and must -satisfy their constraints before the compiled call. - -The functional versions take `state` first and return `(sample, next_state)`: - -```python -indices, state = backend.integers(state, low=0, high=10, size=(5,)) -shuffled, state = backend.permutation(state, 10) -waiting_times, state = backend.exponential(state, scale=2.0, size=(5,)) -counts, state = backend.poisson(state, lam=3.0, size=(5,)) -``` - ### JAX Compilation Example ```python