lightrider 0.1.0__tar.gz

lightrider-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include lightrider/data *.npy

lightrider-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: lightrider
+Version: 0.1.0
+Summary: Quantum random numbers from IQM hardware-generated bit pools
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.21
+
+# lightrider
+
+Quantum random numbers sourced from IQM hardware measurements.
+
+## Installation
+
+```bash
+pip install lightrider
+```
+
+## Usage
+
+```python
+from lightrider import IQM_sirius
+
+# 5 random integers between 1 and 100
+IQM_sirius(5, 1, 100)
+# → [42, 7, 88, 13, 56]
+
+# 3 floats between 0.0 and 1.0 in steps of 0.1
+IQM_sirius(3, 0.0, 1.0, step=0.1)
+# → [0.3, 0.8, 0.1]
+
+# 4 floats between 10.0 and 99.9 in steps of 0.1
+IQM_sirius(4, 10.0, 99.9, step=0.1)
+# → [23.4, 67.8, 45.1, 88.0]
+```
+
+## API
+
+### `IQM_sirius(count, min_val, max_val, step=None)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `count` | `int` | Number of values to return |
+| `min_val` | `int` or `float` | Inclusive lower bound |
+| `max_val` | `int` or `float` | Inclusive upper bound |
+| `step` | `float` or `None` | Value granularity; `None` means integer steps |
+
+Returns a `list` of quantum-random numbers in `[min_val, max_val]`.
+
+## Data source
+
+The pool contains ~2 million bits collected from IQM quantum hardware via Hadamard coin-flip circuits across 10 qubits. Numbers are produced using rejection sampling for unbiased output.

lightrider-0.1.0/README.md

@@ -0,0 +1,44 @@
+# lightrider
+
+Quantum random numbers sourced from IQM hardware measurements.
+
+## Installation
+
+```bash
+pip install lightrider
+```
+
+## Usage
+
+```python
+from lightrider import IQM_sirius
+
+# 5 random integers between 1 and 100
+IQM_sirius(5, 1, 100)
+# → [42, 7, 88, 13, 56]
+
+# 3 floats between 0.0 and 1.0 in steps of 0.1
+IQM_sirius(3, 0.0, 1.0, step=0.1)
+# → [0.3, 0.8, 0.1]
+
+# 4 floats between 10.0 and 99.9 in steps of 0.1
+IQM_sirius(4, 10.0, 99.9, step=0.1)
+# → [23.4, 67.8, 45.1, 88.0]
+```
+
+## API
+
+### `IQM_sirius(count, min_val, max_val, step=None)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `count` | `int` | Number of values to return |
+| `min_val` | `int` or `float` | Inclusive lower bound |
+| `max_val` | `int` or `float` | Inclusive upper bound |
+| `step` | `float` or `None` | Value granularity; `None` means integer steps |
+
+Returns a `list` of quantum-random numbers in `[min_val, max_val]`.
+
+## Data source
+
+The pool contains ~2 million bits collected from IQM quantum hardware via Hadamard coin-flip circuits across 10 qubits. Numbers are produced using rejection sampling for unbiased output.

lightrider-0.1.0/lightrider/__init__.py

@@ -0,0 +1,8 @@
+"""
+lightrider — Quantum random numbers from IQM hardware data.
+"""
+
+from .core import IQM_sirius
+
+__all__ = ["IQM_sirius"]
+__version__ = "0.1.0"

lightrider-0.1.0/lightrider/_pool.py

