Generation Module

The pyhdc.generation module provides deterministic random number generators for reproducible hypervector generation.

HDCGenerator (abstract base)

class pyhdc.generation.base.HDCGenerator(seed: int | None = None)

Bases: ABC

Abstract base class for HDC-compatible random number generators.

Generators can produce bits, words, or floats, and are used to generate hypervectors with specific properties (e.g., using LFSRs, LCGs, etc.).

generate_bits(length: int) → List[int]

Generate a sequence of bits.

Parameters:

length – Number of bits to generate

Returns:

List of bits (0s and 1s)

Raises:

• NotImplementedError – If the generator doesn’t support bit generation

• ValueError – If length is not positive

generate_floats(length: int, min_val: float = -1.0, max_val: float = 1.0) → List[float]

Generate a sequence of floating-point values.

Parameters:

• length – Number of floats to generate

• min_val – Minimum value (inclusive)

• max_val – Maximum value (inclusive)

Returns:

List of floats in [min_val, max_val]

Raises:

• NotImplementedError – If the generator doesn’t support float generation

• ValueError – If length is not positive

generate_words(length: int, word_size: int = 32) → List[int]

Generate a sequence of words.

Parameters:

• length – Number of words to generate

• word_size – Size of each word in bits

Returns:

List of words (integers)

Raises:

• NotImplementedError – If the generator doesn’t support word generation

• ValueError – If length is not positive

abstractmethod get_parameters() → Dict[str, Any]

Get current generator parameters.

Returns:

Dictionary of parameter names and values

get_seed() → int | None

Get the current seed.

abstractmethod get_state() → Any

Get the current generator state.

Returns:

The current state (generator-specific format)

abstractmethod reset() → None

Reset the generator to its initial state.

abstractmethod set_parameters(**kwargs) → None

Set generator parameters.

Parameters:

**kwargs – Generator-specific parameters

Raises:

ValueError – If parameters are invalid

set_seed(seed: int) → None

Set the generator seed.

Parameters:

seed – The seed value

supports_bits() → bool

Check if generator supports bit generation.

supports_floats() → bool

Check if generator supports float generation.

supports_words() → bool

Check if generator supports word generation.

Constructor:

HDCGenerator(seed=None)

param seed:

Optional integer seed. If None, the generator is initialised from a random source.

Abstract methods (must be implemented by subclasses):

• _configure_internal(): called during __init__; sets up state from parameters

• _next_bit(): return the next bit (0 or 1); raise NotImplementedError if not supported

• _next_word(word_size=32): return the next integer of word_size bits

• set_parameters(**kwargs): update generator-specific parameters

• get_parameters(): return current parameter dict

• reset(): restore to initial state

Concrete methods:

• generate_bits(length) → list[int]

• generate_words(length, word_size=32) → list[int]

• generate_floats(length, min_val=-1.0, max_val=1.0) → list[float]

• supports_bits() → bool

• supports_words() → bool

• supports_floats() → bool

• get_state() → internal state (type is generator-dependent)

• set_seed(seed): set a new seed and reinitialise

DefaultGenerator

class pyhdc.generation.base.DefaultGenerator(seed: int | None = None)

Bases: HDCGenerator

Default generator using NumPy’s random number generator. Supports all output types.

generate_floats(length: int, min_val: float = -1.0, max_val: float = 1.0) → List[float]

Generate floats efficiently using NumPy.

get_parameters() → Dict[str, Any]

Get parameters.

get_state() → Any

Get NumPy RNG state.

reset() → None

Reset to initial seed state.

set_parameters(**kwargs) → None

Default generator has no additional parameters.

NumPy-backed generator used when no custom generator is specified. Wraps numpy.random.default_rng() internally.

param seed:

Optional integer seed passed to numpy.random.default_rng.

LCG family

class pyhdc.generation.lcg.LCGGenerator(modulus: int = 4294967296, multiplier: int = 1664525, increment: int = 1013904223, seed: int | None = None)

Bases: HDCGenerator

Linear Congruential Generator for hypervector generation.

