https://github.com/mahmoudelshimi/fastapi_quantum_rng
A FastAPI-React-based Quantum Random Number Generator using Qiskit and AerSimulator. It simulates quantum circuits with Hadamard gates to generate random numbers.
https://github.com/mahmoudelshimi/fastapi_quantum_rng
fastapi python quantum-computing random-number-generators react reactjs
Last synced: about 2 months ago
JSON representation
A FastAPI-React-based Quantum Random Number Generator using Qiskit and AerSimulator. It simulates quantum circuits with Hadamard gates to generate random numbers.
- Host: GitHub
- URL: https://github.com/mahmoudelshimi/fastapi_quantum_rng
- Owner: mahmoudElshimi
- License: mit
- Created: 2025-05-16T10:45:26.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-21T15:20:50.000Z (7 months ago)
- Last Synced: 2025-11-21T17:23:33.130Z (7 months ago)
- Topics: fastapi, python, quantum-computing, random-number-generators, react, reactjs
- Language: Python
- Homepage:
- Size: 223 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# FastAPI Quantum Random Number Generator (QRNG)
This repository provides a **FastAPI-based API** that generates **quantum random numbers** using Qiskit's quantum circuit simulator, along with a **React/Vite** frontend to interact with it visually.
## Features
- Generates **true quantum-random** numbers (not pseudorandom)
- Supports **variable bit lengths** (8-bit, 16-bit, 256-bit, etc.)
- Allows **range-bound** random numbers (min/max)
- Uses **AerSimulator** for quantum circuit execution
- **Chunked generation** for large bit requests (29 qubits at a time)
- Interactive frontend with ReactJS to request quantum random numbers
### Note:
This project follows **RTFM** (Read The F*cking Manual) and **KISS** (Keep It Simple, Stupid!) principles. Contributions and improvements welcome!
---
## API Endpoints
### **Base Endpoint (`/`)**
Generates a **256-bit quantum random number**
**Example Response:**
```json
{
"bits": "101010...0101",
"as_num": 1234567890,
"bits_length": 256
}
```
### **Custom Random Number (`/random`)**
Generates quantum random numbers with flexible parameters:
- `length`: Bit length (required)
- `min`: Minimum value (optional)
- `max`: Maximum value (optional)
**Example Usage:**
```bash
curl "http://localhost:8000/random?length=32"
curl "http://localhost:8000/random?length=64&min=100&max=1000"
```
---
## Installation & Run
### **Requirements**
- python==3.13
- fastapi==0.115.12
- qiskit==2.0.0
- qiskit-aer==0.17.0
- uvicorn==0.34.2
### **Install Dependencies**
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### **Run the API**
```bash
python3 main.py
```
or
```bash
uvicorn main:app --reload
```
Access the API at: `http://localhost:8000`
### **Run with Docker Compose**
```bash
docker-compose up --build
```
---
## How It Works
### **Quantum Circuit Process**
1. Creates quantum circuit with Hadamard gates (puts qubits in superposition)
2. Measures qubits to collapse superposition into 0/1 states
3. Chunks large requests (29 qubits max per circuit)
4. Combines results into final bitstring
### **Range-Bound Generation**
When `min_val` and `max_val` are provided:
1. Calculates required bits for the range
2. Generates numbers until one falls within range
3. Adjusts to fit min/max bounds
---
## Technical Notes
### **Quantum Limitations**
- AerSimulator supports max **29 qubits per circuit**
- Large requests are automatically chunked
- True quantum randomness (not pseudorandom)
### **Performance Considerations**
- Each circuit execution takes ~50-100ms
- Range-bound numbers may require multiple attempts
- Consider caching for high-frequency requests
---
## License
MIT/X Consortium License © 2025 [mahmoudElshimi](mailto:mahmoudelshimi@protonmail.ch)