@@ -0,0 +1,123 @@
+"""
+Manages the quantum bit pool loaded from IQM hardware data.
+Bits are consumed sequentially with wrap-around.
+"""
+
+from __future__ import annotations
+
+import math
+import importlib.resources
+from pathlib import Path
+import threading
+
+import numpy as np
+
+
+_QUBIT_FILES = [f"qubit_{i}_sequence.npy" for i in range(10)]
+
+
+def _load_bits() -> np.ndarray:
+    """Load and concatenate all qubit bit sequences into a single uint8 array."""
+    chunks = []
+    try:
+        # Python 3.9+ path
+        pkg_files = importlib.resources.files("lightrider.data")
+        for fname in _QUBIT_FILES:
+            data_bytes = (pkg_files / fname).read_bytes()
+            arr = np.frombuffer(data_bytes, dtype=np.uint8)
+            # npy files: reconstruct via np.load from bytes
+            import io
+            arr = np.load(io.BytesIO(data_bytes))
+            chunks.append(arr.astype(np.uint8).ravel())
+    except Exception:
+        # Fallback: load from package directory relative path
+        data_dir = Path(__file__).parent / "data"
+        for fname in _QUBIT_FILES:
+            arr = np.load(data_dir / fname)
+            chunks.append(arr.astype(np.uint8).ravel())
+    return np.concatenate(chunks)
+
+
+class QuantumPool:
+    """Thread-safe sequential consumer of quantum random bits."""
+
+    def __init__(self) -> None:
+        self._bits: np.ndarray = _load_bits()
+        self._pos: int = 0
+        self._total: int = len(self._bits)
+        self._lock = threading.Lock()
+
+    @property
+    def total_bits(self) -> int:
+        return self._total
+
+    def consume(self, n: int) -> np.ndarray:
+        """Return the next *n* bits, wrapping around if the pool is exhausted."""
+        with self._lock:
+            if n > self._total:
+                raise ValueError(
+                    f"Requested {n} bits but pool only has {self._total} bits total."
+                )
+            end = self._pos + n
+            if end <= self._total:
+                result = self._bits[self._pos : end].copy()
+                self._pos = end % self._total
+            else:
+                # Wrap around
+                tail = self._bits[self._pos :].copy()
+                head_n = n - len(tail)
+                head = self._bits[:head_n].copy()
+                result = np.concatenate([tail, head])
+                self._pos = head_n
+        return result
+
+    def bits_to_uint(self, bits: np.ndarray) -> int:
+        """Interpret a 1-D bit array (MSB first) as an unsigned integer."""
+        result = 0
+        for b in bits:
+            result = (result << 1) | int(b)
+        return result
+
+    def draw_integers(self, count: int, n_values: int) -> list[int]:
+        """
+        Draw *count* unbiased integers in [0, n_values) using rejection sampling.
+        Uses ceil(log2(n_values)) bits per candidate.
+        """
+        if n_values <= 0:
+            raise ValueError("n_values must be positive.")
+        if n_values == 1:
+            return [0] * count
+
+        bits_per = max(1, math.ceil(math.log2(n_values)))
+        # Upper power-of-two threshold for rejection
+        threshold = (1 << bits_per)  # = 2**bits_per
+
+        results: list[int] = []
+        # Over-sample to reduce rejection loop iterations
+        batch = max(count * 2, 64)
+
+        while len(results) < count:
+            raw_bits = self.consume(batch * bits_per)
+            for i in range(batch):
+                segment = raw_bits[i * bits_per : (i + 1) * bits_per]
+                val = self.bits_to_uint(segment)
+                if val < n_values:
+                    results.append(val)
+                    if len(results) == count:
+                        break
+
+        return results[:count]
+
+
+# Module-level singleton
+_pool: QuantumPool | None = None
+_pool_lock = threading.Lock()
+
+
+def get_pool() -> QuantumPool:
+    global _pool
+    if _pool is None:
+        with _pool_lock:
+            if _pool is None:
+                _pool = QuantumPool()
+    return _pool

lightrider-0.1.0/lightrider/core.py