Uses the formula: X(n+1) = (a * X(n) + c) mod m where a is the multiplier, c is the increment, and m is the modulus.

generate_floats(length: int, min_val: float = -1.0, max_val: float = 1.0) → List[float]

Generate floats efficiently using LCG.

get_increment() → int

Get the increment parameter.

get_modulus() → int

Get the modulus parameter.

get_multiplier() → int

Get the multiplier parameter.

get_parameters() → Dict[str, Any]

Get current LCG parameters.

get_state() → int

Get current state.

reset() → None

Reset to initial state.

set_increment(increment: int) → None

Set the increment parameter.

set_modulus(modulus: int) → None

Set the modulus parameter.

set_multiplier(multiplier: int) → None

Set the multiplier parameter.

set_parameters(modulus: int | None = None, multiplier: int | None = None, increment: int | None = None, seed: int | None = None) → None

Set LCG parameters.

Parameters:

• modulus – The modulus value (m)

• multiplier – The multiplier value (a)

• increment – The increment value (c)

• seed – The seed value

Linear Congruential Generator: \(X_{n+1} = (a X_n + c) \bmod m\)

param modulus:

m (default: 2³²)

param multiplier:

a (default: 1664525)

param increment:

c (default: 1013904223)

param seed:

Initial state

class pyhdc.generation.lcg.MultiplicativeLCGGenerator(modulus: int = 2147483647, multiplier: int = 48271, seed: int | None = None)

Bases: LCGGenerator

Multiplicative LCG Generator (increment = 0).

Uses the formula: X(n+1) = (a * X(n)) mod m

set_parameters(modulus: int | None = None, multiplier: int | None = None, seed: int | None = None, **kwargs) → None

Set parameters (increment is always 0).

LCG with c = 0 (multiplicative / Lehmer generator).

class pyhdc.generation.CommonLCGGenerators

Factory for named LCG presets. All methods take an optional seed parameter and return an LCGGenerator instance.

Method	Parameters
numerical_recipes(seed)	a=1664525, c=1013904223, m=232
park_miller(seed)	a=16807, c=0, m=231-1 (Lehmer)
minstd_rand(seed)	a=48271, c=0, m=231-1
minstd_rand0(seed)	a=16807, c=0, m=231-1
borland(seed)	Borland C++ parameters
glibc(seed)	GNU C Library parameters
msvc(seed)	Microsoft Visual C++ parameters
randu(seed)	IBM RANDU (historical; poor quality)

LFSR family

class pyhdc.generation.lfsr.FibonacciLFSRGenerator(width: int = 32, taps: List[int] | None = None, seed: int | None = None)

Bases: LFSRGenerator

Fibonacci-style LFSR generator.

class pyhdc.generation.lfsr.GaloisLFSRGenerator(width: int = 32, taps: List[int] | None = None, seed: int | None = None)

Bases: LFSRGenerator

Galois-style LFSR generator.

class pyhdc.generation.CommonLFSRGenerators

Factory for named LFSR presets. Methods return FibonacciLFSRGenerator or GaloisLFSRGenerator instances with preset tap configurations for widths 8, 10, 12, 14, 16, 24, 32.

DLFSR family

class pyhdc.generation.dlfsr.FibonacciDLFSRGenerator(width: int = 32, word_size: int = 32, taps: List[int] | None = None, seed: int | None = None)

Bases: DLFSRGenerator

Fibonacci-style DLFSR generator.

class pyhdc.generation.dlfsr.GaloisDLFSRGenerator(width: int = 32, word_size: int = 32, taps: List[int] | None = None, seed: int | None = None)

Bases: DLFSRGenerator

Galois-style DLFSR generator.

class pyhdc.generation.dlfsr.MatrixDLFSRGenerator(width: int = 32, word_size: int = 32, taps: List[int] | None = None, matrix_coeffs: List[int] | None = None, seed: int | None = None)

Bases: DLFSRGenerator

Matrix-based DLFSR generator.

Uses matrix multiplication over GF(2^word_size) for feedback.

get_matrix_coefficients() → List[int]

Get matrix coefficients.

get_parameters() → Dict[str, Any]

