mrpro.utils.RandomGenerator

class mrpro.utils.RandomGenerator[source]

Bases: object

Generate random numbers for various purposes.

Uses a fixed seed to ensure reproducibility.

Provides:
  • Scalar uniform random numbers:

    int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64, complex64, complex128

  • Tensor of uniform random numbers:

    int8_tensor, int16_tensor, int32_tensor, int64_tensor, uint8_tensor, float32_tensor, float64_tensor, complex64_tensor, complex128_tensor (Note: uint16, uint32, uint64 tensors are not yet supported by PyTorch)

  • Tuple of uniform random numbers:

    int8_tuple, int16_tuple, int32_tuple, int64_tuple, uint8_tuple, uint16_tuple, uint32_tuple, uint64_tuple, float32_tuple, float64_tuple, complex64_tuple, complex128_tuple

__init__(seed: int)[source]

Initialize the random generator with a fixed seed.

ascii(size: int) → str[source]

Generate a random ASCII string.

Parameters:

size (int) – Length of the string.

Returns:

Random ASCII string.

bool() → bool[source]

Generate a random boolean value.

Returns:

Random boolean.

complex128(low: float = 0, high: float = 1.0) → complex[source]

Generate a complex128 scalar with uniform amplitude in [low, high).

The phase is uniformly distributed in [-π, π].

Parameters:

  • low (float, default: 0) – Lower bound for amplitude (must be non-negative).

  • high (float, default: 1.0) – Upper bound for amplitude.

Returns:

Random complex128 number.

complex128_tensor(size: Sequence[int] | int = (1,), low: float = 0.0, high: float = 1.0) → Tensor[source]

Generate a complex128 tensor with uniform amplitude in [low, high).

The phase is uniformly distributed in [-π, π].

Parameters:

  • size (Sequence[int] | int, default: (1,)) – Shape of the output tensor.

  • low (float, default: 0.0) – Lower bound for amplitude (must be non-negative).

  • high (float, default: 1.0) – Upper bound for amplitude.

Returns:

Tensor of complex128 random numbers.

complex128_tuple(size: int, low: float = 0, high: float = 1) → tuple[complex, ...][source]

Generate a tuple of complex128 numbers with uniform amplitude in [low, high).

The phase is uniformly distributed in [-π, π].

Parameters:

  • size (int) – Number of elements.

  • low (float, default: 0) – Lower bound for amplitude (must be non-negative).

  • high (float, default: 1) – Upper bound for amplitude.

Returns:

Tuple of complex128 random numbers.

complex64(low: float = 0, high: float = 1.0) → complex[source]

Generate a complex64 scalar with uniform amplitude in [low, high).

The phase is uniformly distributed in [-π, π].

Parameters:

  • low (float, default: 0) – Lower bound for amplitude (must be non-negative).

  • high (float, default: 1.0) – Upper bound for amplitude.

Returns:

Random complex64 number.

complex64_tensor(size: Sequence[int] | int = (1,), low: float = 0.0, high: float = 1.0) → Tensor[source]

Generate a complex64 tensor with uniform amplitude in [low, high).

The phase is uniformly distributed in [-π, π].

Parameters:

  • size (Sequence[int] | int, default: (1,)) – Shape of the output tensor.

  • low (float, default: 0.0) – Lower bound for amplitude (must be non-negative).

  • high (float, default: 1.0) – Upper bound for amplitude.

Returns:

Tensor of complex64 random numbers.

complex64_tuple(size: int, low: float = 0, high: float = 1) → tuple[complex, ...][source]

Generate a tuple of complex64 numbers with uniform amplitude in [low, high).

The phase is uniformly distributed in [-π, π].

Parameters:

  • size (int) – Number of elements.

  • low (float, default: 0) – Lower bound for amplitude (must be non-negative).

  • high (float, default: 1) – Upper bound for amplitude.

Returns:

Tuple of complex64 random numbers.

float32(low: float = 0.0, high: float = 1.0) → float[source]

Generate a float32 scalar with uniform distribution in [low, high).

Parameters:

  • low (float, default: 0.0) – Lower bound.

  • high (float, default: 1.0) – Upper bound.

Returns:

Random float32 number.

float32_tensor(size: Sequence[int] | int = (1,), low: float = 0.0, high: float = 1.0) → Tensor[source]