@@ -0,0 +1,80 @@
+"""
+Core API for the lightrider quantum random number generator.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Union
+
+from ._pool import get_pool
+
+Number = Union[int, float]
+
+
+def IQM_sirius(
+    count: int,
+    min_val: Number,
+    max_val: Number,
+    step: float | None = None,
+) -> list[Number]:
+    """
+    Return *count* quantum random numbers drawn from a hardware-generated bit pool.
+
+    Parameters
+    ----------
+    count : int
+        How many random values to return.
+    min_val : int or float
+        Inclusive lower bound.
+    max_val : int or float
+        Inclusive upper bound.
+    step : float or None
+        Granularity of values.  ``None`` means integer steps (step=1).
+        Example: ``step=0.1`` produces values like 23.4, 67.8.
+
+    Returns
+    -------
+    list of int or float
+        Quantum-random values in [min_val, max_val].
+
+    Raises
+    ------
+    ValueError
+        If arguments are invalid.
+
+    Examples
+    --------
+    >>> IQM_sirius(5, 1, 100)
+    [42, 7, 88, 13, 56]
+
+    >>> IQM_sirius(3, 0.0, 1.0, step=0.1)
+    [0.3, 0.8, 0.1]
+    """
+    if count <= 0:
+        raise ValueError(f"count must be a positive integer, got {count!r}.")
+    if min_val > max_val:
+        raise ValueError(
+            f"min_val ({min_val}) must be <= max_val ({max_val})."
+        )
+
+    effective_step: float = step if step is not None else 1.0
+    if effective_step <= 0:
+        raise ValueError(f"step must be positive, got {step!r}.")
+
+    # Number of discrete values in the range (inclusive on both ends)
+    n_values = round((max_val - min_val) / effective_step) + 1
+
+    pool = get_pool()
+    indices = pool.draw_integers(count, n_values)
+
+    if step is None:
+        # Return plain ints when no step is specified and both bounds are int
+        if isinstance(min_val, int) and isinstance(max_val, int):
+            return [int(min_val) + idx for idx in indices]
+        else:
+            return [min_val + idx for idx in indices]
+    else:
+        # Round to avoid floating-point noise (e.g. 0.1+0.2 artifacts)
+        decimal_places = max(0, -math.floor(math.log10(step)))
+        return [round(min_val + idx * step, decimal_places) for idx in indices]

lightrider-0.1.0/lightrider.egg-info/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: lightrider
+Version: 0.1.0
+Summary: Quantum random numbers from IQM hardware-generated bit pools
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.21
+
+# lightrider
+
+Quantum random numbers sourced from IQM hardware measurements.
+
+## Installation
+
+```bash
+pip install lightrider
+```
+
+## Usage
+
+```python
+from lightrider import IQM_sirius
+
+# 5 random integers between 1 and 100
+IQM_sirius(5, 1, 100)
+# → [42, 7, 88, 13, 56]
+
+# 3 floats between 0.0 and 1.0 in steps of 0.1
+IQM_sirius(3, 0.0, 1.0, step=0.1)
+# → [0.3, 0.8, 0.1]
+
+# 4 floats between 10.0 and 99.9 in steps of 0.1
+IQM_sirius(4, 10.0, 99.9, step=0.1)
+# → [23.4, 67.8, 45.1, 88.0]
+```
+
+## API
+
+### `IQM_sirius(count, min_val, max_val, step=None)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `count` | `int` | Number of values to return |
+| `min_val` | `int` or `float` | Inclusive lower bound |
+| `max_val` | `int` or `float` | Inclusive upper bound |
+| `step` | `float` or `None` | Value granularity; `None` means integer steps |
+
+Returns a `list` of quantum-random numbers in `[min_val, max_val]`.
+
+## Data source
+
+The pool contains ~2 million bits collected from IQM quantum hardware via Hadamard coin-flip circuits across 10 qubits. Numbers are produced using rejection sampling for unbiased output.

lightrider-0.1.0/lightrider.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+lightrider/__init__.py
+lightrider/_pool.py
+lightrider/core.py
+lightrider.egg-info/PKG-INFO
+lightrider.egg-info/SOURCES.txt
+lightrider.egg-info/dependency_links.txt
+lightrider.egg-info/requires.txt
+lightrider.egg-info/top_level.txt
+lightrider/data/__init__.py
+lightrider/data/qubit_0_sequence.npy
+lightrider/data/qubit_1_sequence.npy
+lightrider/data/qubit_2_sequence.npy
+lightrider/data/qubit_3_sequence.npy
+lightrider/data/qubit_4_sequence.npy
+lightrider/data/qubit_5_sequence.npy
+lightrider/data/qubit_6_sequence.npy
+lightrider/data/qubit_7_sequence.npy
+lightrider/data/qubit_8_sequence.npy
+lightrider/data/qubit_9_sequence.npy

lightrider-0.1.0/lightrider.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lightrider-0.1.0/lightrider.egg-info/requires.txt

@@ -0,0 +1 @@
+numpy>=1.21

lightrider-0.1.0/lightrider.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+dist
+lightrider

lightrider-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lightrider"
+version = "0.1.0"
+description = "Quantum random numbers from IQM hardware-generated bit pools"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["numpy>=1.21"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+
+[tool.setuptools.package-data]
+lightrider = ["data/*.npy"]

lightrider-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lightrider-0.1.0/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()