qrandom

qrandom is a small, inspectable CLI tool for generating and maintaining local pools of random bits derived directly from measurements performed on remote quantum computing backends.

The project is minimal by design. Its primary goals are:

• clarity of entropy provenance
• reproducibility
• avoidance of unnecessary complexity

This early release focuses on simple operation and transparency.

---

What qrandom does (v0.1.0)

• Retrieves measurement results from live quantum backends
• Derives random bits from those results
• Appends bits into a local bucket file on disk
• Provides a CLI to:
  • fill the bucket
  • inspect the bucket status
  • run basic statistical health checks on the bucket

The bucket is stored locally using OS-native paths and is never transmitted elsewhere by qrandom.

---

What qrandom does not do

• It is not a replacement for /dev/urandom
• It is not a cryptographic oracle
• It does not claim certified or provably perfect randomness
• It does not run as a background daemon or service (yet)

The current release is deliberately scoped.

---

Requirements

• Python ≥ 3.10
• A Unix-like environment (Linux, macOS, or WSL)
• IBM Quantum account credentials (configured via qiskit-ibm-runtime)

qrandom targets Qiskit ≥1.0 and relies on Qiskit to manage its internal components (Terra, Rustworkx, etc). Legacy Qiskit (<1.0) environments are not supported.

---

Quick start

Clone the repository and run the provided setup script:

git clone https://github.com/LyndonShuster/qrandom
cd qrandom
./qsetup.sh

The setup script will:

1. Create a local Python virtual environment

2. Install qrandom and its dependencies

3. Display the CLI help output to confirm installation

No global Python packages are modified.

---

Basic usage

Once installed, the qrandom CLI is available inside the virtual environment.

Before using the CLI, activate the virtual environment that was created during setup:

cd path/to/qrandom source venv/bin/activate

Examples:

qrandom -h
qrandom status
qrandom fill
qrandom health

status shows current bucket size, path, and shots per fill fill retrieves additional quantum-derived bits health runs basic statistical checks on the bucket

---

Project status

This is an early, intentionally minimal release.

v0.1.x focuses on:

• stable interfaces
• predictable behavior
• explicit handling of entropy sources

More complex features are explicitly deferred.

---

License

Apache License 2.0