Generate a float32 tensor with uniform distribution in [low, high).

Parameters:

  • size (Sequence[int] | int, default: (1,)) – Shape of the output tensor.

  • low (float, default: 0.0) – Lower bound.

  • high (float, default: 1.0) – Upper bound.

Returns:

Tensor of float32 random numbers.

float32_tuple(size: int, low: float = 0, high: float = 1) → tuple[float, ...][source]

Generate a tuple of float32 numbers with uniform distribution in [low, high).

Parameters:

  • size (int) – Number of elements.

  • low (float, default: 0) – Lower bound.

  • high (float, default: 1) – Upper bound.

Returns:

Tuple of float32 random numbers.

float64(low: float = 0.0, high: float = 1.0) → float[source]

Generate a float64 scalar with uniform distribution in [low, high).

Parameters:

  • low (float, default: 0.0) – Lower bound.

  • high (float, default: 1.0) – Upper bound.

Returns:

Random float64 number.

float64_tensor(size: Sequence[int] | int = (1,), low: float = 0.0, high: float = 1.0) → Tensor[source]

Generate a float64 tensor with uniform distribution in [low, high).

Parameters:

  • size (Sequence[int] | int, default: (1,)) – Shape of the output tensor.

  • low (float, default: 0.0) – Lower bound.

  • high (float, default: 1.0) – Upper bound.

Returns:

Tensor of float64 random numbers.

float64_tuple(size: int, low: float = 0, high: float = 1) → tuple[float, ...][source]

Generate a tuple of float64 numbers with uniform distribution in [low, high).

Parameters:

  • size (int) – Number of elements.

  • low (float, default: 0) – Lower bound.

  • high (float, default: 1) – Upper bound.

Returns:

Tuple of float64 random numbers.

gaussian_variable_density_samples(shape: Sequence[int], low: int, high: int, fwhm: float = float('inf'), always_sample: Sequence[int] = ()) → Tensor[source]

Generate Gaussian variable density samples.

