go-seedlab

A research-grade deterministic randomness laboratory for Go. This framework provides reproducible pseudo-random sequences using different algorithms, with support for replay, branching seeds, entropy analysis, and exportable streams.

Features

• Multiple Algorithms: LCG, PCG, and Xoshiro256** generators
• Reproducibility: Deterministic sequences with seed control
• State Management: Save and restore generator states for replay
• Seed Branching: Create independent sequences from a base seed
• Entropy Analysis: Statistical analysis including Shannon entropy, chi-square, and auto-correlation
• Stream Export/Import: JSON serialization of random sequences
• High Performance: Optimized implementations with benchmarks

Installation

go get github.com/BaseMax/go-seedlab

Quick Start

package main

import (
    "fmt"
    "github.com/BaseMax/go-seedlab"
)

func main() {
    // Create a generator with a seed
    gen := seedlab.NewPCG(12345)
    
    // Generate random numbers
    for i := 0; i < 5; i++ {
        fmt.Println(gen.Next())
    }
    
    // Generate floats in [0.0, 1.0)
    fmt.Println(gen.NextFloat64())
    
    // Generate integers in a range [min, max)
    fmt.Println(gen.NextInRange(1, 100))
}

Algorithms

Linear Congruential Generator (LCG)

Classic PRNG using the formula: X(n+1) = (a * X(n) + c) mod m

• Fast and simple
• Uses Knuth's MMIX parameters for 64-bit
• Suitable for simulations and testing

Permuted Congruential Generator (PCG)

Modern PRNG with better statistical properties

• PCG-XSH-RR variant
• Passes statistical tests
• Good balance of speed and quality

Xoshiro256**

High-quality, fast PRNG

• Passes all known statistical tests
• Supports jump function for parallel streams
• Recommended for cryptographic research (non-production)

Usage Examples

Reproducible Sequences (Replay)

gen := seedlab.NewPCG(12345)

// Generate and save state
state := gen.GetState()
val1 := gen.Next()

// Continue generating...
for i := 0; i < 100; i++ {
    gen.Next()
}

// Restore previous state
gen.SetState(state)
val2 := gen.Next() // val2 == val1

Seed Branching

baseSeed := uint64(9999)

// Create independent branches
for i := uint64(1); i <= 3; i++ {
    branchSeed := seedlab.BranchSeed(baseSeed, i)
    gen := seedlab.NewXoshiro256(branchSeed)
    // Each branch produces a different sequence
}

Stream Export/Import

gen := seedlab.NewLCG(7777)

// Export stream to JSON
stream := seedlab.ExportStream(gen, 1000)
data, _ := seedlab.MarshalStream(stream)

// Import stream
stream2, _ := seedlab.UnmarshalStream(data)
gen2, _ := seedlab.ImportStream(stream2)

Entropy Analysis

gen := seedlab.NewXoshiro256(31415)

values := make([]uint64, 10000)
for i := 0; i < len(values); i++ {
    values[i] = gen.Next()
}

metrics := seedlab.AnalyzeEntropy(values)
fmt.Printf("Shannon Entropy: %.2f bits/byte\n", metrics.ShannonEntropy)
fmt.Printf("Chi-Square: %.2f\n", metrics.ChiSquare)
fmt.Printf("Auto-correlation: %.6f\n", metrics.AutoCorrelation)

Running Examples

cd examples/demo
go run main.go

Testing

go test -v
go test -bench=.

API Reference

Generator Interface

All generators implement the Generator interface:

• Next() uint64 - Returns the next random uint64
• NextFloat64() float64 - Returns a random float64 in [0.0, 1.0)
• NextInRange(min, max int64) int64 - Returns a random int64 in [min, max)
• Seed(seed uint64) - Sets or resets the generator seed
• GetState() State - Returns the current state for replay
• SetState(state State) error - Restores a previous state
• Algorithm() string - Returns the algorithm name

Functions

• NewLCG(seed uint64) *LCG - Create LCG generator
• NewPCG(seed uint64) *PCG - Create PCG generator
• NewXoshiro256(seed uint64) *Xoshiro256 - Create Xoshiro256** generator
• ExportStream(gen Generator, n int) *Stream - Export n values
• ImportStream(stream *Stream) (Generator, error) - Import stream
• MarshalStream(stream *Stream) ([]byte, error) - Serialize to JSON
• UnmarshalStream(data []byte) (*Stream, error) - Deserialize from JSON
• AnalyzeEntropy(values []uint64) *EntropyMetrics - Compute entropy metrics
• BranchSeed(originalSeed, branchID uint64) uint64 - Create branch seed

Use Cases

• Simulations: Reproducible Monte Carlo simulations
• Testing: Deterministic test data generation
• Research: Cryptographic research (non-production)
• Benchmarking: Performance testing with controlled randomness
• Game Development: Procedural generation with save/load support

Warning

This library is intended for research, simulations, and testing. DO NOT use for production cryptographic applications. Use Go's crypto/rand for cryptographic purposes.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.