Get parameters including matrix coefficients.

set_matrix_coefficients(coeffs: List[int]) → None

Set matrix coefficients.

set_parameters(width: int | None = None, word_size: int | None = None, taps: List[int] | None = None, matrix_coeffs: List[int] | None = None, seed: int | None = None, **kwargs) → None

Set parameters including matrix coefficients.

class pyhdc.generation.CommonDLFSRGenerators

Factory for DLFSR presets (compact configurations).

LCA family

class pyhdc.generation.lca.ElementaryLCAGenerator(width: int = 32, rule: int = 30, boundary: str = 'periodic', seed: int | None = None)

Bases: LCAGenerator

Elementary LCA generator using standard elementary CA rules.

class pyhdc.generation.lca.TotalisticLCAGenerator(width: int = 32, rule: int = 14, boundary: str = 'periodic', seed: int | None = None)

Bases: LCAGenerator

Totalistic LCA generator.

Uses totalistic rules where next state depends only on the sum of neighborhood values.

class pyhdc.generation.CommonLCAGenerators

Factory for LCA presets based on selected cellular automata rules.

PCG family

class pyhdc.generation.pcg.PCGGenerator(state_bits: int = 64, output_bits: int = 32, multiplier: int = 6364136223846793005, increment: int = 1442695040888963407, seed: int | None = None, permutation: str = 'xsh-rs')

Bases: HDCGenerator

Permuted Congruential Generator for hypervector generation.

Uses an LCG with a permutation function for improved statistical properties.

generate_floats(length: int, min_val: float = -1.0, max_val: float = 1.0) → List[float]

Generate floats efficiently using PCG.

get_increment() → int

Get the increment parameter.

get_multiplier() → int

Get the multiplier parameter.

get_output_bits() → int

Get the output bits parameter.

get_parameters() → Dict[str, Any]

Get current PCG parameters.

get_permutation() → str

Get the permutation method.

get_state() → int

Get current state.

get_state_bits() → int

Get the state bits parameter.

reset() → None

Reset to initial state.

set_increment(increment: int) → None

Set the increment parameter.

set_multiplier(multiplier: int) → None

Set the multiplier parameter.

set_output_bits(output_bits: int) → None

Set the output bits parameter.

set_parameters(state_bits: int | None = None, output_bits: int | None = None, multiplier: int | None = None, increment: int | None = None, permutation: str | None = None, seed: int | None = None) → None

Set PCG parameters.

Parameters:

• state_bits – Number of bits in internal state

• output_bits – Number of bits in output

• multiplier – LCG multiplier value

• increment – LCG increment value

• permutation – Output permutation method

• seed – The seed value

set_permutation(permutation: str) → None

Set the permutation method.

set_state_bits(state_bits: int) → None

Set the state bits parameter.

class pyhdc.generation.pcg.MultiplicativePCGGenerator(state_bits: int = 64, output_bits: int = 32, multiplier: int = 6364136223846793005, seed: int | None = None)

Bases: PCGGenerator

PCG based on Multiplicative Congruential Generator.

Uses MCG (increment = 0) instead of LCG for the underlying generator.

set_parameters(state_bits: int | None = None, output_bits: int | None = None, multiplier: int | None = None, seed: int | None = None, **kwargs) → None

Set parameters (increment always 0).

class pyhdc.generation.CommonPCGGenerators

Method	Description
pcg32(seed)	Standard 32-bit PCG (recommended)
pcg32_fast(seed)	Multiplicative variant; slightly faster

Xorshift family

class pyhdc.generation.xorshift.Xorshift32Generator(seed: int | None = None)

Bases: XorshiftGenerator

32-bit Xorshift generator with (13,17,5) parameters.

class pyhdc.generation.xorshift.Xorshift64Generator(seed: int | None = None)

Bases: XorshiftGenerator

64-bit Xorshift generator with (13,7,17) parameters.

class pyhdc.generation.xorshift.Xorshift128Generator(seed: int | List[int] | None = None)

Bases: XorshiftGenerator

128-bit Xorshift generator (4 x 32-bit words).