Generates indices in [low, high[ with a gaussian weighting.

Parameters:

  • shape (Sequence[int]) – Shape of the output tensor. The generated indices are 1D and in the last dimension. All other dimensions are batch dimensions.

  • low (int) – Lower bound of the sampling domain.

  • high (int) – Upper bound of the sampling domain.

  • fwhm (float, default: float('inf')) – Full-width at half-maximum of the Gaussian.

  • always_sample (Sequence[int], default: ()) – indices that should always included in the samples. For example, range(-n_center//2, n_center//2)

Returns:

1D tensor of selected indices.

int16(low: int = -1 << 15, high: int = 1 << 15 - 1) → int[source]

Generate an int16 scalar with uniform distribution in [low, high).

Parameters:

  • low (int, default: -1 << 15) – Lower bound (inclusive).

  • high (int, default: 1 << 15 - 1) – Upper bound (exclusive).

Returns:

Random int16 number.

int16_tensor(size: Sequence[int] | int = (1,), low: int = -1 << 15, high: int = 1 << 15) → Tensor[source]

Generate an int16 tensor with uniform distribution in [low, high).

Parameters:

  • size (Sequence[int] | int, default: (1,)) – Shape of the output tensor.

  • low (int, default: -1 << 15) – Lower bound (inclusive).

  • high (int, default: 1 << 15) – Upper bound (exclusive).

Returns:

Tensor of int16 random numbers.

int16_tuple(size: int, low: int = -1 << 15, high: int = 1 << 15) → tuple[int, ...][source]

Generate a tuple of int16 numbers with uniform distribution in [low, high).

Parameters:

  • size (int) – Number of elements.

  • low (int, default: -1 << 15) – Lower bound (inclusive).

  • high (int, default: 1 << 15) – Upper bound (exclusive).

Returns:

Tuple of int16 random numbers.

int32(low: int = -1 << 31, high: int = 1 << 31 - 1) → int[source]

Generate an int32 scalar with uniform distribution in [low, high).

Parameters:

  • low (int, default: -1 << 31) – Lower bound (inclusive).

  • high (int, default: 1 << 31 - 1) – Upper bound (exclusive).

Returns:

Random int32 number.

int32_tensor(size: Sequence[int] | int = (1,), low: int = -1 << 31, high: int = 1 << 31) → Tensor[source]

Generate an int32 tensor with uniform distribution in [low, high).

Parameters:

  • size (Sequence[int] | int, default: (1,)) – Shape of the output tensor.

  • low (int, default: -1 << 31) – Lower bound (inclusive).

  • high (int, default: 1 << 31) – Upper bound (exclusive).

Returns:

Tensor of int32 random numbers.

int32_tuple(size: int, low: int = -1 << 31, high: int = 1 << 31) → tuple[int, ...][source]

Generate a tuple of int32 numbers with uniform distribution in [low, high).

Parameters:

  • size (int) – Number of elements.

  • low (int, default: -1 << 31) – Lower bound (inclusive).

  • high (int, default: 1 << 31) – Upper bound (exclusive).

Returns:

Tuple of int32 random numbers.

int64(low: int = -1 << 63, high: int = 1 << 63 - 1) → int[source]

Generate an int64 scalar with uniform distribution in [low, high).

Parameters:

  • low (int, default: -1 << 63) – Lower bound (inclusive).

  • high (int, default: 1 << 63 - 1) – Upper bound (exclusive).

Returns:

Random int64 number.

int64_tensor(size: Sequence[int] | int = (1,), low: int = -1 << 63, high: int = 1 << 63) → Tensor[source]

Generate an int64 tensor with uniform distribution in [low, high).

Parameters:

  • size (Sequence[int] | int, default: (1,)) – Shape of the output tensor.

  • low (int, default: -1 << 63) – Lower bound (inclusive).

  • high (int, default: 1 << 63) – Upper bound (exclusive).

Returns:

Tensor of int64 random numbers.

int64_tuple(size: int, low: int = -1 << 63, high: int = 1 << 63) → tuple[int, ...][source]

Generate a tuple of int64 numbers with uniform distribution in [low, high).

Parameters:

  • size (int) – Number of elements.

  • low (int, default: -1 << 63) – Lower bound (inclusive).

  • high (int, default: 1 << 63) – Upper bound (exclusive).

Returns:

Tuple of int64 random numbers.

int8(low: int = -1 << 7, high: int = 1 << 7 - 1) → int[source]

Generate an int8 scalar with uniform distribution in [low, high).

Parameters:

  • low (int, default: -1 << 7) – Lower bound (inclusive).

  • high (int, default: 1 << 7 - 1) – Upper bound (exclusive).

Returns:

Random int8 number.

int8_tensor(size: Sequence[int] | int = (1,), low: int = -1 << 7, high: int = 1 << 7) → Tensor[source]

Generate an int8 tensor with uniform distribution in [low, high).

Parameters:

  • size (Sequence[int] | int, default: (1,)) – Shape of the output tensor.

  • low (int, default: -1 << 7) – Lower bound (inclusive).

  • high (int, default: 1 << 7) – Upper bound (exclusive).

Returns:

Tensor of int8 random numbers.

int8_tuple(size: int, low: int = -1 << 7, high: int = 1 << 7) → tuple[int, ...][source]

Generate a tuple of int8 numbers with uniform distribution in [low, high).

Parameters:

  • size (int) – Number of elements.

  • low (int, default: -1 << 7) – Lower bound (inclusive).

  • high (int, default: 1 << 7) – Upper bound (exclusive).

Returns:

Tuple of int8 random numbers.

rand_like(x: Tensor, low: float = 0.0, high: float = 1.0) → Tensor[source]

Generate a tensor with the same shape and dtype as x, filled with uniform random numbers.

Parameters:

  • x (Tensor) – Reference tensor.

  • low (float, default: 0.0) – Lower bound.

  • high (float, default: 1.0) – Upper bound.

Returns:

Random tensor with the same shape and dtype as x.

rand_tensor(size: Sequence[int], dtype: dtype, low: float | int = 0, high: int | float = 1) → Tensor[source]

Generate a tensor of given shape and dtype with uniform random numbers in [low, high).

Parameters:

  • size (Sequence[int]) – Shape of the output tensor.

  • dtype (dtype) – Data type of the output tensor.

  • low (float | int, default: 0) – Lower bound.

  • high (int | float, default: 1) – Upper bound.

Returns:

Random tensor.

randn_tensor(size: Sequence[int], dtype: dtype) → Tensor[source]

Generate a tensor of given shape and dtype with standard normal distribution.

Parameters:

  • size (Sequence[int]) – Shape of the output tensor.

  • dtype (dtype) – Data type of the output tensor.

Returns:

Random tensor with normal distribution.

randperm(n: int, *, dtype: dtype = torch.int64) → Tensor[source]

Generate a random permutation of integers from 0 to n - 1.

Parameters:

  • n (int) – Number of elements.

  • dtype (dtype, default: torch.int64) – Data type of the output tensor.

Returns:

Tensor containing a random permutation.

uint16(low: int = 0, high: int = 1 << 16 - 1) → int[source]

Generate a uint16 scalar with uniform distribution in [low, high).

Parameters:

  • low (int, default: 0) – Lower bound (inclusive).

  • high (int, default: 1 << 16 - 1) – Upper bound (exclusive).

Returns:

Random uint16 number.

uint16_tuple(size: int, low: int = 0, high: int = 1 << 16 - 1) → tuple[int, ...][source]

Generate a tuple of uint16 numbers with uniform distribution in [low, high).

Parameters:

  • size (int) – Number of elements.

  • low (int, default: 0) – Lower bound (inclusive).

  • high (int, default: 1 << 16 - 1) – Upper bound (exclusive).

Returns:

Tuple of uint16 random numbers.

uint32(low: int = 0, high: int = 1 << 32 - 1) → int[source]

Generate a uint32 scalar with uniform distribution in [low, high).

Parameters:

  • low (int, default: 0) – Lower bound (inclusive).

  • high (int, default: 1 << 32 - 1) – Upper bound (exclusive).

Returns:

Random uint32 number.

uint32_tuple(size: int, low: int = 0, high: int = 1 << 32 - 1) → tuple[int, ...][source]

Generate a tuple of uint32 numbers with uniform distribution in [low, high).

Parameters:

  • size (int) – Number of elements.

  • low (int, default: 0) – Lower bound (inclusive).

  • high (int, default: 1 << 32 - 1) – Upper bound (exclusive).

Returns:

Tuple of uint32 random numbers.

uint64(low: int = 0, high: int = 1 << 64 - 1) → int[source]

Generate a uint64 scalar with uniform distribution in [low, high).

Parameters:

  • low (int, default: 0) – Lower bound (inclusive).

  • high (int, default: 1 << 64 - 1) – Upper bound (exclusive).

Returns:

Random uint64 number.

uint64_tuple(size: int, low: int = 0, high: int = 1 << 64 - 1) → tuple[int, ...][source]

Generate a tuple of uint64 numbers with uniform distribution in [low, high).

Parameters:

  • size (int) – Number of elements.

  • low (int, default: 0) – Lower bound (inclusive).

  • high (int, default: 1 << 64 - 1) – Upper bound (exclusive).

Returns:

Tuple of uint64 random numbers.

uint8(low: int = 0, high: int = 1 << 8 - 1) → int[source]

Generate a uint8 scalar with uniform distribution in [low, high).

Parameters:

  • low (int, default: 0) – Lower bound (inclusive).

  • high (int, default: 1 << 8 - 1) – Upper bound (exclusive).

Returns:

Random uint8 number.

uint8_tensor(size: Sequence[int] | int = (1,), low: int = 0, high: int = 1 << 8 - 1) → Tensor[source]

Generate a uint8 tensor with uniform distribution in [low, high).

Parameters:

  • size (Sequence[int] | int, default: (1,)) – Shape of the output tensor.

  • low (int, default: 0) – Lower bound (inclusive).

  • high (int, default: 1 << 8 - 1) – Upper bound (exclusive).

Returns:

Tensor of uint8 random numbers.

uint8_tuple(size: int, low: int = 0, high: int = 1 << 8 - 1) → tuple[int, ...][source]

Generate a tuple of uint8 numbers with uniform distribution in [low, high).

Parameters:

  • size (int) – Number of elements.

  • low (int, default: 0) – Lower bound (inclusive).

  • high (int, default: 1 << 8 - 1) – Upper bound (exclusive).

Returns:

Tuple of uint8 random numbers.

__eq__(value, /)

Return self==value.

__new__(**kwargs)