{"id":28581734,"url":"https://github.com/mahmoudelshimi/fastapi_quantum_rng","last_synced_at":"2026-04-30T19:31:17.548Z","repository":{"id":293642814,"uuid":"984689263","full_name":"mahmoudElshimi/fastapi_quantum_rng","owner":"mahmoudElshimi","description":"A FastAPI-React-based Quantum Random Number Generator using Qiskit and AerSimulator. It simulates quantum circuits with Hadamard gates to generate random numbers.","archived":false,"fork":false,"pushed_at":"2025-11-21T15:20:50.000Z","size":228,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-21T17:23:33.130Z","etag":null,"topics":["fastapi","python","quantum-computing","random-number-generators","react","reactjs"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mahmoudElshimi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-16T10:45:26.000Z","updated_at":"2025-11-21T15:49:22.000Z","dependencies_parsed_at":"2025-05-16T11:46:05.416Z","dependency_job_id":null,"html_url":"https://github.com/mahmoudElshimi/fastapi_quantum_rng","commit_stats":null,"previous_names":["mahmoudelshimi/fastapi_quantum_rng"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mahmoudElshimi/fastapi_quantum_rng","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahmoudElshimi%2Ffastapi_quantum_rng","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahmoudElshimi%2Ffastapi_quantum_rng/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahmoudElshimi%2Ffastapi_quantum_rng/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahmoudElshimi%2Ffastapi_quantum_rng/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mahmoudElshimi","download_url":"https://codeload.github.com/mahmoudElshimi/fastapi_quantum_rng/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahmoudElshimi%2Ffastapi_quantum_rng/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32475191,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"ssl_error","status_checked_at":"2026-04-30T13:12:06.837Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","python","quantum-computing","random-number-generators","react","reactjs"],"created_at":"2025-06-11T04:30:42.358Z","updated_at":"2026-04-30T19:31:17.542Z","avatar_url":"https://github.com/mahmoudElshimi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FastAPI Quantum Random Number Generator (QRNG)\n\nThis 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.\n\n![Frontend with ReactJS](frontend/reactjs.png)\n\n![Quantum Circuit](backend/quantum_circuit.png)\n\n\n## Features\n- Generates **true quantum-random** numbers (not pseudorandom)\n- Supports **variable bit lengths** (8-bit, 16-bit, 256-bit, etc.)\n- Allows **range-bound** random numbers (min/max)\n- Uses **AerSimulator** for quantum circuit execution\n- **Chunked generation** for large bit requests (29 qubits at a time)\n- Interactive frontend with ReactJS to request quantum random numbers\n### Note:\nThis project follows **RTFM** (Read The F*cking Manual) and **KISS** (Keep It Simple, Stupid!) principles. Contributions and improvements welcome!\n\n---\n\n## API Endpoints\n\n### **Base Endpoint (`/`)**\nGenerates a **256-bit quantum random number**  \n**Example Response:**\n```json\n{\n  \"bits\": \"101010...0101\",\n  \"as_num\": 1234567890,\n  \"bits_length\": 256\n}\n```\n\n### **Custom Random Number (`/random`)**\nGenerates quantum random numbers with flexible parameters:\n- `length`: Bit length (required)\n- `min`: Minimum value (optional)\n- `max`: Maximum value (optional)\n\n**Example Usage:**\n```bash\ncurl \"http://localhost:8000/random?length=32\"\ncurl \"http://localhost:8000/random?length=64\u0026min=100\u0026max=1000\"\n```\n\n---\n\n##  Installation \u0026 Run\n\n### **Requirements**\n- python==3.13\n- fastapi==0.115.12\n- qiskit==2.0.0\n- qiskit-aer==0.17.0\n- uvicorn==0.34.2\n\n\n### **Install Dependencies**\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n```\n\n### **Run the API**\n```bash\npython3 main.py\n```\nor\n```bash\nuvicorn main:app --reload\n```\nAccess the API at: `http://localhost:8000`\n\n### **Run with Docker Compose**\n```bash\ndocker-compose up --build\n```\n\n---\n\n## How It Works\n\n### **Quantum Circuit Process**\n1. Creates quantum circuit with Hadamard gates (puts qubits in superposition)\n2. Measures qubits to collapse superposition into 0/1 states\n3. Chunks large requests (29 qubits max per circuit)\n4. Combines results into final bitstring\n\n### **Range-Bound Generation**\nWhen `min_val` and `max_val` are provided:\n1. Calculates required bits for the range\n2. Generates numbers until one falls within range\n3. Adjusts to fit min/max bounds\n\n---\n\n## Technical Notes\n\n### **Quantum Limitations**\n- AerSimulator supports max **29 qubits per circuit**\n- Large requests are automatically chunked\n- True quantum randomness (not pseudorandom)\n\n### **Performance Considerations**\n- Each circuit execution takes ~50-100ms\n- Range-bound numbers may require multiple attempts\n- Consider caching for high-frequency requests\n\n---\n\n## License  \nMIT/X Consortium License © 2025 [mahmoudElshimi](mailto:mahmoudelshimi@protonmail.ch)  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahmoudelshimi%2Ffastapi_quantum_rng","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmahmoudelshimi%2Ffastapi_quantum_rng","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahmoudelshimi%2Ffastapi_quantum_rng/lists"}