riescue.lib

The riescue.lib module provides core utilities for the RiESCUE framework. It includes tools for logging, randomization, register management, instruction handling, and command-line processing.

riescue.lib.logger.add_args(parser: ArgumentParser)

Add logger arguments to parser.

Parameters:: parser (argparse.ArgumentParser) – ArgumentParser to add logger arguments to

riescue.lib.logger.from_args(args: Namespace, default_logger_file=None): Create a Logger instance from command-line arguments. Optional default_logger_file if –logger_file argument isn’t used

riescue.lib.logger.init_logger(log_path: Path, level: str = 'WARNING', max_log_size: int = 1, tee_to_stderr: bool = False, logger_timestamp: bool = True, verbose: bool = False) → None

Initializes a logger instance.

Parameters:

log_path (str or Path) – Path to log file
level (int) – Logging level (DEBUG, INFO, WARN, ERROR)
max_log_size (int) – Maximum log file size in GB
verbose (bool) – Enable verbose logging

# Initializing for first time:
from riescue.lib.logger import init_logger
log = init_logger(log_path="riescue.log", level="DEBUG", max_log_size=1, tee_to_stderr=True, verbose=True)

# Subsequent times:
import logging
...
log = logging.getLogger(__name__)
log.info("Hello, world!")

class riescue.lib.rand.RandNum(seed, distribution='uniform')

Random number generator with configurable distributions.

Extends Python’s random module to support multiple probability distributions with a consistent interface.

Parameters:

seed (int) – Seed value for reproducible randomness, required to reinforce creatingonce and passing around instance
distribution (str, optional) – Probability distribution to use, defaults to “uniform”

Supported distributions:

“uniform” - Uniform distribution in range [0.0, 1.0)
“triangular” - Triangular distribution with mode=0.5
“beta” - Beta distribution with alpha=2.0, beta=2.0
“exponential” - Exponential distribution with lambda=1.0
“log” - Log-normal distribution with mu=-2.0, sigma=0.5
“gaussian” - Gaussian (normal) distribution with mu=-0.5, sigma=0.5

Raises:: ValueError – If an invalid distribution type is specified

rand = RandNum(seed=42)
rand.random_in_range(1, 10)  # Returns 7

seed(seed: int)

Set the internal random number generator’s seed. Can only set seed once.

Parameters:: seed (int) – Seed value for reproducible randomness
Returns:: None
Raises:: ValueError – If seed is already set

get_seed() → int: Get the current seed value.

set_master_seed(seed) → None: Set the seed for compatibility with older seed method usage.

random() → float

Generate a random float from the chosen distribution.

Returns:: A random float in the range [0.0, 1.0), distributed according to the probability distribution specified during initialization
Return type:: float

random_in_range(range_lo: int, range_hi: int, range_step=1) → int

Generate a random integer within the specified range.

Parameters:

range_lo (int) – Lower bound of the range (inclusive)
range_hi (int) – Upper bound of the range (exclusive)
range_step (int, optional) – Step size between values, defaults to 1

Returns:

A random integer between range_lo and range_hi - 1, that is divisible by range_step

Return type:

int

Raises:

ValueError – If range_lo, range_hi, or range_step are not integers
ValueError – If range_hi <= range_lo
ValueError – If range_step <= 0

random_index_in(x: list)

Return a random valid index from the given list.

Parameters:: x (list) – List to select index from
Returns:: Random valid index
Return type:: int
Raises:: ValueError – If the list is empty

random_entry_in(x: list)

Return a random entry from the given list.

Parameters:: x (list) – List from which to select an element
Returns:: Randomly selected element from the list
Raises:: ValueError – If the list is empty

rand = RandNum(seed=42)
rand.random_entry_in(["apple", "banana", "cherry"])  # Returns 'banana'

sample(x: list, num_samples: int)

Return a sample of the specified size from the given list.

Parameters:

x (list) – List to sample from
num_samples (int) – Number of samples to take

Returns:

Random sample from list

Return type:

list

Raises:

ValueError – If num_samples > len(x)

random_in_bitrange(bitrange_lo, bitrange_hi, bitrange_step=1) → int

Return a random integer using bit manipulation within the specified bit range.

Parameters:

bitrange_lo (int) – Lower bound of the bit range (inclusive)
bitrange_hi (int) – Upper bound of the bit range (exclusive)
bitrange_step (int, optional) – Step size for alignment, defaults to 1

Returns:

Random integer with random bit length in the specified range

Return type:

int

rand = RandNum(seed=42)
rand.random_in_bitrange(3, 8)  # Returns a random 3-7 bit number (e.g., 42)

random_nbit(bits) → int

Return a random integer with the specified number of bits.

Parameters:: bits (int) – Number of bits in the generated integer
Returns:: Random integer with the specified bit length
Return type:: int

rand = RandNum(seed=42)
rand.random_nbit(8)  # Returns a random 8-bit number (0-255, e.g., 142)

get_rand_bits(num_bits: int) → int: Return a random integer generated from the specified number of bits.

randint(a: int, b: int) → int: Return a random integer between a and b inclusive.

percent() → int: Return a random integer between 0 and 99 inclusive.

with_probability_of(percent) → bool

Return True with the specified percent likelihood.

Parameters:: percent (int|float) – Probability percentage (0-100)
Returns:: True with probability of percent/100, False otherwise
Return type:: bool

rand = RandNum(seed=42)
rand.with_probability_of(75)  # Returns True with 75% probability

random_key_value(d: dict)

Return a random key and its corresponding value from the dictionary.

Parameters:: d (dict) – Dictionary to select from
Returns:: Tuple containing (list with selected key, corresponding value)
Return type:: tuple(list, any)
Raises:: ValueError – If dictionary is empty

rand = RandNum(seed=42)
rand.random_key_value({"a": 1, "b": 2, "c": 3})  # Returns (['b'], 2)

random_key_in(d: dict)

Return a list containing a randomly selected key from the dictionary.

Parameters:: d (dict) – Dictionary to select from
Returns:: List containing a single randomly selected key
Return type:: list
Raises:: ValueError – If dictionary is empty

rand = RandNum(seed=42)
rand.random_key_in({"a": 1, "b": 2, "c": 3})  # Returns ['b']

random_choice_weighted(x: dict)

Return a randomly selected key from the dictionary, weighted by its value.

Keys with higher values have a higher probability of being selected.

Parameters:: x (dict) – Dictionary with keys as choices and values as weights
Returns:: A randomly selected key, with selection probability proportional to its value
Raises:: ValueError – If dictionary is empty or contains negative weights

rand = RandNum(seed=42)
rand.random_choice_weighted({"a": 10, "b": 1, "c": 5})  # Returns 'a'
# 'a' has higher probability due to weight 10

shuffle(lst: list)

Randomly reorder the elements in the list in-place.

Parameters:: lst (list) – List to be shuffled
Returns:: None (shuffles in-place)

rand = RandNum(seed=42)
nums = [1, 2, 3, 4, 5]
rand.shuffle(nums)  # nums becomes [2, 5, 1, 3, 4]

choice(x: list[T]) → T

Return a random element from the list x. Uses random.Random.choice()

Parameters:: x (list) – List to select from
Returns:: Randomly selected element from the list
Return type:: any
Raises:: IndexError – If the list is empty

rand = RandNum(seed=42)
rand.choice([1, 2, 3, 4, 5])  # Returns 3

choices(x, weights=None, k=1)

Return a list of k unique random elements from the list x. Uses random.Random.choices()

Parameters:

weights (list, optional) – Weights for each element in x, defaults to None
k (int, optional) – Number of elements to select, defaults to 1

Returns:

List of k unique random elements from x

Return type:

list

Raises:

IndexError – If the list is empty
ValueError – If weights are negative

rand = RandNum(seed=42)
rand.choices([1, 2, 3, 4, 5], weights=[1, 2, 3, 4, 5], k=3)  # Returns [2, 4, 5]

randrange(start: int, stop: int | None = None, step: int = 1) → int

Return a random integer between start and stop, inclusive.

Parameters:

start (int) – Start of the range (inclusive)
stop (int, optional) – End of the range (exclusive)
step (int, optional) – Step size between values, defaults to 1

Returns:

A random integer between start and stop, inclusive

rand = RandNum(seed=42)
rand.randrange(1, 10)  # Returns a random number between 1 and 9