class pyhdc.generation.xorshift.XorshiftPlusGenerator(seed: int | List[int] | None = None)

Bases: XorshiftGenerator

Xorshift+ generator with addition for improved low-bit randomness.

class pyhdc.generation.xorshift.XorshiftStarGenerator(seed: int | List[int] | None = None)

Bases: XorshiftGenerator

Xorshift* generator with multiplication for better statistics.

class pyhdc.generation.xorshift.Xoroshiro128PlusGenerator(seed: int | List[int] | None = None)

Bases: XorshiftGenerator

Xoroshiro128+ - fast variant with 128-bit state.

jump() → None

Jump ahead by 2^64 steps.

class pyhdc.generation.xorshift.Xoroshiro128StarStarGenerator(seed: int | List[int] | None = None)

Bases: XorshiftGenerator

Xoroshiro128** - improved statistics over Plus variant.

class pyhdc.generation.xorshift.Xoshiro256StarStarGenerator(seed: int | List[int] | None = None)

Bases: XorshiftGenerator

Xoshiro256** - modern xorshift with excellent properties.

jump() → None

Jump ahead by 2^128 steps.

class pyhdc.generation.xorshift.SplitMix64Generator(seed: int | None = None)

Bases: XorshiftGenerator

SplitMix64 - good for seeding other generators.

class pyhdc.generation.CommonXorshiftGenerators

Method	Generator class
xorshift32(seed)	Xorshift32Generator
xorshift64(seed)	Xorshift64Generator
xorshift128(seed)	Xorshift128Generator

pyhdc.generation.xorshift.splitmix64_seed(seed)

Generate N independent seeds from a single master seed using the SplitMix64 algorithm. Useful for initialising multiple independent streams.

Parameters:

seed – Master seed integer.

Returns:

SplitMix64Generator that can be used to seed other generators.

ShiftedCounter family

class pyhdc.generation.shifted_counter.FeistelCounterGenerator(bit_width: int = 32, shift_amount: int = 13, rounds: int = 4, round_keys: List[int] | None = None, seed: int | None = None)

Bases: ShiftedCounterGenerator

Shifted counter with Feistel network mapping.

Uses a Feistel network to create an invertible permutation.

get_round_keys() → List[int]

Get the round keys.

set_round_keys(round_keys: List[int]) → None

Set the round keys.

class pyhdc.generation.shifted_counter.ARXCounterGenerator(bit_width: int = 32, shift_amount: int = 11, constants: List[int] | None = None, rotations: List[int] | None = None, seed: int | None = None)

Bases: ShiftedCounterGenerator

Shifted counter with Addition-Rotation-XOR mapping.

Uses ARX operations for fast, secure mixing.

get_constants() → List[int]

Get the ARX constants.

get_rotations() → List[int]

Get the rotation amounts.

set_constants(constants: List[int]) → None

Set the ARX constants.

set_rotations(rotations: List[int]) → None

Set the rotation amounts.

class pyhdc.generation.shifted_counter.SPNCounterGenerator(bit_width: int = 32, shift_amount: int = 17, sbox_size: int = 4, sbox: List[int] | None = None, pbox: List[int] | None = None, seed: int | None = None)

Bases: ShiftedCounterGenerator

Shifted counter with Substitution-Permutation Network mapping.

Uses S-boxes and permutation for invertible mapping.

get_pbox() → List[int]

Get the P-box.

get_sbox() → List[int]

Get the S-box.

set_pbox(pbox: List[int]) → None

Set the P-box.

set_sbox(sbox: List[int]) → None

Set the S-box.

class pyhdc.generation.shifted_counter.CustomMappingCounterGenerator(bit_width: int = 32, shift_amount: int = 15, mapping_func: Callable[[int], int] | None = None, seed: int | None = None)

Bases: ShiftedCounterGenerator

Shifted counter with custom user-defined mapping.

Allows users to provide their own invertible mapping function.

set_mapping_function(mapping_func: Callable[[int], int]) → None

Set a new mapping function.

class pyhdc.generation.CommonCounterGenerators

Factory for ShiftedCounter presets with preset key configurations.