A layered pseudo-random number generator that blends mathematical constants, complex dynamics, and prime-driven mixing with an avalanche hash stage. It exposes a simple CLI and a small Python API for integers, floats, constrained-length integers, and random choices.

Note: This generator is designed for experimentation, simulations, and games. It is not a cryptographic RNG—do not use it for security-sensitive purposes.

• Three entropy layers:
  • Irrational Walker: steps through digits of constants (pi, e, phi, sqrt2, sqrt3, ln2, Catalan).
  • Complex Chaos: nonlinear complex recurrence using trig and phase/magnitude blending.
  • Prime Mixer: small prime indexer that mixes digits across constants.
• Avalanche mixing via SHA-256 with a rolling entropy buffer.
• Small Python API: randint, random, choice, fixed-length constrained randint.
• CLI with validation, warnings, and demo/test modes.

• Python 3.8+
• Dependencies (see requirements.txt):
  • mpmath>=1.3.0
• All other imports are from the Python standard library.

Install dependencies with pip:

pip install -r requirements.txt

• Running without flags executes the challenge tests and then a short demo.
• Or use explicit modes:
  • --test to run the challenge tests (entropy, compression, distribution)
  • --demo to print usage examples

Examples:

# Generate 4 numbers of length 2 between 40 and 100 while omitting digits 2 and 5
python trinity_chaotic_rng.py --gen 4 --len 2 --ran 40,100 --omit 2,5

# Generate 10 integers in [0, 100]
python trinity_chaotic_rng.py --gen 10 --ran 0,100

# Run tests
python trinity_chaotic_rng.py --test

# Run demo
python trinity_chaotic_rng.py --demo

• --gen N Number of values to generate (default: 1)
• --len N Length in digits (applies to integers only)
• --ran A,B Inclusive range (min,max). Default: 0,100
• --omit D1,D2 Digits to omit from results (applies to integers)
• --test Run challenge tests
• --demo Show usage demo

Input validation provides helpful errors and warnings (e.g., small ranges, too many omitted digits, or infeasible length vs. range constraints). When constraints are tight, generation attempts are capped; failures are reported per item.

Import and construct the generator:

from trinity_chaotic_rng import TrinityChaoticRNG
rng = TrinityChaoticRNG(verbose=False, precision=50000)

Methods:

• next() -> int
  • Returns a 64-bit integer derived from all layers and SHA-256 mixing.
• randint(a: int, b: int) -> int
  • Uniform integer in [a, b].
• random() -> float
  • Float in [0.0, 1.0) using 52-bit fraction from the mixed state.
• choice(sequence) -> Any
  • Chooses a random element from a non-empty sequence.
• randint_with_length(length: int, min_val: int, max_val: int, omit_digits: Optional[Iterable[str]]) -> Optional[int]
  • Integer of exact digit length within [min_val, max_val] subject to digit-omission constraints. Returns None if constraints are infeasible after bounded attempts.

Constructor parameters:

• verbose (bool): Print initialization details (default False).
• precision (int): Decimal precision used by mpmath to precompute digits of constants (default 50,000). Higher precision uses more memory/time at startup.

1. Irrational Walker

   • Selects a constant and position; reads a digit and updates position, step size, and next constant based on digit thresholds.

2. Complex Chaos

   • Iterates a complex value with sin/cos nonlinearities, combines magnitude and phase (scaled), applies drift and normalization.

3. Prime Mixer

   • Uses a small-prime index to sample digits from pi, e, and phi at prime-derived offsets, producing a mixed small integer which advances the prime index.

4. Avalanche Mix

   • Combines layer outputs with any buffered history, hashes via SHA-256, and returns the first 64 bits. A rolling buffer preserves short-term state diversity.

• Shannon Entropy over 100,000 integers in [0, 100]
• DEFLATE compression ratio (expect near-incompressible)
• Chi-square distribution uniformity (101 bins)

Run these with --test. The script prints timing, rates, statistics, and a summary. These tests are heuristic and not a substitute for rigorous suites like TestU01 or NIST SP 800-22.

• Startup computes many digits of constants via mpmath; this is the main cost. Reduce precision with TrinityChaoticRNG(..., precision=10000) to speed up initialization at the expense of a smaller digit pool.
• Generation after initialization is fast, with modest Python overhead per sample.

The current implementation seeds from system time and Python object IDs. It does not expose a user seed parameter. For reproducible runs, consider extending the constructor to accept an explicit seed and bypass time/memory entropy.

• Not a cryptographic RNG.
• Do not use for keys, tokens, lotteries, or any security-critical decisions.

• trinity_chaotic_rng.py – Implementation, CLI, tests, and demo
• requirements.txt – Dependency pin(s)

This project is licensed under the Apache License, Version 2.0 (Apache-2.0). See the LICENSE and NOTICE files for details.

• mpmath for high-precision constants and arithmetic.
• Classic statistical tests (entropy, chi-square) and compression as quick heuristics.