Random Number Utilities

Stable, reproducible random number generation for scientific computing and experimental repeatability.

Core Functions

random_generator

random_generator() -> Generator

Get the current random number generator instance.

Returns:

• Generator –

  numpy.random.Generator: The current random number generator

set_random_seed

set_random_seed(seed: Optional[int] = None) -> None

Set the seed of the random number generator.

Parameters:

• seed

  (Optional[int], default: None ) –

  Seed for pseudo-random number generation, or None for truly random

Raises:

• TypeError –

  If seed is not an int or None

stable_random

stable_random(path: Optional[str] = None) -> float

Return next random number in stable sequence.

Parameters:

• path

  (Optional[str], default: None ) –

  Legacy compatibility parameter (ignored)

Returns:

• float –

  Next random number from stable sequence

Raises:

• StopIteration –

  When no more numbers available

• FileNotFoundError –

  For legacy compatibility when sequence unavailable

generate_stable_random

generate_stable_random(N: int, path: Optional[str] = None) -> List[float]

Generate a sequence of random numbers for repeatability.

This function returns N random numbers from the embedded stable sequence, maintaining compatibility with legacy code that expects file-based generation. For compatibility, the path parameter is accepted but ignored.

Parameters:

• N

  (int) –

  Number of random numbers to generate

• path

  (Optional[str], default: None ) –

  Legacy compatibility parameter (ignored)

Returns:

• List[float] –

  List of N random numbers from the stable sequence

Raises:

• ValueError –

  If N is greater than available sequence length

init_stable_random

init_stable_random(offset: int = 0) -> None

Set the stable random offset and clear cache.

Sets the stable random offset so that different stable sequences can be generated from the same embedded data. Also clears the cache.

Parameters:

• offset

  (int, default: 0 ) –

  Offset which generates different sequences

Classes

Randomise

Supported experiment randomisations.

RandomIntegers

RandomIntegers(n: int, subsample: int = 0, path: Optional[str] = None)

Iterable producing repeatable sequences of random integers.

Produces repeatable sequences of random integers for all integers in a range from 0 to specified n.

Parameters:

• n

  (int) –

  Maximum integer in sequence (exclusive upper bound)

• subsample

  (int, default: 0 ) –

  Unique integer id for each sequence

• path

  (Optional[str], default: None ) –

  Legacy compatibility parameter (ignored)

Raises:

• TypeError –

  If bad argument type

• ValueError –

  If bad argument value

• FileNotFoundError –

  If stable random sequence unavailable

Methods:

• __iter__ –

  Initialize the iterator.

• __next__ –

  Return next integer in random sequence.

__iter__

__iter__() -> RandomIntegers

Initialize the iterator.

Returns:

• RandomIntegers –

  The initialized iterator

__next__

__next__() -> int

Return next integer in random sequence.

Returns:

• int –

  Next integer in random sequence

Raises:

• StopIteration –

  When all values have been returned

Usage Examples

Basic Random Number Generation

from causaliq_core.utils.random import random_generator, set_random_seed

# Set seed for reproducibility
set_random_seed(42)

# Get generator instance
gen = random_generator()
value = gen.random()  # Generate random float [0.0, 1.0)

Stable Random Sequences

from causaliq_core.utils.random import stable_random, init_stable_random

# Initialize stable random sequence
init_stable_random()

# Generate stable random numbers
for i in range(5):
    print(stable_random())  # Same sequence every run

Random Integer Sequences

from causaliq_core.utils.random import RandomIntegers

# Create iterator for random integers 1-10
rand_ints = RandomIntegers(1, 10)
for value in rand_ints:
    print(value)  # Each integer appears exactly once

Experiment Randomization Types

from causaliq_core.utils.random import Randomise

# Available randomization types for experiments
print(Randomise.ORDER)      # Randomize variable order
print(Randomise.NAMES)      # Randomize variable names  
print(Randomise.KNOWLEDGE)  # Randomize knowledge
print(Randomise.ROWS)       # Randomize row order
print(Randomise.SAMPLE)     # Randomize sample rows

Features

• Cross-platform reproducibility: Same sequences on all platforms
• Stable sequences: Pre-generated sequence for consistent results
• Configurable seeding: Support for both deterministic and random seeding
• Iterator patterns: Clean iteration over random integer sequences
• Experiment support: Built-in randomization types for scientific experiments