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 | None = None)[source]

Initialize the random generator with a fixed seed.

Parameters:: seed (int | None, default: None) – Seed for the random generator. If None, default torch seeding is used.

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.

bool_tensor(size: Sequence[int] | int = (1,)) → Tensor[source]

Generate boolean tensor of given size.

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

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) → 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) – 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) → 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) – 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 - 1) → 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) - 1) – Upper bound (exclusive). Maximum value is (1 << 63) - 1 due to https://github.com/pytorch/pytorch/issues/81446

Returns:

Tensor of int64 random numbers.

int64_tuple(size: int, low: int = -1 << 63, high: int = 1 << 63 - 1) → 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) - 1) – Upper bound (exclusive).

Returns:

Tuple of int64 random numbers.

int8(low: int = -1 << 7, high: int = 1 << 7) → 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) – 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, device, 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_like(x: Tensor) → Tensor[source]

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

Parameters:: x (Tensor) – Reference tensor.
Returns:: Random tensor with the same shape and dtype as x.

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) → 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) – Upper bound (exclusive).

Returns:

Random uint16 number.

uint16_tuple(size: int, low: int = 0, high: int = 1 << 16) → 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) – Upper bound (exclusive).

Returns:

Tuple of uint16 random numbers.

uint32(low: int = 0, high: int = 1 << 32) → 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) – Upper bound (exclusive).

Returns:

Random uint32 number.

uint32_tuple(size: int, low: int = 0, high: int = 1 << 32) → 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) – 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) → 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) – Upper bound (exclusive).

Returns:

Tensor of uint8 random numbers.

uint8_tuple(size: int, low: int = 0, high: int = 1 << 8) → 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) – Upper bound (exclusive).

Returns:

Tuple of uint8 random numbers.

__eq__(value, /): Return self==value.

__new__(**kwargs)