Random Number Generators

PyHDC provides seven families of deterministic random number generators. They plug into encodings via the generator= constructor parameter and produce reproducible hypervectors when seeded.

The HDCGenerator interface

All generators implement the abstract base class HDCGenerator. Its public interface:

Method	Description
`generate_bits(length)`	Return a list of `length` random bits (0 or 1)
`generate_words(length, word_size=32)`	Return a list of `length` random integers of `word_size` bits
`generate_floats(length, min_val=-1, max_val=1)`	Return a list of `length` random floats in [min_val, max_val]
`supports_bits()`	True if this generator can produce bits
`supports_words()`	True if this generator can produce words
`supports_floats()`	True if this generator can produce floats
`reset()`	Return to the initial state as if just constructed
`get_state()`	Return the current internal state
`set_seed(seed)`	Set a new seed and reinitialise

Generator output types and encoding compatibility

Each generator produces one of three output types. The encoding’s EncodingSpec.generator_output_type specifies which type it needs.

Generator family	Output type	Compatible encoding families
LCG, PCG, Xorshift, ShiftedCounter	words / floats	All encodings (MAP_C, HRR, BSC, BSDC, FHRR, VTB, MBAT, …)
LFSR, DLFSR	bits	Binary/integer encodings only: MAP_B, MAP_I, BSC, BSDC
LCA	bits	Binary/integer encodings only: MAP_B, MAP_I, BSC, BSDC

LCG: Linear Congruential Generator

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

Fast and simple, low-order bits are less random. Sufficient for most HDC experiments.

Classes: LCGGenerator, MultiplicativeLCGGenerator

Presets (CommonLCGGenerators):

numerical_recipes(seed) : a = 1664525, c = 1013904223, m = 2^32
park_miller(seed) : Lehmer generator, no increment; a = 16807, m = 2^31-1
minstd_rand(seed) : a = 48271
borland(seed) : Borland C++ parameters
glibc(seed) : glibc parameters
msvc(seed) : Visual C++ parameters

LFSR: Linear Feedback Shift Register

Shifts a binary register and XORs feedback taps to generate bits. Produces a maximal-length sequence of period \(2^n - 1\) for an \(n\)-bit register. Natively produces bits so is suitable for binary and integer encodings.

Classes: LFSRGenerator, FibonacciLFSRGenerator, GaloisLFSRGenerator

Presets (CommonLFSRGenerators): preset tap configurations for widths 8, 10, 12, 14, 16, 24, 32.

DLFSR: Digit-Serial LFSR

A digit-serial variant of LFSR that processes multiple bits per cycle. Useful for hardware implementations where parallelism is available.

Classes: DLFSRGenerator, FibonacciDLFSRGenerator, GaloisDLFSRGenerator, MatrixDLFSRGenerator

Presets (CommonDLFSRGenerators): various compact configurations.

LCA: Linear Cellular Automata

A 1-D cellular automaton where each cell’s next state depends on itself and its neighbours. Simple, spatially structured, and highly parallelisable.

Classes: LCAGenerator, ElementaryLCAGenerator, TotalisticLCAGenerator

Presets (CommonLCAGenerators): selected rules with good randomness properties.

PCG: Permuted Congruential Generator

An LCG with a final permutation step that produces substantially better statistical quality than plain LCG while keeping the same speed. Recommended when you want both reproducibility and good randomness.

Classes: PCGGenerator, MultiplicativePCGGenerator

Presets (CommonPCGGenerators):

pcg32(seed) : standard 32-bit PCG (recommended)
pcg32_fast(seed) : multiplicative variant, slightly faster

Xorshift family

Very fast generators based on XOR and bit-shift operations. Excellent for large-batch generation with continuous encodings.

Classes (all inherit from XorshiftGenerator): Xorshift32Generator, Xorshift64Generator, Xorshift128Generator, XorshiftPlusGenerator, XorshiftStarGenerator, Xoroshiro128PlusGenerator, Xoroshiro128StarStarGenerator, Xoshiro256StarStarGenerator, SplitMix64Generator

Presets (CommonXorshiftGenerators):

xorshift32(seed) : 32-bit Xorshift
xorshift64(seed) : 64-bit Xorshift (better period)
xorshift128(seed) : 128-bit state (very long period)

Utility: splitmix64_seed(seed); generates independent seeds for multiple generators from a single master seed.

ShiftedCounter family

Counter-based generators that apply a cryptographic-style scrambling function to a monotonically increasing counter. The scrambling function (Feistel network, ARX cipher, SPN, or custom) ensures that sequential counter values produce seemingly random outputs.

Classes: ShiftedCounterGenerator, FeistelCounterGenerator, ARXCounterGenerator, SPNCounterGenerator, CustomMappingCounterGenerator

Presets (CommonCounterGenerators): preset key configurations for each variant.

When to use each family

Use case	Recommended family
General-purpose reproducibility	PCG (`pcg32`) or LCG (`numerical_recipes`)
Hardware mapping	LFSR or LCA (natively produce bits)
High-throughput float generation	Xorshift (`xorshift64` or `xoshiro256`)
Parallel generation from one seed	Xorshift + `splitmix64_seed` for independent streams
Custom cryptographic properties	ShiftedCounter (`FeistelCounterGenerator`)
Maximum simplicity and portability	LCG (`numerical_recipes`)